@tangle-network/agent-runtime 6.0.8 → 8.0.0

package/dist/{settle-record-U7fkQEZa.js → settle-record-WWQasnDq.js}

@@ -1,3 +1,4 @@
+import { W as FileSpawnJournal, n as terminalAccounting } from "./supervisor-accounting-Bw4MJk-b.js";
 import { t as isNoEntError } from "./jsonl-file-DsxVI0E_.js";
 import { a as writeAtomicDurableFile, r as publishExclusiveDurableFile } from "./durable-file-DstVeHcj.js";
 import { canonicalCandidateDigest, canonicalCandidateJson } from "@tangle-network/agent-interface";
@@ -88,10 +89,17 @@ async function writeFailureRecord(runDir, record) {
 }
 /**
 * Read the settle record a run directory holds, or `undefined` when it holds none. A file that
-* is present but is not a settle record is corruption and fails loud.
+* is present but is not a settle record is corruption and fails loud. `usage` annotates legacy
+* results by replay without changing their sealed fields; recorded usage always wins.
 */
-async function readSettleRecord(runDir) {
-	return readTerminalFile(runDir, SETTLE_RECORD_FILE, parseSettleRecord);
+async function readSettleRecord(runDir, options = {}) {
+	const recorded = await readTerminalFile(runDir, SETTLE_RECORD_FILE, parseSettleRecord);
+	if (!recorded || !options.usage || recorded.usage) return recorded;
+	const { usage } = await terminalAccounting(new FileSpawnJournal(resolve(runDir, "spawn-journal.jsonl")), recorded.tree.root, recorded.spentTotal.ms, options.requestedProfile);
+	return {
+		...recorded,
+		usage
+	};
 }
 async function readTerminalFile(runDir, file, parse) {
 	const path = resolve(runDir, file);
@@ -127,4 +135,4 @@ async function readFailureRecord(runDir) {
 }
 export { readFailureRecord as a, writeFailureRecord as c, parseSettleRecord as i, writeSettleRecord as l, SETTLE_RECORD_FILE as n, readSettleRecord as o, SettledRunDirectoryError as r, settleRecordDigest as s, FAILURE_RECORD_FILE as t };
 
-//# sourceMappingURL=settle-record-U7fkQEZa.js.map
+//# sourceMappingURL=settle-record-WWQasnDq.js.map

package/dist/settle-record-WWQasnDq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settle-record-WWQasnDq.js","names":[],"sources":["../src/durable/settle-record.ts"],"sourcesContent":["import { readFile } from 'node:fs/promises'\nimport { resolve } from 'node:path'\nimport {\n  type AgentProfile,\n  canonicalCandidateDigest,\n  canonicalCandidateJson,\n} from '@tangle-network/agent-interface'\nimport {\n  publishExclusiveDurableFile,\n  writeAtomicDurableFile,\n} from '../runtime/supervise/durable-file'\nimport { terminalAccounting } from '../runtime/supervise/supervisor-accounting'\nimport type { RootStreamReceipt, SupervisedResult } from '../runtime/supervise/types'\nimport { isNoEntError } from './jsonl-file'\nimport { FileSpawnJournal } from './spawn-journal/journal-store'\n\n/** Terminal evidence has one result per segment. Reopen archives that result byte for byte;\n * a failed attempt may resume because failure.json records only the latest throw.\n * Serialization, exclusive publication and validation stay with the record operations below.\n */\n\n/** The settle record: the returned `SupervisedResult` as canonical JSON, written once. */\nexport const SETTLE_RECORD_FILE = 'result.json'\n/** The failure record: the most recent throw, replaced by a later throw. */\nexport const FAILURE_RECORD_FILE = 'failure.json'\n\n/** What `failure.json` records about the most recent throw. */\nexport interface DurableFailureRecord {\n  readonly runId: string\n  readonly pursuitId: string\n  /** ISO instant the throw was recorded. */\n  readonly at: string\n  readonly error: { readonly name: string; readonly message: string }\n  /** The root's retained provider stream at the time of the throw, when the directory holds one:\n   *  a root that died mid-turn keeps what it had streamed, and this names it. */\n  readonly rootStream?: RootStreamReceipt\n}\n\n/** The directory already holds a settle record, so the run it records must not be re-entered. */\nexport class SettledRunDirectoryError extends Error {\n  readonly path: string\n  /** The root of the recorded run, which is its `runId`. */\n  readonly recordedRunId: string\n\n  constructor(path: string, recordedRunId: string, requestedRunId: string) {\n    super(\n      recordedRunId === requestedRunId\n        ? `supervisePursuit: ${path} records that run '${recordedRunId}' already settled; a settled run is not re-entered unless the call passes reopen: { operator, reason, operationId }`\n        : `supervisePursuit: ${path} records that run '${recordedRunId}' already settled in this directory; a directory holds one settle record, so run '${requestedRunId}' needs its own runDir`,\n    )\n    this.name = 'SettledRunDirectoryError'\n    this.path = path\n    this.recordedRunId = recordedRunId\n  }\n}\n\n/** A result member whose JSON form would misstate it. */\nclass UnrecordableSettleValueError extends TypeError {\n  readonly path: string\n\n  constructor(path: string, kind: string) {\n    super(\n      `supervisePursuit: result${path} is a ${kind}, which JSON cannot record faithfully; a settle record holds plain data only`,\n    )\n    this.name = 'UnrecordableSettleValueError'\n    this.path = path\n  }\n}\n\nconst PLAIN_PROTOTYPES = new Set<unknown>([Object.prototype, Array.prototype, null])\n\n/**\n * The JSON value of a result, or a throw naming the first member JSON would misstate. An\n * `undefined` member and a function are dropped, exactly as any JSON consumer drops them; a Map,\n * a Set, a Date, a typed array, or a class instance would be rewritten to `{}` or a string and\n * so is refused.\n */\nfunction jsonValue(result: unknown): unknown {\n  const seen: unknown[] = []\n  const visit = (value: unknown, path: string): void => {\n    if (value === null || typeof value !== 'object') return\n    if (value instanceof Map) throw new UnrecordableSettleValueError(path, 'Map')\n    if (value instanceof Set) throw new UnrecordableSettleValueError(path, 'Set')\n    if (value instanceof Date) throw new UnrecordableSettleValueError(path, 'Date')\n    if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {\n      throw new UnrecordableSettleValueError(path, 'binary buffer')\n    }\n    if (!PLAIN_PROTOTYPES.has(Object.getPrototypeOf(value))) {\n      throw new UnrecordableSettleValueError(path, 'class instance')\n    }\n    if (seen.includes(value)) throw new UnrecordableSettleValueError(path, 'cycle')\n    seen.push(value)\n    if (Array.isArray(value)) {\n      for (const [index, item] of value.entries()) visit(item, `${path}[${index}]`)\n    } else {\n      for (const [key, item] of Object.entries(value)) visit(item, `${path}.${key}`)\n    }\n    seen.pop()\n  }\n  visit(result, '')\n  return JSON.parse(JSON.stringify(result))\n}\n\n/**\n * The exact bytes `result.json` holds for a result: its JSON value serialized as RFC 8785\n * canonical JSON. Throws `UnrecordableSettleValueError` before any byte is written when the\n * result carries a value JSON would misstate.\n */\nexport function settleRecordJson(result: unknown): string {\n  return canonicalCandidateJson(jsonValue(result))\n}\n\n/** The digest the settle record's bytes hash to: the candidate digest of the result's JSON value. */\nexport function settleRecordDigest(result: unknown): string {\n  return canonicalCandidateDigest(jsonValue(result))\n}\n\n/** Publish `result.json` in the run directory once. Throws when a record is already there. */\nexport async function writeSettleRecord(runDir: string, result: unknown): Promise<string> {\n  const path = resolve(runDir, SETTLE_RECORD_FILE)\n  if (!publishExclusiveDurableFile(path, settleRecordJson(result))) {\n    throw new Error(`supervisePursuit: ${path} already exists; a settle record is written once`)\n  }\n  return path\n}\n\n/** Replace `failure.json` in the run directory with the most recent throw. */\nexport async function writeFailureRecord(\n  runDir: string,\n  record: DurableFailureRecord,\n): Promise<string> {\n  const path = resolve(runDir, FAILURE_RECORD_FILE)\n  writeAtomicDurableFile(path, `${JSON.stringify(record, null, 2)}\\n`)\n  return path\n}\n\n/**\n * Read the settle record a run directory holds, or `undefined` when it holds none. A file that\n * is present but is not a settle record is corruption and fails loud. `usage` annotates legacy\n * results by replay without changing their sealed fields; recorded usage always wins.\n */\nexport async function readSettleRecord(\n  runDir: string,\n  options: { readonly usage?: boolean; readonly requestedProfile?: AgentProfile } = {},\n): Promise<SupervisedResult<unknown> | undefined> {\n  const recorded = await readTerminalFile(runDir, SETTLE_RECORD_FILE, parseSettleRecord)\n  if (!recorded || !options.usage || recorded.usage) return recorded\n  const { usage } = await terminalAccounting(\n    new FileSpawnJournal(resolve(runDir, 'spawn-journal.jsonl')),\n    recorded.tree.root,\n    recorded.spentTotal.ms,\n    options.requestedProfile,\n  )\n  return { ...recorded, usage }\n}\n\nasync function readTerminalFile<T>(\n  runDir: string,\n  file: string,\n  parse: (text: string, path: string) => T,\n): Promise<T | undefined> {\n  const path = resolve(runDir, file)\n  try {\n    return parse(await readFile(path, 'utf8'), path)\n  } catch (error) {\n    if (isNoEntError(error)) return undefined\n    throw error\n  }\n}\n\nfunction parseTerminalJson(text: string, path: string): unknown {\n  try {\n    return JSON.parse(text)\n  } catch (cause) {\n    throw new Error(`supervisePursuit: ${path} is not valid JSON`, { cause })\n  }\n}\n\n/** Parse settle-record bytes already read, so a caller hashes and parses the same bytes. */\nexport function parseSettleRecord(text: string, path: string): SupervisedResult<unknown> {\n  const parsed = parseTerminalJson(text, path)\n  const record = parsed as { kind?: unknown; tree?: { root?: unknown } }\n  if (\n    typeof record !== 'object' ||\n    record === null ||\n    typeof record.kind !== 'string' ||\n    typeof record.tree !== 'object' ||\n    record.tree === null ||\n    typeof record.tree.root !== 'string'\n  ) {\n    throw new Error(`supervisePursuit: ${path} is not a settle record (no kind or tree.root)`)\n  }\n  return parsed as SupervisedResult<unknown>\n}\n\n/** Read the most recent failure record, or `undefined` when the directory holds none. */\nexport async function readFailureRecord(runDir: string): Promise<DurableFailureRecord | undefined> {\n  return readTerminalFile(runDir, FAILURE_RECORD_FILE, (text, path) => {\n    const parsed = parseTerminalJson(text, path)\n    const record = parsed as Partial<DurableFailureRecord>\n    if (\n      typeof record !== 'object' ||\n      record === null ||\n      typeof record.runId !== 'string' ||\n      typeof record.pursuitId !== 'string' ||\n      typeof record.at !== 'string' ||\n      typeof record.error?.name !== 'string' ||\n      typeof record.error.message !== 'string' ||\n      (record.rootStream !== undefined &&\n        (typeof record.rootStream.ref !== 'string' || typeof record.rootStream.events !== 'number'))\n    ) {\n      throw new Error(`supervisePursuit: ${path} is not a failure record`)\n    }\n    return parsed as DurableFailureRecord\n  })\n}\n"],"mappings":"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"}

package/dist/{snapshot-Cgj2Wzi6.js → snapshot-BKI_w3JD.js}

@@ -1,4 +1,4 @@
-import { m as ValidationError } from "./errors-AzSuGI23.js";
+import { m as ValidationError } from "./errors-DG8yufqX.js";
 import { REDACTION_VERSION, redact } from "@tangle-network/agent-eval/traces";
 // src/redact.ts
 /**
@@ -45,7 +45,8 @@ function resolveRedactor(redact) {
 const maxCauseDepth = 4;
 const maxMessageLength = 32768;
 const maxPartLength = 2048;
-/** A persisted failure must explain its wrappers without exporting credentials or unbounded data. */
+/** A persisted failure must explain its wrappers without exporting credentials or unbounded data.
+*  Redaction runs per line so one credential cannot erase the lines around it. */
 function errorText(value) {
 	let text;
 	try {
@@ -53,7 +54,7 @@ function errorText(value) {
 	} catch {
 		text = "[unprintable rejection]";
 	}
-	return String(defaultRedactor(text)).slice(0, maxMessageLength);
+	return text.split("\n").map((line) => String(defaultRedactor(line))).join("\n").slice(0, maxMessageLength);
 }
 function errorProperty(error, field) {
 	try {
@@ -120,6 +121,19 @@ function causeChain(error) {
 	}
 	return chain;
 }
+const maxStackFrames = 40;
+/** The deepest cause's stack that has one, redacted and bounded to {@link maxStackFrames} frames,
+*  so a failure the messages alone cannot place still names its throw site (#2347). Outer
+*  wrappers' stacks are skipped: they restate the wrap site the record's own fields name. */
+function errorStack(error) {
+	let found;
+	for (const value of causeChain(error)) {
+		if (!(value instanceof Error)) continue;
+		const stack = errorProperty(value, "stack");
+		if (stack !== void 0 && stack !== "[unreadable error stack]") found = stack;
+	}
+	return found === void 0 ? void 0 : found.split("\n").slice(0, maxStackFrames).join("\n");
+}
 // src/runtime/supervise/snapshot.ts
 /** Deeply detach and freeze untrusted data at a runtime decision boundary. The clone prevents the
 * caller from mutating it later; the freeze prevents downstream code from mutating the snapshot.
@@ -205,6 +219,6 @@ function deepFreeze(value, seen = /* @__PURE__ */ new Set()) {
 	for (const child of Object.values(value)) deepFreeze(child, seen);
 	return Object.freeze(value);
 }
-export { errMessage as a, errorText as c, resolveRedactor as d, causeChain as i, defaultRedactor as l, detachedSnapshot as n, errorHttpStatus as o, shareParsedStrings as r, errorProperty as s, detachedFrozen as t, defaultRedactorIdentityMaterial as u };
+export { errMessage as a, errorStack as c, defaultRedactorIdentityMaterial as d, resolveRedactor as f, causeChain as i, errorText as l, detachedSnapshot as n, errorHttpStatus as o, shareParsedStrings as r, errorProperty as s, detachedFrozen as t, defaultRedactor as u };
 
-//# sourceMappingURL=snapshot-Cgj2Wzi6.js.map
+//# sourceMappingURL=snapshot-BKI_w3JD.js.map

package/dist/snapshot-BKI_w3JD.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-BKI_w3JD.js","names":[],"sources":["../src/redact.ts","../src/runtime/supervise/error-message.ts","../src/runtime/supervise/snapshot.ts"],"sourcesContent":["/**\n * Redaction for values that may leave the Runtime process. The built-in\n * redactor is agent-eval's redaction core (`@tangle-network/agent-eval/traces`,\n * default profile): credentials found by field name or value shape are\n * replaced whole, email, card, SSN and phone values in place, and token counts\n * such as `inputTokens` or `max_tokens` are kept. A customer with\n * domain-specific PII supplies their own `redact` hook.\n *\n * This is narrower than `src/sanitize.ts`, which drops fields of the runtime's\n * *event envelope* unless the caller opts in: here the value is opaque customer\n * payload, so the scrub is value-shaped, not schema-shaped.\n *\n * @experimental\n */\n\nimport { REDACTION_VERSION, redact } from '@tangle-network/agent-eval/traces'\n\n/** A redactor maps an arbitrary trace value to a safe-to-export value. Pure;\n *  must not throw on cyclic input (the default tolerates cycles). */\nexport type Redactor = (value: unknown) => unknown\n\n/**\n * The built-in redactor. Cycle-safe, depth-bounded and total: it never throws\n * on customer input and never mutates it.\n */\nexport function defaultRedactor(value: unknown): unknown {\n  return redact(value).value\n}\n\n/** Stable identity input for saved work that depends on built-in redaction behavior. */\nexport function defaultRedactorIdentityMaterial(): unknown {\n  return {\n    core: '@tangle-network/agent-eval/traces redact',\n    profile: 'default',\n    version: REDACTION_VERSION,\n  }\n}\n\n/**\n * Resolve the redactor a client uses. A caller-supplied hook handles\n * domain-specific values first, then the built-in scrubber still removes\n * credentials and personal data. Returning `false` is the explicit opt-out for\n * already-reviewed public values.\n */\nexport function resolveRedactor(redact: Redactor | false | undefined): Redactor {\n  if (redact === false) return (value) => value\n  if (!redact) return defaultRedactor\n  return (value) => defaultRedactor(redact(value))\n}\n","import { defaultRedactor } from '../../redact'\n\nconst maxCauseDepth = 4\nconst maxMessageLength = 32_768\nconst maxPartLength = 2_048\n\n/** A persisted failure must explain its wrappers without exporting credentials or unbounded data.\n *  Redaction runs per line so one credential cannot erase the lines around it. */\nexport function errorText(value: unknown): string {\n  let text: string\n  try {\n    text = typeof value === 'string' ? value : (JSON.stringify(value) ?? String(value))\n  } catch {\n    text = '[unprintable rejection]'\n  }\n  const lines = text.split('\\n').map((line) => String(defaultRedactor(line)))\n  return lines.join('\\n').slice(0, maxMessageLength)\n}\n\nexport function errorProperty(\n  error: Error,\n  field: 'name' | 'message' | 'stack',\n): string | undefined {\n  try {\n    const value = error[field]\n    return value === undefined\n      ? undefined\n      : errorText(value).slice(0, field === 'name' ? 256 : maxMessageLength)\n  } catch {\n    return `[unreadable error ${field}]`\n  }\n}\n\n/** An HTTP status carried on a thrown error, read without trusting its getter. Provider SDKs put\n *  one on their own error classes, so this is how a refusal is recognised outside the transport\n *  taxonomy — for the persisted message here, and for the driver's retry verdict. */\nexport function errorHttpStatus(error: Error): number | undefined {\n  try {\n    const status: unknown = Reflect.get(error, 'status')\n    return typeof status === 'number' && Number.isInteger(status) && status >= 100 && status <= 599\n      ? status\n      : undefined\n  } catch {\n    return undefined\n  }\n}\n\n/** Shared by child settlements, driver attempts, and the final no-winner result. */\nexport function errMessage(error: unknown): string {\n  const parts: string[] = []\n  const seen = new Set<Error>()\n  let current = error\n  for (let depth = 0; depth <= maxCauseDepth; depth += 1) {\n    try {\n      if (!(current instanceof Error)) {\n        parts.push(errorText(current).slice(0, maxPartLength))\n        break\n      }\n      if (seen.has(current)) {\n        parts.push('[circular]')\n        break\n      }\n      seen.add(current)\n      const status = errorHttpStatus(current)\n      const message =\n        (status === undefined ? '' : `HTTP ${status}: `) + (errorProperty(current, 'message') ?? '')\n      // An AggregateError's members carry its evidence: name each, one level deep.\n      const members: unknown = Reflect.get(current, 'errors')\n      const named = Array.isArray(members)\n        ? ` [${members.map((m) => (m instanceof Error ? `${errorProperty(m, 'name')}: ${errorProperty(m, 'message')}` : errorText(m))).join('; ')}]`\n        : ''\n      const part = depth === 0 ? message : `${errorProperty(current, 'name')}: ${message}`\n      parts.push(`${part}${named}`.slice(0, maxPartLength))\n      current = current.cause\n      if (current === undefined || current === null) break\n      if (depth === maxCauseDepth) parts.push('[cause chain truncated]')\n    } catch {\n      parts.push('[unreadable error cause]')\n      break\n    }\n  }\n  return parts.join(': caused by ').slice(0, maxMessageLength)\n}\n\n/** The error and its causes (`cause`, and `errors` members), bounded and cycle-safe. */\nexport function causeChain(error: unknown): object[] {\n  const chain: object[] = []\n  const queue: unknown[] = [error]\n  while (queue.length > 0 && chain.length < 12) {\n    const value = queue.shift()\n    if (typeof value !== 'object' || value === null || chain.includes(value)) continue\n    chain.push(value)\n    try {\n      const errors: unknown = Reflect.get(value, 'errors')\n      if (Array.isArray(errors)) queue.push(...errors)\n      queue.push(Reflect.get(value, 'cause'))\n    } catch {\n      // A cause that cannot be read ends this branch of the walk.\n    }\n  }\n  return chain\n}\n\nconst maxStackFrames = 40\n\n/** The deepest cause's stack that has one, redacted and bounded to {@link maxStackFrames} frames,\n *  so a failure the messages alone cannot place still names its throw site (#2347). Outer\n *  wrappers' stacks are skipped: they restate the wrap site the record's own fields name. */\nexport function errorStack(error: unknown): string | undefined {\n  let found: string | undefined\n  for (const value of causeChain(error)) {\n    if (!(value instanceof Error)) continue\n    const stack = errorProperty(value, 'stack')\n    if (stack !== undefined && stack !== '[unreadable error stack]') found = stack\n  }\n  return found === undefined ? undefined : found.split('\\n').slice(0, maxStackFrames).join('\\n')\n}\n","import { ValidationError } from '../../errors'\n\n/** Deeply detach and freeze untrusted data at a runtime decision boundary. The clone prevents the\n * caller from mutating it later; the freeze prevents downstream code from mutating the snapshot.\n * Strings are immutable, so the snapshot shares the caller's strings instead of copying them. */\nexport function detachedSnapshot<T>(value: T, context: string): T {\n  let clone: T\n  try {\n    clone = structuredClone(value)\n  } catch (error) {\n    throw new ValidationError(`${context}: input must be structured-cloneable`, { cause: error })\n  }\n  return deepFreeze(shareSourceStrings(value, clone))\n}\n\n/** Detach a value from its caller and freeze it, without the `ValidationError` framing\n *  {@link detachedSnapshot} adds. For a boundary that has already validated its input. */\nexport function detachedFrozen<T>(value: T): T {\n  return deepFreeze(shareSourceStrings(value, structuredClone(value)))\n}\n\n/**\n * Point each string in a fresh structured clone at the equal string in its source.\n *\n * `structuredClone` copies every string, and a copied string buys no isolation: only objects and\n * arrays can change through a shared reference. A spawned profile passes several boundaries, and\n * each one kept its own copy: in a reproduction of Discovery's hosted coordinator, a child profile\n * that mounts a 5.3 MB file packet was held four times per spawned child. A scope keeps every\n * child it spawned, so the heap grew about 22 MB per spawn, and hosted coordinators died with V8\n * heap OOM after 37 spawns.\n *\n * The walk pairs only own data properties of plain objects and arrays. Accessors, Maps, Sets and\n * other cloned types keep the clone's values. A string is replaced only by a string equal to it,\n * so the snapshot holds exactly the clone's value. The snapshot keeps the source's strings alive.\n */\nfunction shareSourceStrings<T>(source: unknown, clone: T): T {\n  const visited = new Set<object>()\n  const visit = (from: unknown, to: unknown): void => {\n    if (from === null || to === null || typeof from !== 'object' || typeof to !== 'object') return\n    const array = Array.isArray(to)\n    if (array !== Array.isArray(from)) return\n    if (!array && Object.getPrototypeOf(to) !== Object.prototype) return\n    if (visited.has(to)) return\n    visited.add(to)\n    const target = to as Record<string, unknown>\n    for (const key of Object.keys(target)) {\n      const own = Object.getOwnPropertyDescriptor(from, key)\n      if (own === undefined || !('value' in own)) continue\n      const cloned = target[key]\n      if (typeof cloned === 'string') {\n        if (own.value === cloned) target[key] = own.value\n      } else visit(own.value, cloned)\n    }\n  }\n  visit(source, clone)\n  return clone\n}\n\n/**\n * Replace each string in a freshly parsed JSON value with an equal string already in `pool`, and\n * add the new ones. One recovery pass parses every interrupted child's profile from its own blob,\n * so children that carry the same file packet would otherwise hold one copy each. The value is\n * updated in place, so it must belong to the caller; frozen objects are left as they are.\n */\nexport function shareParsedStrings<T>(value: T, pool: Map<string, string>): T {\n  const visit = (node: unknown): void => {\n    if (node === null || typeof node !== 'object' || Object.isFrozen(node)) return\n    if (!Array.isArray(node) && Object.getPrototypeOf(node) !== Object.prototype) return\n    const target = node as Record<string, unknown>\n    for (const key of Object.keys(target)) {\n      const item = target[key]\n      if (typeof item !== 'string') {\n        visit(item)\n        continue\n      }\n      const shared = pool.get(item)\n      if (shared === undefined) pool.set(item, item)\n      else target[key] = shared\n    }\n  }\n  visit(value)\n  return value\n}\n\nfunction deepFreeze<T>(value: T, seen = new Set<object>()): T {\n  // `Object.freeze` throws `TypeError: Cannot freeze array buffer views with elements` on any\n  // non-empty TypedArray or Buffer, so binary inside a payload must be handed back untouched\n  // rather than frozen. Its bytes are already detached by the `structuredClone` above.\n  if (value === null || typeof value !== 'object' || ArrayBuffer.isView(value) || seen.has(value)) {\n    return value\n  }\n  seen.add(value)\n  for (const child of Object.values(value as Record<string, unknown>)) deepFreeze(child, seen)\n  return Object.freeze(value)\n}\n"],"mappings":"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"}

package/dist/{structural-rollout-BwTwTUXF.js → structural-rollout-C1xxoWcN.js}

@@ -1,10 +1,10 @@
-import { Br as executableAgentProfileSnapshot, Cr as knownMaterializationReceipt, Fr as runtimeOwnedPendingExecutorMaterialization, Mr as runtimeOwnedExecutorExecutionBinding, Nr as runtimeOwnedExecutorMaterialization, Rr as unknownExecutionBindingReceipt, Sr as knownExecutionBindingReceipt, ii as providerMessageText, ni as promptFromAgentTurnInput, qr as awaitAbortable, ri as promptOptionsFromAgentTurnInput, yr as authoredProfileDigest, zr as unknownMaterializationReceipt } from "./scope-gIYQ5ZiL.js";
-import { m as ValidationError, p as SessionMismatchError, r as BackendTransportError } from "./errors-AzSuGI23.js";
-import { I as armDeadlineTimer, c as errorMessage, f as isAsyncIterable } from "./util-C_cdPNC4.js";
-import { ct as canonicalStreamEventFromSandboxEvent, mt as createSandboxUsageLedger, n as runtimeFailureCause, nt as mapSandboxEvent, rt as mapSandboxToolEvent, st as terminalTextFromSandboxEvent, tt as createSandboxToolPartState } from "./failure-cause-BzjUUsRz.js";
-import { C as createExecutor, S as captureReusableExecutorConfig, _ as withDriverExecutor, an as readSandboxOutcome, b as createExecutorRegistry, in as projectSandboxOutcome, n as createSupervisor, v as InMemoryResultBlobStore, y as InMemorySpawnJournal } from "./supervisor-1A27fE6k.js";
-import { c as profileModelExecutionSettings, g as observedModelMatchesDeclared, i as concreteModelId, l as profileProviderModel, o as enforceTokenLimits, s as profileBridgeWireModel, t as assertExecutableAgentProfile } from "./model-policy-JOcg3NRs.js";
-import { z as sha256Bytes$1 } from "./workspace-streams-B7yNMahl.js";
+import { $r as awaitAbortable, Br as runtimeOwnedPendingExecutorMaterialization, Dr as knownExecutionBindingReceipt, Gr as executableAgentProfileSnapshot, Lr as runtimeOwnedExecutorExecutionBinding, Or as knownMaterializationReceipt, Rr as runtimeOwnedExecutorMaterialization, Ur as unknownExecutionBindingReceipt, Wr as unknownMaterializationReceipt, di as providerMessageText, li as promptFromAgentTurnInput, ui as promptOptionsFromAgentTurnInput, wr as authoredProfileDigest } from "./supervisor-accounting-Bw4MJk-b.js";
+import { m as ValidationError, p as SessionMismatchError, r as BackendTransportError } from "./errors-DG8yufqX.js";
+import { I as armDeadlineTimer, c as errorMessage, f as isAsyncIterable } from "./util-fcckrkKp.js";
+import { ct as terminalTextFromSandboxEvent, ht as createSandboxUsageLedger, it as mapSandboxToolEvent, lt as canonicalStreamEventFromSandboxEvent, n as runtimeFailureCause, nt as createSandboxToolPartState, rt as mapSandboxEvent } from "./failure-cause-CVB-YE88.js";
+import { C as createExecutor, Qt as readSandboxOutcome, S as captureReusableExecutorConfig, Zt as projectSandboxOutcome, _ as withDriverExecutor, b as createExecutorRegistry, n as createSupervisor, v as InMemoryResultBlobStore, y as InMemorySpawnJournal } from "./supervisor-Dpeu7rnZ.js";
+import { c as profileModelExecutionSettings, g as observedModelMatchesDeclared, i as concreteModelId, l as profileProviderModel, o as enforceTokenLimits, s as profileBridgeWireModel, t as assertExecutableAgentProfile } from "./model-policy-yxOrDTTj.js";
+import { z as sha256Bytes$1 } from "./workspace-streams-DA9R3j-p.js";
 import { agentProfileSchema, canonicalAgentProfileDigest, canonicalCandidateDigest, renderInputPartsAsText } from "@tangle-network/agent-interface";
 import { costForTokenPricing, makeProposalFinding, scoreKnowledgeReadiness } from "@tangle-network/agent-eval";
 import { createAgentRunOutcomeTracker } from "@tangle-network/sandbox/runtime";
@@ -702,52 +702,16 @@ function deriveTurnSignal(callerSignal, timeoutMs) {
 }
 // src/runtime/stream-agent-turn.ts
 /**
-* `streamAgentTurn` — the ONE run-a-turn event-stream contract over every
-* execution substrate: a sandbox box (`SandboxInstance.streamPrompt`), a
-* one-shot Runtime-owned `Executor` (cli-bridge / router / sandbox, via
-* `ExecutorFactory`), and an in-process `AgentExecutionBackend`.
-*
-* One function, one vocabulary: every backend kind yields the existing
-* `RuntimeStreamEvent` union incrementally and ALWAYS terminates with a
-* `final` event whose `text` is the turn's final text and whose
-* `metadata.tokenUsage` / `metadata.costUsd` / `metadata.model` carry the
-* turn's metered usage. `collectAgentTurn` drains a stream into that terminal
-* summary plus the full event list.
-*
-* This is a UNIFICATION seam, not a new stream parser — each kind is a thin
-* adapter over code that already exists and is already hardened:
-*   - `box`      — `mapSandboxEvent` projects the sandbox event stream and one
-*                  `SandboxUsageLedger` (sandbox-events.ts) meters it, so a harness
-*                  that reports usage only in its own event is counted once per turn;
-*                  its requested profile is explicitly recorded as unverified because
-*                  the box already exists.
-*   - `executor` — Runtime materializes the exact `AgentProfile`, records its
-*                  identity receipts, drives the executor once, and tears it
-*                  down after capturing the terminal artifact.
-*   - `chat`     — the backend's own `stream()` surface, normalized by
-*                  `normalizeBackendStreamEvent`; its requested profile is likewise
-*                  unverified because an arbitrary backend cannot attest its setup.
-*
-* Distinct from `openSandboxRun` (box-only, session resume over one persistent
-* artifact, raw `SandboxEvent` deliverables) and from `runAgentTaskStream`
-* (full task lifecycle: knowledge preflight, session store, resume). This is
-* the minimal turn primitive underneath both worlds: prompt in, one normalized
-* event stream out, terminal result+usage guaranteed on every non-thrown path.
-*
-* Stream envelope: `backend_start` → incremental events → (`backend_error` on
-* failure) → `final`. A caller-initiated abort terminates with
-* `final.status: 'aborted'`; an expired `timeoutMs` deadline with
-* `final.status: 'failed'` — so cancellation stays distinguishable from a
-* blown deadline.
-*
-* Mid-stream lifecycle work needs NO extra API: the generator is pull-based,
-* so the producer is suspended between yields and resumes only when the caller
-* pulls again. A consumer can therefore run arbitrary async work between
-* events — sync state on each `tool_result`, decide a no-op retry after
-* draining, run a pre-`done` flush when it receives `final` and BEFORE it
-* forwards its own terminal event downstream. The interleaving is guaranteed
-* (and locked by test): nothing is produced past the event the caller is
-* holding.
+* `streamAgentTurn` is the one run-a-turn event stream for a sandbox box, a one-shot `Executor`,
+* and an in-process `AgentExecutionBackend`. Every kind yields `RuntimeStreamEvent` and ends with
+* `final` (`text`, `metadata.tokenUsage`, `metadata.costUsd`, `metadata.model`). `collectAgentTurn`
+* drains that. `box` meters with one `SandboxUsageLedger` and records the requested profile
+* unverified. `executor` materializes the `AgentProfile`, drives once, and tears down after the
+* terminal artifact. `chat` normalizes `stream()` and is likewise unverified. This is not
+* `openSandboxRun` or `runAgentTaskStream`. Envelope: `backend_start`, incremental events,
+* `backend_error` on failure, then `final`. Abort ends `final.status: 'aborted'`; `timeoutMs`
+* ends `final.status: 'failed'`. The generator is pull-based, so a consumer can work between events
+* and nothing is produced past the event it holds.
 *
 * @stable
 */
@@ -904,6 +868,7 @@ async function* streamAgentTurnInternal(backend, input, opts) {
 			}, {
 				signal: deadline.signal,
 				seams: {},
+				...opts.propagatedHeaders ? { propagatedHeaders: opts.propagatedHeaders } : {},
 				node: {
 					rootId: nodeId,
 					parentId: nodeId,
@@ -1104,7 +1069,9 @@ function materializedModel(receipt, profile) {
 // src/runtime/profile-chat-client.ts
 /** Profile-exact adapter for packages that consume agent-eval's ChatClient contract.
 * Every call still enters Runtime through createExecutor -> streamAgentTurn, and every
-* behavioral field is checked against the exact AgentProfile before any transport runs. */
+* behavioral field is checked against the exact AgentProfile before any transport runs.
+* Optional `headers` are forwarded on every Router request. Runtime's own content-type,
+* authorization, idempotency-key, and x-correlation-id keep precedence. */
 function profileChatClient(args) {
 	const binding = bindProfileChat(args);
 	return {
@@ -1190,12 +1157,14 @@ function bindProfileChat(args) {
 	const profile = executableAgentProfileSnapshot(args.profile, args.context);
 	const model = concreteModelId(profile.model?.default);
 	if (!model) throw new Error(`${args.context}: AgentProfile.model.default must be concrete`);
+	const headers = callerRequestHeaders(args.headers, args.context);
 	return {
 		profile,
 		executor: captureReusableExecutorConfig(args.executor, args.context),
 		context: args.context,
 		model,
-		settings: profileModelExecutionSettings(profile, args.context, args.executor.backend === "provider" ? "provider" : "router")
+		settings: profileModelExecutionSettings(profile, args.context, args.executor.backend === "provider" ? "provider" : "router"),
+		...headers ? { headers } : {}
 	};
 }
 async function runBoundProfileChat(binding, req, callOpts) {
@@ -1212,7 +1181,8 @@ async function runBoundProfileChat(binding, req, callOpts) {
 		...req.timeoutMs !== void 0 ? { timeoutMs: req.timeoutMs } : {},
 		...callOpts?.signal ? { signal: callOpts.signal } : {},
 		...callOpts?.idempotencyKey ? { callId: callOpts.idempotencyKey } : {},
-		...callOpts?.correlationId ? { correlationId: callOpts.correlationId } : {}
+		...callOpts?.correlationId ? { correlationId: callOpts.correlationId } : {},
+		...binding.headers ? { propagatedHeaders: binding.headers } : {}
 	}));
 	if (turn.status !== "completed") return {
 		succeeded: false,
@@ -1305,6 +1275,18 @@ function toolCarryingExecutor(binding, req) {
 		tools
 	}, binding.context);
 }
+/** Caller headers are a lowercase token map. Runtime overwrites its own connection headers later. */
+function callerRequestHeaders(headers, context) {
+	if (headers === void 0) return void 0;
+	if (headers === null || typeof headers !== "object" || Array.isArray(headers)) throw new Error(`${context}: headers must be an object of lowercase header names to strings`);
+	const normalized = {};
+	for (const [name, value] of Object.entries(headers)) {
+		if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) throw new Error(`${context}: header name ${JSON.stringify(name)} must be a lowercase token such as x-tangle-client`);
+		if (typeof value !== "string" || value.length === 0 || /[\r\n\0]/.test(value)) throw new Error(`${context}: header ${JSON.stringify(name)} must be one non-empty line`);
+		normalized[name] = value;
+	}
+	return normalized;
+}
 function assertSupportedChatCallOptions(opts, context) {
 	if (opts?.maxCostUsd !== void 0) throw new Error(`${context}: maxCostUsd is not enforced by Runtime's exact turn path; refusing to treat it as a limit`);
 }
@@ -3070,4 +3052,4 @@ function structuralRollout(config = {}) {
 }
 export { defaultAnalystInstruction as A, InMemoryRuntimeSessionStore as B, optimizerMethod as C, runAgentic as D, refine as E, collectAgentTurn as F, nowIso as H, streamAgentTurn as I, createIterableBackend as L, renderReport as M, profileChatClient as N, sample as O, profileOptimizerModelCall as P, createSandboxPromptBackend as R, strategyAuthorSystemPrompt as S, depthStrategy as T, startOrResumeRuntimeSession as U, newRuntimeSession as V, touchSession as W, defineStrategy as _, defaultStructuralRolloutPolicy as a, sampleThenRefine as b, officialChecksFromMeta as c, selectBestIndex as d, structuralRollout as f, authorStrategy as g, assertStrategyContract as h, defaultExtractCandidate as i, observe as j, ObservationError as k, resolveEntrySymbol as l, adaptiveRefine as m, compareCheckOutcomes as n, filterAuthoredAsserts as o, visibleCheckScore as p, composeCheckSources as r, modelAuthoredChecks as s, canDisplace as t, sandboxCheckRunner as u, loadAuthoredStrategy as v, breadthStrategy as w, strategyAuthorContract as x, requestStrategySource as y, normalizeBackendStreamEvent as z };
 
-//# sourceMappingURL=structural-rollout-BwTwTUXF.js.map
+//# sourceMappingURL=structural-rollout-C1xxoWcN.js.map