@bondedhq/sdk 0.0.0-stage → 0.1.1

package/dist/guarded.d.ts

@@ -0,0 +1,80 @@
+import { type EvmMandate } from "@bondedhq/shared";
+import { type ApproveParams, type CallParams, type SwapParams, type TransferParams, type VaultAction } from "./actions.js";
+import type { DryRunResult } from "./breaches.js";
+import { type SentinelVerdict } from "./errors.js";
+import { type MessageSigner, type SentinelInput } from "./sentinel.js";
+import type { ActionResult, BondedVault } from "./vault.js";
+/** A token the agent trades, so Sentinel sees symbols and whole units as it was trained on. */
+export interface TokenInfo {
+    symbol: string;
+    address: string;
+    decimals: number;
+}
+export interface SentinelGuardOptions {
+    /** The Bonded API that serves `POST /sentinel/check`. */
+    apiUrl: string;
+    /** The mandate in plain words, or the mandate itself (described with `describeMandate`). */
+    mandate: string | EvmMandate;
+    /** Names token addresses in the check. */
+    tokens?: readonly TokenInfo[];
+    /** Defaults to the vault's `agentId()`. */
+    agentId?: bigint | number | string;
+    /** Defaults to the public client's chain. */
+    chainId?: number;
+    /** Signs the check. Defaults to the vault's wallet (the agent key). */
+    account?: MessageSigner;
+    /**
+     * When Sentinel can't answer (down, busy, rate limited): "refuse" the action (the default),
+     * or "proceed" without its advice. The vault enforces the mandate either way.
+     */
+    onUnavailable?: "refuse" | "proceed";
+    fetch?: typeof fetch;
+    /** Give up on Sentinel after this long, in milliseconds. Default 15,000. */
+    timeoutMs?: number;
+}
+export interface GuardOptions {
+    /** Ask Sentinel before each write that passes the dry run. Off unless set. */
+    sentinel?: SentinelGuardOptions;
+}
+/** What the agent read before this action, for Sentinel. */
+export interface GuardContext {
+    untrustedInputs?: readonly SentinelInput[];
+}
+/** What a guarded write did, and the checks it passed. */
+export interface GuardedResult extends ActionResult {
+    dryRun: DryRunResult;
+    /** Sentinel's answer, when it was asked and answered. */
+    sentinel?: SentinelVerdict;
+}
+/** The checks an action passed, without sending it. */
+export interface GuardCheck {
+    dryRun: DryRunResult;
+    sentinel?: SentinelVerdict;
+}
+/**
+ * A vault that checks every write before sending it: first a dry run of `execute` against the
+ * chain's current state, refused if the vault would record a breach (`PredictedBreachError`);
+ * then, if configured, Sentinel, refused if it advises against (`SentinelRefusedError`).
+ *
+ * This turns a Monitor-mode vault into one that doesn't knowingly breach. It is a client-side
+ * check: the state can change between the dry run and the transaction, and the vault's own
+ * verdict on chain is what counts.
+ */
+export declare class GuardedVault {
+    readonly vault: BondedVault;
+    private readonly options;
+    /** The chain id and agent id Sentinel checks are signed for, read once. */
+    private identity;
+    constructor(vault: BondedVault, options?: GuardOptions);
+    swap(params: SwapParams, context?: GuardContext): Promise<GuardedResult>;
+    transfer(params: TransferParams, context?: GuardContext): Promise<GuardedResult>;
+    approve(params: ApproveParams, context?: GuardContext): Promise<GuardedResult>;
+    call(params: CallParams, context?: GuardContext): Promise<GuardedResult>;
+    execute(action: VaultAction, context?: GuardContext): Promise<GuardedResult>;
+    /** Runs the guard's checks on an action and throws if one refuses. Sends nothing. */
+    check(action: VaultAction, context?: GuardContext): Promise<GuardCheck>;
+    private askSentinel;
+}
+/** Wraps a vault so every write is dry-run (and optionally checked by Sentinel) first. */
+export declare function guarded(vault: BondedVault, options?: GuardOptions): GuardedVault;
+//# sourceMappingURL=guarded.d.ts.map

package/dist/guarded.js

