@theokit/sdk 4.63.4 → 5.0.0-next.2

package/dist/a2a/index.cjs

@@ -1,8 +1,9 @@
 'use strict';
 
-var chunk4O5TGQBW_cjs = require('../chunk-4O5TGQBW.cjs');
+var chunkQME6FDFG_cjs = require('../chunk-QME6FDFG.cjs');
 require('../chunk-NINIJCHU.cjs');
-var chunkEG4QM7ZJ_cjs = require('../chunk-EG4QM7ZJ.cjs');
+var chunkJ7J7J2GN_cjs = require('../chunk-J7J7J2GN.cjs');
+var chunk6LHQPOMI_cjs = require('../chunk-6LHQPOMI.cjs');
 
 // src/a2a/agent-mailbox.ts
 var AgentMailbox = class {
@@ -28,22 +29,36 @@ var AgentMailbox = class {
     this._handler = null;
   }
   _dispatch(msg) {
-    if (this._handler) {
-      return this._handler(msg);
-    }
+    if (this._handler === null) return void 0;
+    return this._handler(msg);
   }
 };
 
 // src/a2a/message-bus.ts
-var A2ARequestTimeoutError = class extends Error {
+var A2APeerNotRegisteredError = class extends chunkJ7J7J2GN_cjs.TheokitAgentError {
+  constructor(to) {
+    super(`Agent "${to}" not registered on MessageBus`, {
+      code: "a2a_peer_not_registered",
+      isRetryable: false
+    });
+    this.to = to;
+  }
+  to;
+  name = "A2APeerNotRegisteredError";
+  code = "a2a_peer_not_registered";
+};
+var A2ARequestTimeoutError = class extends chunkJ7J7J2GN_cjs.TheokitAgentError {
   constructor(to, timeoutMs) {
-    super(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`);
+    super(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`, {
+      code: "a2a_request_timeout",
+      isRetryable: true
+    });
     this.to = to;
     this.timeoutMs = timeoutMs;
-    this.name = "A2ARequestTimeoutError";
   }
   to;
   timeoutMs;
+  name = "A2ARequestTimeoutError";
   code = "a2a_request_timeout";
 };
 var MessageBus = class {
@@ -57,7 +72,7 @@ var MessageBus = class {
   async send(from, to, partial) {
     const handler = this._handlers.get(to);
     if (!handler) {
-      throw new Error(`Agent "${to}" not registered on MessageBus`);
+      throw new A2APeerNotRegisteredError(to);
     }
     const message = {
       ...partial,
@@ -69,14 +84,14 @@ var MessageBus = class {
     };
     void Promise.resolve(handler(message)).catch((cause) => {
       const reason = cause instanceof Error ? cause.message : String(cause);
-      chunkEG4QM7ZJ_cjs.diag(`[theokit-sdk] a2a: handler for "${to}" failed on a fire-and-forget send: ${reason}
+      chunk6LHQPOMI_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);
     if (!handler) {
-      throw new Error(`Agent "${to}" not registered on MessageBus`);
+      throw new A2APeerNotRegisteredError(to);
     }
     const timeoutMs = opts?.timeoutMs ?? 3e4;
     const message = {
@@ -109,12 +124,13 @@ var MessageBus = class {
 
 Object.defineProperty(exports, "MaxDelegationDepthError", {
   enumerable: true,
-  get: function () { return chunk4O5TGQBW_cjs.MaxDelegationDepthError; }
+  get: function () { return chunkQME6FDFG_cjs.MaxDelegationDepthError; }
 });
 Object.defineProperty(exports, "SubAgent", {
   enumerable: true,
-  get: function () { return chunk4O5TGQBW_cjs.SubAgent; }
+  get: function () { return chunkQME6FDFG_cjs.SubAgent; }
 });
+exports.A2APeerNotRegisteredError = A2APeerNotRegisteredError;
 exports.A2ARequestTimeoutError = A2ARequestTimeoutError;
 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":["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 * A peer did not answer a {@link MessageBus.request} within its timeout.\n *\n * Carries `code: \"a2a_request_timeout\"`, the peer's address and the limit as FIELDS, so a caller\n * branches on the contract rather than on prose — `docs/error-codes.md`: \"Branch on `code`, never\n * on the message: messages carry context (an id, a path, a limit) and change with it, while a code\n * is the contract.\" Until #380 this rejection was a plain `Error` with neither, and the message it\n * carried embeds both the address and the limit, so matching on it changed with context exactly as\n * that document warns.\n *\n * The distinction it restores is what a retry policy is built on. A peer that did not answer in\n * time is transient and worth retrying; a peer whose handler threw is likely deterministic and\n * retrying repeats the failure. A handler's own error propagates unchanged and is NOT this type —\n * an unattended agent can therefore tell the two apart without reading English.\n *\n * @public\n */\nexport class A2ARequestTimeoutError extends Error {\n  readonly code = \"a2a_request_timeout\" as const;\n  constructor(\n    /** The peer that did not answer. */\n    public readonly to: string,\n    /** The limit it exceeded, in milliseconds. */\n    public readonly timeoutMs: number,\n  ) {\n    super(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`);\n    this.name = \"A2ARequestTimeoutError\";\n  }\n}\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 an {@link A2ARequestTimeoutError} carrying\n   * `code: \"a2a_request_timeout\"`, `to` and `timeoutMs` (#380), so a caller distinguishes a\n   * timeout from a handler failure by branching on the code — a handler's own error propagates\n   * unchanged and is not that type.\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(() => reject(new A2ARequestTimeoutError(to, timeoutMs)), timeoutMs);\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":["TheokitAgentError","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    // A disposed mailbox is still registered until the bus drops it, so a\n    // message can arrive with no handler. `undefined` is the reply in that\n    // case, and saying so explicitly is what lets `noImplicitReturns` hold.\n    if (this._handler === null) return undefined;\n    return this._handler(msg);\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 { TheokitAgentError } from \"../errors.js\";\nimport { diag } from \"../internal/diagnostics.js\";\nimport type { A2AMessage, MessageHandler } from \"./types.js\";\n\n/**\n * Thrown by {@link MessageBus.send} and {@link MessageBus.request} when `to` has no registered\n * handler.\n *\n * The sibling below records why a typed error was introduced for the TIMEOUT, quoting\n * `docs/error-codes.md`: \"Branch on `code`, never on the message: messages carry context (an id, a\n * path, a limit) and change with it, while a code is the contract.\" This failure had exactly the\n * shape that reasoning rejects — a bare `Error` whose message embeds the address — in the FIRST\n * branch of the same two methods whose second branch was fixed.\n *\n * @public\n */\nexport class A2APeerNotRegisteredError extends TheokitAgentError {\n  override readonly name = \"A2APeerNotRegisteredError\";\n  override readonly code = \"a2a_peer_not_registered\" as const;\n\n  constructor(\n    /** The address with no registered handler. */\n    public readonly to: string,\n  ) {\n    // Not retryable: a peer registers or it does not, and re-sending does not register it. A caller\n    // that expects it to appear should await registration, not retry the send.\n    super(`Agent \"${to}\" not registered on MessageBus`, {\n      code: \"a2a_peer_not_registered\",\n      isRetryable: false,\n    });\n  }\n}\n\n/**\n * A peer did not answer a {@link MessageBus.request} within its timeout.\n *\n * Carries `code: \"a2a_request_timeout\"`, the peer's address and the limit as FIELDS, so a caller\n * branches on the contract rather than on prose — `docs/error-codes.md`: \"Branch on `code`, never\n * on the message: messages carry context (an id, a path, a limit) and change with it, while a code\n * is the contract.\" Until #380 this rejection was a plain `Error` with neither, and the message it\n * carried embeds both the address and the limit, so matching on it changed with context exactly as\n * that document warns.\n *\n * The distinction it restores is what a retry policy is built on. A peer that did not answer in\n * time is transient and worth retrying; a peer whose handler threw is likely deterministic and\n * retrying repeats the failure. A handler's own error propagates unchanged and is NOT this type —\n * an unattended agent can therefore tell the two apart without reading English.\n *\n * @public\n */\nexport class A2ARequestTimeoutError extends TheokitAgentError {\n  override readonly name = \"A2ARequestTimeoutError\";\n  override readonly code = \"a2a_request_timeout\" as const;\n  constructor(\n    /** The peer that did not answer. */\n    public readonly to: string,\n    /** The limit it exceeded, in milliseconds. */\n    public readonly timeoutMs: number,\n  ) {\n    // Retryable: a peer that missed one deadline may answer the next request.\n    super(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`, {\n      code: \"a2a_request_timeout\",\n      isRetryable: true,\n    });\n  }\n}\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 an {@link A2ARequestTimeoutError} carrying\n   * `code: \"a2a_request_timeout\"`, `to` and `timeoutMs` (#380), so a caller distinguishes a\n   * timeout from a handler failure by branching on the code — a handler's own error propagates\n   * unchanged and is not that type.\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 {@link A2APeerNotRegisteredError}\n * (code `a2a_peer_not_registered`, carrying `to`) 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 A2APeerNotRegisteredError(to);\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 A2APeerNotRegisteredError(to);\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(() => reject(new A2ARequestTimeoutError(to, timeoutMs)), timeoutMs);\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.d.cts

@@ -5,6 +5,6 @@
  */
 export type { ToolContextMessage } from "../types/agent-prims.js";
 export { AgentMailbox } from "./agent-mailbox.js";
-export { A2ARequestTimeoutError, MessageBus, type RequestOptions } from "./message-bus.js";
+export { A2APeerNotRegisteredError, A2ARequestTimeoutError, MessageBus, type RequestOptions, } from "./message-bus.js";
 export { type DelegationCompleteContext, type DelegationCompleteDecision, type DelegationStartContext, type DelegationStartDecision, MaxDelegationDepthError, type MessageFilterArgs, SubAgent, type SubAgentSpec, } from "./subagent.js";
 export type { A2AMessage, MessageHandler } from "./types.js";

package/dist/a2a/index.d.ts

@@ -5,6 +5,6 @@
  */
 export type { ToolContextMessage } from "../types/agent-prims.js";
 export { AgentMailbox } from "./agent-mailbox.js";
-export { A2ARequestTimeoutError, MessageBus, type RequestOptions } from "./message-bus.js";
+export { A2APeerNotRegisteredError, A2ARequestTimeoutError, MessageBus, type RequestOptions, } from "./message-bus.js";
 export { type DelegationCompleteContext, type DelegationCompleteDecision, type DelegationStartContext, type DelegationStartDecision, MaxDelegationDepthError, type MessageFilterArgs, SubAgent, type SubAgentSpec, } from "./subagent.js";
 export type { A2AMessage, MessageHandler } from "./types.js";

package/dist/a2a/index.js

@@ -1,6 +1,7 @@
-export { MaxDelegationDepthError, SubAgent } from '../chunk-RNB4APBZ.js';
+export { MaxDelegationDepthError, SubAgent } from '../chunk-6WAKKTBO.js';
 import '../chunk-6X6ID4MO.js';
-import { diag } from '../chunk-XEQ3TM66.js';
+import { TheokitAgentError } from '../chunk-ALUN2B4W.js';
+import { diag } from '../chunk-CZJ6Q7CW.js';
 
 // src/a2a/agent-mailbox.ts
 var AgentMailbox = class {
@@ -26,22 +27,36 @@ var AgentMailbox = class {
     this._handler = null;
   }
   _dispatch(msg) {
-    if (this._handler) {
-      return this._handler(msg);
-    }
+    if (this._handler === null) return void 0;
+    return this._handler(msg);
   }
 };
 
 // src/a2a/message-bus.ts
-var A2ARequestTimeoutError = class extends Error {
+var A2APeerNotRegisteredError = class extends TheokitAgentError {
+  constructor(to) {
+    super(`Agent "${to}" not registered on MessageBus`, {
+      code: "a2a_peer_not_registered",
+      isRetryable: false
+    });
+    this.to = to;
+  }
+  to;
+  name = "A2APeerNotRegisteredError";
+  code = "a2a_peer_not_registered";
+};
+var A2ARequestTimeoutError = class extends TheokitAgentError {
   constructor(to, timeoutMs) {
-    super(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`);
+    super(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`, {
+      code: "a2a_request_timeout",
+      isRetryable: true
+    });
     this.to = to;
     this.timeoutMs = timeoutMs;
-    this.name = "A2ARequestTimeoutError";
   }
   to;
   timeoutMs;
+  name = "A2ARequestTimeoutError";
   code = "a2a_request_timeout";
 };
 var MessageBus = class {
@@ -55,7 +70,7 @@ var MessageBus = class {
   async send(from, to, partial) {
     const handler = this._handlers.get(to);
     if (!handler) {
-      throw new Error(`Agent "${to}" not registered on MessageBus`);
+      throw new A2APeerNotRegisteredError(to);
     }
     const message = {
       ...partial,
@@ -74,7 +89,7 @@ var MessageBus = class {
   async request(from, to, partial, opts) {
     const handler = this._handlers.get(to);
     if (!handler) {
-      throw new Error(`Agent "${to}" not registered on MessageBus`);
+      throw new A2APeerNotRegisteredError(to);
     }
     const timeoutMs = opts?.timeoutMs ?? 3e4;
     const message = {
@@ -105,6 +120,6 @@ var MessageBus = class {
   }
 };
 
-export { A2ARequestTimeoutError, AgentMailbox, MessageBus };
+export { A2APeerNotRegisteredError, A2ARequestTimeoutError, AgentMailbox, MessageBus };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

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\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 * A peer did not answer a {@link MessageBus.request} within its timeout.\n *\n * Carries `code: \"a2a_request_timeout\"`, the peer's address and the limit as FIELDS, so a caller\n * branches on the contract rather than on prose — `docs/error-codes.md`: \"Branch on `code`, never\n * on the message: messages carry context (an id, a path, a limit) and change with it, while a code\n * is the contract.\" Until #380 this rejection was a plain `Error` with neither, and the message it\n * carried embeds both the address and the limit, so matching on it changed with context exactly as\n * that document warns.\n *\n * The distinction it restores is what a retry policy is built on. A peer that did not answer in\n * time is transient and worth retrying; a peer whose handler threw is likely deterministic and\n * retrying repeats the failure. A handler's own error propagates unchanged and is NOT this type —\n * an unattended agent can therefore tell the two apart without reading English.\n *\n * @public\n */\nexport class A2ARequestTimeoutError extends Error {\n  readonly code = \"a2a_request_timeout\" as const;\n  constructor(\n    /** The peer that did not answer. */\n    public readonly to: string,\n    /** The limit it exceeded, in milliseconds. */\n    public readonly timeoutMs: number,\n  ) {\n    super(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`);\n    this.name = \"A2ARequestTimeoutError\";\n  }\n}\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 an {@link A2ARequestTimeoutError} carrying\n   * `code: \"a2a_request_timeout\"`, `to` and `timeoutMs` (#380), so a caller distinguishes a\n   * timeout from a handler failure by branching on the code — a handler's own error propagates\n   * unchanged and is not that type.\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(() => reject(new A2ARequestTimeoutError(to, timeoutMs)), timeoutMs);\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":"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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\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    // A disposed mailbox is still registered until the bus drops it, so a\n    // message can arrive with no handler. `undefined` is the reply in that\n    // case, and saying so explicitly is what lets `noImplicitReturns` hold.\n    if (this._handler === null) return undefined;\n    return this._handler(msg);\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 { TheokitAgentError } from \"../errors.js\";\nimport { diag } from \"../internal/diagnostics.js\";\nimport type { A2AMessage, MessageHandler } from \"./types.js\";\n\n/**\n * Thrown by {@link MessageBus.send} and {@link MessageBus.request} when `to` has no registered\n * handler.\n *\n * The sibling below records why a typed error was introduced for the TIMEOUT, quoting\n * `docs/error-codes.md`: \"Branch on `code`, never on the message: messages carry context (an id, a\n * path, a limit) and change with it, while a code is the contract.\" This failure had exactly the\n * shape that reasoning rejects — a bare `Error` whose message embeds the address — in the FIRST\n * branch of the same two methods whose second branch was fixed.\n *\n * @public\n */\nexport class A2APeerNotRegisteredError extends TheokitAgentError {\n  override readonly name = \"A2APeerNotRegisteredError\";\n  override readonly code = \"a2a_peer_not_registered\" as const;\n\n  constructor(\n    /** The address with no registered handler. */\n    public readonly to: string,\n  ) {\n    // Not retryable: a peer registers or it does not, and re-sending does not register it. A caller\n    // that expects it to appear should await registration, not retry the send.\n    super(`Agent \"${to}\" not registered on MessageBus`, {\n      code: \"a2a_peer_not_registered\",\n      isRetryable: false,\n    });\n  }\n}\n\n/**\n * A peer did not answer a {@link MessageBus.request} within its timeout.\n *\n * Carries `code: \"a2a_request_timeout\"`, the peer's address and the limit as FIELDS, so a caller\n * branches on the contract rather than on prose — `docs/error-codes.md`: \"Branch on `code`, never\n * on the message: messages carry context (an id, a path, a limit) and change with it, while a code\n * is the contract.\" Until #380 this rejection was a plain `Error` with neither, and the message it\n * carried embeds both the address and the limit, so matching on it changed with context exactly as\n * that document warns.\n *\n * The distinction it restores is what a retry policy is built on. A peer that did not answer in\n * time is transient and worth retrying; a peer whose handler threw is likely deterministic and\n * retrying repeats the failure. A handler's own error propagates unchanged and is NOT this type —\n * an unattended agent can therefore tell the two apart without reading English.\n *\n * @public\n */\nexport class A2ARequestTimeoutError extends TheokitAgentError {\n  override readonly name = \"A2ARequestTimeoutError\";\n  override readonly code = \"a2a_request_timeout\" as const;\n  constructor(\n    /** The peer that did not answer. */\n    public readonly to: string,\n    /** The limit it exceeded, in milliseconds. */\n    public readonly timeoutMs: number,\n  ) {\n    // Retryable: a peer that missed one deadline may answer the next request.\n    super(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`, {\n      code: \"a2a_request_timeout\",\n      isRetryable: true,\n    });\n  }\n}\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 an {@link A2ARequestTimeoutError} carrying\n   * `code: \"a2a_request_timeout\"`, `to` and `timeoutMs` (#380), so a caller distinguishes a\n   * timeout from a handler failure by branching on the code — a handler's own error propagates\n   * unchanged and is not that type.\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 {@link A2APeerNotRegisteredError}\n * (code `a2a_peer_not_registered`, carrying `to`) 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 A2APeerNotRegisteredError(to);\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 A2APeerNotRegisteredError(to);\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(() => reject(new A2ARequestTimeoutError(to, timeoutMs)), timeoutMs);\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

@@ -6,7 +6,29 @@
  *
  * @public
  */
+import { TheokitAgentError } from "../errors.js";
 import type { MessageHandler } from "./types.js";
+/**
+ * Thrown by {@link MessageBus.send} and {@link MessageBus.request} when `to` has no registered
+ * handler.
+ *
+ * The sibling below records why a typed error was introduced for the TIMEOUT, quoting
+ * `docs/error-codes.md`: "Branch on `code`, never on the message: messages carry context (an id, a
+ * path, a limit) and change with it, while a code is the contract." This failure had exactly the
+ * shape that reasoning rejects — a bare `Error` whose message embeds the address — in the FIRST
+ * branch of the same two methods whose second branch was fixed.
+ *
+ * @public
+ */
+export declare class A2APeerNotRegisteredError extends TheokitAgentError {
+    /** The address with no registered handler. */
+    readonly to: string;
+    readonly name = "A2APeerNotRegisteredError";
+    readonly code: "a2a_peer_not_registered";
+    constructor(
+    /** The address with no registered handler. */
+    to: string);
+}
 /**
  * A peer did not answer a {@link MessageBus.request} within its timeout.
  *
@@ -24,11 +46,12 @@ import type { MessageHandler } from "./types.js";
  *
  * @public
  */
-export declare class A2ARequestTimeoutError extends Error {
+export declare class A2ARequestTimeoutError extends TheokitAgentError {
     /** The peer that did not answer. */
     readonly to: string;
     /** The limit it exceeded, in milliseconds. */
     readonly timeoutMs: number;
+    readonly name = "A2ARequestTimeoutError";
     readonly code: "a2a_request_timeout";
     constructor(
     /** The peer that did not answer. */
@@ -63,8 +86,8 @@ export interface RequestOptions {
  * 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
+ * How it fails: `send` and `request` both reject with {@link A2APeerNotRegisteredError}
+ * (code `a2a_peer_not_registered`, carrying `to`) 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`.
  *

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

@@ -6,7 +6,29 @@
  *
  * @public
  */
+import { TheokitAgentError } from "../errors.js";
 import type { MessageHandler } from "./types.js";
+/**
+ * Thrown by {@link MessageBus.send} and {@link MessageBus.request} when `to` has no registered
+ * handler.
+ *
+ * The sibling below records why a typed error was introduced for the TIMEOUT, quoting
+ * `docs/error-codes.md`: "Branch on `code`, never on the message: messages carry context (an id, a
+ * path, a limit) and change with it, while a code is the contract." This failure had exactly the
+ * shape that reasoning rejects — a bare `Error` whose message embeds the address — in the FIRST
+ * branch of the same two methods whose second branch was fixed.
+ *
+ * @public
+ */
+export declare class A2APeerNotRegisteredError extends TheokitAgentError {
+    /** The address with no registered handler. */
+    readonly to: string;
+    readonly name = "A2APeerNotRegisteredError";
+    readonly code: "a2a_peer_not_registered";
+    constructor(
+    /** The address with no registered handler. */
+    to: string);
+}
 /**
  * A peer did not answer a {@link MessageBus.request} within its timeout.
  *
@@ -24,11 +46,12 @@ import type { MessageHandler } from "./types.js";
  *
  * @public
  */
-export declare class A2ARequestTimeoutError extends Error {
+export declare class A2ARequestTimeoutError extends TheokitAgentError {
     /** The peer that did not answer. */
     readonly to: string;
     /** The limit it exceeded, in milliseconds. */
     readonly timeoutMs: number;
+    readonly name = "A2ARequestTimeoutError";
     readonly code: "a2a_request_timeout";
     constructor(
     /** The peer that did not answer. */
@@ -63,8 +86,8 @@ export interface RequestOptions {
  * 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
+ * How it fails: `send` and `request` both reject with {@link A2APeerNotRegisteredError}
+ * (code `a2a_peer_not_registered`, carrying `to`) 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`.
  *

package/dist/a2a/subagent.d.cts

@@ -14,7 +14,8 @@
  *
  * @public
  */
-import { type InheritedCredentials } from "../internal/runtime/concurrency/subagent-credentials.js";
+import { TheokitAgentError } from "../errors.js";
+import { type InheritedCredentials } from "../internal/concurrency/subagent-credentials.js";
 import type { AgentOptions, CustomTool, ToolContextMessage } from "../types/agent.js";
 import type { ModelSelection } from "../types/agent-prims.js";
 /** Arguments passed to {@link SubAgentSpec.messageFilter} (SE12). */
@@ -186,9 +187,10 @@ export interface SubAgentSpec {
  * 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 {
+export declare class MaxDelegationDepthError extends TheokitAgentError {
     readonly currentDepth: number;
     readonly maxDepth: number;
+    readonly name = "MaxDelegationDepthError";
     readonly code: "max_delegation_depth";
     constructor(currentDepth: number, maxDepth: number);
 }
@@ -199,7 +201,10 @@ export declare class MaxDelegationDepthError extends Error {
  * child's inner tool calls run under the same policy.
  */
 export declare function buildChildCreateOptions(spec: SubAgentSpec, inherited: InheritedCredentials | undefined): AgentOptions;
-/** SE36 — `SubAgent.create` replaces `defineSubAgent` (ADR 0015). @public */
+/** SE36 — `SubAgent.create` replaces `defineSubAgent` (ADR 0015). @public  *
+ * `SubAgent.create` returns a **`CustomTool`** — the sub-agent is exposed to the
+ * parent as a callable tool, not as a `SubAgent` instance.
+ */
 export declare class SubAgent {
     private constructor();
     static create(spec: SubAgentSpec, parentDepth?: number): CustomTool;

package/dist/a2a/subagent.d.ts

@@ -14,7 +14,8 @@
  *
  * @public
  */
-import { type InheritedCredentials } from "../internal/runtime/concurrency/subagent-credentials.js";
+import { TheokitAgentError } from "../errors.js";
+import { type InheritedCredentials } from "../internal/concurrency/subagent-credentials.js";
 import type { AgentOptions, CustomTool, ToolContextMessage } from "../types/agent.js";
 import type { ModelSelection } from "../types/agent-prims.js";
 /** Arguments passed to {@link SubAgentSpec.messageFilter} (SE12). */
@@ -186,9 +187,10 @@ export interface SubAgentSpec {
  * 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 {
+export declare class MaxDelegationDepthError extends TheokitAgentError {
     readonly currentDepth: number;
     readonly maxDepth: number;
+    readonly name = "MaxDelegationDepthError";
     readonly code: "max_delegation_depth";
     constructor(currentDepth: number, maxDepth: number);
 }
@@ -199,7 +201,10 @@ export declare class MaxDelegationDepthError extends Error {
  * child's inner tool calls run under the same policy.
  */
 export declare function buildChildCreateOptions(spec: SubAgentSpec, inherited: InheritedCredentials | undefined): AgentOptions;
-/** SE36 — `SubAgent.create` replaces `defineSubAgent` (ADR 0015). @public */
+/** SE36 — `SubAgent.create` replaces `defineSubAgent` (ADR 0015). @public  *
+ * `SubAgent.create` returns a **`CustomTool`** — the sub-agent is exposed to the
+ * parent as a callable tool, not as a `SubAgent` instance.
+ */
 export declare class SubAgent {
     private constructor();
     static create(spec: SubAgentSpec, parentDepth?: number): CustomTool;