agentbnb 4.0.0 → 4.0.1

package/dist/index.d.ts

@@ -1874,6 +1874,15 @@ declare function expandEnvVars(value: string): string;
  */
 declare function parseSkillsFile(yamlContent: string): SkillConfig[];
 
+/**
+ * Progress callback for long-running skill executions.
+ * Called between steps/sub-tasks to indicate forward progress.
+ */
+type ProgressCallback = (info: {
+    step: number;
+    total: number;
+    message: string;
+}) => void;
 /**
  * Result returned by SkillExecutor.execute() for every invocation.
  * Always includes timing data regardless of success or failure.
@@ -1900,7 +1909,7 @@ interface ExecutorMode {
      * @param params - The input parameters passed by the caller.
      * @returns A partial ExecutionResult without latency_ms (added by SkillExecutor).
      */
-    execute(config: SkillConfig, params: Record<string, unknown>): Promise<Omit<ExecutionResult, 'latency_ms'>>;
+    execute(config: SkillConfig, params: Record<string, unknown>, onProgress?: ProgressCallback): Promise<Omit<ExecutionResult, 'latency_ms'>>;
 }
 /**
  * Central dispatcher that routes skill execution requests to the appropriate
@@ -1933,7 +1942,7 @@ declare class SkillExecutor {
      * @param params - Input parameters for the skill.
      * @returns ExecutionResult including success, result/error, and latency_ms.
      */
-    execute(skillId: string, params: Record<string, unknown>): Promise<ExecutionResult>;
+    execute(skillId: string, params: Record<string, unknown>, onProgress?: ProgressCallback): Promise<ExecutionResult>;
     /**
      * Returns the IDs of all registered skills.
      *
@@ -2087,7 +2096,7 @@ declare class PipelineExecutor implements ExecutorMode {
      * @param params - Input parameters from the caller.
      * @returns Partial ExecutionResult (without latency_ms — added by SkillExecutor wrapper).
      */
-    execute(config: SkillConfig, params: Record<string, unknown>): Promise<Omit<ExecutionResult, 'latency_ms'>>;
+    execute(config: SkillConfig, params: Record<string, unknown>, onProgress?: ProgressCallback): Promise<Omit<ExecutionResult, 'latency_ms'>>;
 }
 
 /**
@@ -2214,6 +2223,8 @@ interface MatchResult {
     selected_agent: string;
     /** Skill ID on the selected agent's card. */
     selected_skill: string;
+    /** Capability card ID of the selected agent. Used for relay execution of remote agents. */
+    selected_card_id?: string;
     /** Match quality score (0-1). */
     score: number;
     /** Negotiated credit cost. */
@@ -2314,6 +2325,8 @@ interface MatchOptions {
     subtasks: SubTask[];
     /** Owner ID of the conductor agent — excluded from matches (self-exclusion). */
     conductorOwner: string;
+    /** Optional remote registry URL for fallback when local search returns no results. */
+    registryUrl?: string;
 }
 /**
  * Finds the best agent for each sub-task using registry FTS search and peer scoring.
@@ -2329,7 +2342,7 @@ interface MatchOptions {
  * @param opts - Match configuration including database, subtasks, and conductor owner ID.
  * @returns MatchResult[] in the same order as the input subtasks.
  */
-declare function matchSubTasks(opts: MatchOptions): MatchResult[];
+declare function matchSubTasks(opts: MatchOptions): Promise<MatchResult[]>;
 
 /**
  * Configuration for credit budget enforcement.
@@ -2467,11 +2480,16 @@ declare const CONDUCTOR_OWNER = "agentbnb-conductor";
  * - `orchestrate` (5 cr): Decomposes and executes multi-agent tasks
  * - `plan` (1 cr): Returns an execution plan with cost estimate only
  *
+ * When `owner` is provided, the card is attributed to that agent owner
+ * with a deterministic owner-specific ID. When omitted, uses the default
+ * singleton CONDUCTOR_OWNER and fixed UUID.
+ *
  * The returned card is validated against CapabilityCardV2Schema before return.
  *
+ * @param owner - Optional agent owner. When provided, card is owner-specific.
  * @returns A valid CapabilityCardV2 for the Conductor.
  */
-declare function buildConductorCard(): CapabilityCardV2;
+declare function buildConductorCard(owner?: string): CapabilityCardV2;
 /**
  * Registers the Conductor card in the given SQLite database.
  *
@@ -2485,719 +2503,199 @@ declare function buildConductorCard(): CapabilityCardV2;
 declare function registerConductorCard(db: Database.Database): CapabilityCardV2;
 
 /**
- * PipelineOrchestrator — DAG-based remote execution engine for the Conductor.
- *
- * Executes sub-tasks across remote agents via the Gateway client,
- * respecting dependency ordering (parallel waves for independent tasks),
- * output piping between steps, and retry with alternative agents on failure.
- *
- * Budget checking is NOT done here — the caller (ConductorMode) handles that.
- * This module is pure execution.
- */
-
-/**
- * Options for the orchestrate() function.
- */
-interface OrchestrateOptions {
-    /** Ordered list of sub-tasks forming a dependency DAG. */
-    subtasks: SubTask[];
-    /** Match results keyed by subtask ID. */
-    matches: Map<string, MatchResult>;
-    /** Bearer token for authenticating with remote agents. */
-    gatewayToken: string;
-    /** Resolves an agent owner to their gateway URL and card ID. */
-    resolveAgentUrl: (agentOwner: string) => {
-        url: string;
-        cardId: string;
-    };
-    /** Per-task timeout in milliseconds. Default 30000. */
-    timeoutMs?: number;
-    /** Maximum budget in credits. If set, aborts remaining tasks when exceeded. */
-    maxBudget?: number;
-}
-/**
- * Executes a DAG of sub-tasks across remote agents via Gateway.
- *
- * Execution flow:
- * 1. Computes execution waves from dependency graph
- * 2. For each wave, executes all tasks in parallel via Promise.allSettled
- * 3. Before each task, interpolates params against completed step outputs
- * 4. On failure, retries with the first alternative agent from MatchResult
- * 5. Tracks per-task spending and total credits
- * 6. Optionally enforces a maxBudget ceiling
- *
- * @param opts - Orchestration options.
- * @returns Aggregated orchestration result.
- */
-declare function orchestrate(opts: OrchestrateOptions): Promise<OrchestrationResult>;
-
-/**
- * ConductorMode — ExecutorMode implementation for Conductor skills.
- *
- * Chains TaskDecomposer -> CapabilityMatcher -> BudgetController -> PipelineOrchestrator
- * to execute multi-agent orchestration pipelines via the SkillExecutor dispatch system.
- *
- * Supports two conductor skills:
- * - `orchestrate`: Full pipeline — decompose, match, budget check, execute, return results.
- * - `plan`: Planning only — decompose, match, budget check, return plan without executing.
- */
-
-/**
- * Configuration options for ConductorMode.
- */
-interface ConductorModeOptions {
-    /** Registry database for card search (FTS5). */
-    db: Database.Database;
-    /** Credit database for budget checks. */
-    creditDb: Database.Database;
-    /** Owner ID of the conductor agent — used for self-exclusion in matching. */
-    conductorOwner: string;
-    /** Bearer token for authenticating with remote agents. */
-    gatewayToken: string;
-    /** Resolves an agent owner to their gateway URL and card ID. */
-    resolveAgentUrl: (owner: string) => {
-        url: string;
-        cardId: string;
-    };
-    /** Maximum budget in credits for orchestration runs. Default 100. */
-    maxBudget?: number;
-}
-/**
- * ExecutorMode implementation for Conductor skills ('orchestrate' and 'plan').
- *
- * Dispatches through the full Conductor pipeline:
- * 1. TaskDecomposer breaks the task into SubTasks
- * 2. CapabilityMatcher finds agents for each sub-task
- * 3. BudgetController validates cost against limits
- * 4. PipelineOrchestrator executes the DAG (orchestrate only)
- */
-declare class ConductorMode implements ExecutorMode {
-    private readonly db;
-    private readonly creditDb;
-    private readonly conductorOwner;
-    private readonly gatewayToken;
-    private readonly resolveAgentUrl;
-    private readonly maxBudget;
-    constructor(opts: ConductorModeOptions);
-    /**
-     * Execute a conductor skill with the given config and params.
-     *
-     * @param config - SkillConfig with type 'conductor' and conductor_skill field.
-     * @param params - Must include `task` string.
-     * @returns Execution result without latency_ms (added by SkillExecutor).
-     */
-    execute(config: SkillConfig, params: Record<string, unknown>): Promise<Omit<ExecutionResult, 'latency_ms'>>;
-}
-
-/**
- * Ed25519 keypair as raw DER-encoded Buffers.
- */
-interface KeyPair {
-    publicKey: Buffer;
-    privateKey: Buffer;
-}
-/**
- * Generates a new Ed25519 keypair.
- * Uses Node.js built-in crypto — no external dependencies.
- *
- * @returns Object with publicKey and privateKey as DER-encoded Buffers.
- */
-declare function generateKeyPair(): KeyPair;
-/**
- * Saves an Ed25519 keypair to disk.
- * Private key is written with mode 0o600 (owner read/write only).
- *
- * @param configDir - Directory to write key files into.
- * @param keys - The keypair to persist.
- */
-declare function saveKeyPair(configDir: string, keys: KeyPair): void;
-/**
- * Loads an Ed25519 keypair from disk.
- *
- * @param configDir - Directory containing private.key and public.key files.
- * @returns The loaded keypair.
- * @throws {AgentBnBError} with code 'KEYPAIR_NOT_FOUND' if either key file is missing.
- */
-declare function loadKeyPair(configDir: string): KeyPair;
-/**
- * Signs escrow receipt data with an Ed25519 private key.
- * Data is serialized to canonical JSON (sorted keys) before signing.
- *
- * @param data - The receipt data to sign (all fields except 'signature').
- * @param privateKey - DER-encoded Ed25519 private key.
- * @returns Base64url-encoded signature string.
- */
-declare function signEscrowReceipt(data: Record<string, unknown>, privateKey: Buffer): string;
-/**
- * Verifies an Ed25519 signature over escrow receipt data.
- * Returns false (does not throw) for invalid signatures or wrong keys.
- *
- * @param data - The receipt data that was signed (all fields except 'signature').
- * @param signature - Base64url-encoded signature string.
- * @param publicKey - DER-encoded Ed25519 public key.
- * @returns true if signature is valid, false otherwise.
- */
-declare function verifyEscrowReceipt(data: Record<string, unknown>, signature: string, publicKey: Buffer): boolean;
-
-/**
- * Zod schema for validating EscrowReceipt objects.
- * Used by providers to validate incoming receipts before verification.
+ * WebSocket relay message types for agent-to-registry communication.
+ * All messages are JSON-encoded with a discriminating `type` field.
  */