@@ -0,0 +1,97 @@
+import { describeMandate } from "@bondedhq/shared";
+import { describeAction, } from "./actions.js";
+import { BondedError, PredictedBreachError, SentinelError, SentinelRefusedError, } from "./errors.js";
+import { checkWithSentinel } from "./sentinel.js";
+/**
+ * A vault that checks every write before sending it: first a dry run of `execute` against the
+ * chain's current state, refused if the vault would record a breach (`PredictedBreachError`);
+ * then, if configured, Sentinel, refused if it advises against (`SentinelRefusedError`).
+ *
+ * This turns a Monitor-mode vault into one that doesn't knowingly breach. It is a client-side
+ * check: the state can change between the dry run and the transaction, and the vault's own
+ * verdict on chain is what counts.
+ */
+export class GuardedVault {
+    vault;
+    options;
+    /** The chain id and agent id Sentinel checks are signed for, read once. */
+    identity;
+    constructor(vault, options = {}) {
+        this.vault = vault;
+        this.options = options;
+    }
+    swap(params, context) {
+        return this.execute({ type: "swap", ...params }, context);
+    }
+    transfer(params, context) {
+        return this.execute({ type: "transfer", ...params }, context);
+    }
+    approve(params, context) {
+        return this.execute({ type: "approve", ...params }, context);
+    }
+    call(params, context) {
+        return this.execute({ type: "call", ...params }, context);
+    }
+    async execute(action, context = {}) {
+        const checks = await this.check(action, context);
+        const result = await this.vault.execute(action);
+        return { ...result, ...checks };
+    }
+    /** Runs the guard's checks on an action and throws if one refuses. Sends nothing. */
+    async check(action, context = {}) {
+        const dryRun = await this.vault.dryRun(action);
+        if (!dryRun.ok)
+            throw new PredictedBreachError(dryRun);
+        const sentinel = await this.askSentinel(action, context);
+        if (sentinel?.blocked)
+            throw new SentinelRefusedError(sentinel);
+        return sentinel ? { dryRun, sentinel } : { dryRun };
+    }
+    async askSentinel(action, context) {
+        const s = this.options.sentinel;
+        if (!s)
+            return undefined;
+        const wallet = this.vault.walletClient;
+        const account = s.account ??
+            (wallet
+                ? { signMessage: (args) => wallet.signMessage({ account: wallet.account, ...args }) }
+                : undefined);
+        if (!account)
+            throw new BondedError("CONFIG", "Sentinel checks are signed by the agent key; none is set");
+        this.identity ??= Promise.all([
+            s.chainId ?? this.vault.publicClient.getChainId(),
+            s.agentId ?? this.vault.status().then((status) => status.agentId),
+        ]);
+        const [chainId, agentId] = await this.identity.catch((error) => {
+            this.identity = undefined;
+            throw error;
+        });
+        try {
+            return await checkWithSentinel({
+                apiUrl: s.apiUrl,
+                chainId,
+                agentId,
+                vault: this.vault.address,
+                mandate: typeof s.mandate === "string" ? s.mandate : describeMandate(s.mandate, s.tokens),
+                proposedAction: describeAction(action, s.tokens),
+                untrustedInputs: context.untrustedInputs ?? [],
+                account,
+                signal: AbortSignal.timeout(s.timeoutMs ?? 15_000),
+                ...(s.fetch ? { fetch: s.fetch } : {}),
+            });
+        }
+        catch (error) {
+            // Only unavailability may be skipped; a refused request (bad signature, wrong vault) is a bug.
+            const unavailable = error instanceof SentinelError &&
+                (error.status === undefined || error.status === 429 || error.status >= 500);
+            if (unavailable && s.onUnavailable === "proceed")
+                return undefined;
+            throw error;
+        }
+    }
+}
+/** Wraps a vault so every write is dry-run (and optionally checked by Sentinel) first. */
+export function guarded(vault, options = {}) {
+    return new GuardedVault(vault, options);
+}
+//# sourceMappingURL=guarded.js.map

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @bondedhq/sdk: trade through a Bonded Mandate Vault from any TypeScript agent.
+ *
+ * Framework plugins live in subpaths, each with its framework as an optional peer dependency:
+ * `@bondedhq/sdk/agentkit`, `@bondedhq/sdk/solana-agent-kit`, `@bondedhq/sdk/eliza`,
+ * `@bondedhq/sdk/langchain`, `@bondedhq/sdk/ai-sdk`. The episode's tools over MCP are in
+ * `@bondedhq/sdk/mcp`, and the Agent URL handler in `@bondedhq/sdk/agent-url`.
+ */
+export { BondedVault, type ActionResult, type BondedVaultConfig, type VaultStatus, } from "./vault.js";
+export { demoRouter, describeAction, type ApproveParams, type CallParams, type SwapParams, type SwapRouter, type TransferParams, type VaultAction, type VaultCall, } from "./actions.js";
+export { breachReason, type DryRunResult, type VaultBreach } from "./breaches.js";
+export { guarded, GuardedVault, type GuardCheck, type GuardContext, type GuardedResult, type GuardOptions, type SentinelGuardOptions, type TokenInfo, } from "./guarded.js";
+export { checkWithSentinel, type MessageSigner, type SentinelCheckRequest, type SentinelInput, } from "./sentinel.js";
+export { buildMandate, describeMandate, type BuiltMandate, type EvmMandate, type EvmMandateParams, type EvmMandateRules, } from "./mandate.js";
+export { BlockedByMandateError, BondedError, CallRevertedError, NotAgentError, PredictedBreachError, SentinelError, SentinelRefusedError, VaultFrozenError, type SentinelVerdict, } from "./errors.js";
+export type { BreachType } from "@bondedhq/shared";
+export { BONDED_VAULT_TOOLS, bondedVaultFromEnv, bondedVaultTools, type BondedVaultTool, type BondedVaultToolName, type BondedVaultToolsOptions, } from "./vault-tools.js";
+export { bondedEpisodeEnv, episodeVault, fromBondedEnv, isBondedEpisode, type BondedEpisode, } from "./episode.js";
+export { checkUnprotectedAllowances, deploymentTokens, unprotectedAllowancesWarning, type AllowanceCheck, type AllowanceFinding, type TokenRef, installMandateModule, type InstallMandateModuleInput, type ModuleAccountType, type ModuleInstallPlan, } from "./module.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @bondedhq/sdk: trade through a Bonded Mandate Vault from any TypeScript agent.
+ *
+ * Framework plugins live in subpaths, each with its framework as an optional peer dependency:
+ * `@bondedhq/sdk/agentkit`, `@bondedhq/sdk/solana-agent-kit`, `@bondedhq/sdk/eliza`,
+ * `@bondedhq/sdk/langchain`, `@bondedhq/sdk/ai-sdk`. The episode's tools over MCP are in
+ * `@bondedhq/sdk/mcp`, and the Agent URL handler in `@bondedhq/sdk/agent-url`.
+ */
+export { BondedVault, } from "./vault.js";
+export { demoRouter, describeAction, } from "./actions.js";
+export { breachReason } from "./breaches.js";
+export { guarded, GuardedVault, } from "./guarded.js";
+export { checkWithSentinel, } from "./sentinel.js";
+export { buildMandate, describeMandate, } from "./mandate.js";
+export { BlockedByMandateError, BondedError, CallRevertedError, NotAgentError, PredictedBreachError, SentinelError, SentinelRefusedError, VaultFrozenError, } from "./errors.js";
+export { BONDED_VAULT_TOOLS, bondedVaultFromEnv, bondedVaultTools, } from "./vault-tools.js";
+export { bondedEpisodeEnv, episodeVault, fromBondedEnv, isBondedEpisode, } from "./episode.js";
+export { checkUnprotectedAllowances, deploymentTokens, unprotectedAllowancesWarning, installMandateModule, } from "./module.js";
+//# sourceMappingURL=index.js.map

