agentbnb 3.0.0 → 3.1.1

package/dist/index.d.ts

@@ -686,8 +686,8 @@ declare const ApiSkillConfigSchema: z.ZodObject<{
         key: z.ZodString;
     }, "strip", z.ZodTypeAny, {
         type: "apikey";
-        key: string;
         header: string;
+        key: string;
     }, {
         type: "apikey";
         key: string;
@@ -744,8 +744,8 @@ declare const ApiSkillConfigSchema: z.ZodObject<{
         token: string;
     } | {
         type: "apikey";
-        key: string;
         header: string;
+        key: string;
     } | {
         type: "basic";
         username: string;
@@ -1031,8 +1031,8 @@ declare const SkillConfigSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         key: z.ZodString;
     }, "strip", z.ZodTypeAny, {
         type: "apikey";
-        key: string;
         header: string;
+        key: string;
     }, {
         type: "apikey";
         key: string;
@@ -1089,8 +1089,8 @@ declare const SkillConfigSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         token: string;
     } | {
         type: "apikey";
-        key: string;
         header: string;
+        key: string;
     } | {
         type: "basic";
         username: string;
@@ -1357,8 +1357,8 @@ declare const SkillsFileSchema: z.ZodObject<{
             key: z.ZodString;
         }, "strip", z.ZodTypeAny, {
             type: "apikey";
-            key: string;
             header: string;
+            key: string;
         }, {
             type: "apikey";
             key: string;
@@ -1415,8 +1415,8 @@ declare const SkillsFileSchema: z.ZodObject<{
             token: string;
         } | {
             type: "apikey";
-            key: string;
             header: string;
+            key: string;
         } | {
             type: "basic";
             username: string;
@@ -1679,8 +1679,8 @@ declare const SkillsFileSchema: z.ZodObject<{
             token: string;
         } | {
             type: "apikey";
-            key: string;
             header: string;
+            key: string;
         } | {
             type: "basic";
             username: string;
@@ -2645,20 +2645,20 @@ declare const EscrowReceiptSchema: z.ZodObject<{
     nonce: z.ZodString;
     signature: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    card_id: string;
     signature: string;
     requester_owner: string;
     requester_public_key: string;
     amount: number;
+    card_id: string;
     timestamp: string;
     nonce: string;
     skill_id?: string | undefined;
 }, {
-    card_id: string;
     signature: string;
     requester_owner: string;
     requester_public_key: string;
     amount: number;
+    card_id: string;
     timestamp: string;
     nonce: string;
     skill_id?: string | undefined;
@@ -2727,4 +2727,1046 @@ declare function settleRequesterEscrow(requesterDb: Database.Database, escrowId:
  */
 declare function releaseRequesterEscrow(requesterDb: Database.Database, escrowId: string): void;
 
-export { ApiExecutor, type ApiSkillConfig, ApiSkillConfigSchema, BudgetController, CONDUCTOR_OWNER, type CapabilityCard, CapabilityCardSchema, CommandExecutor, type CommandSkillConfig, CommandSkillConfigSchema, ConductorMode, type ConductorModeOptions, type ConductorSkillConfig, ConductorSkillConfigSchema, type CreateReceiptOpts, type EscrowReceipt, EscrowReceiptSchema, type ExecutionBudget, type ExecutionResult, type ExecutorMode, type KeyPair, type MatchOptions, type MatchResult, ORCHESTRATION_FEE, OpenClawBridge, type OpenClawSkillConfig, OpenClawSkillConfigSchema, type OrchestrateOptions, type OrchestrationResult, PipelineExecutor, type PipelineSkillConfig, PipelineSkillConfigSchema, type SkillConfig, SkillConfigSchema, SkillExecutor, SkillsFileSchema, type SubTask, TEMPLATES, applyInputMapping, buildAuthHeaders, buildConductorCard, createGatewayServer, createSignedEscrowReceipt, createSkillExecutor, decompose, expandEnvVars, extractByPath, generateKeyPair, getBalance, getCard, insertCard, interpolate, interpolateObject, loadKeyPair, matchSubTasks, openCreditDb, openDatabase, orchestrate, parseSkillsFile, registerConductorCard, releaseRequesterEscrow, resolvePath, saveKeyPair, searchCards, settleProviderEarning, settleRequesterEscrow, signEscrowReceipt, verifyEscrowReceipt };
+/**
+ * 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, {
+        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;
+}>;
+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, {
+    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;
+}, {
+    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;
+}
+
+/**
+ * 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<{
+    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>;
+}>;
+/** 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>;
+    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: "relay_request";
+    params: Record<string, unknown>;
+    id: string;
+    card_id: string;
+    target_owner: string;
+    skill_id?: string | undefined;
+    requester?: string | undefined;
+    escrow_receipt?: Record<string, unknown> | undefined;
+}, {
+    type: "relay_request";
+    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;
+}>;
+/** 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, {
+        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;
+}>;
+/** 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, {
+        code: number;
+        message: string;
+    }, {
+        code: number;
+        message: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    type: "response";
+    id: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    } | undefined;
+}, {
+    type: "response";
+    id: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    } | undefined;
+}>;
+/** 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>;
+}, "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">;
+    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>>;
+}, "strip", z.ZodTypeAny, {
+    type: "relay_request";
+    params: Record<string, unknown>;
+    id: string;
+    card_id: string;
+    target_owner: string;
+    skill_id?: string | undefined;
+    requester?: string | undefined;
+    escrow_receipt?: Record<string, unknown> | undefined;
+}, {
+    type: "relay_request";
+    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;
+    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;
+}>, 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;
+    }, "strip", z.ZodTypeAny, {
+        code: number;
+        message: string;
+    }, {
+        code: number;
+        message: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    type: "response";
+    id: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    } | undefined;
+}, {
+    type: "response";
+    id: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    } | undefined;
+}>, 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;
+}>]>;
+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;
+}
+
+/**
+ * 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.
+ */
+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;
+    };
+}
+/** 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 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;
+}
+/**
+ * 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>;
+    /** 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;
+}
+
+/**
+ * Options for executing a capability request.
+ * Used by both the HTTP /rpc handler and WebSocket relay.
+ */
+interface ExecuteRequestOptions {
+    registryDb: Database.Database;
+    creditDb: Database.Database;
+    cardId: string;
+    skillId?: string;
+    params: Record<string, unknown>;
+    requester: string;
+    escrowReceipt?: EscrowReceipt;
+    skillExecutor?: SkillExecutor;
+    handlerUrl?: string;
+    timeoutMs?: number;
+}
+/**
+ * Result of a capability execution.
+ */
+type ExecuteResult = {
+    success: true;
+    result: unknown;
+} | {
+    success: false;
+    error: {
+        code: number;
+        message: string;
+        data?: Record<string, unknown>;
+    };
+};
+/**
+ * Executes a capability request with full escrow, reputation, and logging.
+ * Shared between HTTP gateway (/rpc) and WebSocket relay paths.
+ *
+ * @param opts - Execution options including DB handles, card/skill IDs, and executor.
+ * @returns Success with result, or failure with error details.
+ */
+declare function executeCapabilityRequest(opts: ExecuteRequestOptions): Promise<ExecuteResult>;
+
+/**
+ * Options for requesting a capability via WebSocket relay.
+ */
+interface RelayRequestOptions {
+    /** Target agent owner to relay the request to. */
+    targetOwner: 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>;
+    /** Signed escrow receipt for cross-machine credit verification. */
+    escrowReceipt?: EscrowReceipt;
+    /** Timeout in milliseconds. Default 30000. */
+    timeoutMs?: number;
+}
+/**
+ * Sends a capability request to another agent via the WebSocket relay.
+ *
+ * @param relay - Connected RelayClient instance.
+ * @param opts - Relay request options.
+ * @returns The result from the capability execution.
+ * @throws {AgentBnBError} on relay error, timeout, or target agent offline.
+ */
+declare function requestViaRelay(relay: RelayClient, opts: RelayRequestOptions): Promise<unknown>;
+
+/**
+ * Capability detection patterns and templates for smart onboarding.
+ *
+ * Pure data — regex patterns to detect known APIs/tools in markdown files,
+ * and pre-built templates for the interactive fallback menu.
+ */
+/**
+ * A detected capability from doc scanning or template selection.
+ * Lightweight — converted to a full Skill via capabilitiesToV2Card().
+ */
+interface DetectedCapability {
+    /** Unique key for deduplication, e.g. 'openai', 'elevenlabs' */
+    key: string;
+    /** Human-readable name, e.g. 'OpenAI Text Generation' */
+    name: string;
+    /** Category label, e.g. 'Text Gen', 'TTS' */
+    category: string;
+    /** Default credits per call */
+    credits_per_call: number;
+    /** Metadata tags for FTS indexing */
+    tags: string[];
+}
+/**
+ * A regex pattern entry mapping a pattern to a DetectedCapability.
+ */
+interface PatternEntry {
+    /** Regex to test against document content */
+    pattern: RegExp;
+    /** The capability to return if the pattern matches */
+    capability: DetectedCapability;
+}
+/**
+ * Regex patterns for detecting known APIs and tools in markdown documentation.
+ * Each pattern maps to a DetectedCapability with sensible defaults.
+ */
+declare const API_PATTERNS: PatternEntry[];
+/**
+ * Pre-built templates for the interactive onboarding fallback menu.
+ * Shown when no capabilities are auto-detected.
+ */
+declare const INTERACTIVE_TEMPLATES: DetectedCapability[];
+
+/**
+ * Scans markdown content for known API/tool patterns and returns detected capabilities.
+ *
+ * - Tests each API_PATTERNS regex against the full content
+ * - Deduplicates by capability key (first match wins)
+ * - Returns empty array if nothing is detected
+ *
+ * @param content - Markdown file content to scan
+ * @returns Array of detected capabilities (may be empty)
+ */
+declare function detectFromDocs(content: string): DetectedCapability[];
+
+/**
+ * Result of the capability detection chain.
+ * The `source` field indicates which detection method succeeded.
+ */
+interface DetectionResult {
+    /** Which detection method produced results */
+    source: 'soul' | 'docs' | 'env' | 'none';
+    /** Detected capabilities (for 'docs' source) */
+    capabilities: DetectedCapability[];
+    /** Raw SOUL.md content (for 'soul' source — caller passes to publishFromSoulV2) */
+    soulContent?: string;
+    /** Detected env var names (for 'env' source — caller passes to buildDraftCard) */
+    envKeys?: string[];
+    /** Which file was used for detection */
+    sourceFile?: string;
+}
+/**
+ * Options for the detection chain.
+ */
+interface DetectOptions {
+    /** Explicit file to parse (--from flag) */
+    fromFile?: string;
+    /** Working directory to search for doc files (default: process.cwd()) */
+    cwd?: string;
+}
+/**
+ * Runs the capability detection priority chain.
+ *
+ * Checks sources in order and stops at the first one that produces results:
+ * 1. --from <file> → detectFromDocs()
+ * 2. SOUL.md → returns raw content for publishFromSoulV2()
+ * 3. CLAUDE.md / AGENTS.md / README.md → detectFromDocs()
+ * 4. Environment variables → detectApiKeys()
+ * 5. Returns { source: 'none' } if nothing found
+ *
+ * @param opts - Detection options (fromFile, cwd)
+ * @returns Detection result with source indicator and data
+ */
+declare function detectCapabilities(opts?: DetectOptions): DetectionResult;
+/**
+ * Converts detected capabilities into a v2.0 CapabilityCard with skills.
+ *
+ * Each DetectedCapability becomes a Skill on the card. The card is validated
+ * via CapabilityCardV2Schema before returning.
+ *
+ * @param capabilities - Detected capabilities to convert
+ * @param owner - Agent owner name
+ * @param agentName - Optional agent display name (defaults to owner)
+ * @returns A valid v2.0 CapabilityCard
+ */
+declare function capabilitiesToV2Card(capabilities: DetectedCapability[], owner: string, agentName?: string): CapabilityCardV2;
+
+export { API_PATTERNS, AgentBnBConsumer, AgentBnBProvider, type AgentCertificate, AgentCertificateSchema, type AgentIdentity, AgentIdentitySchema, ApiExecutor, type ApiSkillConfig, ApiSkillConfigSchema, BudgetController, CONDUCTOR_OWNER, type CapabilityCard, CapabilityCardSchema, CommandExecutor, type CommandSkillConfig, CommandSkillConfigSchema, ConductorMode, type ConductorModeOptions, type ConductorSkillConfig, ConductorSkillConfigSchema, type ConsumerOptions, type ConsumerRequestOptions, type CreateReceiptOpts, type DetectOptions, type DetectedCapability, type DetectionResult, type ErrorMessage, type EscrowReceipt, EscrowReceiptSchema, type ExecuteRequestOptions, type ExecuteResult, type ExecutionBudget, type ExecutionResult, type ExecutorMode, GUARANTOR_CREDIT_POOL, type GuarantorRecord, GuarantorRecordSchema, INTERACTIVE_TEMPLATES, type IncomingRequestMessage, type KeyPair, MAX_AGENTS_PER_GUARANTOR, type MatchOptions, type MatchResult, ORCHESTRATION_FEE, OpenClawBridge, type OpenClawSkillConfig, OpenClawSkillConfigSchema, type OrchestrateOptions, type OrchestrationResult, PipelineExecutor, type PipelineSkillConfig, PipelineSkillConfigSchema, type ProviderOptions, type RegisterMessage, type RegisteredMessage, RelayClient, type RelayClientOptions, type RelayHandlerResult, type RelayMessage, RelayMessageSchema, type RelayRequestMessage, type RelayRequestOptions, type RelayResponseMessage, type RelayState, type ResponseMessage, type SharingContext, type SkillConfig, SkillConfigSchema, SkillExecutor, SkillsFileSchema, type StartSharingOptions, type SubTask, TEMPLATES, applyInputMapping, buildAuthHeaders, buildConductorCard, capabilitiesToV2Card, createGatewayServer, createIdentity, createSignedEscrowReceipt, createSkillExecutor, decompose, deriveAgentId, detectCapabilities, detectFromDocs, ensureIdentity, executeCapabilityRequest, expandEnvVars, extractByPath, generateKeyPair, getAgentGuarantor, getBalance, getCard, getGuarantor, initiateGithubAuth, insertCard, interpolate, interpolateObject, issueAgentCertificate, linkAgentToGuarantor, loadIdentity, loadKeyPair, matchSubTasks, openCreditDb, openDatabase, orchestrate, parseSkillsFile, registerConductorCard, registerGuarantor, registerWebSocketRelay, releaseRequesterEscrow, requestViaRelay, resolvePath, saveIdentity, saveKeyPair, searchCards, settleProviderEarning, settleRequesterEscrow, signEscrowReceipt, verifyAgentCertificate, verifyEscrowReceipt };