-declare const EscrowReceiptSchema: z.ZodObject<{
-    requester_owner: z.ZodString;
-    requester_public_key: z.ZodString;
-    amount: z.ZodNumber;
+/** Agent → Registry: Register agent and card on connect */
+declare const RegisterMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"register">;
+    owner: z.ZodString;
+    token: z.ZodString;
+    card: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    cards: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    type: "register";
+    owner: string;
+    token: string;
+    card: Record<string, unknown>;
+    cards?: Record<string, unknown>[] | undefined;
+}, {
+    type: "register";
+    owner: string;
+    token: string;
+    card: Record<string, unknown>;
+    cards?: Record<string, unknown>[] | undefined;
+}>;
+/** Registry → Agent: Acknowledge registration */
+declare const RegisteredMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"registered">;
+    agent_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "registered";
+    agent_id: string;
+}, {
+    type: "registered";
+    agent_id: string;
+}>;
+/** Agent A → Registry: Request relay to another agent */
+declare const RelayRequestMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"relay_request">;
+    id: z.ZodString;
+    target_owner: z.ZodString;
     card_id: z.ZodString;
     skill_id: z.ZodOptional<z.ZodString>;
-    timestamp: z.ZodString;
-    nonce: z.ZodString;
-    signature: z.ZodString;
+    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    requester: z.ZodOptional<z.ZodString>;
+    escrow_receipt: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
-    signature: string;
-    requester_owner: string;
-    requester_public_key: string;
-    amount: number;
+    type: "relay_request";
+    params: Record<string, unknown>;
+    id: string;
     card_id: string;
-    timestamp: string;
-    nonce: string;
+    target_owner: string;
     skill_id?: string | undefined;
+    requester?: string | undefined;
+    escrow_receipt?: Record<string, unknown> | undefined;
 }, {
-    signature: string;
-    requester_owner: string;
-    requester_public_key: string;
-    amount: number;
+    type: "relay_request";
+    id: string;
     card_id: string;
-    timestamp: string;
-    nonce: string;
+    target_owner: string;
+    params?: Record<string, unknown> | undefined;
     skill_id?: string | undefined;
+    requester?: string | undefined;
+    escrow_receipt?: Record<string, unknown> | undefined;
 }>;
-/**
- * Options for creating a signed escrow receipt.
- */
-interface CreateReceiptOpts {
-    /** Agent owner identifier (requester). */
-    owner: string;
-    /** Number of credits to commit. */
-    amount: number;
-    /** Capability Card ID being requested. */
-    cardId: string;
-    /** Optional skill ID within the card. */
-    skillId?: string;
-}
-/**
- * Creates a signed escrow receipt by atomically holding credits in the local DB
- * and producing a cryptographically signed receipt that can be sent to a provider.
- *
- * This combines local escrow hold + receipt generation from the requester's perspective.
- *
- * @param db - The credit database instance.
- * @param privateKey - DER-encoded Ed25519 private key for signing.
- * @param publicKey - DER-encoded Ed25519 public key (included in receipt for verification).
- * @param opts - Receipt creation options (owner, amount, cardId, skillId).
- * @returns Object with escrowId (local reference) and signed receipt (for transmission).
- * @throws {AgentBnBError} with code 'INSUFFICIENT_CREDITS' if balance is too low.
- */
-declare function createSignedEscrowReceipt(db: Database.Database, privateKey: Buffer, publicKey: Buffer, opts: CreateReceiptOpts): {
-    escrowId: string;
-    receipt: EscrowReceipt;
-};
-
-/**
- * Provider-side settlement: records earnings from a signed escrow receipt.
- * The provider calls this after successfully executing a capability.
- * Credits are recorded in the provider's own local DB.
- *
- * @param providerDb - The provider's local credit database.
- * @param providerOwner - Provider agent identifier.
- * @param receipt - The signed escrow receipt from the requester.
- * @returns Object indicating settlement success.
- */
-declare function settleProviderEarning(providerDb: Database.Database, providerOwner: string, receipt: EscrowReceipt): {
-    settled: true;
-};
-/**
- * Requester-side settlement: confirms that the escrow debit is permanent.
- * Called after the requester receives confirmation that the provider
- * successfully executed the capability. Marks escrow as 'settled' without
- * crediting anyone (credits stay deducted from requester).
- *
- * @param requesterDb - The requester's local credit database.
- * @param escrowId - The escrow ID to confirm as settled.
- */
-declare function settleRequesterEscrow(requesterDb: Database.Database, escrowId: string): void;
-/**
- * Requester-side failure handling: releases escrowed credits (refund).
- * Called when the capability execution fails and the requester needs
- * their credits back.
- *
- * @param requesterDb - The requester's local credit database.
- * @param escrowId - The escrow ID to release.
- */
-declare function releaseRequesterEscrow(requesterDb: Database.Database, escrowId: string): void;
-
-/**
- * Agent Identity — the unified identity record for an AgentBnB agent.
- * Stored at ~/.agentbnb/identity.json.
- */
-declare const AgentIdentitySchema: z.ZodObject<{
-    /** Deterministic ID derived from public key: sha256(hex).slice(0, 16). */
-    agent_id: z.ZodString;
-    /** Human-readable owner name (from config or init). */
-    owner: z.ZodString;
-    /** Hex-encoded Ed25519 public key. */
-    public_key: z.ZodString;
-    /** ISO 8601 timestamp of identity creation. */
-    created_at: z.ZodString;
-    /** Optional guarantor info if linked to a human. */
-    guarantor: z.ZodOptional<z.ZodObject<{
-        github_login: z.ZodString;
-        verified_at: z.ZodString;
+/** Registry → Agent B: Incoming request forwarded from Agent A */
+declare const IncomingRequestMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"incoming_request">;
+    id: z.ZodString;
+    from_owner: z.ZodString;
+    card_id: z.ZodString;
+    skill_id: z.ZodOptional<z.ZodString>;
+    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    requester: z.ZodOptional<z.ZodString>;
+    escrow_receipt: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    type: "incoming_request";
+    params: Record<string, unknown>;
+    id: string;
+    card_id: string;
+    from_owner: string;
+    skill_id?: string | undefined;
+    requester?: string | undefined;
+    escrow_receipt?: Record<string, unknown> | undefined;
+}, {
+    type: "incoming_request";
+    id: string;
+    card_id: string;
+    from_owner: string;
+    params?: Record<string, unknown> | undefined;
+    skill_id?: string | undefined;
+    requester?: string | undefined;
+    escrow_receipt?: Record<string, unknown> | undefined;
+}>;
+/** Agent B → Registry: Response to a relayed request */
+declare const RelayResponseMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"relay_response">;
+    id: z.ZodString;
+    result: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodNumber;
+        message: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        github_login: string;
-        verified_at: string;
+        code: number;
+        message: string;
     }, {
-        github_login: string;
-        verified_at: string;
+        code: number;
+        message: string;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    owner: string;
-    created_at: string;
-    agent_id: string;
-    public_key: string;
-    guarantor?: {
-        github_login: string;
-        verified_at: string;
+    type: "relay_response";
+    id: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
     } | undefined;
 }, {
-    owner: string;
-    created_at: string;
-    agent_id: string;
-    public_key: string;
-    guarantor?: {
-        github_login: string;
-        verified_at: string;
+    type: "relay_response";
+    id: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
     } | undefined;
 }>;