package/dist/json-schema-zod3.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod/v3";
+/**
+ * A zod 3 schema for a tool's JSON Schema, for frameworks whose tools are typed with zod 3
+ * (Coinbase AgentKit 0.10). It covers what the Arena's tools use (objects of strings with
+ * patterns and lengths, numbers, booleans, arrays, enums); anything else is accepted as is, and
+ * the gateway checks every call against the real schema anyway.
+ */
+export declare function zod3FromJsonSchema(schema: unknown): z.ZodTypeAny;
+//# sourceMappingURL=json-schema-zod3.d.ts.map

package/dist/json-schema-zod3.js

@@ -0,0 +1,54 @@
+import { z } from "zod/v3";
+/**
+ * A zod 3 schema for a tool's JSON Schema, for frameworks whose tools are typed with zod 3
+ * (Coinbase AgentKit 0.10). It covers what the Arena's tools use (objects of strings with
+ * patterns and lengths, numbers, booleans, arrays, enums); anything else is accepted as is, and
+ * the gateway checks every call against the real schema anyway.
+ */
+export function zod3FromJsonSchema(schema) {
+    const s = (schema ?? {});
+    const described = (t) => typeof s.description === "string" ? t.describe(s.description) : t;
+    if (Array.isArray(s.enum) && s.enum.length > 0 && s.enum.every((v) => typeof v === "string"))
+        return described(z.enum(s.enum));
+    if ("const" in s && ["string", "number", "boolean"].includes(typeof s.const))
+        return described(z.literal(s.const));
+    switch (s.type) {
+        case "object": {
+            const properties = (s.properties ?? {});
+            const required = new Set(Array.isArray(s.required) ? s.required : []);
+            const shape = {};
+            for (const [key, value] of Object.entries(properties)) {
+                const t = zod3FromJsonSchema(value);
+                shape[key] = required.has(key) ? t : t.optional();
+            }
+            const object = z.object(shape);
+            return described(s.additionalProperties === false ? object.strict() : object.passthrough());
+        }
+        case "string": {
+            let t = z.string();
+            if (typeof s.minLength === "number")
+                t = t.min(s.minLength);
+            if (typeof s.maxLength === "number")
+                t = t.max(s.maxLength);
+            if (typeof s.pattern === "string")
+                t = t.regex(new RegExp(s.pattern));
+            return described(t);
+        }
+        case "integer":
+        case "number": {
+            let t = s.type === "integer" ? z.number().int() : z.number();
+            if (typeof s.minimum === "number")
+                t = t.min(s.minimum);
+            if (typeof s.maximum === "number")
+                t = t.max(s.maximum);
+            return described(t);
+        }
+        case "boolean":
+            return described(z.boolean());
+        case "array":
+            return described(z.array(zod3FromJsonSchema(s.items)));
+        default:
+            return described(z.any());
+    }
+}
+//# sourceMappingURL=json-schema-zod3.js.map

