@bondedhq/sdk 0.1.6 → 0.1.7

package/README.md

@@ -388,6 +388,27 @@ if (isBondedEpisode()) {
 `isBondedEpisode()` is true when the runner set valid `BONDED_*` variables. `fromBondedEnv` reads
 and checks them, naming every missing or malformed one (`BondedError`, code `EPISODE_ENV`).
 
+That is the vault world, where ratings run. An agent that trades through a broker can also be
+tested on the brokerage world (a simulated brokerage account, no vault; docs/BROKERAGE.md), with a
+runner started with `--world brokerage`. Its episode is read with `fromBondedBrokerageEnv()`, and
+`bondedEpisodeWorld()` says which world the runner set up:
+
+```ts
+import { bondedEpisodeWorld, fromBondedBrokerageEnv, fromBondedEnv } from "@bondedhq/sdk";
+
+const world = bondedEpisodeWorld(); // "vault", "brokerage", or undefined outside an episode
+if (world === "brokerage") {
+  const episode = fromBondedBrokerageEnv(); // { world, episodeId, task, mode: "tools", endpoints, deadlineMs }
+} else if (world === "vault") {
+  const episode = fromBondedEnv();
+}
+```
+
+`isBondedEpisode()` is true in both worlds, so an agent under test never falls through to its
+production tools. In a brokerage episode `fromBondedEnv` and the vault tool helpers throw
+`EPISODE_ENV` rather than guess. By Agent URL, `createBondedHandler` runs brokerage episodes with
+`onBrokerageEpisode` and refuses them (422) without it.
+
 The mode decides how the agent acts:
 
 - **tools**: reads and writes are tool calls; `swap`, `transfer` and `approve` are tools, and the

package/dist/agent-url.d.ts

@@ -1,5 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { BondedEpisode } from "./episode.js";
+import type { BondedBrokerageEpisode, BondedEpisode } from "./episode.js";
 import type { EpisodeUsage } from "./mcp.js";
 /** For your own handler: the proof a verify answer carries, and the whole answer. */
 export { agentUrlVerifyProof, answerAgentUrlVerify } from "@bondedhq/shared/agent-url";
@@ -40,6 +40,14 @@ export interface BondedHandlerOptions {
     secret: string | string[];
     /** Runs one episode. Resolve when the agent is finished; the handler then posts `/done`. */
     onEpisode(episode: BondedEpisode, context: EpisodeContext): Promise<EpisodeOutcome | void> | EpisodeOutcome | void;
+    /**
+     * Runs one brokerage episode (a simulated brokerage account; docs/BROKERAGE.md). Without it, the
+     * handler refuses brokerage episodes with 422, so an agent built for the vault world never gets
+     * one by surprise. Errors are passed to `onBrokerageError` (default `console.error`).
+     */
+    onBrokerageEpisode?(episode: BondedBrokerageEpisode, context: EpisodeContext): Promise<EpisodeOutcome | void> | EpisodeOutcome | void;
+    /** Called when `onBrokerageEpisode` throws (default: `console.error`). `/done` is still posted. */
+    onBrokerageError?: (error: unknown, episode: BondedBrokerageEpisode) => void;
     /**
      * Your agent's version (a release tag, a git commit). Reported when Bonded verifies the URL;
      * it becomes the rating's code hash when you don't declare one.

package/dist/agent-url.js

@@ -32,17 +32,29 @@ export function createBondedHandler(options) {
     /** Signatures already accepted, until they fall out of the window: replays are refused. */
     const replay = new AgentUrlReplayGuard(tolerance);
     const running = new Map();
-    const run = async (episode, controller) => {
+    const onBrokerageError = options.onBrokerageError ??
+        ((error, episode) => console.error(`Bonded brokerage episode ${episode.episodeId} failed:`, error));
+    const run = async (episode, controller, work, reportError) => {
         const deadline = setTimeout(() => controller.abort(new Error("the episode's deadline passed")), episode.deadlineMs);
+        // A reporter that throws must not stop `/done` from being posted: the gateway would wait out
+        // the deadline for an episode that has already failed.
+        const report = (error) => {
+            try {
+                reportError(error, episode);
+            }
+            catch (reporterError) {
+                console.error(`Bonded episode ${episode.episodeId}: the error reporter threw:`, reporterError);
+            }
+        };
         let outcome;
         let failed = false;
         try {
-            outcome = await options.onEpisode(episode, { signal: controller.signal });
+            outcome = await work(episode, { signal: controller.signal });
         }
         catch (error) {
             failed = true;
             if (!controller.signal.aborted)
-                onError(error, episode);
+                report(error);
             outcome = {
                 finalMessage: `the agent failed: ${error instanceof Error ? error.message : String(error)}`.slice(0, 4_000),
             };
@@ -64,7 +76,7 @@ export function createBondedHandler(options) {
         }
         catch (error) {
             if (!failed)
-                onError(error, episode);
+                report(error);
         }
     };
     return async (request, context) => {
@@ -92,20 +104,25 @@ export function createBondedHandler(options) {
             controller?.abort(new Error("Bonded cancelled the episode"));
             return json(200, { ok: true, cancelled: controller !== undefined });
         }
-        const episode = toEpisode(message);
-        if (running.has(episode.episodeId))
-            return json(200, { ok: true, episodeId: episode.episodeId, alreadyRunning: true });
+        if (message.world === "brokerage" && !options.onBrokerageEpisode)
+            return json(422, {
+                error: "this agent doesn't take brokerage episodes (no onBrokerageEpisode)",
+            });
+        if (running.has(message.episodeId))
+            return json(200, { ok: true, episodeId: message.episodeId, alreadyRunning: true });
         if (running.size >= maxConcurrent)
             return json(429, { error: `already running ${running.size} episodes` });
         const controller = new AbortController();
-        running.set(episode.episodeId, controller);
-        const work = run(episode, controller);
+        running.set(message.episodeId, controller);
+        const work = message.world === "brokerage"
+            ? run(toBrokerageEpisode(message), controller, (e, c) => options.onBrokerageEpisode(e, c), onBrokerageError)
+            : run(toEpisode(message), controller, (e, c) => options.onEpisode(e, c), onError);
         // Called as a method: Cloudflare's ctx.waitUntil needs its `this`.
         if (context?.waitUntil)
             context.waitUntil(work);
         else
             options.waitUntil?.(work);
-        return json(202, { ok: true, episodeId: episode.episodeId });
+        return json(202, { ok: true, episodeId: message.episodeId });
     };
 }
 /**
@@ -122,6 +139,17 @@ async function signingSecret(secrets, body, headers, nowMs, toleranceSeconds) {
     }
     return secrets[0];
 }
+/** A brokerage episode as the agent sees it (the same shape `fromBondedBrokerageEnv` returns). */
+function toBrokerageEpisode(message) {
+    return {
+        world: "brokerage",
+        episodeId: message.episodeId,
+        task: message.task,
+        mode: "tools",
+        endpoints: message.endpoints,
+        deadlineMs: message.deadlineMs,
+    };
+}
 /** The episode as the agent sees it (the same shape `fromBondedEnv` returns). */
 function toEpisode(message) {
     // The runner protocol's message, minus `type`, `nonce` and `teeKeyId` (TEE-bound agents use

package/dist/episode.d.ts

@@ -41,6 +41,7 @@ export interface BondedEpisode {
  * 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_WORLD: import("zod").ZodOptional<import("zod").ZodLiteral<"vault">>;
     BONDED_EPISODE_ID: import("zod").ZodString;
     BONDED_MODE: import("zod").ZodEnum<{
         tools: "tools";
@@ -57,6 +58,7 @@ export declare const bondedEpisodeEnv: import("zod").ZodObject<{
             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;
+        tools: import("zod").ZodOptional<import("zod").ZodReadonly<import("zod").ZodArray<import("zod").ZodString>>>;
     }, import("zod/v4/core").$strip>>;
     BONDED_MCP_URL: import("zod").ZodURL;
     BONDED_TOOLS_URL: import("zod").ZodURL;
@@ -84,6 +86,11 @@ export declare const bondedEpisodeEnv: import("zod").ZodObject<{
  * ```ts
  * const tools = isBondedEpisode() ? await bondedLangChainTools() : productionTools;
  * ```
+ *
+ * True in every world, so an agent under test never falls through to its production tools. In a
+ * world the agent wasn't built for, the helpers then fail loudly: in a brokerage episode
+ * `fromBondedEnv` and the vault tool helpers throw `EPISODE_ENV`. `bondedEpisodeWorld()` says
+ * which world it is.
  */
 export declare function isBondedEpisode(env?: Record<string, string | undefined>): boolean;
 /**
@@ -105,4 +112,48 @@ export declare function fromBondedEnv(env?: Record<string, string | undefined>):
  * or when the key is held by a TEE (no session key): use your own signer there.
  */
 export declare function episodeVault(episode: BondedEpisode): BondedVault;
+/**
+ * A brokerage episode: the agent manages a simulated brokerage account (stocks, filings, orders,
+ * cash withdrawals) through the episode's tools. There is no chain, vault or key: every read and
+ * write is a tool call, and the Arena judges it by the brokerage ledger. Needs runner protocol 2
+ * (`@bondedhq/runner` 0.1.4 or later), started with `--world brokerage`.
+ */
+export interface BondedBrokerageEpisode {
+    world: "brokerage";
+    episodeId: string;
+    task: AgentTask;
+    mode: "tools";
+    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;
+    };
+    /** How long the agent has, in milliseconds from when it starts. */
+    deadlineMs: number;
+}
+/**
+ * Which world the runner's episode is for: `vault` (on-chain trading from a Mandate Vault, read
+ * with `fromBondedEnv`), `brokerage` (read with `fromBondedBrokerageEnv`), or undefined when this
+ * process isn't running a Bonded episode.
+ *
+ * ```ts
+ * const world = bondedEpisodeWorld();
+ * const tools =
+ *   world === "brokerage"
+ *     ? await myBrokerageTools(fromBondedBrokerageEnv())
+ *     : world === "vault"
+ *       ? await bondedLangChainTools()
+ *       : productionTools;
+ * ```
+ */
+export declare function bondedEpisodeWorld(env?: Record<string, string | undefined>): "vault" | "brokerage" | undefined;
+/**
+ * Reads a brokerage episode the Bonded runner set up from the environment. Throws `BondedError`
+ * (`EPISODE_ENV`) naming every missing or malformed variable.
+ */
+export declare function fromBondedBrokerageEnv(env?: Record<string, string | undefined>): BondedBrokerageEpisode;
 //# sourceMappingURL=episode.d.ts.map

package/dist/episode.js

@@ -1,4 +1,4 @@
-import { EpisodeEnv, parseEpisodeEnv } from "@bondedhq/shared";
+import { EpisodeEnv, parseBrokerageEpisodeEnv, parseEpisodeEnv, } from "@bondedhq/shared";
 import { defineChain } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { BondedError } from "./errors.js";
@@ -15,9 +15,14 @@ export const bondedEpisodeEnv = EpisodeEnv;
  * ```ts
  * const tools = isBondedEpisode() ? await bondedLangChainTools() : productionTools;
  * ```
+ *
+ * True in every world, so an agent under test never falls through to its production tools. In a
+ * world the agent wasn't built for, the helpers then fail loudly: in a brokerage episode
+ * `fromBondedEnv` and the vault tool helpers throw `EPISODE_ENV`. `bondedEpisodeWorld()` says
+ * which world it is.
  */
 export function isBondedEpisode(env = typeof process === "undefined" ? {} : process.env) {
-    return parseEpisodeEnv(env).ok;
+    return bondedEpisodeWorld(env) !== undefined;
 }
 /**
  * Reads the episode the Bonded runner set up from the environment. Throws `BondedError`
@@ -62,4 +67,37 @@ export function episodeVault(episode) {
         router: episode.contracts.exchange,
     });
 }
+/**
+ * Which world the runner's episode is for: `vault` (on-chain trading from a Mandate Vault, read
+ * with `fromBondedEnv`), `brokerage` (read with `fromBondedBrokerageEnv`), or undefined when this
+ * process isn't running a Bonded episode.
+ *
+ * ```ts
+ * const world = bondedEpisodeWorld();
+ * const tools =
+ *   world === "brokerage"
+ *     ? await myBrokerageTools(fromBondedBrokerageEnv())
+ *     : world === "vault"
+ *       ? await bondedLangChainTools()
+ *       : productionTools;
+ * ```
+ */
+export function bondedEpisodeWorld(env = typeof process === "undefined" ? {} : process.env) {
+    // Fails closed: once the runner has named the brokerage world for an episode, that is the
+    // answer even if another variable is malformed. `fromBondedBrokerageEnv` then names the bad
+    // variable, where "not an episode" would send the agent to its production tools.
+    if (env.BONDED_WORLD === "brokerage" && env.BONDED_EPISODE_ID?.trim())
+        return "brokerage";
+    return parseEpisodeEnv(env).ok ? "vault" : undefined;
+}
+/**
+ * Reads a brokerage episode the Bonded runner set up from the environment. Throws `BondedError`
+ * (`EPISODE_ENV`) naming every missing or malformed variable.
+ */
+export function fromBondedBrokerageEnv(env = process.env) {
+    const parsed = parseBrokerageEpisodeEnv(env);
+    if (!parsed.ok)
+        throw new BondedError("EPISODE_ENV", `not a valid Bonded brokerage episode environment: ${parsed.problems.join("; ")}`);
+    return parsed.episode;
+}
 //# sourceMappingURL=episode.js.map

package/dist/index.d.ts

@@ -24,6 +24,6 @@ export { BONDED_API_URL, PaymentGate, paymentGate, type GateAnswer, type GateChe
 export { guardPayments, guardVendorChanges, isPaymentRefusal, PaymentGuard, paymentGuard, type GuardPaymentsOptions, type GuardVendorChangesOptions, type PaymentBreach, type PaymentGuardOptions, type PaymentGuardState, type PaymentMandate, type PaymentSource, type PaymentVendor, type PaymentVerdict, } from "./payments.js";
 export { describePaymentMandate, GATE_RULE_WORDS, GATE_RULES, PAYMENT_RULE_WORDS, PAYMENT_RULES, type GateRule, type PaidPayment, type PayableInvoice, type PayableRefund, type PaymentAttempt, type PaymentRule, type VerifiedChange, } 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 { bondedEpisodeEnv, bondedEpisodeWorld, episodeVault, fromBondedBrokerageEnv, fromBondedEnv, isBondedEpisode, type BondedBrokerageEpisode, 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

@@ -23,6 +23,6 @@ export { BONDED_API_URL, PaymentGate, paymentGate, } from "./gate.js";
 export { guardPayments, guardVendorChanges, isPaymentRefusal, PaymentGuard, paymentGuard, } from "./payments.js";
 export { describePaymentMandate, GATE_RULE_WORDS, GATE_RULES, PAYMENT_RULE_WORDS, PAYMENT_RULES, } from "@bondedhq/shared";
 export { BONDED_VAULT_TOOLS, bondedVaultFromEnv, bondedVaultTools, } from "./vault-tools.js";
-export { bondedEpisodeEnv, episodeVault, fromBondedEnv, isBondedEpisode, } from "./episode.js";
+export { bondedEpisodeEnv, bondedEpisodeWorld, episodeVault, fromBondedBrokerageEnv, fromBondedEnv, isBondedEpisode, } from "./episode.js";
 export { checkUnprotectedAllowances, deploymentTokens, unprotectedAllowancesWarning, installMandateModule, } from "./module.js";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bondedhq/sdk",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Trade through a Bonded Mandate Vault and get rated by the Bonded Arena from any TypeScript agent: a typed vault client with dry runs, Sentinel checks and a mandate builder; the Arena episode's tools for LangChain, the Vercel AI SDK, ElizaOS and Coinbase AgentKit; a payment guard for pay tools (LangChain, the AI SDK, MCP, the OpenAI Agents SDK) and x402 clients; and an Agent URL handler.",
   "license": "MIT",
   "keywords": [
@@ -94,7 +94,7 @@
     "@modelcontextprotocol/sdk": "1.30.1",
     "viem": "^2.56.9",
     "zod": "^4.6.5",
-    "@bondedhq/shared": "^0.1.5"
+    "@bondedhq/shared": "^0.1.6"
   },
   "devDependencies": {
     "@coinbase/agentkit": "0.10.4",