-type AgentIdentity = z.infer<typeof AgentIdentitySchema>;
-/**
- * Agent Certificate — a self-signed attestation of agent identity.
- * Used for P2P identity verification without a shared auth server.
- */
-declare const AgentCertificateSchema: z.ZodObject<{
-    identity: z.ZodObject<{
-        /** Deterministic ID derived from public key: sha256(hex).slice(0, 16). */
-        agent_id: z.ZodString;
-        /** Human-readable owner name (from config or init). */
-        owner: z.ZodString;
-        /** Hex-encoded Ed25519 public key. */
-        public_key: z.ZodString;
-        /** ISO 8601 timestamp of identity creation. */
-        created_at: z.ZodString;
-        /** Optional guarantor info if linked to a human. */
-        guarantor: z.ZodOptional<z.ZodObject<{
-            github_login: z.ZodString;
-            verified_at: z.ZodString;
-        }, "strip", z.ZodTypeAny, {
-            github_login: string;
-            verified_at: string;
-        }, {
-            github_login: string;
-            verified_at: string;
-        }>>;
+/** Registry → Agent A: Forwarded response from Agent B */
+declare const ResponseMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"response">;
+    id: z.ZodString;
+    result: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodNumber;
+        message: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        owner: string;
-        created_at: string;
-        agent_id: string;
-        public_key: string;
-        guarantor?: {
-            github_login: string;
-            verified_at: string;
-        } | undefined;
+        code: number;
+        message: string;
     }, {
-        owner: string;
-        created_at: string;
-        agent_id: string;
-        public_key: string;
-        guarantor?: {
-            github_login: string;
-            verified_at: string;
-        } | undefined;
-    }>;
-    /** ISO 8601 timestamp of certificate issuance. */
-    issued_at: z.ZodString;
-    /** ISO 8601 timestamp of certificate expiry. */
-    expires_at: z.ZodString;
-    /** Hex-encoded public key of the issuer (same as identity for self-signed). */
-    issuer_public_key: z.ZodString;
-    /** Base64url Ed25519 signature over { identity, issued_at, expires_at, issuer_public_key }. */
-    signature: z.ZodString;
+        code: number;
+        message: string;
+    }>>;
 }, "strip", z.ZodTypeAny, {
-    signature: string;
-    identity: {
-        owner: string;
-        created_at: string;
-        agent_id: string;
-        public_key: string;
-        guarantor?: {
-            github_login: string;
-            verified_at: string;
-        } | undefined;
-    };
-    issued_at: string;
-    expires_at: string;
-    issuer_public_key: string;
+    type: "response";
+    id: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    } | undefined;
 }, {
-    signature: string;
-    identity: {
-        owner: string;
-        created_at: string;
-        agent_id: string;
-        public_key: string;
-        guarantor?: {
-            github_login: string;
-            verified_at: string;
-        } | undefined;
-    };
-    issued_at: string;
-    expires_at: string;
-    issuer_public_key: string;
+    type: "response";
+    id: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    } | undefined;
 }>;