package/dist/langchain.d.ts

@@ -0,0 +1,39 @@
+import { DynamicStructuredTool } from "@langchain/core/tools";
+import { type EpisodeTools, type EpisodeToolsSource } from "./mcp.js";
+import { type BondedVaultToolsOptions } from "./vault-tools.js";
+export type { BondedVaultToolsOptions } from "./vault-tools.js";
+/**
+ * The episode's tools as LangChain `StructuredTool`s, for LangChain and LangGraph agents
+ * (`createReactAgent`, `ToolNode`, `model.bindTools`). Each takes the tool's own JSON Schema and
+ * returns what the Arena returned, as text; a failed call returns `Error: ...` so the model can
+ * react, as it would to a production tool.
+ *
+ * With no argument it reads the episode from the runner's `BONDED_*` variables. Switch to them
+ * only while being rated:
+ *
+ * ```ts
+ * const tools = isBondedEpisode() ? await bondedLangChainTools() : productionTools;
+ * const agent = createReactAgent({ llm, tools });
+ * ```
+ *
+ * Peer dependency: `@langchain/core` 1.
+ */
+export declare function bondedLangChainTools(from?: EpisodeTools | EpisodeToolsSource): Promise<DynamicStructuredTool[]>;
+/**
+ * The agent's Mandate Vault as LangChain tools, for production: `swap`, `transfer`, `approve`
+ * and `vault_status`, every write sent through `BondedVault` so the vault checks it against the
+ * mandate. Each write is dry-run first and refused on a predicted breach (`guard`, on by
+ * default); with `sentinel`, Sentinel is asked too, with what `context()` says the agent read.
+ * A refusal or failure comes back as `Error: ...` text, so the model can react.
+ *
+ * The names and arguments match the episode's write tools, so the agent's prompts work the same
+ * while it is rated:
+ *
+ * ```ts
+ * const tools = isBondedEpisode()
+ *   ? await bondedLangChainTools()
+ *   : [...productionTools, ...bondedVaultLangChainTools({ vault })];
+ * ```
+ */
+export declare function bondedVaultLangChainTools(options: BondedVaultToolsOptions): DynamicStructuredTool[];
+//# sourceMappingURL=langchain.d.ts.map

package/dist/langchain.js

