/**
 * Agent Registry Accessor — cross-DB CRUD for agent data.
 *
 * Post-T310 (ADR-037), agent identity lives in the GLOBAL
 * `$XDG_DATA_HOME/cleo/signaldock.db:agents` table; per-project
 * visibility and overrides live in the PROJECT
 * `.cleo/conduit.db:project_agent_refs` table.
 *
 * This module provides three module-level functions that perform the
 * in-memory cross-DB join, plus the backward-compatible
 * `AgentRegistryAccessor` class that wraps them.
 *
 * Architecture:
 *   global  signaldock.db — canonical identity (openGlobalDb)
 *   project conduit.db    — project_agent_refs  (openConduitDb)
 *   Join performed in Node (SQLite cannot cross-file-handle JOIN).
 *
 * @see .cleo/specs/T310-conduit-signaldock-spec.md §3.5
 * @see .cleo/adrs/ADR-037-conduit-signaldock-separation.md
 * @task T355
 * @epic T310
 */
import type { AgentCredential, AgentListFilter, AgentRegistryAPI, AgentWithProjectOverride, ProjectAgentRef } from '@cleocode/contracts';
/**
 * Cross-DB agent lookup. Opens both the global signaldock.db and the
 * current project's conduit.db, joins project_agent_refs ⨝ agents by
 * agentId, and returns the merged view.
 *
 * Default (includeGlobal=false): returns null if no project_agent_refs row
 * exists, even if the agent exists globally. An enabled=0 row is also treated
 * as absent.
 *
 * includeGlobal=true: returns the global agent with `projectRef: null` if no
 * project attachment row exists.
 *
 * Dangling soft-FK detection: if a project_agent_refs row exists but the
 * referenced global agent does not, logs a WARN and returns null.
 *
 * @param projectRoot     - Absolute path to the project root directory.
 * @param agentId         - Agent business identifier.
 * @param opts.includeGlobal - When true, returns global identity even without project ref.
 * @returns Merged agent record or null if not found.
 *
 * @task T355
 * @epic T310
 */
export declare function lookupAgent(projectRoot: string, agentId: string, opts?: {
    includeGlobal?: boolean;
}): AgentWithProjectOverride | null;
/**
 * Lists agents visible in the current project.
 *
 * Default (includeGlobal=false): INNER JOIN on project_agent_refs (enabled=1)
 * — only agents explicitly attached to this project are returned.
 *
 * includeGlobal=true: returns all global agents regardless of project
 * attachment, with projectRef populated for attached ones and null for the rest.
 *
 * includeDisabled=true: also returns agents with enabled=0 in project_agent_refs.
 * Ignored when includeGlobal=true (all global agents are returned regardless).
 *
 * @param projectRoot            - Absolute path to the project root directory.
 * @param opts.includeGlobal     - Include all global agents (bypasses project filter).
 * @param opts.includeDisabled   - Include agents with enabled=0 in project_agent_refs.
 * @returns Array of merged agent records.
 *
 * @task T355
 * @epic T310
 */
export declare function listAgentsForProject(projectRoot: string, opts?: {
    includeGlobal?: boolean;
    includeDisabled?: boolean;
}): AgentWithProjectOverride[];
/**
 * Creates a new agent: writes identity row to global signaldock.db AND attaches
 * it to the current project via conduit.db:project_agent_refs.
 *
 * Write order: global first, then project ref. If the project ref write fails,
 * the global row remains (recoverable via `cleo agent attach <id>`).
 *
 * API key derivation: HMAC-SHA256(machineKey || globalSalt, agentId) per ADR-037 §5.
 *
 * @param projectRoot - Absolute path to the project root directory.
 * @param spec        - Agent creation spec (without createdAt/updatedAt).
 * @returns Merged agent record including the new project ref.
 *
 * @task T355
 * @epic T310
 */
export declare function createProjectAgent(projectRoot: string, spec: Omit<AgentCredential, 'createdAt' | 'updatedAt'>): AgentWithProjectOverride;
/**
 * Attach a globally-registered agent to the current project.
 *
 * Creates a `project_agent_refs` row with `enabled=1`. If a row already exists
 * with `enabled=0`, it is re-enabled (idempotent). If the row already has
 * `enabled=1`, this is a no-op.
 *
 * The agent MUST already exist in the global `signaldock.db:agents` table.
 * This function does NOT validate global existence — callers must check via
 * `lookupAgent(..., { includeGlobal: true })` first.
 *
 * @param projectRoot - Absolute path to the project root directory.
 * @param agentId     - Agent business identifier.
 * @param opts.role                - Optional per-project role override (nullable).
 * @param opts.capabilitiesOverride - Optional JSON blob of capability overrides (nullable).
 *
 * @task T364
 * @epic T310
 */
export declare function attachAgentToProject(projectRoot: string, agentId: string, opts?: {
    role?: string | null;
    capabilitiesOverride?: string | null;
}): void;
/**
 * Detach an agent from the current project by setting `project_agent_refs.enabled=0`.
 *
 * This is a soft-delete: the global `signaldock.db:agents` row is preserved.
 * The agent can be re-attached later via `attachAgentToProject`.
 *
 * Returns `false` if no row exists in `project_agent_refs` for the given agentId
 * (agent was never attached or was already fully removed).
 *
 * @param projectRoot - Absolute path to the project root directory.
 * @param agentId     - Agent business identifier.
 * @returns `true` if a row was updated; `false` if no row existed.
 *
 * @task T364
 * @epic T310
 */
