@theokit/sdk 0.0.0-compat-580-20260905204608

package/dist/a2a/index.js

@@ -0,0 +1,125 @@
+export { MaxDelegationDepthError, SubAgent } from '../chunk-CFE6QF2Q.js';
+import '../chunk-6X6ID4MO.js';
+import { TheokitAgentError } from '../chunk-ALUN2B4W.js';
+import { diag } from '../chunk-CZJ6Q7CW.js';
+
+// src/a2a/agent-mailbox.ts
+var AgentMailbox = class {
+  agentId;
+  _bus;
+  _handler = null;
+  constructor(agentId, bus) {
+    this.agentId = agentId;
+    this._bus = bus;
+    this._bus.register(agentId, (msg) => this._dispatch(msg));
+  }
+  onMessage(handler) {
+    this._handler = handler;
+  }
+  async send(to, partial) {
+    return this._bus.send(this.agentId, to, partial);
+  }
+  async request(to, partial, opts) {
+    return this._bus.request(this.agentId, to, partial, opts);
+  }
+  dispose() {
+    this._bus.unregister(this.agentId);
+    this._handler = null;
+  }
+  _dispatch(msg) {
+    if (this._handler === null) return void 0;
+    return this._handler(msg);
+  }
+};
+
+// src/a2a/message-bus.ts
+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`, {
+      code: "a2a_request_timeout",
+      isRetryable: true
+    });
+    this.to = to;
+    this.timeoutMs = timeoutMs;
+  }
+  to;
+  timeoutMs;
+  name = "A2ARequestTimeoutError";
+  code = "a2a_request_timeout";
+};
+var MessageBus = class {
+  _handlers = /* @__PURE__ */ new Map();
+  register(agentId, handler) {
+    this._handlers.set(agentId, handler);
+  }
+  unregister(agentId) {
+    this._handlers.delete(agentId);
+  }
+  async send(from, to, partial) {
+    const handler = this._handlers.get(to);
+    if (!handler) {
+      throw new A2APeerNotRegisteredError(to);
+    }
+    const message = {
+      ...partial,
+      from,
+      to,
+      timestamp: Date.now(),
+      // SE3 — provenance projection of the sender address (thin view over `from`).
+      origin: { kind: "peer", from }
+    };
+    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);
+    if (!handler) {
+      throw new A2APeerNotRegisteredError(to);
+    }
+    const timeoutMs = opts?.timeoutMs ?? 3e4;
+    const message = {
+      ...partial,
+      from,
+      to,
+      timestamp: Date.now(),
+      // SE3 — provenance projection of the sender address (thin view over `from`).
+      origin: { kind: "peer", from }
+    };
+    let timer;
+    try {
+      return await Promise.race([
+        Promise.resolve(handler(message)),
+        new Promise((_, reject) => {
+          timer = setTimeout(() => reject(new A2ARequestTimeoutError(to, timeoutMs)), timeoutMs);
+        })
+      ]);
+    } finally {
+      if (timer !== void 0) clearTimeout(timer);
+    }
+  }
+  has(agentId) {
+    return this._handlers.has(agentId);
+  }
+  listAgents() {
+    return [...this._handlers.keys()];
+  }
+};
+
+export { A2APeerNotRegisteredError, A2ARequestTimeoutError, AgentMailbox, MessageBus };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/a2a/index.js.map

@@ -0,0 +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    // 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

@@ -0,0 +1,118 @@
+/**
+ * MessageBus — in-process typed message router for A2A (T20.1, ADR D453).
+ *
+ * Routes messages between agents by ID. Supports fire-and-forget (send)
+ * and request/response (request with timeout).
+ *
+ * @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.
+ *
+ * Carries `code: "a2a_request_timeout"`, the peer's address and the limit as FIELDS, so a caller
+ * branches on the contract rather than on prose — `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." Until #380 this rejection was a plain `Error` with neither, and the message it
+ * carried embeds both the address and the limit, so matching on it changed with context exactly as
+ * that document warns.
+ *
+ * The distinction it restores is what a retry policy is built on. A peer that did not answer in
+ * time is transient and worth retrying; a peer whose handler threw is likely deterministic and
+ * retrying repeats the failure. A handler's own error propagates unchanged and is NOT this type —
+ * an unattended agent can therefore tell the two apart without reading English.
+ *
+ * @public
+ */
+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. */
+    to: string, 
+    /** The limit it exceeded, in milliseconds. */
+    timeoutMs: number);
+}
+/**
+ * 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 an {@link A2ARequestTimeoutError} carrying
+     * `code: "a2a_request_timeout"`, `to` and `timeoutMs` (#380), so a caller distinguishes a
+     * timeout from a handler failure by branching on the code — a handler's own error propagates
+     * unchanged and is not that type.
+     */
+    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 {@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`.
+ *
+ * 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;
+    unregister(agentId: string): void;
+    send(from: string, to: string, partial: {
+        type: string;
+        payload: unknown;
+    }): Promise<void>;
+    request(from: string, to: string, partial: {
+        type: string;
+        payload: unknown;
+    }, opts?: RequestOptions): Promise<unknown>;
+    has(agentId: string): boolean;
+    listAgents(): string[];
+}

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

@@ -0,0 +1,118 @@
+/**
+ * MessageBus — in-process typed message router for A2A (T20.1, ADR D453).
+ *
+ * Routes messages between agents by ID. Supports fire-and-forget (send)
+ * and request/response (request with timeout).
+ *
+ * @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.
+ *
+ * Carries `code: "a2a_request_timeout"`, the peer's address and the limit as FIELDS, so a caller
+ * branches on the contract rather than on prose — `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." Until #380 this rejection was a plain `Error` with neither, and the message it
+ * carried embeds both the address and the limit, so matching on it changed with context exactly as
+ * that document warns.
+ *
+ * The distinction it restores is what a retry policy is built on. A peer that did not answer in
+ * time is transient and worth retrying; a peer whose handler threw is likely deterministic and
+ * retrying repeats the failure. A handler's own error propagates unchanged and is NOT this type —
+ * an unattended agent can therefore tell the two apart without reading English.
+ *
+ * @public
+ */
+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. */
+    to: string, 
+    /** The limit it exceeded, in milliseconds. */
+    timeoutMs: number);
+}
+/**
+ * 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 an {@link A2ARequestTimeoutError} carrying
+     * `code: "a2a_request_timeout"`, `to` and `timeoutMs` (#380), so a caller distinguishes a
+     * timeout from a handler failure by branching on the code — a handler's own error propagates
+     * unchanged and is not that type.
+     */
+    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 {@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`.
+ *
+ * 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;
+    unregister(agentId: string): void;
+    send(from: string, to: string, partial: {
+        type: string;
+        payload: unknown;
+    }): Promise<void>;
+    request(from: string, to: string, partial: {
+        type: string;
+        payload: unknown;
+    }, opts?: RequestOptions): Promise<unknown>;
+    has(agentId: string): boolean;
+    listAgents(): string[];
+}

package/dist/a2a/subagent.d.cts

@@ -0,0 +1,231 @@
+/**
+ * Subagent delegation — declarative child agent invocable as a tool.
+ *
+ * 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 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
+ * let the caller reject, rewrite, observe, or annotate a delegation.
+ *
+ * @public
+ */
+import { TheokitAgentError } from "../errors.js";
+import { type InheritedCredentials } from "../internal/concurrency/subagent-credentials.js";
+import type { AgentOptions, BuiltinToolName, CustomTool, ToolContextMessage } from "../types/agent.js";
+import type { ModelSelection } from "../types/agent-prims.js";
+/** Arguments passed to {@link SubAgentSpec.messageFilter} (SE12). */
+export interface MessageFilterArgs {
+    /** The supervisor transcript (read-only text projection) available to this delegation. */
+    messages: readonly ToolContextMessage[];
+    /** The prompt about to be delegated (after any `onDelegationStart` rewrite). */
+    input: string;
+    /** The subagent's name. */
+    name: string;
+}
+/** Context passed to {@link SubAgentSpec.onDelegationStart} before the child runs. */
+export interface DelegationStartContext {
+    input: string;
+    name: string;
+    /**
+     * SE15 — 1-based count of times THIS subagent tool has been invoked (a
+     * per-`defineSubAgent`-instance counter). Incremented before this hook runs;
+     * a rejected delegation still counts. Enables reject-after-N patterns.
+     */
+    iteration: number;
+}
+/**
+ * Decision returned from {@link SubAgentSpec.onDelegationStart}. Discriminated on
+ * `proceed` so a rejection (`proceed: false` + `rejectionReason`) and an approval
+ * (`modifiedInput`) cannot be mixed into one nonsensical object.
+ */
+export type DelegationStartDecision = {
+    proceed: false;
+    rejectionReason?: string;
+} | {
+    proceed?: true;
+    modifiedInput?: string;
+    /** SE13 — cap the child's iteration count (forwarded as `SendOptions.maxIterations`). */
+    modifiedMaxSteps?: number;
+};
+/** Context passed to {@link SubAgentSpec.onDelegationComplete} after the child settles. */
+export interface DelegationCompleteContext {
+    input: string;
+    name: string;
+    /** The child's text result (present on success). */
+    result?: string;
+    /** The error the child threw (present on failure); the error is still re-thrown. */
+    error?: unknown;
+    /** SE15 — the same 1-based iteration this delegation's `onDelegationStart` saw. */
+    iteration: number;
+}
+/**
+ * The return of a delegation hook: a decision, a promise of one, or nothing —
+ * `void` lets a side-effect-only callback (`(ctx) => { log(ctx) }`) type-check,
+ * which is the common case (mirrors a peer framework's `async ctx => { ... }` hooks).
+ */
+type DelegationHookResult<T> = T | void | Promise<T | void>;
+/** Decision returned from {@link SubAgentSpec.onDelegationComplete}. */
+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;
+    instructions: string;
+    /**
+     * A bare id string (back-compat) OR a full {@link ModelSelection} carrying
+     * `params` (e.g. `[{ id: "thinking", value: "low" }]` for reasoning effort). The
+     * object form is required for per-subagent reasoning effort to survive to the child
+     * — the pre-M33 path took only `.id` and dropped params.
+     */
+    model?: string | ModelSelection;
+    tools?: CustomTool[];
+    /** Per-subagent shell sandbox toggle (M33). `true` ⇒ child `local.sandboxOptions.enabled`. */
+    sandbox?: boolean;
+    /**
+     * #580 — builtin tools this role removes from its child's catalog, UNIONED with whatever the
+     * parent already withheld.
+     *
+     * A role declared read-only in prose is not read-only: a `shell` tool is always registered on a
+     * local agent, including when `tools: []` is passed, so withholding is the only mechanism that
+     * removes it — and until #580 a spec could not ask for it and a parent's withholding did not
+     * survive delegation either.
+     *
+     * ## Union, not override — and this is the one field here that works that way
+     *
+     * `model` and `sandbox` let the role's own value WIN, including `sandbox: false` turning
+     * confinement off for a child of a confined parent. That asymmetry is deliberate: a posture is
+     * declared, whereas withholding removes a capability from the catalog. Letting a role override a
+     * withholding would let a child recover a tool its parent revoked, which is the defect #580
+     * reports — so a child may only ever ADD to the set.
+     */
+    withheldBuiltinTools?: readonly BuiltinToolName[];
+    /**
+     * 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 }`
+     * to reject (the child never runs and `rejectionReason` becomes the tool
+     * result), or `{ modifiedInput }` to rewrite the delegated prompt. A throwing
+     * hook surfaces (never silently swallowed).
+     */
+    onDelegationStart?: (ctx: DelegationStartContext) => DelegationHookResult<DelegationStartDecision>;
+    /**
+     * SE11 — called after the delegation settles. On success `ctx.result` is set
+     * and an optional `{ feedback }` is appended to it. On failure `ctx.error` is
+     * set and the original error is ALWAYS re-thrown after this hook runs — a throw
+     * from this hook on the error path is suppressed so it cannot mask the
+     * delegation's real failure (on the success path a throw does propagate).
+     */
+    onDelegationComplete?: (ctx: DelegationCompleteContext) => DelegationHookResult<DelegationCompleteDecision>;
+    /**
+     * SE12 — opt-in parent-context forwarding. When set, the supervisor transcript
+     * (`ctx.messages`, a read-only text projection) is passed to this filter and the
+     * returned subset is forwarded to the child as a role-tagged context preamble
+     * prepended to the delegated input. When ABSENT the child runs input-only —
+     * memory isolation stays the default. A filter returning `[]` forwards nothing.
+     * A throwing filter propagates (fail-fast, never swallowed — same contract as
+     * `onDelegationStart`); the delegation surfaces as a tool error.
+     */
+    messageFilter?: (args: MessageFilterArgs) => readonly ToolContextMessage[];
+    /**
+     * SE14 — opt-in subagent result-context control. When `true`, the child's
+     * completed tool-call results (name + result) are appended to the delegation
+     * payload returned to the supervisor, inside a `<subagent-tool-results>` block.
+     * When absent/`false` the delegation returns the child's final text only —
+     * text-only stays the default (a peer framework's scoped posture). See ADR 0006.
+     */
+    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 TheokitAgentError {
+    readonly currentDepth: number;
+    readonly maxDepth: number;
+    readonly name = "MaxDelegationDepthError";
+    readonly code: "max_delegation_depth";
+    constructor(currentDepth: number, maxDepth: number);
+}
+/**
+ * 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
+ * overrides it), — #55 — the parent's plugins (permission gate/guards) so the
+ * child's inner tool calls run under the same policy, and — #578 — the configuration
+ * surfaces the parent was declared to read (see {@link buildChildLocalOptions}).
+ */
+export declare function buildChildCreateOptions(spec: SubAgentSpec, inherited: InheritedCredentials | undefined): AgentOptions;
+/** 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;
+}
+export {};