@theokit/sdk 4.53.0 → 4.54.0

package/LICENSE

@@ -137,8 +137,8 @@
 
    6. Trademarks. This License does not grant permission to use the trade
       names, trademarks, service marks, or product names of the Licensor,
-      except as required for describing the origin of the Work and
-      reproducing the content of the NOTICE file.
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
 
    7. Disclaimer of Warranty. Unless required by applicable law or
       agreed to in writing, Licensor provides the Work (and each

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
-  <a href="https://usetheo.dev">
-    <img src="https://usetheo.dev/logo-128.png" alt="Theo" height="80" />
+  <a href="https://github.com/usetheokit/theokit-sdk">
+    <img src="https://raw.githubusercontent.com/usetheodev/theokit-sdk/main/assets/logo.png" alt="TheoKit" height="96" />
   </a>
 </p>
 
@@ -13,7 +13,7 @@
     Same agent surface, local or cloud. No vendor lock-in.
   </p>
   <p align="center">
-    <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square"></a>
+    <a href="https://github.com/usetheokit/theokit-sdk/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-DE2329?style=flat-square"></a>
     <img alt="TypeScript" src="https://img.shields.io/badge/typescript-5.8%2B-3178C6?style=flat-square&logo=typescript&logoColor=white">
     <img alt="Node" src="https://img.shields.io/badge/node-22.12%2B-339933?style=flat-square&logo=node.js&logoColor=white">
     <img alt="Status" src="https://img.shields.io/badge/status-public%20beta-orange?style=flat-square">
@@ -24,20 +24,25 @@
 
 > **Public beta.** APIs may change before general availability.
 
-For the full reference, see the [root README](https://github.com/usetheodev/theokit-sdk#readme) and the [**Harness Capability Map**](https://github.com/usetheodev/theokit-sdk/blob/main/wiki/reference/harness-capability-map.md). The exported TypeScript types are the canonical contract.
+For the full reference, see the [root README](https://github.com/usetheokit/theokit-sdk#readme). The exported TypeScript types are the canonical contract.
 
 ## Capability map
 
-New here? The [**Theo Harness Capability Map**](https://github.com/usetheodev/theokit-sdk/blob/main/wiki/reference/harness-capability-map.md) is the discovery front-door — every harness primitive with its import path, signature, and a one-line example (find `compactTranscript`, `buildRepoMap`, `isTransientError`, `@theokit/sdk/persistence`, ... without reading source). The exported TypeScript types are the canonical contract.
+New here? The exported TypeScript types are the discovery front-door and the canonical contract — every harness primitive with its import path, signature and JSDoc example (`compactTranscript`, `buildRepoMap`, `isTransientError`, `@theokit/sdk/persistence`, ...), surfaced by your editor.
 
-It also **ships inside this package** — no network needed, and pinned to the version you installed:
+Two references ship inside the package — no network, pinned to the version you installed, and both
+GENERATED from the built declarations so they cannot drift from what you actually got:
 
 ```
-node_modules/@theokit/sdk/docs/harness-capability-map.md   # every public primitive + import path
-node_modules/@theokit/sdk/docs/error-codes.md              # AgentRunError.code reference
-node_modules/@theokit/sdk/claude-template/                 # agent context (npx theokit-init-claude)
+node_modules/@theokit/sdk/docs/harness-capability-map.md   # every public symbol + its exact import specifier
+node_modules/@theokit/sdk/docs/error-codes.md              # every `code` an error can carry, and where it is raised
 ```
 
+If you are an agent: read the capability map before writing an import. Several symbols are reachable
+from more than one specifier, and a class emitted into a subpath entry is a DISTINCT nominal type
+from the one in the root bundle — import a symbol and everything you pass it to from the same
+specifier, or the call fails on a private field.
+
 Agents that consume documentation should prefer the machine-readable corpora on the docs site ([llmstxt.org](https://llmstxt.org) convention): [`llms.txt`](https://docs.usetheo.dev/llms.txt) (curated index) and [`llms-full.txt`](https://docs.usetheo.dev/llms-full.txt) (every page inlined).
 
 ## Install

package/bin/theokit-migrate-config.mjs

@@ -7,6 +7,7 @@
 //
 // Usage: theokit-migrate-config [--cwd <path>] [--apply] [--no-backup] [--help]
 
+import { randomBytes } from "node:crypto";
 import { existsSync } from "node:fs";
 import { mkdir, readdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
@@ -53,10 +54,18 @@ manual edits). Atomic write per file (crash mid-write is safe).
   );
 }
 
-/** Atomic write: tmpfile + rename. Mirrors atomicWriteText in the SDK. */
+/**
+ * Atomic write: tmpfile + rename. Mirrors atomicWriteText in the SDK.
+ *
+ * The suffix comes from `randomBytes`, matching `atomicWriteTempPath` in
+ * src/internal/persistence/atomic-write.ts — `<file>.<pid>.<16 hex>.tmp`. It used
+ * `Math.random()`, which this comment already claimed it did not: a temp name in a
+ * directory an attacker can also write to is guessable, and the window between
+ * choosing the name and `rename` is where a symlink gets planted.
+ */
 async function atomicWriteText(filePath, content) {
   await mkdir(join(filePath, ".."), { recursive: true });
-  const tmp = `${filePath}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
+  const tmp = `${filePath}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
   await writeFile(tmp, content, "utf8");
   await rename(tmp, filePath);
 }

package/dist/a2a/agent-mailbox.d.cts

@@ -8,6 +8,33 @@
  */
 import type { MessageBus, RequestOptions } from "./message-bus.js";
 import type { MessageHandler } from "./types.js";
+/**
+ * One agent's endpoint on a {@link MessageBus}: registers `agentId` on
+ * construction and forwards inbound messages to the handler installed by
+ * `onMessage`.
+ *
+ *   const mailbox = new AgentMailbox("worker", bus);
+ *   mailbox.onMessage((m) => `echo:${m.payload}`);
+ *   await mailbox.send("boss", { type: "ready", payload: null });
+ *
+ * Needs an already-constructed `MessageBus` — the mailbox does not create one, and
+ * two mailboxes reach each other only through the SAME bus instance.
+ *
+ * How it fails: `send` and `request` are thin forwards, so they carry the bus's
+ * failures unchanged (plain `Error` for an unregistered peer, plus a timeout
+ * rejection for `request`).
+ *
+ * Traps:
+ *  - The constructor registers IMMEDIATELY, before `onMessage` can be called. A
+ *    message arriving in that window is dropped silently, and a peer's `request`
+ *    RESOLVES WITH `undefined` instead of timing out — install the handler in the
+ *    same tick as construction.
+ *  - Constructing a second mailbox with the same `agentId` on the same bus takes
+ *    the id over silently (`MessageBus.register` overwrites), and the loser's
+ *    `dispose()` then unregisters the WINNER.
+ *  - `dispose()` only unregisters and clears the handler. Requests already in
+ *    flight are neither cancelled nor rejected; they time out on the caller's side.
+ */
 export declare class AgentMailbox {
     readonly agentId: string;
     private readonly _bus;

package/dist/a2a/agent-mailbox.d.ts

@@ -8,6 +8,33 @@
  */
 import type { MessageBus, RequestOptions } from "./message-bus.js";
 import type { MessageHandler } from "./types.js";
+/**
+ * One agent's endpoint on a {@link MessageBus}: registers `agentId` on
+ * construction and forwards inbound messages to the handler installed by
+ * `onMessage`.
+ *
+ *   const mailbox = new AgentMailbox("worker", bus);
+ *   mailbox.onMessage((m) => `echo:${m.payload}`);
+ *   await mailbox.send("boss", { type: "ready", payload: null });
+ *
+ * Needs an already-constructed `MessageBus` — the mailbox does not create one, and
+ * two mailboxes reach each other only through the SAME bus instance.
+ *
+ * How it fails: `send` and `request` are thin forwards, so they carry the bus's
+ * failures unchanged (plain `Error` for an unregistered peer, plus a timeout
+ * rejection for `request`).
+ *
+ * Traps:
+ *  - The constructor registers IMMEDIATELY, before `onMessage` can be called. A
+ *    message arriving in that window is dropped silently, and a peer's `request`
+ *    RESOLVES WITH `undefined` instead of timing out — install the handler in the
+ *    same tick as construction.
+ *  - Constructing a second mailbox with the same `agentId` on the same bus takes
+ *    the id over silently (`MessageBus.register` overwrites), and the loser's
+ *    `dispose()` then unregisters the WINNER.
+ *  - `dispose()` only unregisters and clears the handler. Requests already in
+ *    flight are neither cancelled nor rejected; they time out on the caller's side.
+ */
 export declare class AgentMailbox {
     readonly agentId: string;
     private readonly _bus;

package/dist/a2a/index.cjs

@@ -1,7 +1,8 @@
 'use strict';
 
-var chunkB4YA6BRS_cjs = require('../chunk-B4YA6BRS.cjs');
+var chunk4O5TGQBW_cjs = require('../chunk-4O5TGQBW.cjs');
 require('../chunk-NINIJCHU.cjs');
+var chunkNUKRL3I6_cjs = require('../chunk-NUKRL3I6.cjs');
 
 // src/a2a/agent-mailbox.ts
 var AgentMailbox = class {
@@ -55,7 +56,11 @@ var MessageBus = class {
       // SE3 — provenance projection of the sender address (thin view over `from`).
       origin: { kind: "peer", from }
     };
-    handler(message);
+    void Promise.resolve(handler(message)).catch((cause) => {
+      const reason = cause instanceof Error ? cause.message : String(cause);
+      chunkNUKRL3I6_cjs.diag(`[theokit-sdk] a2a: handler for "${to}" failed on a fire-and-forget send: ${reason}
+`);
+    });
   }
   async request(from, to, partial, opts) {
     const handler = this._handlers.get(to);
@@ -96,11 +101,11 @@ var MessageBus = class {
 
 Object.defineProperty(exports, "MaxDelegationDepthError", {
   enumerable: true,
-  get: function () { return chunkB4YA6BRS_cjs.MaxDelegationDepthError; }
+  get: function () { return chunk4O5TGQBW_cjs.MaxDelegationDepthError; }
 });
 Object.defineProperty(exports, "SubAgent", {
   enumerable: true,
-  get: function () { return chunkB4YA6BRS_cjs.SubAgent; }
+  get: function () { return chunk4O5TGQBW_cjs.SubAgent; }
 });
 exports.AgentMailbox = AgentMailbox;
 exports.MessageBus = MessageBus;

package/dist/a2a/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/a2a/agent-mailbox.ts","../../src/a2a/message-bus.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * AgentMailbox — per-agent inbox for A2A communication (T20.1, ADR D453).\n *\n * Wraps MessageBus registration with a convenient API for sending,\n * receiving, and requesting messages.\n *\n * @public\n */\n\nimport type { MessageBus, RequestOptions } from \"./message-bus.js\";\nimport type { A2AMessage, MessageHandler } from \"./types.js\";\n\nexport class AgentMailbox {\n  readonly agentId: string;\n  private readonly _bus: MessageBus;\n  private _handler: MessageHandler | null = null;\n\n  constructor(agentId: string, bus: MessageBus) {\n    this.agentId = agentId;\n    this._bus = bus;\n    this._bus.register(agentId, (msg) => this._dispatch(msg));\n  }\n\n  onMessage(handler: MessageHandler): void {\n    this._handler = handler;\n  }\n\n  async send(to: string, partial: { type: string; payload: unknown }): Promise<void> {\n    return this._bus.send(this.agentId, to, partial);\n  }\n\n  async request(\n    to: string,\n    partial: { type: string; payload: unknown },\n    opts?: RequestOptions,\n  ): Promise<unknown> {\n    return this._bus.request(this.agentId, to, partial, opts);\n  }\n\n  dispose(): void {\n    this._bus.unregister(this.agentId);\n    this._handler = null;\n  }\n\n  private _dispatch(msg: A2AMessage): unknown {\n    if (this._handler) {\n      return this._handler(msg);\n    }\n  }\n}\n","/**\n * MessageBus — in-process typed message router for A2A (T20.1, ADR D453).\n *\n * Routes messages between agents by ID. Supports fire-and-forget (send)\n * and request/response (request with timeout).\n *\n * @public\n */\n\nimport type { A2AMessage, MessageHandler } from \"./types.js\";\n\nexport interface RequestOptions {\n  timeoutMs?: number;\n}\n\nexport class MessageBus {\n  private readonly _handlers = new Map<string, MessageHandler>();\n\n  register(agentId: string, handler: MessageHandler): void {\n    this._handlers.set(agentId, handler);\n  }\n\n  unregister(agentId: string): void {\n    this._handlers.delete(agentId);\n  }\n\n  async send(from: string, to: string, partial: { type: string; payload: unknown }): Promise<void> {\n    const handler = this._handlers.get(to);\n    if (!handler) {\n      throw new Error(`Agent \"${to}\" not registered on MessageBus`);\n    }\n    const message: A2AMessage = {\n      ...partial,\n      from,\n      to,\n      timestamp: Date.now(),\n      // SE3 — provenance projection of the sender address (thin view over `from`).\n      origin: { kind: \"peer\", from },\n    };\n    // Fire-and-forget: invoke handler but don't await result\n    handler(message);\n  }\n\n  async request(\n    from: string,\n    to: string,\n    partial: { type: string; payload: unknown },\n    opts?: RequestOptions,\n  ): Promise<unknown> {\n    const handler = this._handlers.get(to);\n    if (!handler) {\n      throw new Error(`Agent \"${to}\" not registered on MessageBus`);\n    }\n    const timeoutMs = opts?.timeoutMs ?? 30_000;\n    const message: A2AMessage = {\n      ...partial,\n      from,\n      to,\n      timestamp: Date.now(),\n      // SE3 — provenance projection of the sender address (thin view over `from`).\n      origin: { kind: \"peer\", from },\n    };\n    // Hold the timer so it can be cleared once the race settles — otherwise a\n    // successful request leaks a live `setTimeout` that keeps the Node event loop\n    // alive (the process hangs after the reply). Cleared in `finally`.\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    try {\n      return await Promise.race([\n        Promise.resolve(handler(message)),\n        new Promise((_, reject) => {\n          timer = setTimeout(\n            () =>\n              reject(new Error(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`)),\n            timeoutMs,\n          );\n        }),\n      ]);\n    } finally {\n      if (timer !== undefined) clearTimeout(timer);\n    }\n  }\n\n  has(agentId: string): boolean {\n    return this._handlers.has(agentId);\n  }\n\n  listAgents(): string[] {\n    return [...this._handlers.keys()];\n  }\n}\n"]}
+{"version":3,"sources":["../../src/a2a/agent-mailbox.ts","../../src/a2a/message-bus.ts"],"names":["diag"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * AgentMailbox — per-agent inbox for A2A communication (T20.1, ADR D453).\n *\n * Wraps MessageBus registration with a convenient API for sending,\n * receiving, and requesting messages.\n *\n * @public\n */\n\nimport type { MessageBus, RequestOptions } from \"./message-bus.js\";\nimport type { A2AMessage, MessageHandler } from \"./types.js\";\n\n/**\n * One agent's endpoint on a {@link MessageBus}: registers `agentId` on\n * construction and forwards inbound messages to the handler installed by\n * `onMessage`.\n *\n *   const mailbox = new AgentMailbox(\"worker\", bus);\n *   mailbox.onMessage((m) => `echo:${m.payload}`);\n *   await mailbox.send(\"boss\", { type: \"ready\", payload: null });\n *\n * Needs an already-constructed `MessageBus` — the mailbox does not create one, and\n * two mailboxes reach each other only through the SAME bus instance.\n *\n * How it fails: `send` and `request` are thin forwards, so they carry the bus's\n * failures unchanged (plain `Error` for an unregistered peer, plus a timeout\n * rejection for `request`).\n *\n * Traps:\n *  - The constructor registers IMMEDIATELY, before `onMessage` can be called. A\n *    message arriving in that window is dropped silently, and a peer's `request`\n *    RESOLVES WITH `undefined` instead of timing out — install the handler in the\n *    same tick as construction.\n *  - Constructing a second mailbox with the same `agentId` on the same bus takes\n *    the id over silently (`MessageBus.register` overwrites), and the loser's\n *    `dispose()` then unregisters the WINNER.\n *  - `dispose()` only unregisters and clears the handler. Requests already in\n *    flight are neither cancelled nor rejected; they time out on the caller's side.\n */\nexport class AgentMailbox {\n  readonly agentId: string;\n  private readonly _bus: MessageBus;\n  private _handler: MessageHandler | null = null;\n\n  constructor(agentId: string, bus: MessageBus) {\n    this.agentId = agentId;\n    this._bus = bus;\n    this._bus.register(agentId, (msg) => this._dispatch(msg));\n  }\n\n  onMessage(handler: MessageHandler): void {\n    this._handler = handler;\n  }\n\n  async send(to: string, partial: { type: string; payload: unknown }): Promise<void> {\n    return this._bus.send(this.agentId, to, partial);\n  }\n\n  async request(\n    to: string,\n    partial: { type: string; payload: unknown },\n    opts?: RequestOptions,\n  ): Promise<unknown> {\n    return this._bus.request(this.agentId, to, partial, opts);\n  }\n\n  dispose(): void {\n    this._bus.unregister(this.agentId);\n    this._handler = null;\n  }\n\n  private _dispatch(msg: A2AMessage): unknown {\n    if (this._handler) {\n      return this._handler(msg);\n    }\n  }\n}\n","/**\n * MessageBus — in-process typed message router for A2A (T20.1, ADR D453).\n *\n * Routes messages between agents by ID. Supports fire-and-forget (send)\n * and request/response (request with timeout).\n *\n * @public\n */\n\nimport { diag } from \"../internal/diagnostics.js\";\nimport type { A2AMessage, MessageHandler } from \"./types.js\";\n\n/**\n * Per-call knobs for {@link MessageBus.request} / `AgentMailbox.request`.\n */\nexport interface RequestOptions {\n  /**\n   * How long to wait for the peer handler to settle before rejecting.\n   * Default `30_000` (30 s). The rejection is a plain `Error` reading\n   * `A2A request timeout: <to> did not respond within <n>ms` — there is no typed\n   * timeout class and no `code` field, so a caller that must distinguish a\n   * timeout from a handler failure has to match on the message.\n   */\n  timeoutMs?: number;\n}\n\n/**\n * In-process router that delivers A2A messages between agents keyed by string id.\n *\n * Purely in-memory and single-process: nothing is persisted and nothing crosses a\n * process or network boundary. Register one handler per agent id, then `send`\n * (fire-and-forget) or `request` (await the handler's return value).\n *\n *   const bus = new MessageBus();\n *   bus.register(\"worker\", (m) => `echo:${m.payload}`);\n *   const reply = await bus.request(\"boss\", \"worker\", { type: \"ping\", payload: 1 });\n *\n * Callers supply only `{ type, payload }`; the bus stamps `from`, `to`,\n * `timestamp` and `origin` onto the delivered {@link A2AMessage}.\n *\n * How it fails: `send` and `request` both reject with a plain `Error`\n * (`Agent \"<to>\" not registered on MessageBus`) when `to` has no handler, and\n * `request` additionally rejects on timeout. No typed error class is exported for\n * either, so there is nothing to `instanceof`.\n *\n * Traps:\n *  - `register` silently OVERWRITES an existing id; the previous handler simply\n *    stops receiving anything. Call `has(id)` first when that matters.\n *  - `send` is declared `async` but never awaits the handler. A handler that\n *    rejects produces an UNHANDLED rejection that `await bus.send(...)` does not\n *    observe — only the \"not registered\" failure reaches the caller. Use\n *    `request` when the handler's failure has to be visible.\n *  - `from` is whatever the caller passes; the bus never checks that the sender\n *    is registered. It is self-asserted provenance, not authentication.\n */\nexport class MessageBus {\n  private readonly _handlers = new Map<string, MessageHandler>();\n\n  register(agentId: string, handler: MessageHandler): void {\n    this._handlers.set(agentId, handler);\n  }\n\n  unregister(agentId: string): void {\n    this._handlers.delete(agentId);\n  }\n\n  async send(from: string, to: string, partial: { type: string; payload: unknown }): Promise<void> {\n    const handler = this._handlers.get(to);\n    if (!handler) {\n      throw new Error(`Agent \"${to}\" not registered on MessageBus`);\n    }\n    const message: A2AMessage = {\n      ...partial,\n      from,\n      to,\n      timestamp: Date.now(),\n      // SE3 — provenance projection of the sender address (thin view over `from`).\n      origin: { kind: \"peer\", from },\n    };\n    // Fire-and-forget: the SENDER does not wait for the result, which is the whole point of\n    // `send`. It does not mean nobody is told when delivery fails — that is the difference\n    // between asynchronous and silent (#365).\n    //\n    // The returned promise used to be dropped on the floor. `MessageHandler` may return one, so a\n    // rejecting handler became an unhandled rejection: fatal under Node's default\n    // `--unhandled-rejections=throw`, and invisible to the caller, whose `await send(...)`\n    // resolved cleanly either way. Attaching a catch keeps the call non-blocking and reports the\n    // failure instead of discarding it (`error-handling.md` § 5).\n    void Promise.resolve(handler(message)).catch((cause: unknown) => {\n      const reason = cause instanceof Error ? cause.message : String(cause);\n      diag(`[theokit-sdk] a2a: handler for \"${to}\" failed on a fire-and-forget send: ${reason}\\n`);\n    });\n  }\n\n  async request(\n    from: string,\n    to: string,\n    partial: { type: string; payload: unknown },\n    opts?: RequestOptions,\n  ): Promise<unknown> {\n    const handler = this._handlers.get(to);\n    if (!handler) {\n      throw new Error(`Agent \"${to}\" not registered on MessageBus`);\n    }\n    const timeoutMs = opts?.timeoutMs ?? 30_000;\n    const message: A2AMessage = {\n      ...partial,\n      from,\n      to,\n      timestamp: Date.now(),\n      // SE3 — provenance projection of the sender address (thin view over `from`).\n      origin: { kind: \"peer\", from },\n    };\n    // Hold the timer so it can be cleared once the race settles — otherwise a\n    // successful request leaks a live `setTimeout` that keeps the Node event loop\n    // alive (the process hangs after the reply). Cleared in `finally`.\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    try {\n      return await Promise.race([\n        Promise.resolve(handler(message)),\n        new Promise((_, reject) => {\n          timer = setTimeout(\n            () =>\n              reject(new Error(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`)),\n            timeoutMs,\n          );\n        }),\n      ]);\n    } finally {\n      if (timer !== undefined) clearTimeout(timer);\n    }\n  }\n\n  has(agentId: string): boolean {\n    return this._handlers.has(agentId);\n  }\n\n  listAgents(): string[] {\n    return [...this._handlers.keys()];\n  }\n}\n"]}

package/dist/a2a/index.js

@@ -1,5 +1,6 @@
-export { MaxDelegationDepthError, SubAgent } from '../chunk-RP5HQVLD.js';
+export { MaxDelegationDepthError, SubAgent } from '../chunk-RNB4APBZ.js';
 import '../chunk-6X6ID4MO.js';
+import { diag } from '../chunk-T7O6K6PX.js';
 
 // src/a2a/agent-mailbox.ts
 var AgentMailbox = class {
@@ -53,7 +54,11 @@ var MessageBus = class {
       // SE3 — provenance projection of the sender address (thin view over `from`).
       origin: { kind: "peer", from }
     };
-    handler(message);
+    void Promise.resolve(handler(message)).catch((cause) => {
+      const reason = cause instanceof Error ? cause.message : String(cause);
+      diag(`[theokit-sdk] a2a: handler for "${to}" failed on a fire-and-forget send: ${reason}
+`);
+    });
   }
   async request(from, to, partial, opts) {
     const handler = this._handlers.get(to);

package/dist/a2a/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/a2a/agent-mailbox.ts","../../src/a2a/message-bus.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * AgentMailbox — per-agent inbox for A2A communication (T20.1, ADR D453).\n *\n * Wraps MessageBus registration with a convenient API for sending,\n * receiving, and requesting messages.\n *\n * @public\n */\n\nimport type { MessageBus, RequestOptions } from \"./message-bus.js\";\nimport type { A2AMessage, MessageHandler } from \"./types.js\";\n\nexport class AgentMailbox {\n  readonly agentId: string;\n  private readonly _bus: MessageBus;\n  private _handler: MessageHandler | null = null;\n\n  constructor(agentId: string, bus: MessageBus) {\n    this.agentId = agentId;\n    this._bus = bus;\n    this._bus.register(agentId, (msg) => this._dispatch(msg));\n  }\n\n  onMessage(handler: MessageHandler): void {\n    this._handler = handler;\n  }\n\n  async send(to: string, partial: { type: string; payload: unknown }): Promise<void> {\n    return this._bus.send(this.agentId, to, partial);\n  }\n\n  async request(\n    to: string,\n    partial: { type: string; payload: unknown },\n    opts?: RequestOptions,\n  ): Promise<unknown> {\n    return this._bus.request(this.agentId, to, partial, opts);\n  }\n\n  dispose(): void {\n    this._bus.unregister(this.agentId);\n    this._handler = null;\n  }\n\n  private _dispatch(msg: A2AMessage): unknown {\n    if (this._handler) {\n      return this._handler(msg);\n    }\n  }\n}\n","/**\n * MessageBus — in-process typed message router for A2A (T20.1, ADR D453).\n *\n * Routes messages between agents by ID. Supports fire-and-forget (send)\n * and request/response (request with timeout).\n *\n * @public\n */\n\nimport type { A2AMessage, MessageHandler } from \"./types.js\";\n\nexport interface RequestOptions {\n  timeoutMs?: number;\n}\n\nexport class MessageBus {\n  private readonly _handlers = new Map<string, MessageHandler>();\n\n  register(agentId: string, handler: MessageHandler): void {\n    this._handlers.set(agentId, handler);\n  }\n\n  unregister(agentId: string): void {\n    this._handlers.delete(agentId);\n  }\n\n  async send(from: string, to: string, partial: { type: string; payload: unknown }): Promise<void> {\n    const handler = this._handlers.get(to);\n    if (!handler) {\n      throw new Error(`Agent \"${to}\" not registered on MessageBus`);\n    }\n    const message: A2AMessage = {\n      ...partial,\n      from,\n      to,\n      timestamp: Date.now(),\n      // SE3 — provenance projection of the sender address (thin view over `from`).\n      origin: { kind: \"peer\", from },\n    };\n    // Fire-and-forget: invoke handler but don't await result\n    handler(message);\n  }\n\n  async request(\n    from: string,\n    to: string,\n    partial: { type: string; payload: unknown },\n    opts?: RequestOptions,\n  ): Promise<unknown> {\n    const handler = this._handlers.get(to);\n    if (!handler) {\n      throw new Error(`Agent \"${to}\" not registered on MessageBus`);\n    }\n    const timeoutMs = opts?.timeoutMs ?? 30_000;\n    const message: A2AMessage = {\n      ...partial,\n      from,\n      to,\n      timestamp: Date.now(),\n      // SE3 — provenance projection of the sender address (thin view over `from`).\n      origin: { kind: \"peer\", from },\n    };\n    // Hold the timer so it can be cleared once the race settles — otherwise a\n    // successful request leaks a live `setTimeout` that keeps the Node event loop\n    // alive (the process hangs after the reply). Cleared in `finally`.\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    try {\n      return await Promise.race([\n        Promise.resolve(handler(message)),\n        new Promise((_, reject) => {\n          timer = setTimeout(\n            () =>\n              reject(new Error(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`)),\n            timeoutMs,\n          );\n        }),\n      ]);\n    } finally {\n      if (timer !== undefined) clearTimeout(timer);\n    }\n  }\n\n  has(agentId: string): boolean {\n    return this._handlers.has(agentId);\n  }\n\n  listAgents(): string[] {\n    return [...this._handlers.keys()];\n  }\n}\n"]}
+{"version":3,"sources":["../../src/a2a/agent-mailbox.ts","../../src/a2a/message-bus.ts"],"names":[],"mappings":";;;;;AAuCO,IAAM,eAAN,MAAmB;AAAA,EACf,OAAA;AAAA,EACQ,IAAA;AAAA,EACT,QAAA,GAAkC,IAAA;AAAA,EAE1C,WAAA,CAAY,SAAiB,GAAA,EAAiB;AAC5C,IAAA,IAAA,CAAK,OAAA,GAAU,OAAA;AACf,IAAA,IAAA,CAAK,IAAA,GAAO,GAAA;AACZ,IAAA,IAAA,CAAK,IAAA,CAAK,SAAS,OAAA,EAAS,CAAC,QAAQ,IAAA,CAAK,SAAA,CAAU,GAAG,CAAC,CAAA;AAAA,EAC1D;AAAA,EAEA,UAAU,OAAA,EAA+B;AACvC,IAAA,IAAA,CAAK,QAAA,GAAW,OAAA;AAAA,EAClB;AAAA,EAEA,MAAM,IAAA,CAAK,EAAA,EAAY,OAAA,EAA4D;AACjF,IAAA,OAAO,KAAK,IAAA,CAAK,IAAA,CAAK,IAAA,CAAK,OAAA,EAAS,IAAI,OAAO,CAAA;AAAA,EACjD;AAAA,EAEA,MAAM,OAAA,CACJ,EAAA,EACA,OAAA,EACA,IAAA,EACkB;AAClB,IAAA,OAAO,KAAK,IAAA,CAAK,OAAA,CAAQ,KAAK,OAAA,EAAS,EAAA,EAAI,SAAS,IAAI,CAAA;AAAA,EAC1D;AAAA,EAEA,OAAA,GAAgB;AACd,IAAA,IAAA,CAAK,IAAA,CAAK,UAAA,CAAW,IAAA,CAAK,OAAO,CAAA;AACjC,IAAA,IAAA,CAAK,QAAA,GAAW,IAAA;AAAA,EAClB;AAAA,EAEQ,UAAU,GAAA,EAA0B;AAC1C,IAAA,IAAI,KAAK,QAAA,EAAU;AACjB,MAAA,OAAO,IAAA,CAAK,SAAS,GAAG,CAAA;AAAA,IAC1B;AAAA,EACF;AACF;;;ACrBO,IAAM,aAAN,MAAiB;AAAA,EACL,SAAA,uBAAgB,GAAA,EAA4B;AAAA,EAE7D,QAAA,CAAS,SAAiB,OAAA,EAA+B;AACvD,IAAA,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,OAAA,EAAS,OAAO,CAAA;AAAA,EACrC;AAAA,EAEA,WAAW,OAAA,EAAuB;AAChC,IAAA,IAAA,CAAK,SAAA,CAAU,OAAO,OAAO,CAAA;AAAA,EAC/B;AAAA,EAEA,MAAM,IAAA,CAAK,IAAA,EAAc,EAAA,EAAY,OAAA,EAA4D;AAC/F,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,EAAE,CAAA;AACrC,IAAA,IAAI,CAAC,OAAA,EAAS;AACZ,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,OAAA,EAAU,EAAE,CAAA,8BAAA,CAAgC,CAAA;AAAA,IAC9D;AACA,IAAA,MAAM,OAAA,GAAsB;AAAA,MAC1B,GAAG,OAAA;AAAA,MACH,IAAA;AAAA,MACA,EAAA;AAAA,MACA,SAAA,EAAW,KAAK,GAAA,EAAI;AAAA;AAAA,MAEpB,MAAA,EAAQ,EAAE,IAAA,EAAM,MAAA,EAAQ,IAAA;AAAK,KAC/B;AAUA,IAAA,KAAK,OAAA,CAAQ,QAAQ,OAAA,CAAQ,OAAO,CAAC,CAAA,CAAE,KAAA,CAAM,CAAC,KAAA,KAAmB;AAC/D,MAAA,MAAM,SAAS,KAAA,YAAiB,KAAA,GAAQ,KAAA,CAAM,OAAA,GAAU,OAAO,KAAK,CAAA;AACpE,MAAA,IAAA,CAAK,CAAA,gCAAA,EAAmC,EAAE,CAAA,oCAAA,EAAuC,MAAM;AAAA,CAAI,CAAA;AAAA,IAC7F,CAAC,CAAA;AAAA,EACH;AAAA,EAEA,MAAM,OAAA,CACJ,IAAA,EACA,EAAA,EACA,SACA,IAAA,EACkB;AAClB,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,EAAE,CAAA;AACrC,IAAA,IAAI,CAAC,OAAA,EAAS;AACZ,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,OAAA,EAAU,EAAE,CAAA,8BAAA,CAAgC,CAAA;AAAA,IAC9D;AACA,IAAA,MAAM,SAAA,GAAY,MAAM,SAAA,IAAa,GAAA;AACrC,IAAA,MAAM,OAAA,GAAsB;AAAA,MAC1B,GAAG,OAAA;AAAA,MACH,IAAA;AAAA,MACA,EAAA;AAAA,MACA,SAAA,EAAW,KAAK,GAAA,EAAI;AAAA;AAAA,MAEpB,MAAA,EAAQ,EAAE,IAAA,EAAM,MAAA,EAAQ,IAAA;AAAK,KAC/B;AAIA,IAAA,IAAI,KAAA;AACJ,IAAA,IAAI;AACF,MAAA,OAAO,MAAM,QAAQ,IAAA,CAAK;AAAA,QACxB,OAAA,CAAQ,OAAA,CAAQ,OAAA,CAAQ,OAAO,CAAC,CAAA;AAAA,QAChC,IAAI,OAAA,CAAQ,CAAC,CAAA,EAAG,MAAA,KAAW;AACzB,UAAA,KAAA,GAAQ,UAAA;AAAA,YACN,MACE,OAAO,IAAI,KAAA,CAAM,wBAAwB,EAAE,CAAA,wBAAA,EAA2B,SAAS,CAAA,EAAA,CAAI,CAAC,CAAA;AAAA,YACtF;AAAA,WACF;AAAA,QACF,CAAC;AAAA,OACF,CAAA;AAAA,IACH,CAAA,SAAE;AACA,MAAA,IAAI,KAAA,KAAU,MAAA,EAAW,YAAA,CAAa,KAAK,CAAA;AAAA,IAC7C;AAAA,EACF;AAAA,EAEA,IAAI,OAAA,EAA0B;AAC5B,IAAA,OAAO,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,OAAO,CAAA;AAAA,EACnC;AAAA,EAEA,UAAA,GAAuB;AACrB,IAAA,OAAO,CAAC,GAAG,IAAA,CAAK,SAAA,CAAU,MAAM,CAAA;AAAA,EAClC;AACF","file":"index.js","sourcesContent":["/**\n * AgentMailbox — per-agent inbox for A2A communication (T20.1, ADR D453).\n *\n * Wraps MessageBus registration with a convenient API for sending,\n * receiving, and requesting messages.\n *\n * @public\n */\n\nimport type { MessageBus, RequestOptions } from \"./message-bus.js\";\nimport type { A2AMessage, MessageHandler } from \"./types.js\";\n\n/**\n * One agent's endpoint on a {@link MessageBus}: registers `agentId` on\n * construction and forwards inbound messages to the handler installed by\n * `onMessage`.\n *\n *   const mailbox = new AgentMailbox(\"worker\", bus);\n *   mailbox.onMessage((m) => `echo:${m.payload}`);\n *   await mailbox.send(\"boss\", { type: \"ready\", payload: null });\n *\n * Needs an already-constructed `MessageBus` — the mailbox does not create one, and\n * two mailboxes reach each other only through the SAME bus instance.\n *\n * How it fails: `send` and `request` are thin forwards, so they carry the bus's\n * failures unchanged (plain `Error` for an unregistered peer, plus a timeout\n * rejection for `request`).\n *\n * Traps:\n *  - The constructor registers IMMEDIATELY, before `onMessage` can be called. A\n *    message arriving in that window is dropped silently, and a peer's `request`\n *    RESOLVES WITH `undefined` instead of timing out — install the handler in the\n *    same tick as construction.\n *  - Constructing a second mailbox with the same `agentId` on the same bus takes\n *    the id over silently (`MessageBus.register` overwrites), and the loser's\n *    `dispose()` then unregisters the WINNER.\n *  - `dispose()` only unregisters and clears the handler. Requests already in\n *    flight are neither cancelled nor rejected; they time out on the caller's side.\n */\nexport class AgentMailbox {\n  readonly agentId: string;\n  private readonly _bus: MessageBus;\n  private _handler: MessageHandler | null = null;\n\n  constructor(agentId: string, bus: MessageBus) {\n    this.agentId = agentId;\n    this._bus = bus;\n    this._bus.register(agentId, (msg) => this._dispatch(msg));\n  }\n\n  onMessage(handler: MessageHandler): void {\n    this._handler = handler;\n  }\n\n  async send(to: string, partial: { type: string; payload: unknown }): Promise<void> {\n    return this._bus.send(this.agentId, to, partial);\n  }\n\n  async request(\n    to: string,\n    partial: { type: string; payload: unknown },\n    opts?: RequestOptions,\n  ): Promise<unknown> {\n    return this._bus.request(this.agentId, to, partial, opts);\n  }\n\n  dispose(): void {\n    this._bus.unregister(this.agentId);\n    this._handler = null;\n  }\n\n  private _dispatch(msg: A2AMessage): unknown {\n    if (this._handler) {\n      return this._handler(msg);\n    }\n  }\n}\n","/**\n * MessageBus — in-process typed message router for A2A (T20.1, ADR D453).\n *\n * Routes messages between agents by ID. Supports fire-and-forget (send)\n * and request/response (request with timeout).\n *\n * @public\n */\n\nimport { diag } from \"../internal/diagnostics.js\";\nimport type { A2AMessage, MessageHandler } from \"./types.js\";\n\n/**\n * Per-call knobs for {@link MessageBus.request} / `AgentMailbox.request`.\n */\nexport interface RequestOptions {\n  /**\n   * How long to wait for the peer handler to settle before rejecting.\n   * Default `30_000` (30 s). The rejection is a plain `Error` reading\n   * `A2A request timeout: <to> did not respond within <n>ms` — there is no typed\n   * timeout class and no `code` field, so a caller that must distinguish a\n   * timeout from a handler failure has to match on the message.\n   */\n  timeoutMs?: number;\n}\n\n/**\n * In-process router that delivers A2A messages between agents keyed by string id.\n *\n * Purely in-memory and single-process: nothing is persisted and nothing crosses a\n * process or network boundary. Register one handler per agent id, then `send`\n * (fire-and-forget) or `request` (await the handler's return value).\n *\n *   const bus = new MessageBus();\n *   bus.register(\"worker\", (m) => `echo:${m.payload}`);\n *   const reply = await bus.request(\"boss\", \"worker\", { type: \"ping\", payload: 1 });\n *\n * Callers supply only `{ type, payload }`; the bus stamps `from`, `to`,\n * `timestamp` and `origin` onto the delivered {@link A2AMessage}.\n *\n * How it fails: `send` and `request` both reject with a plain `Error`\n * (`Agent \"<to>\" not registered on MessageBus`) when `to` has no handler, and\n * `request` additionally rejects on timeout. No typed error class is exported for\n * either, so there is nothing to `instanceof`.\n *\n * Traps:\n *  - `register` silently OVERWRITES an existing id; the previous handler simply\n *    stops receiving anything. Call `has(id)` first when that matters.\n *  - `send` is declared `async` but never awaits the handler. A handler that\n *    rejects produces an UNHANDLED rejection that `await bus.send(...)` does not\n *    observe — only the \"not registered\" failure reaches the caller. Use\n *    `request` when the handler's failure has to be visible.\n *  - `from` is whatever the caller passes; the bus never checks that the sender\n *    is registered. It is self-asserted provenance, not authentication.\n */\nexport class MessageBus {\n  private readonly _handlers = new Map<string, MessageHandler>();\n\n  register(agentId: string, handler: MessageHandler): void {\n    this._handlers.set(agentId, handler);\n  }\n\n  unregister(agentId: string): void {\n    this._handlers.delete(agentId);\n  }\n\n  async send(from: string, to: string, partial: { type: string; payload: unknown }): Promise<void> {\n    const handler = this._handlers.get(to);\n    if (!handler) {\n      throw new Error(`Agent \"${to}\" not registered on MessageBus`);\n    }\n    const message: A2AMessage = {\n      ...partial,\n      from,\n      to,\n      timestamp: Date.now(),\n      // SE3 — provenance projection of the sender address (thin view over `from`).\n      origin: { kind: \"peer\", from },\n    };\n    // Fire-and-forget: the SENDER does not wait for the result, which is the whole point of\n    // `send`. It does not mean nobody is told when delivery fails — that is the difference\n    // between asynchronous and silent (#365).\n    //\n    // The returned promise used to be dropped on the floor. `MessageHandler` may return one, so a\n    // rejecting handler became an unhandled rejection: fatal under Node's default\n    // `--unhandled-rejections=throw`, and invisible to the caller, whose `await send(...)`\n    // resolved cleanly either way. Attaching a catch keeps the call non-blocking and reports the\n    // failure instead of discarding it (`error-handling.md` § 5).\n    void Promise.resolve(handler(message)).catch((cause: unknown) => {\n      const reason = cause instanceof Error ? cause.message : String(cause);\n      diag(`[theokit-sdk] a2a: handler for \"${to}\" failed on a fire-and-forget send: ${reason}\\n`);\n    });\n  }\n\n  async request(\n    from: string,\n    to: string,\n    partial: { type: string; payload: unknown },\n    opts?: RequestOptions,\n  ): Promise<unknown> {\n    const handler = this._handlers.get(to);\n    if (!handler) {\n      throw new Error(`Agent \"${to}\" not registered on MessageBus`);\n    }\n    const timeoutMs = opts?.timeoutMs ?? 30_000;\n    const message: A2AMessage = {\n      ...partial,\n      from,\n      to,\n      timestamp: Date.now(),\n      // SE3 — provenance projection of the sender address (thin view over `from`).\n      origin: { kind: \"peer\", from },\n    };\n    // Hold the timer so it can be cleared once the race settles — otherwise a\n    // successful request leaks a live `setTimeout` that keeps the Node event loop\n    // alive (the process hangs after the reply). Cleared in `finally`.\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    try {\n      return await Promise.race([\n        Promise.resolve(handler(message)),\n        new Promise((_, reject) => {\n          timer = setTimeout(\n            () =>\n              reject(new Error(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`)),\n            timeoutMs,\n          );\n        }),\n      ]);\n    } finally {\n      if (timer !== undefined) clearTimeout(timer);\n    }\n  }\n\n  has(agentId: string): boolean {\n    return this._handlers.has(agentId);\n  }\n\n  listAgents(): string[] {\n    return [...this._handlers.keys()];\n  }\n}\n"]}

package/dist/a2a/message-bus.d.cts

@@ -7,9 +7,48 @@
  * @public
  */
 import type { MessageHandler } from "./types.js";
+/**
+ * Per-call knobs for {@link MessageBus.request} / `AgentMailbox.request`.
+ */
 export interface RequestOptions {
+    /**
+     * How long to wait for the peer handler to settle before rejecting.
+     * Default `30_000` (30 s). The rejection is a plain `Error` reading
+     * `A2A request timeout: <to> did not respond within <n>ms` — there is no typed
+     * timeout class and no `code` field, so a caller that must distinguish a
+     * timeout from a handler failure has to match on the message.
+     */
     timeoutMs?: number;
 }
+/**
+ * In-process router that delivers A2A messages between agents keyed by string id.
+ *
+ * Purely in-memory and single-process: nothing is persisted and nothing crosses a
+ * process or network boundary. Register one handler per agent id, then `send`
+ * (fire-and-forget) or `request` (await the handler's return value).
+ *
+ *   const bus = new MessageBus();
+ *   bus.register("worker", (m) => `echo:${m.payload}`);
+ *   const reply = await bus.request("boss", "worker", { type: "ping", payload: 1 });
+ *
+ * Callers supply only `{ type, payload }`; the bus stamps `from`, `to`,
+ * `timestamp` and `origin` onto the delivered {@link A2AMessage}.
+ *
+ * How it fails: `send` and `request` both reject with a plain `Error`
+ * (`Agent "<to>" not registered on MessageBus`) when `to` has no handler, and
+ * `request` additionally rejects on timeout. No typed error class is exported for
+ * either, so there is nothing to `instanceof`.
+ *
+ * Traps:
+ *  - `register` silently OVERWRITES an existing id; the previous handler simply
+ *    stops receiving anything. Call `has(id)` first when that matters.
+ *  - `send` is declared `async` but never awaits the handler. A handler that
+ *    rejects produces an UNHANDLED rejection that `await bus.send(...)` does not
+ *    observe — only the "not registered" failure reaches the caller. Use
+ *    `request` when the handler's failure has to be visible.
+ *  - `from` is whatever the caller passes; the bus never checks that the sender
+ *    is registered. It is self-asserted provenance, not authentication.
+ */
 export declare class MessageBus {
     private readonly _handlers;
     register(agentId: string, handler: MessageHandler): void;

package/dist/a2a/message-bus.d.ts

@@ -7,9 +7,48 @@
  * @public
  */
 import type { MessageHandler } from "./types.js";
+/**
+ * Per-call knobs for {@link MessageBus.request} / `AgentMailbox.request`.
+ */
 export interface RequestOptions {
+    /**
+     * How long to wait for the peer handler to settle before rejecting.
+     * Default `30_000` (30 s). The rejection is a plain `Error` reading
+     * `A2A request timeout: <to> did not respond within <n>ms` — there is no typed
+     * timeout class and no `code` field, so a caller that must distinguish a
+     * timeout from a handler failure has to match on the message.
+     */
     timeoutMs?: number;
 }
+/**
+ * In-process router that delivers A2A messages between agents keyed by string id.
+ *
+ * Purely in-memory and single-process: nothing is persisted and nothing crosses a
+ * process or network boundary. Register one handler per agent id, then `send`
+ * (fire-and-forget) or `request` (await the handler's return value).
+ *
+ *   const bus = new MessageBus();
+ *   bus.register("worker", (m) => `echo:${m.payload}`);
+ *   const reply = await bus.request("boss", "worker", { type: "ping", payload: 1 });
+ *
+ * Callers supply only `{ type, payload }`; the bus stamps `from`, `to`,
+ * `timestamp` and `origin` onto the delivered {@link A2AMessage}.
+ *
+ * How it fails: `send` and `request` both reject with a plain `Error`
+ * (`Agent "<to>" not registered on MessageBus`) when `to` has no handler, and
+ * `request` additionally rejects on timeout. No typed error class is exported for
+ * either, so there is nothing to `instanceof`.
+ *
+ * Traps:
+ *  - `register` silently OVERWRITES an existing id; the previous handler simply
+ *    stops receiving anything. Call `has(id)` first when that matters.
+ *  - `send` is declared `async` but never awaits the handler. A handler that
+ *    rejects produces an UNHANDLED rejection that `await bus.send(...)` does not
+ *    observe — only the "not registered" failure reaches the caller. Use
+ *    `request` when the handler's failure has to be visible.
+ *  - `from` is whatever the caller passes; the bus never checks that the sender
+ *    is registered. It is self-asserted provenance, not authentication.
+ */
 export declare class MessageBus {
     private readonly _handlers;
     register(agentId: string, handler: MessageHandler): void;

package/dist/a2a/subagent.d.cts

@@ -3,7 +3,10 @@
  *
  * Per ADR D2: `defineSubAgent(spec)` returns a `CustomTool` that, when
  * invoked by the LLM, creates a child agent and sends the input as a
- * message. EC-2: delegation depth tracked to prevent infinite recursion.
+ * message. EC-2: delegation depth is tracked across the RUN (#364) — each
+ * delegation publishes its depth on the async scope its child executes in, so a
+ * subagent that delegates to a subagent is bounded by `maxDelegationDepth`
+ * without the caller threading a counter by hand.
  *
  * SE10 — the handler forwards the parent run's `AbortSignal` to the child.
  * SE11 — optional `onDelegationStart` / `onDelegationComplete` lifecycle hooks
@@ -70,6 +73,46 @@ export interface DelegationCompleteDecision {
     /** Appended to the child's result string. */
     feedback?: string;
 }
+/**
+ * The declaration of a delegating child agent, handed to `SubAgent.create(spec)`.
+ *
+ * `name`, `description` and `instructions` are the only required fields: the first
+ * two become the tool the supervisor's model sees, the third becomes the child's
+ * system prompt. Everything else narrows what the child inherits.
+ *
+ *   const research = SubAgent.create({
+ *     name: "research",
+ *     description: "Look a fact up",
+ *     instructions: "You answer with one sentence.",
+ *   });
+ *   const agent = await Agent.create({ tools: [research] });
+ *
+ * The tool's own input schema is fixed — one required string property, `input`.
+ * It is not derived from this spec and cannot be widened here.
+ *
+ * What the child inherits from the parent AT DISPATCH TIME, not from this object:
+ * the API key, the model (unless `model` is set), the parent's plugins, and the
+ * parent's sandbox posture (unless `sandbox` is set). An absent `sandbox` inherits;
+ * an explicit `sandbox: false` turns confinement OFF for a child of a confined
+ * parent, which is not the same thing.
+ *
+ * How it fails: the child's failure is re-thrown to the supervisor as a tool error
+ * — a run ending in `status: "error"` becomes
+ * `subagent "<name>" run failed: <cause>`. `onDelegationStart` and `messageFilter`
+ * propagate their own throws; only a throw from `onDelegationComplete` ON THE
+ * ERROR PATH is suppressed, so it cannot mask the real cause.
+ *
+ * Traps:
+ *  - `model` as a bare string drops reasoning parameters. Pass the
+ *    {@link ModelSelection} object form when the child needs `params`.
+ *  - `maxDelegationDepth` (default 3) bounds the delegation CHAIN, counted at
+ *    dispatch across the run (#364) — the depth is not something you thread. The
+ *    `parentDepth` argument of `SubAgent.create` still offsets it, for a supervisor
+ *    that wants a lower ceiling than the chain it sits in.
+ *  - Context isolation is the DEFAULT. Without `messageFilter` the child sees only
+ *    the delegated string; without `includeToolResults` the supervisor gets only
+ *    the child's final text.
+ */
 export interface SubAgentSpec {
     name: string;
     description: string;
@@ -84,6 +127,11 @@ export interface SubAgentSpec {
     tools?: CustomTool[];
     /** Per-subagent shell sandbox toggle (M33). `true` ⇒ child `local.sandboxOptions.enabled`. */
     sandbox?: boolean;
+    /**
+     * Maximum length of the delegation CHAIN rooted at this tool, counted at dispatch
+     * (default 3). Depth 1 is this subagent; a subagent it delegates to is depth 2.
+     * Exceeding it throws {@link MaxDelegationDepthError} from the tool handler.
+     */
     maxDelegationDepth?: number;
     /**
      * SE11 — called before the supervisor delegates. Return `{ proceed: false }`
@@ -119,18 +167,31 @@ export interface SubAgentSpec {
      */
     includeToolResults?: boolean;
 }
+/**
+ * Raised by `SubAgent.create(spec, parentDepth)` when `parentDepth + 1` exceeds
+ * `spec.maxDelegationDepth` (default 3). Carries `currentDepth`, `maxDepth` and a
+ * stable `code: "max_delegation_depth"`.
+ *
+ * Thrown from the subagent tool's handler when a delegation would exceed
+ * `maxDelegationDepth` (default 3), so it surfaces as the tool call's failure —
+ * catching it around the dispatching `agent.send()` works.
+ *
+ * Also thrown eagerly at TOOL-CONSTRUCTION time when a caller threads its own
+ * `parentDepth` that is already past the limit; such a tool could never be
+ * dispatched, so refusing to build it fails earlier and clearer.
+ *
+ * Before #364 the construction-time check was the ONLY one, against a depth
+ * nothing in the SDK incremented — so under the documented `SubAgent.create(spec)`
+ * call this error could not fire at all and nested delegation was unbounded. The
+ * chain length now travels with the run (`internal/runtime/concurrency/delegation-depth.ts`),
+ * and a caller-threaded `parentDepth` still adds to it.
+ */
 export declare class MaxDelegationDepthError extends Error {
     readonly currentDepth: number;
     readonly maxDepth: number;
     readonly code: "max_delegation_depth";
     constructor(currentDepth: number, maxDepth: number);
 }
-/**
- * Create the transient child agent and send the input, composing every forwarded
- * `SendOptions` onto ONE `send` call — SE10 `signal` + SE13 `maxIterations`. Absent
- * every option ⇒ the pre-SE10 single-arg `send(input)` shape. SE14 — when
- * `includeToolResults` is set, append the child's completed tool results. Dispose in `finally`.
- */
 /**
  * Build the child agent's `Agent.create` options: the child inherits the parent's
  * apiKey (else `Agent.create` throws "Missing API key"), its model (unless the spec

package/dist/a2a/subagent.d.ts

@@ -3,7 +3,10 @@
  *
  * Per ADR D2: `defineSubAgent(spec)` returns a `CustomTool` that, when
  * invoked by the LLM, creates a child agent and sends the input as a
- * message. EC-2: delegation depth tracked to prevent infinite recursion.
+ * message. EC-2: delegation depth is tracked across the RUN (#364) — each
+ * delegation publishes its depth on the async scope its child executes in, so a
+ * subagent that delegates to a subagent is bounded by `maxDelegationDepth`
+ * without the caller threading a counter by hand.
  *
  * SE10 — the handler forwards the parent run's `AbortSignal` to the child.
  * SE11 — optional `onDelegationStart` / `onDelegationComplete` lifecycle hooks
@@ -70,6 +73,46 @@ export interface DelegationCompleteDecision {
     /** Appended to the child's result string. */
     feedback?: string;
 }
+/**
+ * The declaration of a delegating child agent, handed to `SubAgent.create(spec)`.
+ *
+ * `name`, `description` and `instructions` are the only required fields: the first
+ * two become the tool the supervisor's model sees, the third becomes the child's
+ * system prompt. Everything else narrows what the child inherits.
+ *
+ *   const research = SubAgent.create({
+ *     name: "research",
+ *     description: "Look a fact up",
+ *     instructions: "You answer with one sentence.",
+ *   });
+ *   const agent = await Agent.create({ tools: [research] });
+ *
+ * The tool's own input schema is fixed — one required string property, `input`.
+ * It is not derived from this spec and cannot be widened here.
+ *
+ * What the child inherits from the parent AT DISPATCH TIME, not from this object:
+ * the API key, the model (unless `model` is set), the parent's plugins, and the
+ * parent's sandbox posture (unless `sandbox` is set). An absent `sandbox` inherits;
+ * an explicit `sandbox: false` turns confinement OFF for a child of a confined
+ * parent, which is not the same thing.
+ *
+ * How it fails: the child's failure is re-thrown to the supervisor as a tool error
+ * — a run ending in `status: "error"` becomes
+ * `subagent "<name>" run failed: <cause>`. `onDelegationStart` and `messageFilter`
+ * propagate their own throws; only a throw from `onDelegationComplete` ON THE
+ * ERROR PATH is suppressed, so it cannot mask the real cause.
+ *
+ * Traps:
+ *  - `model` as a bare string drops reasoning parameters. Pass the
+ *    {@link ModelSelection} object form when the child needs `params`.
+ *  - `maxDelegationDepth` (default 3) bounds the delegation CHAIN, counted at
+ *    dispatch across the run (#364) — the depth is not something you thread. The
+ *    `parentDepth` argument of `SubAgent.create` still offsets it, for a supervisor
+ *    that wants a lower ceiling than the chain it sits in.
+ *  - Context isolation is the DEFAULT. Without `messageFilter` the child sees only
+ *    the delegated string; without `includeToolResults` the supervisor gets only
+ *    the child's final text.
+ */
 export interface SubAgentSpec {
     name: string;
     description: string;
@@ -84,6 +127,11 @@ export interface SubAgentSpec {
     tools?: CustomTool[];
     /** Per-subagent shell sandbox toggle (M33). `true` ⇒ child `local.sandboxOptions.enabled`. */
     sandbox?: boolean;
+    /**
+     * Maximum length of the delegation CHAIN rooted at this tool, counted at dispatch
+     * (default 3). Depth 1 is this subagent; a subagent it delegates to is depth 2.
+     * Exceeding it throws {@link MaxDelegationDepthError} from the tool handler.
+     */
     maxDelegationDepth?: number;
     /**
      * SE11 — called before the supervisor delegates. Return `{ proceed: false }`
@@ -119,18 +167,31 @@ export interface SubAgentSpec {
      */
     includeToolResults?: boolean;
 }
+/**
+ * Raised by `SubAgent.create(spec, parentDepth)` when `parentDepth + 1` exceeds
+ * `spec.maxDelegationDepth` (default 3). Carries `currentDepth`, `maxDepth` and a
+ * stable `code: "max_delegation_depth"`.
+ *
+ * Thrown from the subagent tool's handler when a delegation would exceed
+ * `maxDelegationDepth` (default 3), so it surfaces as the tool call's failure —
+ * catching it around the dispatching `agent.send()` works.
+ *
+ * Also thrown eagerly at TOOL-CONSTRUCTION time when a caller threads its own
+ * `parentDepth` that is already past the limit; such a tool could never be
+ * dispatched, so refusing to build it fails earlier and clearer.
+ *
+ * Before #364 the construction-time check was the ONLY one, against a depth
+ * nothing in the SDK incremented — so under the documented `SubAgent.create(spec)`
+ * call this error could not fire at all and nested delegation was unbounded. The
+ * chain length now travels with the run (`internal/runtime/concurrency/delegation-depth.ts`),
+ * and a caller-threaded `parentDepth` still adds to it.
+ */
 export declare class MaxDelegationDepthError extends Error {
     readonly currentDepth: number;
     readonly maxDepth: number;
     readonly code: "max_delegation_depth";
     constructor(currentDepth: number, maxDepth: number);
 }
-/**
- * Create the transient child agent and send the input, composing every forwarded
- * `SendOptions` onto ONE `send` call — SE10 `signal` + SE13 `maxIterations`. Absent
- * every option ⇒ the pre-SE10 single-arg `send(input)` shape. SE14 — when
- * `includeToolResults` is set, append the child's completed tool results. Dispose in `finally`.
- */
 /**
  * Build the child agent's `Agent.create` options: the child inherits the parent's
  * apiKey (else `Agent.create` throws "Missing API key"), its model (unless the spec