-type AgentCertificate = z.infer<typeof AgentCertificateSchema>;
-/**
- * Derives a deterministic agent_id from a hex-encoded public key.
- * Uses first 16 chars of SHA-256 hash.
- */
-declare function deriveAgentId(publicKeyHex: string): string;
-/**
- * Creates a new agent identity. Generates an Ed25519 keypair if one does not
- * already exist. Writes identity.json to the config directory.
- *
- * @param configDir - Directory to write identity.json into (e.g. ~/.agentbnb).
- * @param owner - Human-readable agent owner name.
- * @returns The newly created AgentIdentity.
- */
-declare function createIdentity(configDir: string, owner: string): AgentIdentity;
-/**
- * Loads an existing agent identity from disk.
- *
- * @param configDir - Directory containing identity.json.
- * @returns Parsed AgentIdentity or null if file does not exist.
- */
-declare function loadIdentity(configDir: string): AgentIdentity | null;
-/**
- * Persists an agent identity to disk.
- *
- * @param configDir - Directory to write identity.json into.
- * @param identity - The identity to save.
- */
-declare function saveIdentity(configDir: string, identity: AgentIdentity): void;
-/**
- * Issues a self-signed Agent Certificate. Valid for 365 days.
- *
- * @param identity - The agent identity to certify.
- * @param privateKey - DER-encoded Ed25519 private key.
- * @returns A signed AgentCertificate.
- */
-declare function issueAgentCertificate(identity: AgentIdentity, privateKey: Buffer): AgentCertificate;
-/**
- * Verifies an Agent Certificate's signature and expiry.
- *
- * @param cert - The certificate to verify.
- * @returns true if signature is valid and certificate has not expired.
- */
-declare function verifyAgentCertificate(cert: AgentCertificate): boolean;
-/**
- * Ensures an identity exists for the given config directory.
- * If identity.json already exists, returns it. Otherwise creates a new one.
- *
- * @param configDir - Config directory path.
- * @param owner - Owner name to use if creating new identity.
- * @returns The loaded or newly created AgentIdentity.
- */
-declare function ensureIdentity(configDir: string, owner: string): AgentIdentity;
-
-/**
- * Options for constructing an AgentBnBConsumer.
- */
-interface ConsumerOptions {
-    /** Override the config directory (default: ~/.agentbnb or AGENTBNB_DIR). */
-    configDir?: string;
-}
-/**
- * Options for requesting a capability.
- */
-interface ConsumerRequestOptions {
-    /** Gateway URL of the target agent. */
-    gatewayUrl: string;
-    /** Bearer token for the target agent's gateway. */
-    token: string;
-    /** Capability Card ID to execute. */
-    cardId: string;
-    /** Optional skill ID within the card. */
-    skillId?: string;
-    /** Input parameters for the capability. */
-    params?: Record<string, unknown>;
-    /** Credit amount to commit (escrow). */
-    credits: number;
-    /** Timeout in milliseconds. Default 30000. */
-    timeoutMs?: number;
-}
-/**
- * AgentBnBConsumer — high-level SDK class for agents consuming capabilities.
- *
- * Encapsulates the full request lifecycle: identity loading, escrow creation,
- * capability request, and settlement/release.
- *
- * @example
- * ```typescript
- * const consumer = new AgentBnBConsumer();
- * consumer.authenticate();
- * const result = await consumer.request({
- *   gatewayUrl: 'http://peer:7700',
- *   token: 'peer-token',
- *   cardId: 'uuid-of-card',
- *   credits: 5,
- * });
- * ```
- */
-declare class AgentBnBConsumer {
-    private configDir;
-    private identity;
-    private keys;
-    private creditDb;
-    constructor(opts?: ConsumerOptions);
-    /**
-     * Loads agent identity and keypair from disk.
-     * Creates identity if none exists (uses owner from config.json or generates one).
-     *
-     * @returns The loaded AgentIdentity.
-     * @throws {AgentBnBError} if keypair is missing and cannot be created.
-     */
-    authenticate(): AgentIdentity;
-    /**
-     * Returns the cached identity. Throws if not yet authenticated.
-     */
-    getIdentity(): AgentIdentity;
-    /**
-     * Requests a capability from a remote agent with full escrow lifecycle.
-     *
-     * 1. Creates a signed escrow receipt (holds credits locally)
-     * 2. Sends the request to the target gateway
-     * 3. Settles escrow on success, releases on failure
-     *
-     * @param opts - Request options including target, card, credits, and params.
-     * @returns The result from the capability execution.
-     * @throws {AgentBnBError} on insufficient credits, network error, or RPC error.
-     */
-    request(opts: ConsumerRequestOptions): Promise<unknown>;
-    /**
-     * Returns the current credit balance for this agent.
-     */
-    getBalance(): number;
-    /**
-     * Returns basic reputation data from the local credit database.
-     * Note: success_rate is computed from local request history only.
-     */
-    getReputation(): {
-        success_rate: number;
-        total_requests: number;
-    };
-    /**
-     * Closes the credit database connection. Call when done.
-     */
-    close(): void;
-    /** Lazily opens and caches the credit database. */
-    private getCreditDb;
-}
-
-/**
- * Options for constructing an AgentBnBProvider.
- */
-interface ProviderOptions {
-    /** Override the config directory (default: ~/.agentbnb or AGENTBNB_DIR). */
-    configDir?: string;
-}
-/**
- * Options for starting the sharing gateway.
- */
-interface StartSharingOptions {
-    /** Port to listen on (default: from config or 7700). */
-    port?: number;
-    /** Host to bind to (default: '0.0.0.0'). */
-    host?: string;
-}
-/**
- * Context returned after sharing starts.
- */
-interface SharingContext {
-    /** The Fastify gateway server instance. */
-    gateway: FastifyInstance;
-    /** Port the gateway is listening on. */
-    port: number;
-}
-/**
- * AgentBnBProvider — high-level SDK class for agents providing capabilities.
- *
- * Manages identity, gateway lifecycle, and capability listing.
- *
- * @example
- * ```typescript
- * const provider = new AgentBnBProvider();
- * provider.authenticate();
- * const ctx = await provider.startSharing({ port: 7700 });
- * console.log(provider.listCapabilities());
- * await provider.stopSharing();
- * ```
- */
-declare class AgentBnBProvider {
-    private configDir;
-    private identity;
-    private registryDb;
-    private creditDb;
-    private gateway;
-    constructor(opts?: ProviderOptions);
-    /**
-     * Loads agent identity from disk.
-     * Creates identity if none exists.
-     *
-     * @returns The loaded AgentIdentity.
-     */
-    authenticate(): AgentIdentity;
-    /**
-     * Returns the cached identity. Throws if not yet authenticated.
-     */
-    getIdentity(): AgentIdentity;
-    /**
-     * Starts the gateway server to share capabilities.
-     *
-     * @param opts - Optional port and host configuration.
-     * @returns Context with the gateway server and port.
-     */
-    startSharing(opts?: StartSharingOptions): Promise<SharingContext>;
-    /**
-     * Stops the gateway server.
-     */
-    stopSharing(): Promise<void>;
-    /**
-     * Returns all capability cards owned by this agent.
-     */
-    listCapabilities(): CapabilityCard[];
-    /**
-     * Returns the current credit balance for this agent.
-     */
-    getBalance(): number;
-    /**
-     * Closes all database connections and stops the gateway. Call when done.
-     */
-    close(): Promise<void>;
-    /** Lazily opens and caches the registry database. */
-    private getRegistryDb;
-    /** Lazily opens and caches the credit database. */
-    private getCreditDb;
-}
-
-/** Maximum agents a single human guarantor can back. */
-declare const MAX_AGENTS_PER_GUARANTOR = 10;
-/** Free credits granted per human guarantor registration. */
-declare const GUARANTOR_CREDIT_POOL = 50;
-/**
- * A Human Guarantor — a real person backing one or more agents.
- * Provides initial trust and credit pool for the agent network.
- */
-declare const GuarantorRecordSchema: z.ZodObject<{
-    id: z.ZodString;
-    github_login: z.ZodString;
-    agent_count: z.ZodNumber;
-    credit_pool: z.ZodNumber;
-    created_at: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    id: string;
-    created_at: string;
-    github_login: string;
-    agent_count: number;
-    credit_pool: number;
-}, {
-    id: string;
-    created_at: string;
-    github_login: string;
-    agent_count: number;
-    credit_pool: number;
-}>;
-type GuarantorRecord = z.infer<typeof GuarantorRecordSchema>;
-/**
- * Registers a new human guarantor via GitHub login.
- * Grants GUARANTOR_CREDIT_POOL (50) credits to be distributed among linked agents.
- *
- * @param db - The credit database instance.
- * @param githubLogin - GitHub username of the guarantor.
- * @returns The created GuarantorRecord.
- * @throws {AgentBnBError} with code 'GUARANTOR_EXISTS' if login already registered.
- */
-declare function registerGuarantor(db: Database.Database, githubLogin: string): GuarantorRecord;
-/**
- * Links an agent to a human guarantor.
- * Enforces the MAX_AGENTS_PER_GUARANTOR limit (10).
- *
- * @param db - The credit database instance.
- * @param agentId - The agent_id to link.
- * @param githubLogin - The guarantor's GitHub login.
- * @returns Updated GuarantorRecord.
- * @throws {AgentBnBError} with code 'GUARANTOR_NOT_FOUND' if login not registered.
- * @throws {AgentBnBError} with code 'MAX_AGENTS_EXCEEDED' if limit reached.
- * @throws {AgentBnBError} with code 'AGENT_ALREADY_LINKED' if agent already has a guarantor.
- */
-declare function linkAgentToGuarantor(db: Database.Database, agentId: string, githubLogin: string): GuarantorRecord;
-/**
- * Retrieves a guarantor record by GitHub login.
- *
- * @param db - The credit database instance.
- * @param githubLogin - The GitHub username to look up.
- * @returns GuarantorRecord or null if not found.
- */
-declare function getGuarantor(db: Database.Database, githubLogin: string): GuarantorRecord | null;
-/**
- * Gets the guarantor linked to an agent, if any.
- *
- * @param db - The credit database instance.
- * @param agentId - The agent_id to look up.
- * @returns GuarantorRecord or null if agent has no guarantor.
- */
-declare function getAgentGuarantor(db: Database.Database, agentId: string): GuarantorRecord | null;
-/**
- * Initiates a GitHub OAuth flow for guarantor verification.
- * This is a STUB — returns placeholder values. Actual OAuth implementation
- * is deferred to a future version.
- *
- * @returns Object with auth_url and state for the OAuth flow.
- */
-declare function initiateGithubAuth(): {
-    auth_url: string;
-    state: string;
-};
-
-/**
- * WebSocket relay message types for agent-to-registry communication.
- * All messages are JSON-encoded with a discriminating `type` field.
- */
-/** Agent → Registry: Register agent and card on connect */
-declare const RegisterMessageSchema: z.ZodObject<{
+/** Error message (either direction) */
+declare const ErrorMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    code: z.ZodString;
+    message: z.ZodString;
+    request_id: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "error";
+    code: string;
+    message: string;
+    request_id?: string | undefined;
+}, {
+    type: "error";
+    code: string;
+    message: string;
+    request_id?: string | undefined;
+}>;
+/** Discriminated union of all relay messages */
+declare const RelayMessageSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: z.ZodLiteral<"register">;
     owner: z.ZodString;
     token: z.ZodString;
     card: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    cards: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">>;
 }, "strip", z.ZodTypeAny, {
     type: "register";
     owner: string;
     token: string;
     card: Record<string, unknown>;
+    cards?: Record<string, unknown>[] | undefined;
 }, {
     type: "register";
     owner: string;
     token: string;
     card: Record<string, unknown>;
-}>;
-/** Registry → Agent: Acknowledge registration */
-declare const RegisteredMessageSchema: z.ZodObject<{
+    cards?: Record<string, unknown>[] | undefined;
+}>, z.ZodObject<{
     type: z.ZodLiteral<"registered">;
     agent_id: z.ZodString;
 }, "strip", z.ZodTypeAny, {
@@ -3206,9 +2704,7 @@ declare const RegisteredMessageSchema: z.ZodObject<{
 }, {
     type: "registered";
     agent_id: string;
-}>;
-/** Agent A → Registry: Request relay to another agent */
-declare const RelayRequestMessageSchema: z.ZodObject<{
+}>, z.ZodObject<{
     type: z.ZodLiteral<"relay_request">;
     id: z.ZodString;
     target_owner: z.ZodString;
@@ -3235,9 +2731,7 @@ declare const RelayRequestMessageSchema: z.ZodObject<{
     skill_id?: string | undefined;
     requester?: string | undefined;
     escrow_receipt?: Record<string, unknown> | undefined;
-}>;
-/** Registry → Agent B: Incoming request forwarded from Agent A */
-declare const IncomingRequestMessageSchema: z.ZodObject<{
+}>, z.ZodObject<{
     type: z.ZodLiteral<"incoming_request">;
     id: z.ZodString;
     from_owner: z.ZodString;
@@ -3264,9 +2758,7 @@ declare const IncomingRequestMessageSchema: z.ZodObject<{
     skill_id?: string | undefined;
     requester?: string | undefined;
     escrow_receipt?: Record<string, unknown> | undefined;
-}>;
-/** Agent B → Registry: Response to a relayed request */
-declare const RelayResponseMessageSchema: z.ZodObject<{
+}>, z.ZodObject<{
     type: z.ZodLiteral<"relay_response">;
     id: z.ZodString;
     result: z.ZodOptional<z.ZodUnknown>;
@@ -3296,9 +2788,7 @@ declare const RelayResponseMessageSchema: z.ZodObject<{
         code: number;
         message: string;
     } | undefined;
-}>;
-/** Registry → Agent A: Forwarded response from Agent B */
-declare const ResponseMessageSchema: z.ZodObject<{
+}>, z.ZodObject<{
     type: z.ZodLiteral<"response">;
     id: z.ZodString;
     result: z.ZodOptional<z.ZodUnknown>;
@@ -3328,9 +2818,7 @@ declare const ResponseMessageSchema: z.ZodObject<{
         code: number;
         message: string;
     } | undefined;
-}>;
-/** Error message (either direction) */
-declare const ErrorMessageSchema: z.ZodObject<{
+}>, z.ZodObject<{
     type: z.ZodLiteral<"error">;
     code: z.ZodString;
     message: z.ZodString;
@@ -3345,266 +2833,865 @@ declare const ErrorMessageSchema: z.ZodObject<{
     code: string;
     message: string;
     request_id?: string | undefined;
-}>;
-/** Discriminated union of all relay messages */
-declare const RelayMessageSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
-    type: z.ZodLiteral<"register">;
-    owner: z.ZodString;
-    token: z.ZodString;
-    card: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-}, "strip", z.ZodTypeAny, {
-    type: "register";
-    owner: string;
-    token: string;
-    card: Record<string, unknown>;
-}, {
-    type: "register";
-    owner: string;
-    token: string;
-    card: Record<string, unknown>;
-}>, z.ZodObject<{
-    type: z.ZodLiteral<"registered">;
-    agent_id: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    type: "registered";
-    agent_id: string;
-}, {
-    type: "registered";
-    agent_id: string;
 }>, z.ZodObject<{
-    type: z.ZodLiteral<"relay_request">;
+    type: z.ZodLiteral<"relay_progress">;
     id: z.ZodString;
-    target_owner: z.ZodString;
-    card_id: z.ZodString;
-    skill_id: z.ZodOptional<z.ZodString>;
-    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    requester: z.ZodOptional<z.ZodString>;
-    escrow_receipt: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    progress: z.ZodOptional<z.ZodNumber>;
+    message: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    type: "relay_request";
-    params: Record<string, unknown>;
+    type: "relay_progress";
     id: string;
-    card_id: string;
-    target_owner: string;
-    skill_id?: string | undefined;
-    requester?: string | undefined;
-    escrow_receipt?: Record<string, unknown> | undefined;
+    message?: string | undefined;
+    progress?: number | undefined;
 }, {
-    type: "relay_request";
+    type: "relay_progress";
     id: string;
-    card_id: string;
-    target_owner: string;
-    params?: Record<string, unknown> | undefined;
-    skill_id?: string | undefined;
-    requester?: string | undefined;
-    escrow_receipt?: Record<string, unknown> | undefined;
-}>, z.ZodObject<{
-    type: z.ZodLiteral<"incoming_request">;
-    id: z.ZodString;
-    from_owner: z.ZodString;
+    message?: string | undefined;
+    progress?: number | undefined;
+}>]>;
+type RegisterMessage = z.infer<typeof RegisterMessageSchema>;
+type RegisteredMessage = z.infer<typeof RegisteredMessageSchema>;
+type RelayRequestMessage = z.infer<typeof RelayRequestMessageSchema>;
+type IncomingRequestMessage = z.infer<typeof IncomingRequestMessageSchema>;
+type RelayResponseMessage = z.infer<typeof RelayResponseMessageSchema>;
+type ResponseMessage = z.infer<typeof ResponseMessageSchema>;
+type ErrorMessage = z.infer<typeof ErrorMessageSchema>;
+type RelayMessage = z.infer<typeof RelayMessageSchema>;
+/** Pending relay request tracking */
+interface PendingRelayRequest {
+    originOwner: string;
+    timeout: ReturnType<typeof setTimeout>;
+    /** Escrow ID for the credit hold, if credits were reserved for this request */
+    escrowId?: string;
+    /** The target provider owner, needed to release escrow on provider disconnect */
+    targetOwner?: string;
+    /** Job ID if this request was dispatched from the job queue (relay bridge) */
+    jobId?: string;
+}
+/** Relay server state returned from registerWebSocketRelay */
+interface RelayState {
+    /** Number of currently connected agents */
+    getOnlineCount(): number;
+    /** List of connected agent owners */
+    getOnlineOwners(): string[];
+    /** Graceful shutdown -- close all connections */
+    shutdown(): void;
+    /** Set a callback invoked when an agent registers (comes online) */
+    setOnAgentOnline?(cb: (owner: string) => void): void;
+    /** Get the active connections map (owner -> WebSocket) */
+    getConnections?(): Map<string, unknown>;
+    /** Get the pending requests map */
+    getPendingRequests?(): Map<string, PendingRelayRequest>;
+    /** Send a JSON message over a WebSocket */
+    sendMessage?(ws: unknown, msg: Record<string, unknown>): void;
+}
+
+/** Result of handling an incoming relay request */
+interface RelayHandlerResult {
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+/** Options for the RelayClient constructor */
+interface RelayClientOptions {
+    /** Registry WebSocket URL (e.g., "wss://hub.agentbnb.dev/ws") */
+    registryUrl: string;
+    /** Agent owner identifier */
+    owner: string;
+    /** Authentication token */
+    token: string;
+    /** Capability card data to register */
+    card: Record<string, unknown>;
+    /** Additional cards to register alongside the primary card (e.g., conductor card) */
+    cards?: Record<string, unknown>[];
+    /** Handler for incoming relay requests from other agents */
+    onRequest: (req: IncomingRequestMessage) => Promise<RelayHandlerResult>;
+    /** Suppress logging. Default false. */
+    silent?: boolean;
+}
+/** Options for making a relay request to another agent */
+interface RelayRequestOptions$1 {
+    targetOwner: string;
+    cardId: string;
+    skillId?: string;
+    params: Record<string, unknown>;
+    requester?: string;
+    escrowReceipt?: Record<string, unknown>;
+    timeoutMs?: number;
+    /** Optional callback invoked when the provider sends relay_progress heartbeats. */
+    onProgress?: (progress: {
+        id: string;
+        progress?: number;
+        message?: string;
+    }) => void;
+}
+/**
+ * WebSocket client for connecting to an AgentBnB registry relay.
+ * Handles registration, auto-reconnect, incoming requests, and outbound relay requests.
+ */
+declare class RelayClient {
+    private ws;
+    private readonly opts;
+    private readonly pendingRequests;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private intentionalClose;
+    private registered;
+    private pongTimeout;
+    private pingInterval;
+    constructor(opts: RelayClientOptions);
+    /**
+     * Connect to the registry relay and register.
+     * Resolves when registration is acknowledged.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the registry relay.
+     */
+    disconnect(): void;
+    /**
+     * Send a relay request to another agent via the registry.
+     * @returns The result from the target agent.
+     */
+    request(opts: RelayRequestOptions$1): Promise<unknown>;
+    /**
+     * Send a relay_progress message to the relay server for a given request.
+     * Used by the onRequest handler to forward SkillExecutor progress updates
+     * to the requesting agent so it can reset its timeout window.
+     *
+     * @param requestId - The relay request ID to associate progress with.
+     * @param info - Progress details (step, total, message).
+     */
+    sendProgress(requestId: string, info: {
+        step: number;
+        total: number;
+        message: string;
+    }): void;
+    /** Whether the client is connected and registered */
+    get isConnected(): boolean;
+    private buildWsUrl;
+    private handleMessage;
+    private handleIncomingRequest;
+    private handleResponse;
+    private handleError;
+    private handleProgress;
+    private send;
+    private startPingInterval;
+    private stopPingInterval;
+    private cleanup;
+    private scheduleReconnect;
+}
+
+/**
+ * PipelineOrchestrator — DAG-based remote execution engine for the Conductor.
+ *
+ * Executes sub-tasks across remote agents via the Gateway client,
+ * respecting dependency ordering (parallel waves for independent tasks),
+ * output piping between steps, and retry with alternative agents on failure.
+ *
+ * Budget checking is NOT done here — the caller (ConductorMode) handles that.
+ * This module is pure execution.
+ */
+
+/**
+ * Options for the orchestrate() function.
+ */
+interface OrchestrateOptions {
+    /** Ordered list of sub-tasks forming a dependency DAG. */
+    subtasks: SubTask[];
+    /** Match results keyed by subtask ID. */
+    matches: Map<string, MatchResult>;
+    /** Bearer token for authenticating with remote agents. */
+    gatewayToken: string;
+    /** Resolves an agent owner to their gateway URL and card ID. */
+    resolveAgentUrl: (agentOwner: string) => {
+        url: string;
+        cardId: string;
+    };
+    /** Per-task timeout in milliseconds. Default 30000. */
+    timeoutMs?: number;
+    /** Maximum budget in credits. If set, aborts remaining tasks when exceeded. */
+    maxBudget?: number;
+    /** Optional relay client for executing tasks on remote agents (relay:// URLs). */
+    relayClient?: RelayClient;
+    /** Owner identifier of the requester agent. Used for relay requests. */
+    requesterOwner?: string;
+}
+/**
+ * Executes a DAG of sub-tasks across remote agents via Gateway.
+ *
+ * Execution flow:
+ * 1. Computes execution waves from dependency graph
+ * 2. For each wave, executes all tasks in parallel via Promise.allSettled
+ * 3. Before each task, interpolates params against completed step outputs
+ * 4. On failure, retries with the first alternative agent from MatchResult
+ * 5. Tracks per-task spending and total credits
+ * 6. Optionally enforces a maxBudget ceiling
+ *
+ * @param opts - Orchestration options.
+ * @returns Aggregated orchestration result.
+ */
+declare function orchestrate(opts: OrchestrateOptions): Promise<OrchestrationResult>;
+
+/**
+ * ConductorMode — ExecutorMode implementation for Conductor skills.
+ *
+ * Chains TaskDecomposer -> CapabilityMatcher -> BudgetController -> PipelineOrchestrator
+ * to execute multi-agent orchestration pipelines via the SkillExecutor dispatch system.
+ *
+ * Supports two conductor skills:
+ * - `orchestrate`: Full pipeline — decompose, match, budget check, execute, return results.
+ * - `plan`: Planning only — decompose, match, budget check, return plan without executing.
+ */
+
+/**
+ * Configuration options for ConductorMode.
+ */
+interface ConductorModeOptions {
+    /** Registry database for card search (FTS5). */
+    db: Database.Database;
+    /** Credit database for budget checks. */
+    creditDb: Database.Database;
+    /** Owner ID of the conductor agent — used for self-exclusion in matching. */
+    conductorOwner: string;
+    /** Bearer token for authenticating with remote agents. */
+    gatewayToken: string;
+    /** Resolves an agent owner to their gateway URL and card ID. */
+    resolveAgentUrl: (owner: string) => {
+        url: string;
+        cardId: string;
+    };
+    /** Maximum budget in credits for orchestration runs. Default 100. */
+    maxBudget?: number;
+}
+/**
+ * ExecutorMode implementation for Conductor skills ('orchestrate' and 'plan').
+ *
+ * Dispatches through the full Conductor pipeline:
+ * 1. TaskDecomposer breaks the task into SubTasks
+ * 2. CapabilityMatcher finds agents for each sub-task
+ * 3. BudgetController validates cost against limits
+ * 4. PipelineOrchestrator executes the DAG (orchestrate only)
+ */
+declare class ConductorMode implements ExecutorMode {
+    private readonly db;
+    private readonly creditDb;
+    private readonly conductorOwner;
+    private readonly gatewayToken;
+    private readonly resolveAgentUrl;
+    private readonly maxBudget;
+    constructor(opts: ConductorModeOptions);
+    /**
+     * Execute a conductor skill with the given config and params.
+     *
+     * @param config - SkillConfig with type 'conductor' and conductor_skill field.
+     * @param params - Must include `task` string.
+     * @returns Execution result without latency_ms (added by SkillExecutor).
+     */
+    execute(config: SkillConfig, params: Record<string, unknown>, onProgress?: ProgressCallback): Promise<Omit<ExecutionResult, 'latency_ms'>>;
+}
+
+/**
+ * Ed25519 keypair as raw DER-encoded Buffers.
+ */
+interface KeyPair {
+    publicKey: Buffer;
+    privateKey: Buffer;
+}
+/**
+ * Generates a new Ed25519 keypair.
+ * Uses Node.js built-in crypto — no external dependencies.
+ *
+ * @returns Object with publicKey and privateKey as DER-encoded Buffers.
+ */
+declare function generateKeyPair(): KeyPair;
+/**
+ * Saves an Ed25519 keypair to disk.
+ * Private key is written with mode 0o600 (owner read/write only).
+ *
+ * @param configDir - Directory to write key files into.
+ * @param keys - The keypair to persist.
+ */
+declare function saveKeyPair(configDir: string, keys: KeyPair): void;
+/**
+ * Loads an Ed25519 keypair from disk.
+ *
+ * @param configDir - Directory containing private.key and public.key files.
+ * @returns The loaded keypair.
+ * @throws {AgentBnBError} with code 'KEYPAIR_NOT_FOUND' if either key file is missing.
+ */
+declare function loadKeyPair(configDir: string): KeyPair;
+/**
+ * Signs escrow receipt data with an Ed25519 private key.
+ * Data is serialized to canonical JSON (sorted keys) before signing.
+ *
+ * @param data - The receipt data to sign (all fields except 'signature').
+ * @param privateKey - DER-encoded Ed25519 private key.
+ * @returns Base64url-encoded signature string.
+ */
+declare function signEscrowReceipt(data: Record<string, unknown>, privateKey: Buffer): string;
+/**
+ * Verifies an Ed25519 signature over escrow receipt data.
+ * Returns false (does not throw) for invalid signatures or wrong keys.
+ *
+ * @param data - The receipt data that was signed (all fields except 'signature').
+ * @param signature - Base64url-encoded signature string.
+ * @param publicKey - DER-encoded Ed25519 public key.
+ * @returns true if signature is valid, false otherwise.
+ */
+declare function verifyEscrowReceipt(data: Record<string, unknown>, signature: string, publicKey: Buffer): boolean;
+
+/**
+ * Zod schema for validating EscrowReceipt objects.
+ * Used by providers to validate incoming receipts before verification.
+ */
+declare const EscrowReceiptSchema: z.ZodObject<{
+    requester_owner: z.ZodString;
+    requester_public_key: z.ZodString;
+    amount: z.ZodNumber;
     card_id: z.ZodString;
     skill_id: z.ZodOptional<z.ZodString>;
-    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    requester: z.ZodOptional<z.ZodString>;
-    escrow_receipt: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    timestamp: z.ZodString;
+    nonce: z.ZodString;
+    signature: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    type: "incoming_request";
-    params: Record<string, unknown>;
-    id: string;
+    signature: string;
+    requester_owner: string;
+    requester_public_key: string;
+    amount: number;
     card_id: string;
-    from_owner: string;
+    timestamp: string;
+    nonce: string;
     skill_id?: string | undefined;
-    requester?: string | undefined;
-    escrow_receipt?: Record<string, unknown> | undefined;
 }, {
-    type: "incoming_request";
-    id: string;
+    signature: string;
+    requester_owner: string;
+    requester_public_key: string;
+    amount: number;
     card_id: string;
-    from_owner: string;
-    params?: Record<string, unknown> | undefined;
+    timestamp: string;
+    nonce: string;
     skill_id?: string | undefined;
-    requester?: string | undefined;
-    escrow_receipt?: Record<string, unknown> | undefined;
-}>, z.ZodObject<{
-    type: z.ZodLiteral<"relay_response">;
-    id: z.ZodString;
-    result: z.ZodOptional<z.ZodUnknown>;
-    error: z.ZodOptional<z.ZodObject<{
-        code: z.ZodNumber;
-        message: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        code: number;
-        message: string;
-    }, {
-        code: number;
-        message: string;
-    }>>;
-}, "strip", z.ZodTypeAny, {
-    type: "relay_response";
-    id: string;
-    result?: unknown;
-    error?: {
-        code: number;
-        message: string;
-    } | undefined;
-}, {
-    type: "relay_response";
-    id: string;
-    result?: unknown;
-    error?: {
-        code: number;
-        message: string;
-    } | undefined;
-}>, z.ZodObject<{
-    type: z.ZodLiteral<"response">;
-    id: z.ZodString;
-    result: z.ZodOptional<z.ZodUnknown>;
-    error: z.ZodOptional<z.ZodObject<{
-        code: z.ZodNumber;
-        message: z.ZodString;
+}>;
+/**
+ * Options for creating a signed escrow receipt.
+ */
+interface CreateReceiptOpts {
+    /** Agent owner identifier (requester). */
+    owner: string;
+    /** Number of credits to commit. */
+    amount: number;
+    /** Capability Card ID being requested. */
+    cardId: string;
+    /** Optional skill ID within the card. */
+    skillId?: string;
+}
+/**
+ * Creates a signed escrow receipt by atomically holding credits in the local DB
+ * and producing a cryptographically signed receipt that can be sent to a provider.
+ *
+ * This combines local escrow hold + receipt generation from the requester's perspective.
+ *
+ * @param db - The credit database instance.
+ * @param privateKey - DER-encoded Ed25519 private key for signing.
+ * @param publicKey - DER-encoded Ed25519 public key (included in receipt for verification).
+ * @param opts - Receipt creation options (owner, amount, cardId, skillId).
+ * @returns Object with escrowId (local reference) and signed receipt (for transmission).
+ * @throws {AgentBnBError} with code 'INSUFFICIENT_CREDITS' if balance is too low.
+ */
+declare function createSignedEscrowReceipt(db: Database.Database, privateKey: Buffer, publicKey: Buffer, opts: CreateReceiptOpts): {
+    escrowId: string;
+    receipt: EscrowReceipt;
+};
+
+/**
+ * Provider-side settlement: records earnings from a signed escrow receipt.
+ * The provider calls this after successfully executing a capability.
+ * Credits are recorded in the provider's own local DB.
+ *
+ * @param providerDb - The provider's local credit database.
+ * @param providerOwner - Provider agent identifier.
+ * @param receipt - The signed escrow receipt from the requester.
+ * @returns Object indicating settlement success.
+ */
+declare function settleProviderEarning(providerDb: Database.Database, providerOwner: string, receipt: EscrowReceipt): {
+    settled: true;
+};
+/**
+ * Requester-side settlement: confirms that the escrow debit is permanent.
+ * Called after the requester receives confirmation that the provider
+ * successfully executed the capability. Marks escrow as 'settled' without
+ * crediting anyone (credits stay deducted from requester).
+ *
+ * @param requesterDb - The requester's local credit database.
+ * @param escrowId - The escrow ID to confirm as settled.
+ */
+declare function settleRequesterEscrow(requesterDb: Database.Database, escrowId: string): void;
+/**
+ * Requester-side failure handling: releases escrowed credits (refund).
+ * Called when the capability execution fails and the requester needs
+ * their credits back.
+ *
+ * @param requesterDb - The requester's local credit database.
+ * @param escrowId - The escrow ID to release.
+ */
+declare function releaseRequesterEscrow(requesterDb: Database.Database, escrowId: string): void;
+
+/**
+ * Agent Identity — the unified identity record for an AgentBnB agent.
+ * Stored at ~/.agentbnb/identity.json.
+ */
+declare const AgentIdentitySchema: z.ZodObject<{
+    /** Deterministic ID derived from public key: sha256(hex).slice(0, 16). */
+    agent_id: z.ZodString;
+    /** Human-readable owner name (from config or init). */
+    owner: z.ZodString;
+    /** Hex-encoded Ed25519 public key. */
+    public_key: z.ZodString;
+    /** ISO 8601 timestamp of identity creation. */
+    created_at: z.ZodString;
+    /** Optional guarantor info if linked to a human. */
+    guarantor: z.ZodOptional<z.ZodObject<{
+        github_login: z.ZodString;
+        verified_at: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        code: number;
-        message: string;
+        github_login: string;
+        verified_at: string;
     }, {
-        code: number;
-        message: string;
+        github_login: string;
+        verified_at: string;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    type: "response";
-    id: string;
-    result?: unknown;
-    error?: {
-        code: number;
-        message: string;
+    owner: string;
+    created_at: string;
+    agent_id: string;
+    public_key: string;
+    guarantor?: {
+        github_login: string;
+        verified_at: string;
     } | undefined;
 }, {
-    type: "response";
-    id: string;
-    result?: unknown;
-    error?: {
-        code: number;
-        message: string;
+    owner: string;
+    created_at: string;
+    agent_id: string;
+    public_key: string;
+    guarantor?: {
+        github_login: string;
+        verified_at: string;
     } | undefined;
-}>, z.ZodObject<{
-    type: z.ZodLiteral<"error">;
-    code: z.ZodString;
-    message: z.ZodString;
-    request_id: z.ZodOptional<z.ZodString>;
+}>;
+type AgentIdentity = z.infer<typeof AgentIdentitySchema>;
+/**
+ * Agent Certificate — a self-signed attestation of agent identity.
+ * Used for P2P identity verification without a shared auth server.
+ */
+declare const AgentCertificateSchema: z.ZodObject<{
+    identity: z.ZodObject<{
+        /** Deterministic ID derived from public key: sha256(hex).slice(0, 16). */
+        agent_id: z.ZodString;
+        /** Human-readable owner name (from config or init). */
+        owner: z.ZodString;
+        /** Hex-encoded Ed25519 public key. */
+        public_key: z.ZodString;
+        /** ISO 8601 timestamp of identity creation. */
+        created_at: z.ZodString;
+        /** Optional guarantor info if linked to a human. */
+        guarantor: z.ZodOptional<z.ZodObject<{
+            github_login: z.ZodString;
+            verified_at: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            github_login: string;
+            verified_at: string;
+        }, {
+            github_login: string;
+            verified_at: string;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        owner: string;
+        created_at: string;
+        agent_id: string;
+        public_key: string;
+        guarantor?: {
+            github_login: string;
+            verified_at: string;
+        } | undefined;
+    }, {
+        owner: string;
+        created_at: string;
+        agent_id: string;
+        public_key: string;
+        guarantor?: {
+            github_login: string;
+            verified_at: string;
+        } | undefined;
+    }>;
+    /** ISO 8601 timestamp of certificate issuance. */
+    issued_at: z.ZodString;
+    /** ISO 8601 timestamp of certificate expiry. */
+    expires_at: z.ZodString;
+    /** Hex-encoded public key of the issuer (same as identity for self-signed). */
+    issuer_public_key: z.ZodString;
+    /** Base64url Ed25519 signature over { identity, issued_at, expires_at, issuer_public_key }. */
+    signature: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    type: "error";
-    code: string;
-    message: string;
-    request_id?: string | undefined;
+    signature: string;
+    identity: {
+        owner: string;
+        created_at: string;
+        agent_id: string;
+        public_key: string;
+        guarantor?: {
+            github_login: string;
+            verified_at: string;
+        } | undefined;
+    };
+    issued_at: string;
+    expires_at: string;
+    issuer_public_key: string;
 }, {
-    type: "error";
-    code: string;
-    message: string;
-    request_id?: string | undefined;
-}>]>;
-type RegisterMessage = z.infer<typeof RegisterMessageSchema>;
-type RegisteredMessage = z.infer<typeof RegisteredMessageSchema>;
-type RelayRequestMessage = z.infer<typeof RelayRequestMessageSchema>;
-type IncomingRequestMessage = z.infer<typeof IncomingRequestMessageSchema>;
-type RelayResponseMessage = z.infer<typeof RelayResponseMessageSchema>;
-type ResponseMessage = z.infer<typeof ResponseMessageSchema>;
-type ErrorMessage = z.infer<typeof ErrorMessageSchema>;
-type RelayMessage = z.infer<typeof RelayMessageSchema>;
-/** Relay server state returned from registerWebSocketRelay */
-interface RelayState {
-    /** Number of currently connected agents */
-    getOnlineCount(): number;
-    /** List of connected agent owners */
-    getOnlineOwners(): string[];
-    /** Graceful shutdown — close all connections */
-    shutdown(): void;
+    signature: string;
+    identity: {
+        owner: string;
+        created_at: string;
+        agent_id: string;
+        public_key: string;
+        guarantor?: {
+            github_login: string;
+            verified_at: string;
+        } | undefined;
+    };
+    issued_at: string;
+    expires_at: string;
+    issuer_public_key: string;
+}>;
+type AgentCertificate = z.infer<typeof AgentCertificateSchema>;
+/**
+ * Derives a deterministic agent_id from a hex-encoded public key.
+ * Uses first 16 chars of SHA-256 hash.
+ */
+declare function deriveAgentId(publicKeyHex: string): string;
+/**
+ * Creates a new agent identity. Generates an Ed25519 keypair if one does not
+ * already exist. Writes identity.json to the config directory.
+ *
+ * @param configDir - Directory to write identity.json into (e.g. ~/.agentbnb).
+ * @param owner - Human-readable agent owner name.
+ * @returns The newly created AgentIdentity.
+ */
+declare function createIdentity(configDir: string, owner: string): AgentIdentity;
+/**
+ * Loads an existing agent identity from disk.
+ *
+ * @param configDir - Directory containing identity.json.
+ * @returns Parsed AgentIdentity or null if file does not exist.
+ */
+declare function loadIdentity(configDir: string): AgentIdentity | null;
+/**
+ * Persists an agent identity to disk.
+ *
+ * @param configDir - Directory to write identity.json into.
+ * @param identity - The identity to save.
+ */
+declare function saveIdentity(configDir: string, identity: AgentIdentity): void;
+/**
+ * Issues a self-signed Agent Certificate. Valid for 365 days.
+ *
+ * @param identity - The agent identity to certify.
+ * @param privateKey - DER-encoded Ed25519 private key.
+ * @returns A signed AgentCertificate.
+ */
+declare function issueAgentCertificate(identity: AgentIdentity, privateKey: Buffer): AgentCertificate;
+/**
+ * Verifies an Agent Certificate's signature and expiry.
+ *
+ * @param cert - The certificate to verify.
+ * @returns true if signature is valid and certificate has not expired.
+ */
+declare function verifyAgentCertificate(cert: AgentCertificate): boolean;
+/**
+ * Ensures an identity exists for the given config directory.
+ * If identity.json already exists, returns it. Otherwise creates a new one.
+ *
+ * @param configDir - Config directory path.
+ * @param owner - Owner name to use if creating new identity.
+ * @returns The loaded or newly created AgentIdentity.
+ */
+declare function ensureIdentity(configDir: string, owner: string): AgentIdentity;
+
+/**
+ * Options for constructing an AgentBnBConsumer.
+ */
+interface ConsumerOptions {
+    /** Override the config directory (default: ~/.agentbnb or AGENTBNB_DIR). */
+    configDir?: string;
+}
+/**
+ * Options for requesting a capability.
+ */
+interface ConsumerRequestOptions {
+    /** Gateway URL of the target agent. */
+    gatewayUrl: string;
+    /** Bearer token for the target agent's gateway. */
+    token: string;
+    /** Capability Card ID to execute. */
+    cardId: string;
+    /** Optional skill ID within the card. */
+    skillId?: string;
+    /** Input parameters for the capability. */
+    params?: Record<string, unknown>;
+    /** Credit amount to commit (escrow). */
+    credits: number;
+    /** Timeout in milliseconds. Default 30000. */
+    timeoutMs?: number;
+}
+/**
+ * AgentBnBConsumer — high-level SDK class for agents consuming capabilities.
+ *
+ * Encapsulates the full request lifecycle: identity loading, escrow creation,
+ * capability request, and settlement/release.
+ *
+ * @example
+ * ```typescript
+ * const consumer = new AgentBnBConsumer();
+ * consumer.authenticate();
+ * const result = await consumer.request({
+ *   gatewayUrl: 'http://peer:7700',
+ *   token: 'peer-token',
+ *   cardId: 'uuid-of-card',
+ *   credits: 5,
+ * });
+ * ```
+ */
+declare class AgentBnBConsumer {
+    private configDir;
+    private identity;
+    private keys;
+    private creditDb;
+    constructor(opts?: ConsumerOptions);
+    /**
+     * Loads agent identity and keypair from disk.
+     * Creates identity if none exists (uses owner from config.json or generates one).
+     *
+     * @returns The loaded AgentIdentity.
+     * @throws {AgentBnBError} if keypair is missing and cannot be created.
+     */
+    authenticate(): AgentIdentity;
+    /**
+     * Returns the cached identity. Throws if not yet authenticated.
+     */
+    getIdentity(): AgentIdentity;
+    /**
+     * Requests a capability from a remote agent with full escrow lifecycle.
+     *
+     * 1. Creates a signed escrow receipt (holds credits locally)
+     * 2. Sends the request to the target gateway
+     * 3. Settles escrow on success, releases on failure
+     *
+     * @param opts - Request options including target, card, credits, and params.
+     * @returns The result from the capability execution.
+     * @throws {AgentBnBError} on insufficient credits, network error, or RPC error.
+     */
+    request(opts: ConsumerRequestOptions): Promise<unknown>;
+    /**
+     * Returns the current credit balance for this agent.
+     */
+    getBalance(): number;
+    /**
+     * Returns basic reputation data from the local credit database.
+     * Note: success_rate is computed from local request history only.
+     */
+    getReputation(): {
+        success_rate: number;
+        total_requests: number;
+    };
+    /**
+     * Closes the credit database connection. Call when done.
+     */
+    close(): void;
+    /** Lazily opens and caches the credit database. */
+    private getCreditDb;
 }
 
 /**
- * Registers WebSocket relay on an existing Fastify instance.
- * Adds a `/ws` route that upgrades HTTP to WebSocket for agent relay.
- *
- * @param server - Fastify instance with @fastify/websocket already registered.
- * @param db - Registry database instance.
- * @returns RelayState for monitoring and graceful shutdown.
+ * Options for constructing an AgentBnBProvider.
  */
-declare function registerWebSocketRelay(server: FastifyInstance, db: Database.Database): RelayState;
-
-/** Result of handling an incoming relay request */
-interface RelayHandlerResult {
-    result?: unknown;
-    error?: {
-        code: number;
-        message: string;
-    };
+interface ProviderOptions {
+    /** Override the config directory (default: ~/.agentbnb or AGENTBNB_DIR). */
+    configDir?: string;
 }
-/** Options for the RelayClient constructor */
-interface RelayClientOptions {
-    /** Registry WebSocket URL (e.g., "wss://hub.agentbnb.dev/ws") */
-    registryUrl: string;
-    /** Agent owner identifier */
-    owner: string;
-    /** Authentication token */
-    token: string;
-    /** Capability card data to register */
-    card: Record<string, unknown>;
-    /** Handler for incoming relay requests from other agents */
-    onRequest: (req: IncomingRequestMessage) => Promise<RelayHandlerResult>;
-    /** Suppress logging. Default false. */
-    silent?: boolean;
+/**
+ * Options for starting the sharing gateway.
+ */
+interface StartSharingOptions {
+    /** Port to listen on (default: from config or 7700). */
+    port?: number;
+    /** Host to bind to (default: '0.0.0.0'). */
+    host?: string;
 }
-/** Options for making a relay request to another agent */
-interface RelayRequestOptions$1 {
-    targetOwner: string;
-    cardId: string;
-    skillId?: string;
-    params: Record<string, unknown>;
-    requester?: string;
-    escrowReceipt?: Record<string, unknown>;
-    timeoutMs?: number;
+/**
+ * Context returned after sharing starts.
+ */
+interface SharingContext {
+    /** The Fastify gateway server instance. */
+    gateway: FastifyInstance;
+    /** Port the gateway is listening on. */
+    port: number;
 }
 /**
- * WebSocket client for connecting to an AgentBnB registry relay.
- * Handles registration, auto-reconnect, incoming requests, and outbound relay requests.
+ * AgentBnBProvider — high-level SDK class for agents providing capabilities.
+ *
+ * Manages identity, gateway lifecycle, and capability listing.
+ *
+ * @example
+ * ```typescript
+ * const provider = new AgentBnBProvider();
+ * provider.authenticate();
+ * const ctx = await provider.startSharing({ port: 7700 });
+ * console.log(provider.listCapabilities());
+ * await provider.stopSharing();
+ * ```
  */
-declare class RelayClient {
-    private ws;
-    private readonly opts;
-    private readonly pendingRequests;
-    private reconnectAttempts;
-    private reconnectTimer;
-    private intentionalClose;
-    private registered;
-    private pongTimeout;
-    private pingInterval;
-    constructor(opts: RelayClientOptions);
+declare class AgentBnBProvider {
+    private configDir;
+    private identity;
+    private registryDb;
+    private creditDb;
+    private gateway;
+    constructor(opts?: ProviderOptions);
     /**
-     * Connect to the registry relay and register.
-     * Resolves when registration is acknowledged.
+     * Loads agent identity from disk.
+     * Creates identity if none exists.
+     *
+     * @returns The loaded AgentIdentity.
      */
-    connect(): Promise<void>;
+    authenticate(): AgentIdentity;
     /**
-     * Disconnect from the registry relay.
+     * Returns the cached identity. Throws if not yet authenticated.
      */
-    disconnect(): void;
+    getIdentity(): AgentIdentity;
     /**
-     * Send a relay request to another agent via the registry.
-     * @returns The result from the target agent.
+     * Starts the gateway server to share capabilities.
+     *
+     * @param opts - Optional port and host configuration.
+     * @returns Context with the gateway server and port.
      */
-    request(opts: RelayRequestOptions$1): Promise<unknown>;
-    /** Whether the client is connected and registered */
-    get isConnected(): boolean;
-    private buildWsUrl;
-    private handleMessage;
-    private handleIncomingRequest;
-    private handleResponse;
-    private handleError;
-    private send;
-    private startPingInterval;
-    private stopPingInterval;
-    private cleanup;
-    private scheduleReconnect;
+    startSharing(opts?: StartSharingOptions): Promise<SharingContext>;
+    /**
+     * Stops the gateway server.
+     */
+    stopSharing(): Promise<void>;
+    /**
+     * Returns all capability cards owned by this agent.
+     */
+    listCapabilities(): CapabilityCard[];
+    /**
+     * Returns the current credit balance for this agent.
+     */
+    getBalance(): number;
+    /**
+     * Closes all database connections and stops the gateway. Call when done.
+     */
+    close(): Promise<void>;
+    /** Lazily opens and caches the registry database. */
+    private getRegistryDb;
+    /** Lazily opens and caches the credit database. */
+    private getCreditDb;
 }
 
+/** Maximum agents a single human guarantor can back. */
+declare const MAX_AGENTS_PER_GUARANTOR = 10;
+/** Free credits granted per human guarantor registration. */
+declare const GUARANTOR_CREDIT_POOL = 50;
+/**
+ * A Human Guarantor — a real person backing one or more agents.
+ * Provides initial trust and credit pool for the agent network.
+ */
+declare const GuarantorRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    github_login: z.ZodString;
+    agent_count: z.ZodNumber;
+    credit_pool: z.ZodNumber;
+    created_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    created_at: string;
+    github_login: string;
+    agent_count: number;
+    credit_pool: number;
+}, {
+    id: string;
+    created_at: string;
+    github_login: string;
+    agent_count: number;
+    credit_pool: number;
+}>;
+type GuarantorRecord = z.infer<typeof GuarantorRecordSchema>;
+/**
+ * Registers a new human guarantor via GitHub login.
+ * Grants GUARANTOR_CREDIT_POOL (50) credits to be distributed among linked agents.
+ *
+ * @param db - The credit database instance.
+ * @param githubLogin - GitHub username of the guarantor.
+ * @returns The created GuarantorRecord.
+ * @throws {AgentBnBError} with code 'GUARANTOR_EXISTS' if login already registered.
+ */
+declare function registerGuarantor(db: Database.Database, githubLogin: string): GuarantorRecord;
+/**
+ * Links an agent to a human guarantor.
+ * Enforces the MAX_AGENTS_PER_GUARANTOR limit (10).
+ *
+ * @param db - The credit database instance.
+ * @param agentId - The agent_id to link.
+ * @param githubLogin - The guarantor's GitHub login.
+ * @returns Updated GuarantorRecord.
+ * @throws {AgentBnBError} with code 'GUARANTOR_NOT_FOUND' if login not registered.
+ * @throws {AgentBnBError} with code 'MAX_AGENTS_EXCEEDED' if limit reached.
+ * @throws {AgentBnBError} with code 'AGENT_ALREADY_LINKED' if agent already has a guarantor.
+ */
+declare function linkAgentToGuarantor(db: Database.Database, agentId: string, githubLogin: string): GuarantorRecord;
+/**
+ * Retrieves a guarantor record by GitHub login.
+ *
+ * @param db - The credit database instance.
+ * @param githubLogin - The GitHub username to look up.
+ * @returns GuarantorRecord or null if not found.
+ */
+declare function getGuarantor(db: Database.Database, githubLogin: string): GuarantorRecord | null;
+/**
+ * Gets the guarantor linked to an agent, if any.
+ *
+ * @param db - The credit database instance.
+ * @param agentId - The agent_id to look up.
+ * @returns GuarantorRecord or null if agent has no guarantor.
+ */
+declare function getAgentGuarantor(db: Database.Database, agentId: string): GuarantorRecord | null;
+/**
+ * Initiates a GitHub OAuth flow for guarantor verification.
+ * This is a STUB — returns placeholder values. Actual OAuth implementation
+ * is deferred to a future version.
+ *
+ * @returns Object with auth_url and state for the OAuth flow.
+ */
+declare function initiateGithubAuth(): {
+    auth_url: string;
+    state: string;
+};
+
+/**
+ * Registers WebSocket relay on an existing Fastify instance.
+ * Adds a `/ws` route that upgrades HTTP to WebSocket for agent relay.
+ *
+ * @param server - Fastify instance with @fastify/websocket already registered.
+ * @param db - Registry database instance (for card lookups and online status).
+ * @param creditDb - Optional credit database. When provided, credits are held
+ *   before forwarding requests, settled on success, and released on failure/timeout/disconnect.
+ *   When undefined, all credit operations are skipped (backward compat for tests).
+ * @returns RelayState for monitoring and graceful shutdown.
+ */
+declare function registerWebSocketRelay(server: FastifyInstance, db: Database.Database, creditDb?: Database.Database): RelayState;
+
 /**
  * Options for executing a capability request.
  * Used by both the HTTP /rpc handler and WebSocket relay.
@@ -3620,6 +3707,8 @@ interface ExecuteRequestOptions {
     skillExecutor?: SkillExecutor;
     handlerUrl?: string;
     timeoutMs?: number;
+    /** Optional progress callback forwarded to SkillExecutor during execution. */
+    onProgress?: ProgressCallback;
 }
 /**
  * Result of a capability execution.