export declare function detachAgentFromProject(projectRoot: string, agentId: string): boolean;
/**
 * Get the raw `project_agent_refs` row for a given agentId in this project.
 *
 * Returns `null` if no row exists (agent not attached to this project).
 *
 * @param projectRoot - Absolute path to the project root directory.
 * @param agentId     - Agent business identifier.
 * @returns Typed `ProjectAgentRef` object or `null`.
 *
 * @task T364
 * @epic T310
 */
export declare function getProjectAgentRef(projectRoot: string, agentId: string): ProjectAgentRef | null;
/**
 * AgentRegistryAccessor — backward-compatible CRUD wrapper around the
 * cross-DB module-level functions.
 *
 * Post-T310 (ADR-037), the constructor accepts the project root (same
 * semantics as `projectPath` in the pre-T310 version). All operations are
 * routed through the cross-DB functions above.
 *
 * @task T355
 * @epic T310
 */
export declare class AgentRegistryAccessor implements AgentRegistryAPI {
    private readonly projectPath;
    /**
     * @param projectPath - Absolute path to the project root directory.
     *   Used as the `projectRoot` argument for all cross-DB operations.
     * @task T355
     * @epic T310
     */
    constructor(projectPath: string);
    /**
     * Ensure both databases exist with their full schemas before any operation.
     *
     * @task T355
     * @epic T310
     */
    private ensureDbs;
    /**
     * Register (create or update) an agent in global signaldock.db and attach
     * it to the current project via conduit.db:project_agent_refs.
     *
     * @param credential - Agent spec (without createdAt/updatedAt).
     * @returns The registered agent credential.
     * @task T355
     * @epic T310
     */
    register(credential: Omit<AgentCredential, 'createdAt' | 'updatedAt'>): Promise<AgentCredential>;
    /**
     * Get agent by agentId. Project-scoped by default (INNER JOIN).
     *
     * @param agentId             - Agent business identifier.
     * @param opts.includeGlobal  - When true, returns global identity even without project ref.
     * @returns The agent credential, or null if not found.
     * @task T355
     * @epic T310
     */
    get(agentId: string, opts?: {
        includeGlobal?: boolean;
    }): Promise<AgentCredential | null>;
    /**
     * Lists project-scoped agents (INNER JOIN on project_agent_refs with enabled=1).
     *
     * @param filter - Optional filter (active field maps to is_active in global agents).
     * @returns Array of agent credentials visible in this project.
     * @task T355
     * @epic T310
     */
    list(filter?: AgentListFilter): Promise<AgentCredential[]>;
    /**
     * Lists all global agents (no project filter). Exposed for `--global` CLI flag.
     *
     * @param filter - Optional filter (active field maps to is_active in global agents).
     * @returns Array of all globally registered agent credentials.
     * @task T355
     * @epic T310
     */
    listGlobal(filter?: AgentListFilter): Promise<AgentCredential[]>;
    /**
     * Update agent identity fields in global signaldock.db.
     * Project-specific fields (role, capabilitiesOverride) require direct
     * conduit.db manipulation (not yet exposed by this method).
     *
     * @param agentId  - Agent business identifier.
     * @param updates  - Partial set of fields to update.
     * @returns The updated agent credential (project-scoped lookup).
     * @task T355
     * @epic T310
     */
    update(agentId: string, updates: Partial<Omit<AgentCredential, 'agentId' | 'createdAt'>>): Promise<AgentCredential>;
    /**
     * Remove agent from current project (sets project_agent_refs.enabled=0).
     * Does NOT delete from global signaldock.db (per ADR-037 §6 / Q4=C).
     *
     * @param agentId - Agent business identifier.
     * @task T355
     * @epic T310
     */
    remove(agentId: string): Promise<void>;
    /**
     * Remove agent from global signaldock.db.
     * Requires explicit opt-in. Warns if cross-project refs may exist.
     *
     * @param agentId     - Agent business identifier.
     * @param opts.force  - Skip the global-delete warning when refs exist.
     * @task T355
     * @epic T310
     */
    removeGlobal(agentId: string, opts?: {
        force?: boolean;
    }): Promise<void>;
    /**
     * Rotate API key via cloud endpoint and re-encrypt with the new T310 KDF
     * in global signaldock.db.
     *
     * @param agentId - Agent business identifier.
     * @returns Object with agentId and a redacted new API key string.
     * @task T355
     * @epic T310
     */
    rotateKey(agentId: string): Promise<{
        agentId: string;
        newApiKey: string;
    }>;
    /**
     * Get the most recently used active agent in the current project.
     *
     * @returns The most-recently-used active agent, or null if none found.
     * @task T355
     * @epic T310
     */
    getActive(): Promise<AgentCredential | null>;
    /**
     * Update last_used_at in both global signaldock.db:agents and
     * conduit.db:project_agent_refs.
     *
     * @param agentId - Agent business identifier.
     * @task T355
     * @epic T310
     */
    markUsed(agentId: string): Promise<void>;
}
//# sourceMappingURL=agent-registry-accessor.d.ts.map