@theokit/sdk 4.55.0 → 4.56.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 4.56.0
+
+### Minor Changes
+
+- b08f696: `MessageBus.request` now rejects a timeout with `A2ARequestTimeoutError`, carrying
+  `code: "a2a_request_timeout"` plus the peer's address and the limit as fields.
+
+  It used to reject with a plain `Error` and no code, so the only way to identify a timeout was to
+  match the message — the practice `docs/error-codes.md` tells consumers never to rely on, and that
+  message embeds the address and the limit, so it changes with context exactly as the document warns.
+
+  The distinction this restores is what a retry policy is built on: a peer that did not answer is
+  transient and worth retrying, a peer whose handler threw is likely deterministic. A handler's own
+  error still propagates unchanged and is not this type.
+
+- f7e70e4: The memory store now writes the layout the Claude Code CLI reads.
+
+  This SDK's differentiator is that it emits the formats that CLI opens — point `local.sessionDir` at
+  `~/.claude` and `--continue` a session your agent wrote. Memory did not hold that line: a fact was a
+  bullet under `## Facts`, so pointing a memory directory at `~/.claude/projects/<project>/memory/`
+  produced nothing the CLI could read.
+
+  Now each memory is its own file with the frontmatter Claude Code writes — `name`, `description`, and
+  `metadata` carrying `type` and an ISO 8601 `modified` — and `MEMORY.md` is the index that points at
+  them.
+
+  Legacy `## Facts` bullets are still read, so no store loses what it recorded. The brief encoding that
+  put a fact's kind in a trailing HTML comment never reached a published version, so there is nothing
+  to migrate from it.
+
+  `parseSimpleYaml` also stops flattening nested maps: `metadata:` with indented keys used to yield
+  `metadata: []` plus the nested keys as top-level entries, so `metadata.type` read as `undefined`
+  while `type` appeared where it never was.
+
+- 5036f04: A memory fact can now say what it IS and when it was learned.
+
+  `MemoryFact` gains an optional `kind` — `user`, `feedback`, `project` or `reference` — and a
+  `modified` timestamp. Without them a durable preference and a project note that went stale were
+  indistinguishable: no staleness signal, no way for recall to filter, no basis for selective
+  retention, and no way for a surface to separate "what I remember about you" from "what I know about
+  this project".
+
+  Additive, so existing stores keep working. A hand-written bullet under `## Facts` still parses and
+  stays untyped — a kind is never inferred, because a wrong one makes recall confident about the wrong
+  thing. `modified` is stamped by the SDK and ignored when supplied by a caller: a timestamp a caller
+  can set is one that can lie about when something was learned.
+
+### Patch Changes
+
+- 7587c00: A confined command that spawns a child no longer loses its output.
+
+  The restricted-network seccomp filter denied `getsockname`, `getpeername`, `setsockopt` and
+  `getsockopt`. Those four take an already-open fd, and cBPF cannot dereference one to learn its
+  address family — so they were denied on AF_UNIX too, which is what libuv uses for a child's IPC
+  channel. Any command that spawned a child died, and the parent's buffered stdout died with it:
+  `node --test` returned zero lines through `shell_exec`, and an agent reading test output saw an
+  empty string.
+
+  The four leave the denied set. Everything that takes an address or changes an fd's role —
+  `connect`, `bind`, `listen`, `accept`, `accept4`, `sendto`, `sendmmsg`, `recvmmsg`, `shutdown` —
+  stays denied, and `socket()` still refuses every family but AF_UNIX. Measured across the fix: an
+  AF_INET socket is `EPERM` before and after.
+
 ## 4.55.0
 
 ### Minor Changes

package/dist/a2a/index.cjs

@@ -35,6 +35,17 @@ var AgentMailbox = class {
 };
 
 // src/a2a/message-bus.ts