@@ -0,0 +1,53 @@
+import { DynamicStructuredTool } from "@langchain/core/tools";
+import { resolveTools, resultText } from "./mcp.js";
+import { bondedVaultTools } from "./vault-tools.js";
+/**
+ * The episode's tools as LangChain `StructuredTool`s, for LangChain and LangGraph agents
+ * (`createReactAgent`, `ToolNode`, `model.bindTools`). Each takes the tool's own JSON Schema and
+ * returns what the Arena returned, as text; a failed call returns `Error: ...` so the model can
+ * react, as it would to a production tool.
+ *
+ * With no argument it reads the episode from the runner's `BONDED_*` variables. Switch to them
+ * only while being rated:
+ *
+ * ```ts
+ * const tools = isBondedEpisode() ? await bondedLangChainTools() : productionTools;
+ * const agent = createReactAgent({ llm, tools });
+ * ```
+ *
+ * Peer dependency: `@langchain/core` 1.
+ */
+export async function bondedLangChainTools(from) {
+    const episode = await resolveTools(from);
+    return episode.tools.map((t) => new DynamicStructuredTool({
+        name: t.name,
+        description: t.description,
+        schema: t.inputSchema,
+        func: async (args) => resultText(await t.call(args ?? {})),
+    }));
+}
+/**
+ * The agent's Mandate Vault as LangChain tools, for production: `swap`, `transfer`, `approve`
+ * and `vault_status`, every write sent through `BondedVault` so the vault checks it against the
+ * mandate. Each write is dry-run first and refused on a predicted breach (`guard`, on by
+ * default); with `sentinel`, Sentinel is asked too, with what `context()` says the agent read.
+ * A refusal or failure comes back as `Error: ...` text, so the model can react.
+ *
+ * The names and arguments match the episode's write tools, so the agent's prompts work the same
+ * while it is rated:
+ *
+ * ```ts
+ * const tools = isBondedEpisode()
+ *   ? await bondedLangChainTools()
+ *   : [...productionTools, ...bondedVaultLangChainTools({ vault })];
+ * ```
+ */
+export function bondedVaultLangChainTools(options) {
+    return bondedVaultTools(options).map((t) => new DynamicStructuredTool({
+        name: t.name,
+        description: t.description,
+        schema: t.inputSchema,
+        func: async (args) => resultText(await t.call(args ?? {})),
+    }));
+}
+//# sourceMappingURL=langchain.js.map

package/dist/mandate.d.ts

@@ -0,0 +1,36 @@
+import { type EvmMandate, type EvmMandateParams, type EvmMandateRules } from "@bondedhq/shared";
+import type { Hex } from "viem";
+export type { EvmMandate, EvmMandateParams, EvmMandateRules };
+export { describeMandate } from "@bondedhq/shared";
+/** A mandate ready for `MandateVaultFactory.createVault`. */
+export interface BuiltMandate {
+    /** The canonical mandate JSON: keep it, the API and raters check it against the hash. */
+    mandate: EvmMandate;
+    /**
+     * The hash stored on chain. For a vault: keccak256 of the canonical JSON. For a module: the
+     * commitment to the enforced params (`mandateCommitment`), which MandateModuleFactory checks.
+     * Ratings, quotes and cover use this value.
+     */
+    mandateHash: Hex;
+    /** The struct `createVault` (or, for a module, `createModule`) takes. */
+    params: EvmMandateParams;
+}
+/**
+ * Plain rules (dollars, percentages, function signatures) to the mandate a vault enforces.
+ * The same builder the web app's onboarding uses, so both hash the same rules the same way.
+ * Pass `{ for: "module" }` for a MandateModule on a smart account.
+ *
+ * ```ts
+ * const { params, mandate } = buildMandate({
+ *   chainId: 46630, agentId: 12n, mode: "enforce",
+ *   baseAsset: usdg, assets: [tsla],
+ *   targets: [{ address: router, functions: ["swap(address,address,uint256,address)"] }],
+ *   maxTradeUsd: 5_000, maxDailyUsd: 25_000, maxDrawdownPct: 15, maxSlippagePct: 3,
+ *   description: "Rebalance a tech basket against tUSDG.",
+ * });
+ * ```
+ */
+export declare function buildMandate(rules: EvmMandateRules, options?: {
+    for?: "vault" | "module";
+}): BuiltMandate;
+//# sourceMappingURL=mandate.d.ts.map

package/dist/mandate.js

