agentbnb 2.2.0

package/dist/index.d.ts

@@ -0,0 +1,676 @@
+import { z } from 'zod';
+import Database from 'better-sqlite3';
+import { FastifyInstance } from 'fastify';
+
+/**
+ * Capability Card — the core unit of AgentBnB
+ *
+ * Level 1 (Atomic): Single API capability (e.g. ElevenLabs TTS)
+ * Level 2 (Pipeline): Multiple Atomics chained (e.g. text → voice → video)
+ * Level 3 (Environment): Full deployment with all dependencies
+ */
+declare const CapabilityCardSchema: z.ZodObject<{
+    spec_version: z.ZodDefault<z.ZodLiteral<"1.0">>;
+    id: z.ZodString;
+    owner: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    level: z.ZodUnion<[z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
+    inputs: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<["text", "json", "file", "audio", "image", "video", "stream"]>;
+        description: z.ZodOptional<z.ZodString>;
+        required: z.ZodDefault<z.ZodBoolean>;
+        schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        type: "text" | "json" | "file" | "audio" | "image" | "video" | "stream";
+        required: boolean;
+        description?: string | undefined;
+        schema?: Record<string, unknown> | undefined;
+    }, {
+        name: string;
+        type: "text" | "json" | "file" | "audio" | "image" | "video" | "stream";
+        description?: string | undefined;
+        required?: boolean | undefined;
+        schema?: Record<string, unknown> | undefined;
+    }>, "many">;
+    outputs: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<["text", "json", "file", "audio", "image", "video", "stream"]>;
+        description: z.ZodOptional<z.ZodString>;
+        required: z.ZodDefault<z.ZodBoolean>;
+        schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        type: "text" | "json" | "file" | "audio" | "image" | "video" | "stream";
+        required: boolean;
+        description?: string | undefined;
+        schema?: Record<string, unknown> | undefined;
+    }, {
+        name: string;
+        type: "text" | "json" | "file" | "audio" | "image" | "video" | "stream";
+        description?: string | undefined;
+        required?: boolean | undefined;
+        schema?: Record<string, unknown> | undefined;
+    }>, "many">;
+    pricing: z.ZodObject<{
+        credits_per_call: z.ZodNumber;
+        credits_per_minute: z.ZodOptional<z.ZodNumber>;
+        /** Number of free monthly calls. Shown as a "N free/mo" badge in the Hub. */
+        free_tier: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    }, {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    }>;
+    availability: z.ZodObject<{
+        online: z.ZodBoolean;
+        schedule: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        online: boolean;
+        schedule?: string | undefined;
+    }, {
+        online: boolean;
+        schedule?: string | undefined;
+    }>;
+    powered_by: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodOptional<z.ZodString>;
+        tier: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        provider: string;
+        model?: string | undefined;
+        tier?: string | undefined;
+    }, {
+        provider: string;
+        model?: string | undefined;
+        tier?: string | undefined;
+    }>, "many">>;
+    /**
+     * Private per-card metadata. Stripped from all API and CLI responses —
+     * never transmitted beyond the local store.
+     */
+    _internal: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        apis_used: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        avg_latency_ms: z.ZodOptional<z.ZodNumber>;
+        success_rate: z.ZodOptional<z.ZodNumber>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        apis_used?: string[] | undefined;
+        avg_latency_ms?: number | undefined;
+        success_rate?: number | undefined;
+        tags?: string[] | undefined;
+    }, {
+        apis_used?: string[] | undefined;
+        avg_latency_ms?: number | undefined;
+        success_rate?: number | undefined;
+        tags?: string[] | undefined;
+    }>>;
+    created_at: z.ZodOptional<z.ZodString>;
+    updated_at: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    spec_version: "1.0";
+    id: string;
+    owner: string;
+    level: 1 | 2 | 3;
+    inputs: {
+        name: string;
+        type: "text" | "json" | "file" | "audio" | "image" | "video" | "stream";
+        required: boolean;
+        description?: string | undefined;
+        schema?: Record<string, unknown> | undefined;
+    }[];
+    outputs: {
+        name: string;
+        type: "text" | "json" | "file" | "audio" | "image" | "video" | "stream";
+        required: boolean;
+        description?: string | undefined;
+        schema?: Record<string, unknown> | undefined;
+    }[];
+    pricing: {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    };
+    availability: {
+        online: boolean;
+        schedule?: string | undefined;
+    };
+    powered_by?: {
+        provider: string;
+        model?: string | undefined;
+        tier?: string | undefined;
+    }[] | undefined;
+    _internal?: Record<string, unknown> | undefined;
+    metadata?: {
+        apis_used?: string[] | undefined;
+        avg_latency_ms?: number | undefined;
+        success_rate?: number | undefined;
+        tags?: string[] | undefined;
+    } | undefined;
+    created_at?: string | undefined;
+    updated_at?: string | undefined;
+}, {
+    name: string;
+    description: string;
+    id: string;
+    owner: string;
+    level: 1 | 2 | 3;
+    inputs: {
+        name: string;
+        type: "text" | "json" | "file" | "audio" | "image" | "video" | "stream";
+        description?: string | undefined;
+        required?: boolean | undefined;
+        schema?: Record<string, unknown> | undefined;
+    }[];
+    outputs: {
+        name: string;
+        type: "text" | "json" | "file" | "audio" | "image" | "video" | "stream";
+        description?: string | undefined;
+        required?: boolean | undefined;
+        schema?: Record<string, unknown> | undefined;
+    }[];
+    pricing: {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    };
+    availability: {
+        online: boolean;
+        schedule?: string | undefined;
+    };
+    spec_version?: "1.0" | undefined;
+    powered_by?: {
+        provider: string;
+        model?: string | undefined;
+        tier?: string | undefined;
+    }[] | undefined;
+    _internal?: Record<string, unknown> | undefined;
+    metadata?: {
+        apis_used?: string[] | undefined;
+        avg_latency_ms?: number | undefined;
+        success_rate?: number | undefined;
+        tags?: string[] | undefined;
+    } | undefined;
+    created_at?: string | undefined;
+    updated_at?: string | undefined;
+}>;
+type CapabilityCard = z.infer<typeof CapabilityCardSchema>;
+
+/**
+ * Opens a SQLite database at the given path (or in-memory if ':memory:').
+ * Applies WAL mode, enables foreign keys, creates base tables and FTS virtual table,
+ * calls createRequestLogTable, then runs schema migrations (which installs v2.0 triggers).
+ *
+ * @param path - File path or ':memory:' for in-memory. Defaults to ':memory:'.
+ * @returns Opened Database instance.
+ */
+declare function openDatabase(path?: string): Database.Database;
+/**
+ * Inserts a CapabilityCard into the registry.
+ * Validates the card via Zod schema before inserting.
+ * Auto-sets created_at and updated_at to current ISO timestamp.
+ *
+ * @param db - Open database instance.
+ * @param card - Card to insert.
+ * @throws {AgentBnBError} with code VALIDATION_ERROR if card fails schema validation.
+ */
+declare function insertCard(db: Database.Database, card: CapabilityCard): void;
+/**
+ * Retrieves a CapabilityCard by its ID.
+ *
+ * @param db - Open database instance.
+ * @param id - UUID of the card to retrieve.
+ * @returns The CapabilityCard if found, or null if not found.
+ */
+declare function getCard(db: Database.Database, id: string): CapabilityCard | null;
+
+/**
+ * Filters for capability card search.
+ */
+interface SearchFilters {
+    /** Filter to a specific capability level: 1 (Atomic), 2 (Pipeline), 3 (Environment). */
+    level?: 1 | 2 | 3;
+    /** Filter by online availability. */
+    online?: boolean;
+    /** Filter cards that use all of the specified APIs. */
+    apis_used?: string[];
+}
+/**
+ * Searches CapabilityCards using FTS5 full-text search with optional filters.
+ * Results are ranked by BM25 relevance score (most relevant first).
+ * Returns up to 50 results.
+ *
+ * @param db - Open database instance.
+ * @param query - Full-text search query string.
+ * @param filters - Optional filters for level, online status, and apis_used.
+ * @returns Array of matching CapabilityCard objects sorted by relevance.
+ */
+declare function searchCards(db: Database.Database, query: string, filters?: SearchFilters): CapabilityCard[];
+
+/**
+ * Opens a SQLite database for the credit system.
+ * Uses WAL mode for better read concurrency.
+ *
+ * @param path - Path to the database file. Defaults to ':memory:' for in-memory.
+ * @returns Configured Database instance with all credit tables created.
+ */
+declare function openCreditDb(path?: string): Database.Database;
+/**
+ * Returns the current credit balance for an agent.
+ * Returns 0 if the agent has never been bootstrapped.
+ *
+ * @param db - The credit database instance.
+ * @param owner - Agent identifier.
+ * @returns Current balance in credits.
+ */
+declare function getBalance(db: Database.Database, owner: string): number;
+
+/**
+ * Discriminated union over all four skill configuration types.
+ * Used by SkillExecutor to dispatch to the correct executor mode.
+ */
+declare const SkillConfigSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"api">;
+    name: z.ZodString;
+    endpoint: z.ZodString;
+    method: z.ZodEnum<["GET", "POST", "PUT", "DELETE"]>;
+    auth: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"bearer">;
+        token: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "bearer";
+        token: string;
+    }, {
+        type: "bearer";
+        token: string;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"apikey">;
+        header: z.ZodDefault<z.ZodString>;
+        key: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "apikey";
+        header: string;
+        key: string;
+    }, {
+        type: "apikey";
+        key: string;
+        header?: string | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"basic">;
+        username: z.ZodString;
+        password: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "basic";
+        username: string;
+        password: string;
+    }, {
+        type: "basic";
+        username: string;
+        password: string;
+    }>]>>;
+    input_mapping: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    output_mapping: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    pricing: z.ZodObject<{
+        credits_per_call: z.ZodNumber;
+        credits_per_minute: z.ZodOptional<z.ZodNumber>;
+        free_tier: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    }, {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    }>;
+    timeout_ms: z.ZodDefault<z.ZodNumber>;
+    retries: z.ZodDefault<z.ZodNumber>;
+    provider: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "api";
+    id: string;
+    pricing: {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    };
+    endpoint: string;
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    input_mapping: Record<string, string>;
+    output_mapping: Record<string, string>;
+    timeout_ms: number;
+    retries: number;
+    provider?: string | undefined;
+    auth?: {
+        type: "bearer";
+        token: string;
+    } | {
+        type: "apikey";
+        header: string;
+        key: string;
+    } | {
+        type: "basic";
+        username: string;
+        password: string;
+    } | undefined;
+}, {
+    name: string;
+    type: "api";
+    id: string;
+    pricing: {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    };
+    endpoint: string;
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    provider?: string | undefined;
+    auth?: {
+        type: "bearer";
+        token: string;
+    } | {
+        type: "apikey";
+        key: string;
+        header?: string | undefined;
+    } | {
+        type: "basic";
+        username: string;
+        password: string;
+    } | undefined;
+    input_mapping?: Record<string, string> | undefined;
+    output_mapping?: Record<string, string> | undefined;
+    timeout_ms?: number | undefined;
+    retries?: number | undefined;
+}>, z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"pipeline">;
+    name: z.ZodString;
+    steps: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        skill_id: z.ZodString;
+        input_mapping: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        input_mapping: Record<string, string>;
+        skill_id: string;
+    }, {
+        skill_id: string;
+        input_mapping?: Record<string, string> | undefined;
+    }>, z.ZodObject<{
+        command: z.ZodString;
+        input_mapping: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        input_mapping: Record<string, string>;
+        command: string;
+    }, {
+        command: string;
+        input_mapping?: Record<string, string> | undefined;
+    }>]>, "many">;
+    pricing: z.ZodObject<{
+        credits_per_call: z.ZodNumber;
+        credits_per_minute: z.ZodOptional<z.ZodNumber>;
+        free_tier: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    }, {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    }>;
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "pipeline";
+    id: string;
+    pricing: {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    };
+    steps: ({
+        input_mapping: Record<string, string>;
+        skill_id: string;
+    } | {
+        input_mapping: Record<string, string>;
+        command: string;
+    })[];
+    timeout_ms?: number | undefined;
+}, {
+    name: string;
+    type: "pipeline";
+    id: string;
+    pricing: {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    };
+    steps: ({
+        skill_id: string;
+        input_mapping?: Record<string, string> | undefined;
+    } | {
+        command: string;
+        input_mapping?: Record<string, string> | undefined;
+    })[];
+    timeout_ms?: number | undefined;
+}>, z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"openclaw">;
+    name: z.ZodString;
+    agent_name: z.ZodString;
+    channel: z.ZodEnum<["telegram", "webhook", "process"]>;
+    pricing: z.ZodObject<{
+        credits_per_call: z.ZodNumber;
+        credits_per_minute: z.ZodOptional<z.ZodNumber>;
+        free_tier: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    }, {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    }>;
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "openclaw";
+    id: string;
+    pricing: {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    };
+    agent_name: string;
+    channel: "telegram" | "webhook" | "process";
+    timeout_ms?: number | undefined;
+}, {
+    name: string;
+    type: "openclaw";
+    id: string;
+    pricing: {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    };
+    agent_name: string;
+    channel: "telegram" | "webhook" | "process";
+    timeout_ms?: number | undefined;
+}>, z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"command">;
+    name: z.ZodString;
+    command: z.ZodString;
+    output_type: z.ZodEnum<["json", "text", "file"]>;
+    allowed_commands: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    working_dir: z.ZodOptional<z.ZodString>;
+    timeout_ms: z.ZodDefault<z.ZodNumber>;
+    pricing: z.ZodObject<{
+        credits_per_call: z.ZodNumber;
+        credits_per_minute: z.ZodOptional<z.ZodNumber>;
+        free_tier: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    }, {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "command";
+    id: string;
+    pricing: {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    };
+    timeout_ms: number;
+    command: string;
+    output_type: "text" | "json" | "file";
+    allowed_commands?: string[] | undefined;
+    working_dir?: string | undefined;
+}, {
+    name: string;
+    type: "command";
+    id: string;
+    pricing: {
+        credits_per_call: number;
+        credits_per_minute?: number | undefined;
+        free_tier?: number | undefined;
+    };
+    command: string;
+    output_type: "text" | "json" | "file";
+    timeout_ms?: number | undefined;
+    allowed_commands?: string[] | undefined;
+    working_dir?: string | undefined;
+}>]>;
+/** TypeScript type for any skill config entry */
+type SkillConfig = z.infer<typeof SkillConfigSchema>;
+
+/**
+ * Result returned by SkillExecutor.execute() for every invocation.
+ * Always includes timing data regardless of success or failure.
+ */
+interface ExecutionResult {
+    /** Whether the skill executed successfully. */
+    success: boolean;
+    /** The output produced by the skill on success. */
+    result?: unknown;
+    /** Error message if success is false. */
+    error?: string;
+    /** Wall-clock execution time in milliseconds. */
+    latency_ms: number;
+}
+/**
+ * Interface that all executor mode implementations must satisfy.
+ * Each mode handles one skill type: 'api' | 'pipeline' | 'openclaw' | 'command'.
+ */
+interface ExecutorMode {
+    /**
+     * Execute a skill with the given config and input parameters.
+     *
+     * @param config - The validated SkillConfig for this skill.
+     * @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'>>;
+}
+/**
+ * Central dispatcher that routes skill execution requests to the appropriate
+ * executor mode based on the skill's `type` field.
+ *
+ * Usage:
+ * ```ts
+ * const executor = createSkillExecutor(configs, modes);
+ * const result = await executor.execute('tts-skill', { text: 'hello' });
+ * ```
+ */
+declare class SkillExecutor {
+    private readonly skillMap;
+    private readonly modeMap;
+    /**
+     * @param configs - Parsed SkillConfig array (from parseSkillsFile).
+     * @param modes - Map from skill type string to its executor implementation.
+     */
+    constructor(configs: SkillConfig[], modes: Map<string, ExecutorMode>);
+    /**
+     * Execute a skill by ID with the given input parameters.
+     *
+     * Dispatch order:
+     * 1. Look up skill config by skillId.
+     * 2. Find executor mode by config.type.
+     * 3. Invoke mode.execute(), wrap with latency timing.
+     * 4. Catch any thrown errors and return as ExecutionResult with success:false.
+     *
+     * @param skillId - The ID of the skill to execute.
+     * @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>;
+    /**
+     * Returns the IDs of all registered skills.
+     *
+     * @returns Array of skill ID strings.
+     */
+    listSkills(): string[];
+    /**
+     * Returns the SkillConfig for a given skill ID, or undefined if not found.
+     *
+     * @param skillId - The skill ID to look up.
+     * @returns The SkillConfig or undefined.
+     */
+    getSkillConfig(skillId: string): SkillConfig | undefined;
+}
+
+/**
+ * Options for creating a gateway server.
+ */
+interface GatewayOptions {
+    /** Port to listen on. Default 7700. */
+    port?: number;
+    /** Open registry database instance. */
+    registryDb: Database.Database;
+    /** Open credit database instance. */
+    creditDb: Database.Database;
+    /** Valid bearer tokens for auth. */
+    tokens: string[];
+    /** URL of the local capability handler. */
+    handlerUrl: string;
+    /** Request timeout in ms. Default 30000. */
+    timeoutMs?: number;
+    /** Disable logging (useful for tests). */
+    silent?: boolean;
+    /**
+     * Optional SkillExecutor instance.
+     * When provided, skill execution is dispatched through SkillExecutor.execute()
+     * instead of forwarding via fetch(handlerUrl).
+     * When absent, the original handlerUrl fetch path is used (backward compat).
+     */
+    skillExecutor?: SkillExecutor;
+}
+/**
+ * Creates a Fastify gateway server for agent-to-agent communication.
+ * Registers /health (unauthenticated) and /rpc (token-authenticated) endpoints.
+ * Returns a configured Fastify instance (call .ready() before using inject,
+ * or .listen() to start accepting connections).
+ *
+ * @param opts - Gateway configuration options.
+ * @returns Configured Fastify instance (not yet listening).
+ */
+declare function createGatewayServer(opts: GatewayOptions): FastifyInstance;
+
+export { type CapabilityCard, CapabilityCardSchema, createGatewayServer, getBalance, getCard, insertCard, openCreditDb, openDatabase, searchCards };