@bondedhq/sdk 0.0.0-stage → 0.1.1

package/dist/eliza.js

@@ -0,0 +1,281 @@
+import { erc20Abi, getAddress, isAddress, parseUnits } from "viem";
+import { z } from "zod";
+import { BondedError } from "./errors.js";
+import { GuardedVault, } from "./guarded.js";
+import { SENTINEL_INPUT_CHARS } from "@bondedhq/shared";
+import { episodeVault, fromBondedEnv } from "./episode.js";
+import { isBondedEpisode, resolveTools, resultText, } from "./mcp.js";
+/** The action names this plugin adds. */
+export const BONDED_ACTIONS = ["BONDED_SWAP", "BONDED_TRANSFER", "BONDED_APPROVE"];
+const amount = z.string().regex(/^\d+(\.\d+)?$/, "a decimal amount, e.g. 250 or 12.5");
+const PARAMS = {
+    BONDED_SWAP: z.object({ tokenIn: z.string(), tokenOut: z.string(), amount }),
+    BONDED_TRANSFER: z.object({ token: z.string(), to: z.string(), amount }),
+    BONDED_APPROVE: z.object({ token: z.string(), spender: z.string(), amount }),
+};
+const DESCRIPTIONS = {
+    BONDED_SWAP: "Swap one token for another with the funds in the agent's Bonded Mandate Vault.",
+    BONDED_TRANSFER: "Send tokens from the agent's Bonded Mandate Vault to an address.",
+    BONDED_APPROVE: "Let an address spend tokens from the agent's Bonded Mandate Vault.",
+};
+const FIELDS = {
+    BONDED_SWAP: '{"tokenIn": symbol or address, "tokenOut": symbol or address, "amount": "decimal"}',
+    BONDED_TRANSFER: '{"token": symbol or address, "to": "0x address", "amount": "decimal"}',
+    BONDED_APPROVE: '{"token": symbol or address, "spender": "0x address", "amount": "decimal"}',
+};
+/**
+ * An ElizaOS plugin: `BONDED_SWAP`, `BONDED_TRANSFER` and `BONDED_APPROVE` act through the
+ * agent's Mandate Vault, and the `BONDED_VAULT` provider tells the agent the vault's state.
+ *
+ * Each action takes its parameters from `options.parameters` when the caller passes them, or
+ * asks the runtime's `OBJECT_SMALL` model to read them from the conversation. Amounts are whole
+ * tokens ("12.5"). By default each action is dry-run against the vault first and refused if the
+ * vault would record a breach; with `sentinel`, Sentinel is asked too, with the conversation as
+ * what the agent read.
+ */
+export function bondedPlugin(options) {
+    const guard = options.guard ?? true;
+    const guarded = new GuardedVault(options.vault, options.sentinel ? { sentinel: options.sentinel } : {});
+    const action = (name) => ({
+        name,
+        similes: [],
+        description: DESCRIPTIONS[name],
+        validate: async () => options.vault.walletClient !== undefined,
+        handler: async (runtime, message, state, handlerOptions, callback) => {
+            try {
+                const params = await readParams(name, runtime, message, state, handlerOptions);
+                const vaultAction = await toVaultAction(name, params, options);
+                const context = { untrustedInputs: conversation(message, state) };
+                const result = guard || options.sentinel
+                    ? await guarded.execute(vaultAction, context)
+                    : await options.vault.execute(vaultAction);
+                const text = result.breaches.length
+                    ? `Done, but the vault recorded a breach: ${result.breaches.map((b) => `${b.type} (${b.reason})`).join("; ")}. The vault may have frozen the agent.`
+                    : `Done within the mandate (${result.hashes.length} transaction${result.hashes.length === 1 ? "" : "s"}).`;
+                await callback?.({ text, actions: [name] });
+                return {
+                    success: true,
+                    text,
+                    data: {
+                        hashes: result.hashes,
+                        breaches: result.breaches.map((b) => ({
+                            ...b,
+                            id: b.id.toString(),
+                            lossUsd6: b.lossUsd6.toString(),
+                        })),
+                    },
+                };
+            }
+            catch (error) {
+                const text = `Not done: ${error instanceof Error ? error.message : String(error)}`;
+                await callback?.({ text, actions: [name] });
+                return { success: false, text, error: error instanceof Error ? error : String(error) };
+            }
+        },
+    });
+    const provider = {
+        name: "BONDED_VAULT",
+        description: "The agent's Bonded Mandate Vault: mode, frozen or not, and breaches recorded.",
+        get: async () => {
+            const status = await options.vault.status();
+            const text = (status.kind === "module"
+                ? `Funds are in smart account ${status.holder}, guarded by Bonded mandate module ${options.vault.address} (${status.mode} mode). `
+                : `Funds are in Bonded Mandate Vault ${options.vault.address} (${status.mode} mode). `) +
+                (status.frozen
+                    ? "It is frozen: no action will run until its guardian unfreezes it. "
+                    : "It is active. ") +
+                `${status.breachCount} breach${status.breachCount === 1n ? "" : "es"} recorded.`;
+            return {
+                text,
+                values: { bondedVaultFrozen: status.frozen, bondedVaultMode: status.mode },
+                data: {
+                    vault: options.vault.address,
+                    kind: status.kind,
+                    holder: status.holder,
+                    frozen: status.frozen,
+                    mode: status.mode,
+                    breachCount: status.breachCount.toString(),
+                },
+            };
+        },
+    };
+    const plugin = {
+        name: "bonded",
+        description: "Trade through a Bonded Mandate Vault, checked against the agent's mandate.",
+        actions: BONDED_ACTIONS.map(action),
+        providers: [provider],
+    };
+    if ((options.rating ?? "auto") === "auto")
+        plugin.init = async (config, runtime) => {
+            if (!isBondedEpisode())
+                return;
+            const rated = bondedEpisodePlugin({ guard });
+            await rated.init(config, runtime);
+            plugin.actions = rated.actions;
+            plugin.providers = rated.providers;
+        };
+    return plugin;
+}
+/**
+ * Rating mode for ElizaOS: a plugin whose actions are the episode's tools, so an Eliza agent is
+ * rated with the same character and model it runs in production. Each tool becomes an action
+ * named after it in capitals (`get_prices` is `GET_PRICES`); its parameters come from
+ * `options.parameters`, or the runtime's `OBJECT_SMALL` model reads them from the conversation
+ * against the tool's JSON Schema. The `BONDED_TASK` provider gives the agent the episode's task.
+ *
+ * In tools mode the writes (`SWAP`, `TRANSFER`, `APPROVE`) are tools too. In chain mode only the
+ * reads are, and the plugin adds `BONDED_SWAP`, `BONDED_TRANSFER` and `BONDED_APPROVE` on the
+ * episode vault, signed with the episode's session key (`episodeVault`).
+ *
+ * The actions are filled in by `init`, which the runtime calls when it registers the plugin
+ * (before it reads them). `bondedPlugin` does this by itself while an episode is running.
+ */
+export function bondedEpisodePlugin(options = {}) {
+    const plugin = {
+        name: "bonded-episode",
+        description: "The tools of a Bonded Arena episode.",
+        actions: [],
+        providers: [],
+        init: async () => {
+            const episode = options.episode ?? fromBondedEnv();
+            const tools = await resolveTools(options.tools ?? episode);
+            const actions = tools.tools.map(toolAction);
+            if (episode.mode === "chain" && episode.sessionKey)
+                actions.push(...bondedPlugin({
+                    vault: episodeVault(episode),
+                    tokens: episode.contracts.tokens,
+                    guard: options.guard ?? true,
+                    rating: "off",
+                }).actions);
+            plugin.actions = actions;
+            plugin.providers = [taskProvider(episode)];
+        },
+    };
+    return plugin;
+}
+/** One episode tool as an Eliza action. */
+function toolAction(t) {
+    const name = t.name.toUpperCase();
+    const takesArgs = Object.keys(t.inputSchema.properties ?? {}).length > 0;
+    return {
+        name,
+        similes: [t.name],
+        description: t.description,
+        validate: async () => true,
+        handler: async (runtime, message, state, handlerOptions, callback) => {
+            const given = handlerOptions?.parameters;
+            const args = given && typeof given === "object"
+                ? given
+                : takesArgs
+                    ? await runtime.useModel("OBJECT_SMALL", {
+                        prompt: [
+                            `Extract the parameters for ${name} (${t.description}) from the conversation.`,
+                            `Answer with JSON only, matching this JSON Schema: ${JSON.stringify(t.inputSchema)}`,
+                            "Use only values the conversation states.",
+                            "",
+                            state?.text ?? message.content.text ?? "",
+                        ].join("\n"),
+                    })
+                    : {};
+            const result = await t.call(args && typeof args === "object" ? args : {});
+            const text = resultText(result);
+            await callback?.({ text, actions: [name] });
+            return result.ok
+                ? { success: true, text, data: { tool: t.name, output: result.output } }
+                : { success: false, text, error: result.error, data: { tool: t.name } };
+        },
+    };
+}
+/** The episode's task, as the agent's current instructions. */
+function taskProvider(episode) {
+    const text = [
+        `Your task: ${episode.task.goal}`,
+        `Your mandate: ${episode.task.mandate}`,
+        `Tokens: ${episode.contracts.tokens.map((t) => t.symbol).join(", ")}.`,
+    ].join("\n");
+    return {
+        name: "BONDED_TASK",
+        description: "The task the agent is working on, and its mandate.",
+        get: async () => ({
+            text,
+            values: { bondedTaskGoal: episode.task.goal },
+            data: { episodeId: episode.episodeId, task: episode.task },
+        }),
+    };
+}
+/** The action's parameters: given by the caller, or read from the conversation by the model. */
+async function readParams(name, runtime, message, state, handlerOptions) {
+    const given = handlerOptions?.parameters;
+    const raw = given && typeof given === "object"
+        ? given
+        : await runtime.useModel("OBJECT_SMALL", {
+            prompt: [
+                `Extract the parameters for ${name} (${DESCRIPTIONS[name]}) from the conversation.`,
+                `Answer with JSON only: ${FIELDS[name]}.`,
+                "Use only values the conversation states. Amounts are in whole tokens.",
+                "",
+                state?.text ?? message.content.text ?? "",
+            ].join("\n"),
+        });
+    const parsed = PARAMS[name].safeParse(raw);
+    if (!parsed.success)
+        throw new BondedError("INVALID_ACTION", `${name} needs ${FIELDS[name]}: ${parsed.error.issues.map((i) => `${i.path.join(".")} ${i.message}`).join(", ")}`);
+    return parsed.data;
+}
+async function toVaultAction(name, params, options) {
+    const token = (value) => resolveToken(value, options);
+    const units = async (value, amount) => parseUnits(amount, (await token(value)).decimals);
+    const recipient = (field, value) => {
+        if (!isAddress(value, { strict: false }))
+            throw new BondedError("INVALID_ACTION", `${field} must be a 0x address, not "${value}"`);
+        return getAddress(value);
+    };
+    switch (name) {
+        case "BONDED_SWAP":
+            return {
+                type: "swap",
+                tokenIn: (await token(params.tokenIn)).address,
+                tokenOut: (await token(params.tokenOut)).address,
+                amountIn: await units(params.tokenIn, params.amount),
+            };
+        case "BONDED_TRANSFER":
+            return {
+                type: "transfer",
+                token: (await token(params.token)).address,
+                to: recipient("to", params.to),
+                amount: await units(params.token, params.amount),
+            };
+        case "BONDED_APPROVE":
+            return {
+                type: "approve",
+                token: (await token(params.token)).address,
+                spender: recipient("spender", params.spender),
+                amount: await units(params.token, params.amount),
+            };
+    }
+}
+/** A configured token by symbol (any case) or address; an unknown address's decimals are read. */
+async function resolveToken(value, options) {
+    const tokens = options.tokens ?? [];
+    const known = tokens.find((t) => t.symbol.toLowerCase() === value.toLowerCase() ||
+        t.address.toLowerCase() === value.toLowerCase());
+    if (known)
+        return known;
+    if (!isAddress(value, { strict: false }))
+        throw new BondedError("INVALID_ACTION", `unknown token "${value}"; use one of ${tokens.map((t) => t.symbol).join(", ") || "the configured tokens"} or a token address`);
+    const address = getAddress(value);
+    const decimals = await options.vault.publicClient.readContract({
+        address,
+        abi: erc20Abi,
+        functionName: "decimals",
+    });
+    return { symbol: address, address, decimals };
+}
+/** What the agent read before acting: the message and recent conversation, for Sentinel. */
+function conversation(message, state) {
+    const inputs = [{ tool: "message", output: message.content.text ?? "" }];
+    if (state?.text)
+        inputs.push({ tool: "conversation", output: state.text.slice(-SENTINEL_INPUT_CHARS) });
+    return inputs.filter((i) => i.output.length > 0);
+}
+//# sourceMappingURL=eliza.js.map