@@ -0,0 +1,26 @@
+import { buildEvmMandate, mandateHash, toEvmMandateParams, withMandateCommitment, } from "@bondedhq/shared";
+export { describeMandate } from "@bondedhq/shared";
+/**
+ * Plain rules (dollars, percentages, function signatures) to the mandate a vault enforces.
+ * The same builder the web app's onboarding uses, so both hash the same rules the same way.
+ * Pass `{ for: "module" }` for a MandateModule on a smart account.
+ *
+ * ```ts
+ * const { params, mandate } = buildMandate({
+ *   chainId: 46630, agentId: 12n, mode: "enforce",
+ *   baseAsset: usdg, assets: [tsla],
+ *   targets: [{ address: router, functions: ["swap(address,address,uint256,address)"] }],
+ *   maxTradeUsd: 5_000, maxDailyUsd: 25_000, maxDrawdownPct: 15, maxSlippagePct: 3,
+ *   description: "Rebalance a tech basket against tUSDG.",
+ * });
+ * ```
+ */
+export function buildMandate(rules, options = {}) {
+    const mandate = buildEvmMandate(rules);
+    if (options.for === "module") {
+        const params = withMandateCommitment(toEvmMandateParams(mandate));
+        return { mandate, mandateHash: params.mandateHash, params };
+    }
+    return { mandate, mandateHash: mandateHash(mandate), params: toEvmMandateParams(mandate) };
+}
+//# sourceMappingURL=mandate.js.map

package/dist/mcp-config-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=mcp-config-cli.d.ts.map

