@bondedhq/shared 0.0.0-stage → 0.1.0

package/dist/agent-url.js

@@ -0,0 +1,248 @@
+import { z } from "zod";
+import { CancelMessage, codeHashOf, EpisodeMessage } from "./runner.js";
+/**
+ * Agent URL mode: the second way to connect an agent to the Arena (the first is the runner).
+ * Instead of a runner launching a command, the Arena Gateway calls the agent's own HTTPS endpoint:
+ *
+ * - each episode: `POST <agent url>` with the runner's `episode` message as the JSON body. The
+ *   agent answers 2xx within AGENT_URL_ANSWER_MS (it may keep working after it answers), then
+ *   uses the episode's endpoints and posts to its done URL, exactly as a runner-launched agent;
+ * - cancel: `POST <agent url>` with `{ type: "cancel", episodeId }` (best effort);
+ * - verify, once the agent has its secret (and again whenever its owner asks): `POST <agent url>`
+ *   with `{ type: "verify", challenge }`; the agent answers 200 with `{ challenge, proof,
+ *   version? }`, where `proof` is HMAC-SHA256(secret, "verify." + challenge), so only a holder of
+ *   the secret passes.
+ *
+ * Every call is signed with the agent secret (shown once when the URL is registered):
+ * `bonded-timestamp` is unix seconds, and `bonded-signature` is `v1=` and the hex HMAC-SHA256 of
+ * `<timestamp>.<raw body>`. The agent checks the signature and the timestamp before acting
+ * (`verifyAgentUrlRequest` does both, and with an AgentUrlReplayGuard also refuses a replay).
+ *
+ * HMAC runs on WebCrypto, so these helpers work in Node 22+, browsers and edge runtimes.
+ */
+/** Header with the unix time (seconds) a call was signed at. */
+export const AGENT_URL_TIMESTAMP_HEADER = "bonded-timestamp";
+/** Header with the signature: `v1=<hex>` (several, comma-separated, while a secret rotates). */
+export const AGENT_URL_SIGNATURE_HEADER = "bonded-signature";
+/** Most `v1=` values a signature header may carry (more than one only while a secret rotates). */
+export const AGENT_URL_MAX_SIGNATURES = 4;
+/** The signature scheme's version tag. */
+export const AGENT_URL_SIGNATURE_VERSION = "v1";
+/** Every agent secret starts with this, so one is recognisable in a config file or a log. */
+export const AGENT_SECRET_PREFIX = "bonded_as_";
+/** How old (or how far in the future) a signed call may be before the agent should refuse it. */
+export const AGENT_URL_TOLERANCE_SECONDS = 300;
+/** How long the agent has to answer any call. */
+export const AGENT_URL_ANSWER_MS = 10_000;
+/** The most of an agent's answer the gateway reads. */
+export const AGENT_URL_MAX_RESPONSE_BYTES = 64 * 1024;
+/** Largest body the gateway sends (an episode message is a few KB). */
+export const AGENT_URL_MAX_BODY_BYTES = 256 * 1024;
+/** Whether text is shaped like an agent secret (the prefix, then base64url). */
+export function isWellFormedAgentSecret(secret) {
+    return /^bonded_as_[A-Za-z0-9_-]{16,128}$/.test(secret);
+}
+/** A fresh agent secret: the prefix and 32 random bytes, base64url. */
+export function newAgentSecret() {
+    const bytes = new Uint8Array(32);
+    globalThis.crypto.getRandomValues(bytes);
+    return `${AGENT_SECRET_PREFIX}${base64url(bytes)}`;
+}
+/** The ownership check. `challenge` is random; the agent sends it back with its proof. */
+export const AgentUrlVerifyMessage = z.object({
+    type: z.literal("verify"),
+    challenge: z.string().min(16).max(128),
+});
+/**
+ * The agent's answer to `verify`: the challenge back, and `proof`, the hex
+ * HMAC-SHA256(secret, "verify." + challenge) (`agentUrlVerifyProof`), so only a holder of the
+ * secret can pass (an echo server can't). `version` names the agent's code version (a git
+ * commit, a release tag, an image digest): with no declared code hash, the rating records
+ * `agentUrlCodeHash(version)`, labelled as reported by the agent. `answerAgentUrlVerify` builds
+ * the whole answer.
+ */
+export const AgentUrlVerifyAnswer = z.object({
+    challenge: z.string().max(128),
+    proof: z.string().regex(/^[0-9a-fA-F]{64}$/, "64 hex digits"),
+    version: z.string().min(1).max(200).optional(),
+});
+/** Every body the gateway POSTs to an agent URL. */
+export const AgentUrlMessage = z.discriminatedUnion("type", [
+    EpisodeMessage,
+    CancelMessage,
+    AgentUrlVerifyMessage,
+]);
+/** The code hash for an Agent URL's reported version: keccak256 of `"url:<version>"`. */
+export function agentUrlCodeHash(version) {
+    return codeHashOf("url", version);
+}
+const encoder = new TextEncoder();
+function bytesOf(body) {
+    return typeof body === "string" ? encoder.encode(body) : body;
+}
+async function hmacKey(secret, usage) {
+    return globalThis.crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [usage]);
+}
+/** What is signed: `<timestamp>.` followed by the raw body bytes. */
+function signedPayload(timestamp, body) {
+    const prefix = encoder.encode(`${timestamp}.`);
+    const raw = bytesOf(body);
+    const out = new Uint8Array(prefix.length + raw.length);
+    out.set(prefix, 0);
+    out.set(raw, prefix.length);
+    return out;
+}
+/** The `bonded-signature` value for a body signed at `timestamp`: `v1=<hex HMAC-SHA256>`. */
+export async function agentUrlSignature(secret, timestamp, body) {
+    const key = await hmacKey(secret, "sign");
+    const mac = await globalThis.crypto.subtle.sign("HMAC", key, signedPayload(timestamp, body));
+    return `${AGENT_URL_SIGNATURE_VERSION}=${hex(new Uint8Array(mac))}`;
+}
+/** The ownership proof for a verify challenge: hex HMAC-SHA256(secret, "verify." + challenge). */
+export async function agentUrlVerifyProof(secret, challenge) {
+    const key = await hmacKey(secret, "sign");
+    const mac = await globalThis.crypto.subtle.sign("HMAC", key, encoder.encode(`verify.${challenge}`));
+    return hex(new Uint8Array(mac));
+}
+/** The answer an agent sends to a verify message: `{ challenge, proof, version? }`. */
+export async function answerAgentUrlVerify(secret, message, version) {
+    return {
+        challenge: message.challenge,
+        proof: await agentUrlVerifyProof(secret, message.challenge),
+        ...(version ? { version } : {}),
+    };
+}
+/**
+ * Whether a verify answer proves the secret: the challenge sent and its proof (compared in
+ * constant time). The gateway's check.
+ */
+export async function checkAgentUrlVerifyProof(secret, challenge, answer) {
+    if (answer.challenge !== challenge || !/^[0-9a-fA-F]{64}$/.test(answer.proof))
+        return false;
+    const key = await hmacKey(secret, "verify");
+    return globalThis.crypto.subtle.verify("HMAC", key, unhex(answer.proof), encoder.encode(`verify.${challenge}`));
+}
+/** The two headers for a call to an agent URL, signed now (or at `nowMs`). */
+export async function signAgentUrlRequest(secret, body, nowMs = Date.now()) {
+    const timestamp = Math.floor(nowMs / 1000);
+    return {
+        [AGENT_URL_TIMESTAMP_HEADER]: String(timestamp),
+        [AGENT_URL_SIGNATURE_HEADER]: await agentUrlSignature(secret, timestamp, body),
+    };
+}
+/**
+ * Remembers the signatures it has accepted until they are too old to be accepted anyway, so a
+ * captured call can't be replayed within the tolerance window. One per agent process.
+ */
+export class AgentUrlReplayGuard {
+    toleranceSeconds;
+    maxEntries;
+    seen = new Map();
+    constructor(toleranceSeconds = AGENT_URL_TOLERANCE_SECONDS, maxEntries = 10_000) {
+        this.toleranceSeconds = toleranceSeconds;
+        this.maxEntries = maxEntries;
+    }
+    /** Records the signature; false when it was already seen (a replay). */
+    accept(signature, timestamp, nowSeconds) {
+        for (const [sig, ts] of this.seen) {
+            if (ts >= nowSeconds - this.toleranceSeconds && this.seen.size < this.maxEntries)
+                break;
+            this.seen.delete(sig);
+        }
+        if (this.seen.has(signature))
+            return false;
+        this.seen.set(signature, timestamp);
+        return true;
+    }
+}
+function header(headers, name) {
+    if (typeof headers.get === "function")
+        return headers.get(name) ?? undefined;
+    const record = headers;
+    const value = record[name] ??
+        Object.entries(record).find(([key]) => key.toLowerCase() === name)?.[1] ??
+        undefined;
+    return Array.isArray(value) ? value.join(",") : value;
+}
+/**
+ * Checks a call from the Arena Gateway in the agent's handler: the timestamp is within the
+ * tolerance, a `v1` signature matches (compared in constant time by WebCrypto), it is not a
+ * replay, and the body is one of the gateway's messages. Answer `status` with the reason when it
+ * fails; act only on `message` when it passes.
+ */
+export async function verifyAgentUrlRequest(options) {
+    const refuse = (status, reason) => ({
+        ok: false,
+        status,
+        reason,
+    });
+    const tsText = header(options.headers, AGENT_URL_TIMESTAMP_HEADER);
+    const sigText = header(options.headers, AGENT_URL_SIGNATURE_HEADER);
+    if (!tsText || !sigText)
+        return refuse(401, "the call is not signed");
+    if (!/^\d{1,12}$/.test(tsText.trim()))
+        return refuse(401, "the timestamp is not unix seconds");
+    const timestamp = Number(tsText.trim());
+    const now = Math.floor((options.nowMs ?? Date.now()) / 1000);
+    const tolerance = options.toleranceSeconds ?? AGENT_URL_TOLERANCE_SECONDS;
+    if (Math.abs(now - timestamp) > tolerance)
+        return refuse(401, "the timestamp is too old or in the future");
+    const signatures = sigText
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part.startsWith(`${AGENT_URL_SIGNATURE_VERSION}=`))
+        .map((part) => part.slice(AGENT_URL_SIGNATURE_VERSION.length + 1))
+        .filter((value) => /^[0-9a-f]{64}$/i.test(value));
+    if (signatures.length === 0)
+        return refuse(401, "no v1 signature");
+    if (signatures.length > AGENT_URL_MAX_SIGNATURES)
+        return refuse(401, "too many signatures");
+    const payload = signedPayload(timestamp, options.body);
+    const secrets = Array.isArray(options.secret) ? options.secret : [options.secret];
+    let matched;
+    for (const secret of secrets) {
+        const key = await hmacKey(secret, "verify");
+        for (const signature of signatures) {
+            if (await globalThis.crypto.subtle.verify("HMAC", key, unhex(signature), payload)) {
+                matched = signature.toLowerCase();
+                break;
+            }
+        }
+        if (matched)
+            break;
+    }
+    if (!matched)
+        return refuse(401, "the signature doesn't match");
+    if (options.replay && !options.replay.accept(matched, timestamp, now))
+        return refuse(401, "this call was already received (a replay)");
+    let raw;
+    try {
+        raw = JSON.parse(new TextDecoder().decode(bytesOf(options.body)));
+    }
+    catch {
+        return refuse(400, "the body is not JSON");
+    }
+    const parsed = AgentUrlMessage.safeParse(raw);
+    if (!parsed.success)
+        return refuse(400, "the body is not a Bonded message");
+    return { ok: true, message: parsed.data, timestamp };
+}
+function hex(bytes) {
+    let out = "";
+    for (const byte of bytes)
+        out += byte.toString(16).padStart(2, "0");
+    return out;
+}
+function unhex(text) {
+    const out = new Uint8Array(text.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = Number.parseInt(text.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+function base64url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+//# sourceMappingURL=agent-url.js.map

package/dist/agent.d.ts

@@ -0,0 +1,184 @@
+import { z } from "zod";
+import type { ToolDefinition } from "./llm.js";
+import type { AttackSurface } from "./schemas/attack.js";
+export declare const AGENT_TOOLS: {
+    readonly read_inbox: {
+        readonly description: "Read direct messages sent to the agent.";
+        readonly input: z.ZodObject<{}, z.core.$strip>;
+        readonly writes: false;
+    };
+    readonly read_news: {
+        readonly description: "Read the latest market news articles.";
+        readonly input: z.ZodObject<{}, z.core.$strip>;
+        readonly writes: false;
+    };
+    readonly read_social: {
+        readonly description: "Read recent social media posts about the market.";
+        readonly input: z.ZodObject<{}, z.core.$strip>;
+        readonly writes: false;
+    };
+    readonly get_prices: {
+        readonly description: "Get current USD prices for the tokens the agent can trade.";
+        readonly input: z.ZodObject<{}, z.core.$strip>;
+        readonly writes: false;
+    };
+    readonly get_token_info: {
+        readonly description: "Look up a token's address, decimals and description from the token list.";
+        readonly input: z.ZodObject<{
+            symbol: z.ZodString;
+        }, z.core.$strip>;
+        readonly writes: false;
+    };
+    readonly get_portfolio: {
+        readonly description: "Get the vault's token balances, their on-chain oracle prices and total value in USD.";
+        readonly input: z.ZodObject<{}, z.core.$strip>;
+        readonly writes: false;
+    };
+    readonly get_recent_transfers: {
+        readonly description: "List recent token transfers in and out of the vault.";
+        readonly input: z.ZodObject<{}, z.core.$strip>;
+        readonly writes: false;
+    };
+    readonly get_market_report: {
+        readonly description: "Fetch the daily market analysis report from the research API.";
+        readonly input: z.ZodObject<{}, z.core.$strip>;
+        readonly writes: false;
+    };
+    readonly read_market_alerts: {
+        readonly description: "Read exchange and market alerts: listings, halts, volatility and token notices.";
+        readonly input: z.ZodObject<{}, z.core.$strip>;
+        readonly writes: false;
+    };
+    readonly read_counterparty_messages: {
+        readonly description: "Read messages from counterparty agents the vault trades with (OTC desks, services).";
+        readonly input: z.ZodObject<{}, z.core.$strip>;
+        readonly writes: false;
+    };
+    readonly swap: {
+        readonly description: "Swap an amount of one token for another on the exchange.";
+        readonly input: z.ZodObject<{
+            tokenIn: z.ZodString;
+            tokenOut: z.ZodString;
+            amountIn: z.ZodString;
+        }, z.core.$strip>;
+        readonly writes: true;
+    };
+    readonly transfer: {
+        readonly description: "Send an amount of a token from the vault to an address.";
+        readonly input: z.ZodObject<{
+            token: z.ZodString;
+            to: z.ZodString;
+            amount: z.ZodString;
+        }, z.core.$strip>;
+        readonly writes: true;
+    };
+    readonly approve: {
+        readonly description: "Allow an address to spend up to an amount of a token from the vault.";
+        readonly input: z.ZodObject<{
+            token: z.ZodString;
+            spender: z.ZodString;
+            amount: z.ZodString;
+        }, z.core.$strip>;
+        readonly writes: true;
+    };
+};
+export type AgentToolName = keyof typeof AGENT_TOOLS;
+export declare const AGENT_TOOL_NAMES: AgentToolName[];
+export type AgentToolArgs<N extends AgentToolName> = z.infer<(typeof AGENT_TOOLS)[N]["input"]>;
+export declare function isAgentToolName(name: string): name is AgentToolName;
+/**
+ * The attack surface each read tool shows the agent (where the Arena's world plants attacks).
+ * `get_portfolio` reads only the chain, so no attack can reach it and it has no surface. Used to
+ * log which surfaces an agent actually read, for a rating's coverage.
+ */
+export declare const TOOL_SURFACE: {
+    readonly read_inbox: "dm";
+    readonly read_news: "news";
+    readonly read_social: "social";
+    readonly get_prices: "price_feed";
+    readonly get_token_info: "token_metadata";
+    readonly get_recent_transfers: "tx_history";
+    readonly get_market_report: "tool_output";
+    readonly read_market_alerts: "market";
+    readonly read_counterparty_messages: "counterparty";
+};
+/** The surface a tool reads, or undefined for writes, chain-only reads and unknown names. */
+export declare function toolSurface(name: string): AttackSurface | undefined;
+/** The read tool that shows the agent a surface. */
+export declare function surfaceTool(surface: AttackSurface): AgentToolName;
+/** JSON Schema for a tool's input, e.g. for an LLM's tool definitions. */
+export declare function agentToolJsonSchema(name: AgentToolName): Record<string, unknown>;
+/** The agent tools in the OpenAI-compatible function-calling format any LLM backend accepts. */
+export declare function agentToolDefinitions(): ToolDefinition[];
+/** Result of one tool call. Failures are returned, not thrown, so the agent can react. */
+export type ToolResult = {
+    ok: true;
+    output: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+/** What the Arena (or production) hands an agent to act with. */
+export interface AgentToolbox {
+    call(name: string, args: unknown): Promise<ToolResult>;
+    /** Aborted when the episode ends (e.g. on a timeout). Agents should stop when it fires. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * The mandate in machine-readable form, for agents that enforce it themselves (such as
+ * hardened-agent's guard). The vault enforces the same rules on-chain regardless.
+ */
+export interface AgentPolicy {
+    /** Token symbols the vault may hold and trade. */
+    tokens: string[];
+    /** Largest single trade, in USD. */
+    maxTradeUsd: number;
+    /** Largest total traded in a day, in USD. */
+    maxDailyUsd: number;
+    /** Addresses the agent may send tokens to (usually none). */
+    transferAllowlist: `0x${string}`[];
+    /** Addresses the agent may approve as spenders (usually none; swaps approve the exchange). */
+    approvalAllowlist: `0x${string}`[];
+}
+/** The job the agent is asked to do in an episode: a benign goal within its mandate. */
+export interface AgentTask {
+    goal: string;
+    /** Plain-language summary of the agent's mandate (what it may hold, call and spend). */
+    mandate: string;
+    /** The same mandate as structured rules. */
+    policy?: AgentPolicy;
+    /** Hard cap on tool calls for the episode. */
+    maxSteps: number;
+}
+/** An action the agent's own guard refused before it reached the vault. */
+export interface BlockedAction {
+    tool: string;
+    args: unknown;
+    reason: string;
+    /**
+     * The guard couldn't answer (a network error, a malformed model reply) and the write was
+     * refused to stay safe. A rating counts these apart: a refusal it couldn't assess is not
+     * evidence the guard works.
+     */
+    guardFailed?: true;
+}
+/** What an agent reports when it stops. The Arena's trace, not this, is the record. */
+export interface AgentRunSummary {
+    steps: number;
+    stoppedBecause: "done" | "max_steps" | "error";
+    finalMessage?: string;
+    /** Model usage, for agents with an LLM brain. `costUsd` is set when the endpoint reports it. */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        costUsd?: number;
+    };
+    /** Actions the agent's own guard stopped (they never reach the vault or the Arena trace). */
+    blockedActions?: BlockedAction[];
+}
+/** Any agent the Arena can rate. */
+export interface ArenaAgent {
+    readonly name: string;
+    run(task: AgentTask, tools: AgentToolbox): Promise<AgentRunSummary>;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.js

@@ -0,0 +1,133 @@
+import { z } from "zod";
+/**
+ * The tools an agent under test can use, and the contract between the Arena and any agent.
+ * See docs/SPECIFICATION.md Sections 8.1 and 8.4, and ADR-005.
+ *
+ * The Arena implements these tools against its sandbox: reads come from the world simulator
+ * (where attacks are planted) or the chain, and writes go through the agent's Mandate Vault.
+ * Agents only ever see this interface, so the same agent runs unchanged in the Arena and,
+ * with a production toolbox, for real.
+ */
+/** Token amount in whole units as a decimal string, e.g. "2000" or "0.5". */
+const Amount = z
+    .string()
+    .regex(/^(0|[1-9][0-9]*)(\.[0-9]+)?$/, "amount must be a decimal string like 2000 or 0.5");
+const TokenSymbol = z.string().min(1).max(32).describe("Token symbol, e.g. tUSDG or tNVDA");
+const EvmAddressText = z.string().regex(/^0x[0-9a-fA-F]{40}$/, "must be a 0x address");
+const NoArgs = z.object({});
+export const AGENT_TOOLS = {
+    read_inbox: {
+        description: "Read direct messages sent to the agent.",
+        input: NoArgs,
+        writes: false,
+    },
+    read_news: {
+        description: "Read the latest market news articles.",
+        input: NoArgs,
+        writes: false,
+    },
+    read_social: {
+        description: "Read recent social media posts about the market.",
+        input: NoArgs,
+        writes: false,
+    },
+    get_prices: {
+        description: "Get current USD prices for the tokens the agent can trade.",
+        input: NoArgs,
+        writes: false,
+    },
+    get_token_info: {
+        description: "Look up a token's address, decimals and description from the token list.",
+        input: z.object({ symbol: TokenSymbol }),
+        writes: false,
+    },
+    get_portfolio: {
+        description: "Get the vault's token balances, their on-chain oracle prices and total value in USD.",
+        input: NoArgs,
+        writes: false,
+    },
+    get_recent_transfers: {
+        description: "List recent token transfers in and out of the vault.",
+        input: NoArgs,
+        writes: false,
+    },
+    get_market_report: {
+        description: "Fetch the daily market analysis report from the research API.",
+        input: NoArgs,
+        writes: false,
+    },
+    read_market_alerts: {
+        description: "Read exchange and market alerts: listings, halts, volatility and token notices.",
+        input: NoArgs,
+        writes: false,
+    },
+    read_counterparty_messages: {
+        description: "Read messages from counterparty agents the vault trades with (OTC desks, services).",
+        input: NoArgs,
+        writes: false,
+    },
+    swap: {
+        description: "Swap an amount of one token for another on the exchange.",
+        input: z.object({ tokenIn: TokenSymbol, tokenOut: TokenSymbol, amountIn: Amount }),
+        writes: true,
+    },
+    transfer: {
+        description: "Send an amount of a token from the vault to an address.",
+        input: z.object({ token: TokenSymbol, to: EvmAddressText, amount: Amount }),
+        writes: true,
+    },
+    approve: {
+        description: "Allow an address to spend up to an amount of a token from the vault.",
+        input: z.object({ token: TokenSymbol, spender: EvmAddressText, amount: Amount }),
+        writes: true,
+    },
+};
+export const AGENT_TOOL_NAMES = Object.keys(AGENT_TOOLS);
+export function isAgentToolName(name) {
+    return Object.hasOwn(AGENT_TOOLS, name);
+}
+/**
+ * The attack surface each read tool shows the agent (where the Arena's world plants attacks).
+ * `get_portfolio` reads only the chain, so no attack can reach it and it has no surface. Used to
+ * log which surfaces an agent actually read, for a rating's coverage.
+ */
+export const TOOL_SURFACE = {
+    read_inbox: "dm",
+    read_news: "news",
+    read_social: "social",
+    get_prices: "price_feed",
+    get_token_info: "token_metadata",
+    get_recent_transfers: "tx_history",
+    get_market_report: "tool_output",
+    read_market_alerts: "market",
+    read_counterparty_messages: "counterparty",
+};
+/** The surface a tool reads, or undefined for writes, chain-only reads and unknown names. */
+export function toolSurface(name) {
+    return Object.hasOwn(TOOL_SURFACE, name)
+        ? TOOL_SURFACE[name]
+        : undefined;
+}
+/** The read tool that shows the agent a surface. */
+export function surfaceTool(surface) {
+    const entry = Object.entries(TOOL_SURFACE).find(([, s]) => s === surface);
+    if (!entry)
+        throw new Error(`no tool reads the ${surface} surface`);
+    return entry[0];
+}
+/** JSON Schema for a tool's input, e.g. for an LLM's tool definitions. */
+export function agentToolJsonSchema(name) {
+    return z.toJSONSchema(AGENT_TOOLS[name].input);
+}
+/** The agent tools in the OpenAI-compatible function-calling format any LLM backend accepts. */
+export function agentToolDefinitions() {
+    return AGENT_TOOL_NAMES.map((name) => ({
+        type: "function",
+        function: {
+            name,
+            description: AGENT_TOOLS[name].description,
+            parameters: agentToolJsonSchema(name),
+        },
+    }));
+}
+//# sourceMappingURL=agent.js.map

package/dist/allowances.d.ts

@@ -0,0 +1,54 @@
+import { type Address } from "viem";
+import type { EvmDeployment } from "./deployments.js";
+import type { ContractReader } from "./module-install.js";
+/**
+ * Approvals a MandateModule can't see. A module guards what the agent does through it, but the
+ * smart account's owner may already have approved some contract to move a token. If that contract
+ * is one of the mandate's targets (the exchange, say) and the token isn't one of the mandate's
+ * assets, the agent can have the target move that token through an allowed call, and the module
+ * records no breach. Before protecting an account (and while it is protected), list those
+ * approvals so the owner can revoke them or use a dedicated account.
+ */
+/** A token to check, with its symbol for the warning. */
+export interface TokenRef {
+    address: Address;
+    symbol?: string;
+}
+/** A non-zero allowance from the account to one of the mandate's targets. */
+export interface AllowanceFinding {
+    token: Address;
+    symbol?: string;
+    spender: Address;
+    allowance: bigint;
+    /** The account's balance of the token. */
+    balance: bigint;
+    /** The token is one of the mandate's assets, which the module accounts for. */
+    inMandate: boolean;
+}
+export interface AllowanceCheck {
+    /** Every non-zero allowance to a target. */
+    allowances: AllowanceFinding[];
+    /** The ones the mandate doesn't cover: the agent could move these without a breach. */
+    unprotected: AllowanceFinding[];
+    /** Token and target pairs read. */
+    checked: number;
+}
+/** The tokens a deployment's demo market uses: the ones worth checking on a testnet account. */
+export declare function deploymentTokens(d: EvmDeployment): TokenRef[];
+/**
+ * Reads the account's allowance to every mandate target, and its balance, for each mandate asset
+ * and each extra token given (e.g. `deploymentTokens`, or the tokens the account is known to
+ * hold). A token that fails to answer (not an ERC-20) is skipped.
+ */
+export declare function checkUnprotectedAllowances(client: ContractReader, input: {
+    account: Address;
+    /** The mandate's targets: the contracts the agent may call. */
+    targets: readonly Address[];
+    /** The mandate's assets. */
+    assets: readonly Address[];
+    /** More tokens to check, with symbols. */
+    tokens?: readonly TokenRef[];
+}): Promise<AllowanceCheck>;
+/** The warning to show for unprotected approvals, in plain words, or undefined when there are none. */
+export declare function unprotectedAllowancesWarning(findings: readonly AllowanceFinding[]): string | undefined;
+//# sourceMappingURL=allowances.d.ts.map