package/dist/episode.d.ts

@@ -0,0 +1,108 @@
+import { type AgentTask } from "@bondedhq/shared";
+import { type Address, type Hex } from "viem";
+import type { TokenInfo } from "./guarded.js";
+import { BondedVault } from "./vault.js";
+/**
+ * An Arena episode, as the Bonded runner hands it to an agent it launches: the task, where the
+ * episode's tools are, and in chain mode a fork RPC and the key to sign with. The agent acts
+ * exactly as in production, against these endpoints, and the Arena judges it by the episode
+ * vault's breach log.
+ */
+export interface BondedEpisode {
+    episodeId: string;
+    task: AgentTask;
+    /** tools: writes are the `swap`/`transfer`/`approve` tools. chain: writes are signed `execute` txs to `endpoints.rpc`. */
+    mode: "tools" | "chain";
+    endpoints: {
+        /** MCP over streamable HTTP. */
+        mcp: string;
+        /** Plain HTTP: `GET {tools}` lists them, `POST {tools}/{name}` with JSON args calls one. */
+        tools: string;
+        openapi: string;
+        /** `POST` here when finished (`{ finalMessage? }`). */
+        done: string;
+        /** Chain mode: the episode's fork. Only signed `execute` calls to the episode vault are accepted. */
+        rpc?: string;
+    };
+    vault: Address;
+    chainId: number;
+    /** The episode's market: the exchange (swap router) and the tokens the agent can trade. */
+    contracts: {
+        exchange: Address;
+        tokens: TokenInfo[];
+    };
+    /** Chain mode: the episode's agent key. Absent when the agent's key lives in a TEE. */
+    sessionKey?: Hex;
+    /** How long the agent has, in milliseconds from when it starts. */
+    deadlineMs: number;
+}
+/**
+ * The BONDED_* variables the runner sets for each episode. The schema lives in @bondedhq/shared,
+ * next to `episodeEnv` that writes them, so the runner, the gateway and the SDK can't drift.
+ */
+export declare const bondedEpisodeEnv: import("zod").ZodObject<{
+    BONDED_EPISODE_ID: import("zod").ZodString;
+    BONDED_MODE: import("zod").ZodEnum<{
+        tools: "tools";
+        chain: "chain";
+    }>;
+    BONDED_TASK: import("zod").ZodPipe<import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<unknown, string>>, import("zod").ZodObject<{
+        goal: import("zod").ZodString;
+        mandate: import("zod").ZodString;
+        policy: import("zod").ZodOptional<import("zod").ZodObject<{
+            tokens: import("zod").ZodArray<import("zod").ZodString>;
+            maxTradeUsd: import("zod").ZodNumber;
+            maxDailyUsd: import("zod").ZodNumber;
+            transferAllowlist: import("zod").ZodArray<import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<`0x${string}`, string>>>;
+            approvalAllowlist: import("zod").ZodArray<import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<`0x${string}`, string>>>;
+        }, import("zod/v4/core").$strip>>;
+        maxSteps: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>>;
+    BONDED_MCP_URL: import("zod").ZodURL;
+    BONDED_TOOLS_URL: import("zod").ZodURL;
+    BONDED_OPENAPI_URL: import("zod").ZodURL;
+    BONDED_DONE_URL: import("zod").ZodURL;
+    BONDED_RPC_URL: import("zod").ZodOptional<import("zod").ZodURL>;
+    BONDED_SESSION_KEY: import("zod").ZodOptional<import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<`0x${string}`, string>>>;
+    BONDED_TEE_KEY_ID: import("zod").ZodOptional<import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<`0x${string}`, string>>>;
+    BONDED_VAULT: import("zod").ZodPipe<import("zod").ZodString & import("zod").ZodType<`0x${string}`, string, import("zod/v4/core").$ZodTypeInternals<`0x${string}`, string>>, import("zod").ZodTransform<`0x${string}`, `0x${string}`>>;
+    BONDED_CHAIN_ID: import("zod").ZodCoercedNumber<unknown>;
+    BONDED_CONTRACTS: import("zod").ZodPipe<import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<unknown, string>>, import("zod").ZodObject<{
+        tokens: import("zod").ZodArray<import("zod").ZodObject<{
+            symbol: import("zod").ZodString;
+            address: import("zod").ZodPipe<import("zod").ZodString & import("zod").ZodType<`0x${string}`, string, import("zod/v4/core").$ZodTypeInternals<`0x${string}`, string>>, import("zod").ZodTransform<`0x${string}`, `0x${string}`>>;
+            decimals: import("zod").ZodNumber;
+        }, import("zod/v4/core").$strip>>;
+        exchange: import("zod").ZodPipe<import("zod").ZodString & import("zod").ZodType<`0x${string}`, string, import("zod/v4/core").$ZodTypeInternals<`0x${string}`, string>>, import("zod").ZodTransform<`0x${string}`, `0x${string}`>>;
+    }, import("zod/v4/core").$strip>>;
+    BONDED_DEADLINE_MS: import("zod").ZodCoercedNumber<unknown>;
+}, import("zod/v4/core").$strip>;
+/**
+ * Whether this process is running a Bonded episode: the runner set valid `BONDED_*` variables.
+ * Lets an agent pick the episode's tools when it is being rated and its own otherwise:
+ *
+ * ```ts
+ * const tools = isBondedEpisode() ? await bondedLangChainTools() : productionTools;
+ * ```
+ */
+export declare function isBondedEpisode(env?: Record<string, string | undefined>): boolean;
+/**
+ * Reads the episode the Bonded runner set up from the environment. Throws `BondedError`
+ * (`EPISODE_ENV`) naming every missing or malformed variable.
+ *
+ * ```ts
+ * const episode = fromBondedEnv();
+ * if (episode.mode === "chain") {
+ *   const vault = new BondedVault({ vault: episode.vault, rpcUrl: episode.endpoints.rpc, ... });
+ * }
+ * ```
+ */
+export declare function fromBondedEnv(env?: Record<string, string | undefined>): BondedEpisode;
+/**
+ * Chain mode: the episode vault as a `BondedVault`, signing with the episode's session key
+ * through the episode's fork RPC, and swapping on the episode's exchange. Writes are then signed
+ * `execute` calls, exactly as in production. Throws `BondedError` (`EPISODE_MODE`) in tools mode
+ * or when the key is held by a TEE (no session key): use your own signer there.
+ */
+export declare function episodeVault(episode: BondedEpisode): BondedVault;
+//# sourceMappingURL=episode.d.ts.map

package/dist/episode.js

@@ -0,0 +1,65 @@
+import { EpisodeEnv, parseEpisodeEnv } from "@bondedhq/shared";
+import { defineChain } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { BondedError } from "./errors.js";
+import { BondedVault } from "./vault.js";
+/**
+ * The BONDED_* variables the runner sets for each episode. The schema lives in @bondedhq/shared,
+ * next to `episodeEnv` that writes them, so the runner, the gateway and the SDK can't drift.
+ */
+export const bondedEpisodeEnv = EpisodeEnv;
+/**
+ * Whether this process is running a Bonded episode: the runner set valid `BONDED_*` variables.
+ * Lets an agent pick the episode's tools when it is being rated and its own otherwise:
+ *
+ * ```ts
+ * const tools = isBondedEpisode() ? await bondedLangChainTools() : productionTools;
+ * ```
+ */
+export function isBondedEpisode(env = typeof process === "undefined" ? {} : process.env) {
+    return parseEpisodeEnv(env).ok;
+}
+/**
+ * Reads the episode the Bonded runner set up from the environment. Throws `BondedError`
+ * (`EPISODE_ENV`) naming every missing or malformed variable.
+ *
+ * ```ts
+ * const episode = fromBondedEnv();
+ * if (episode.mode === "chain") {
+ *   const vault = new BondedVault({ vault: episode.vault, rpcUrl: episode.endpoints.rpc, ... });
+ * }
+ * ```
+ */
+export function fromBondedEnv(env = process.env) {
+    const parsed = parseEpisodeEnv(env);
+    if (!parsed.ok)
+        throw new BondedError("EPISODE_ENV", `not a valid Bonded episode environment: ${parsed.problems.join("; ")}`);
+    const { contracts, ...episode } = parsed.episode;
+    return { ...episode, contracts: { exchange: contracts.exchange, tokens: contracts.tokens } };
+}
+/**
+ * Chain mode: the episode vault as a `BondedVault`, signing with the episode's session key
+ * through the episode's fork RPC, and swapping on the episode's exchange. Writes are then signed
+ * `execute` calls, exactly as in production. Throws `BondedError` (`EPISODE_MODE`) in tools mode
+ * or when the key is held by a TEE (no session key): use your own signer there.
+ */
+export function episodeVault(episode) {
+    const rpc = episode.endpoints.rpc;
+    if (episode.mode !== "chain" || !rpc)
+        throw new BondedError("EPISODE_MODE", "only a chain-mode episode has a vault to sign for; in tools mode, writes are tool calls");
+    if (!episode.sessionKey)
+        throw new BondedError("EPISODE_MODE", "this episode has no session key (the agent's key is in a TEE); build a BondedVault with your own signer");
+    return new BondedVault({
+        vault: episode.vault,
+        chain: defineChain({
+            id: episode.chainId,
+            name: `Bonded episode ${episode.episodeId}`,
+            nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+            rpcUrls: { default: { http: [rpc] } },
+        }),
+        rpcUrl: rpc,
+        account: privateKeyToAccount(episode.sessionKey),
+        router: episode.contracts.exchange,
+    });
+}
+//# sourceMappingURL=episode.js.map

package/dist/errors.d.ts

@@ -0,0 +1,93 @@
+import type { Hex } from "viem";
+import type { DryRunResult, VaultBreach } from "./breaches.js";
+/** Base class for every error the SDK throws on purpose. `code` is stable; messages may change. */
+export declare class BondedError extends Error {
+    readonly code: string;
+    readonly name: string;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The signing key isn't the vault's agent key: only that key can call `execute`. */
+export declare class NotAgentError extends BondedError {
+    readonly vault: Hex;
+    readonly signer: Hex | undefined;
+    readonly name = "NotAgentError";
+    constructor(vault: Hex, signer: Hex | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The vault is frozen: its guardian froze it, or a breach did (freeze on breach). Nothing the
+ * agent sends will run until the guardian unfreezes it.
+ */
+export declare class VaultFrozenError extends BondedError {
+    readonly vault: Hex;
+    /** Set when this action froze it: the vault found an earlier unexplained outflow first. */
+    readonly breach?: VaultBreach | undefined;
+    /** The transaction that froze it, when this action did. */
+    readonly hash?: Hex | undefined;
+    readonly name = "VaultFrozenError";
+    constructor(vault: Hex, 
+    /** Set when this action froze it: the vault found an earlier unexplained outflow first. */
+    breach?: VaultBreach | undefined, 
+    /** The transaction that froze it, when this action did. */
+    hash?: Hex | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/** Enforce mode stopped the action: the vault recorded the attempt as a breach and moved nothing. */
+export declare class BlockedByMandateError extends BondedError {
+    readonly breach: VaultBreach;
+    readonly hash: Hex;
+    readonly name = "BlockedByMandateError";
+    constructor(breach: VaultBreach, hash: Hex);
+}
+/** A guarded vault refused to send an action because its dry run predicts a breach. */
+export declare class PredictedBreachError extends BondedError {
+    readonly dryRun: DryRunResult;
+    readonly name = "PredictedBreachError";
+    constructor(dryRun: DryRunResult);
+}
+/** Sentinel's answer for a proposed action, as `POST /sentinel/check` returns it. */
+export interface SentinelVerdict {
+    /** True when Sentinel advises against the action (manipulated at or above the threshold). */
+    blocked: boolean;
+    /** How strongly the action looks driven by the untrusted inputs, 0 to 1. */
+    manipulated: number;
+    /** How strongly the inputs look like they contain instructions for the agent, 0 to 1. */
+    injection: number;
+    blockThreshold: number;
+    model: string;
+    latencyMs: number;
+    advice: string;
+}
+/** A guarded vault refused an action because Sentinel advised against it. */
+export declare class SentinelRefusedError extends BondedError {
+    readonly verdict: SentinelVerdict;
+    readonly name = "SentinelRefusedError";
+    constructor(verdict: SentinelVerdict);
+}
+/** The Sentinel API didn't give an answer: refused the request, was busy, or couldn't be reached. */
+export declare class SentinelError extends BondedError {
+    /** HTTP status, when the API answered. */
+    readonly status?: number | undefined;
+    readonly name = "SentinelError";
+    constructor(message: string, 
+    /** HTTP status, when the API answered. */
+    status?: number | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/** The call the agent asked the vault to make reverted (e.g. not enough balance). Nothing changed. */
+export declare class CallRevertedError extends BondedError {
+    /** The revert data, when the node returned it. */
+    readonly data?: Hex | undefined;
+    readonly name = "CallRevertedError";
+    constructor(message: string, 
+    /** The revert data, when the node returned it. */
+    data?: Hex | undefined, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,97 @@
+/** Base class for every error the SDK throws on purpose. `code` is stable; messages may change. */
+export class BondedError extends Error {
+    code;
+    name = "BondedError";
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+/** The signing key isn't the vault's agent key: only that key can call `execute`. */
+export class NotAgentError extends BondedError {
+    vault;
+    signer;
+    name = "NotAgentError";
+    constructor(vault, signer, options) {
+        super("NOT_AGENT", `${signer ?? "this account"} is not the agent key of vault ${vault}; only the vault's agent can act through it`, options);
+        this.vault = vault;
+        this.signer = signer;
+    }
+}
+/**
+ * The vault is frozen: its guardian froze it, or a breach did (freeze on breach). Nothing the
+ * agent sends will run until the guardian unfreezes it.
+ */
+export class VaultFrozenError extends BondedError {
+    vault;
+    breach;
+    hash;
+    name = "VaultFrozenError";
+    constructor(vault, 
+    /** Set when this action froze it: the vault found an earlier unexplained outflow first. */
+    breach, 
+    /** The transaction that froze it, when this action did. */
+    hash, options) {
+        super("VAULT_FROZEN", breach
+            ? `vault ${vault} froze before acting: it found an earlier outflow it couldn't explain (breach ${breach.id})`
+            : `vault ${vault} is frozen; its guardian has to unfreeze it`, options);
+        this.vault = vault;
+        this.breach = breach;
+        this.hash = hash;
+    }
+}
+/** Enforce mode stopped the action: the vault recorded the attempt as a breach and moved nothing. */
+export class BlockedByMandateError extends BondedError {
+    breach;
+    hash;
+    name = "BlockedByMandateError";
+    constructor(breach, hash) {
+        super("BLOCKED_BY_MANDATE", `the vault blocked this action (${breach.type}): ${breach.reason}. The attempt is recorded as breach ${breach.id}`);
+        this.breach = breach;
+        this.hash = hash;
+    }
+}
+/** A guarded vault refused to send an action because its dry run predicts a breach. */
+export class PredictedBreachError extends BondedError {
+    dryRun;
+    name = "PredictedBreachError";
+    constructor(dryRun) {
+        const breach = dryRun.breach;
+        super("PREDICTED_BREACH", breach
+            ? `refused: the vault would record a breach (${breach.type}): ${breach.reason}`
+            : "refused: the vault would not run this action");
+        this.dryRun = dryRun;
+    }
+}
+/** A guarded vault refused an action because Sentinel advised against it. */
+export class SentinelRefusedError extends BondedError {
+    verdict;
+    name = "SentinelRefusedError";
+    constructor(verdict) {
+        super("SENTINEL_REFUSED", `refused on Sentinel's advice (manipulated ${verdict.manipulated.toFixed(2)} ≥ ${verdict.blockThreshold}): ${verdict.advice}`);
+        this.verdict = verdict;
+    }
+}
+/** The Sentinel API didn't give an answer: refused the request, was busy, or couldn't be reached. */
+export class SentinelError extends BondedError {
+    status;
+    name = "SentinelError";
+    constructor(message, 
+    /** HTTP status, when the API answered. */
+    status, options) {
+        super("SENTINEL_ERROR", message, options);
+        this.status = status;
+    }
+}
+/** The call the agent asked the vault to make reverted (e.g. not enough balance). Nothing changed. */
+export class CallRevertedError extends BondedError {
+    data;
+    name = "CallRevertedError";
+    constructor(message, 
+    /** The revert data, when the node returned it. */
+    data, options) {
+        super("CALL_REVERTED", message, options);
+        this.data = data;
+    }
+}
+//# sourceMappingURL=errors.js.map