package/dist/mcp-config-cli.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { BondedError } from "./errors.js";
+import { fromBondedEnv } from "./episode.js";
+import { mcpConfigJson } from "./mcp.js";
+/**
+ * `bonded-mcp-config [--style http|url|stdio] [--name <name>]`: prints the MCP config for the
+ * episode the Bonded runner set up (`BONDED_*` variables), for agents that read an `mcpServers`
+ * file. The URL is per episode: run it at the start of every episode.
+ */
+const USAGE = "usage: bonded-mcp-config [--style http|url|stdio] [--name <name>]";
+function main(argv) {
+    const options = {};
+    for (let i = 0; i < argv.length; i++) {
+        const flag = argv[i];
+        const value = argv[i + 1];
+        if (flag === "--help" || flag === "-h") {
+            process.stdout.write(`${USAGE}\n`);
+            return 0;
+        }
+        if (flag === "--style" && (value === "http" || value === "url" || value === "stdio")) {
+            options.style = value;
+            i++;
+        }
+        else if (flag === "--name" && value) {
+            options.name = value;
+            i++;
+        }
+        else {
+            process.stderr.write(`${USAGE}\n`);
+            return 2;
+        }
+    }
+    try {
+        process.stdout.write(mcpConfigJson(fromBondedEnv(), options));
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof BondedError ? error.message : String(error)}\n` +
+            "bonded-mcp-config reads the episode the Bonded runner sets up; run it inside an episode.\n");
+        return 1;
+    }
+}
+process.exitCode = main(process.argv.slice(2));
+//# sourceMappingURL=mcp-config-cli.js.map

package/dist/mcp.d.ts

@@ -0,0 +1,131 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { DoneRequest } from "@bondedhq/shared";
+export { isBondedEpisode } from "./episode.js";
+export { finishEpisode } from "./done.js";
+/**
+ * Where an episode's tools are. A `BondedEpisode` (from `fromBondedEnv`, or the one an Agent URL
+ * handler hands you) has these, and so does the runner protocol's `EpisodeMessage`.
+ */
+export interface EpisodeToolsSource {
+    endpoints: {
+        /** MCP over streamable HTTP. The URL carries the episode's capability: it is per episode. */
+        mcp: string;
+        /** `POST` here when finished. */
+        done: string;
+    };
+}
+/** A JSON Schema for a tool's arguments: always an object. */
+export interface ToolInputSchema {
+    type: "object";
+    properties?: Record<string, unknown>;
+    required?: string[];
+    [key: string]: unknown;
+}
+/**
+ * The result of one tool call, as the Arena returns it. Failures are returned, not thrown, so the
+ * agent's model can read them and react, as it would to a production tool's error. `text` is what
+ * a model should read: the output as JSON, or the error.
+ */
+export type EpisodeToolResult = {
+    ok: true;
+    output: unknown;
+    text: string;
+} | {
+    ok: false;
+    error: string;
+    text: string;
+};
+/** One of the episode's tools, framework-neutral. */
+export interface EpisodeTool {
+    name: string;
+    description: string;
+    inputSchema: ToolInputSchema;
+    /** Calls the tool at the gateway. */
+    call(args?: Record<string, unknown>): Promise<EpisodeToolResult>;
+}
+/** Usage an agent reports at the end of an episode (recorded, never trusted for limits). */
+export type EpisodeUsage = NonNullable<DoneRequest["usage"]>;
+/** An MCP client connected to one episode, with its tools listed. */
+export interface EpisodeTools {
+    /** The official MCP SDK client, for anything not covered here. */
+    readonly client: Client;
+    /** The episode's tools, listed once at connect. */
+    readonly tools: EpisodeTool[];
+    /** MCP `tools/list`, as the server answers it. */
+    listTools(): ReturnType<Client["listTools"]>;
+    /** Calls a tool by name. */
+    callTool(name: string, args?: Record<string, unknown>): Promise<EpisodeToolResult>;
+    /** Tells the gateway the agent is finished (`POST {done}`). Later tool calls are refused. */
+    done(body?: DoneRequest): Promise<void>;
+    close(): Promise<void>;
+}
+export interface ConnectOptions {
+    /** Closes the connection when it fires (e.g. the episode's deadline). */
+    signal?: AbortSignal;
+    /** The `fetch` to use (default: the global one). */
+    fetch?: typeof fetch;
+    /** How the client names itself to the server. */
+    clientName?: string;
+}
+/**
+ * Connects to the episode's MCP endpoint and lists its tools. With no argument it reads the
+ * episode from the runner's `BONDED_*` variables (`fromBondedEnv`); in Agent URL mode pass the
+ * episode your handler received.
+ *
+ * ```ts
+ * const episode = await connectEpisodeTools();
+ * for (const tool of episode.tools) console.log(tool.name, tool.inputSchema);
+ * const prices = await episode.callTool("get_prices");
+ * await episode.done({ finalMessage: "bought tNVDA" });
+ * ```
+ */
+export declare function connectEpisodeTools(episode?: EpisodeToolsSource, options?: ConnectOptions): Promise<EpisodeTools>;
+/** The text a string-returning framework (LangChain, AgentKit) gives its model. */
+export declare function resultText(result: EpisodeToolResult): string;
+/** Tools from a connection, or a fresh connection to the episode. */
+export declare function resolveTools(from: EpisodeTools | EpisodeToolsSource | undefined): Promise<EpisodeTools>;
+/** The `mcp-remote` bridge, pinned, for MCP clients that only start local (stdio) servers. */
+export declare const MCP_REMOTE_PACKAGE = "mcp-remote@0.14.3";
+export interface McpConfigOptions {
+    /** The server's name in the config. Default `bonded-episode`. */
+    name?: string;
+    /**
+     * - `http` (default): `{ type: "http", url }`, for clients that speak streamable HTTP
+     *   (Claude Code's `.mcp.json`, Cursor's `mcp.json`, and most current agents).
+     * - `url`: `{ url }` only, for clients that infer the transport from the URL (older Cursor).
+     * - `stdio`: `npx mcp-remote <url>`, for clients that only launch local servers (Claude Desktop).
+     */
+    style?: "http" | "url" | "stdio";
+}
+export type McpServerEntry = {
+    type: "http";
+    url: string;
+} | {
+    url: string;
+} | {
+    command: string;
+    args: string[];
+};
+/**
+ * The `mcpServers` block an MCP-aware agent accepts, pointing at this episode's MCP endpoint.
+ * The URL carries the episode's capability and stops working when the episode ends, so write the
+ * config afresh for every episode (e.g. at the start of the runner's agent command):
+ *
+ * ```sh
+ * bonded-runner --command 'bonded-mcp-config > .mcp.json && my-agent --mcp-config .mcp.json'
+ * ```
+ */
+export declare function mcpConfig(episode?: {
+    endpoints: {
+        mcp: string;
+    };
+}, options?: McpConfigOptions): {
+    mcpServers: Record<string, McpServerEntry>;
+};
+/** `mcpConfig` as pretty-printed JSON, ready to write to a file. */
+export declare function mcpConfigJson(episode?: {
+    endpoints: {
+        mcp: string;
+    };
+}, options?: McpConfigOptions): string;
+//# sourceMappingURL=mcp.d.ts.map