@graphorin/core 0.6.0 → 0.7.0

package/dist/types/run.d.ts

@@ -73,14 +73,24 @@ interface RunStateUsageByModel {
  * to the checkpoint store on every `awaiting_approval` boundary, so a
  * separate process can resume the run.
  *
- * The shape is intentionally JSON-stable: every nested type is plain
- * `JSON`-encodable (no `Map`, no `Set`, no `Date`).
+ * JSON stability is guaranteed by the serializer, not by naive
+ * `JSON.stringify`: `messages` and tool-outcome `contentParts` may carry
+ * `Uint8Array | URL` payloads, which the documented wire projection
+ * (`WireRunState` via `toJsonSafeRunState`) encodes as base64 / href
+ * envelopes before stringification. No `Map`, `Set` or `Date` appears
+ * anywhere in the shape.
  *
  * @stable
  */
 interface RunState {
   readonly id: string;
   readonly agentId: string;
+  /**
+   * The agent whose model drives the NEXT step. During a handoff it is
+   * the target for exactly the child observation window and is restored
+   * to the parent when the child returns (W-034) - the child's identity
+   * is durably recorded in {@link RunState.handoffs}, never here.
+   */
   readonly currentAgentId: string;
   readonly sessionId: string;
   readonly userId?: string;
@@ -119,10 +129,76 @@ interface RunState {
    * prompt each turn). Absent until the agent writes one.
    */
   todos?: ReadonlyArray<TodoItem>;
+  /**
+   * W-001: sub-agent runs parked on this (parent) run because the
+   * child suspended with `awaiting_approval`. Each entry snapshots the
+   * suspended child state; the child's pending approvals are mirrored
+   * onto this run's `pendingApprovals` with `subRunToolCallId` set to
+   * the entry's `toolCallId`. Absent until a child parks.
+   */
+  pendingSubRuns?: PendingSubRun[];
   readonly startedAt: string;
   finishedAt?: string;
   error?: RunError;
 }
+/**
+ * One sub-agent run parked on its parent because the child suspended
+ * awaiting approvals (W-001). `state` is a JSON-compatible snapshot of
+ * the suspended child run; in serialized form (the agent package's
+ * `SerializedRunState`) it carries the child's own version-stamped,
+ * secret-redacted snapshot, recursively.
+ *
+ * @stable
+ */
+interface PendingSubRun {
+  /** The PARENT's toolCallId of the parked handoff / sub-agent call. */
+  readonly toolCallId: string;
+  /** The parent-side tool name (`transfer_to_<name>` or the toTool name). */
+  readonly toolName: string;
+  /** The child agent's configured name (for diagnostics and usage folding). */
+  readonly targetAgentName: string;
+  /** Suspended child run state (carries the child's own pendingApprovals). */
+  readonly state: RunState;
+}
+/**
+ * Read-only projection of {@link RunState} handed to tools and hooks
+ * via {@link RunContext.state} (W-047). Structurally identical to
+ * `RunState` - `RunState` is assignable to it - but every property is
+ * `readonly` and every array a `ReadonlyArray`, so typed tool code
+ * cannot corrupt run bookkeeping (splice `pendingApprovals`, flip
+ * `status`, ...). This is a compile-time contract only: there is no
+ * runtime freeze. A hand-written mirror (not a generic DeepReadonly):
+ * the nested types are already readonly-typed, and keyof-parity with
+ * `RunState` is pinned by type tests.
+ *
+ * @stable
+ */
+interface ReadonlyRunState {
+  readonly id: string;
+  readonly agentId: string;
+  readonly currentAgentId: string;
+  readonly sessionId: string;
+  readonly userId?: string;
+  readonly status: RunStatus;
+  readonly steps: ReadonlyArray<RunStep>;
+  readonly messages: ReadonlyArray<Message>;
+  readonly pendingApprovals: ReadonlyArray<ToolApproval>;
+  readonly handoffs: ReadonlyArray<HandoffRecord>;
+  readonly usage: Usage;
+  /** See {@link RunState.usageByModel}. */
+  readonly usageByModel?: RunStateUsageByModel;
+  /** See {@link RunState.taintSummary}. */
+  readonly taintSummary?: RunTaintSummary;
+  /** See {@link RunState.promotedTools}. */
+  readonly promotedTools?: ReadonlyArray<string>;
+  /** See {@link RunState.todos}. */
+  readonly todos?: ReadonlyArray<TodoItem>;
+  /** See {@link RunState.pendingSubRuns}. */
+  readonly pendingSubRuns?: ReadonlyArray<PendingSubRun>;
+  readonly startedAt: string;
+  readonly finishedAt?: string;
+  readonly error?: RunError;
+}
 /**
  * Coarse, serializable data-flow taint summary persisted in {@link RunState}
  * across suspend/resume (AG-19). Structurally identical to
@@ -195,7 +271,13 @@ interface RunContext<TDeps = unknown> {
   readonly usage: UsageAccumulator;
   readonly stepNumber: number;
   readonly messages: ReadonlyArray<Message>;
-  readonly state: RunState;
+  /**
+   * Read-only snapshot of the run's state (W-047). Tools observe the
+   * run; they do not mutate its bookkeeping - writes to `status`,
+   * `pendingApprovals` etc. are compile errors. The runtime keeps the
+   * only mutable reference.
+   */
+  readonly state: ReadonlyRunState;
   /**
    * C7: the current `agent.step` span (when the runtime traces). Spans
    * created inside tool execution parent under it so a run's traces
@@ -204,5 +286,5 @@ interface RunContext<TDeps = unknown> {
   readonly span?: AISpan;
 }
 //#endregion
-export { RunContext, RunError, RunState, RunStateUsageByModel, RunStatus, RunStep, RunStepProviderResponse, RunTaintSummary, TodoItem, flattenUsageByModel };
+export { PendingSubRun, ReadonlyRunState, RunContext, RunError, RunState, RunStateUsageByModel, RunStatus, RunStep, RunStepProviderResponse, RunTaintSummary, TodoItem, flattenUsageByModel };
 //# sourceMappingURL=run.d.ts.map

package/dist/types/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","names":[],"sources":["../../src/types/run.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;AAaA;AAQA;;;AAgB8B,KAxBlB,SAAA,GAwBkB,SAAA,GAAA,WAAA,GAAA,QAAA,GAAA,SAAA,GAAA,mBAAA;;AAW9B;AAkBA;AAcA;;;AAQqB,UAnEJ,OAAA,CAmEI;EACQ,SAAA,UAAA,EAAA,MAAA;EACR,SAAA,SAAA,EAAA,MAAA;EACH,SAAA,OAAA,CAAA,EAAA,MAAA;EAQD,SAAA,KAAA,CAAA,EA1EE,KA0EF;EASA,SAAA,SAAA,EAAA,SAlFc,iBAkFd,EAAA;EAKC;;;EAUR,SAAA,OAAA,EAAA,MAAA;EAAQ;AAUlB;AAoBA;AAeA;;;EAEG,SAAA,gBAAA,CAAA,EArI2B,uBAqI3B;;AAwBH;AAeA;;;;;;;AAWkB,UA5KD,uBAAA,CA4KC;EAAQ,SAAA,OAAA,EAAA,MAAA;EAM+B,SAAA,IAAA,CAAA,EAAA,MAAA;uBA/KlC,cAAc;;;;;;;;;;;;;;UAepB,oBAAA;8BACa;;;;;;;;;;;;;;UAab,QAAA;;;;;;UAMP;kBACQ;qBACG;6BACQ;qBACR;kBACH;;;;;;;;iBAQD;;;;;;;;;iBASA;;;;;kBAKC;;;;;;;UAOR,cAAc;;;UAGd;;;;;;;;;UAUO,eAAA;;;iCAGgB;;;;;;;4BAOL;;;;;;;;;UAUX,QAAA;;;;;;;;;;;;;;iBAeD,mBAAA,UACL,mCACR,cAAc;;;;;;;UAwBA,QAAA;;;;;;;;;;;;;;UAeA;;;;;iBAKA;mBACE;mBACA;kBACD;;qBAEG,cAAc;kBACjB;;;;;;kBAAQ"}
+{"version":3,"file":"run.d.ts","names":[],"sources":["../../src/types/run.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;AAaA;AAQA;;;AAgB8B,KAxBlB,SAAA,GAwBkB,SAAA,GAAA,WAAA,GAAA,QAAA,GAAA,SAAA,GAAA,mBAAA;;AAW9B;AAkBA;AAkBA;;;AAcqB,UA7EJ,OAAA,CA6EI;EACQ,SAAA,UAAA,EAAA,MAAA;EACR,SAAA,SAAA,EAAA,MAAA;EACH,SAAA,OAAA,CAAA,EAAA,MAAA;EAQD,SAAA,KAAA,CAAA,EApFE,KAoFF;EASA,SAAA,SAAA,EAAA,SA5Fc,iBA4Fd,EAAA;EAKC;;;EAeC,SAAA,OAAA,EAAA,MAAA;EAGT;;AAYV;AAwBA;;;EAOkB,SAAA,gBAAA,CAAA,EAnJY,uBAmJZ;;;;;;;;;;AAUS,UAlJV,uBAAA,CAkJU;EAEM,SAAA,OAAA,EAAA,MAAA;EAAd,SAAA,IAAA,CAAA,EAAA,MAAA;EAEuB,SAAA,SAAA,CAAA,EAnJnB,aAmJmB,CAnJL,QAmJK,CAAA;;;;AAa1C;AAoBA;AAeA;;;;;AA0BA;AAeA;;AAMmB,UAnOF,oBAAA,CAmOE;EACA,UAAA,OAAA,EAAA,MAAA,CAAA,EAnOW,KAmOX,GAAA;IACD,SAAA,YAAA,EAAA,MAAA;EAEiB,CAAA;;;;;;;;;;;;;;;;UArNlB,QAAA;;;;;;;;;;;;UAYP;kBACQ;qBACG;6BACQ;qBACR;kBACH;;;;;;;;iBAQD;;;;;;;;;iBASA;;;;;kBAKC;;;;;;;UAOR,cAAc;;;;;;;;mBAQL;;;UAGT;;;;;;;;;;;UAYO,aAAA;;;;;;;;kBAQC;;;;;;;;;;;;;;;UAgBD,gBAAA;;;;;;mBAME;kBACD,cAAc;qBACX,cAAc;6BACN,cAAc;qBACtB,cAAc;kBACjB;;0BAEQ;;0BAEA;;2BAEC;;mBAER,cAAc;;4BAEL,cAAc;;;mBAGvB;;;;;;;;;UAUF,eAAA;;;iCAGgB;;;;;;;4BAOL;;;;;;;;;UAUX,QAAA;;;;;;;;;;;;;;iBAeD,mBAAA,UACL,mCACR,cAAc;;;;;;;UAwBA,QAAA;;;;;;;;;;;;;;UAeA;;;;;iBAKA;mBACE;mBACA;kBACD;;qBAEG,cAAc;;;;;;;kBAOjB;;;;;;kBAAgB"}

package/dist/types/run.js.map

@@ -1 +1 @@
-{"version":3,"file":"run.js","names":["out: ModelUsage[]","m: ModelUsage"],"sources":["../../src/types/run.ts"],"sourcesContent":["import type { Tracer } from '../contracts/tracer.js';\nimport type { HandoffRecord } from './handoff.js';\nimport type { Message } from './message.js';\nimport type { CompletedToolCall, ToolApproval } from './tool.js';\nimport type { ToolCall } from './tool-call.js';\nimport type { ModelUsage, Usage, UsageAccumulator } from './usage.js';\n\n/**\n * Status of an in-flight or completed agent run. Append-only persistence\n * stores expose this verbatim on the `runs` table.\n *\n * @stable\n */\nexport type RunStatus = 'running' | 'completed' | 'failed' | 'aborted' | 'awaiting_approval';\n\n/**\n * Single step inside an agent run. The agent runtime appends one\n * `RunStep` per provider call.\n *\n * @stable\n */\nexport interface RunStep {\n  readonly stepNumber: number;\n  readonly startedAt: string;\n  readonly endedAt?: string;\n  readonly usage?: Usage;\n  readonly toolCalls: readonly CompletedToolCall[];\n  /**\n   * Stable agent id active for this step (changes after a handoff).\n   */\n  readonly agentId: string;\n  /**\n   * The model response this step produced, recorded when the agent runs\n   * with `recordProviderResponses: true` (C3). Enables deterministic\n   * replay: `createReplayProvider(state)` serves these back in order so\n   * a run re-executes without live model calls.\n   */\n  readonly providerResponse?: RunStepProviderResponse;\n}\n\n/**\n * Journaled model response for one step (C3, opt-in via the agent's\n * `recordProviderResponses`). Captures the RAW model output - the text\n * before any lateral-leak block replaced it in the transcript - so a\n * replay reproduces the original run faithfully.\n *\n * @stable\n */\nexport interface RunStepProviderResponse {\n  readonly modelId: string;\n  readonly text?: string;\n  readonly toolCalls?: ReadonlyArray<ToolCall>;\n}\n\n/**\n * Per-model usage breakdown carried alongside the aggregate\n * {@link Usage} on {@link RunState}. Populated by the per-step retry\n * loop when `Agent.fallbackModels` fires; for runs that never fall\n * back, the map carries a single entry for the primary model with\n * `attemptCount: 1`.\n *\n * The aggregate `RunState.usage` is always the sum of every entry's\n * `Usage` portion (the field is asserted in tests).\n *\n * @stable\n */\nexport interface RunStateUsageByModel {\n  readonly [modelId: string]: Usage & { readonly attemptCount: number };\n}\n\n/**\n * The full, serializable state of a run. The agent runtime persists this\n * to the checkpoint store on every `awaiting_approval` boundary, so a\n * separate process can resume the run.\n *\n * The shape is intentionally JSON-stable: every nested type is plain\n * `JSON`-encodable (no `Map`, no `Set`, no `Date`).\n *\n * @stable\n */\nexport interface RunState {\n  readonly id: string;\n  readonly agentId: string;\n  readonly currentAgentId: string;\n  readonly sessionId: string;\n  readonly userId?: string;\n  status: RunStatus;\n  readonly steps: RunStep[];\n  readonly messages: Message[];\n  readonly pendingApprovals: ToolApproval[];\n  readonly handoffs: HandoffRecord[];\n  readonly usage: Usage;\n  /**\n   * Per-model usage breakdown. Populated by the per-step retry loop\n   * when `Agent.fallbackModels` fires (RB-48 / suggested DEC-164 /\n   * suggested ADR-052). Backward-compat: rehydrating a serialized\n   * state that omits the field synthesizes a single-entry map for\n   * the primary model.\n   */\n  usageByModel?: RunStateUsageByModel;\n  /**\n   * AG-19: coarse data-flow taint summary, carried across suspend/resume so a\n   * resumed run does not start with an empty ledger that silently un-gates\n   * sinks exposed before the suspend. Structurally matches\n   * `@graphorin/security`'s `TaintLedgerSnapshot` (core takes no security\n   * dependency); only the load-bearing flags are persisted - never the tracked\n   * untrusted text spans.\n   */\n  taintSummary?: RunTaintSummary;\n  /**\n   * AG-19: names of deferred tools promoted by `tool_search` this run, carried\n   * across suspend/resume so discovered tools remain in the per-step catalogue.\n   */\n  promotedTools?: ReadonlyArray<string>;\n  /**\n   * D6 structured plan/todo list - the agent's own working plan,\n   * journaled so it survives suspend/resume (a TodoWrite-style tool\n   * mutates it, and attention-recitation renders it back into the\n   * prompt each turn). Absent until the agent writes one.\n   */\n  todos?: ReadonlyArray<TodoItem>;\n  readonly startedAt: string;\n  finishedAt?: string;\n  error?: RunError;\n}\n\n/**\n * Coarse, serializable data-flow taint summary persisted in {@link RunState}\n * across suspend/resume (AG-19). Structurally identical to\n * `@graphorin/security`'s `TaintLedgerSnapshot`; carries no untrusted text.\n *\n * @stable\n */\nexport interface RunTaintSummary {\n  readonly untrustedSeen: boolean;\n  readonly sensitiveSeen: boolean;\n  readonly untrustedSourceKinds: ReadonlyArray<string>;\n  /**\n   * C6: one-way FNV-1a hashes of normalized untrusted-span tiles. Re-arms\n   * the verbatim-carry probe after a resume at tile granularity. Hashes\n   * only - no untrusted text is ever persisted (the invariant above\n   * holds).\n   */\n  readonly spanTileHashes?: ReadonlyArray<string>;\n}\n\n/**\n * One item in the agent's structured plan (D6). `status` drives both\n * the recitation rendering and progress reporting; `id` lets a\n * status-flip mutation target an item without rewriting the list.\n *\n * @stable\n */\nexport interface TodoItem {\n  readonly id: string;\n  readonly content: string;\n  readonly status: 'pending' | 'in_progress' | 'completed';\n}\n\n/**\n * Snapshot helper used by `@graphorin/observability` aggregators to\n * convert the on-disk `usageByModel` shape into the canonical\n * {@link ModelUsage} array. Pure utility - kept in core so consumers\n * do not have to take an observability dependency just to flatten a\n * run-state breakdown.\n *\n * @stable\n */\nexport function flattenUsageByModel(\n  byModel: RunStateUsageByModel | undefined,\n): ReadonlyArray<ModelUsage> {\n  if (byModel === undefined) return [];\n  const out: ModelUsage[] = [];\n  for (const [modelId, entry] of Object.entries(byModel)) {\n    const m: ModelUsage = {\n      modelId,\n      promptTokens: entry.promptTokens,\n      completionTokens: entry.completionTokens,\n      totalTokens: entry.totalTokens,\n      callCount: entry.attemptCount,\n      ...(entry.reasoningTokens !== undefined ? { reasoningTokens: entry.reasoningTokens } : {}),\n      ...(entry.cost !== undefined ? { cost: entry.cost } : {}),\n    };\n    out.push(m);\n  }\n  return out;\n}\n\n/**\n * Failure carried by `RunState.error`. The shape mirrors the wire format\n * used by `agent.error` events.\n *\n * @stable\n */\nexport interface RunError {\n  readonly message: string;\n  readonly code: string;\n  readonly details?: unknown;\n}\n\n/**\n * Per-run dependency / context bag handed to every tool, hook and\n * provider middleware in scope. Generic over the user-defined deps shape.\n *\n * `tracer`, `signal`, `usage` and `state` are always present; everything\n * else is optional.\n *\n * @stable\n */\nexport interface RunContext<TDeps = unknown> {\n  readonly runId: string;\n  readonly sessionId: string;\n  readonly userId?: string;\n  readonly agentId: string;\n  readonly deps: TDeps;\n  readonly tracer: Tracer;\n  readonly signal: AbortSignal;\n  readonly usage: UsageAccumulator;\n  readonly stepNumber: number;\n  readonly messages: ReadonlyArray<Message>;\n  readonly state: RunState;\n  /**\n   * C7: the current `agent.step` span (when the runtime traces). Spans\n   * created inside tool execution parent under it so a run's traces\n   * form one tree.\n   */\n  readonly span?: import('../contracts/tracer.js').AISpan;\n}\n"],"mappings":";;;;;;;;;;AAwKA,SAAgB,oBACd,SAC2B;AAC3B,KAAI,YAAY,OAAW,QAAO,EAAE;CACpC,MAAMA,MAAoB,EAAE;AAC5B,MAAK,MAAM,CAAC,SAAS,UAAU,OAAO,QAAQ,QAAQ,EAAE;EACtD,MAAMC,IAAgB;GACpB;GACA,cAAc,MAAM;GACpB,kBAAkB,MAAM;GACxB,aAAa,MAAM;GACnB,WAAW,MAAM;GACjB,GAAI,MAAM,oBAAoB,SAAY,EAAE,iBAAiB,MAAM,iBAAiB,GAAG,EAAE;GACzF,GAAI,MAAM,SAAS,SAAY,EAAE,MAAM,MAAM,MAAM,GAAG,EAAE;GACzD;AACD,MAAI,KAAK,EAAE;;AAEb,QAAO"}
+{"version":3,"file":"run.js","names":["out: ModelUsage[]","m: ModelUsage"],"sources":["../../src/types/run.ts"],"sourcesContent":["import type { Tracer } from '../contracts/tracer.js';\nimport type { HandoffRecord } from './handoff.js';\nimport type { Message } from './message.js';\nimport type { CompletedToolCall, ToolApproval } from './tool.js';\nimport type { ToolCall } from './tool-call.js';\nimport type { ModelUsage, Usage, UsageAccumulator } from './usage.js';\n\n/**\n * Status of an in-flight or completed agent run. Append-only persistence\n * stores expose this verbatim on the `runs` table.\n *\n * @stable\n */\nexport type RunStatus = 'running' | 'completed' | 'failed' | 'aborted' | 'awaiting_approval';\n\n/**\n * Single step inside an agent run. The agent runtime appends one\n * `RunStep` per provider call.\n *\n * @stable\n */\nexport interface RunStep {\n  readonly stepNumber: number;\n  readonly startedAt: string;\n  readonly endedAt?: string;\n  readonly usage?: Usage;\n  readonly toolCalls: readonly CompletedToolCall[];\n  /**\n   * Stable agent id active for this step (changes after a handoff).\n   */\n  readonly agentId: string;\n  /**\n   * The model response this step produced, recorded when the agent runs\n   * with `recordProviderResponses: true` (C3). Enables deterministic\n   * replay: `createReplayProvider(state)` serves these back in order so\n   * a run re-executes without live model calls.\n   */\n  readonly providerResponse?: RunStepProviderResponse;\n}\n\n/**\n * Journaled model response for one step (C3, opt-in via the agent's\n * `recordProviderResponses`). Captures the RAW model output - the text\n * before any lateral-leak block replaced it in the transcript - so a\n * replay reproduces the original run faithfully.\n *\n * @stable\n */\nexport interface RunStepProviderResponse {\n  readonly modelId: string;\n  readonly text?: string;\n  readonly toolCalls?: ReadonlyArray<ToolCall>;\n}\n\n/**\n * Per-model usage breakdown carried alongside the aggregate\n * {@link Usage} on {@link RunState}. Populated by the per-step retry\n * loop when `Agent.fallbackModels` fires; for runs that never fall\n * back, the map carries a single entry for the primary model with\n * `attemptCount: 1`.\n *\n * The aggregate `RunState.usage` is always the sum of every entry's\n * `Usage` portion (the field is asserted in tests).\n *\n * @stable\n */\nexport interface RunStateUsageByModel {\n  readonly [modelId: string]: Usage & { readonly attemptCount: number };\n}\n\n/**\n * The full, serializable state of a run. The agent runtime persists this\n * to the checkpoint store on every `awaiting_approval` boundary, so a\n * separate process can resume the run.\n *\n * JSON stability is guaranteed by the serializer, not by naive\n * `JSON.stringify`: `messages` and tool-outcome `contentParts` may carry\n * `Uint8Array | URL` payloads, which the documented wire projection\n * (`WireRunState` via `toJsonSafeRunState`) encodes as base64 / href\n * envelopes before stringification. No `Map`, `Set` or `Date` appears\n * anywhere in the shape.\n *\n * @stable\n */\nexport interface RunState {\n  readonly id: string;\n  readonly agentId: string;\n  /**\n   * The agent whose model drives the NEXT step. During a handoff it is\n   * the target for exactly the child observation window and is restored\n   * to the parent when the child returns (W-034) - the child's identity\n   * is durably recorded in {@link RunState.handoffs}, never here.\n   */\n  readonly currentAgentId: string;\n  readonly sessionId: string;\n  readonly userId?: string;\n  status: RunStatus;\n  readonly steps: RunStep[];\n  readonly messages: Message[];\n  readonly pendingApprovals: ToolApproval[];\n  readonly handoffs: HandoffRecord[];\n  readonly usage: Usage;\n  /**\n   * Per-model usage breakdown. Populated by the per-step retry loop\n   * when `Agent.fallbackModels` fires (RB-48 / suggested DEC-164 /\n   * suggested ADR-052). Backward-compat: rehydrating a serialized\n   * state that omits the field synthesizes a single-entry map for\n   * the primary model.\n   */\n  usageByModel?: RunStateUsageByModel;\n  /**\n   * AG-19: coarse data-flow taint summary, carried across suspend/resume so a\n   * resumed run does not start with an empty ledger that silently un-gates\n   * sinks exposed before the suspend. Structurally matches\n   * `@graphorin/security`'s `TaintLedgerSnapshot` (core takes no security\n   * dependency); only the load-bearing flags are persisted - never the tracked\n   * untrusted text spans.\n   */\n  taintSummary?: RunTaintSummary;\n  /**\n   * AG-19: names of deferred tools promoted by `tool_search` this run, carried\n   * across suspend/resume so discovered tools remain in the per-step catalogue.\n   */\n  promotedTools?: ReadonlyArray<string>;\n  /**\n   * D6 structured plan/todo list - the agent's own working plan,\n   * journaled so it survives suspend/resume (a TodoWrite-style tool\n   * mutates it, and attention-recitation renders it back into the\n   * prompt each turn). Absent until the agent writes one.\n   */\n  todos?: ReadonlyArray<TodoItem>;\n  /**\n   * W-001: sub-agent runs parked on this (parent) run because the\n   * child suspended with `awaiting_approval`. Each entry snapshots the\n   * suspended child state; the child's pending approvals are mirrored\n   * onto this run's `pendingApprovals` with `subRunToolCallId` set to\n   * the entry's `toolCallId`. Absent until a child parks.\n   */\n  pendingSubRuns?: PendingSubRun[];\n  readonly startedAt: string;\n  finishedAt?: string;\n  error?: RunError;\n}\n\n/**\n * One sub-agent run parked on its parent because the child suspended\n * awaiting approvals (W-001). `state` is a JSON-compatible snapshot of\n * the suspended child run; in serialized form (the agent package's\n * `SerializedRunState`) it carries the child's own version-stamped,\n * secret-redacted snapshot, recursively.\n *\n * @stable\n */\nexport interface PendingSubRun {\n  /** The PARENT's toolCallId of the parked handoff / sub-agent call. */\n  readonly toolCallId: string;\n  /** The parent-side tool name (`transfer_to_<name>` or the toTool name). */\n  readonly toolName: string;\n  /** The child agent's configured name (for diagnostics and usage folding). */\n  readonly targetAgentName: string;\n  /** Suspended child run state (carries the child's own pendingApprovals). */\n  readonly state: RunState;\n}\n\n/**\n * Read-only projection of {@link RunState} handed to tools and hooks\n * via {@link RunContext.state} (W-047). Structurally identical to\n * `RunState` - `RunState` is assignable to it - but every property is\n * `readonly` and every array a `ReadonlyArray`, so typed tool code\n * cannot corrupt run bookkeeping (splice `pendingApprovals`, flip\n * `status`, ...). This is a compile-time contract only: there is no\n * runtime freeze. A hand-written mirror (not a generic DeepReadonly):\n * the nested types are already readonly-typed, and keyof-parity with\n * `RunState` is pinned by type tests.\n *\n * @stable\n */\nexport interface ReadonlyRunState {\n  readonly id: string;\n  readonly agentId: string;\n  readonly currentAgentId: string;\n  readonly sessionId: string;\n  readonly userId?: string;\n  readonly status: RunStatus;\n  readonly steps: ReadonlyArray<RunStep>;\n  readonly messages: ReadonlyArray<Message>;\n  readonly pendingApprovals: ReadonlyArray<ToolApproval>;\n  readonly handoffs: ReadonlyArray<HandoffRecord>;\n  readonly usage: Usage;\n  /** See {@link RunState.usageByModel}. */\n  readonly usageByModel?: RunStateUsageByModel;\n  /** See {@link RunState.taintSummary}. */\n  readonly taintSummary?: RunTaintSummary;\n  /** See {@link RunState.promotedTools}. */\n  readonly promotedTools?: ReadonlyArray<string>;\n  /** See {@link RunState.todos}. */\n  readonly todos?: ReadonlyArray<TodoItem>;\n  /** See {@link RunState.pendingSubRuns}. */\n  readonly pendingSubRuns?: ReadonlyArray<PendingSubRun>;\n  readonly startedAt: string;\n  readonly finishedAt?: string;\n  readonly error?: RunError;\n}\n\n/**\n * Coarse, serializable data-flow taint summary persisted in {@link RunState}\n * across suspend/resume (AG-19). Structurally identical to\n * `@graphorin/security`'s `TaintLedgerSnapshot`; carries no untrusted text.\n *\n * @stable\n */\nexport interface RunTaintSummary {\n  readonly untrustedSeen: boolean;\n  readonly sensitiveSeen: boolean;\n  readonly untrustedSourceKinds: ReadonlyArray<string>;\n  /**\n   * C6: one-way FNV-1a hashes of normalized untrusted-span tiles. Re-arms\n   * the verbatim-carry probe after a resume at tile granularity. Hashes\n   * only - no untrusted text is ever persisted (the invariant above\n   * holds).\n   */\n  readonly spanTileHashes?: ReadonlyArray<string>;\n}\n\n/**\n * One item in the agent's structured plan (D6). `status` drives both\n * the recitation rendering and progress reporting; `id` lets a\n * status-flip mutation target an item without rewriting the list.\n *\n * @stable\n */\nexport interface TodoItem {\n  readonly id: string;\n  readonly content: string;\n  readonly status: 'pending' | 'in_progress' | 'completed';\n}\n\n/**\n * Snapshot helper used by `@graphorin/observability` aggregators to\n * convert the on-disk `usageByModel` shape into the canonical\n * {@link ModelUsage} array. Pure utility - kept in core so consumers\n * do not have to take an observability dependency just to flatten a\n * run-state breakdown.\n *\n * @stable\n */\nexport function flattenUsageByModel(\n  byModel: RunStateUsageByModel | undefined,\n): ReadonlyArray<ModelUsage> {\n  if (byModel === undefined) return [];\n  const out: ModelUsage[] = [];\n  for (const [modelId, entry] of Object.entries(byModel)) {\n    const m: ModelUsage = {\n      modelId,\n      promptTokens: entry.promptTokens,\n      completionTokens: entry.completionTokens,\n      totalTokens: entry.totalTokens,\n      callCount: entry.attemptCount,\n      ...(entry.reasoningTokens !== undefined ? { reasoningTokens: entry.reasoningTokens } : {}),\n      ...(entry.cost !== undefined ? { cost: entry.cost } : {}),\n    };\n    out.push(m);\n  }\n  return out;\n}\n\n/**\n * Failure carried by `RunState.error`. The shape mirrors the wire format\n * used by `agent.error` events.\n *\n * @stable\n */\nexport interface RunError {\n  readonly message: string;\n  readonly code: string;\n  readonly details?: unknown;\n}\n\n/**\n * Per-run dependency / context bag handed to every tool, hook and\n * provider middleware in scope. Generic over the user-defined deps shape.\n *\n * `tracer`, `signal`, `usage` and `state` are always present; everything\n * else is optional.\n *\n * @stable\n */\nexport interface RunContext<TDeps = unknown> {\n  readonly runId: string;\n  readonly sessionId: string;\n  readonly userId?: string;\n  readonly agentId: string;\n  readonly deps: TDeps;\n  readonly tracer: Tracer;\n  readonly signal: AbortSignal;\n  readonly usage: UsageAccumulator;\n  readonly stepNumber: number;\n  readonly messages: ReadonlyArray<Message>;\n  /**\n   * Read-only snapshot of the run's state (W-047). Tools observe the\n   * run; they do not mutate its bookkeeping - writes to `status`,\n   * `pendingApprovals` etc. are compile errors. The runtime keeps the\n   * only mutable reference.\n   */\n  readonly state: ReadonlyRunState;\n  /**\n   * C7: the current `agent.step` span (when the runtime traces). Spans\n   * created inside tool execution parent under it so a run's traces\n   * form one tree.\n   */\n  readonly span?: import('../contracts/tracer.js').AISpan;\n}\n"],"mappings":";;;;;;;;;;AAsPA,SAAgB,oBACd,SAC2B;AAC3B,KAAI,YAAY,OAAW,QAAO,EAAE;CACpC,MAAMA,MAAoB,EAAE;AAC5B,MAAK,MAAM,CAAC,SAAS,UAAU,OAAO,QAAQ,QAAQ,EAAE;EACtD,MAAMC,IAAgB;GACpB;GACA,cAAc,MAAM;GACpB,kBAAkB,MAAM;GACxB,aAAa,MAAM;GACnB,WAAW,MAAM;GACjB,GAAI,MAAM,oBAAoB,SAAY,EAAE,iBAAiB,MAAM,iBAAiB,GAAG,EAAE;GACzF,GAAI,MAAM,SAAS,SAAY,EAAE,MAAM,MAAM,MAAM,GAAG,EAAE;GACzD;AACD,MAAI,KAAK,EAAE;;AAEb,QAAO"}

package/dist/types/tool.d.ts

@@ -268,6 +268,16 @@ interface ToolApproval {
   readonly args: unknown;
   readonly reason?: string;
   readonly requestedAt: string;
+  /**
+   * W-001: set when this approval belongs to a PARKED sub-agent run.
+   * It is the PARENT's toolCallId of the parked handoff / sub-agent
+   * call (the `RunState.pendingSubRuns` key), never a child-local id.
+   * Operators echo it back on the matching `ApprovalDecision` so
+   * resume decisions match on the composite (toolCallId,
+   * subRunToolCallId) key - child-local toolCallIds of two different
+   * children may collide.
+   */
+  readonly subRunToolCallId?: string;
 }
 /**
  * A `ToolCall` paired with its outcome and execution metadata. Captured

package/dist/types/tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","names":[],"sources":["../../src/types/tool.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAWA;AAsBA;AAyBA;AAmBA;AAuBA;AAUA;AAeY,KAlHA,aAAA,GAkHU,MAAA,GAAA,WAAA,GAAA,UAAA,GAAA,QAAA;AAmBtB;AAgBA;;;;;AAgCA;AA+BA;AA8BA;AAQA;AAyBA;;;;;AASA;AAcA;;;;AAE+B,KAtRnB,eAAA,GAsRmB,MAAA,GAAA,0BAAA,GAAA,cAAA,GAAA,SAAA,GAAA,WAAA;;;;;;;;;;;;;;;;;;;KA7PnB,eAAA;;;;;;;;;;;;;;;;;;KAmBA,yBAAA;;;;;;;;;;;;;;;;;KAuBA,kBAAA;;;;;;;;;KAUA,cAAA;;;;;;;;KAeA,UAAA;;;;;;;;;;;;;;;;;;;;;;;;KAmBA,YAAA;;;;;;;;;iBAGiC;;;;;;;;UAa5B;;;mBAGE;;;;;;mCAAO,cAAA;;;;;;;;;;0BAgBA;;;;;;;;;;;;UAaT,YAAA;;;;;;;;;;;;;;;;;;;;;;gCAsBe;;;;;;;;KASpB,aAAA;;;;;;;;;;;;;;;;;KA8BA,YAAA;;;;;;;UAQK,SAAA;;;iBAGA;;;;;;;;;;;;;0BAaS;;;;;;;;KASd,iCAAiC,WAAW,WAAW;;;;;;;;UASlD,YAAA;;;;;;;;;;;;;UAcA;iBACA;oBACG,YAAY"}
+{"version":3,"file":"tool.d.ts","names":[],"sources":["../../src/types/tool.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAWA;AAsBA;AAyBA;AAmBA;AAuBA;AAUA;AAeY,KAlHA,aAAA,GAkHU,MAAA,GAAA,WAAA,GAAA,UAAA,GAAA,QAAA;AAmBtB;AAgBA;;;;;AAgCA;AA+BA;AA8BA;AAQA;AAyBA;;;;;AASA;AAwBA;;;;AAE+B,KAhSnB,eAAA,GAgSmB,MAAA,GAAA,0BAAA,GAAA,cAAA,GAAA,SAAA,GAAA,WAAA;;;;;;;;;;;;;;;;;;;KAvQnB,eAAA;;;;;;;;;;;;;;;;;;KAmBA,yBAAA;;;;;;;;;;;;;;;;;KAuBA,kBAAA;;;;;;;;;KAUA,cAAA;;;;;;;;KAeA,UAAA;;;;;;;;;;;;;;;;;;;;;;;;KAmBA,YAAA;;;;;;;;;iBAGiC;;;;;;;;UAa5B;;;mBAGE;;;;;;mCAAO,cAAA;;;;;;;;;;0BAgBA;;;;;;;;;;;;UAaT,YAAA;;;;;;;;;;;;;;;;;;;;;;gCAsBe;;;;;;;;KASpB,aAAA;;;;;;;;;;;;;;;;;KA8BA,YAAA;;;;;;;UAQK,SAAA;;;iBAGA;;;;;;;;;;;;;0BAaS;;;;;;;;KASd,iCAAiC,WAAW,WAAW;;;;;;;;UASlD,YAAA;;;;;;;;;;;;;;;;;;;;;;;UAwBA;iBACA;oBACG,YAAY"}

package/dist/types/usage.d.ts

@@ -44,7 +44,17 @@ interface Usage {
  * @stable
  */
 interface Cost {
-  /** Amount in the smallest fractional unit of the declared currency. */
+  /**
+   * Amount in WHOLE units of `currency` - for USD that is dollars, and
+   * fractional values are expected (a typical LLM call costs a fraction
+   * of a cent, e.g. `0.0042`). This is deliberately NOT "minor units" /
+   * cents (W-045): the canonical producer -
+   * `calculateCost` in `@graphorin/pricing` - and every consumer
+   * (`CostTracker` in `@graphorin/observability`, the memory
+   * consolidator's `costUsd` budget, persisted checkpoints) already
+   * operate in whole currency units, and sub-cent per-call figures make
+   * minor units impractical. Do not divide by 100.
+   */
   amount: number;
   /** ISO-4217 currency code; default `'USD'`. */
   currency: string;

package/dist/types/usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage.d.ts","names":[],"sources":["../../src/types/usage.ts"],"sourcesContent":[],"mappings":";;AASA;AAoCA;AAaA;AAoBA;;;;;AAWc,UAhFG,KAAA,CAgFH;EAAa;AAQ3B;AAUA;;;;;;;;;;;;;;;;;;;;;;;;SAvES;;;;;;;;UASQ,IAAA;;;;;;;;;;;;UAaA,UAAA;;;;;;;;SAQR;;;;;;;;;;;UAYQ,gBAAA;;kBAEC;;oBAEE,oBAAoB;;8BAGV;;;;cAIhB;;;;;;;UAQG,aAAA;kBACC;6BACW;;;;;;;iBAQb,SAAA,CAAA,GAAa"}
+{"version":3,"file":"usage.d.ts","names":[],"sources":["../../src/types/usage.ts"],"sourcesContent":[],"mappings":";;AASA;AAoCA;AAuBA;AAoBA;;;;;AAWc,UA1FG,KAAA,CA0FH;EAAa;AAQ3B;AAUA;;;;;;;;;;;;;;;;;;;;;;;;SAjFS;;;;;;;;UASQ,IAAA;;;;;;;;;;;;;;;;;;;;;;UAuBA,UAAA;;;;;;;;SAQR;;;;;;;;;;;UAYQ,gBAAA;;kBAEC;;oBAEE,oBAAoB;;8BAGV;;;;cAIhB;;;;;;;UAQG,aAAA;kBACC;6BACW;;;;;;;iBAQb,SAAA,CAAA,GAAa"}

package/dist/types/usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"usage.js","names":[],"sources":["../../src/types/usage.ts"],"sourcesContent":["/**\n * Token / cost metrics for a single LLM call.\n *\n * `cost` is optional because the framework cannot compute it without a\n * pricing snapshot - providers/middleware fill it in (e.g. through the\n * separate `@graphorin/pricing` package) when the snapshot is available.\n *\n * @stable\n */\nexport interface Usage {\n  /**\n   * Total input tokens for the call, INCLUDING any prompt-cache reads and\n   * writes (`cachedReadTokens` / `cacheWriteTokens` are informational\n   * subsets, not additions). This matches the context size the model saw.\n   */\n  promptTokens: number;\n  completionTokens: number;\n  /**\n   * Reasoning tokens billed IN ADDITION to `completionTokens` (exclusive;\n   * adapters that receive an inclusive total split it so the sum stays\n   * exact). Cost formulas may add this to the output leg without\n   * double-counting.\n   */\n  reasoningTokens?: number;\n  /**\n   * Prompt tokens served from the provider's prompt cache (a subset of\n   * `promptTokens`), billed at the discounted cache-read rate.\n   */\n  cachedReadTokens?: number;\n  /**\n   * Prompt tokens written to the provider's prompt cache this call (a\n   * subset of `promptTokens`), billed at the cache-write premium where the\n   * provider charges one (Anthropic does; OpenAI does not report writes).\n   */\n  cacheWriteTokens?: number;\n  totalTokens: number;\n  cost?: Cost;\n}\n\n/**\n * Money figure attached to a `Usage`. Always carries a 3-letter currency\n * code so that consumers can perform aggregation safely.\n *\n * @stable\n */\nexport interface Cost {\n  /** Amount in the smallest fractional unit of the declared currency. */\n  amount: number;\n  /** ISO-4217 currency code; default `'USD'`. */\n  currency: string;\n}\n\n/**\n * Per-model breakdown used by aggregators (e.g. `CostTracker` in\n * `@graphorin/observability`).\n *\n * @stable\n */\nexport interface ModelUsage {\n  modelId: string;\n  promptTokens: number;\n  completionTokens: number;\n  reasoningTokens?: number;\n  cachedReadTokens?: number;\n  cacheWriteTokens?: number;\n  totalTokens: number;\n  cost?: Cost;\n  callCount: number;\n}\n\n/**\n * A live accumulator of token / cost figures. Implementations live in\n * `@graphorin/observability`. The contract sits here so every package\n * (agent, workflow, server, …) can type a parameter as `UsageAccumulator`\n * without taking an observability dependency.\n *\n * @stable\n */\nexport interface UsageAccumulator {\n  /** Current rolled-up totals across every model that has been added. */\n  readonly total: Usage;\n  /** Per-model breakdown; preserves call counts for observability. */\n  readonly byModel: ReadonlyMap<string, ModelUsage>;\n\n  /** Add a single LLM-call usage record under the given model id. */\n  add(modelId: string, usage: Usage): void;\n  /** Reset the accumulator to a zeroed state. */\n  reset(): void;\n  /** Render an immutable snapshot suitable for serialization / span attrs. */\n  snapshot(): UsageSnapshot;\n}\n\n/**\n * Immutable, JSON-serializable snapshot of a `UsageAccumulator`.\n *\n * @stable\n */\nexport interface UsageSnapshot {\n  readonly total: Usage;\n  readonly byModel: readonly ModelUsage[];\n}\n\n/**\n * Returns a fresh, zeroed `Usage` value.\n *\n * @stable\n */\nexport function zeroUsage(): Usage {\n  return { promptTokens: 0, completionTokens: 0, totalTokens: 0 };\n}\n"],"mappings":";;;;;;AA2GA,SAAgB,YAAmB;AACjC,QAAO;EAAE,cAAc;EAAG,kBAAkB;EAAG,aAAa;EAAG"}
+{"version":3,"file":"usage.js","names":[],"sources":["../../src/types/usage.ts"],"sourcesContent":["/**\n * Token / cost metrics for a single LLM call.\n *\n * `cost` is optional because the framework cannot compute it without a\n * pricing snapshot - providers/middleware fill it in (e.g. through the\n * separate `@graphorin/pricing` package) when the snapshot is available.\n *\n * @stable\n */\nexport interface Usage {\n  /**\n   * Total input tokens for the call, INCLUDING any prompt-cache reads and\n   * writes (`cachedReadTokens` / `cacheWriteTokens` are informational\n   * subsets, not additions). This matches the context size the model saw.\n   */\n  promptTokens: number;\n  completionTokens: number;\n  /**\n   * Reasoning tokens billed IN ADDITION to `completionTokens` (exclusive;\n   * adapters that receive an inclusive total split it so the sum stays\n   * exact). Cost formulas may add this to the output leg without\n   * double-counting.\n   */\n  reasoningTokens?: number;\n  /**\n   * Prompt tokens served from the provider's prompt cache (a subset of\n   * `promptTokens`), billed at the discounted cache-read rate.\n   */\n  cachedReadTokens?: number;\n  /**\n   * Prompt tokens written to the provider's prompt cache this call (a\n   * subset of `promptTokens`), billed at the cache-write premium where the\n   * provider charges one (Anthropic does; OpenAI does not report writes).\n   */\n  cacheWriteTokens?: number;\n  totalTokens: number;\n  cost?: Cost;\n}\n\n/**\n * Money figure attached to a `Usage`. Always carries a 3-letter currency\n * code so that consumers can perform aggregation safely.\n *\n * @stable\n */\nexport interface Cost {\n  /**\n   * Amount in WHOLE units of `currency` - for USD that is dollars, and\n   * fractional values are expected (a typical LLM call costs a fraction\n   * of a cent, e.g. `0.0042`). This is deliberately NOT \"minor units\" /\n   * cents (W-045): the canonical producer -\n   * `calculateCost` in `@graphorin/pricing` - and every consumer\n   * (`CostTracker` in `@graphorin/observability`, the memory\n   * consolidator's `costUsd` budget, persisted checkpoints) already\n   * operate in whole currency units, and sub-cent per-call figures make\n   * minor units impractical. Do not divide by 100.\n   */\n  amount: number;\n  /** ISO-4217 currency code; default `'USD'`. */\n  currency: string;\n}\n\n/**\n * Per-model breakdown used by aggregators (e.g. `CostTracker` in\n * `@graphorin/observability`).\n *\n * @stable\n */\nexport interface ModelUsage {\n  modelId: string;\n  promptTokens: number;\n  completionTokens: number;\n  reasoningTokens?: number;\n  cachedReadTokens?: number;\n  cacheWriteTokens?: number;\n  totalTokens: number;\n  cost?: Cost;\n  callCount: number;\n}\n\n/**\n * A live accumulator of token / cost figures. Implementations live in\n * `@graphorin/observability`. The contract sits here so every package\n * (agent, workflow, server, …) can type a parameter as `UsageAccumulator`\n * without taking an observability dependency.\n *\n * @stable\n */\nexport interface UsageAccumulator {\n  /** Current rolled-up totals across every model that has been added. */\n  readonly total: Usage;\n  /** Per-model breakdown; preserves call counts for observability. */\n  readonly byModel: ReadonlyMap<string, ModelUsage>;\n\n  /** Add a single LLM-call usage record under the given model id. */\n  add(modelId: string, usage: Usage): void;\n  /** Reset the accumulator to a zeroed state. */\n  reset(): void;\n  /** Render an immutable snapshot suitable for serialization / span attrs. */\n  snapshot(): UsageSnapshot;\n}\n\n/**\n * Immutable, JSON-serializable snapshot of a `UsageAccumulator`.\n *\n * @stable\n */\nexport interface UsageSnapshot {\n  readonly total: Usage;\n  readonly byModel: readonly ModelUsage[];\n}\n\n/**\n * Returns a fresh, zeroed `Usage` value.\n *\n * @stable\n */\nexport function zeroUsage(): Usage {\n  return { promptTokens: 0, completionTokens: 0, totalTokens: 0 };\n}\n"],"mappings":";;;;;;AAqHA,SAAgB,YAAmB;AACjC,QAAO;EAAE,cAAc;EAAG,kBAAkB;EAAG,aAAa;EAAG"}

package/dist/utils/binary-json.d.ts

@@ -0,0 +1,165 @@
+import { AssistantMessage, AudioContent, FileContent, ImageContent, Message, MessageContent, SystemMessage, ToolMessage, UserMessage } from "../types/message.js";
+import { CompletedToolCall, ToolError, ToolResult } from "../types/tool.js";
+import { PendingSubRun, RunState, RunStep } from "../types/run.js";
+
+//#region src/utils/binary-json.d.ts
+
+/**
+ * Base64-encoded binary payload as it appears on the wire.
+ *
+ * @stable
+ */
+interface EncodedBytes {
+  readonly enc: 'base64';
+  readonly data: string;
+}
+/**
+ * URL reference as it appears on the wire (`URL` instances do not
+ * survive `JSON.stringify`).
+ *
+ * @stable
+ */
+interface EncodedUrl {
+  readonly enc: 'url';
+  readonly href: string;
+}
+/**
+ * Wire form of a `Uint8Array | URL` binary field.
+ *
+ * @stable
+ */
+type EncodedBinary = EncodedBytes | EncodedUrl;
+/** Wire twin of {@link ImageContent}. @stable */
+interface WireImageContent extends Omit<ImageContent, 'image'> {
+  readonly image: EncodedBinary;
+}
+/** Wire twin of {@link AudioContent}. @stable */
+interface WireAudioContent extends Omit<AudioContent, 'audio'> {
+  readonly audio: EncodedBinary;
+}
+/** Wire twin of {@link FileContent}. @stable */
+interface WireFileContent extends Omit<FileContent, 'file'> {
+  readonly file: EncodedBinary;
+}
+/**
+ * JSON-safe twin of {@link MessageContent}: binary-bearing variants
+ * carry {@link EncodedBinary} envelopes, text/reasoning variants pass
+ * through untouched.
+ *
+ * @stable
+ */
+type WireMessageContent = Exclude<MessageContent, ImageContent | AudioContent | FileContent> | WireImageContent | WireAudioContent | WireFileContent;
+/** Wire twin of {@link UserMessage}. @stable */
+interface WireUserMessage extends Omit<UserMessage, 'content'> {
+  readonly content: string | readonly WireMessageContent[];
+}
+/** Wire twin of {@link AssistantMessage}. @stable */
+interface WireAssistantMessage extends Omit<AssistantMessage, 'content'> {
+  readonly content: string | readonly WireMessageContent[];
+}
+/** Wire twin of {@link ToolMessage}. @stable */
+interface WireToolMessage extends Omit<ToolMessage, 'content'> {
+  readonly content: string | readonly WireMessageContent[];
+}
+/**
+ * JSON-safe twin of {@link Message}. System messages are plain strings
+ * and pass through unchanged.
+ *
+ * @stable
+ */
+type WireMessage = SystemMessage | WireUserMessage | WireAssistantMessage | WireToolMessage;
+/** Wire twin of {@link ToolResult}: `contentParts` are encoded. @stable */
+type WireToolResult<TOutput = unknown> = Omit<ToolResult<TOutput>, 'contentParts'> & {
+  readonly contentParts?: readonly WireMessageContent[];
+};
+/** Wire twin of `ToolOutcome`. @stable */
+type WireToolOutcome<TOutput = unknown> = WireToolResult<TOutput> | ToolError;
+/** Wire twin of {@link CompletedToolCall}. @stable */
+type WireCompletedToolCall<TOutput = unknown> = Omit<CompletedToolCall<TOutput>, 'outcome'> & {
+  readonly outcome: WireToolOutcome<TOutput>;
+};
+/** Wire twin of {@link RunStep}. @stable */
+type WireRunStep = Omit<RunStep, 'toolCalls'> & {
+  readonly toolCalls: readonly WireCompletedToolCall[];
+};
+/** Wire twin of {@link PendingSubRun}: the child state recurses. @stable */
+type WirePendingSubRun = Omit<PendingSubRun, 'state'> & {
+  readonly state: WireRunState;
+};
+/**
+ * JSON-safe twin of {@link RunState}: `messages`, every
+ * `steps[].toolCalls[].outcome.contentParts`, and each parked
+ * `pendingSubRuns[].state` (recursively, W-001) are projected through
+ * the binary codec. Everything else is structurally identical.
+ *
+ * `pendingApprovals[].args` and `ToolResult.output` are model-produced
+ * JSON and are assumed JSON-safe already - the projection does not
+ * walk them.
+ *
+ * @stable
+ */
+type WireRunState = Omit<RunState, 'messages' | 'steps' | 'pendingSubRuns'> & {
+  readonly messages: readonly WireMessage[];
+  readonly steps: readonly WireRunStep[];
+  readonly pendingSubRuns?: readonly WirePendingSubRun[];
+};
+/**
+ * Encode bytes as standard (padded) base64 without relying on `Buffer`
+ * or `btoa`.
+ *
+ * @stable
+ */
+declare function bytesToBase64(bytes: Uint8Array): string;
+/**
+ * Decode standard base64 (padding optional). Throws on characters
+ * outside the base64 alphabet.
+ *
+ * @stable
+ */
+declare function base64ToBytes(data: string): Uint8Array;
+/**
+ * Project multimodal content parts into their JSON-safe wire form.
+ * Text and reasoning parts pass through untouched.
+ *
+ * @stable
+ */
+declare function toJsonSafeContentParts(parts: readonly MessageContent[]): readonly WireMessageContent[];
+/**
+ * Inverse of {@link toJsonSafeContentParts}. Accepts legacy corrupted
+ * payloads (numeric-key byte objects) and repairs them best-effort.
+ *
+ * @stable
+ */
+declare function fromJsonSafeContentParts(parts: readonly WireMessageContent[]): readonly MessageContent[];
+/**
+ * Project a {@link Message} into its JSON-safe wire form. Idempotent:
+ * projecting an already-wire message returns an equivalent value.
+ *
+ * @stable
+ */
+declare function toJsonSafeMessage(message: Message | WireMessage): WireMessage;
+/**
+ * Inverse of {@link toJsonSafeMessage}.
+ *
+ * @stable
+ */
+declare function fromJsonSafeMessage(message: WireMessage | Message): Message;
+/**
+ * Project a full {@link RunState} into its JSON-safe {@link WireRunState}
+ * twin: `messages` and `steps[].toolCalls[].outcome.contentParts` go
+ * through the binary codec, everything else is copied structurally.
+ *
+ * @stable
+ */
+declare function toJsonSafeRunState(state: RunState | WireRunState): WireRunState;
+/**
+ * Inverse of {@link toJsonSafeRunState}. Best-effort: legacy corrupted
+ * binary fields (numeric-key byte objects from schema <= 1.1 payloads)
+ * are repaired to `Uint8Array`; unrecoverable shapes are left as-is.
+ *
+ * @stable
+ */
+declare function fromJsonSafeRunState(state: WireRunState): RunState;
+//#endregion
+export { EncodedBinary, EncodedBytes, EncodedUrl, WireAssistantMessage, WireAudioContent, WireCompletedToolCall, WireFileContent, WireImageContent, WireMessage, WireMessageContent, WireRunState, WireRunStep, WireToolMessage, WireToolOutcome, WireToolResult, WireUserMessage, base64ToBytes, bytesToBase64, fromJsonSafeContentParts, fromJsonSafeMessage, fromJsonSafeRunState, toJsonSafeContentParts, toJsonSafeMessage, toJsonSafeRunState };
+//# sourceMappingURL=binary-json.d.ts.map

package/dist/utils/binary-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-json.d.ts","names":[],"sources":["../../src/utils/binary-json.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAkFA;;AAC4B,UA9CX,YAAA,CA8CW;EAAe,SAAA,GAAA,EAAA,QAAA;EAAe,SAAA,IAAA,EAAA,MAAA;;;;;;AAM1D;;AACsC,UA1CrB,UAAA,CA0CqB;EADG,SAAA,GAAA,EAAA,KAAA;EAAI,SAAA,IAAA,EAAA,MAAA;AAK7C;;;;;AAKA;AAA8C,KAzClC,aAAA,GAAgB,YAyCkB,GAzCH,UAyCG;;AAAL,UAtCxB,gBAAA,SAAyB,IAsCD,CAtCM,YAsCN,EAAA,OAAA,CAAA,CAAA;EAAI,SAAA,KAAA,EArC3B,aAqC2B;AAU7C;;AAA0C,UA3CzB,gBAAA,SAAyB,IA2CA,CA3CK,YA2CL,EAAA,OAAA,CAAA,CAAA;EAAkB,SAAA,KAAA,EA1C1C,aA0C0C;;;AAGhD,UAzCK,eAAA,SAAwB,IAyCf,CAzCoB,WAyCpB,EAAA,MAAA,CAAA,CAAA;EAAsC,SAAA,IAAA,EAxC/C,aAwC+C;;;;;AAKhE;;;;AAAoF,KAnCxE,kBAAA,GACR,OAkCgF,CAlCxE,cAkCwE,EAlCxD,YAkCwD,GAlCzC,YAkCyC,GAlC1B,WAkC0B,CAAA,GAjChF,gBAiCgF,GAhChF,gBAgCgF,GA/BhF,eA+BgF;AAGpF;AACoB,UAhCH,eAAA,SAAwB,IAgCrB,CAhC0B,WAgC1B,EAAA,SAAA,CAAA,CAAA;EAAlB,SAAA,OAAA,EAAA,MAAA,GAAA,SA/BoC,kBA+BpC,EAAA;;;AAGkB,UA9BH,oBAAA,SAA6B,IA8B1B,CA9B+B,gBA8B/B,EAAA,SAAA,CAAA,CAAA;EAAe,SAAA,OAAA,EAAA,MAAA,GAAA,SA7BG,kBA6BH,EAAA;AAInC;;AAA0B,UA7BT,eAAA,SAAwB,IA6Bf,CA7BoB,WA6BpB,EAAA,SAAA,CAAA,CAAA;EACK,SAAA,OAAA,EAAA,MAAA,GAAA,SA7BO,kBA6BP,EAAA;;AAI/B;;;;;AAgBA;AAAgC,KAxCpB,WAAA,GAAc,aAwCM,GAxCU,eAwCV,GAxC4B,oBAwC5B,GAxCmD,eAwCnD;;AACF,KAtClB,cAsCkB,CAAA,UAAA,OAAA,CAAA,GAtCkB,IAsClB,CAtCuB,UAsCvB,CAtCkC,OAsClC,CAAA,EAAA,cAAA,CAAA,GAAA;EACH,SAAA,YAAA,CAAA,EAAA,SAtCQ,kBAsCR,EAAA;CACU;;AAerB,KAlDJ,eAkDiB,CAAA,UAAQ,OAAU,CAAA,GAlDE,cAkDF,CAlDiB,OAkDjB,CAAA,GAlD4B,SAkD5B;AAoB/C;AAyGgB,KA5KJ,qBA4K0B,CAAA,UACpB,OAAA,CAAA,GA7KqC,IA8K3C,CA7KV,iBA6K4B,CA7KV,OA6KU,CAAA,EAAA,SAAA,CAAA,GAAA;EAUd,SAAA,OAAA,EApLI,eAoLoB,CApLJ,OAqLlB,CAAA;AAWlB,CAAA;;AAAqD,KA5LzC,WAAA,GAAc,IA4L2B,CA5LtB,OA4LsB,EAAA,WAAA,CAAA,GAAA;EAAc,SAAA,SAAA,EAAA,SA3LpC,qBA2LoC,EAAA;CAAW;AAY9E;AAA6C,KAnMjC,iBAAA,GAAoB,IAmMa,CAnMR,aAmMQ,EAAA,OAAA,CAAA,GAAA;EAAc,SAAA,KAAA,EAlMzC,YAkMyC;CAAU;;AAuDrE;;;;;AA0BA;;;;;;KApQY,YAAA,GAAe,KAAK;8BACF;2BACH;qCACU;;;;;;;;iBAerB,aAAA,QAAqB;;;;;;;iBAoBrB,aAAA,gBAA6B;;;;;;;iBAyG7B,sBAAA,iBACE,4BACN;;;;;;;iBAUI,wBAAA,iBACE,gCACN;;;;;;;iBAUI,iBAAA,UAA2B,UAAU,cAAc;;;;;;iBAYnD,mBAAA,UAA6B,cAAc,UAAU;;;;;;;;iBAuDrD,kBAAA,QAA0B,WAAW,eAAe;;;;;;;;iBA0BpD,oBAAA,QAA4B,eAAe"}

package/dist/utils/binary-json.js

@@ -0,0 +1,240 @@
+//#region src/utils/binary-json.ts
+const B64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const B64_LOOKUP = new Map([...B64_ALPHABET].map((ch, i) => [ch, i]));
+/**
+* Encode bytes as standard (padded) base64 without relying on `Buffer`
+* or `btoa`.
+*
+* @stable
+*/
+function bytesToBase64(bytes) {
+	let out = "";
+	for (let i = 0; i < bytes.length; i += 3) {
+		const b0 = bytes[i];
+		const b1 = i + 1 < bytes.length ? bytes[i + 1] : void 0;
+		const b2 = i + 2 < bytes.length ? bytes[i + 2] : void 0;
+		out += B64_ALPHABET[b0 >> 2];
+		out += B64_ALPHABET[(b0 & 3) << 4 | (b1 ?? 0) >> 4];
+		out += b1 === void 0 ? "=" : B64_ALPHABET[(b1 & 15) << 2 | (b2 ?? 0) >> 6];
+		out += b2 === void 0 ? "=" : B64_ALPHABET[b2 & 63];
+	}
+	return out;
+}
+/**
+* Decode standard base64 (padding optional). Throws on characters
+* outside the base64 alphabet.
+*
+* @stable
+*/
+function base64ToBytes(data) {
+	let end = data.length;
+	while (end > 0 && data.charCodeAt(end - 1) === 61) end -= 1;
+	const stripped = data.slice(0, end);
+	const out = new Uint8Array(Math.floor(stripped.length * 6 / 8));
+	let offset = 0;
+	let buffer = 0;
+	let bits = 0;
+	for (const ch of stripped) {
+		const value = B64_LOOKUP.get(ch);
+		if (value === void 0) throw new Error(`base64ToBytes: invalid base64 character ${JSON.stringify(ch)}`);
+		buffer = buffer << 6 | value;
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			out[offset] = buffer >> bits & 255;
+			offset += 1;
+		}
+	}
+	return out;
+}
+function isRecord(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function encodeBinary(value) {
+	if (value instanceof Uint8Array) return {
+		enc: "base64",
+		data: bytesToBase64(value)
+	};
+	if (value instanceof URL) return {
+		enc: "url",
+		href: value.href
+	};
+	return value;
+}
+/**
+* Repair the exact corruption `JSON.stringify(Uint8Array)` produces: an
+* object whose keys are the dense indices `0..n-1` with byte values.
+* Applied ONLY to known binary fields of legacy (schema <= 1.1)
+* payloads; anything else is returned as-is.
+*/
+function repairNumericKeyBytes(value) {
+	const keys = Object.keys(value);
+	if (keys.length === 0) return void 0;
+	const out = new Uint8Array(keys.length);
+	for (let i = 0; i < keys.length; i += 1) {
+		const raw = value[String(i)];
+		if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0 || raw > 255) return;
+		out[i] = raw;
+	}
+	return out;
+}
+function decodeBinary(value) {
+	if (value instanceof Uint8Array || value instanceof URL) return value;
+	if (!isRecord(value)) return value;
+	if (value.enc === "base64" && typeof value.data === "string") return base64ToBytes(value.data);
+	if (value.enc === "url" && typeof value.href === "string") return new URL(value.href);
+	return repairNumericKeyBytes(value) ?? value;
+}
+function encodeContentPart(part) {
+	switch (part.type) {
+		case "image": return {
+			...part,
+			image: encodeBinary(part.image)
+		};
+		case "audio": return {
+			...part,
+			audio: encodeBinary(part.audio)
+		};
+		case "file": return {
+			...part,
+			file: encodeBinary(part.file)
+		};
+		default: return part;
+	}
+}
+function decodeContentPart(part) {
+	switch (part.type) {
+		case "image": return {
+			...part,
+			image: decodeBinary(part.image)
+		};
+		case "audio": return {
+			...part,
+			audio: decodeBinary(part.audio)
+		};
+		case "file": return {
+			...part,
+			file: decodeBinary(part.file)
+		};
+		default: return part;
+	}
+}
+/**
+* Project multimodal content parts into their JSON-safe wire form.
+* Text and reasoning parts pass through untouched.
+*
+* @stable
+*/
+function toJsonSafeContentParts(parts) {
+	return parts.map(encodeContentPart);
+}
+/**
+* Inverse of {@link toJsonSafeContentParts}. Accepts legacy corrupted
+* payloads (numeric-key byte objects) and repairs them best-effort.
+*
+* @stable
+*/
+function fromJsonSafeContentParts(parts) {
+	return parts.map(decodeContentPart);
+}
+/**
+* Project a {@link Message} into its JSON-safe wire form. Idempotent:
+* projecting an already-wire message returns an equivalent value.
+*
+* @stable
+*/
+function toJsonSafeMessage(message) {
+	if (message.role === "system" || typeof message.content === "string") return message;
+	return {
+		...message,
+		content: message.content.map(encodeContentPart)
+	};
+}
+/**
+* Inverse of {@link toJsonSafeMessage}.
+*
+* @stable
+*/
+function fromJsonSafeMessage(message) {
+	if (message.role === "system" || typeof message.content === "string") return message;
+	return {
+		...message,
+		content: message.content.map(decodeContentPart)
+	};
+}
+function encodeOutcome(outcome) {
+	if (isRecord(outcome) && Array.isArray(outcome.contentParts)) return {
+		...outcome,
+		contentParts: toJsonSafeContentParts(outcome.contentParts)
+	};
+	return outcome;
+}
+function decodeOutcome(outcome) {
+	if (isRecord(outcome) && Array.isArray(outcome.contentParts)) return {
+		...outcome,
+		contentParts: fromJsonSafeContentParts(outcome.contentParts)
+	};
+	return outcome;
+}
+function encodeStep(step) {
+	if (step.toolCalls.length === 0) return step;
+	return {
+		...step,
+		toolCalls: step.toolCalls.map((tc) => ({
+			...tc,
+			outcome: encodeOutcome(tc.outcome)
+		}))
+	};
+}
+function decodeStep(step) {
+	if (step.toolCalls.length === 0) return step;
+	return {
+		...step,
+		toolCalls: step.toolCalls.map((tc) => ({
+			...tc,
+			outcome: decodeOutcome(tc.outcome)
+		}))
+	};
+}
+/**
+* Project a full {@link RunState} into its JSON-safe {@link WireRunState}
+* twin: `messages` and `steps[].toolCalls[].outcome.contentParts` go
+* through the binary codec, everything else is copied structurally.
+*
+* @stable
+*/
+function toJsonSafeRunState(state) {
+	const subRuns = state.pendingSubRuns;
+	return {
+		...state,
+		messages: state.messages.map(toJsonSafeMessage),
+		steps: state.steps.map(encodeStep),
+		...subRuns !== void 0 && subRuns.length > 0 ? { pendingSubRuns: subRuns.map((sub) => ({
+			...sub,
+			state: toJsonSafeRunState(sub.state)
+		})) } : {}
+	};
+}
+/**
+* Inverse of {@link toJsonSafeRunState}. Best-effort: legacy corrupted
+* binary fields (numeric-key byte objects from schema <= 1.1 payloads)
+* are repaired to `Uint8Array`; unrecoverable shapes are left as-is.
+*
+* @stable
+*/
+function fromJsonSafeRunState(state) {
+	const subRuns = state.pendingSubRuns;
+	return {
+		...state,
+		messages: state.messages.map(fromJsonSafeMessage),
+		steps: state.steps.map(decodeStep),
+		...subRuns !== void 0 && subRuns.length > 0 ? { pendingSubRuns: subRuns.map((sub) => ({
+			...sub,
+			state: fromJsonSafeRunState(sub.state)
+		})) } : {}
+	};
+}
+
+//#endregion
+export { base64ToBytes, bytesToBase64, fromJsonSafeContentParts, fromJsonSafeMessage, fromJsonSafeRunState, toJsonSafeContentParts, toJsonSafeMessage, toJsonSafeRunState };
+//# sourceMappingURL=binary-json.js.map