+var A2ARequestTimeoutError = class extends Error {
+  constructor(to, timeoutMs) {
+    super(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`);
+    this.to = to;
+    this.timeoutMs = timeoutMs;
+    this.name = "A2ARequestTimeoutError";
+  }
+  to;
+  timeoutMs;
+  code = "a2a_request_timeout";
+};
 var MessageBus = class {
   _handlers = /* @__PURE__ */ new Map();
   register(agentId, handler) {
@@ -81,10 +92,7 @@ var MessageBus = class {
       return await Promise.race([
         Promise.resolve(handler(message)),
         new Promise((_, reject) => {
-          timer = setTimeout(
-            () => reject(new Error(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`)),
-            timeoutMs
-          );
+          timer = setTimeout(() => reject(new A2ARequestTimeoutError(to, timeoutMs)), timeoutMs);
         })
       ]);
     } finally {
@@ -107,6 +115,7 @@ Object.defineProperty(exports, "SubAgent", {
   enumerable: true,
   get: function () { return chunk4O5TGQBW_cjs.SubAgent; }
 });
+exports.A2ARequestTimeoutError = A2ARequestTimeoutError;
 exports.AgentMailbox = AgentMailbox;
 exports.MessageBus = MessageBus;
 //# sourceMappingURL=index.cjs.map

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 * Per-call knobs for {@link MessageBus.request} / `AgentMailbox.request`.\n */\nexport interface RequestOptions {\n  /**\n   * How long to wait for the peer handler to settle before rejecting.\n   * Default `30_000` (30 s). The rejection is a plain `Error` reading\n   * `A2A request timeout: <to> did not respond within <n>ms` — there is no typed\n   * timeout class and no `code` field, so a caller that must distinguish a\n   * timeout from a handler failure has to match on the message.\n   */\n  timeoutMs?: number;\n}\n\n/**\n * In-process router that delivers A2A messages between agents keyed by string id.\n *\n * Purely in-memory and single-process: nothing is persisted and nothing crosses a\n * process or network boundary. Register one handler per agent id, then `send`\n * (fire-and-forget) or `request` (await the handler's return value).\n *\n *   const bus = new MessageBus();\n *   bus.register(\"worker\", (m) => `echo:${m.payload}`);\n *   const reply = await bus.request(\"boss\", \"worker\", { type: \"ping\", payload: 1 });\n *\n * Callers supply only `{ type, payload }`; the bus stamps `from`, `to`,\n * `timestamp` and `origin` onto the delivered {@link A2AMessage}.\n *\n * How it fails: `send` and `request` both reject with a plain `Error`\n * (`Agent \"<to>\" not registered on MessageBus`) when `to` has no handler, and\n * `request` additionally rejects on timeout. No typed error class is exported for\n * either, so there is nothing to `instanceof`.\n *\n * Traps:\n *  - `register` silently OVERWRITES an existing id; the previous handler simply\n *    stops receiving anything. Call `has(id)` first when that matters.\n *  - `send` is declared `async` but never awaits the handler. A handler that\n *    rejects produces an UNHANDLED rejection that `await bus.send(...)` does not\n *    observe — only the \"not registered\" failure reaches the caller. Use\n *    `request` when the handler's failure has to be visible.\n *  - `from` is whatever the caller passes; the bus never checks that the sender\n *    is registered. It is self-asserted provenance, not authentication.\n */\nexport class MessageBus {\n  private readonly _handlers = new Map<string, MessageHandler>();\n\n  register(agentId: string, handler: MessageHandler): void {\n    this._handlers.set(agentId, handler);\n  }\n\n  unregister(agentId: string): void {\n    this._handlers.delete(agentId);\n  }\n\n  async send(from: string, to: string, partial: { type: string; payload: unknown }): Promise<void> {\n    const handler = this._handlers.get(to);\n    if (!handler) {\n      throw new Error(`Agent \"${to}\" not registered on MessageBus`);\n    }\n    const message: A2AMessage = {\n      ...partial,\n      from,\n      to,\n      timestamp: Date.now(),\n      // SE3 — provenance projection of the sender address (thin view over `from`).\n      origin: { kind: \"peer\", from },\n    };\n    // Fire-and-forget: the SENDER does not wait for the result, which is the whole point of\n    // `send`. It does not mean nobody is told when delivery fails — that is the difference\n    // between asynchronous and silent (#365).\n    //\n    // The returned promise used to be dropped on the floor. `MessageHandler` may return one, so a\n    // rejecting handler became an unhandled rejection: fatal under Node's default\n    // `--unhandled-rejections=throw`, and invisible to the caller, whose `await send(...)`\n    // resolved cleanly either way. Attaching a catch keeps the call non-blocking and reports the\n    // failure instead of discarding it (`error-handling.md` § 5).\n    void Promise.resolve(handler(message)).catch((cause: unknown) => {\n      const reason = cause instanceof Error ? cause.message : String(cause);\n      diag(`[theokit-sdk] a2a: handler for \"${to}\" failed on a fire-and-forget send: ${reason}\\n`);\n    });\n  }\n\n  async request(\n    from: string,\n    to: string,\n    partial: { type: string; payload: unknown },\n    opts?: RequestOptions,\n  ): Promise<unknown> {\n    const handler = this._handlers.get(to);\n    if (!handler) {\n      throw new Error(`Agent \"${to}\" not registered on MessageBus`);\n    }\n    const timeoutMs = opts?.timeoutMs ?? 30_000;\n    const message: A2AMessage = {\n      ...partial,\n      from,\n      to,\n      timestamp: Date.now(),\n      // SE3 — provenance projection of the sender address (thin view over `from`).\n      origin: { kind: \"peer\", from },\n    };\n    // Hold the timer so it can be cleared once the race settles — otherwise a\n    // successful request leaks a live `setTimeout` that keeps the Node event loop\n    // alive (the process hangs after the reply). Cleared in `finally`.\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    try {\n      return await Promise.race([\n        Promise.resolve(handler(message)),\n        new Promise((_, reject) => {\n          timer = setTimeout(\n            () =>\n              reject(new Error(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`)),\n            timeoutMs,\n          );\n        }),\n      ]);\n    } finally {\n      if (timer !== undefined) clearTimeout(timer);\n    }\n  }\n\n  has(agentId: string): boolean {\n    return this._handlers.has(agentId);\n  }\n\n  listAgents(): string[] {\n    return [...this._handlers.keys()];\n  }\n}\n"]}
+{"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"]}

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 { MessageBus, type RequestOptions } from "./message-bus.js";
+export { 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 { MessageBus, type RequestOptions } from "./message-bus.js";
+export { 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

@@ -33,6 +33,17 @@ var AgentMailbox = class {
 };
 
 // src/a2a/message-bus.ts
+var A2ARequestTimeoutError = class extends Error {
+  constructor(to, timeoutMs) {
+    super(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`);
+    this.to = to;
+    this.timeoutMs = timeoutMs;
+    this.name = "A2ARequestTimeoutError";
+  }
+  to;
+  timeoutMs;
+  code = "a2a_request_timeout";
+};
 var MessageBus = class {
   _handlers = /* @__PURE__ */ new Map();
   register(agentId, handler) {
@@ -79,10 +90,7 @@ var MessageBus = class {
       return await Promise.race([
         Promise.resolve(handler(message)),
         new Promise((_, reject) => {
-          timer = setTimeout(
-            () => reject(new Error(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`)),
-            timeoutMs
-          );
+          timer = setTimeout(() => reject(new A2ARequestTimeoutError(to, timeoutMs)), timeoutMs);
         })
       ]);
     } finally {
@@ -97,6 +105,6 @@ var MessageBus = class {
   }
 };
 
