@graphorin/agent 0.6.0 → 0.7.0

package/dist/fanout/index.d.ts

@@ -1,5 +1,5 @@
 import { ContentOriginKind, MergeGuardConfig, TrustClass } from "../lateral-leak/merge-guard.js";
-import { AgentEvent } from "@graphorin/core";
+import { AgentEvent, Usage } from "@graphorin/core";
 
 //#region src/fanout/index.d.ts
 
@@ -61,6 +61,11 @@ interface ChildResult<TOutput = unknown> {
   readonly tokensUsed: number;
   readonly toolCallCount: number;
   readonly durationMs: number;
+  /**
+   * Full usage breakdown, present only for usage-reporting children
+   * (an `invoke` resolving to a full `AgentResult`, W-033).
+   */
+  readonly usage?: Usage;
 }
 /**
  * Aggregate result returned by `Agent.fanOut(...)`.
@@ -72,6 +77,13 @@ interface FanOutResult<TOutput = unknown> {
   readonly output: TOutput;
   readonly children: ReadonlyArray<ChildResult<TOutput>>;
   readonly mergeDurationMs: number;
+  /**
+   * Sum of every usage-reporting child's usage (W-033); zero when no
+   * child reported. The fan-out helper never mutates the parent run's
+   * live state (it runs outside the loop and would race it) - folding
+   * this into the parent run's accounting is the caller's decision.
+   */
+  readonly usage: Usage;
 }
 /**
  * Per-call options accepted by `Agent.fanOut(...)`.

package/dist/fanout/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/fanout/index.ts"],"sourcesContent":[],"mappings":";;;;;;AA0EA;AAeA;;;;AAGqB,UA5DJ,cAAA,CA4DI;EAAa;AASlC;;;;;EAOqB,SAAA,MAAA,CAAA,EAAA,MAAA;EAoBE;;;;EAKyB,SAAA,SAAA,CAAA,EAAA,MAAA;EAAZ;EAEV,SAAA,UAAA,CAAA,EAAA,MAAA;;;AAkM1B;;;;AAEW,KArRC,aAqRD,CAAA,UAAA,OAAA,CAAA,GAAA;EAAR,SAAA,IAAA,EAAA,QAAA;EAAO,SAAA,SAAA,CAAA,EAAA,MAAA;;;;;6BAhRuB,cAAc,YAAY,cAAc,QAAQ;;;6BAIhD,cAAc,YAAY,cAAc,QAAQ;;;;;;;;;;UAWhE;;;oBAGG;;;;;;;;;;;;;;UAYH;;mBAEE;qBACE,cAAc,YAAY;;;;;;;;UAS9B;;;;;;;qBAOI;;;;;;;;;2BASM,QAAQ;;0BAET;;sBAEJ;;;;;;;uBAOC;;2BAEI,cAAc;oBACrB;;oCAEgB,YAAY;;0BAEtB;;;;;;;;;wBASF;;;;;;;;;;;;;;;iBAyLF,yBACd,cAAc,WACnB,QAAQ,aAAa"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/fanout/index.ts"],"sourcesContent":[],"mappings":";;;;;;AA2EA;AAoBA;;;;AAGqB,UAjEJ,cAAA,CAiEI;EAQH;;AAQlB;;;;EAoBsB,SAAA,MAAA,CAAA,EAAA,MAAA;EAbD;;;;EAuBD,SAAA,SAAA,CAAA,EAAA,MAAA;EAE4B;EAAZ,SAAA,UAAA,CAAA,EAAA,MAAA;;;;AAsNpC;;;AAEwB,KAnTZ,aAmTY,CAAA,UAAA,OAAA,CAAA,GAAA;EAAb,SAAA,IAAA,EAAA,QAAA;EAAR,SAAA,SAAA,CAAA,EAAA,MAAA;CAAO,GAAA;;;;6BA9SuB,cAAc,YAAY,cAAc,QAAQ;;;6BAIhD,cAAc,YAAY,cAAc,QAAQ;;;;;;;;;;UAWhE;;;oBAGG;;;;;;;;;;;;mBASD;;;;;;;UAQF;;mBAEE;qBACE,cAAc,YAAY;;;;;;;;kBAQ7B;;;;;;;UAQD;;;;;;;qBAOI;;;;;;;;;2BASM,QAAQ;;0BAET;;sBAEJ;;;;;;;uBAOC;;2BAEI,cAAc;oBACrB;;oCAEgB,YAAY;;0BAEtB;;;;;;;;;wBASF;;;;;;;;;;;;;;;iBA2MF,yBACd,cAAc,WACnB,QAAQ,aAAa"}

package/dist/fanout/index.js

@@ -1,5 +1,7 @@
 import { MergeBlockedError } from "../errors/index.js";
 import { computeSourceTrust, evaluateMerge } from "../lateral-leak/merge-guard.js";
+import { accumulateUsage } from "../runtime/messages.js";
+import { zeroUsage } from "@graphorin/core";
 import { createHash } from "node:crypto";
 
 //#region src/fanout/index.ts
@@ -37,10 +39,12 @@ function harvestAgentResult(value) {
 		const calls = step.toolCalls;
 		if (Array.isArray(calls)) toolCallCount += calls.length;
 	}
+	const usage = typeof v.usage.promptTokens === "number" && typeof v.usage.completionTokens === "number" ? v.usage : void 0;
 	return {
 		output: v.output,
 		tokensUsed: v.usage.totalTokens,
-		toolCallCount
+		toolCallCount,
+		...usage !== void 0 ? { usage } : {}
 	};
 }
 /**
@@ -95,7 +99,8 @@ async function runWithSemaphore(children, cap, signal, perBudget, onChildResult)
 					},
 					tokensUsed,
 					toolCallCount,
-					durationMs: Date.now() - start
+					durationMs: Date.now() - start,
+					...report?.usage !== void 0 ? { usage: report.usage } : {}
 				};
 				return {
 					agentId: child.agentId,
@@ -103,7 +108,8 @@ async function runWithSemaphore(children, cap, signal, perBudget, onChildResult)
 					output,
 					tokensUsed,
 					toolCallCount,
-					durationMs: Date.now() - start
+					durationMs: Date.now() - start,
+					...report?.usage !== void 0 ? { usage: report.usage } : {}
 				};
 			} catch (cause) {
 				const message = cause instanceof Error ? cause.message : String(cause);
@@ -239,11 +245,14 @@ async function runFanOut(opts) {
 		mergeDurationMs,
 		childMetadata
 	});
+	const usage = zeroUsage();
+	for (const r of results) if (r.usage !== void 0) accumulateUsage(usage, r.usage);
 	return {
 		fanOutId,
 		output: merged,
 		children: results,
-		mergeDurationMs
+		mergeDurationMs,
+		usage
 	};
 }
 

package/dist/fanout/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["results: ChildResult<TOutput>[]","running: Set<Promise<void>>","timer: ReturnType<typeof setTimeout> | undefined","status: ChildResult<TOutput>['status']","merge: MergeStrategy<TOutput>","merged: TOutput","parts: string[]","childMetadata: FanOutChildMetadata[]"],"sources":["../../src/fanout/index.ts"],"sourcesContent":["/**\n * Agent-step-level fan-out - `Agent.fanOut(...)` convenience that\n * spawns N sub-agents in parallel under a bounded-fanout cap with\n * per-child budgets and four built-in merge strategies.\n *\n * Boundary discipline against the workflow `Dispatch(...)`\n * primitive: fan-out is **agent-step-level inline result** (children\n * share parent `RunContext` lineage; result consumed by parent's\n * continuing loop within one or few `agent.run(...)` calls).\n * `Dispatch(...)` is workflow-step-level checkpointed durable graph.\n * The two compose orthogonally.\n *\n * @packageDocumentation\n */\n\nimport { createHash } from 'node:crypto';\nimport type { AgentEvent, FanOutChildMetadata } from '@graphorin/core';\nimport { MergeBlockedError } from '../errors/index.js';\nimport {\n  type ContentOriginKind,\n  computeSourceTrust,\n  evaluateMerge,\n  type MergeGuardConfig,\n  type TrustClass,\n} from '../lateral-leak/merge-guard.js';\n\n/**\n * Per-child budget. Defaults derived from the canonical 2026\n * scaling-rule table for agent fan-out workloads.\n *\n * @stable\n */\nexport interface PerChildBudget {\n  /**\n   * Max `usage.totalTokens` per child. Enforced **post-hoc** and only\n   * for usage-reporting children (an `invoke` that resolves to a full\n   * `AgentResult` - e.g. `() => child.run(input)`); a child returning a\n   * plain value reports `tokensUsed: 0` and this cap cannot fire.\n   */\n  readonly tokens?: number;\n  /**\n   * Max tool calls per child. Same usage-reporting contract as\n   * {@link PerChildBudget.tokens} (counted from `state.steps`).\n   */\n  readonly toolCalls?: number;\n  /** Wall-clock cap, enforced for every child via a race timer. */\n  readonly durationMs?: number;\n}\n\n/**\n * Built-in merge-strategy taxonomy.\n *\n * @stable\n */\nexport type MergeStrategy<TOutput = unknown> =\n  | { readonly kind: 'concat'; readonly separator?: string }\n  | { readonly kind: 'first-success' }\n  | {\n      readonly kind: 'judge-merge';\n      readonly judge: (children: ReadonlyArray<ChildResult<TOutput>>) => Promise<TOutput>;\n    }\n  | {\n      readonly kind: 'custom';\n      readonly merge: (children: ReadonlyArray<ChildResult<TOutput>>) => Promise<TOutput>;\n    };\n\n/**\n * Per-child outcome surfaced on\n * {@link FanOutResult.children}. Failed-child isolation: a child\n * that throws produces a `ChildResult` with `status: 'failed'` -\n * never an exception thrown from the fan-out call itself.\n *\n * @stable\n */\nexport interface ChildResult<TOutput = unknown> {\n  readonly agentId: string;\n  readonly status: 'completed' | 'failed' | 'budget-exceeded' | 'cancelled';\n  readonly output?: TOutput;\n  readonly error?: { readonly message: string; readonly code: string };\n  readonly tokensUsed: number;\n  readonly toolCallCount: number;\n  readonly durationMs: number;\n}\n\n/**\n * Aggregate result returned by `Agent.fanOut(...)`.\n *\n * @stable\n */\nexport interface FanOutResult<TOutput = unknown> {\n  readonly fanOutId: string;\n  readonly output: TOutput;\n  readonly children: ReadonlyArray<ChildResult<TOutput>>;\n  readonly mergeDurationMs: number;\n}\n\n/**\n * Per-call options accepted by `Agent.fanOut(...)`.\n *\n * @stable\n */\nexport interface FanOutOptions<TOutput = unknown> {\n  /**\n   * The sub-agents to invoke. Each entry is invoked as a function\n   * returning a `Promise<TOutput>` - the fan-out helper does not\n   * impose an `Agent` shape on the children so the runtime can\n   * adapt any callable surface.\n   */\n  readonly children: ReadonlyArray<{\n    readonly agentId: string;\n    /**\n     * Child callable. Resolve to a plain `TOutput`, or to a full\n     * `AgentResult` (e.g. `() => childAgent.run(input)`) - the fan-out\n     * detects the result envelope structurally (`output` + numeric\n     * `usage.totalTokens` + `state`), unwraps `output`, and harvests\n     * `tokensUsed` / `toolCallCount` so per-child budgets can enforce.\n     */\n    readonly invoke: () => Promise<TOutput>;\n    /** Trust-class for the merge guard (default `'loopback'`). */\n    readonly trustClass?: TrustClass;\n    /** Content-origin for the merge guard (default `'built-in'`). */\n    readonly origin?: ContentOriginKind;\n    /** Rolling trust adjustment in `[0,1]` (default `1`). */\n    readonly historyAdjustment?: number;\n  }>;\n  /** Default `4` per the canonical 2026 production lesson. */\n  readonly maxConcurrentChildren?: number;\n  /** Per-child budget; default unset. */\n  readonly perBudget?: PerChildBudget;\n  /** Default `{ kind: 'concat' }`. */\n  readonly mergeStrategy?: MergeStrategy<TOutput>;\n  readonly signal?: AbortSignal;\n  /** Optional callback for per-child completion observability. */\n  readonly onChildResult?: (result: ChildResult<TOutput>) => void;\n  /** Optional event emitter for `agent.fanout.spawned / merged`. */\n  readonly emit?: (event: AgentEvent) => void;\n  /**\n   * Sideways-injection merge guard (AG-7): on `'judge-merge'` the\n   * fan-out scores each child's source trust and contribution weight\n   * against the judge's merged output; a biased merge emits\n   * `agent.lateral-leak.detected` (vector `sideways-injection`) and -\n   * under `strictness: 'detect-and-block'` - throws\n   * {@link MergeBlockedError}.\n   */\n  readonly mergeGuard?: MergeGuardConfig;\n  /** Identifiers required to populate the events. */\n  readonly runId: string;\n  readonly sessionId: string;\n  readonly agentId: string;\n  /** Default - generated from `runId + Date.now()`. */\n  readonly fanOutId?: string;\n}\n\nconst DEFAULT_MAX_CONCURRENT_CHILDREN = 4;\n\n/**\n * Structurally detect a full `AgentResult` returned by a child\n * `invoke` (AG-16): an object carrying `output`, a numeric\n * `usage.totalTokens`, and a `state` with string `id`/`status`. The\n * three-field match makes accidental collision with a user `TOutput`\n * negligible; children whose genuine output looks like this should\n * resolve a plain value instead.\n */\nfunction harvestAgentResult(\n  value: unknown,\n):\n  | { readonly output: unknown; readonly tokensUsed: number; readonly toolCallCount: number }\n  | undefined {\n  if (typeof value !== 'object' || value === null) return undefined;\n  const v = value as {\n    readonly output?: unknown;\n    readonly usage?: { readonly totalTokens?: unknown };\n    readonly state?: { readonly id?: unknown; readonly status?: unknown; readonly steps?: unknown };\n  };\n  if (!('output' in v)) return undefined;\n  if (typeof v.usage?.totalTokens !== 'number') return undefined;\n  if (typeof v.state?.id !== 'string' || typeof v.state.status !== 'string') return undefined;\n  let toolCallCount = 0;\n  if (Array.isArray(v.state.steps)) {\n    for (const step of v.state.steps) {\n      const calls = (step as { readonly toolCalls?: unknown }).toolCalls;\n      if (Array.isArray(calls)) toolCallCount += calls.length;\n    }\n  }\n  return { output: v.output, tokensUsed: v.usage.totalTokens, toolCallCount };\n}\n\n/**\n * Whitespace-token overlap of a child's output against the merged\n * output, in `[0,1]` - the contribution-weight estimate the merge\n * guard's docstring contracts (each child scored independently; a\n * judge parroting one child verbatim yields ~1.0 for that child).\n */\nfunction contributionWeight(childText: string, mergedText: string): number {\n  if (childText.length === 0 || mergedText.length === 0) return 0;\n  const mergedTokens = mergedText.split(/\\s+/).filter((t) => t.length > 0);\n  if (mergedTokens.length === 0) return 0;\n  const childTokens = new Set(childText.split(/\\s+/).filter((t) => t.length > 0));\n  let hits = 0;\n  for (const token of mergedTokens) {\n    if (childTokens.has(token)) hits += 1;\n  }\n  return hits / mergedTokens.length;\n}\n\nasync function runWithSemaphore<TOutput>(\n  children: ReadonlyArray<FanOutOptions<TOutput>['children'][number]>,\n  cap: number,\n  signal: AbortSignal | undefined,\n  perBudget: PerChildBudget | undefined,\n  onChildResult?: (r: ChildResult<TOutput>) => void,\n): Promise<ReadonlyArray<ChildResult<TOutput>>> {\n  const results: ChildResult<TOutput>[] = new Array(children.length);\n  let cursor = 0;\n  const running: Set<Promise<void>> = new Set();\n  const limit = Math.max(1, Math.min(cap, children.length));\n\n  const launchOne = (index: number): Promise<void> => {\n    const child = children[index];\n    if (child === undefined) return Promise.resolve();\n    const start = Date.now();\n    const exec = async (): Promise<ChildResult<TOutput>> => {\n      if (signal?.aborted) {\n        return {\n          agentId: child.agentId,\n          status: 'cancelled',\n          tokensUsed: 0,\n          toolCallCount: 0,\n          durationMs: 0,\n        };\n      }\n      let timer: ReturnType<typeof setTimeout> | undefined;\n      try {\n        const timedPromise =\n          perBudget?.durationMs !== undefined\n            ? new Promise<TOutput>((_, reject) => {\n                timer = setTimeout(\n                  () => reject(new Error('budget-exceeded:durationMs')),\n                  perBudget.durationMs,\n                );\n              })\n            : undefined;\n        const racePromise = timedPromise\n          ? Promise.race([child.invoke(), timedPromise])\n          : child.invoke();\n        const raw = await racePromise;\n        // AG-16: a child resolving to a full AgentResult reports its\n        // real usage - unwrap the output and harvest the counters.\n        const report = harvestAgentResult(raw);\n        const output = (report === undefined ? raw : report.output) as TOutput;\n        const tokensUsed = report?.tokensUsed ?? 0;\n        const toolCallCount = report?.toolCallCount ?? 0;\n        // Post-hoc budget enforcement (only fires for usage-reporting\n        // children): the over-budget output is withheld from the merge.\n        const exceeded =\n          (perBudget?.tokens !== undefined && tokensUsed > perBudget.tokens\n            ? `tokens ${tokensUsed} > ${perBudget.tokens}`\n            : undefined) ??\n          (perBudget?.toolCalls !== undefined && toolCallCount > perBudget.toolCalls\n            ? `toolCalls ${toolCallCount} > ${perBudget.toolCalls}`\n            : undefined);\n        if (exceeded !== undefined) {\n          return {\n            agentId: child.agentId,\n            status: 'budget-exceeded',\n            error: { message: `budget-exceeded: ${exceeded}`, code: 'budget-exceeded' },\n            tokensUsed,\n            toolCallCount,\n            durationMs: Date.now() - start,\n          };\n        }\n        return {\n          agentId: child.agentId,\n          status: 'completed',\n          output,\n          tokensUsed,\n          toolCallCount,\n          durationMs: Date.now() - start,\n        };\n      } catch (cause) {\n        const message = cause instanceof Error ? cause.message : String(cause);\n        const aborted = signal?.aborted;\n        const status: ChildResult<TOutput>['status'] = message.startsWith('budget-exceeded')\n          ? 'budget-exceeded'\n          : aborted\n            ? 'cancelled'\n            : 'failed';\n        return {\n          agentId: child.agentId,\n          status,\n          error: { message, code: status },\n          tokensUsed: 0,\n          toolCallCount: 0,\n          durationMs: Date.now() - start,\n        };\n      } finally {\n        // AG-16: the duration timer must die on EVERY path - leaving it\n        // armed on rejection held the event loop open.\n        if (timer !== undefined) clearTimeout(timer);\n      }\n    };\n    const promise = exec().then((r) => {\n      results[index] = r;\n      onChildResult?.(r);\n    });\n    running.add(promise);\n    promise.finally(() => running.delete(promise));\n    return promise;\n  };\n\n  while (cursor < children.length || running.size > 0) {\n    while (running.size < limit && cursor < children.length) {\n      void launchOne(cursor);\n      cursor += 1;\n    }\n    if (running.size > 0) {\n      await Promise.race(running);\n    }\n  }\n  return results;\n}\n\n/**\n * Run a fan-out and produce the aggregate {@link FanOutResult}.\n * Pure with respect to side effects - the runtime emits events /\n * audit rows / counter increments via the supplied `emit` callback.\n *\n * @stable\n */\nexport async function runFanOut<TOutput>(\n  opts: FanOutOptions<TOutput>,\n): Promise<FanOutResult<TOutput>> {\n  const fanOutId = opts.fanOutId ?? `fanout-${opts.runId.slice(-8)}-${Date.now().toString(36)}`;\n  const merge: MergeStrategy<TOutput> = opts.mergeStrategy ?? {\n    kind: 'concat',\n  };\n  const cap = opts.maxConcurrentChildren ?? DEFAULT_MAX_CONCURRENT_CHILDREN;\n\n  opts.emit?.({\n    type: 'agent.fanout.spawned',\n    runId: opts.runId,\n    sessionId: opts.sessionId,\n    agentId: opts.agentId,\n    fanOutId,\n    childCount: opts.children.length,\n    mergeStrategyKind: merge.kind,\n    spawnedAtIso: new Date().toISOString(),\n  });\n\n  const results = await runWithSemaphore<TOutput>(\n    opts.children,\n    cap,\n    opts.signal,\n    opts.perBudget,\n    opts.onChildResult,\n  );\n\n  const mergeStart = Date.now();\n  let merged: TOutput;\n  switch (merge.kind) {\n    case 'concat': {\n      const sep = merge.separator ?? '\\n\\n---\\n\\n';\n      const parts: string[] = [];\n      for (const r of results) {\n        if (r.status === 'completed' && r.output !== undefined) {\n          parts.push(typeof r.output === 'string' ? r.output : JSON.stringify(r.output));\n        } else if (\n          r.status === 'failed' ||\n          r.status === 'budget-exceeded' ||\n          r.status === 'cancelled'\n        ) {\n          parts.push(`[${r.status}: ${r.agentId}]`);\n        }\n      }\n      merged = parts.join(sep) as unknown as TOutput;\n      break;\n    }\n    case 'first-success': {\n      const first = results.find((r) => r.status === 'completed');\n      merged = first?.output ?? ('' as unknown as TOutput);\n      break;\n    }\n    case 'judge-merge': {\n      merged = await merge.judge(results);\n      // AG-7: the sideways-injection merge guard scores each child's\n      // source trust × contribution weight against the judge's merged\n      // output. A biased merge emits `agent.lateral-leak.detected`;\n      // 'detect-and-block' refuses the merge entirely.\n      if (opts.mergeGuard !== undefined && opts.mergeGuard.strictness !== 'off') {\n        const mergedText = typeof merged === 'string' ? merged : JSON.stringify(merged);\n        const overrides = opts.mergeGuard.sourceTrustOverrides ?? {};\n        const perChild = results.map((r, i) => {\n          const c = opts.children[i];\n          const childText =\n            r.output === undefined\n              ? ''\n              : typeof r.output === 'string'\n                ? r.output\n                : JSON.stringify(r.output);\n          return {\n            agentId: r.agentId,\n            sourceTrust: computeSourceTrust(\n              {\n                agentId: r.agentId,\n                trustClass: c?.trustClass ?? 'loopback',\n                origin: c?.origin ?? 'built-in',\n                ...(c?.historyAdjustment !== undefined\n                  ? { historyAdjustment: c.historyAdjustment }\n                  : {}),\n              },\n              overrides,\n            ),\n            contributionWeight: contributionWeight(childText, mergedText),\n          };\n        });\n        const verdict = evaluateMerge(perChild, opts.mergeGuard);\n        if (verdict.biased) {\n          opts.emit?.({\n            type: 'agent.lateral-leak.detected',\n            runId: opts.runId,\n            sessionId: opts.sessionId,\n            agentId: opts.agentId,\n            vector: 'sideways-injection',\n            severity: verdict.decision === 'block' ? 'block' : 'warn',\n            causalityChain: verdict.offendingChild === undefined ? [] : [verdict.offendingChild],\n            messageContentSha256: createHash('sha256').update(mergedText, 'utf8').digest('hex'),\n            decision:\n              verdict.decision === 'block'\n                ? 'block'\n                : verdict.decision === 'flag'\n                  ? 'flag'\n                  : 'detect',\n            detectedAtIso: new Date().toISOString(),\n          });\n          if (verdict.decision === 'block') {\n            throw new MergeBlockedError(\n              fanOutId,\n              `low-trust child '${verdict.offendingChild}' (sourceTrust ${verdict.sourceTrust?.toFixed(2)}) contributes ${(\n                (verdict.contributionWeight ?? 0) * 100\n              ).toFixed(0)}% of the merged output`,\n            );\n          }\n        }\n      }\n      break;\n    }\n    case 'custom':\n      merged = await merge.merge(results);\n      break;\n    default: {\n      const _exhaustive: never = merge;\n      void _exhaustive;\n      merged = '' as unknown as TOutput;\n    }\n  }\n  const mergeDurationMs = Date.now() - mergeStart;\n\n  const childMetadata: FanOutChildMetadata[] = results.map((r) => ({\n    agentId: r.agentId,\n    status: r.status,\n    tokensUsed: r.tokensUsed,\n    toolCallCount: r.toolCallCount,\n    durationMs: r.durationMs,\n  }));\n  const successfulChildCount = results.filter((r) => r.status === 'completed').length;\n\n  opts.emit?.({\n    type: 'agent.fanout.merged',\n    runId: opts.runId,\n    sessionId: opts.sessionId,\n    agentId: opts.agentId,\n    fanOutId,\n    childCount: opts.children.length,\n    successfulChildCount,\n    mergeStrategyKind: merge.kind,\n    mergeDurationMs,\n    childMetadata,\n  });\n\n  return {\n    fanOutId,\n    output: merged,\n    children: results,\n    mergeDurationMs,\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["results: ChildResult<TOutput>[]","running: Set<Promise<void>>","timer: ReturnType<typeof setTimeout> | undefined","status: ChildResult<TOutput>['status']","merge: MergeStrategy<TOutput>","merged: TOutput","parts: string[]","childMetadata: FanOutChildMetadata[]"],"sources":["../../src/fanout/index.ts"],"sourcesContent":["/**\n * Agent-step-level fan-out - `Agent.fanOut(...)` convenience that\n * spawns N sub-agents in parallel under a bounded-fanout cap with\n * per-child budgets and four built-in merge strategies.\n *\n * Boundary discipline against the workflow `Dispatch(...)`\n * primitive: fan-out is **agent-step-level inline result** (children\n * share parent `RunContext` lineage; result consumed by parent's\n * continuing loop within one or few `agent.run(...)` calls).\n * `Dispatch(...)` is workflow-step-level checkpointed durable graph.\n * The two compose orthogonally.\n *\n * @packageDocumentation\n */\n\nimport { createHash } from 'node:crypto';\nimport { type AgentEvent, type FanOutChildMetadata, type Usage, zeroUsage } from '@graphorin/core';\nimport { MergeBlockedError } from '../errors/index.js';\nimport {\n  type ContentOriginKind,\n  computeSourceTrust,\n  evaluateMerge,\n  type MergeGuardConfig,\n  type TrustClass,\n} from '../lateral-leak/merge-guard.js';\nimport { accumulateUsage } from '../runtime/messages.js';\n\n/**\n * Per-child budget. Defaults derived from the canonical 2026\n * scaling-rule table for agent fan-out workloads.\n *\n * @stable\n */\nexport interface PerChildBudget {\n  /**\n   * Max `usage.totalTokens` per child. Enforced **post-hoc** and only\n   * for usage-reporting children (an `invoke` that resolves to a full\n   * `AgentResult` - e.g. `() => child.run(input)`); a child returning a\n   * plain value reports `tokensUsed: 0` and this cap cannot fire.\n   */\n  readonly tokens?: number;\n  /**\n   * Max tool calls per child. Same usage-reporting contract as\n   * {@link PerChildBudget.tokens} (counted from `state.steps`).\n   */\n  readonly toolCalls?: number;\n  /** Wall-clock cap, enforced for every child via a race timer. */\n  readonly durationMs?: number;\n}\n\n/**\n * Built-in merge-strategy taxonomy.\n *\n * @stable\n */\nexport type MergeStrategy<TOutput = unknown> =\n  | { readonly kind: 'concat'; readonly separator?: string }\n  | { readonly kind: 'first-success' }\n  | {\n      readonly kind: 'judge-merge';\n      readonly judge: (children: ReadonlyArray<ChildResult<TOutput>>) => Promise<TOutput>;\n    }\n  | {\n      readonly kind: 'custom';\n      readonly merge: (children: ReadonlyArray<ChildResult<TOutput>>) => Promise<TOutput>;\n    };\n\n/**\n * Per-child outcome surfaced on\n * {@link FanOutResult.children}. Failed-child isolation: a child\n * that throws produces a `ChildResult` with `status: 'failed'` -\n * never an exception thrown from the fan-out call itself.\n *\n * @stable\n */\nexport interface ChildResult<TOutput = unknown> {\n  readonly agentId: string;\n  readonly status: 'completed' | 'failed' | 'budget-exceeded' | 'cancelled';\n  readonly output?: TOutput;\n  readonly error?: { readonly message: string; readonly code: string };\n  readonly tokensUsed: number;\n  readonly toolCallCount: number;\n  readonly durationMs: number;\n  /**\n   * Full usage breakdown, present only for usage-reporting children\n   * (an `invoke` resolving to a full `AgentResult`, W-033).\n   */\n  readonly usage?: Usage;\n}\n\n/**\n * Aggregate result returned by `Agent.fanOut(...)`.\n *\n * @stable\n */\nexport interface FanOutResult<TOutput = unknown> {\n  readonly fanOutId: string;\n  readonly output: TOutput;\n  readonly children: ReadonlyArray<ChildResult<TOutput>>;\n  readonly mergeDurationMs: number;\n  /**\n   * Sum of every usage-reporting child's usage (W-033); zero when no\n   * child reported. The fan-out helper never mutates the parent run's\n   * live state (it runs outside the loop and would race it) - folding\n   * this into the parent run's accounting is the caller's decision.\n   */\n  readonly usage: Usage;\n}\n\n/**\n * Per-call options accepted by `Agent.fanOut(...)`.\n *\n * @stable\n */\nexport interface FanOutOptions<TOutput = unknown> {\n  /**\n   * The sub-agents to invoke. Each entry is invoked as a function\n   * returning a `Promise<TOutput>` - the fan-out helper does not\n   * impose an `Agent` shape on the children so the runtime can\n   * adapt any callable surface.\n   */\n  readonly children: ReadonlyArray<{\n    readonly agentId: string;\n    /**\n     * Child callable. Resolve to a plain `TOutput`, or to a full\n     * `AgentResult` (e.g. `() => childAgent.run(input)`) - the fan-out\n     * detects the result envelope structurally (`output` + numeric\n     * `usage.totalTokens` + `state`), unwraps `output`, and harvests\n     * `tokensUsed` / `toolCallCount` so per-child budgets can enforce.\n     */\n    readonly invoke: () => Promise<TOutput>;\n    /** Trust-class for the merge guard (default `'loopback'`). */\n    readonly trustClass?: TrustClass;\n    /** Content-origin for the merge guard (default `'built-in'`). */\n    readonly origin?: ContentOriginKind;\n    /** Rolling trust adjustment in `[0,1]` (default `1`). */\n    readonly historyAdjustment?: number;\n  }>;\n  /** Default `4` per the canonical 2026 production lesson. */\n  readonly maxConcurrentChildren?: number;\n  /** Per-child budget; default unset. */\n  readonly perBudget?: PerChildBudget;\n  /** Default `{ kind: 'concat' }`. */\n  readonly mergeStrategy?: MergeStrategy<TOutput>;\n  readonly signal?: AbortSignal;\n  /** Optional callback for per-child completion observability. */\n  readonly onChildResult?: (result: ChildResult<TOutput>) => void;\n  /** Optional event emitter for `agent.fanout.spawned / merged`. */\n  readonly emit?: (event: AgentEvent) => void;\n  /**\n   * Sideways-injection merge guard (AG-7): on `'judge-merge'` the\n   * fan-out scores each child's source trust and contribution weight\n   * against the judge's merged output; a biased merge emits\n   * `agent.lateral-leak.detected` (vector `sideways-injection`) and -\n   * under `strictness: 'detect-and-block'` - throws\n   * {@link MergeBlockedError}.\n   */\n  readonly mergeGuard?: MergeGuardConfig;\n  /** Identifiers required to populate the events. */\n  readonly runId: string;\n  readonly sessionId: string;\n  readonly agentId: string;\n  /** Default - generated from `runId + Date.now()`. */\n  readonly fanOutId?: string;\n}\n\nconst DEFAULT_MAX_CONCURRENT_CHILDREN = 4;\n\n/**\n * Structurally detect a full `AgentResult` returned by a child\n * `invoke` (AG-16): an object carrying `output`, a numeric\n * `usage.totalTokens`, and a `state` with string `id`/`status`. The\n * three-field match makes accidental collision with a user `TOutput`\n * negligible; children whose genuine output looks like this should\n * resolve a plain value instead.\n */\nfunction harvestAgentResult(value: unknown):\n  | {\n      readonly output: unknown;\n      readonly tokensUsed: number;\n      readonly toolCallCount: number;\n      readonly usage?: Usage;\n    }\n  | undefined {\n  if (typeof value !== 'object' || value === null) return undefined;\n  const v = value as {\n    readonly output?: unknown;\n    readonly usage?: {\n      readonly totalTokens?: unknown;\n      readonly promptTokens?: unknown;\n      readonly completionTokens?: unknown;\n    };\n    readonly state?: { readonly id?: unknown; readonly status?: unknown; readonly steps?: unknown };\n  };\n  if (!('output' in v)) return undefined;\n  if (typeof v.usage?.totalTokens !== 'number') return undefined;\n  if (typeof v.state?.id !== 'string' || typeof v.state.status !== 'string') return undefined;\n  let toolCallCount = 0;\n  if (Array.isArray(v.state.steps)) {\n    for (const step of v.state.steps) {\n      const calls = (step as { readonly toolCalls?: unknown }).toolCalls;\n      if (Array.isArray(calls)) toolCallCount += calls.length;\n    }\n  }\n  const usage =\n    typeof v.usage.promptTokens === 'number' && typeof v.usage.completionTokens === 'number'\n      ? (v.usage as Usage)\n      : undefined;\n  return {\n    output: v.output,\n    tokensUsed: v.usage.totalTokens,\n    toolCallCount,\n    ...(usage !== undefined ? { usage } : {}),\n  };\n}\n\n/**\n * Whitespace-token overlap of a child's output against the merged\n * output, in `[0,1]` - the contribution-weight estimate the merge\n * guard's docstring contracts (each child scored independently; a\n * judge parroting one child verbatim yields ~1.0 for that child).\n */\nfunction contributionWeight(childText: string, mergedText: string): number {\n  if (childText.length === 0 || mergedText.length === 0) return 0;\n  const mergedTokens = mergedText.split(/\\s+/).filter((t) => t.length > 0);\n  if (mergedTokens.length === 0) return 0;\n  const childTokens = new Set(childText.split(/\\s+/).filter((t) => t.length > 0));\n  let hits = 0;\n  for (const token of mergedTokens) {\n    if (childTokens.has(token)) hits += 1;\n  }\n  return hits / mergedTokens.length;\n}\n\nasync function runWithSemaphore<TOutput>(\n  children: ReadonlyArray<FanOutOptions<TOutput>['children'][number]>,\n  cap: number,\n  signal: AbortSignal | undefined,\n  perBudget: PerChildBudget | undefined,\n  onChildResult?: (r: ChildResult<TOutput>) => void,\n): Promise<ReadonlyArray<ChildResult<TOutput>>> {\n  const results: ChildResult<TOutput>[] = new Array(children.length);\n  let cursor = 0;\n  const running: Set<Promise<void>> = new Set();\n  const limit = Math.max(1, Math.min(cap, children.length));\n\n  const launchOne = (index: number): Promise<void> => {\n    const child = children[index];\n    if (child === undefined) return Promise.resolve();\n    const start = Date.now();\n    const exec = async (): Promise<ChildResult<TOutput>> => {\n      if (signal?.aborted) {\n        return {\n          agentId: child.agentId,\n          status: 'cancelled',\n          tokensUsed: 0,\n          toolCallCount: 0,\n          durationMs: 0,\n        };\n      }\n      let timer: ReturnType<typeof setTimeout> | undefined;\n      try {\n        const timedPromise =\n          perBudget?.durationMs !== undefined\n            ? new Promise<TOutput>((_, reject) => {\n                timer = setTimeout(\n                  () => reject(new Error('budget-exceeded:durationMs')),\n                  perBudget.durationMs,\n                );\n              })\n            : undefined;\n        const racePromise = timedPromise\n          ? Promise.race([child.invoke(), timedPromise])\n          : child.invoke();\n        const raw = await racePromise;\n        // AG-16: a child resolving to a full AgentResult reports its\n        // real usage - unwrap the output and harvest the counters.\n        const report = harvestAgentResult(raw);\n        const output = (report === undefined ? raw : report.output) as TOutput;\n        const tokensUsed = report?.tokensUsed ?? 0;\n        const toolCallCount = report?.toolCallCount ?? 0;\n        // Post-hoc budget enforcement (only fires for usage-reporting\n        // children): the over-budget output is withheld from the merge.\n        const exceeded =\n          (perBudget?.tokens !== undefined && tokensUsed > perBudget.tokens\n            ? `tokens ${tokensUsed} > ${perBudget.tokens}`\n            : undefined) ??\n          (perBudget?.toolCalls !== undefined && toolCallCount > perBudget.toolCalls\n            ? `toolCalls ${toolCallCount} > ${perBudget.toolCalls}`\n            : undefined);\n        if (exceeded !== undefined) {\n          return {\n            agentId: child.agentId,\n            status: 'budget-exceeded',\n            error: { message: `budget-exceeded: ${exceeded}`, code: 'budget-exceeded' },\n            tokensUsed,\n            toolCallCount,\n            durationMs: Date.now() - start,\n            ...(report?.usage !== undefined ? { usage: report.usage } : {}),\n          };\n        }\n        return {\n          agentId: child.agentId,\n          status: 'completed',\n          output,\n          tokensUsed,\n          toolCallCount,\n          durationMs: Date.now() - start,\n          ...(report?.usage !== undefined ? { usage: report.usage } : {}),\n        };\n      } catch (cause) {\n        const message = cause instanceof Error ? cause.message : String(cause);\n        const aborted = signal?.aborted;\n        const status: ChildResult<TOutput>['status'] = message.startsWith('budget-exceeded')\n          ? 'budget-exceeded'\n          : aborted\n            ? 'cancelled'\n            : 'failed';\n        return {\n          agentId: child.agentId,\n          status,\n          error: { message, code: status },\n          tokensUsed: 0,\n          toolCallCount: 0,\n          durationMs: Date.now() - start,\n        };\n      } finally {\n        // AG-16: the duration timer must die on EVERY path - leaving it\n        // armed on rejection held the event loop open.\n        if (timer !== undefined) clearTimeout(timer);\n      }\n    };\n    const promise = exec().then((r) => {\n      results[index] = r;\n      onChildResult?.(r);\n    });\n    running.add(promise);\n    promise.finally(() => running.delete(promise));\n    return promise;\n  };\n\n  while (cursor < children.length || running.size > 0) {\n    while (running.size < limit && cursor < children.length) {\n      void launchOne(cursor);\n      cursor += 1;\n    }\n    if (running.size > 0) {\n      await Promise.race(running);\n    }\n  }\n  return results;\n}\n\n/**\n * Run a fan-out and produce the aggregate {@link FanOutResult}.\n * Pure with respect to side effects - the runtime emits events /\n * audit rows / counter increments via the supplied `emit` callback.\n *\n * @stable\n */\nexport async function runFanOut<TOutput>(\n  opts: FanOutOptions<TOutput>,\n): Promise<FanOutResult<TOutput>> {\n  const fanOutId = opts.fanOutId ?? `fanout-${opts.runId.slice(-8)}-${Date.now().toString(36)}`;\n  const merge: MergeStrategy<TOutput> = opts.mergeStrategy ?? {\n    kind: 'concat',\n  };\n  const cap = opts.maxConcurrentChildren ?? DEFAULT_MAX_CONCURRENT_CHILDREN;\n\n  opts.emit?.({\n    type: 'agent.fanout.spawned',\n    runId: opts.runId,\n    sessionId: opts.sessionId,\n    agentId: opts.agentId,\n    fanOutId,\n    childCount: opts.children.length,\n    mergeStrategyKind: merge.kind,\n    spawnedAtIso: new Date().toISOString(),\n  });\n\n  const results = await runWithSemaphore<TOutput>(\n    opts.children,\n    cap,\n    opts.signal,\n    opts.perBudget,\n    opts.onChildResult,\n  );\n\n  const mergeStart = Date.now();\n  let merged: TOutput;\n  switch (merge.kind) {\n    case 'concat': {\n      const sep = merge.separator ?? '\\n\\n---\\n\\n';\n      const parts: string[] = [];\n      for (const r of results) {\n        if (r.status === 'completed' && r.output !== undefined) {\n          parts.push(typeof r.output === 'string' ? r.output : JSON.stringify(r.output));\n        } else if (\n          r.status === 'failed' ||\n          r.status === 'budget-exceeded' ||\n          r.status === 'cancelled'\n        ) {\n          parts.push(`[${r.status}: ${r.agentId}]`);\n        }\n      }\n      merged = parts.join(sep) as unknown as TOutput;\n      break;\n    }\n    case 'first-success': {\n      const first = results.find((r) => r.status === 'completed');\n      merged = first?.output ?? ('' as unknown as TOutput);\n      break;\n    }\n    case 'judge-merge': {\n      merged = await merge.judge(results);\n      // AG-7: the sideways-injection merge guard scores each child's\n      // source trust × contribution weight against the judge's merged\n      // output. A biased merge emits `agent.lateral-leak.detected`;\n      // 'detect-and-block' refuses the merge entirely.\n      if (opts.mergeGuard !== undefined && opts.mergeGuard.strictness !== 'off') {\n        const mergedText = typeof merged === 'string' ? merged : JSON.stringify(merged);\n        const overrides = opts.mergeGuard.sourceTrustOverrides ?? {};\n        const perChild = results.map((r, i) => {\n          const c = opts.children[i];\n          const childText =\n            r.output === undefined\n              ? ''\n              : typeof r.output === 'string'\n                ? r.output\n                : JSON.stringify(r.output);\n          return {\n            agentId: r.agentId,\n            sourceTrust: computeSourceTrust(\n              {\n                agentId: r.agentId,\n                trustClass: c?.trustClass ?? 'loopback',\n                origin: c?.origin ?? 'built-in',\n                ...(c?.historyAdjustment !== undefined\n                  ? { historyAdjustment: c.historyAdjustment }\n                  : {}),\n              },\n              overrides,\n            ),\n            contributionWeight: contributionWeight(childText, mergedText),\n          };\n        });\n        const verdict = evaluateMerge(perChild, opts.mergeGuard);\n        if (verdict.biased) {\n          opts.emit?.({\n            type: 'agent.lateral-leak.detected',\n            runId: opts.runId,\n            sessionId: opts.sessionId,\n            agentId: opts.agentId,\n            vector: 'sideways-injection',\n            severity: verdict.decision === 'block' ? 'block' : 'warn',\n            causalityChain: verdict.offendingChild === undefined ? [] : [verdict.offendingChild],\n            messageContentSha256: createHash('sha256').update(mergedText, 'utf8').digest('hex'),\n            decision:\n              verdict.decision === 'block'\n                ? 'block'\n                : verdict.decision === 'flag'\n                  ? 'flag'\n                  : 'detect',\n            detectedAtIso: new Date().toISOString(),\n          });\n          if (verdict.decision === 'block') {\n            throw new MergeBlockedError(\n              fanOutId,\n              `low-trust child '${verdict.offendingChild}' (sourceTrust ${verdict.sourceTrust?.toFixed(2)}) contributes ${(\n                (verdict.contributionWeight ?? 0) * 100\n              ).toFixed(0)}% of the merged output`,\n            );\n          }\n        }\n      }\n      break;\n    }\n    case 'custom':\n      merged = await merge.merge(results);\n      break;\n    default: {\n      const _exhaustive: never = merge;\n      void _exhaustive;\n      merged = '' as unknown as TOutput;\n    }\n  }\n  const mergeDurationMs = Date.now() - mergeStart;\n\n  const childMetadata: FanOutChildMetadata[] = results.map((r) => ({\n    agentId: r.agentId,\n    status: r.status,\n    tokensUsed: r.tokensUsed,\n    toolCallCount: r.toolCallCount,\n    durationMs: r.durationMs,\n  }));\n  const successfulChildCount = results.filter((r) => r.status === 'completed').length;\n\n  opts.emit?.({\n    type: 'agent.fanout.merged',\n    runId: opts.runId,\n    sessionId: opts.sessionId,\n    agentId: opts.agentId,\n    fanOutId,\n    childCount: opts.children.length,\n    successfulChildCount,\n    mergeStrategyKind: merge.kind,\n    mergeDurationMs,\n    childMetadata,\n  });\n\n  const usage = zeroUsage();\n  for (const r of results) {\n    if (r.usage !== undefined) accumulateUsage(usage, r.usage);\n  }\n\n  return {\n    fanOutId,\n    output: merged,\n    children: results,\n    mergeDurationMs,\n    usage,\n  };\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -1,17 +1,19 @@
-import { AgentResolutionError, AgentRuntimeError, AgentRuntimeErrorCode, EvaluatorOptimizerConfigError, InvalidAgentConfigError, InvalidPreferredModelError, MergeBlockedError, MultipleHandoffsInStepError, ProgressWriteError, ProtocolInjectionRejectError, ProviderMiddlewareOrderError, RunStateMalformedError, RunStateVersionUnsupportedError, ToolNotFoundError } from "./errors/index.js";
+import { AgentResolutionError, AgentRuntimeError, AgentRuntimeErrorCode, EvaluatorOptimizerConfigError, InvalidAgentConfigError, InvalidPreferredModelError, MergeBlockedError, MultipleHandoffsInStepError, ProgressWriteError, ProtocolInjectionRejectError, ProviderMiddlewareOrderError, RunStateMalformedError, RunStateVersionUnsupportedError, SubAgentResumeTargetNotFoundError, ToolNotFoundError } from "./errors/index.js";
 import { EvaluatorCallable, EvaluatorOptimizerOptions, EvaluatorOptimizerOutcome, EvaluatorOutcome, GeneratorCallable, Rubric, evaluatorOptimizer } from "./evaluator-optimizer/index.js";
 import { AgentFallbackEligibility, AgentFallbackPolicy, AgentFallbackReason, isAgentFallbackEligible } from "./fallback/index.js";
 import { ChildTrustInput, ContentOriginKind, MergeBiasDecision, MergeGuardConfig, TrustClass, computeSourceTrust, evaluateMerge } from "./lateral-leak/merge-guard.js";
 import { ChildResult, FanOutOptions, FanOutResult, MergeStrategy, PerChildBudget, runFanOut } from "./fanout/index.js";
 import { CausalityMonitor, CausalityMonitorCheck, CausalityMonitorConfig, CausalityMonitorStrictness, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH } from "./lateral-leak/causality-monitor.js";
 import { ProgressIO, ProgressIOConfig, ProgressReadOptions, ProgressWriteOptions, createProgressIO } from "./progress/index.js";
-import { AbortOptions, Agent, AgentCallOptions, AgentCapability, AgentConfig, AgentInput, AgentToToolOptions, CompactOptions, CompactionApiResult, OutputSpec, PostCompactionHook, PrepareStepHook, PrepareStepOverrides, ResponseVerifier, ResumeDirective, SkillsRegistryLike, VerifierResult } from "./types.js";
+import { AbortOptions, Agent, AgentCallOptions, AgentCapability, AgentConfig, AgentInput, AgentToToolOptions, CompactOptions, CompactionApiResult, HandoffEntry, OutputSpec, PostCompactionHook, PrepareStepHook, PrepareStepOverrides, ResponseVerifier, ResumeDirective, SkillsRegistryLike, VerifierResult } from "./types.js";
 import { createAgent } from "./factory.js";
 import { DescribedFilter, FILTER_KIND_CUSTOM, bySensitivity, compose, custom, defaultHandoffFilter, filters, full, lastN, lastUser, stripReasoning, stripSensitiveOutputs, stripToolCalls, summary } from "./filters/index.js";
 import { GuardOutcome, ProtocolBoundary, ProtocolEscapePolicy, ProtocolGuardConfig, guardOutboundContent, resolvePolicy } from "./lateral-leak/protocol-guard.js";
 import "./lateral-leak/index.js";
 import { PreferredModelResolution, ResolvePreferredModelInput, pickTopTierAcrossTools, resolvePreferredModel } from "./preferred-model/index.js";
-import { RUN_STATE_SCHEMA_MAJOR_SUPPORTED, RUN_STATE_SCHEMA_VERSION, SerializeRunStateOptions, SerializedRunState, addModelUsage, aggregateUsageFromByModel, completedToolCallsFromState, createInitialRunState, deserializeRunState, runStateFromJSON, runStateToJSON, serializeRunState } from "./run-state/index.js";
+import { RUN_STATE_SCHEMA_MAJOR_SUPPORTED, RUN_STATE_SCHEMA_VERSION, SerializeRunStateOptions, SerializedPendingSubRun, SerializedRunState, addModelUsage, aggregateUsageFromByModel, completedToolCallsFromState, createInitialRunState, deserializeRunState, runStateFromJSON, runStateToJSON, serializeRunState } from "./run-state/index.js";
+import { SUBAGENT_TOOL, SubAgentFoldTaint, SubAgentToolRefs, getSubAgentToolRefs } from "./runtime/agent-to-tool.js";
+import { foldChildRunUsage } from "./runtime/messages.js";
 import { ReplayProviderOptions, createReplayProvider } from "./testing/replay-provider.js";
 import { GuardrailContext, GuardrailDefinition, GuardrailResult, InputGuardrail, OutputGuardrail } from "@graphorin/security/guardrails";
 
@@ -45,8 +47,7 @@ import { GuardrailContext, GuardrailDefinition, GuardrailResult, InputGuardrail,
  *
  * @packageDocumentation
  */
-/** Canonical version constant. Mirrors the `package.json` version. */
-declare const VERSION = "0.6.0";
+declare const VERSION: string;
 //#endregion
-export { type AbortOptions, type Agent, type AgentCallOptions, type AgentCapability, type AgentConfig, type AgentFallbackEligibility, type AgentFallbackPolicy, type AgentFallbackReason, type AgentInput, AgentResolutionError, AgentRuntimeError, type AgentRuntimeErrorCode, type AgentToToolOptions, CausalityMonitor, type CausalityMonitorCheck, type CausalityMonitorConfig, type CausalityMonitorStrictness, type ChildResult, type ChildTrustInput, type CompactOptions, type CompactionApiResult, type ContentOriginKind, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH, type DescribedFilter, type EvaluatorCallable, EvaluatorOptimizerConfigError, type EvaluatorOptimizerOptions, type EvaluatorOptimizerOutcome, type EvaluatorOutcome, FILTER_KIND_CUSTOM, type FanOutOptions, type FanOutResult, type GeneratorCallable, type GuardOutcome, type GuardrailContext, type GuardrailDefinition, type GuardrailResult, type InputGuardrail, InvalidAgentConfigError, InvalidPreferredModelError, type MergeBiasDecision, MergeBlockedError, type MergeGuardConfig, type MergeStrategy, MultipleHandoffsInStepError, type OutputGuardrail, type OutputSpec, type PerChildBudget, type PostCompactionHook, type PreferredModelResolution, type PrepareStepHook, type PrepareStepOverrides, type ProgressIO, type ProgressIOConfig, type ProgressReadOptions, ProgressWriteError, type ProgressWriteOptions, type ProtocolBoundary, type ProtocolEscapePolicy, type ProtocolGuardConfig, ProtocolInjectionRejectError, ProviderMiddlewareOrderError, RUN_STATE_SCHEMA_MAJOR_SUPPORTED, RUN_STATE_SCHEMA_VERSION, type ReplayProviderOptions, type ResolvePreferredModelInput, type ResponseVerifier, type ResumeDirective, type Rubric, RunStateMalformedError, RunStateVersionUnsupportedError, type SerializeRunStateOptions, type SerializedRunState, type SkillsRegistryLike, ToolNotFoundError, type TrustClass, VERSION, type VerifierResult, addModelUsage, aggregateUsageFromByModel, bySensitivity, completedToolCallsFromState, compose, computeSourceTrust, createAgent, createInitialRunState, createProgressIO, createReplayProvider, custom, defaultHandoffFilter, deserializeRunState, evaluateMerge, evaluatorOptimizer, filters, full, guardOutboundContent, isAgentFallbackEligible, lastN, lastUser, pickTopTierAcrossTools, resolvePolicy, resolvePreferredModel, runFanOut, runStateFromJSON, runStateToJSON, serializeRunState, stripReasoning, stripSensitiveOutputs, stripToolCalls, summary };
+export { type AbortOptions, type Agent, type AgentCallOptions, type AgentCapability, type AgentConfig, type AgentFallbackEligibility, type AgentFallbackPolicy, type AgentFallbackReason, type AgentInput, AgentResolutionError, AgentRuntimeError, type AgentRuntimeErrorCode, type AgentToToolOptions, CausalityMonitor, type CausalityMonitorCheck, type CausalityMonitorConfig, type CausalityMonitorStrictness, type ChildResult, type ChildTrustInput, type CompactOptions, type CompactionApiResult, type ContentOriginKind, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH, type DescribedFilter, type EvaluatorCallable, EvaluatorOptimizerConfigError, type EvaluatorOptimizerOptions, type EvaluatorOptimizerOutcome, type EvaluatorOutcome, FILTER_KIND_CUSTOM, type FanOutOptions, type FanOutResult, type GeneratorCallable, type GuardOutcome, type GuardrailContext, type GuardrailDefinition, type GuardrailResult, type HandoffEntry, type InputGuardrail, InvalidAgentConfigError, InvalidPreferredModelError, type MergeBiasDecision, MergeBlockedError, type MergeGuardConfig, type MergeStrategy, MultipleHandoffsInStepError, type OutputGuardrail, type OutputSpec, type PerChildBudget, type PostCompactionHook, type PreferredModelResolution, type PrepareStepHook, type PrepareStepOverrides, type ProgressIO, type ProgressIOConfig, type ProgressReadOptions, ProgressWriteError, type ProgressWriteOptions, type ProtocolBoundary, type ProtocolEscapePolicy, type ProtocolGuardConfig, ProtocolInjectionRejectError, ProviderMiddlewareOrderError, RUN_STATE_SCHEMA_MAJOR_SUPPORTED, RUN_STATE_SCHEMA_VERSION, type ReplayProviderOptions, type ResolvePreferredModelInput, type ResponseVerifier, type ResumeDirective, type Rubric, RunStateMalformedError, RunStateVersionUnsupportedError, SUBAGENT_TOOL, type SerializeRunStateOptions, type SerializedPendingSubRun, type SerializedRunState, type SkillsRegistryLike, type SubAgentFoldTaint, SubAgentResumeTargetNotFoundError, type SubAgentToolRefs, ToolNotFoundError, type TrustClass, VERSION, type VerifierResult, addModelUsage, aggregateUsageFromByModel, bySensitivity, completedToolCallsFromState, compose, computeSourceTrust, createAgent, createInitialRunState, createProgressIO, createReplayProvider, custom, defaultHandoffFilter, deserializeRunState, evaluateMerge, evaluatorOptimizer, filters, foldChildRunUsage, full, getSubAgentToolRefs, guardOutboundContent, isAgentFallbackEligible, lastN, lastUser, pickTopTierAcrossTools, resolvePolicy, resolvePreferredModel, runFanOut, runStateFromJSON, runStateToJSON, serializeRunState, stripReasoning, stripSensitiveOutputs, stripToolCalls, summary };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA;;;;;;;;;;;cAAa,OAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA;;;;;;;;cAAa"}

package/dist/index.js

@@ -1,16 +1,18 @@
-import { AgentResolutionError, AgentRuntimeError, EvaluatorOptimizerConfigError, InvalidAgentConfigError, InvalidPreferredModelError, MergeBlockedError, MultipleHandoffsInStepError, ProgressWriteError, ProtocolInjectionRejectError, ProviderMiddlewareOrderError, RunStateMalformedError, RunStateVersionUnsupportedError, ToolNotFoundError } from "./errors/index.js";
+import { version } from "./package.js";
+import { AgentResolutionError, AgentRuntimeError, EvaluatorOptimizerConfigError, InvalidAgentConfigError, InvalidPreferredModelError, MergeBlockedError, MultipleHandoffsInStepError, ProgressWriteError, ProtocolInjectionRejectError, ProviderMiddlewareOrderError, RunStateMalformedError, RunStateVersionUnsupportedError, SubAgentResumeTargetNotFoundError, ToolNotFoundError } from "./errors/index.js";
 import { evaluatorOptimizer } from "./evaluator-optimizer/index.js";
-import { isAgentFallbackEligible } from "./fallback/index.js";
+import { CausalityMonitor, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH } from "./lateral-leak/causality-monitor.js";
+import { createProgressIO } from "./progress/index.js";
+import { RUN_STATE_SCHEMA_MAJOR_SUPPORTED, RUN_STATE_SCHEMA_VERSION, addModelUsage, aggregateUsageFromByModel, completedToolCallsFromState, createInitialRunState, deserializeRunState, runStateFromJSON, runStateToJSON, serializeRunState } from "./run-state/index.js";
 import { computeSourceTrust, evaluateMerge } from "./lateral-leak/merge-guard.js";
+import { foldChildRunUsage } from "./runtime/messages.js";
 import { runFanOut } from "./fanout/index.js";
+import { SUBAGENT_TOOL, getSubAgentToolRefs } from "./runtime/agent-to-tool.js";
 import { FILTER_KIND_CUSTOM, bySensitivity, compose, custom, defaultHandoffFilter, filters, full, lastN, lastUser, stripReasoning, stripSensitiveOutputs, stripToolCalls, summary } from "./filters/index.js";
-import { CausalityMonitor, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH } from "./lateral-leak/causality-monitor.js";
+import { isAgentFallbackEligible } from "./fallback/index.js";
 import { pickTopTierAcrossTools, resolvePreferredModel } from "./preferred-model/index.js";
-import { createProgressIO } from "./progress/index.js";
-import { RUN_STATE_SCHEMA_MAJOR_SUPPORTED, RUN_STATE_SCHEMA_VERSION, addModelUsage, aggregateUsageFromByModel, completedToolCallsFromState, createInitialRunState, deserializeRunState, runStateFromJSON, runStateToJSON, serializeRunState } from "./run-state/index.js";
 import { createAgent } from "./factory.js";
 import { guardOutboundContent, resolvePolicy } from "./lateral-leak/protocol-guard.js";
-import "./lateral-leak/index.js";
 import { createReplayProvider } from "./testing/replay-provider.js";
 
 //#region src/index.ts
@@ -42,9 +44,9 @@ import { createReplayProvider } from "./testing/replay-provider.js";
 *
 * @packageDocumentation
 */
-/** Canonical version constant. Mirrors the `package.json` version. */
-const VERSION = "0.6.0";
+/** Canonical version constant, derived from `package.json` at build time. */
+const VERSION = version;
 
 //#endregion
-export { AgentResolutionError, AgentRuntimeError, CausalityMonitor, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH, EvaluatorOptimizerConfigError, FILTER_KIND_CUSTOM, InvalidAgentConfigError, InvalidPreferredModelError, MergeBlockedError, MultipleHandoffsInStepError, ProgressWriteError, ProtocolInjectionRejectError, ProviderMiddlewareOrderError, RUN_STATE_SCHEMA_MAJOR_SUPPORTED, RUN_STATE_SCHEMA_VERSION, RunStateMalformedError, RunStateVersionUnsupportedError, ToolNotFoundError, VERSION, addModelUsage, aggregateUsageFromByModel, bySensitivity, completedToolCallsFromState, compose, computeSourceTrust, createAgent, createInitialRunState, createProgressIO, createReplayProvider, custom, defaultHandoffFilter, deserializeRunState, evaluateMerge, evaluatorOptimizer, filters, full, guardOutboundContent, isAgentFallbackEligible, lastN, lastUser, pickTopTierAcrossTools, resolvePolicy, resolvePreferredModel, runFanOut, runStateFromJSON, runStateToJSON, serializeRunState, stripReasoning, stripSensitiveOutputs, stripToolCalls, summary };
+export { AgentResolutionError, AgentRuntimeError, CausalityMonitor, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH, EvaluatorOptimizerConfigError, FILTER_KIND_CUSTOM, InvalidAgentConfigError, InvalidPreferredModelError, MergeBlockedError, MultipleHandoffsInStepError, ProgressWriteError, ProtocolInjectionRejectError, ProviderMiddlewareOrderError, RUN_STATE_SCHEMA_MAJOR_SUPPORTED, RUN_STATE_SCHEMA_VERSION, RunStateMalformedError, RunStateVersionUnsupportedError, SUBAGENT_TOOL, SubAgentResumeTargetNotFoundError, ToolNotFoundError, VERSION, addModelUsage, aggregateUsageFromByModel, bySensitivity, completedToolCallsFromState, compose, computeSourceTrust, createAgent, createInitialRunState, createProgressIO, createReplayProvider, custom, defaultHandoffFilter, deserializeRunState, evaluateMerge, evaluatorOptimizer, filters, foldChildRunUsage, full, getSubAgentToolRefs, guardOutboundContent, isAgentFallbackEligible, lastN, lastUser, pickTopTierAcrossTools, resolvePolicy, resolvePreferredModel, runFanOut, runStateFromJSON, runStateToJSON, serializeRunState, stripReasoning, stripSensitiveOutputs, stripToolCalls, summary };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@graphorin/agent` - agent runtime for the Graphorin framework.\n *\n * The package owns:\n *\n * - The `createAgent({...})` factory that wires the typed\n *   `model -> tool calls -> model` loop, the streaming event\n *   surface, the steering / followUp queues, durable HITL\n *   approvals, multi-agent handoffs (`Agent.toTool`, the filter\n *   library, secrets isolation), the agent-level model fallback\n *   chain, the per-step compaction lifecycle, the per-tool\n *   preferred-model resolution, the structured progress-artifact\n *   APIs, and the lateral-leak defense layer.\n * - `runStateToJSON / runStateFromJSON` helpers for caller-managed\n *   durable HITL.\n * - The handoff filter library.\n * - The agent-step-level fan-out helpers (`runFanOut`,\n *   `evaluatorOptimizer`, the progress IO surface).\n * - Pure decision functions consulted by the loop\n *   (`isAgentFallbackEligible`, `resolvePreferredModel`).\n * - Lateral-leak primitives (`CausalityMonitor`,\n *   `MergeAgentSidewaysInjectionGuard` decision helpers,\n *   protocol-injection guard).\n *\n * The full documentation lives in the package `README.md`.\n *\n * @packageDocumentation\n */\n\n/** Canonical version constant. Mirrors the `package.json` version. */\nexport const VERSION = '0.6.0';\n\n// AG-2 / SDF-4: the canonical guardrail contract lives in\n// `@graphorin/security`; re-exported here for config ergonomics.\nexport type {\n  GuardrailContext,\n  GuardrailDefinition,\n  GuardrailResult,\n  InputGuardrail,\n  OutputGuardrail,\n} from '@graphorin/security/guardrails';\nexport {\n  AgentResolutionError,\n  AgentRuntimeError,\n  type AgentRuntimeErrorCode,\n  EvaluatorOptimizerConfigError,\n  InvalidAgentConfigError,\n  InvalidPreferredModelError,\n  MergeBlockedError,\n  MultipleHandoffsInStepError,\n  ProgressWriteError,\n  ProtocolInjectionRejectError,\n  ProviderMiddlewareOrderError,\n  RunStateMalformedError,\n  RunStateVersionUnsupportedError,\n  ToolNotFoundError,\n} from './errors/index.js';\nexport {\n  type EvaluatorCallable,\n  type EvaluatorOptimizerOptions,\n  type EvaluatorOptimizerOutcome,\n  type EvaluatorOutcome,\n  evaluatorOptimizer,\n  type GeneratorCallable,\n  type Rubric,\n} from './evaluator-optimizer/index.js';\nexport { createAgent } from './factory.js';\nexport {\n  type AgentFallbackEligibility,\n  type AgentFallbackPolicy,\n  type AgentFallbackReason,\n  isAgentFallbackEligible,\n} from './fallback/index.js';\nexport {\n  type ChildResult,\n  type FanOutOptions,\n  type FanOutResult,\n  type MergeStrategy,\n  type PerChildBudget,\n  runFanOut,\n} from './fanout/index.js';\nexport {\n  bySensitivity,\n  compose,\n  custom,\n  type DescribedFilter,\n  defaultHandoffFilter,\n  FILTER_KIND_CUSTOM,\n  filters,\n  full,\n  lastN,\n  lastUser,\n  stripReasoning,\n  stripSensitiveOutputs,\n  stripToolCalls,\n  summary,\n} from './filters/index.js';\nexport {\n  CausalityMonitor,\n  type CausalityMonitorCheck,\n  type CausalityMonitorConfig,\n  type CausalityMonitorStrictness,\n  type ChildTrustInput,\n  type ContentOriginKind,\n  computeSourceTrust,\n  DEFAULT_DENIAL_PATTERNS,\n  DEFAULT_MAX_CHAIN_DEPTH,\n  evaluateMerge,\n  type GuardOutcome,\n  guardOutboundContent,\n  type MergeBiasDecision,\n  type MergeGuardConfig,\n  type ProtocolBoundary,\n  type ProtocolEscapePolicy,\n  type ProtocolGuardConfig,\n  resolvePolicy,\n  type TrustClass,\n} from './lateral-leak/index.js';\nexport {\n  type PreferredModelResolution,\n  pickTopTierAcrossTools,\n  type ResolvePreferredModelInput,\n  resolvePreferredModel,\n} from './preferred-model/index.js';\nexport {\n  createProgressIO,\n  type ProgressIO,\n  type ProgressIOConfig,\n  type ProgressReadOptions,\n  type ProgressWriteOptions,\n} from './progress/index.js';\nexport {\n  addModelUsage,\n  aggregateUsageFromByModel,\n  completedToolCallsFromState,\n  createInitialRunState,\n  deserializeRunState,\n  RUN_STATE_SCHEMA_MAJOR_SUPPORTED,\n  RUN_STATE_SCHEMA_VERSION,\n  runStateFromJSON,\n  runStateToJSON,\n  type SerializedRunState,\n  type SerializeRunStateOptions,\n  serializeRunState,\n} from './run-state/index.js';\nexport {\n  createReplayProvider,\n  type ReplayProviderOptions,\n} from './testing/replay-provider.js';\nexport type {\n  AbortOptions,\n  Agent,\n  AgentCallOptions,\n  AgentCapability,\n  AgentConfig,\n  AgentInput,\n  AgentToToolOptions,\n  CompactionApiResult,\n  CompactOptions,\n  OutputSpec,\n  PostCompactionHook,\n  PrepareStepHook,\n  PrepareStepOverrides,\n  ResponseVerifier,\n  ResumeDirective,\n  SkillsRegistryLike,\n  VerifierResult,\n} from './types.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,MAAa,UAAU"}
+{"version":3,"file":"index.js","names":["VERSION: string","pkg.version"],"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@graphorin/agent` - agent runtime for the Graphorin framework.\n *\n * The package owns:\n *\n * - The `createAgent({...})` factory that wires the typed\n *   `model -> tool calls -> model` loop, the streaming event\n *   surface, the steering / followUp queues, durable HITL\n *   approvals, multi-agent handoffs (`Agent.toTool`, the filter\n *   library, secrets isolation), the agent-level model fallback\n *   chain, the per-step compaction lifecycle, the per-tool\n *   preferred-model resolution, the structured progress-artifact\n *   APIs, and the lateral-leak defense layer.\n * - `runStateToJSON / runStateFromJSON` helpers for caller-managed\n *   durable HITL.\n * - The handoff filter library.\n * - The agent-step-level fan-out helpers (`runFanOut`,\n *   `evaluatorOptimizer`, the progress IO surface).\n * - Pure decision functions consulted by the loop\n *   (`isAgentFallbackEligible`, `resolvePreferredModel`).\n * - Lateral-leak primitives (`CausalityMonitor`,\n *   `MergeAgentSidewaysInjectionGuard` decision helpers,\n *   protocol-injection guard).\n *\n * The full documentation lives in the package `README.md`.\n *\n * @packageDocumentation\n */\n\n/** Canonical version constant, derived from `package.json` at build time. */\nimport pkg from '../package.json' with { type: 'json' };\n\nexport const VERSION: string = pkg.version;\n\n// AG-2 / SDF-4: the canonical guardrail contract lives in\n// `@graphorin/security`; re-exported here for config ergonomics.\nexport type {\n  GuardrailContext,\n  GuardrailDefinition,\n  GuardrailResult,\n  InputGuardrail,\n  OutputGuardrail,\n} from '@graphorin/security/guardrails';\nexport {\n  AgentResolutionError,\n  AgentRuntimeError,\n  type AgentRuntimeErrorCode,\n  EvaluatorOptimizerConfigError,\n  InvalidAgentConfigError,\n  InvalidPreferredModelError,\n  MergeBlockedError,\n  MultipleHandoffsInStepError,\n  ProgressWriteError,\n  ProtocolInjectionRejectError,\n  ProviderMiddlewareOrderError,\n  RunStateMalformedError,\n  RunStateVersionUnsupportedError,\n  SubAgentResumeTargetNotFoundError,\n  ToolNotFoundError,\n} from './errors/index.js';\nexport {\n  type EvaluatorCallable,\n  type EvaluatorOptimizerOptions,\n  type EvaluatorOptimizerOutcome,\n  type EvaluatorOutcome,\n  evaluatorOptimizer,\n  type GeneratorCallable,\n  type Rubric,\n} from './evaluator-optimizer/index.js';\nexport { createAgent } from './factory.js';\nexport {\n  type AgentFallbackEligibility,\n  type AgentFallbackPolicy,\n  type AgentFallbackReason,\n  isAgentFallbackEligible,\n} from './fallback/index.js';\nexport {\n  type ChildResult,\n  type FanOutOptions,\n  type FanOutResult,\n  type MergeStrategy,\n  type PerChildBudget,\n  runFanOut,\n} from './fanout/index.js';\nexport {\n  bySensitivity,\n  compose,\n  custom,\n  type DescribedFilter,\n  defaultHandoffFilter,\n  FILTER_KIND_CUSTOM,\n  filters,\n  full,\n  lastN,\n  lastUser,\n  stripReasoning,\n  stripSensitiveOutputs,\n  stripToolCalls,\n  summary,\n} from './filters/index.js';\nexport {\n  CausalityMonitor,\n  type CausalityMonitorCheck,\n  type CausalityMonitorConfig,\n  type CausalityMonitorStrictness,\n  type ChildTrustInput,\n  type ContentOriginKind,\n  computeSourceTrust,\n  DEFAULT_DENIAL_PATTERNS,\n  DEFAULT_MAX_CHAIN_DEPTH,\n  evaluateMerge,\n  type GuardOutcome,\n  guardOutboundContent,\n  type MergeBiasDecision,\n  type MergeGuardConfig,\n  type ProtocolBoundary,\n  type ProtocolEscapePolicy,\n  type ProtocolGuardConfig,\n  resolvePolicy,\n  type TrustClass,\n} from './lateral-leak/index.js';\nexport {\n  type PreferredModelResolution,\n  pickTopTierAcrossTools,\n  type ResolvePreferredModelInput,\n  resolvePreferredModel,\n} from './preferred-model/index.js';\nexport {\n  createProgressIO,\n  type ProgressIO,\n  type ProgressIOConfig,\n  type ProgressReadOptions,\n  type ProgressWriteOptions,\n} from './progress/index.js';\nexport {\n  addModelUsage,\n  aggregateUsageFromByModel,\n  completedToolCallsFromState,\n  createInitialRunState,\n  deserializeRunState,\n  RUN_STATE_SCHEMA_MAJOR_SUPPORTED,\n  RUN_STATE_SCHEMA_VERSION,\n  runStateFromJSON,\n  runStateToJSON,\n  type SerializedPendingSubRun,\n  type SerializedRunState,\n  type SerializeRunStateOptions,\n  serializeRunState,\n} from './run-state/index.js';\nexport {\n  getSubAgentToolRefs,\n  SUBAGENT_TOOL,\n  type SubAgentFoldTaint,\n  type SubAgentToolRefs,\n} from './runtime/agent-to-tool.js';\nexport { foldChildRunUsage } from './runtime/messages.js';\nexport {\n  createReplayProvider,\n  type ReplayProviderOptions,\n} from './testing/replay-provider.js';\nexport type {\n  AbortOptions,\n  Agent,\n  AgentCallOptions,\n  AgentCapability,\n  AgentConfig,\n  AgentInput,\n  AgentToToolOptions,\n  CompactionApiResult,\n  CompactOptions,\n  HandoffEntry,\n  OutputSpec,\n  PostCompactionHook,\n  PrepareStepHook,\n  PrepareStepOverrides,\n  ResponseVerifier,\n  ResumeDirective,\n  SkillsRegistryLike,\n  VerifierResult,\n} from './types.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,MAAaA,UAAkBC"}

package/dist/lateral-leak/index.js

@@ -1,5 +1,5 @@
-import { computeSourceTrust, evaluateMerge } from "./merge-guard.js";
 import { CausalityMonitor, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH } from "./causality-monitor.js";
+import { computeSourceTrust, evaluateMerge } from "./merge-guard.js";
 import { guardOutboundContent, resolvePolicy } from "./protocol-guard.js";
 
 export { CausalityMonitor, DEFAULT_DENIAL_PATTERNS, DEFAULT_MAX_CHAIN_DEPTH, computeSourceTrust, evaluateMerge, guardOutboundContent, resolvePolicy };

package/dist/package.js

@@ -0,0 +1,6 @@
+//#region package.json
+var version = "0.7.0";
+
+//#endregion
+export { version };
+//# sourceMappingURL=package.js.map

package/dist/package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.js","names":[],"sources":["../package.json"],"sourcesContent":["{\n  \"name\": \"@graphorin/agent\",\n  \"version\": \"0.7.0\",\n  \"description\": \"Agent runtime for the Graphorin framework: createAgent({...}) factory, the typed model -> tool calls -> model loop, the AgentEvent<TOutput> discriminated event stream, steering / followUp queues, durable HITL approvals via runStateToJSON / runStateFromJSON, multi-agent handoffs (Agent.toTool, filter library, secrets isolation), agent-level model fallback chain, intra-loop reasoning preservation, post-compaction hook lifecycle, agent-step-level fan-out (Agent.fanOut + evaluatorOptimizer + progress artifacts), per-tool model-tier hint resolution, lateral-leak defense layer (CausalityMonitor + MergeAgentSidewaysInjectionGuard + protocol-guard), inbound-content sanitization preamble injection, and AbortSignal-aware hard-kill / drain cancellation. Created and maintained by Oleksiy Stepurenko.\",\n  \"license\": \"MIT\",\n  \"author\": \"Oleksiy Stepurenko\",\n  \"homepage\": \"https://github.com/o-stepper/graphorin/tree/main/packages/agent\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/o-stepper/graphorin.git\",\n    \"directory\": \"packages/agent\"\n  },\n  \"bugs\": {\n    \"url\": \"https://github.com/o-stepper/graphorin/issues\"\n  },\n  \"keywords\": [\n    \"graphorin\",\n    \"ai\",\n    \"agents\",\n    \"framework\",\n    \"agent-runtime\",\n    \"agent-loop\",\n    \"streaming\",\n    \"multi-agent\",\n    \"handoff\",\n    \"hitl\",\n    \"approval\",\n    \"fanout\",\n    \"evaluator-optimizer\",\n    \"fallback-chain\",\n    \"context-compaction\",\n    \"lateral-leak\",\n    \"causality-monitor\"\n  ],\n  \"type\": \"module\",\n  \"sideEffects\": false,\n  \"engines\": {\n    \"node\": \">=22.12.0\"\n  },\n  \"main\": \"./dist/index.js\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"default\": \"./dist/index.js\"\n    },\n    \"./factory\": {\n      \"types\": \"./dist/factory.d.ts\",\n      \"default\": \"./dist/factory.js\"\n    },\n    \"./run-state\": {\n      \"types\": \"./dist/run-state/index.d.ts\",\n      \"default\": \"./dist/run-state/index.js\"\n    },\n    \"./filters\": {\n      \"types\": \"./dist/filters/index.d.ts\",\n      \"default\": \"./dist/filters/index.js\"\n    },\n    \"./fallback\": {\n      \"types\": \"./dist/fallback/index.d.ts\",\n      \"default\": \"./dist/fallback/index.js\"\n    },\n    \"./preferred-model\": {\n      \"types\": \"./dist/preferred-model/index.d.ts\",\n      \"default\": \"./dist/preferred-model/index.js\"\n    },\n    \"./fanout\": {\n      \"types\": \"./dist/fanout/index.d.ts\",\n      \"default\": \"./dist/fanout/index.js\"\n    },\n    \"./evaluator-optimizer\": {\n      \"types\": \"./dist/evaluator-optimizer/index.d.ts\",\n      \"default\": \"./dist/evaluator-optimizer/index.js\"\n    },\n    \"./progress\": {\n      \"types\": \"./dist/progress/index.d.ts\",\n      \"default\": \"./dist/progress/index.js\"\n    },\n    \"./lateral-leak\": {\n      \"types\": \"./dist/lateral-leak/index.d.ts\",\n      \"default\": \"./dist/lateral-leak/index.js\"\n    },\n    \"./errors\": {\n      \"types\": \"./dist/errors/index.d.ts\",\n      \"default\": \"./dist/errors/index.js\"\n    },\n    \"./package.json\": \"./package.json\"\n  },\n  \"files\": [\n    \"dist\",\n    \"src\",\n    \"README.md\",\n    \"CHANGELOG.md\",\n    \"LICENSE\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsdown\",\n    \"typecheck\": \"tsc --noEmit && tsc -p tsconfig.tests.json\",\n    \"test\": \"vitest run\",\n    \"lint\": \"biome check .\",\n    \"clean\": \"rimraf dist .turbo *.tsbuildinfo\"\n  },\n  \"dependencies\": {\n    \"@graphorin/core\": \"workspace:*\",\n    \"@graphorin/memory\": \"workspace:*\",\n    \"@graphorin/security\": \"workspace:*\",\n    \"@graphorin/skills\": \"workspace:*\",\n    \"@graphorin/tools\": \"workspace:*\"\n  },\n  \"publishConfig\": {\n    \"access\": \"public\",\n    \"provenance\": true\n  },\n  \"devDependencies\": {\n    \"zod\": \"^3.25.0\"\n  }\n}\n"],"mappings":";cAEa"}

package/dist/run-state/index.d.ts

@@ -1,13 +1,19 @@
-import { CompletedToolCall, HandoffRecord, Message, RunState, RunStateUsageByModel, RunStatus, RunStep, RunTaintSummary, TodoItem, ToolApproval, Usage } from "@graphorin/core";
+import { CompletedToolCall, HandoffRecord, RunState, RunStateUsageByModel, RunStatus, RunTaintSummary, TodoItem, ToolApproval, Usage, WireMessage, WireRunStep } from "@graphorin/core";
 
 //#region src/run-state/index.d.ts
 
 /**
  * Canonical schema id for serialized {@link RunState} payloads.
  *
+ * 1.2 encodes binary message/tool-outcome payloads (`Uint8Array | URL`)
+ * through the core `WireRunState` projection (base64 / href envelopes)
+ * instead of letting `JSON.stringify` corrupt them. 1.0/1.1 payloads
+ * remain readable; their corrupted numeric-key byte objects are
+ * repaired best-effort on rehydration.
+ *
  * @stable
  */
-declare const RUN_STATE_SCHEMA_VERSION: "graphorin-run-state/1.1";
+declare const RUN_STATE_SCHEMA_VERSION: "graphorin-run-state/1.2";
 /**
  * Reader-supported schema id range. Major version 1 only for v0.1.
  *
@@ -16,7 +22,9 @@ declare const RUN_STATE_SCHEMA_VERSION: "graphorin-run-state/1.1";
 declare const RUN_STATE_SCHEMA_MAJOR_SUPPORTED = 1;
 /**
  * On-disk payload returned by {@link serializeRunState} and accepted
- * by {@link deserializeRunState}. The shape is JSON-stable.
+ * by {@link deserializeRunState}. The shape is JSON-stable: binary
+ * message/tool-outcome payloads appear in their `WireMessage` /
+ * `WireRunStep` (base64 / href envelope) form.
  *
  * @stable
  */
@@ -28,8 +36,8 @@ interface SerializedRunState {
   readonly sessionId: string;
   readonly userId?: string;
   readonly status: RunStatus;
-  readonly steps: ReadonlyArray<RunStep>;
-  readonly messages: ReadonlyArray<Message>;
+  readonly steps: ReadonlyArray<WireRunStep>;
+  readonly messages: ReadonlyArray<WireMessage>;
   readonly pendingApprovals: ReadonlyArray<ToolApproval>;
   readonly handoffs: ReadonlyArray<HandoffRecord>;
   readonly usage: Usage;
@@ -40,6 +48,12 @@ interface SerializedRunState {
   readonly promotedTools?: ReadonlyArray<string>;
   /** D6: journaled structured plan/todo list. */
   readonly todos?: ReadonlyArray<TodoItem>;
+  /**
+   * W-001: parked sub-agent runs. Each child snapshot is itself a full
+   * `SerializedRunState` - version-stamped and secret-redacted
+   * recursively, to any nesting depth.
+   */
+  readonly pendingSubRuns?: ReadonlyArray<SerializedPendingSubRun>;
   readonly startedAt: string;
   readonly finishedAt?: string;
   readonly error?: {
@@ -48,6 +62,18 @@ interface SerializedRunState {
     readonly details?: unknown;
   };
 }
+/**
+ * Serialized twin of core's `PendingSubRun` (W-001): the parked child
+ * state travels as its own versioned {@link SerializedRunState}.
+ *
+ * @stable
+ */
+interface SerializedPendingSubRun {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly targetAgentName: string;
+  readonly state: SerializedRunState;
+}
 /**
  * Options accepted by {@link serializeRunState}.
  *
@@ -150,5 +176,5 @@ declare function aggregateUsageFromByModel(byModel: RunStateUsageByModel | undef
  */
 declare function completedToolCallsFromState(state: RunState): ReadonlyArray<CompletedToolCall>;
 //#endregion
-export { RUN_STATE_SCHEMA_MAJOR_SUPPORTED, RUN_STATE_SCHEMA_VERSION, SerializeRunStateOptions, SerializedRunState, addModelUsage, aggregateUsageFromByModel, completedToolCallsFromState, createInitialRunState, deserializeRunState, runStateFromJSON, runStateToJSON, serializeRunState };
+export { RUN_STATE_SCHEMA_MAJOR_SUPPORTED, RUN_STATE_SCHEMA_VERSION, SerializeRunStateOptions, SerializedPendingSubRun, SerializedRunState, addModelUsage, aggregateUsageFromByModel, completedToolCallsFromState, createInitialRunState, deserializeRunState, runStateFromJSON, runStateToJSON, serializeRunState };
 //# sourceMappingURL=index.d.ts.map

package/dist/run-state/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/run-state/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AA6D0B,cA5Bb,wBA4Ba,EAAA,yBAAA;;;;;;AAiBT,cAtCJ,gCAAA,GAsC4B,CAAA;AAoBzC;;;;;AAqFA;AAIU,UA3IO,kBAAA,CA2IW;EA+BZ,SAAA,OAAA,EAAA,OAzKW,wBAyKoC;EAgL/C,SAAA,EAAA,EAAA,MAAgB;EAkBhB,SAAA,OAAA,EAAA,MAAqB;EA+BrB,SAAA,cAAa,EAAA,MAAQ;EAwCrB,SAAA,SAAA,EAAA,MAAA;EA6CA,SAAA,MAAA,CAAA,EAAA,MAAA;EAAmC,SAAA,MAAA,EAzdhC,SAydgC;EAAyB,SAAA,KAAA,EAxd1D,aAwd0D,CAxd5C,OAwd4C,CAAA;EAAd,SAAA,QAAA,EAvdzC,aAudyC,CAvd3B,OAud2B,CAAA;EAAa,SAAA,gBAAA,EAtd9C,aAsd8C,CAtdhC,YAsdgC,CAAA;qBArdtD,cAAc;kBACjB;0BACQ;;0BAEA;;2BAEC;;mBAER,cAAc;;;;;;;;;;;;;;UAWhB,wBAAA;;;;;;;;;;;;;;;;;;;iBAoBD,iBAAA,QACP,oBACE,2BACR;;;;;;;;iBAkFa,cAAA,QAAsB,oBAAoB;UAIhD,kBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+BM,mBAAA,6BAA+C,qBAA0B;;iBAgLzE,gBAAA,+BAA+C,qBAAqB;;;;;;;;iBAkBpE,qBAAA;;;;;;IAMZ;;;;;;;;;iBAyBY,aAAA,QAAqB,kCAAkC;;;;;;;;iBAwCvD,yBAAA,UAAmC,mCAAmC;;;;;;;;iBA6CtE,2BAAA,QAAmC,WAAW,cAAc"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/run-state/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;AAkF4B,cA1Cf,wBA0Ce,EAAA,yBAAA;;AAY5B;AAYA;AAoBA;;AAEW,cAjFE,gCAAA,GAiFF,CAAA;;;AAwGX;AAEC;AAiCD;AAuMA;AAkBA;AA+BA;AAwCgB,UAlfC,kBAAA,CAkfwB;EA6CzB,SAAA,OAAA,EAAA,OA9hBW,wBA8hBgB;EAAQ,SAAA,EAAA,EAAA,MAAA;EAAyB,SAAA,OAAA,EAAA,MAAA;EAAd,SAAA,cAAA,EAAA,MAAA;EAAa,SAAA,SAAA,EAAA,MAAA;;mBAxhBxD;kBACD,cAAc;qBACX,cAAc;6BACN,cAAc;qBACtB,cAAc;kBACjB;0BACQ;;0BAEA;;2BAEC;;mBAER,cAAc;;;;;;4BAML,cAAc;;;;;;;;;;;;;;;UAYzB,uBAAA;;;;kBAIC;;;;;;;UAQD,wBAAA;;;;;;;;;;;;;;;;;;;iBAoBD,iBAAA,QACP,oBACE,2BACR;;;;;;;;iBAuGa,cAAA,QAAsB,oBAAoB;UAIhD,kBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+BM,mBAAA,6BAA+C,qBAA0B;;iBAuMzE,gBAAA,+BAA+C,qBAAqB;;;;;;;;iBAkBpE,qBAAA;;;;;;IAMZ;;;;;;;;;iBAyBY,aAAA,QAAqB,kCAAkC;;;;;;;;iBAwCvD,yBAAA,UAAmC,mCAAmC;;;;;;;;iBA6CtE,2BAAA,QAAmC,WAAW,cAAc"}

package/dist/run-state/index.js

@@ -1,13 +1,19 @@
 import { RunStateMalformedError, RunStateVersionUnsupportedError } from "../errors/index.js";
-import { zeroUsage } from "@graphorin/core";
+import { fromJsonSafeRunState, toJsonSafeRunState, zeroUsage } from "@graphorin/core";
 
 //#region src/run-state/index.ts
 /**
 * Canonical schema id for serialized {@link RunState} payloads.
 *
+* 1.2 encodes binary message/tool-outcome payloads (`Uint8Array | URL`)
+* through the core `WireRunState` projection (base64 / href envelopes)
+* instead of letting `JSON.stringify` corrupt them. 1.0/1.1 payloads
+* remain readable; their corrupted numeric-key byte objects are
+* repaired best-effort on rehydration.
+*
 * @stable
 */
-const RUN_STATE_SCHEMA_VERSION = "graphorin-run-state/1.1";
+const RUN_STATE_SCHEMA_VERSION = "graphorin-run-state/1.2";
 /**
 * Reader-supported schema id range. Major version 1 only for v0.1.
 *
@@ -21,26 +27,34 @@ const RUN_STATE_SCHEMA_MAJOR_SUPPORTED = 1;
 * @stable
 */
 function serializeRunState(state, options = {}) {
+	const wire = toJsonSafeRunState(state);
+	const pendingSubRuns = state.pendingSubRuns !== void 0 && state.pendingSubRuns.length > 0 ? state.pendingSubRuns.map((sub) => ({
+		toolCallId: sub.toolCallId,
+		toolName: sub.toolName,
+		targetAgentName: sub.targetAgentName,
+		state: serializeRunState(sub.state, options)
+	})) : void 0;
 	const out = {
 		version: RUN_STATE_SCHEMA_VERSION,
-		id: state.id,
-		agentId: state.agentId,
-		currentAgentId: state.currentAgentId,
-		sessionId: state.sessionId,
-		...state.userId !== void 0 ? { userId: state.userId } : {},
-		status: state.status,
-		steps: state.steps,
-		messages: state.messages,
-		pendingApprovals: state.pendingApprovals,
-		handoffs: state.handoffs,
-		usage: state.usage,
-		...state.usageByModel !== void 0 ? { usageByModel: state.usageByModel } : {},
-		...state.taintSummary !== void 0 ? { taintSummary: state.taintSummary } : {},
-		...state.promotedTools !== void 0 ? { promotedTools: state.promotedTools } : {},
-		...state.todos !== void 0 ? { todos: state.todos } : {},
-		startedAt: state.startedAt,
-		...state.finishedAt !== void 0 ? { finishedAt: state.finishedAt } : {},
-		...state.error !== void 0 ? { error: state.error } : {}
+		id: wire.id,
+		agentId: wire.agentId,
+		currentAgentId: wire.currentAgentId,
+		sessionId: wire.sessionId,
+		...wire.userId !== void 0 ? { userId: wire.userId } : {},
+		status: wire.status,
+		steps: wire.steps,
+		messages: wire.messages,
+		pendingApprovals: wire.pendingApprovals,
+		handoffs: wire.handoffs,
+		usage: wire.usage,
+		...wire.usageByModel !== void 0 ? { usageByModel: wire.usageByModel } : {},
+		...wire.taintSummary !== void 0 ? { taintSummary: wire.taintSummary } : {},
+		...wire.promotedTools !== void 0 ? { promotedTools: wire.promotedTools } : {},
+		...wire.todos !== void 0 ? { todos: wire.todos } : {},
+		...pendingSubRuns !== void 0 ? { pendingSubRuns } : {},
+		startedAt: wire.startedAt,
+		...wire.finishedAt !== void 0 ? { finishedAt: wire.finishedAt } : {},
+		...wire.error !== void 0 ? { error: wire.error } : {}
 	};
 	const detached = JSON.parse(JSON.stringify(out));
 	if (options.stripTracingApiKey === true) redactSecretKeysInPlace(detached);
@@ -198,7 +212,7 @@ function deserializeRunState(payload, options = {}) {
 		content: t.content,
 		status: t.status
 	})) : void 0;
-	return {
+	const rehydrated = fromJsonSafeRunState({
 		id,
 		agentId,
 		currentAgentId,
@@ -217,7 +231,17 @@ function deserializeRunState(payload, options = {}) {
 		startedAt,
 		...typeof finishedAtRaw === "string" ? { finishedAt: finishedAtRaw } : {},
 		...error !== void 0 ? { error } : {}
-	};
+	});
+	if (Array.isArray(payload.pendingSubRuns) && payload.pendingSubRuns.length > 0) {
+		const subs = payload.pendingSubRuns.filter(isRecord).filter((s) => typeof s.toolCallId === "string" && typeof s.toolName === "string").map((s) => ({
+			toolCallId: s.toolCallId,
+			toolName: s.toolName,
+			targetAgentName: typeof s.targetAgentName === "string" ? s.targetAgentName : s.toolName,
+			state: deserializeRunState(s.state, options)
+		}));
+		if (subs.length > 0) rehydrated.pendingSubRuns = subs;
+	}
+	return rehydrated;
 }
 /** Convenience JSON-string parser pairing with {@link runStateToJSON}. */
 function runStateFromJSON(serialized, options) {