@tangle-network/agent-gateway 0.6.0 → 0.7.1

package/dist/types-DEsMmS-X.d.ts

@@ -0,0 +1,875 @@
+import { NonceStore } from './nonce-store.js';
+import { RateLimitStore } from './rate-limit.js';
+
+/**
+ * A2A protocol types (Google Agent-to-Agent, April 2025).
+ *
+ * Subset shipped by this gateway:
+ *   - Discovery: AgentCard via `.well-known/agent.json`
+ *   - Messaging: `message/send`, `message/stream`
+ *   - Task control: `tasks/get`, `tasks/cancel`, `tasks/resubscribe`
+ *   - Push: `tasks/pushNotificationConfig/{set,get,list,delete}` (gated on `pushStore`)
+ *   - Multi-turn: `input-required` state + follow-up `message/send` with the same `taskId`
+ *   - Capabilities: streaming = true; pushNotifications gated on config; stateTransitionHistory = false
+ *   - Parts: text only on input/output (data/file parts rejected with CONTENT_TYPE_NOT_SUPPORTED)
+ *
+ * Deferred until a real consumer needs them: authenticated extended card,
+ * data/file parts, OAuth2/mTLS auth schemes.
+ */
+interface JSONRPCRequest {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    method: string;
+    params?: unknown;
+}
+interface JSONRPCSuccessResponse<T = unknown> {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result: T;
+}
+interface JSONRPCErrorResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+type JSONRPCResponse<T = unknown> = JSONRPCSuccessResponse<T> | JSONRPCErrorResponse;
+/** Standard JSON-RPC + A2A-specific codes. Negative ints per JSON-RPC spec. */
+declare const A2A_ERROR_CODES: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    readonly TASK_NOT_FOUND: -32001;
+    readonly TASK_NOT_CANCELABLE: -32002;
+    readonly PUSH_NOT_SUPPORTED: -32003;
+    readonly UNSUPPORTED_OPERATION: -32004;
+    readonly CONTENT_TYPE_NOT_SUPPORTED: -32005;
+    readonly INVALID_AGENT_RESPONSE: -32006;
+    readonly AUTHENTICATED_EXTENDED_CARD_NOT_CONFIGURED: -32007;
+};
+interface TextPart {
+    kind: 'text';
+    text: string;
+    metadata?: Record<string, unknown>;
+}
+interface DataPart {
+    kind: 'data';
+    data: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+interface FilePart {
+    kind: 'file';
+    file: {
+        name?: string;
+        mimeType?: string;
+        bytes?: string;
+        uri?: string;
+    };
+    metadata?: Record<string, unknown>;
+}
+type Part = TextPart | DataPart | FilePart;
+interface Message {
+    kind: 'message';
+    role: 'user' | 'agent';
+    parts: Part[];
+    messageId: string;
+    taskId?: string;
+    contextId?: string;
+    metadata?: Record<string, unknown>;
+}
+type TaskState = 'submitted' | 'working' | 'input-required' | 'completed' | 'canceled' | 'failed' | 'rejected' | 'auth-required';
+interface TaskStatus {
+    state: TaskState;
+    message?: Message;
+    timestamp: string;
+}
+interface Artifact {
+    artifactId: string;
+    name?: string;
+    description?: string;
+    parts: Part[];
+    metadata?: Record<string, unknown>;
+}
+interface Task {
+    kind: 'task';
+    id: string;
+    contextId: string;
+    status: TaskStatus;
+    history?: Message[];
+    artifacts?: Artifact[];
+    metadata?: Record<string, unknown>;
+}
+interface TaskStatusUpdateEvent {
+    kind: 'status-update';
+    taskId: string;
+    contextId: string;
+    status: TaskStatus;
+    /** True on the terminal event; clients close the stream after this. */
+    final: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface TaskArtifactUpdateEvent {
+    kind: 'artifact-update';
+    taskId: string;
+    contextId: string;
+    artifact: Artifact;
+    /** True when this artifact's parts should be appended to the prior emit (incremental streaming). */
+    append?: boolean;
+    /** True on the artifact's final chunk. */
+    lastChunk?: boolean;
+    metadata?: Record<string, unknown>;
+}
+type StreamingEvent = TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
+interface MessageSendParams {
+    message: Message;
+    configuration?: {
+        acceptedOutputModes?: string[];
+        blocking?: boolean;
+        historyLength?: number;
+    };
+}
+interface TaskIdParams {
+    id: string;
+    metadata?: Record<string, unknown>;
+}
+interface TaskPushNotificationConfigGetParams {
+    /** Task id whose configs are being queried. */
+    id: string;
+    /** Specific config id to fetch. Required for `set` and `delete`; omitted for `list`. */
+    pushNotificationConfigId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface AgentSkill {
+    id: string;
+    name: string;
+    description: string;
+    tags?: string[];
+    examples?: string[];
+    inputModes?: string[];
+    outputModes?: string[];
+}
+interface AgentCapabilities {
+    streaming?: boolean;
+    pushNotifications?: boolean;
+    stateTransitionHistory?: boolean;
+}
+interface AgentProvider {
+    organization: string;
+    url?: string;
+}
+interface AgentCardAuthentication {
+    /** Auth scheme names the agent accepts (e.g. 'Bearer', 'x402', 'mpp'). */
+    schemes: string[];
+    /** Optional human-readable hint about obtaining credentials. */
+    credentials?: string;
+}
+interface AgentCard {
+    name: string;
+    description: string;
+    /** JSON-RPC endpoint URL — clients POST methods here. */
+    url: string;
+    version: string;
+    documentationUrl?: string;
+    provider?: AgentProvider;
+    capabilities: AgentCapabilities;
+    authentication: AgentCardAuthentication;
+    defaultInputModes: string[];
+    defaultOutputModes: string[];
+    skills: AgentSkill[];
+}
+
+/**
+ * Task persistence behind the JSON-RPC dispatcher. Default adapter is in
+ * memory with a 1-hour TTL — adequate for tests, scratch, and Workers with
+ * a short-lived process. Production deployments wire their own
+ * `TaskStore` (D1, postgres, Durable Object) via `GatewayConfig.a2a`.
+ */
+
+interface TaskStore {
+    get(id: string): Promise<Task | undefined>;
+    put(task: Task): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+declare class InMemoryTaskStore implements TaskStore {
+    private readonly ttlMs;
+    private readonly entries;
+    constructor(ttlMs?: number);
+    get(id: string): Promise<Task | undefined>;
+    put(task: Task): Promise<void>;
+    delete(id: string): Promise<void>;
+    /**
+     * Sweep expired tasks. Called inline on every read/write — cheap for the
+     * Map sizes this is designed for (10s–1000s of concurrent tasks).
+     */
+    private gc;
+}
+
+/**
+ * @stable
+ *
+ * Durable `TaskStore` against any SQL store. Adapter-agnostic: callers wire a
+ * `SqlAdapter` against their driver (D1, postgres, sqlite, libSQL, Turso) and
+ * the same store survives gateway restarts so an in-flight task (and its
+ * artifacts) is recoverable after a Worker recycle.
+ *
+ * Schema is one table: tasks keyed by id with the full JSON payload, plus a
+ * secondary index on `context_id` so `tasks/resubscribe` and conversational
+ * lookups by context are O(log n). TTL is enforced at read time the same way
+ * `InMemoryTaskStore` does — the gateway is single-writer per task id so a
+ * stale row is invisible to callers regardless of when the row is physically
+ * deleted.
+ *
+ * Why not bake in a specific driver? Hono workers run on Cloudflare (D1),
+ * Node (pg / sqlite), Bun, Deno. Burning a hard dependency on one client
+ * limits the gateway's reach. The adapter indirection costs ~5 lines per
+ * driver in the consumer's code and keeps the package free of native deps.
+ *
+ * @example D1
+ *   import { SqlTaskStore, d1ToSqlAdapter } from '@tangle-network/agent-gateway'
+ *   const store = new SqlTaskStore(d1ToSqlAdapter(env.DB))
+ *   await store.migrate()
+ *   const gw = createAgentGateway({ ..., a2a: { taskStore: store } })
+ *
+ * @example libSQL / Turso
+ *   import { createClient } from '@libsql/client'
+ *   const client = createClient({ url: process.env.TURSO_URL!, authToken: process.env.TURSO_TOKEN! })
+ *   const libsql: SqlAdapter = {
+ *     exec: async (sql, params = []) => {
+ *       const r = await client.execute({ sql, args: params as never[] })
+ *       return { rowsAffected: Number(r.rowsAffected ?? 0) }
+ *     },
+ *     query: async (sql, params = []) => {
+ *       const r = await client.execute({ sql, args: params as never[] })
+ *       return r.rows as unknown as Record<string, unknown>[]
+ *     },
+ *   }
+ *   const store = new SqlTaskStore(libsql)
+ *   await store.migrate()
+ */
+
+/**
+ * Minimal SQL driver shape — identical to agent-runtime's `SqlAdapter` so the
+ * same wrapper code works for both packages. Parameter placeholders MUST be
+ * `?` (positional); driver wrappers that use `$1`, `$2`, … should rewrite at
+ * the adapter boundary (see node-postgres example in the durability docs).
+ */
+interface SqlAdapter {
+    exec(sql: string, params?: readonly unknown[]): Promise<{
+        rowsAffected: number;
+    }>;
+    query<TRow = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<TRow[]>;
+}
+/**
+ * Adapt a Cloudflare D1 binding to `SqlAdapter`. The package never imports
+ * `@cloudflare/workers-types`; the binding's structural shape lines up via
+ * TypeScript structural compatibility.
+ */
+declare function d1ToSqlAdapter(db: D1DatabaseLike): SqlAdapter;
+interface D1DatabaseLike {
+    prepare(sql: string): D1StmtLike;
+}
+interface D1StmtLike {
+    bind(...params: unknown[]): D1StmtLike;
+    run(): Promise<unknown>;
+    all<TRow = unknown>(): Promise<{
+        results?: TRow[];
+    }>;
+}
+/**
+ * SQL-backed TaskStore. Stores the full Task JSON; reads return a deep clone
+ * so callers never observe shared references. TTL is enforced at read time:
+ * expired rows are filtered out and (best-effort) deleted, matching the
+ * in-memory store's semantics so behavior is portable across both adapters.
+ */
+declare class SqlTaskStore implements TaskStore {
+    private readonly db;
+    private readonly opts;
+    constructor(db: SqlAdapter, opts?: {
+        ttlMs?: number;
+        table?: string;
+    });
+    private get ttlMs();
+    private get table();
+    /** Idempotent. Call once at deploy. */
+    migrate(): Promise<void>;
+    get(id: string): Promise<Task | undefined>;
+    put(task: Task): Promise<void>;
+    delete(id: string): Promise<void>;
+    /**
+     * Lookup tasks by contextId — used by `tasks/resubscribe` and the multi-turn
+     * dispatcher. Returns most-recent-first. Not part of the base TaskStore
+     * interface since the in-memory store doesn't expose it; consumers that
+     * specifically wire SqlTaskStore can use it for richer queries.
+     */
+    listByContext(contextId: string): Promise<Task[]>;
+}
+
+/**
+ * @stable
+ *
+ * A2A push notifications — a webhook delivery channel that fires when a task
+ * reaches a terminal state (`completed`, `canceled`, `failed`, `rejected`).
+ * The protocol specifies four JSON-RPC methods (`tasks/pushNotificationConfig/`
+ * {set, get, list, delete}) for registering / inspecting / removing configs,
+ * plus the delivery contract: an HTTP POST to the registered URL with the
+ * task envelope as the body and an HMAC-SHA256 signature for verification.
+ *
+ * This is the minimum shape long-horizon agents need. A consumer that finishes
+ * a task in 30 minutes can't keep an SSE stream open against a Worker (CPU
+ * limits) or an unauthenticated browser tab (network drops) — they need a
+ * fire-and-forget endpoint the gateway calls when the task is done.
+ *
+ * Out of scope for the first pass: retries, queue durability, partial-state
+ * notifications. If the webhook returns non-2xx or the request fails, the
+ * gateway logs and moves on — the consumer's endpoint should idempotently
+ * pull state via `tasks/get` rather than rely on at-least-once delivery.
+ *
+ * @example registering a webhook
+ *   {
+ *     "jsonrpc": "2.0", "id": 1, "method": "tasks/pushNotificationConfig/set",
+ *     "params": {
+ *       "taskId": "task_abc",
+ *       "pushNotificationConfig": {
+ *         "id": "cfg_1",
+ *         "url": "https://my-consumer.example.com/agent/done",
+ *         "token": "my-shared-secret-not-the-hmac-secret"
+ *       }
+ *     }
+ *   }
+ *
+ * @example webhook delivery
+ *   POST https://my-consumer.example.com/agent/done
+ *   X-A2A-Notification-Token: my-shared-secret-not-the-hmac-secret
+ *   X-A2A-Signature: sha256=<hex(HMAC-SHA256(webhookSecret, body))>
+ *   Content-Type: application/json
+ *   { "taskId": "task_abc", "state": "completed", "task": { ...full Task... } }
+ */
+
+/**
+ * Authentication metadata for the webhook itself. The A2A spec leaves this
+ * to consumers — the most common shape is a bearer token the gateway sends as
+ * `Authorization: <scheme> <credential>`. We pass it through verbatim.
+ */
+interface PushNotificationAuthentication {
+    schemes: string[];
+    credentials?: string;
+}
+/**
+ * Per-task push notification configuration. A task can have multiple configs
+ * (e.g. one for the consumer's own webhook + one for an audit log endpoint).
+ */
+interface PushNotificationConfig {
+    /** Stable id within the task's config set. Required for get/delete addressing. */
+    id: string;
+    /** HTTPS URL the gateway will POST to. */
+    url: string;
+    /**
+     * Opaque token the gateway sends back as `X-A2A-Notification-Token` so the
+     * webhook can verify the call originated from a registration the consumer
+     * authorized. Distinct from the HMAC signature (which proves the body
+     * wasn't tampered with) — this proves the registration is recognised.
+     */
+    token?: string;
+    /** Optional webhook-side auth metadata. */
+    authentication?: PushNotificationAuthentication;
+}
+interface TaskPushNotificationConfig {
+    taskId: string;
+    pushNotificationConfig: PushNotificationConfig;
+}
+/**
+ * Storage for push configs. The default in-memory store is fine for single
+ * Worker instances + tests; production multi-instance deployments need
+ * `SqlPushNotificationStore` (or any other shared-state adapter) so a config
+ * registered on instance A is visible to a delivery firing from instance B.
+ */
+interface PushNotificationStore {
+    set(taskId: string, config: PushNotificationConfig): Promise<void>;
+    get(taskId: string, configId: string): Promise<PushNotificationConfig | undefined>;
+    list(taskId: string): Promise<PushNotificationConfig[]>;
+    delete(taskId: string, configId: string): Promise<void>;
+}
+declare class InMemoryPushNotificationStore implements PushNotificationStore {
+    private readonly byTask;
+    set(taskId: string, config: PushNotificationConfig): Promise<void>;
+    get(taskId: string, configId: string): Promise<PushNotificationConfig | undefined>;
+    list(taskId: string): Promise<PushNotificationConfig[]>;
+    delete(taskId: string, configId: string): Promise<void>;
+}
+/** SQL-backed push config store. Schema: one row per (taskId, configId). */
+declare class SqlPushNotificationStore implements PushNotificationStore {
+    private readonly db;
+    private readonly table;
+    constructor(db: SqlAdapter, table?: string);
+    migrate(): Promise<void>;
+    set(taskId: string, config: PushNotificationConfig): Promise<void>;
+    get(taskId: string, configId: string): Promise<PushNotificationConfig | undefined>;
+    list(taskId: string): Promise<PushNotificationConfig[]>;
+    delete(taskId: string, configId: string): Promise<void>;
+}
+/**
+ * Send the webhook for each registered config on a task. Signs the body with
+ * HMAC-SHA256 against `webhookSecret` so the consumer can verify authenticity.
+ * Fire-and-forget per the design note above — the function awaits delivery
+ * (so observability hooks see the result) but does not retry on failure.
+ *
+ * The caller decides *when* to deliver — typically on terminal-state
+ * transitions emitted from `message/send` and `message/stream`.
+ */
+declare function deliverPushNotifications(args: {
+    task: Task;
+    store: PushNotificationStore;
+    webhookSecret: string | undefined;
+    /** Inject for tests. Defaults to global `fetch`. */
+    fetcher?: typeof fetch;
+    /** Optional callback so the gateway's observer can log delivery outcomes. */
+    onDelivery?: (result: PushDeliveryResult) => void;
+}): Promise<PushDeliveryResult[]>;
+interface PushDeliveryResult {
+    taskId: string;
+    configId: string;
+    url: string;
+    ok: boolean;
+    status?: number;
+    error?: string;
+}
+
+/**
+ * Observability hook surface.
+ *
+ * Consumers implement GatewayObserver to wire the gateway into their existing
+ * telemetry stack (Langfuse, OTEL, structured logs, Prometheus, etc.) without
+ * the gateway itself depending on any of those libraries.
+ *
+ * Every event carries a requestId so downstream metrics can correlate the
+ * payment verification, sandbox execution, and settlement for one request.
+ * When no observer is configured, the gateway stays silent.
+ */
+
+interface RequestContext {
+    requestId: string;
+    agentSlug: string;
+    startMs: number;
+}
+interface AuthFailureReason {
+    method: 'x402' | 'mpp' | 'apikey' | 'none';
+    code: string;
+    httpStatus: number;
+}
+interface GatewayObserver {
+    /** Called at the start of every chat completions POST. */
+    onRequestStart?: (ctx: RequestContext) => void | Promise<void>;
+    /** Called when a payment method has been successfully verified. */
+    onPaymentVerified?: (ctx: RequestContext, info: {
+        method: PaymentMethod;
+        consumerId: string;
+        keyId?: string;
+    }) => void | Promise<void>;
+    /** Called when auth fails — every branch. */
+    onAuthFailure?: (ctx: RequestContext, reason: AuthFailureReason) => void | Promise<void>;
+    /** Called when a consumer hits the rate limit. */
+    onRateLimited?: (ctx: RequestContext, info: {
+        consumerId: string;
+        retryAfterSeconds: number;
+    }) => void | Promise<void>;
+    /** Called when the request body exceeds the 64KB limit. */
+    onBodyTooLarge?: (ctx: RequestContext, contentLength: number) => void | Promise<void>;
+    /**
+     * Called when prompt-injection patterns are detected.
+     * `blocked` is true when blockInjection config is on and the request was
+     * rejected; false when the patterns were logged but the request proceeded.
+     */
+    onInjectionDetected?: (ctx: RequestContext, info: {
+        consumerId: string;
+        patterns: string[];
+        blocked: boolean;
+    }) => void | Promise<void>;
+    /** Called after a successful stream completes and recordUsage has fired. */
+    onRequestComplete?: (ctx: RequestContext, usage: GatewayUsageEvent) => void | Promise<void>;
+    /** Called when the sandbox throws. The error message is pre-scrubbed. */
+    onStreamError?: (ctx: RequestContext, info: {
+        consumerId: string;
+        errorMessage: string;
+    }) => void | Promise<void>;
+    /** Called when settlement fails. Payment already occurred; this is async bookkeeping. */
+    onSettlementError?: (ctx: RequestContext, info: {
+        consumerId: string;
+        method: PaymentMethod;
+        errorMessage: string;
+    }) => void | Promise<void>;
+}
+/**
+ * Structured-log observer. Emits one JSON line per event on the `log` function.
+ * Default sink: console.log. Production consumers usually pipe their own
+ * structured logger (pino, winston, the cf Logs binding).
+ *
+ * Usage:
+ *   new ConsoleObserver(({ level, event, ...rest }) => logger.info({ event, ...rest }))
+ */
+declare class ConsoleObserver implements GatewayObserver {
+    private readonly log;
+    constructor(log?: (entry: Record<string, unknown>) => void);
+    private emit;
+    onRequestStart(ctx: RequestContext): void;
+    onPaymentVerified(ctx: RequestContext, info: {
+        method: PaymentMethod;
+        consumerId: string;
+        keyId?: string;
+    }): void;
+    onAuthFailure(ctx: RequestContext, reason: AuthFailureReason): void;
+    onRateLimited(ctx: RequestContext, info: {
+        consumerId: string;
+        retryAfterSeconds: number;
+    }): void;
+    onBodyTooLarge(ctx: RequestContext, contentLength: number): void;
+    onInjectionDetected(ctx: RequestContext, info: {
+        consumerId: string;
+        patterns: string[];
+        blocked: boolean;
+    }): void;
+    onRequestComplete(ctx: RequestContext, usage: GatewayUsageEvent): void;
+    onStreamError(ctx: RequestContext, info: {
+        consumerId: string;
+        errorMessage: string;
+    }): void;
+    onSettlementError(ctx: RequestContext, info: {
+        consumerId: string;
+        method: PaymentMethod;
+        errorMessage: string;
+    }): void;
+}
+/**
+ * Compose multiple observers into one. Errors in any individual observer
+ * don't break the others (fire-and-forget telemetry).
+ */
+declare class CompositeObserver implements GatewayObserver {
+    private readonly observers;
+    constructor(observers: GatewayObserver[]);
+    private fanOut;
+    onRequestStart: (ctx: RequestContext) => Promise<void>;
+    onPaymentVerified: (ctx: RequestContext, info: Parameters<Required<GatewayObserver>["onPaymentVerified"]>[1]) => Promise<void>;
+    onAuthFailure: (ctx: RequestContext, reason: AuthFailureReason) => Promise<void>;
+    onRateLimited: (ctx: RequestContext, info: Parameters<Required<GatewayObserver>["onRateLimited"]>[1]) => Promise<void>;
+    onBodyTooLarge: (ctx: RequestContext, contentLength: number) => Promise<void>;
+    onInjectionDetected: (ctx: RequestContext, info: Parameters<Required<GatewayObserver>["onInjectionDetected"]>[1]) => Promise<void>;
+    onRequestComplete: (ctx: RequestContext, usage: GatewayUsageEvent) => Promise<void>;
+    onStreamError: (ctx: RequestContext, info: Parameters<Required<GatewayObserver>["onStreamError"]>[1]) => Promise<void>;
+    onSettlementError: (ctx: RequestContext, info: Parameters<Required<GatewayObserver>["onSettlementError"]>[1]) => Promise<void>;
+}
+/**
+ * Generate a request-id. Crypto-random 16 bytes, hex-encoded with an `req_` prefix.
+ * Works in Workers, Node, and browsers — all have globalThis.crypto.
+ */
+declare function generateRequestId(): string;
+
+interface AgentMeta {
+    /** Unique agent identifier (workspace ID, session ID, etc.) */
+    id: string;
+    /** Owner/creator user ID */
+    ownerId: string;
+    /** Public URL slug */
+    slug: string;
+    /** System prompt for the agent (injected before consumer messages) */
+    systemPrompt?: string;
+    /** Per-token price in USD (default: 0.00002) */
+    pricePerTokenUsd: number;
+    /** Platform fee as decimal 0-1 (default: 0.20 = 20%) */
+    platformFeePercent: number;
+    /** Remote operator endpoint for sovereignty mode (null = centralized) */
+    sandboxEndpoint: string | null;
+    /** Sandbox ID on remote operator */
+    remoteSandboxId: string | null;
+    /** PASETO bearer token for remote operator auth */
+    remoteBearerToken: string | null;
+    /** Whether agent is published and accepting requests */
+    enabled: boolean;
+    /**
+     * CLI harness backend that runs this agent inside the sandbox sidecar.
+     *
+     * When set, the host's `getSandbox()` SHOULD return a `SandboxBox`
+     * whose `streamPrompt` POSTs to the sidecar's
+     * `POST /agent/invoke/chat/completions` endpoint with
+     * `model: "<harness>/<harnessModel>"` — that endpoint runs the
+     * harness against the sandbox workspace and streams OpenAI-shape
+     * `chat.completion.chunk` frames back.
+     *
+     * When unset (legacy / template mode), the host's `streamPrompt`
+     * falls back to the template's own `/api/chat/completions` (proxied
+     * via the sidecar's `/agent/invoke`).
+     *
+     * Known harnesses (registered in agent-dev-container's
+     * cli-agent-bindings.ts): opencode, claude-code, codex, kimi-code,
+     * amp, factory-droids, pi, hermes, openclaw, forge, acp, cursor.
+     * Aliases the sidecar canonicalizes: claude → claude-code,
+     * kimi → kimi-code, factory → factory-droids.
+     */
+    harness?: string;
+    /**
+     * Model identifier to pass after the harness in the
+     * `<harness>/<model>` slash form. Format is harness-specific:
+     *   claude-code:   "sonnet", "opus", or a versioned id like
+     *                  "claude-sonnet-4-20250514"
+     *   opencode:      "anthropic/claude-sonnet-4-5", "openai/gpt-4o", …
+     *                  (opencode embeds provider before model)
+     *   codex:         "gpt-5-codex"
+     *   kimi-code:     "kimi-for-coding"
+     *
+     * Only meaningful when `harness` is set; ignored otherwise.
+     */
+    harnessModel?: string;
+    /**
+     * Optional human description surfaced in the A2A Agent Card. Defaults to
+     * `"{slug} agent"` when absent.
+     */
+    description?: string;
+    /**
+     * Optional A2A skill descriptors. Each entry advertises what the agent
+     * can do so non-Tangle A2A clients can select agents by capability. When
+     * absent, the gateway synthesizes a single default `chat` skill from
+     * `slug` + `description`.
+     */
+    skills?: AgentSkill[];
+}
+type PaymentMethod = 'x402' | 'mpp' | 'apikey' | 'none';
+interface X402Config {
+    /** Ethereum operator address for SpendAuth verification */
+    operatorAddress: string;
+    /** Blockchain network ID (default: 3799) */
+    chainId: number;
+    /** ShieldedCredits contract address */
+    creditsAddress?: string;
+    /** RPC URL for on-chain verification (optional, demo mode skips this) */
+    rpcUrl?: string;
+    /** Demo mode: skip signature verification (default: false). NEVER enable in production. */
+    demoMode?: boolean;
+    /** Production signer verification. Called with the raw SpendAuth payload. Return true if signature is valid. */
+    verifySigner?: (payload: Record<string, unknown>) => Promise<boolean>;
+}
+interface MppConfig {
+    /** MPP realm (e.g. "agents.tangle.tools") */
+    realm: string;
+    /** MPP method name (default: "blueprintevm") */
+    method?: string;
+    /**
+     * Production verifier for the method-specific credential. Return the
+     * authenticated consumer id, or null when the credential is invalid.
+     * The callback receives the decoded JSON payload when one exists plus the
+     * original decoded credential so non-JSON methods can verify their own form.
+     * Omit only when x402.demoMode is explicitly enabled for local testing, or
+     * when x402.verifySigner handles an x402-compatible MPP credential.
+     */
+    verifySigner?: (payload: Record<string, unknown>, context: {
+        method: string;
+        credential: string;
+    }) => Promise<string | null>;
+}
+interface PaymentResult {
+    method: PaymentMethod;
+    consumerId: string;
+    /**
+     * Per-request id (matches `RequestContext.requestId` from the
+     * Observer pattern). Threaded into `settlePayment` so callers can
+     * attribute revenue deterministically per-request without scanning
+     * a FIFO queue keyed by consumerId — when the same consumer is
+     * paying for two concurrent requests against agents A and B, FIFO
+     * misroutes one. With `requestId` the call site can write a
+     * settlement row keyed exactly to the request that earned it.
+     */
+    requestId: string;
+}
+interface ApiKeyInfo {
+    keyId: string;
+    consumerId: string;
+    /** Scopes this key is authorized for (e.g. ["chat", "forms"]) */
+    scopes?: string[];
+    /** Per-key rate limit override (requests per minute). If set, overrides global rate limit. */
+    rateLimitPerMinute?: number;
+    /** Per-key daily limit override. */
+    dailyLimit?: number;
+}
+interface GatewayUsageEvent {
+    /**
+     * Per-request id (matches `RequestContext.requestId`). Lets
+     * `recordUsage` correlate the usage row to the same request that
+     * `settlePayment` settles, observability hooks observe, and
+     * `onRequestComplete` reports — without re-deriving from a
+     * synthetic key. Required field as of 0.4.0; the gateway always has
+     * it in scope at the recordUsage call site.
+     */
+    requestId: string;
+    agentId: string;
+    agentSlug: string;
+    consumerId: string;
+    paymentMethod: PaymentMethod;
+    inputTokens: number;
+    outputTokens: number;
+    totalCostUsd: number;
+    ownerEarnedUsd: number;
+    platformFeeUsd: number;
+    durationMs: number;
+}
+interface SandboxStreamEvent {
+    type?: string;
+    data?: {
+        part?: {
+            type?: string;
+            text?: string;
+        };
+        delta?: string;
+        finalText?: string;
+        /**
+         * Optional sandbox-side signal that the agent has paused and is waiting
+         * for additional input from the caller. The A2A gateway translates this
+         * into an `input-required` task status; the caller can then submit a
+         * follow-up `message/send` with the same `taskId` to continue. Ignored
+         * by the OpenAI-compat path. Carry an optional `prompt` to surface to
+         * the caller (rendered as the input-required message body).
+         */
+        inputRequired?: {
+            prompt?: string;
+        };
+    };
+}
+interface SandboxBox {
+    streamPrompt(message: string, opts?: {
+        sessionId?: string;
+        systemPrompt?: string;
+    }): AsyncIterable<SandboxStreamEvent>;
+}
+interface GatewayConfig {
+    /** Resolve agent metadata by slug. Return null if not found or not published. */
+    resolveAgent: (slug: string) => Promise<AgentMeta | null>;
+    /** Get a sandbox instance for the agent. Called after payment is verified. */
+    getSandbox: (agent: AgentMeta) => Promise<SandboxBox>;
+    /**
+     * Optional host authorization hook fired after payment verification
+     * and before sandbox resolution. Use it for per-agent allowlists,
+     * per-consumer quotas, contract scope checks, and instance ownership.
+     */
+    authorizeConsumer?: (agent: AgentMeta, consumer: {
+        method: PaymentMethod;
+        consumerId: string;
+        keyId?: string;
+        requestId: string;
+    }) => Promise<{
+        allow: true;
+    } | {
+        allow: false;
+        reason: string;
+        code: string;
+    }>;
+    /** Record a usage event after request completes. */
+    recordUsage: (event: GatewayUsageEvent) => Promise<void>;
+    /** x402 payment configuration */
+    x402: X402Config;
+    /** MPP (Machine Payments Protocol) configuration. It is advertised only when a production verifier or explicit demo mode is available. */
+    mpp?: MppConfig;
+    /**
+     * Verify an API key. Return key info if valid, null if invalid.
+     * In explicit x402 demo mode, the built-in verifier accepts `sk_agent_*` keys.
+     * Production gateways must provide this callback.
+     */
+    verifyApiKey?: (authHeader: string) => Promise<ApiKeyInfo | null>;
+    /**
+     * Settle payment after successful response.
+     * For x402: call ShieldedCredits.claimPayment()
+     * For API key: deduct from spending limit
+     * Default: no-op (demo mode).
+     */
+    settlePayment?: (payment: PaymentResult, cost: number) => Promise<void>;
+    /** Base URL for API key purchase links (e.g. "https://film.tangle.tools") */
+    baseUrl?: string;
+    /** Max message length in chars (default: 8000) */
+    maxMessageLength?: number;
+    /** Required scope for chat endpoint (default: "chat"). API keys must include this scope. */
+    requiredScope?: string;
+    /** Block requests with detected injection patterns (default: false — log only) */
+    blockInjection?: boolean;
+    /** Rate limiting config. Default: 60 requests per 60 seconds per consumer. */
+    rateLimit?: {
+        limit: number;
+        windowSeconds: number;
+    };
+    /** Custom rate limit store (default: in-memory). Use KV-backed for Workers. */
+    rateLimitStore?: RateLimitStore;
+    /** Nonce replay protection store (default: in-memory). Rejects reused x402 nonces. */
+    nonceStore?: NonceStore;
+    /**
+     * Observability hook. When set, the gateway emits typed events for request
+     * lifecycle, auth outcomes, rate limits, injection detection, usage, errors,
+     * and settlement failures. See ./observer.ts for the interface and
+     * ConsoleObserver / CompositeObserver implementations.
+     */
+    observer?: GatewayObserver;
+    /**
+     * A2A protocol configuration. When set, the gateway exposes the A2A
+     * surface alongside its OpenAI-compatible endpoints:
+     *   GET  /:slug/.well-known/agent.json   — AgentCard discovery
+     *   POST /:slug                          — JSON-RPC 2.0 endpoint
+     *     methods: message/send, message/stream, tasks/get, tasks/cancel
+     * Auth + rate-limit + injection-filter + authorization all share the
+     * same pipeline as the OpenAI-compat path. `taskStore` defaults to
+     * `InMemoryTaskStore`; swap in D1/postgres/DO for durable deployments.
+     */
+    a2a?: {
+        /**
+         * Where tasks live. Defaults to `InMemoryTaskStore`; swap in
+         * `SqlTaskStore` (D1, postgres, sqlite, libSQL) for durability across
+         * gateway restarts.
+         */
+        taskStore?: TaskStore;
+        /**
+         * Where push notification configs live. When set, the gateway advertises
+         * `capabilities.pushNotifications: true` and exposes the four
+         * `tasks/pushNotificationConfig/*` JSON-RPC methods. Defaults to
+         * undefined (push support disabled), so the agent card honestly reflects
+         * what the gateway will actually do.
+         */
+        pushStore?: PushNotificationStore;
+        /**
+         * Shared HMAC secret used to sign webhook deliveries (`X-A2A-Signature:
+         * sha256=<hex>`). The consumer's webhook verifies the body against this
+         * secret to confirm the call originated from this gateway. Required when
+         * `pushStore` is set; without it, deliveries fire unsigned and a
+         * malicious party that knows the webhook URL can forge deliveries.
+         */
+        webhookSecret?: string;
+        /**
+         * Optional fetcher override for webhook delivery. Defaults to global
+         * `fetch`. Override for tests or to wire a queue-backed sender.
+         */
+        pushFetcher?: typeof fetch;
+    };
+}
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+}
+interface ChatCompletionRequest {
+    model?: string;
+    messages: ChatMessage[];
+    stream?: boolean;
+    temperature?: number;
+    max_tokens?: number;
+}
+interface ChatCompletionChunk {
+    id: string;
+    object: 'chat.completion.chunk';
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        delta: {
+            content?: string;
+            role?: string;
+        };
+        finish_reason: string | null;
+    }>;
+}
+
+export { type TaskStatusUpdateEvent as $, type ApiKeyInfo as A, type PushNotificationAuthentication as B, type ChatMessage as C, type D1DatabaseLike as D, type PushNotificationConfig as E, type FilePart as F, type GatewayConfig as G, type PushNotificationStore as H, InMemoryPushNotificationStore as I, type JSONRPCErrorResponse as J, type SandboxStreamEvent as K, type SqlAdapter as L, type MppConfig as M, SqlPushNotificationStore as N, SqlTaskStore as O, type Part as P, type StreamingEvent as Q, type RequestContext as R, type SandboxBox as S, type Task as T, type TaskArtifactUpdateEvent as U, type TaskIdParams as V, type TaskPushNotificationConfig as W, type X402Config as X, type TaskPushNotificationConfigGetParams as Y, type TaskState as Z, type TaskStatus as _, A2A_ERROR_CODES as a, type TaskStore as a0, type TextPart as a1, d1ToSqlAdapter as a2, deliverPushNotifications as a3, generateRequestId as a4, type AgentCapabilities as b, type AgentCard as c, type AgentCardAuthentication as d, type AgentMeta as e, type AgentProvider as f, type AgentSkill as g, type Artifact as h, type AuthFailureReason as i, type ChatCompletionChunk as j, type ChatCompletionRequest as k, CompositeObserver as l, ConsoleObserver as m, type D1StmtLike as n, type DataPart as o, type GatewayObserver as p, type GatewayUsageEvent as q, InMemoryTaskStore as r, type JSONRPCRequest as s, type JSONRPCResponse as t, type JSONRPCSuccessResponse as u, type Message as v, type MessageSendParams as w, type PaymentMethod as x, type PaymentResult as y, type PushDeliveryResult as z };