-export { AgentMailbox, MessageBus };
+export { 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 * Per-call knobs for {@link MessageBus.request} / `AgentMailbox.request`.\n */\nexport interface RequestOptions {\n  /**\n   * How long to wait for the peer handler to settle before rejecting.\n   * Default `30_000` (30 s). The rejection is a plain `Error` reading\n   * `A2A request timeout: <to> did not respond within <n>ms` — there is no typed\n   * timeout class and no `code` field, so a caller that must distinguish a\n   * timeout from a handler failure has to match on the message.\n   */\n  timeoutMs?: number;\n}\n\n/**\n * In-process router that delivers A2A messages between agents keyed by string id.\n *\n * Purely in-memory and single-process: nothing is persisted and nothing crosses a\n * process or network boundary. Register one handler per agent id, then `send`\n * (fire-and-forget) or `request` (await the handler's return value).\n *\n *   const bus = new MessageBus();\n *   bus.register(\"worker\", (m) => `echo:${m.payload}`);\n *   const reply = await bus.request(\"boss\", \"worker\", { type: \"ping\", payload: 1 });\n *\n * Callers supply only `{ type, payload }`; the bus stamps `from`, `to`,\n * `timestamp` and `origin` onto the delivered {@link A2AMessage}.\n *\n * How it fails: `send` and `request` both reject with a plain `Error`\n * (`Agent \"<to>\" not registered on MessageBus`) when `to` has no handler, and\n * `request` additionally rejects on timeout. No typed error class is exported for\n * either, so there is nothing to `instanceof`.\n *\n * Traps:\n *  - `register` silently OVERWRITES an existing id; the previous handler simply\n *    stops receiving anything. Call `has(id)` first when that matters.\n *  - `send` is declared `async` but never awaits the handler. A handler that\n *    rejects produces an UNHANDLED rejection that `await bus.send(...)` does not\n *    observe — only the \"not registered\" failure reaches the caller. Use\n *    `request` when the handler's failure has to be visible.\n *  - `from` is whatever the caller passes; the bus never checks that the sender\n *    is registered. It is self-asserted provenance, not authentication.\n */\nexport class MessageBus {\n  private readonly _handlers = new Map<string, MessageHandler>();\n\n  register(agentId: string, handler: MessageHandler): void {\n    this._handlers.set(agentId, handler);\n  }\n\n  unregister(agentId: string): void {\n    this._handlers.delete(agentId);\n  }\n\n  async send(from: string, to: string, partial: { type: string; payload: unknown }): Promise<void> {\n    const handler = this._handlers.get(to);\n    if (!handler) {\n      throw new Error(`Agent \"${to}\" not registered on MessageBus`);\n    }\n    const message: A2AMessage = {\n      ...partial,\n      from,\n      to,\n      timestamp: Date.now(),\n      // SE3 — provenance projection of the sender address (thin view over `from`).\n      origin: { kind: \"peer\", from },\n    };\n    // Fire-and-forget: the SENDER does not wait for the result, which is the whole point of\n    // `send`. It does not mean nobody is told when delivery fails — that is the difference\n    // between asynchronous and silent (#365).\n    //\n    // The returned promise used to be dropped on the floor. `MessageHandler` may return one, so a\n    // rejecting handler became an unhandled rejection: fatal under Node's default\n    // `--unhandled-rejections=throw`, and invisible to the caller, whose `await send(...)`\n    // resolved cleanly either way. Attaching a catch keeps the call non-blocking and reports the\n    // failure instead of discarding it (`error-handling.md` § 5).\n    void Promise.resolve(handler(message)).catch((cause: unknown) => {\n      const reason = cause instanceof Error ? cause.message : String(cause);\n      diag(`[theokit-sdk] a2a: handler for \"${to}\" failed on a fire-and-forget send: ${reason}\\n`);\n    });\n  }\n\n  async request(\n    from: string,\n    to: string,\n    partial: { type: string; payload: unknown },\n    opts?: RequestOptions,\n  ): Promise<unknown> {\n    const handler = this._handlers.get(to);\n    if (!handler) {\n      throw new Error(`Agent \"${to}\" not registered on MessageBus`);\n    }\n    const timeoutMs = opts?.timeoutMs ?? 30_000;\n    const message: A2AMessage = {\n      ...partial,\n      from,\n      to,\n      timestamp: Date.now(),\n      // SE3 — provenance projection of the sender address (thin view over `from`).\n      origin: { kind: \"peer\", from },\n    };\n    // Hold the timer so it can be cleared once the race settles — otherwise a\n    // successful request leaks a live `setTimeout` that keeps the Node event loop\n    // alive (the process hangs after the reply). Cleared in `finally`.\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    try {\n      return await Promise.race([\n        Promise.resolve(handler(message)),\n        new Promise((_, reject) => {\n          timer = setTimeout(\n            () =>\n              reject(new Error(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`)),\n            timeoutMs,\n          );\n        }),\n      ]);\n    } finally {\n      if (timer !== undefined) clearTimeout(timer);\n    }\n  }\n\n  has(agentId: string): boolean {\n    return this._handlers.has(agentId);\n  }\n\n  listAgents(): string[] {\n    return [...this._handlers.keys()];\n  }\n}\n"]}
+{"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"]}

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

@@ -7,16 +7,45 @@
  * @public
  */
 import type { MessageHandler } from "./types.js";
+/**
+ * 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 Error {
+    /** The peer that did not answer. */
+    readonly to: string;
+    /** The limit it exceeded, in milliseconds. */
+    readonly timeoutMs: number;
+    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 a plain `Error` reading
-     * `A2A request timeout: <to> did not respond within <n>ms` — there is no typed
-     * timeout class and no `code` field, so a caller that must distinguish a
-     * timeout from a handler failure has to match on the message.
+     * 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;
 }

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

@@ -7,16 +7,45 @@
  * @public
  */
 import type { MessageHandler } from "./types.js";
+/**
+ * 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 Error {
+    /** The peer that did not answer. */
+    readonly to: string;
+    /** The limit it exceeded, in milliseconds. */
+    readonly timeoutMs: number;
+    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 a plain `Error` reading
-     * `A2A request timeout: <to> did not respond within <n>ms` — there is no typed
-     * timeout class and no `code` field, so a caller that must distinguish a
-     * timeout from a handler failure has to match on the message.
+     * 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;
 }

package/dist/{agent-HDEVVUBS.js → agent-K3PQBS7D.js}

@@ -1,6 +1,6 @@
-export { Agent } from './chunk-I5BE5M5L.js';
+export { Agent } from './chunk-KBXWEWKS.js';
 import './chunk-OHBIUXKM.js';
-import './chunk-DAPSQZT4.js';
+import './chunk-ODTZ7HX3.js';
 import './chunk-YMA4S2WO.js';
 import './chunk-2SFBB54R.js';
 import './chunk-SUKXXLWD.js';
@@ -14,7 +14,8 @@ import './chunk-WTMU7J4U.js';
 import './chunk-5JLFFPCH.js';
 import './chunk-BMAZLQQ4.js';
 import './chunk-HKCKOAIO.js';
-import './chunk-5PHVENFV.js';
+import './chunk-7FHZ4VQX.js';
+import './chunk-KVNWIAO4.js';
 import './chunk-UPRJR6IP.js';
 import './chunk-FD2UT76F.js';
 import './chunk-4VPXM6UU.js';
@@ -48,5 +49,5 @@ import './chunk-3OR54XG4.js';
 import './chunk-IDCKSLYH.js';
 import './chunk-T7XEKOVW.js';
 import './chunk-T7O6K6PX.js';
-//# sourceMappingURL=agent-HDEVVUBS.js.map
-//# sourceMappingURL=agent-HDEVVUBS.js.map
+//# sourceMappingURL=agent-K3PQBS7D.js.map
+//# sourceMappingURL=agent-K3PQBS7D.js.map

package/dist/{agent-HDEVVUBS.js.map → agent-K3PQBS7D.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-HDEVVUBS.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-K3PQBS7D.js"}

package/dist/{agent-R2HOJFZJ.cjs → agent-PJMBK7HQ.cjs}

@@ -1,8 +1,8 @@
 'use strict';
 
-var chunkF5WMX4EA_cjs = require('./chunk-F5WMX4EA.cjs');
+var chunkLQYQHXIW_cjs = require('./chunk-LQYQHXIW.cjs');
 require('./chunk-V2UUGUY4.cjs');
-require('./chunk-5UOVYM3P.cjs');
+require('./chunk-6VLKVX7O.cjs');
 require('./chunk-53CBTBWO.cjs');
 require('./chunk-BV2MWEMV.cjs');
 require('./chunk-NGESVVJN.cjs');
@@ -16,7 +16,8 @@ require('./chunk-4OTIXDMU.cjs');
 require('./chunk-DQKERTND.cjs');
 require('./chunk-CTCGWIUD.cjs');
 require('./chunk-2ZPEDVLM.cjs');
-require('./chunk-Q47R5E2X.cjs');
+require('./chunk-E3WZ6Y4H.cjs');
+require('./chunk-KRD3GQAA.cjs');
 require('./chunk-U2AC6JUP.cjs');
 require('./chunk-MUUQ2WFJ.cjs');
 require('./chunk-WJVHMTKB.cjs');
@@ -55,7 +56,7 @@ require('./chunk-NUKRL3I6.cjs');
 
 Object.defineProperty(exports, "Agent", {
   enumerable: true,
-  get: function () { return chunkF5WMX4EA_cjs.Agent; }
+  get: function () { return chunkLQYQHXIW_cjs.Agent; }
 });
-//# sourceMappingURL=agent-R2HOJFZJ.cjs.map
-//# sourceMappingURL=agent-R2HOJFZJ.cjs.map
+//# sourceMappingURL=agent-PJMBK7HQ.cjs.map
+//# sourceMappingURL=agent-PJMBK7HQ.cjs.map

package/dist/{agent-R2HOJFZJ.cjs.map → agent-PJMBK7HQ.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-R2HOJFZJ.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-PJMBK7HQ.cjs"}