@librechat/agents 3.3.4 → 3.3.6

package/dist/esm/tools/toolOutputReferences.mjs

@@ -1,5 +1,6 @@
 import { HARD_MAX_TOOL_RESULT_CHARS, HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE, calculateMaxTotalToolOutputSize } from "../utils/truncation.mjs";
 import { isComputerCallOutputMessage } from "../utils/toolContent.mjs";
+import "./intentArg.mjs";
 import { ToolMessage } from "@langchain/core/messages";
 //#region src/tools/toolOutputReferences.ts
 /**
@@ -25,6 +26,16 @@ import { ToolMessage } from "@langchain/core/messages";
 * registry pristine means downstream bash/jq piping receives the
 * complete, verbatim output with no injected fields.
 */
+/** Parses a stringified JSON object arg; undefined for anything else. */
+function parseStringifiedArgsObject(value) {
+	if (!value.trim().startsWith("{")) return;
+	try {
+		const parsed = JSON.parse(value);
+		if (parsed != null && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+	} catch {
+		return;
+	}
+}
 /**
 * Non-global matcher for a single `{{tool<i>turn<n>}}` placeholder.
 * Exported for consumers that want to detect references (e.g., syntax
@@ -234,13 +245,13 @@ var ToolOutputReferenceRegistry = class ToolOutputReferenceRegistry {
 	* the serialized args, the original input is returned without
 	* walking the tree.
 	*/
-	resolve(runId, args) {
+	resolve(runId, args, options) {
 		if (!hasAnyPlaceholder(args)) return {
 			resolved: args,
 			unresolved: []
 		};
 		const bucket = this.runStates.get(this.keyFor(runId));
-		return this.resolveAgainst(bucket?.entries ?? EMPTY_ENTRIES, args);
+		return this.resolveAgainst(bucket?.entries ?? EMPTY_ENTRIES, args, options);
 	}
 	/**
 	* Captures a frozen snapshot of `runId`'s current entries and
@@ -256,26 +267,49 @@ var ToolOutputReferenceRegistry = class ToolOutputReferenceRegistry {
 	snapshot(runId) {
 		const bucket = this.runStates.get(this.keyFor(runId));
 		const entries = bucket ? new Map(bucket.entries) : EMPTY_ENTRIES;
-		return { resolve: (args) => this.resolveAgainst(entries, args) };
+		return { resolve: (args, options) => this.resolveAgainst(entries, args, options) };
 	}
-	resolveAgainst(entries, args) {
+	resolveAgainst(entries, args, options) {
 		if (!hasAnyPlaceholder(args)) return {
 			resolved: args,
 			unresolved: []
 		};
+		const exemptIntentKey = options?.substituteIntentKey !== true;
 		const unresolved = /* @__PURE__ */ new Set();
+		/**
+		* Providers may deliver the args OBJECT as a JSON string. A plain
+		* string-root transform would expand placeholders inside the `intent`
+		* label too, bypassing the top-level exclusion below — parse, transform
+		* key-aware, and re-serialize so the label stays verbatim while every
+		* other field still substitutes. Only taken when an `intent` key is
+		* actually present; other strings keep the fast raw-string path.
+		*/
+		if (exemptIntentKey && typeof args === "string") {
+			const parsedRoot = parseStringifiedArgsObject(args);
+			if (parsedRoot != null && "intent" in parsedRoot) return {
+				resolved: JSON.stringify(this.transform(entries, parsedRoot, unresolved, true)),
+				unresolved: Array.from(unresolved)
+			};
+		}
 		return {
-			resolved: this.transform(entries, args, unresolved),
+			resolved: this.transform(entries, args, unresolved, exemptIntentKey),
 			unresolved: Array.from(unresolved)
 		};
 	}
-	transform(entries, value, unresolved) {
+	transform(entries, value, unresolved, exemptRootIntent = false) {
 		if (typeof value === "string") return this.replaceInString(entries, value, unresolved);
 		if (Array.isArray(value)) return value.map((item) => this.transform(entries, item, unresolved));
 		if (value !== null && typeof value === "object") {
 			const source = value;
 			const next = {};
-			for (const [key, item] of Object.entries(source)) next[key] = this.transform(entries, item, unresolved);
+			for (const [key, item] of Object.entries(source))
+ /**
+			* The top-level `intent` arg is a display label, never a data
+			* channel: expanding a `{{tool<i>turn<n>}}` placeholder there would
+			* dump a stored output (up to the registry cap) into a single-line
+			* UI label and persist it with the message. Left verbatim instead.
+			*/
+			next[key] = exemptRootIntent && key === "intent" ? item : this.transform(entries, item, unresolved);
 			return next;
 		}
 		return value;

package/dist/esm/tools/toolOutputReferences.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"toolOutputReferences.mjs","names":[],"sources":["../../../src/tools/toolOutputReferences.ts"],"sourcesContent":["/**\n * Tool output reference registry.\n *\n * When enabled via `RunConfig.toolOutputReferences.enabled`, ToolNode\n * stores each successful tool output under a stable key\n * (`tool<idx>turn<turn>`) where `idx` is the tool's position within a\n * ToolNode batch and `turn` is the batch index within the run\n * (incremented once per ToolNode invocation).\n *\n * Subsequent tool calls can pipe a previous output into their args by\n * embedding `{{tool<idx>turn<turn>}}` inside any string argument;\n * {@link ToolOutputReferenceRegistry.resolve} walks the args and\n * substitutes the placeholders immediately before invocation.\n *\n * The registry stores the *raw, untruncated* tool output so a later\n * `{{…}}` substitution pipes the full payload into the next tool —\n * even when the LLM only saw a head+tail-truncated preview in\n * `ToolMessage.content`. Outputs are stored without any annotation\n * (the `_ref` key or the `[ref: ...]` prefix seen by the LLM is\n * strictly a UX signal attached to `ToolMessage.content`). Keeping the\n * registry pristine means downstream bash/jq piping receives the\n * complete, verbatim output with no injected fields.\n */\n\nimport { ToolMessage } from '@langchain/core/messages';\nimport type { BaseMessage } from '@langchain/core/messages';\nimport {\n  calculateMaxTotalToolOutputSize,\n  HARD_MAX_TOOL_RESULT_CHARS,\n  HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE,\n} from '@/utils/truncation';\nimport { isComputerCallOutputMessage } from '@/utils/toolContent';\n\n/**\n * Non-global matcher for a single `{{tool<i>turn<n>}}` placeholder.\n * Exported for consumers that want to detect references (e.g., syntax\n * highlighting, docs). The stateful `g` variant lives inside the\n * registry so nobody trips on `lastIndex`.\n */\nexport const TOOL_OUTPUT_REF_PATTERN = /\\{\\{(tool\\d+turn\\d+)\\}\\}/;\n\n/** Object key used when a parsed-object output has `_ref` injected. */\nexport const TOOL_OUTPUT_REF_KEY = '_ref';\n\n/**\n * Object key used to carry unresolved reference warnings on a parsed-\n * object output. Using a dedicated field instead of a trailing text\n * line keeps the annotated `ToolMessage.content` parseable as JSON for\n * downstream consumers that rely on the object shape.\n */\nexport const TOOL_OUTPUT_UNRESOLVED_KEY = '_unresolved_refs';\n\n/** Single-line prefix prepended to non-object tool outputs so the LLM sees the reference key. */\nexport function buildReferencePrefix(key: string): string {\n  return `[ref: ${key}]`;\n}\n\n/** Stable registry key for a tool output. */\nexport function buildReferenceKey(toolIndex: number, turn: number): string {\n  return `tool${toolIndex}turn${turn}`;\n}\n\nexport type ToolOutputReferenceRegistryOptions = {\n  /** Maximum characters stored per registered output. */\n  maxOutputSize?: number;\n  /** Maximum total characters retained across all registered outputs. */\n  maxTotalSize?: number;\n  /**\n   * Upper bound on the number of concurrently-tracked runs. When\n   * exceeded, the oldest run bucket is evicted (FIFO). Defaults to 32.\n   */\n  maxActiveRuns?: number;\n};\n\n/**\n * Result of resolving placeholders in tool args.\n */\nexport type ResolveResult<T> = {\n  /** Arguments with placeholders replaced. Same shape as the input. */\n  resolved: T;\n  /** Reference keys that were referenced but had no stored value. */\n  unresolved: string[];\n};\n\n/**\n * Read-only view over a frozen registry snapshot. Returned by\n * {@link ToolOutputReferenceRegistry.snapshot} for callers that need\n * to resolve placeholders against the registry state at a specific\n * point in time, ignoring any subsequent registrations.\n */\nexport interface ToolOutputResolveView {\n  resolve<T>(args: T): ResolveResult<T>;\n}\n\n/**\n * Pre-resolved arg map keyed by `toolCallId`. Used by the mixed\n * direct+event dispatch path to feed event calls' resolved args\n * (captured pre-batch) into the dispatcher without re-resolving\n * against the now-stale live registry.\n */\nexport type PreResolvedArgsMap = Map<\n  string,\n  { resolved: Record<string, unknown>; unresolved: string[] }\n>;\n\n/**\n * Per-call sink for resolved args, keyed by `toolCallId`. Threaded\n * as a per-batch local map so concurrent `ToolNode.run()` calls do\n * not race on shared sink state.\n */\nexport type ResolvedArgsByCallId = Map<string, Record<string, unknown>>;\n\nconst EMPTY_ENTRIES: ReadonlyMap<string, string> = new Map<string, string>();\n\n/**\n * Per-run state bucket held inside the registry. Each distinct\n * `run_id` gets its own bucket so overlapping concurrent runs on a\n * shared registry cannot leak outputs, turn counters, or warn-memos\n * into one another.\n */\nclass RunStateBucket {\n  entries: Map<string, string> = new Map();\n  totalSize: number = 0;\n  turnCounter: number = 0;\n  warnedNonStringTools: Set<string> = new Set();\n}\n\n/**\n * Anonymous (`run_id` absent) bucket key. Anonymous batches are\n * treated as fresh runs on every invocation — see `nextTurn`.\n */\nconst ANON_RUN_KEY = '\\0anon';\n\n/**\n * Default upper bound on the number of concurrently-tracked runs per\n * registry. When exceeded, the oldest run's bucket (by insertion\n * order) is evicted. Keeps memory bounded when a ToolNode is reused\n * across many runs without explicit `releaseRun` calls.\n */\nconst DEFAULT_MAX_ACTIVE_RUNS = 32;\n\n/**\n * Ordered map of reference-key → stored output, partitioned by run so\n * concurrent / interleaved runs sharing one registry cannot leak\n * outputs between each other.\n *\n * Each public method takes a `runId` which selects the run's bucket.\n * Hosts typically get one registry per run via `Graph`, in which\n * case only a single bucket is ever populated; the partitioning\n * exists so the registry also behaves correctly when a single\n * instance is reused directly.\n */\nexport class ToolOutputReferenceRegistry {\n  private runStates: Map<string, RunStateBucket> = new Map();\n  private readonly maxOutputSize: number;\n  private readonly maxTotalSize: number;\n  private readonly maxActiveRuns: number;\n  /**\n   * Local stateful matcher used only by `replaceInString`. Kept\n   * off-module so callers of the exported `TOOL_OUTPUT_REF_PATTERN`\n   * never see a stale `lastIndex`.\n   */\n  private static readonly PLACEHOLDER_MATCHER = /\\{\\{(tool\\d+turn\\d+)\\}\\}/g;\n\n  constructor(options: ToolOutputReferenceRegistryOptions = {}) {\n    /**\n     * Per-output default is the same ~400 KB budget as the standard\n     * tool-result truncation (`HARD_MAX_TOOL_RESULT_CHARS`). This\n     * keeps a single `{{…}}` substitution at a size that is safe to\n     * pass through typical shell `ARG_MAX` limits and matches what\n     * the LLM would otherwise have seen. Hosts that want larger per-\n     * output payloads (API consumers, long JSON streams) can raise\n     * the cap explicitly up to the 5 MB total budget.\n     */\n    const perOutput =\n      options.maxOutputSize != null && options.maxOutputSize > 0\n        ? options.maxOutputSize\n        : HARD_MAX_TOOL_RESULT_CHARS;\n    /**\n     * Clamp a caller-supplied `maxTotalSize` to\n     * `HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE` (5 MB) so the documented\n     * absolute cap is enforced regardless of host config —\n     * `calculateMaxTotalToolOutputSize` already applies the same\n     * upper bound on its computed default, but the user-provided\n     * branch was bypassing it.\n     */\n    const totalRaw =\n      options.maxTotalSize != null && options.maxTotalSize > 0\n        ? Math.min(options.maxTotalSize, HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE)\n        : calculateMaxTotalToolOutputSize(perOutput);\n    this.maxTotalSize = totalRaw;\n    /**\n     * The per-output cap can never exceed the per-run aggregate cap:\n     * if a single entry were allowed to be larger than `maxTotalSize`,\n     * the eviction loop would either blow the cap (to keep the entry)\n     * or self-evict a just-stored value. Clamping here turns\n     * `maxTotalSize` into a hard upper bound on *any* state the\n     * registry retains per run.\n     */\n    this.maxOutputSize = Math.min(perOutput, totalRaw);\n    this.maxActiveRuns =\n      options.maxActiveRuns != null && options.maxActiveRuns > 0\n        ? options.maxActiveRuns\n        : DEFAULT_MAX_ACTIVE_RUNS;\n  }\n\n  private keyFor(runId: string | undefined): string {\n    return runId ?? ANON_RUN_KEY;\n  }\n\n  private getOrCreate(runId: string | undefined): RunStateBucket {\n    const key = this.keyFor(runId);\n    let state = this.runStates.get(key);\n    if (state == null) {\n      state = new RunStateBucket();\n      this.runStates.set(key, state);\n      if (this.runStates.size > this.maxActiveRuns) {\n        const oldest = this.runStates.keys().next().value;\n        if (oldest != null && oldest !== key) {\n          this.runStates.delete(oldest);\n        }\n      }\n    }\n    return state;\n  }\n\n  /** Registers (or replaces) the output stored under `key` for `runId`. */\n  set(runId: string | undefined, key: string, value: string): void {\n    const bucket = this.getOrCreate(runId);\n    const clipped =\n      value.length > this.maxOutputSize\n        ? value.slice(0, this.maxOutputSize)\n        : value;\n    const existing = bucket.entries.get(key);\n    if (existing != null) {\n      bucket.totalSize -= existing.length;\n      bucket.entries.delete(key);\n    }\n    bucket.entries.set(key, clipped);\n    bucket.totalSize += clipped.length;\n    this.evictWithinBucket(bucket);\n  }\n\n  /** Returns the stored value for `key` in `runId`'s bucket, or `undefined`. */\n  get(runId: string | undefined, key: string): string | undefined {\n    return this.runStates.get(this.keyFor(runId))?.entries.get(key);\n  }\n\n  /**\n   * Returns `true` when `key` is currently stored in `runId`'s bucket.\n   * Used by {@link annotateMessagesForLLM} to gate transient annotation\n   * on whether the registry still owns the referenced output (a stale\n   * `_refKey` from a prior run silently no-ops here).\n   */\n  has(runId: string | undefined, key: string): boolean {\n    return this.runStates.get(this.keyFor(runId))?.entries.has(key) ?? false;\n  }\n\n  /** Total number of registered outputs across every run bucket. */\n  get size(): number {\n    let n = 0;\n    for (const bucket of this.runStates.values()) {\n      n += bucket.entries.size;\n    }\n    return n;\n  }\n\n  /** Maximum characters retained per output (post-clip). */\n  get perOutputLimit(): number {\n    return this.maxOutputSize;\n  }\n\n  /** Maximum total characters retained *per run*. */\n  get totalLimit(): number {\n    return this.maxTotalSize;\n  }\n\n  /** Drops every run's state. */\n  clear(): void {\n    this.runStates.clear();\n  }\n\n  /**\n   * Explicitly release `runId`'s state. Safe to call when a run has\n   * finished. Hosts sharing one registry across runs should call this\n   * to reclaim memory deterministically; otherwise LRU eviction kicks\n   * in when `maxActiveRuns` runs accumulate.\n   */\n  releaseRun(runId: string | undefined): void {\n    this.runStates.delete(this.keyFor(runId));\n  }\n\n  /**\n   * Claims the next batch turn synchronously from `runId`'s bucket.\n   *\n   * Must be called once at the start of each ToolNode batch before\n   * any `await`, so concurrent invocations within the same run see\n   * distinct turn values (reads are effectively atomic by JS's\n   * single-threaded execution of the sync prefix).\n   *\n   * If `runId` is missing the anonymous bucket is dropped and a\n   * fresh one created so each anonymous call behaves as its own run.\n   */\n  nextTurn(runId: string | undefined): number {\n    if (runId == null) {\n      this.runStates.delete(ANON_RUN_KEY);\n    }\n    const bucket = this.getOrCreate(runId);\n    return bucket.turnCounter++;\n  }\n\n  /**\n   * Records that `toolName` has been warned about in `runId` (returns\n   * `true` on the first call per run, `false` after). Used by\n   * ToolNode to emit one log line per offending tool per run when a\n   * `ToolMessage.content` isn't a string.\n   */\n  claimWarnOnce(runId: string | undefined, toolName: string): boolean {\n    const bucket = this.getOrCreate(runId);\n    if (bucket.warnedNonStringTools.has(toolName)) {\n      return false;\n    }\n    bucket.warnedNonStringTools.add(toolName);\n    return true;\n  }\n\n  /**\n   * Walks `args` and replaces every `{{tool<i>turn<n>}}` placeholder in\n   * string values with the stored output *from `runId`'s bucket*. Non-\n   * string values and object keys are left untouched. Unresolved\n   * references are left in-place and reported so the caller can\n   * surface them to the LLM. When no placeholder appears anywhere in\n   * the serialized args, the original input is returned without\n   * walking the tree.\n   */\n  resolve<T>(runId: string | undefined, args: T): ResolveResult<T> {\n    if (!hasAnyPlaceholder(args)) {\n      return { resolved: args, unresolved: [] };\n    }\n    const bucket = this.runStates.get(this.keyFor(runId));\n    return this.resolveAgainst(bucket?.entries ?? EMPTY_ENTRIES, args);\n  }\n\n  /**\n   * Captures a frozen snapshot of `runId`'s current entries and\n   * returns a view that resolves placeholders against *only* that\n   * snapshot. The snapshot is decoupled from the live registry, so\n   * subsequent `set()` calls (for example, same-turn direct outputs\n   * registering while an event branch is still in flight) are\n   * invisible to the snapshot's `resolve`. Used by the mixed\n   * direct+event dispatch path to preserve same-turn isolation when\n   * a `PreToolUse` hook rewrites event args after directs have\n   * completed.\n   */\n  snapshot(runId: string | undefined): ToolOutputResolveView {\n    const bucket = this.runStates.get(this.keyFor(runId));\n    const entries: ReadonlyMap<string, string> = bucket\n      ? new Map(bucket.entries)\n      : EMPTY_ENTRIES;\n    return {\n      resolve: <T>(args: T): ResolveResult<T> =>\n        this.resolveAgainst(entries, args),\n    };\n  }\n\n  private resolveAgainst<T>(\n    entries: ReadonlyMap<string, string>,\n    args: T\n  ): ResolveResult<T> {\n    if (!hasAnyPlaceholder(args)) {\n      return { resolved: args, unresolved: [] };\n    }\n    const unresolved = new Set<string>();\n    const resolved = this.transform(entries, args, unresolved) as T;\n    return { resolved, unresolved: Array.from(unresolved) };\n  }\n\n  private transform(\n    entries: ReadonlyMap<string, string>,\n    value: unknown,\n    unresolved: Set<string>\n  ): unknown {\n    if (typeof value === 'string') {\n      return this.replaceInString(entries, value, unresolved);\n    }\n    if (Array.isArray(value)) {\n      return value.map((item) => this.transform(entries, item, unresolved));\n    }\n    if (value !== null && typeof value === 'object') {\n      const source = value as Record<string, unknown>;\n      const next: Record<string, unknown> = {};\n      for (const [key, item] of Object.entries(source)) {\n        next[key] = this.transform(entries, item, unresolved);\n      }\n      return next;\n    }\n    return value;\n  }\n\n  private replaceInString(\n    entries: ReadonlyMap<string, string>,\n    input: string,\n    unresolved: Set<string>\n  ): string {\n    if (input.indexOf('{{tool') === -1) {\n      return input;\n    }\n    return input.replace(\n      ToolOutputReferenceRegistry.PLACEHOLDER_MATCHER,\n      (match, key: string) => {\n        const stored = entries.get(key);\n        if (stored == null) {\n          unresolved.add(key);\n          return match;\n        }\n        return stored;\n      }\n    );\n  }\n\n  private evictWithinBucket(bucket: RunStateBucket): void {\n    if (bucket.totalSize <= this.maxTotalSize) {\n      return;\n    }\n    for (const key of bucket.entries.keys()) {\n      if (bucket.totalSize <= this.maxTotalSize) {\n        return;\n      }\n      const entry = bucket.entries.get(key);\n      if (entry == null) {\n        continue;\n      }\n      bucket.totalSize -= entry.length;\n      bucket.entries.delete(key);\n    }\n  }\n}\n\n/**\n * Cheap pre-check: returns true if any string value in `args` contains\n * the `{{tool` substring. Lets `resolve()` skip the deep tree walk (and\n * its object allocations) for the common case of plain args.\n */\nfunction hasAnyPlaceholder(value: unknown): boolean {\n  if (typeof value === 'string') {\n    return value.indexOf('{{tool') !== -1;\n  }\n  if (Array.isArray(value)) {\n    for (const item of value) {\n      if (hasAnyPlaceholder(item)) {\n        return true;\n      }\n    }\n    return false;\n  }\n  if (value !== null && typeof value === 'object') {\n    for (const item of Object.values(value as Record<string, unknown>)) {\n      if (hasAnyPlaceholder(item)) {\n        return true;\n      }\n    }\n    return false;\n  }\n  return false;\n}\n\n/**\n * Annotates `content` with a reference key and/or unresolved-ref\n * warnings so the LLM sees both alongside the tool output.\n *\n * Behavior:\n *  - If `content` parses as a plain (non-array, non-null) JSON object\n *    and the object does not already have a conflicting `_ref` key,\n *    the reference key and (when present) `_unresolved_refs` array\n *    are injected as object fields, preserving JSON validity for\n *    downstream consumers that parse the output.\n *  - Otherwise (string output, JSON array/primitive, parse failure,\n *    or `_ref` collision), a `[ref: <key>]\\n` prefix line is\n *    prepended and unresolved refs are appended as a trailing\n *    `[unresolved refs: …]` line.\n *\n * The annotated string is what the LLM sees as `ToolMessage.content`.\n * The *original* (un-annotated) value is what gets stored in the\n * registry, so downstream piping remains pristine.\n *\n * @param content     Raw (post-truncation) tool output.\n * @param key         Reference key for this output, or undefined when\n *                    there is nothing to register (errors etc.).\n * @param unresolved  Reference keys that failed to resolve during\n *                    argument substitution. Surfaced so the LLM can\n *                    self-correct its next tool call.\n */\nexport function annotateToolOutputWithReference(\n  content: string,\n  key: string | undefined,\n  unresolved: string[] = []\n): string {\n  const hasRefKey = key != null;\n  const hasUnresolved = unresolved.length > 0;\n  if (!hasRefKey && !hasUnresolved) {\n    return content;\n  }\n  const trimmed = content.trimStart();\n  if (trimmed.startsWith('{')) {\n    const annotated = tryInjectRefIntoJsonObject(content, key, unresolved);\n    if (annotated != null) {\n      return annotated;\n    }\n  }\n  const prefix = hasRefKey ? `${buildReferencePrefix(key!)}\\n` : '';\n  const trailer = hasUnresolved\n    ? `\\n[unresolved refs: ${unresolved.join(', ')}]`\n    : '';\n  return `${prefix}${content}${trailer}`;\n}\n\nfunction tryInjectRefIntoJsonObject(\n  content: string,\n  key: string | undefined,\n  unresolved: string[]\n): string | null {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(content);\n  } catch {\n    return null;\n  }\n\n  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {\n    return null;\n  }\n\n  const obj = parsed as Record<string, unknown>;\n  const injectingRef = key != null;\n  const injectingUnresolved = unresolved.length > 0;\n\n  /**\n   * Reject the JSON-injection path (fall back to prefix form) when\n   * either of our keys collides with real payload data:\n   *  - `_ref` collision: existing value is non-null and differs from\n   *    the key we're about to inject.\n   *  - `_unresolved_refs` collision: existing value is non-null and\n   *    is not a deep-equal match for the array we'd inject.\n   * This keeps us from silently overwriting legitimate tool output.\n   */\n  if (\n    injectingRef &&\n    TOOL_OUTPUT_REF_KEY in obj &&\n    obj[TOOL_OUTPUT_REF_KEY] !== key &&\n    obj[TOOL_OUTPUT_REF_KEY] != null\n  ) {\n    return null;\n  }\n  if (\n    injectingUnresolved &&\n    TOOL_OUTPUT_UNRESOLVED_KEY in obj &&\n    obj[TOOL_OUTPUT_UNRESOLVED_KEY] != null &&\n    !arraysShallowEqual(obj[TOOL_OUTPUT_UNRESOLVED_KEY], unresolved)\n  ) {\n    return null;\n  }\n\n  /**\n   * Only strip the framework-owned key we're actually injecting —\n   * leave everything else (including a pre-existing `_ref` on the\n   * unresolved-only path, or a pre-existing `_unresolved_refs` on a\n   * plain-annotation path) untouched so we annotate rather than\n   * mutate downstream payload data. Our injected keys land first in\n   * the serialized JSON so the LLM sees them before the body.\n   */\n  const omitKeys = new Set<string>();\n  if (injectingRef) omitKeys.add(TOOL_OUTPUT_REF_KEY);\n  if (injectingUnresolved) omitKeys.add(TOOL_OUTPUT_UNRESOLVED_KEY);\n  const rest: Record<string, unknown> = {};\n  for (const [k, v] of Object.entries(obj)) {\n    if (!omitKeys.has(k)) {\n      rest[k] = v;\n    }\n  }\n  const injected: Record<string, unknown> = {};\n  if (injectingRef) {\n    injected[TOOL_OUTPUT_REF_KEY] = key;\n  }\n  if (injectingUnresolved) {\n    injected[TOOL_OUTPUT_UNRESOLVED_KEY] = unresolved;\n  }\n  Object.assign(injected, rest);\n\n  const pretty = /^\\{\\s*\\n/.test(content);\n  return pretty ? JSON.stringify(injected, null, 2) : JSON.stringify(injected);\n}\n\nfunction arraysShallowEqual(a: unknown, b: readonly string[]): boolean {\n  if (!Array.isArray(a) || a.length !== b.length) {\n    return false;\n  }\n  for (let i = 0; i < a.length; i++) {\n    if (a[i] !== b[i]) {\n      return false;\n    }\n  }\n  return true;\n}\n\n/**\n * Lazy projection that, given a registry and a runId, returns a new\n * `messages` array where each `ToolMessage` carrying ref metadata is\n * projected into a transient copy with annotated content (when the ref\n * is live in the registry) and with the framework-owned `additional_\n * kwargs` keys (`_refKey`, `_refScope`, `_unresolvedRefs`) stripped\n * regardless of whether annotation applied. The original input array\n * and its messages are never mutated.\n *\n * Annotation is gated on registry presence: a stale `_refKey` from a\n * prior run (e.g. one that survived in persisted history) silently\n * no-ops on the *content* side. The strip-metadata side still runs so\n * stale framework keys never leak onto the wire under any custom or\n * future provider serializer that might transmit `additional_kwargs`.\n * `_unresolvedRefs` is always meaningful and is not gated.\n *\n * **Feature-disabled fast path:** when the host hasn't enabled the\n * tool-output-reference feature, the registry is `undefined` and this\n * function returns the input array reference-equal *without iterating\n * a single message*. The loop is exclusive to the feature-enabled\n * code path.\n */\nexport function annotateMessagesForLLM(\n  messages: BaseMessage[],\n  registry: ToolOutputReferenceRegistry | undefined,\n  runId: string | undefined\n): BaseMessage[] {\n  if (registry == null) return messages;\n\n  /**\n   * Lazy-allocate the output array so the common case (no ToolMessage\n   * carries framework metadata) returns the input reference-equal with\n   * zero allocations beyond the per-message predicate checks.\n   */\n  let out: BaseMessage[] | undefined;\n  for (let i = 0; i < messages.length; i++) {\n    const m = messages[i];\n    if (m._getType() !== 'tool') continue;\n    /**\n     * `additional_kwargs` is untyped at the LangChain layer\n     * (`Record<string, unknown>`), so persisted or client-supplied\n     * ToolMessages can carry arbitrary shapes — including primitives\n     * (a malformed serializer might write a string, or `null`).\n     * Guard with a runtime object check before the `in` probes\n     * because the `in` operator throws `TypeError` on primitives.\n     * A single malformed message must never crash the provider call\n     * path; skip its annotation/strip and continue.\n     */\n    const rawMeta = m.additional_kwargs as unknown;\n    if (rawMeta == null || typeof rawMeta !== 'object') continue;\n    const meta = rawMeta as Record<string, unknown>;\n    const hasRefKey = '_refKey' in meta;\n    const hasRefScope = '_refScope' in meta;\n    const hasUnresolvedField = '_unresolvedRefs' in meta;\n    if (!hasRefKey && !hasRefScope && !hasUnresolvedField) continue;\n    if (isComputerCallOutputMessage(m)) {\n      out ??= messages.slice();\n      out[i] = cloneToolMessageWithContent(m as ToolMessage, m.content);\n      continue;\n    }\n\n    const refKey = readRefKey(meta);\n    const unresolved = readUnresolvedRefs(meta);\n\n    /**\n     * Prefer the message-stamped `_refScope` for the registry lookup.\n     * For named runs it equals the current `runId`; for anonymous\n     * invocations it carries the per-batch synthetic scope minted by\n     * ToolNode (`\\0anon-<n>`), which `runId` from config cannot\n     * recover. Falling back to `runId` keeps backward compatibility\n     * with messages stamped before this field existed.\n     */\n    const lookupScope = readRefScope(meta) ?? runId;\n    const liveRef =\n      refKey != null && registry.has(lookupScope, refKey) ? refKey : undefined;\n    const annotates = liveRef != null || unresolved.length > 0;\n\n    const tm = m as ToolMessage;\n    let nextContent: ToolMessage['content'] = tm.content;\n\n    if (annotates && typeof tm.content === 'string') {\n      nextContent = annotateToolOutputWithReference(\n        tm.content,\n        liveRef,\n        unresolved\n      );\n    } else if (annotates && Array.isArray(tm.content)) {\n      /**\n       * Array tool content. The string annotator can't run — this notably\n       * includes a tail tool result that prompt caching rewrote from a string\n       * into a text-block array to host its `cache_control` / `cachePoint`\n       * marker (the `_refKey` survives on `additional_kwargs`). Project the\n       * same markers the string path would, as leading text blocks: the live\n       * `[ref: …]` prefix and/or the unresolved-refs warning. Without this the\n       * common tool-result tail loses its reference marker once cached.\n       *\n       * `as unknown as ToolMessage['content']` is unavoidable: LangChain's\n       * content union does not accept a freshly built mixed array literal even\n       * though the structural shape is valid at runtime. The double-cast is\n       * structurally safe — every original block is preserved and only\n       * `{ type: 'text', text }` blocks (which all providers accept) are\n       * prepended.\n       */\n      const prefixBlocks: Array<{ type: 'text'; text: string }> = [];\n      if (liveRef != null) {\n        prefixBlocks.push({\n          type: 'text',\n          text: buildReferencePrefix(liveRef),\n        });\n      }\n      if (unresolved.length > 0) {\n        prefixBlocks.push({\n          type: 'text',\n          text: `[unresolved refs: ${unresolved.join(', ')}]`,\n        });\n      }\n      if (prefixBlocks.length > 0) {\n        nextContent = [\n          ...prefixBlocks,\n          ...tm.content,\n        ] as unknown as ToolMessage['content'];\n      }\n    }\n\n    /**\n     * Project unconditionally: even when no annotation applies (stale\n     * `_refKey` or non-annotatable content), `cloneToolMessageWithContent`\n     * runs `stripFrameworkRefMetadata` on `additional_kwargs` so the\n     * framework-owned keys never reach the wire.\n     */\n    out ??= messages.slice();\n    out[i] = cloneToolMessageWithContent(tm, nextContent);\n  }\n\n  return out ?? messages;\n}\n\n/**\n * Reads `_refKey` defensively from untyped `additional_kwargs`. Returns\n * undefined for non-string values so a malformed field cannot poison\n * the registry lookup or downstream string operations.\n */\nfunction readRefKey(\n  meta: Record<string, unknown> | undefined\n): string | undefined {\n  const v = meta?._refKey;\n  return typeof v === 'string' ? v : undefined;\n}\n\n/**\n * Reads `_refScope` defensively from untyped `additional_kwargs`.\n * Mirrors {@link readRefKey} — non-string scopes are dropped (the\n * caller falls back to the run-derived scope) rather than passed into\n * the registry as a malformed key.\n */\nfunction readRefScope(\n  meta: Record<string, unknown> | undefined\n): string | undefined {\n  const v = meta?._refScope;\n  return typeof v === 'string' ? v : undefined;\n}\n\n/**\n * Reads `_unresolvedRefs` defensively from untyped `additional_kwargs`.\n * Returns an empty array for any non-array value, and filters out\n * non-string entries from a real array. Without this guard, a hydrated\n * ToolMessage carrying e.g. `_unresolvedRefs: 'tool0turn0'` would crash\n * `attemptInvoke` on the eventual `.length` / `.join(...)` call.\n */\nfunction readUnresolvedRefs(\n  meta: Record<string, unknown> | undefined\n): string[] {\n  const v = meta?._unresolvedRefs;\n  if (!Array.isArray(v)) return [];\n  const out: string[] = [];\n  for (const item of v) {\n    if (typeof item === 'string') out.push(item);\n  }\n  return out;\n}\n\n/**\n * Builds a fresh `ToolMessage` that mirrors `tm`'s identity fields with\n * the supplied `content`. Every `ToolMessage` field but `content` is\n * carried over so the projection is structurally identical to the\n * original from a LangChain serializer's perspective.\n *\n * `additional_kwargs` is rebuilt with the framework-owned ref keys\n * stripped. Defensive: LangChain's standard provider serializers do not\n * transmit `additional_kwargs` to provider HTTP APIs, but a custom\n * adapter or future LangChain change could. Stripping keeps the\n * implementation correct under any serializer behavior at the cost of a\n * shallow object spread per annotated message.\n */\nfunction cloneToolMessageWithContent(\n  tm: ToolMessage,\n  content: ToolMessage['content']\n): ToolMessage {\n  return new ToolMessage({\n    id: tm.id,\n    name: tm.name,\n    status: tm.status,\n    artifact: tm.artifact,\n    tool_call_id: tm.tool_call_id,\n    response_metadata: tm.response_metadata,\n    additional_kwargs: stripFrameworkRefMetadata(tm.additional_kwargs),\n    content,\n  });\n}\n\n/**\n * Returns a copy of `kwargs` with `_refKey`, `_refScope`, and\n * `_unresolvedRefs` removed. Returns the input reference-equal when\n * none of those keys are present so the no-strip path stays cheap;\n * returns `undefined` when stripping leaves the object empty so the\n * caller can drop the field entirely.\n */\nfunction stripFrameworkRefMetadata(\n  kwargs: Record<string, unknown> | undefined\n): Record<string, unknown> | undefined {\n  if (kwargs == null) return undefined;\n  if (\n    !('_refKey' in kwargs) &&\n    !('_refScope' in kwargs) &&\n    !('_unresolvedRefs' in kwargs)\n  ) {\n    return kwargs;\n  }\n  const { _refKey, _refScope, _unresolvedRefs, ...rest } = kwargs as Record<\n    string,\n    unknown\n  > & {\n    _refKey?: unknown;\n    _refScope?: unknown;\n    _unresolvedRefs?: unknown;\n  };\n  void _refKey;\n  void _refScope;\n  void _unresolvedRefs;\n  return Object.keys(rest).length === 0 ? undefined : rest;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,MAAa,0BAA0B;;AAGvC,MAAa,sBAAsB;;;;;;;AAQnC,MAAa,6BAA6B;;AAG1C,SAAgB,qBAAqB,KAAqB;CACxD,OAAO,SAAS,IAAI;AACtB;;AAGA,SAAgB,kBAAkB,WAAmB,MAAsB;CACzE,OAAO,OAAO,UAAU,MAAM;AAChC;AAoDA,MAAM,gCAA6C,IAAI,IAAoB;;;;;;;AAQ3E,IAAM,iBAAN,MAAqB;CACnB,0BAA+B,IAAI,IAAI;CACvC,YAAoB;CACpB,cAAsB;CACtB,uCAAoC,IAAI,IAAI;AAC9C;;;;;AAMA,MAAM,eAAe;;;;;;;AAQrB,MAAM,0BAA0B;;;;;;;;;;;;AAahC,IAAa,8BAAb,MAAa,4BAA4B;CACvC,4BAAiD,IAAI,IAAI;CACzD;CACA;CACA;;;;;;CAMA,OAAwB,sBAAsB;CAE9C,YAAY,UAA8C,CAAC,GAAG;;;;;;;;;;EAU5D,MAAM,YACJ,QAAQ,iBAAiB,QAAQ,QAAQ,gBAAgB,IACrD,QAAQ,gBACR;;;;;;;;;EASN,MAAM,WACJ,QAAQ,gBAAgB,QAAQ,QAAQ,eAAe,IACnD,KAAK,IAAI,QAAQ,cAAc,+BAA+B,IAC9D,gCAAgC,SAAS;EAC/C,KAAK,eAAe;;;;;;;;;EASpB,KAAK,gBAAgB,KAAK,IAAI,WAAW,QAAQ;EACjD,KAAK,gBACH,QAAQ,iBAAiB,QAAQ,QAAQ,gBAAgB,IACrD,QAAQ,gBACR;CACR;CAEA,OAAe,OAAmC;EAChD,OAAO,SAAS;CAClB;CAEA,YAAoB,OAA2C;EAC7D,MAAM,MAAM,KAAK,OAAO,KAAK;EAC7B,IAAI,QAAQ,KAAK,UAAU,IAAI,GAAG;EAClC,IAAI,SAAS,MAAM;GACjB,QAAQ,IAAI,eAAe;GAC3B,KAAK,UAAU,IAAI,KAAK,KAAK;GAC7B,IAAI,KAAK,UAAU,OAAO,KAAK,eAAe;IAC5C,MAAM,SAAS,KAAK,UAAU,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;IAC5C,IAAI,UAAU,QAAQ,WAAW,KAC/B,KAAK,UAAU,OAAO,MAAM;GAEhC;EACF;EACA,OAAO;CACT;;CAGA,IAAI,OAA2B,KAAa,OAAqB;EAC/D,MAAM,SAAS,KAAK,YAAY,KAAK;EACrC,MAAM,UACJ,MAAM,SAAS,KAAK,gBAChB,MAAM,MAAM,GAAG,KAAK,aAAa,IACjC;EACN,MAAM,WAAW,OAAO,QAAQ,IAAI,GAAG;EACvC,IAAI,YAAY,MAAM;GACpB,OAAO,aAAa,SAAS;GAC7B,OAAO,QAAQ,OAAO,GAAG;EAC3B;EACA,OAAO,QAAQ,IAAI,KAAK,OAAO;EAC/B,OAAO,aAAa,QAAQ;EAC5B,KAAK,kBAAkB,MAAM;CAC/B;;CAGA,IAAI,OAA2B,KAAiC;EAC9D,OAAO,KAAK,UAAU,IAAI,KAAK,OAAO,KAAK,CAAC,CAAC,EAAE,QAAQ,IAAI,GAAG;CAChE;;;;;;;CAQA,IAAI,OAA2B,KAAsB;EACnD,OAAO,KAAK,UAAU,IAAI,KAAK,OAAO,KAAK,CAAC,CAAC,EAAE,QAAQ,IAAI,GAAG,KAAK;CACrE;;CAGA,IAAI,OAAe;EACjB,IAAI,IAAI;EACR,KAAK,MAAM,UAAU,KAAK,UAAU,OAAO,GACzC,KAAK,OAAO,QAAQ;EAEtB,OAAO;CACT;;CAGA,IAAI,iBAAyB;EAC3B,OAAO,KAAK;CACd;;CAGA,IAAI,aAAqB;EACvB,OAAO,KAAK;CACd;;CAGA,QAAc;EACZ,KAAK,UAAU,MAAM;CACvB;;;;;;;CAQA,WAAW,OAAiC;EAC1C,KAAK,UAAU,OAAO,KAAK,OAAO,KAAK,CAAC;CAC1C;;;;;;;;;;;;CAaA,SAAS,OAAmC;EAC1C,IAAI,SAAS,MACX,KAAK,UAAU,OAAO,YAAY;EAEpC,MAAM,SAAS,KAAK,YAAY,KAAK;EACrC,OAAO,OAAO;CAChB;;;;;;;CAQA,cAAc,OAA2B,UAA2B;EAClE,MAAM,SAAS,KAAK,YAAY,KAAK;EACrC,IAAI,OAAO,qBAAqB,IAAI,QAAQ,GAC1C,OAAO;EAET,OAAO,qBAAqB,IAAI,QAAQ;EACxC,OAAO;CACT;;;;;;;;;;CAWA,QAAW,OAA2B,MAA2B;EAC/D,IAAI,CAAC,kBAAkB,IAAI,GACzB,OAAO;GAAE,UAAU;GAAM,YAAY,CAAC;EAAE;EAE1C,MAAM,SAAS,KAAK,UAAU,IAAI,KAAK,OAAO,KAAK,CAAC;EACpD,OAAO,KAAK,eAAe,QAAQ,WAAW,eAAe,IAAI;CACnE;;;;;;;;;;;;CAaA,SAAS,OAAkD;EACzD,MAAM,SAAS,KAAK,UAAU,IAAI,KAAK,OAAO,KAAK,CAAC;EACpD,MAAM,UAAuC,SACzC,IAAI,IAAI,OAAO,OAAO,IACtB;EACJ,OAAO,EACL,UAAa,SACX,KAAK,eAAe,SAAS,IAAI,EACrC;CACF;CAEA,eACE,SACA,MACkB;EAClB,IAAI,CAAC,kBAAkB,IAAI,GACzB,OAAO;GAAE,UAAU;GAAM,YAAY,CAAC;EAAE;EAE1C,MAAM,6BAAa,IAAI,IAAY;EAEnC,OAAO;GAAE,UADQ,KAAK,UAAU,SAAS,MAAM,UAC/B;GAAG,YAAY,MAAM,KAAK,UAAU;EAAE;CACxD;CAEA,UACE,SACA,OACA,YACS;EACT,IAAI,OAAO,UAAU,UACnB,OAAO,KAAK,gBAAgB,SAAS,OAAO,UAAU;EAExD,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,KAAK,SAAS,KAAK,UAAU,SAAS,MAAM,UAAU,CAAC;EAEtE,IAAI,UAAU,QAAQ,OAAO,UAAU,UAAU;GAC/C,MAAM,SAAS;GACf,MAAM,OAAgC,CAAC;GACvC,KAAK,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,MAAM,GAC7C,KAAK,OAAO,KAAK,UAAU,SAAS,MAAM,UAAU;GAEtD,OAAO;EACT;EACA,OAAO;CACT;CAEA,gBACE,SACA,OACA,YACQ;EACR,IAAI,MAAM,QAAQ,QAAQ,MAAM,IAC9B,OAAO;EAET,OAAO,MAAM,QACX,4BAA4B,sBAC3B,OAAO,QAAgB;GACtB,MAAM,SAAS,QAAQ,IAAI,GAAG;GAC9B,IAAI,UAAU,MAAM;IAClB,WAAW,IAAI,GAAG;IAClB,OAAO;GACT;GACA,OAAO;EACT,CACF;CACF;CAEA,kBAA0B,QAA8B;EACtD,IAAI,OAAO,aAAa,KAAK,cAC3B;EAEF,KAAK,MAAM,OAAO,OAAO,QAAQ,KAAK,GAAG;GACvC,IAAI,OAAO,aAAa,KAAK,cAC3B;GAEF,MAAM,QAAQ,OAAO,QAAQ,IAAI,GAAG;GACpC,IAAI,SAAS,MACX;GAEF,OAAO,aAAa,MAAM;GAC1B,OAAO,QAAQ,OAAO,GAAG;EAC3B;CACF;AACF;;;;;;AAOA,SAAS,kBAAkB,OAAyB;CAClD,IAAI,OAAO,UAAU,UACnB,OAAO,MAAM,QAAQ,QAAQ,MAAM;CAErC,IAAI,MAAM,QAAQ,KAAK,GAAG;EACxB,KAAK,MAAM,QAAQ,OACjB,IAAI,kBAAkB,IAAI,GACxB,OAAO;EAGX,OAAO;CACT;CACA,IAAI,UAAU,QAAQ,OAAO,UAAU,UAAU;EAC/C,KAAK,MAAM,QAAQ,OAAO,OAAO,KAAgC,GAC/D,IAAI,kBAAkB,IAAI,GACxB,OAAO;EAGX,OAAO;CACT;CACA,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,gCACd,SACA,KACA,aAAuB,CAAC,GAChB;CACR,MAAM,YAAY,OAAO;CACzB,MAAM,gBAAgB,WAAW,SAAS;CAC1C,IAAI,CAAC,aAAa,CAAC,eACjB,OAAO;CAGT,IADgB,QAAQ,UACd,CAAC,CAAC,WAAW,GAAG,GAAG;EAC3B,MAAM,YAAY,2BAA2B,SAAS,KAAK,UAAU;EACrE,IAAI,aAAa,MACf,OAAO;CAEX;CAKA,OAAO,GAJQ,YAAY,GAAG,qBAAqB,GAAI,EAAE,MAAM,KAI5C,UAHH,gBACZ,uBAAuB,WAAW,KAAK,IAAI,EAAE,KAC7C;AAEN;AAEA,SAAS,2BACP,SACA,KACA,YACe;CACf,IAAI;CACJ,IAAI;EACF,SAAS,KAAK,MAAM,OAAO;CAC7B,QAAQ;EACN,OAAO;CACT;CAEA,IAAI,WAAW,QAAQ,OAAO,WAAW,YAAY,MAAM,QAAQ,MAAM,GACvE,OAAO;CAGT,MAAM,MAAM;CACZ,MAAM,eAAe,OAAO;CAC5B,MAAM,sBAAsB,WAAW,SAAS;;;;;;;;;;CAWhD,IACE,gBAAA,UACuB,OACvB,IAAA,YAA6B,OAC7B,IAAA,WAA4B,MAE5B,OAAO;CAET,IACE,uBAAA,sBAC8B,OAC9B,IAAA,uBAAmC,QACnC,CAAC,mBAAmB,IAAA,qBAAiC,UAAU,GAE/D,OAAO;;;;;;;;;CAWT,MAAM,2BAAW,IAAI,IAAY;CACjC,IAAI,cAAc,SAAS,IAAI,mBAAmB;CAClD,IAAI,qBAAqB,SAAS,IAAI,0BAA0B;CAChE,MAAM,OAAgC,CAAC;CACvC,KAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,GAAG,GACrC,IAAI,CAAC,SAAS,IAAI,CAAC,GACjB,KAAK,KAAK;CAGd,MAAM,WAAoC,CAAC;CAC3C,IAAI,cACF,SAAS,uBAAuB;CAElC,IAAI,qBACF,SAAS,8BAA8B;CAEzC,OAAO,OAAO,UAAU,IAAI;CAG5B,OADe,WAAW,KAAK,OACnB,IAAI,KAAK,UAAU,UAAU,MAAM,CAAC,IAAI,KAAK,UAAU,QAAQ;AAC7E;AAEA,SAAS,mBAAmB,GAAY,GAA+B;CACrE,IAAI,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,QACtC,OAAO;CAET,KAAK,IAAI,IAAI,GAAG,IAAI,EAAE,QAAQ,KAC5B,IAAI,EAAE,OAAO,EAAE,IACb,OAAO;CAGX,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,uBACd,UACA,UACA,OACe;CACf,IAAI,YAAY,MAAM,OAAO;;;;;;CAO7B,IAAI;CACJ,KAAK,IAAI,IAAI,GAAG,IAAI,SAAS,QAAQ,KAAK;EACxC,MAAM,IAAI,SAAS;EACnB,IAAI,EAAE,SAAS,MAAM,QAAQ;;;;;;;;;;;EAW7B,MAAM,UAAU,EAAE;EAClB,IAAI,WAAW,QAAQ,OAAO,YAAY,UAAU;EACpD,MAAM,OAAO;EACb,MAAM,YAAY,aAAa;EAC/B,MAAM,cAAc,eAAe;EACnC,MAAM,qBAAqB,qBAAqB;EAChD,IAAI,CAAC,aAAa,CAAC,eAAe,CAAC,oBAAoB;EACvD,IAAI,4BAA4B,CAAC,GAAG;GAClC,QAAQ,SAAS,MAAM;GACvB,IAAI,KAAK,4BAA4B,GAAkB,EAAE,OAAO;GAChE;EACF;EAEA,MAAM,SAAS,WAAW,IAAI;EAC9B,MAAM,aAAa,mBAAmB,IAAI;;;;;;;;;EAU1C,MAAM,cAAc,aAAa,IAAI,KAAK;EAC1C,MAAM,UACJ,UAAU,QAAQ,SAAS,IAAI,aAAa,MAAM,IAAI,SAAS,KAAA;EACjE,MAAM,YAAY,WAAW,QAAQ,WAAW,SAAS;EAEzD,MAAM,KAAK;EACX,IAAI,cAAsC,GAAG;EAE7C,IAAI,aAAa,OAAO,GAAG,YAAY,UACrC,cAAc,gCACZ,GAAG,SACH,SACA,UACF;OACK,IAAI,aAAa,MAAM,QAAQ,GAAG,OAAO,GAAG;;;;;;;;;;;;;;;;;GAiBjD,MAAM,eAAsD,CAAC;GAC7D,IAAI,WAAW,MACb,aAAa,KAAK;IAChB,MAAM;IACN,MAAM,qBAAqB,OAAO;GACpC,CAAC;GAEH,IAAI,WAAW,SAAS,GACtB,aAAa,KAAK;IAChB,MAAM;IACN,MAAM,qBAAqB,WAAW,KAAK,IAAI,EAAE;GACnD,CAAC;GAEH,IAAI,aAAa,SAAS,GACxB,cAAc,CACZ,GAAG,cACH,GAAG,GAAG,OACR;EAEJ;;;;;;;EAQA,QAAQ,SAAS,MAAM;EACvB,IAAI,KAAK,4BAA4B,IAAI,WAAW;CACtD;CAEA,OAAO,OAAO;AAChB;;;;;;AAOA,SAAS,WACP,MACoB;CACpB,MAAM,IAAI,MAAM;CAChB,OAAO,OAAO,MAAM,WAAW,IAAI,KAAA;AACrC;;;;;;;AAQA,SAAS,aACP,MACoB;CACpB,MAAM,IAAI,MAAM;CAChB,OAAO,OAAO,MAAM,WAAW,IAAI,KAAA;AACrC;;;;;;;;AASA,SAAS,mBACP,MACU;CACV,MAAM,IAAI,MAAM;CAChB,IAAI,CAAC,MAAM,QAAQ,CAAC,GAAG,OAAO,CAAC;CAC/B,MAAM,MAAgB,CAAC;CACvB,KAAK,MAAM,QAAQ,GACjB,IAAI,OAAO,SAAS,UAAU,IAAI,KAAK,IAAI;CAE7C,OAAO;AACT;;;;;;;;;;;;;;AAeA,SAAS,4BACP,IACA,SACa;CACb,OAAO,IAAI,YAAY;EACrB,IAAI,GAAG;EACP,MAAM,GAAG;EACT,QAAQ,GAAG;EACX,UAAU,GAAG;EACb,cAAc,GAAG;EACjB,mBAAmB,GAAG;EACtB,mBAAmB,0BAA0B,GAAG,iBAAiB;EACjE;CACF,CAAC;AACH;;;;;;;;AASA,SAAS,0BACP,QACqC;CACrC,IAAI,UAAU,MAAM,OAAO,KAAA;CAC3B,IACE,EAAE,aAAa,WACf,EAAE,eAAe,WACjB,EAAE,qBAAqB,SAEvB,OAAO;CAET,MAAM,EAAE,SAAS,WAAW,iBAAiB,GAAG,SAAS;CAWzD,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,WAAW,IAAI,KAAA,IAAY;AACtD"}
+{"version":3,"file":"toolOutputReferences.mjs","names":[],"sources":["../../../src/tools/toolOutputReferences.ts"],"sourcesContent":["/**\n * Tool output reference registry.\n *\n * When enabled via `RunConfig.toolOutputReferences.enabled`, ToolNode\n * stores each successful tool output under a stable key\n * (`tool<idx>turn<turn>`) where `idx` is the tool's position within a\n * ToolNode batch and `turn` is the batch index within the run\n * (incremented once per ToolNode invocation).\n *\n * Subsequent tool calls can pipe a previous output into their args by\n * embedding `{{tool<idx>turn<turn>}}` inside any string argument;\n * {@link ToolOutputReferenceRegistry.resolve} walks the args and\n * substitutes the placeholders immediately before invocation.\n *\n * The registry stores the *raw, untruncated* tool output so a later\n * `{{…}}` substitution pipes the full payload into the next tool —\n * even when the LLM only saw a head+tail-truncated preview in\n * `ToolMessage.content`. Outputs are stored without any annotation\n * (the `_ref` key or the `[ref: ...]` prefix seen by the LLM is\n * strictly a UX signal attached to `ToolMessage.content`). Keeping the\n * registry pristine means downstream bash/jq piping receives the\n * complete, verbatim output with no injected fields.\n */\n\nimport { ToolMessage } from '@langchain/core/messages';\nimport type { BaseMessage } from '@langchain/core/messages';\nimport {\n  calculateMaxTotalToolOutputSize,\n  HARD_MAX_TOOL_RESULT_CHARS,\n  HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE,\n} from '@/utils/truncation';\nimport { isComputerCallOutputMessage } from '@/utils/toolContent';\nimport { INTENT_ARG } from '@/tools/intentArg';\n\n/** Parses a stringified JSON object arg; undefined for anything else. */\nfunction parseStringifiedArgsObject(\n  value: string\n): Record<string, unknown> | undefined {\n  if (!value.trim().startsWith('{')) {\n    return undefined;\n  }\n  try {\n    const parsed = JSON.parse(value) as unknown;\n    if (parsed != null && typeof parsed === 'object' && !Array.isArray(parsed)) {\n      return parsed as Record<string, unknown>;\n    }\n  } catch {\n    return undefined;\n  }\n  return undefined;\n}\n\n/**\n * Non-global matcher for a single `{{tool<i>turn<n>}}` placeholder.\n * Exported for consumers that want to detect references (e.g., syntax\n * highlighting, docs). The stateful `g` variant lives inside the\n * registry so nobody trips on `lastIndex`.\n */\nexport const TOOL_OUTPUT_REF_PATTERN = /\\{\\{(tool\\d+turn\\d+)\\}\\}/;\n\n/** Object key used when a parsed-object output has `_ref` injected. */\nexport const TOOL_OUTPUT_REF_KEY = '_ref';\n\n/**\n * Object key used to carry unresolved reference warnings on a parsed-\n * object output. Using a dedicated field instead of a trailing text\n * line keeps the annotated `ToolMessage.content` parseable as JSON for\n * downstream consumers that rely on the object shape.\n */\nexport const TOOL_OUTPUT_UNRESOLVED_KEY = '_unresolved_refs';\n\n/** Single-line prefix prepended to non-object tool outputs so the LLM sees the reference key. */\nexport function buildReferencePrefix(key: string): string {\n  return `[ref: ${key}]`;\n}\n\n/** Stable registry key for a tool output. */\nexport function buildReferenceKey(toolIndex: number, turn: number): string {\n  return `tool${toolIndex}turn${turn}`;\n}\n\nexport type ToolOutputReferenceRegistryOptions = {\n  /** Maximum characters stored per registered output. */\n  maxOutputSize?: number;\n  /** Maximum total characters retained across all registered outputs. */\n  maxTotalSize?: number;\n  /**\n   * Upper bound on the number of concurrently-tracked runs. When\n   * exceeded, the oldest run bucket is evicted (FIFO). Defaults to 32.\n   */\n  maxActiveRuns?: number;\n};\n\n/**\n * Result of resolving placeholders in tool args.\n */\nexport type ResolveResult<T> = {\n  /** Arguments with placeholders replaced. Same shape as the input. */\n  resolved: T;\n  /** Reference keys that were referenced but had no stored value. */\n  unresolved: string[];\n};\n\n/**\n * Read-only view over a frozen registry snapshot. Returned by\n * {@link ToolOutputReferenceRegistry.snapshot} for callers that need\n * to resolve placeholders against the registry state at a specific\n * point in time, ignoring any subsequent registrations.\n */\nexport interface ToolOutputResolveView {\n  resolve<T>(args: T, options?: ResolveOptions): ResolveResult<T>;\n}\n\n/**\n * Per-call resolution options. `substituteIntentKey` opts the top-level\n * `intent` key back INTO placeholder substitution: the exemption protects\n * the injected display label, but a tool whose own schema declares a\n * business parameter named `intent` (the injectors skip such tools) still\n * needs references piped into it like any other argument.\n */\nexport type ResolveOptions = {\n  substituteIntentKey?: boolean;\n};\n\n/**\n * Pre-resolved arg map keyed by `toolCallId`. Used by the mixed\n * direct+event dispatch path to feed event calls' resolved args\n * (captured pre-batch) into the dispatcher without re-resolving\n * against the now-stale live registry.\n */\nexport type PreResolvedArgsMap = Map<\n  string,\n  { resolved: Record<string, unknown>; unresolved: string[] }\n>;\n\n/**\n * Per-call sink for resolved args, keyed by `toolCallId`. Threaded\n * as a per-batch local map so concurrent `ToolNode.run()` calls do\n * not race on shared sink state.\n */\nexport type ResolvedArgsByCallId = Map<string, Record<string, unknown>>;\n\nconst EMPTY_ENTRIES: ReadonlyMap<string, string> = new Map<string, string>();\n\n/**\n * Per-run state bucket held inside the registry. Each distinct\n * `run_id` gets its own bucket so overlapping concurrent runs on a\n * shared registry cannot leak outputs, turn counters, or warn-memos\n * into one another.\n */\nclass RunStateBucket {\n  entries: Map<string, string> = new Map();\n  totalSize: number = 0;\n  turnCounter: number = 0;\n  warnedNonStringTools: Set<string> = new Set();\n}\n\n/**\n * Anonymous (`run_id` absent) bucket key. Anonymous batches are\n * treated as fresh runs on every invocation — see `nextTurn`.\n */\nconst ANON_RUN_KEY = '\\0anon';\n\n/**\n * Default upper bound on the number of concurrently-tracked runs per\n * registry. When exceeded, the oldest run's bucket (by insertion\n * order) is evicted. Keeps memory bounded when a ToolNode is reused\n * across many runs without explicit `releaseRun` calls.\n */\nconst DEFAULT_MAX_ACTIVE_RUNS = 32;\n\n/**\n * Ordered map of reference-key → stored output, partitioned by run so\n * concurrent / interleaved runs sharing one registry cannot leak\n * outputs between each other.\n *\n * Each public method takes a `runId` which selects the run's bucket.\n * Hosts typically get one registry per run via `Graph`, in which\n * case only a single bucket is ever populated; the partitioning\n * exists so the registry also behaves correctly when a single\n * instance is reused directly.\n */\nexport class ToolOutputReferenceRegistry {\n  private runStates: Map<string, RunStateBucket> = new Map();\n  private readonly maxOutputSize: number;\n  private readonly maxTotalSize: number;\n  private readonly maxActiveRuns: number;\n  /**\n   * Local stateful matcher used only by `replaceInString`. Kept\n   * off-module so callers of the exported `TOOL_OUTPUT_REF_PATTERN`\n   * never see a stale `lastIndex`.\n   */\n  private static readonly PLACEHOLDER_MATCHER = /\\{\\{(tool\\d+turn\\d+)\\}\\}/g;\n\n  constructor(options: ToolOutputReferenceRegistryOptions = {}) {\n    /**\n     * Per-output default is the same ~400 KB budget as the standard\n     * tool-result truncation (`HARD_MAX_TOOL_RESULT_CHARS`). This\n     * keeps a single `{{…}}` substitution at a size that is safe to\n     * pass through typical shell `ARG_MAX` limits and matches what\n     * the LLM would otherwise have seen. Hosts that want larger per-\n     * output payloads (API consumers, long JSON streams) can raise\n     * the cap explicitly up to the 5 MB total budget.\n     */\n    const perOutput =\n      options.maxOutputSize != null && options.maxOutputSize > 0\n        ? options.maxOutputSize\n        : HARD_MAX_TOOL_RESULT_CHARS;\n    /**\n     * Clamp a caller-supplied `maxTotalSize` to\n     * `HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE` (5 MB) so the documented\n     * absolute cap is enforced regardless of host config —\n     * `calculateMaxTotalToolOutputSize` already applies the same\n     * upper bound on its computed default, but the user-provided\n     * branch was bypassing it.\n     */\n    const totalRaw =\n      options.maxTotalSize != null && options.maxTotalSize > 0\n        ? Math.min(options.maxTotalSize, HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE)\n        : calculateMaxTotalToolOutputSize(perOutput);\n    this.maxTotalSize = totalRaw;\n    /**\n     * The per-output cap can never exceed the per-run aggregate cap:\n     * if a single entry were allowed to be larger than `maxTotalSize`,\n     * the eviction loop would either blow the cap (to keep the entry)\n     * or self-evict a just-stored value. Clamping here turns\n     * `maxTotalSize` into a hard upper bound on *any* state the\n     * registry retains per run.\n     */\n    this.maxOutputSize = Math.min(perOutput, totalRaw);\n    this.maxActiveRuns =\n      options.maxActiveRuns != null && options.maxActiveRuns > 0\n        ? options.maxActiveRuns\n        : DEFAULT_MAX_ACTIVE_RUNS;\n  }\n\n  private keyFor(runId: string | undefined): string {\n    return runId ?? ANON_RUN_KEY;\n  }\n\n  private getOrCreate(runId: string | undefined): RunStateBucket {\n    const key = this.keyFor(runId);\n    let state = this.runStates.get(key);\n    if (state == null) {\n      state = new RunStateBucket();\n      this.runStates.set(key, state);\n      if (this.runStates.size > this.maxActiveRuns) {\n        const oldest = this.runStates.keys().next().value;\n        if (oldest != null && oldest !== key) {\n          this.runStates.delete(oldest);\n        }\n      }\n    }\n    return state;\n  }\n\n  /** Registers (or replaces) the output stored under `key` for `runId`. */\n  set(runId: string | undefined, key: string, value: string): void {\n    const bucket = this.getOrCreate(runId);\n    const clipped =\n      value.length > this.maxOutputSize\n        ? value.slice(0, this.maxOutputSize)\n        : value;\n    const existing = bucket.entries.get(key);\n    if (existing != null) {\n      bucket.totalSize -= existing.length;\n      bucket.entries.delete(key);\n    }\n    bucket.entries.set(key, clipped);\n    bucket.totalSize += clipped.length;\n    this.evictWithinBucket(bucket);\n  }\n\n  /** Returns the stored value for `key` in `runId`'s bucket, or `undefined`. */\n  get(runId: string | undefined, key: string): string | undefined {\n    return this.runStates.get(this.keyFor(runId))?.entries.get(key);\n  }\n\n  /**\n   * Returns `true` when `key` is currently stored in `runId`'s bucket.\n   * Used by {@link annotateMessagesForLLM} to gate transient annotation\n   * on whether the registry still owns the referenced output (a stale\n   * `_refKey` from a prior run silently no-ops here).\n   */\n  has(runId: string | undefined, key: string): boolean {\n    return this.runStates.get(this.keyFor(runId))?.entries.has(key) ?? false;\n  }\n\n  /** Total number of registered outputs across every run bucket. */\n  get size(): number {\n    let n = 0;\n    for (const bucket of this.runStates.values()) {\n      n += bucket.entries.size;\n    }\n    return n;\n  }\n\n  /** Maximum characters retained per output (post-clip). */\n  get perOutputLimit(): number {\n    return this.maxOutputSize;\n  }\n\n  /** Maximum total characters retained *per run*. */\n  get totalLimit(): number {\n    return this.maxTotalSize;\n  }\n\n  /** Drops every run's state. */\n  clear(): void {\n    this.runStates.clear();\n  }\n\n  /**\n   * Explicitly release `runId`'s state. Safe to call when a run has\n   * finished. Hosts sharing one registry across runs should call this\n   * to reclaim memory deterministically; otherwise LRU eviction kicks\n   * in when `maxActiveRuns` runs accumulate.\n   */\n  releaseRun(runId: string | undefined): void {\n    this.runStates.delete(this.keyFor(runId));\n  }\n\n  /**\n   * Claims the next batch turn synchronously from `runId`'s bucket.\n   *\n   * Must be called once at the start of each ToolNode batch before\n   * any `await`, so concurrent invocations within the same run see\n   * distinct turn values (reads are effectively atomic by JS's\n   * single-threaded execution of the sync prefix).\n   *\n   * If `runId` is missing the anonymous bucket is dropped and a\n   * fresh one created so each anonymous call behaves as its own run.\n   */\n  nextTurn(runId: string | undefined): number {\n    if (runId == null) {\n      this.runStates.delete(ANON_RUN_KEY);\n    }\n    const bucket = this.getOrCreate(runId);\n    return bucket.turnCounter++;\n  }\n\n  /**\n   * Records that `toolName` has been warned about in `runId` (returns\n   * `true` on the first call per run, `false` after). Used by\n   * ToolNode to emit one log line per offending tool per run when a\n   * `ToolMessage.content` isn't a string.\n   */\n  claimWarnOnce(runId: string | undefined, toolName: string): boolean {\n    const bucket = this.getOrCreate(runId);\n    if (bucket.warnedNonStringTools.has(toolName)) {\n      return false;\n    }\n    bucket.warnedNonStringTools.add(toolName);\n    return true;\n  }\n\n  /**\n   * Walks `args` and replaces every `{{tool<i>turn<n>}}` placeholder in\n   * string values with the stored output *from `runId`'s bucket*. Non-\n   * string values and object keys are left untouched. Unresolved\n   * references are left in-place and reported so the caller can\n   * surface them to the LLM. When no placeholder appears anywhere in\n   * the serialized args, the original input is returned without\n   * walking the tree.\n   */\n  resolve<T>(\n    runId: string | undefined,\n    args: T,\n    options?: ResolveOptions\n  ): ResolveResult<T> {\n    if (!hasAnyPlaceholder(args)) {\n      return { resolved: args, unresolved: [] };\n    }\n    const bucket = this.runStates.get(this.keyFor(runId));\n    return this.resolveAgainst(bucket?.entries ?? EMPTY_ENTRIES, args, options);\n  }\n\n  /**\n   * Captures a frozen snapshot of `runId`'s current entries and\n   * returns a view that resolves placeholders against *only* that\n   * snapshot. The snapshot is decoupled from the live registry, so\n   * subsequent `set()` calls (for example, same-turn direct outputs\n   * registering while an event branch is still in flight) are\n   * invisible to the snapshot's `resolve`. Used by the mixed\n   * direct+event dispatch path to preserve same-turn isolation when\n   * a `PreToolUse` hook rewrites event args after directs have\n   * completed.\n   */\n  snapshot(runId: string | undefined): ToolOutputResolveView {\n    const bucket = this.runStates.get(this.keyFor(runId));\n    const entries: ReadonlyMap<string, string> = bucket\n      ? new Map(bucket.entries)\n      : EMPTY_ENTRIES;\n    return {\n      resolve: <T>(args: T, options?: ResolveOptions): ResolveResult<T> =>\n        this.resolveAgainst(entries, args, options),\n    };\n  }\n\n  private resolveAgainst<T>(\n    entries: ReadonlyMap<string, string>,\n    args: T,\n    options?: ResolveOptions\n  ): ResolveResult<T> {\n    if (!hasAnyPlaceholder(args)) {\n      return { resolved: args, unresolved: [] };\n    }\n    const exemptIntentKey = options?.substituteIntentKey !== true;\n    const unresolved = new Set<string>();\n    /**\n     * Providers may deliver the args OBJECT as a JSON string. A plain\n     * string-root transform would expand placeholders inside the `intent`\n     * label too, bypassing the top-level exclusion below — parse, transform\n     * key-aware, and re-serialize so the label stays verbatim while every\n     * other field still substitutes. Only taken when an `intent` key is\n     * actually present; other strings keep the fast raw-string path.\n     */\n    if (exemptIntentKey && typeof args === 'string') {\n      const parsedRoot = parseStringifiedArgsObject(args);\n      if (parsedRoot != null && INTENT_ARG in parsedRoot) {\n        const resolved = JSON.stringify(\n          this.transform(entries, parsedRoot, unresolved, true)\n        ) as T;\n        return { resolved, unresolved: Array.from(unresolved) };\n      }\n    }\n    const resolved = this.transform(\n      entries,\n      args,\n      unresolved,\n      exemptIntentKey\n    ) as T;\n    return { resolved, unresolved: Array.from(unresolved) };\n  }\n\n  private transform(\n    entries: ReadonlyMap<string, string>,\n    value: unknown,\n    unresolved: Set<string>,\n    exemptRootIntent = false\n  ): unknown {\n    if (typeof value === 'string') {\n      return this.replaceInString(entries, value, unresolved);\n    }\n    if (Array.isArray(value)) {\n      return value.map((item) => this.transform(entries, item, unresolved));\n    }\n    if (value !== null && typeof value === 'object') {\n      const source = value as Record<string, unknown>;\n      const next: Record<string, unknown> = {};\n      for (const [key, item] of Object.entries(source)) {\n        /**\n         * The top-level `intent` arg is a display label, never a data\n         * channel: expanding a `{{tool<i>turn<n>}}` placeholder there would\n         * dump a stored output (up to the registry cap) into a single-line\n         * UI label and persist it with the message. Left verbatim instead.\n         */\n        next[key] =\n          exemptRootIntent && key === INTENT_ARG\n            ? item\n            : this.transform(entries, item, unresolved);\n      }\n      return next;\n    }\n    return value;\n  }\n\n  private replaceInString(\n    entries: ReadonlyMap<string, string>,\n    input: string,\n    unresolved: Set<string>\n  ): string {\n    if (input.indexOf('{{tool') === -1) {\n      return input;\n    }\n    return input.replace(\n      ToolOutputReferenceRegistry.PLACEHOLDER_MATCHER,\n      (match, key: string) => {\n        const stored = entries.get(key);\n        if (stored == null) {\n          unresolved.add(key);\n          return match;\n        }\n        return stored;\n      }\n    );\n  }\n\n  private evictWithinBucket(bucket: RunStateBucket): void {\n    if (bucket.totalSize <= this.maxTotalSize) {\n      return;\n    }\n    for (const key of bucket.entries.keys()) {\n      if (bucket.totalSize <= this.maxTotalSize) {\n        return;\n      }\n      const entry = bucket.entries.get(key);\n      if (entry == null) {\n        continue;\n      }\n      bucket.totalSize -= entry.length;\n      bucket.entries.delete(key);\n    }\n  }\n}\n\n/**\n * Cheap pre-check: returns true if any string value in `args` contains\n * the `{{tool` substring. Lets `resolve()` skip the deep tree walk (and\n * its object allocations) for the common case of plain args.\n */\nfunction hasAnyPlaceholder(value: unknown): boolean {\n  if (typeof value === 'string') {\n    return value.indexOf('{{tool') !== -1;\n  }\n  if (Array.isArray(value)) {\n    for (const item of value) {\n      if (hasAnyPlaceholder(item)) {\n        return true;\n      }\n    }\n    return false;\n  }\n  if (value !== null && typeof value === 'object') {\n    for (const item of Object.values(value as Record<string, unknown>)) {\n      if (hasAnyPlaceholder(item)) {\n        return true;\n      }\n    }\n    return false;\n  }\n  return false;\n}\n\n/**\n * Annotates `content` with a reference key and/or unresolved-ref\n * warnings so the LLM sees both alongside the tool output.\n *\n * Behavior:\n *  - If `content` parses as a plain (non-array, non-null) JSON object\n *    and the object does not already have a conflicting `_ref` key,\n *    the reference key and (when present) `_unresolved_refs` array\n *    are injected as object fields, preserving JSON validity for\n *    downstream consumers that parse the output.\n *  - Otherwise (string output, JSON array/primitive, parse failure,\n *    or `_ref` collision), a `[ref: <key>]\\n` prefix line is\n *    prepended and unresolved refs are appended as a trailing\n *    `[unresolved refs: …]` line.\n *\n * The annotated string is what the LLM sees as `ToolMessage.content`.\n * The *original* (un-annotated) value is what gets stored in the\n * registry, so downstream piping remains pristine.\n *\n * @param content     Raw (post-truncation) tool output.\n * @param key         Reference key for this output, or undefined when\n *                    there is nothing to register (errors etc.).\n * @param unresolved  Reference keys that failed to resolve during\n *                    argument substitution. Surfaced so the LLM can\n *                    self-correct its next tool call.\n */\nexport function annotateToolOutputWithReference(\n  content: string,\n  key: string | undefined,\n  unresolved: string[] = []\n): string {\n  const hasRefKey = key != null;\n  const hasUnresolved = unresolved.length > 0;\n  if (!hasRefKey && !hasUnresolved) {\n    return content;\n  }\n  const trimmed = content.trimStart();\n  if (trimmed.startsWith('{')) {\n    const annotated = tryInjectRefIntoJsonObject(content, key, unresolved);\n    if (annotated != null) {\n      return annotated;\n    }\n  }\n  const prefix = hasRefKey ? `${buildReferencePrefix(key!)}\\n` : '';\n  const trailer = hasUnresolved\n    ? `\\n[unresolved refs: ${unresolved.join(', ')}]`\n    : '';\n  return `${prefix}${content}${trailer}`;\n}\n\nfunction tryInjectRefIntoJsonObject(\n  content: string,\n  key: string | undefined,\n  unresolved: string[]\n): string | null {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(content);\n  } catch {\n    return null;\n  }\n\n  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {\n    return null;\n  }\n\n  const obj = parsed as Record<string, unknown>;\n  const injectingRef = key != null;\n  const injectingUnresolved = unresolved.length > 0;\n\n  /**\n   * Reject the JSON-injection path (fall back to prefix form) when\n   * either of our keys collides with real payload data:\n   *  - `_ref` collision: existing value is non-null and differs from\n   *    the key we're about to inject.\n   *  - `_unresolved_refs` collision: existing value is non-null and\n   *    is not a deep-equal match for the array we'd inject.\n   * This keeps us from silently overwriting legitimate tool output.\n   */\n  if (\n    injectingRef &&\n    TOOL_OUTPUT_REF_KEY in obj &&\n    obj[TOOL_OUTPUT_REF_KEY] !== key &&\n    obj[TOOL_OUTPUT_REF_KEY] != null\n  ) {\n    return null;\n  }\n  if (\n    injectingUnresolved &&\n    TOOL_OUTPUT_UNRESOLVED_KEY in obj &&\n    obj[TOOL_OUTPUT_UNRESOLVED_KEY] != null &&\n    !arraysShallowEqual(obj[TOOL_OUTPUT_UNRESOLVED_KEY], unresolved)\n  ) {\n    return null;\n  }\n\n  /**\n   * Only strip the framework-owned key we're actually injecting —\n   * leave everything else (including a pre-existing `_ref` on the\n   * unresolved-only path, or a pre-existing `_unresolved_refs` on a\n   * plain-annotation path) untouched so we annotate rather than\n   * mutate downstream payload data. Our injected keys land first in\n   * the serialized JSON so the LLM sees them before the body.\n   */\n  const omitKeys = new Set<string>();\n  if (injectingRef) omitKeys.add(TOOL_OUTPUT_REF_KEY);\n  if (injectingUnresolved) omitKeys.add(TOOL_OUTPUT_UNRESOLVED_KEY);\n  const rest: Record<string, unknown> = {};\n  for (const [k, v] of Object.entries(obj)) {\n    if (!omitKeys.has(k)) {\n      rest[k] = v;\n    }\n  }\n  const injected: Record<string, unknown> = {};\n  if (injectingRef) {\n    injected[TOOL_OUTPUT_REF_KEY] = key;\n  }\n  if (injectingUnresolved) {\n    injected[TOOL_OUTPUT_UNRESOLVED_KEY] = unresolved;\n  }\n  Object.assign(injected, rest);\n\n  const pretty = /^\\{\\s*\\n/.test(content);\n  return pretty ? JSON.stringify(injected, null, 2) : JSON.stringify(injected);\n}\n\nfunction arraysShallowEqual(a: unknown, b: readonly string[]): boolean {\n  if (!Array.isArray(a) || a.length !== b.length) {\n    return false;\n  }\n  for (let i = 0; i < a.length; i++) {\n    if (a[i] !== b[i]) {\n      return false;\n    }\n  }\n  return true;\n}\n\n/**\n * Lazy projection that, given a registry and a runId, returns a new\n * `messages` array where each `ToolMessage` carrying ref metadata is\n * projected into a transient copy with annotated content (when the ref\n * is live in the registry) and with the framework-owned `additional_\n * kwargs` keys (`_refKey`, `_refScope`, `_unresolvedRefs`) stripped\n * regardless of whether annotation applied. The original input array\n * and its messages are never mutated.\n *\n * Annotation is gated on registry presence: a stale `_refKey` from a\n * prior run (e.g. one that survived in persisted history) silently\n * no-ops on the *content* side. The strip-metadata side still runs so\n * stale framework keys never leak onto the wire under any custom or\n * future provider serializer that might transmit `additional_kwargs`.\n * `_unresolvedRefs` is always meaningful and is not gated.\n *\n * **Feature-disabled fast path:** when the host hasn't enabled the\n * tool-output-reference feature, the registry is `undefined` and this\n * function returns the input array reference-equal *without iterating\n * a single message*. The loop is exclusive to the feature-enabled\n * code path.\n */\nexport function annotateMessagesForLLM(\n  messages: BaseMessage[],\n  registry: ToolOutputReferenceRegistry | undefined,\n  runId: string | undefined\n): BaseMessage[] {\n  if (registry == null) return messages;\n\n  /**\n   * Lazy-allocate the output array so the common case (no ToolMessage\n   * carries framework metadata) returns the input reference-equal with\n   * zero allocations beyond the per-message predicate checks.\n   */\n  let out: BaseMessage[] | undefined;\n  for (let i = 0; i < messages.length; i++) {\n    const m = messages[i];\n    if (m._getType() !== 'tool') continue;\n    /**\n     * `additional_kwargs` is untyped at the LangChain layer\n     * (`Record<string, unknown>`), so persisted or client-supplied\n     * ToolMessages can carry arbitrary shapes — including primitives\n     * (a malformed serializer might write a string, or `null`).\n     * Guard with a runtime object check before the `in` probes\n     * because the `in` operator throws `TypeError` on primitives.\n     * A single malformed message must never crash the provider call\n     * path; skip its annotation/strip and continue.\n     */\n    const rawMeta = m.additional_kwargs as unknown;\n    if (rawMeta == null || typeof rawMeta !== 'object') continue;\n    const meta = rawMeta as Record<string, unknown>;\n    const hasRefKey = '_refKey' in meta;\n    const hasRefScope = '_refScope' in meta;\n    const hasUnresolvedField = '_unresolvedRefs' in meta;\n    if (!hasRefKey && !hasRefScope && !hasUnresolvedField) continue;\n    if (isComputerCallOutputMessage(m)) {\n      out ??= messages.slice();\n      out[i] = cloneToolMessageWithContent(m as ToolMessage, m.content);\n      continue;\n    }\n\n    const refKey = readRefKey(meta);\n    const unresolved = readUnresolvedRefs(meta);\n\n    /**\n     * Prefer the message-stamped `_refScope` for the registry lookup.\n     * For named runs it equals the current `runId`; for anonymous\n     * invocations it carries the per-batch synthetic scope minted by\n     * ToolNode (`\\0anon-<n>`), which `runId` from config cannot\n     * recover. Falling back to `runId` keeps backward compatibility\n     * with messages stamped before this field existed.\n     */\n    const lookupScope = readRefScope(meta) ?? runId;\n    const liveRef =\n      refKey != null && registry.has(lookupScope, refKey) ? refKey : undefined;\n    const annotates = liveRef != null || unresolved.length > 0;\n\n    const tm = m as ToolMessage;\n    let nextContent: ToolMessage['content'] = tm.content;\n\n    if (annotates && typeof tm.content === 'string') {\n      nextContent = annotateToolOutputWithReference(\n        tm.content,\n        liveRef,\n        unresolved\n      );\n    } else if (annotates && Array.isArray(tm.content)) {\n      /**\n       * Array tool content. The string annotator can't run — this notably\n       * includes a tail tool result that prompt caching rewrote from a string\n       * into a text-block array to host its `cache_control` / `cachePoint`\n       * marker (the `_refKey` survives on `additional_kwargs`). Project the\n       * same markers the string path would, as leading text blocks: the live\n       * `[ref: …]` prefix and/or the unresolved-refs warning. Without this the\n       * common tool-result tail loses its reference marker once cached.\n       *\n       * `as unknown as ToolMessage['content']` is unavoidable: LangChain's\n       * content union does not accept a freshly built mixed array literal even\n       * though the structural shape is valid at runtime. The double-cast is\n       * structurally safe — every original block is preserved and only\n       * `{ type: 'text', text }` blocks (which all providers accept) are\n       * prepended.\n       */\n      const prefixBlocks: Array<{ type: 'text'; text: string }> = [];\n      if (liveRef != null) {\n        prefixBlocks.push({\n          type: 'text',\n          text: buildReferencePrefix(liveRef),\n        });\n      }\n      if (unresolved.length > 0) {\n        prefixBlocks.push({\n          type: 'text',\n          text: `[unresolved refs: ${unresolved.join(', ')}]`,\n        });\n      }\n      if (prefixBlocks.length > 0) {\n        nextContent = [\n          ...prefixBlocks,\n          ...tm.content,\n        ] as unknown as ToolMessage['content'];\n      }\n    }\n\n    /**\n     * Project unconditionally: even when no annotation applies (stale\n     * `_refKey` or non-annotatable content), `cloneToolMessageWithContent`\n     * runs `stripFrameworkRefMetadata` on `additional_kwargs` so the\n     * framework-owned keys never reach the wire.\n     */\n    out ??= messages.slice();\n    out[i] = cloneToolMessageWithContent(tm, nextContent);\n  }\n\n  return out ?? messages;\n}\n\n/**\n * Reads `_refKey` defensively from untyped `additional_kwargs`. Returns\n * undefined for non-string values so a malformed field cannot poison\n * the registry lookup or downstream string operations.\n */\nfunction readRefKey(\n  meta: Record<string, unknown> | undefined\n): string | undefined {\n  const v = meta?._refKey;\n  return typeof v === 'string' ? v : undefined;\n}\n\n/**\n * Reads `_refScope` defensively from untyped `additional_kwargs`.\n * Mirrors {@link readRefKey} — non-string scopes are dropped (the\n * caller falls back to the run-derived scope) rather than passed into\n * the registry as a malformed key.\n */\nfunction readRefScope(\n  meta: Record<string, unknown> | undefined\n): string | undefined {\n  const v = meta?._refScope;\n  return typeof v === 'string' ? v : undefined;\n}\n\n/**\n * Reads `_unresolvedRefs` defensively from untyped `additional_kwargs`.\n * Returns an empty array for any non-array value, and filters out\n * non-string entries from a real array. Without this guard, a hydrated\n * ToolMessage carrying e.g. `_unresolvedRefs: 'tool0turn0'` would crash\n * `attemptInvoke` on the eventual `.length` / `.join(...)` call.\n */\nfunction readUnresolvedRefs(\n  meta: Record<string, unknown> | undefined\n): string[] {\n  const v = meta?._unresolvedRefs;\n  if (!Array.isArray(v)) return [];\n  const out: string[] = [];\n  for (const item of v) {\n    if (typeof item === 'string') out.push(item);\n  }\n  return out;\n}\n\n/**\n * Builds a fresh `ToolMessage` that mirrors `tm`'s identity fields with\n * the supplied `content`. Every `ToolMessage` field but `content` is\n * carried over so the projection is structurally identical to the\n * original from a LangChain serializer's perspective.\n *\n * `additional_kwargs` is rebuilt with the framework-owned ref keys\n * stripped. Defensive: LangChain's standard provider serializers do not\n * transmit `additional_kwargs` to provider HTTP APIs, but a custom\n * adapter or future LangChain change could. Stripping keeps the\n * implementation correct under any serializer behavior at the cost of a\n * shallow object spread per annotated message.\n */\nfunction cloneToolMessageWithContent(\n  tm: ToolMessage,\n  content: ToolMessage['content']\n): ToolMessage {\n  return new ToolMessage({\n    id: tm.id,\n    name: tm.name,\n    status: tm.status,\n    artifact: tm.artifact,\n    tool_call_id: tm.tool_call_id,\n    response_metadata: tm.response_metadata,\n    additional_kwargs: stripFrameworkRefMetadata(tm.additional_kwargs),\n    content,\n  });\n}\n\n/**\n * Returns a copy of `kwargs` with `_refKey`, `_refScope`, and\n * `_unresolvedRefs` removed. Returns the input reference-equal when\n * none of those keys are present so the no-strip path stays cheap;\n * returns `undefined` when stripping leaves the object empty so the\n * caller can drop the field entirely.\n */\nfunction stripFrameworkRefMetadata(\n  kwargs: Record<string, unknown> | undefined\n): Record<string, unknown> | undefined {\n  if (kwargs == null) return undefined;\n  if (\n    !('_refKey' in kwargs) &&\n    !('_refScope' in kwargs) &&\n    !('_unresolvedRefs' in kwargs)\n  ) {\n    return kwargs;\n  }\n  const { _refKey, _refScope, _unresolvedRefs, ...rest } = kwargs as Record<\n    string,\n    unknown\n  > & {\n    _refKey?: unknown;\n    _refScope?: unknown;\n    _unresolvedRefs?: unknown;\n  };\n  void _refKey;\n  void _refScope;\n  void _unresolvedRefs;\n  return Object.keys(rest).length === 0 ? undefined : rest;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,SAAS,2BACP,OACqC;CACrC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,WAAW,GAAG,GAC9B;CAEF,IAAI;EACF,MAAM,SAAS,KAAK,MAAM,KAAK;EAC/B,IAAI,UAAU,QAAQ,OAAO,WAAW,YAAY,CAAC,MAAM,QAAQ,MAAM,GACvE,OAAO;CAEX,QAAQ;EACN;CACF;AAEF;;;;;;;AAQA,MAAa,0BAA0B;;AAGvC,MAAa,sBAAsB;;;;;;;AAQnC,MAAa,6BAA6B;;AAG1C,SAAgB,qBAAqB,KAAqB;CACxD,OAAO,SAAS,IAAI;AACtB;;AAGA,SAAgB,kBAAkB,WAAmB,MAAsB;CACzE,OAAO,OAAO,UAAU,MAAM;AAChC;AA+DA,MAAM,gCAA6C,IAAI,IAAoB;;;;;;;AAQ3E,IAAM,iBAAN,MAAqB;CACnB,0BAA+B,IAAI,IAAI;CACvC,YAAoB;CACpB,cAAsB;CACtB,uCAAoC,IAAI,IAAI;AAC9C;;;;;AAMA,MAAM,eAAe;;;;;;;AAQrB,MAAM,0BAA0B;;;;;;;;;;;;AAahC,IAAa,8BAAb,MAAa,4BAA4B;CACvC,4BAAiD,IAAI,IAAI;CACzD;CACA;CACA;;;;;;CAMA,OAAwB,sBAAsB;CAE9C,YAAY,UAA8C,CAAC,GAAG;;;;;;;;;;EAU5D,MAAM,YACJ,QAAQ,iBAAiB,QAAQ,QAAQ,gBAAgB,IACrD,QAAQ,gBACR;;;;;;;;;EASN,MAAM,WACJ,QAAQ,gBAAgB,QAAQ,QAAQ,eAAe,IACnD,KAAK,IAAI,QAAQ,cAAc,+BAA+B,IAC9D,gCAAgC,SAAS;EAC/C,KAAK,eAAe;;;;;;;;;EASpB,KAAK,gBAAgB,KAAK,IAAI,WAAW,QAAQ;EACjD,KAAK,gBACH,QAAQ,iBAAiB,QAAQ,QAAQ,gBAAgB,IACrD,QAAQ,gBACR;CACR;CAEA,OAAe,OAAmC;EAChD,OAAO,SAAS;CAClB;CAEA,YAAoB,OAA2C;EAC7D,MAAM,MAAM,KAAK,OAAO,KAAK;EAC7B,IAAI,QAAQ,KAAK,UAAU,IAAI,GAAG;EAClC,IAAI,SAAS,MAAM;GACjB,QAAQ,IAAI,eAAe;GAC3B,KAAK,UAAU,IAAI,KAAK,KAAK;GAC7B,IAAI,KAAK,UAAU,OAAO,KAAK,eAAe;IAC5C,MAAM,SAAS,KAAK,UAAU,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;IAC5C,IAAI,UAAU,QAAQ,WAAW,KAC/B,KAAK,UAAU,OAAO,MAAM;GAEhC;EACF;EACA,OAAO;CACT;;CAGA,IAAI,OAA2B,KAAa,OAAqB;EAC/D,MAAM,SAAS,KAAK,YAAY,KAAK;EACrC,MAAM,UACJ,MAAM,SAAS,KAAK,gBAChB,MAAM,MAAM,GAAG,KAAK,aAAa,IACjC;EACN,MAAM,WAAW,OAAO,QAAQ,IAAI,GAAG;EACvC,IAAI,YAAY,MAAM;GACpB,OAAO,aAAa,SAAS;GAC7B,OAAO,QAAQ,OAAO,GAAG;EAC3B;EACA,OAAO,QAAQ,IAAI,KAAK,OAAO;EAC/B,OAAO,aAAa,QAAQ;EAC5B,KAAK,kBAAkB,MAAM;CAC/B;;CAGA,IAAI,OAA2B,KAAiC;EAC9D,OAAO,KAAK,UAAU,IAAI,KAAK,OAAO,KAAK,CAAC,CAAC,EAAE,QAAQ,IAAI,GAAG;CAChE;;;;;;;CAQA,IAAI,OAA2B,KAAsB;EACnD,OAAO,KAAK,UAAU,IAAI,KAAK,OAAO,KAAK,CAAC,CAAC,EAAE,QAAQ,IAAI,GAAG,KAAK;CACrE;;CAGA,IAAI,OAAe;EACjB,IAAI,IAAI;EACR,KAAK,MAAM,UAAU,KAAK,UAAU,OAAO,GACzC,KAAK,OAAO,QAAQ;EAEtB,OAAO;CACT;;CAGA,IAAI,iBAAyB;EAC3B,OAAO,KAAK;CACd;;CAGA,IAAI,aAAqB;EACvB,OAAO,KAAK;CACd;;CAGA,QAAc;EACZ,KAAK,UAAU,MAAM;CACvB;;;;;;;CAQA,WAAW,OAAiC;EAC1C,KAAK,UAAU,OAAO,KAAK,OAAO,KAAK,CAAC;CAC1C;;;;;;;;;;;;CAaA,SAAS,OAAmC;EAC1C,IAAI,SAAS,MACX,KAAK,UAAU,OAAO,YAAY;EAEpC,MAAM,SAAS,KAAK,YAAY,KAAK;EACrC,OAAO,OAAO;CAChB;;;;;;;CAQA,cAAc,OAA2B,UAA2B;EAClE,MAAM,SAAS,KAAK,YAAY,KAAK;EACrC,IAAI,OAAO,qBAAqB,IAAI,QAAQ,GAC1C,OAAO;EAET,OAAO,qBAAqB,IAAI,QAAQ;EACxC,OAAO;CACT;;;;;;;;;;CAWA,QACE,OACA,MACA,SACkB;EAClB,IAAI,CAAC,kBAAkB,IAAI,GACzB,OAAO;GAAE,UAAU;GAAM,YAAY,CAAC;EAAE;EAE1C,MAAM,SAAS,KAAK,UAAU,IAAI,KAAK,OAAO,KAAK,CAAC;EACpD,OAAO,KAAK,eAAe,QAAQ,WAAW,eAAe,MAAM,OAAO;CAC5E;;;;;;;;;;;;CAaA,SAAS,OAAkD;EACzD,MAAM,SAAS,KAAK,UAAU,IAAI,KAAK,OAAO,KAAK,CAAC;EACpD,MAAM,UAAuC,SACzC,IAAI,IAAI,OAAO,OAAO,IACtB;EACJ,OAAO,EACL,UAAa,MAAS,YACpB,KAAK,eAAe,SAAS,MAAM,OAAO,EAC9C;CACF;CAEA,eACE,SACA,MACA,SACkB;EAClB,IAAI,CAAC,kBAAkB,IAAI,GACzB,OAAO;GAAE,UAAU;GAAM,YAAY,CAAC;EAAE;EAE1C,MAAM,kBAAkB,SAAS,wBAAwB;EACzD,MAAM,6BAAa,IAAI,IAAY;;;;;;;;;EASnC,IAAI,mBAAmB,OAAO,SAAS,UAAU;GAC/C,MAAM,aAAa,2BAA2B,IAAI;GAClD,IAAI,cAAc,QAAA,YAAsB,YAItC,OAAO;IAAE,UAHQ,KAAK,UACpB,KAAK,UAAU,SAAS,YAAY,YAAY,IAAI,CAEtC;IAAG,YAAY,MAAM,KAAK,UAAU;GAAE;EAE1D;EAOA,OAAO;GAAE,UANQ,KAAK,UACpB,SACA,MACA,YACA,eAEc;GAAG,YAAY,MAAM,KAAK,UAAU;EAAE;CACxD;CAEA,UACE,SACA,OACA,YACA,mBAAmB,OACV;EACT,IAAI,OAAO,UAAU,UACnB,OAAO,KAAK,gBAAgB,SAAS,OAAO,UAAU;EAExD,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,KAAK,SAAS,KAAK,UAAU,SAAS,MAAM,UAAU,CAAC;EAEtE,IAAI,UAAU,QAAQ,OAAO,UAAU,UAAU;GAC/C,MAAM,SAAS;GACf,MAAM,OAAgC,CAAC;GACvC,KAAK,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,MAAM;;;;;;;GAO7C,KAAK,OACH,oBAAoB,QAAA,WAChB,OACA,KAAK,UAAU,SAAS,MAAM,UAAU;GAEhD,OAAO;EACT;EACA,OAAO;CACT;CAEA,gBACE,SACA,OACA,YACQ;EACR,IAAI,MAAM,QAAQ,QAAQ,MAAM,IAC9B,OAAO;EAET,OAAO,MAAM,QACX,4BAA4B,sBAC3B,OAAO,QAAgB;GACtB,MAAM,SAAS,QAAQ,IAAI,GAAG;GAC9B,IAAI,UAAU,MAAM;IAClB,WAAW,IAAI,GAAG;IAClB,OAAO;GACT;GACA,OAAO;EACT,CACF;CACF;CAEA,kBAA0B,QAA8B;EACtD,IAAI,OAAO,aAAa,KAAK,cAC3B;EAEF,KAAK,MAAM,OAAO,OAAO,QAAQ,KAAK,GAAG;GACvC,IAAI,OAAO,aAAa,KAAK,cAC3B;GAEF,MAAM,QAAQ,OAAO,QAAQ,IAAI,GAAG;GACpC,IAAI,SAAS,MACX;GAEF,OAAO,aAAa,MAAM;GAC1B,OAAO,QAAQ,OAAO,GAAG;EAC3B;CACF;AACF;;;;;;AAOA,SAAS,kBAAkB,OAAyB;CAClD,IAAI,OAAO,UAAU,UACnB,OAAO,MAAM,QAAQ,QAAQ,MAAM;CAErC,IAAI,MAAM,QAAQ,KAAK,GAAG;EACxB,KAAK,MAAM,QAAQ,OACjB,IAAI,kBAAkB,IAAI,GACxB,OAAO;EAGX,OAAO;CACT;CACA,IAAI,UAAU,QAAQ,OAAO,UAAU,UAAU;EAC/C,KAAK,MAAM,QAAQ,OAAO,OAAO,KAAgC,GAC/D,IAAI,kBAAkB,IAAI,GACxB,OAAO;EAGX,OAAO;CACT;CACA,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,gCACd,SACA,KACA,aAAuB,CAAC,GAChB;CACR,MAAM,YAAY,OAAO;CACzB,MAAM,gBAAgB,WAAW,SAAS;CAC1C,IAAI,CAAC,aAAa,CAAC,eACjB,OAAO;CAGT,IADgB,QAAQ,UACd,CAAC,CAAC,WAAW,GAAG,GAAG;EAC3B,MAAM,YAAY,2BAA2B,SAAS,KAAK,UAAU;EACrE,IAAI,aAAa,MACf,OAAO;CAEX;CAKA,OAAO,GAJQ,YAAY,GAAG,qBAAqB,GAAI,EAAE,MAAM,KAI5C,UAHH,gBACZ,uBAAuB,WAAW,KAAK,IAAI,EAAE,KAC7C;AAEN;AAEA,SAAS,2BACP,SACA,KACA,YACe;CACf,IAAI;CACJ,IAAI;EACF,SAAS,KAAK,MAAM,OAAO;CAC7B,QAAQ;EACN,OAAO;CACT;CAEA,IAAI,WAAW,QAAQ,OAAO,WAAW,YAAY,MAAM,QAAQ,MAAM,GACvE,OAAO;CAGT,MAAM,MAAM;CACZ,MAAM,eAAe,OAAO;CAC5B,MAAM,sBAAsB,WAAW,SAAS;;;;;;;;;;CAWhD,IACE,gBAAA,UACuB,OACvB,IAAA,YAA6B,OAC7B,IAAA,WAA4B,MAE5B,OAAO;CAET,IACE,uBAAA,sBAC8B,OAC9B,IAAA,uBAAmC,QACnC,CAAC,mBAAmB,IAAA,qBAAiC,UAAU,GAE/D,OAAO;;;;;;;;;CAWT,MAAM,2BAAW,IAAI,IAAY;CACjC,IAAI,cAAc,SAAS,IAAI,mBAAmB;CAClD,IAAI,qBAAqB,SAAS,IAAI,0BAA0B;CAChE,MAAM,OAAgC,CAAC;CACvC,KAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,GAAG,GACrC,IAAI,CAAC,SAAS,IAAI,CAAC,GACjB,KAAK,KAAK;CAGd,MAAM,WAAoC,CAAC;CAC3C,IAAI,cACF,SAAS,uBAAuB;CAElC,IAAI,qBACF,SAAS,8BAA8B;CAEzC,OAAO,OAAO,UAAU,IAAI;CAG5B,OADe,WAAW,KAAK,OACnB,IAAI,KAAK,UAAU,UAAU,MAAM,CAAC,IAAI,KAAK,UAAU,QAAQ;AAC7E;AAEA,SAAS,mBAAmB,GAAY,GAA+B;CACrE,IAAI,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,QACtC,OAAO;CAET,KAAK,IAAI,IAAI,GAAG,IAAI,EAAE,QAAQ,KAC5B,IAAI,EAAE,OAAO,EAAE,IACb,OAAO;CAGX,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,uBACd,UACA,UACA,OACe;CACf,IAAI,YAAY,MAAM,OAAO;;;;;;CAO7B,IAAI;CACJ,KAAK,IAAI,IAAI,GAAG,IAAI,SAAS,QAAQ,KAAK;EACxC,MAAM,IAAI,SAAS;EACnB,IAAI,EAAE,SAAS,MAAM,QAAQ;;;;;;;;;;;EAW7B,MAAM,UAAU,EAAE;EAClB,IAAI,WAAW,QAAQ,OAAO,YAAY,UAAU;EACpD,MAAM,OAAO;EACb,MAAM,YAAY,aAAa;EAC/B,MAAM,cAAc,eAAe;EACnC,MAAM,qBAAqB,qBAAqB;EAChD,IAAI,CAAC,aAAa,CAAC,eAAe,CAAC,oBAAoB;EACvD,IAAI,4BAA4B,CAAC,GAAG;GAClC,QAAQ,SAAS,MAAM;GACvB,IAAI,KAAK,4BAA4B,GAAkB,EAAE,OAAO;GAChE;EACF;EAEA,MAAM,SAAS,WAAW,IAAI;EAC9B,MAAM,aAAa,mBAAmB,IAAI;;;;;;;;;EAU1C,MAAM,cAAc,aAAa,IAAI,KAAK;EAC1C,MAAM,UACJ,UAAU,QAAQ,SAAS,IAAI,aAAa,MAAM,IAAI,SAAS,KAAA;EACjE,MAAM,YAAY,WAAW,QAAQ,WAAW,SAAS;EAEzD,MAAM,KAAK;EACX,IAAI,cAAsC,GAAG;EAE7C,IAAI,aAAa,OAAO,GAAG,YAAY,UACrC,cAAc,gCACZ,GAAG,SACH,SACA,UACF;OACK,IAAI,aAAa,MAAM,QAAQ,GAAG,OAAO,GAAG;;;;;;;;;;;;;;;;;GAiBjD,MAAM,eAAsD,CAAC;GAC7D,IAAI,WAAW,MACb,aAAa,KAAK;IAChB,MAAM;IACN,MAAM,qBAAqB,OAAO;GACpC,CAAC;GAEH,IAAI,WAAW,SAAS,GACtB,aAAa,KAAK;IAChB,MAAM;IACN,MAAM,qBAAqB,WAAW,KAAK,IAAI,EAAE;GACnD,CAAC;GAEH,IAAI,aAAa,SAAS,GACxB,cAAc,CACZ,GAAG,cACH,GAAG,GAAG,OACR;EAEJ;;;;;;;EAQA,QAAQ,SAAS,MAAM;EACvB,IAAI,KAAK,4BAA4B,IAAI,WAAW;CACtD;CAEA,OAAO,OAAO;AAChB;;;;;;AAOA,SAAS,WACP,MACoB;CACpB,MAAM,IAAI,MAAM;CAChB,OAAO,OAAO,MAAM,WAAW,IAAI,KAAA;AACrC;;;;;;;AAQA,SAAS,aACP,MACoB;CACpB,MAAM,IAAI,MAAM;CAChB,OAAO,OAAO,MAAM,WAAW,IAAI,KAAA;AACrC;;;;;;;;AASA,SAAS,mBACP,MACU;CACV,MAAM,IAAI,MAAM;CAChB,IAAI,CAAC,MAAM,QAAQ,CAAC,GAAG,OAAO,CAAC;CAC/B,MAAM,MAAgB,CAAC;CACvB,KAAK,MAAM,QAAQ,GACjB,IAAI,OAAO,SAAS,UAAU,IAAI,KAAK,IAAI;CAE7C,OAAO;AACT;;;;;;;;;;;;;;AAeA,SAAS,4BACP,IACA,SACa;CACb,OAAO,IAAI,YAAY;EACrB,IAAI,GAAG;EACP,MAAM,GAAG;EACT,QAAQ,GAAG;EACX,UAAU,GAAG;EACb,cAAc,GAAG;EACjB,mBAAmB,GAAG;EACtB,mBAAmB,0BAA0B,GAAG,iBAAiB;EACjE;CACF,CAAC;AACH;;;;;;;;AASA,SAAS,0BACP,QACqC;CACrC,IAAI,UAAU,MAAM,OAAO,KAAA;CAC3B,IACE,EAAE,aAAa,WACf,EAAE,eAAe,WACjB,EAAE,qBAAqB,SAEvB,OAAO;CAET,MAAM,EAAE,SAAS,WAAW,iBAAiB,GAAG,SAAS;CAWzD,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,WAAW,IAAI,KAAA,IAAY;AACtD"}

package/dist/types/common/constants.d.ts

@@ -11,3 +11,21 @@ export declare const ANTHROPIC_TOOL_TOKEN_MULTIPLIER = 2.6;
  * Empirically calibrated at ~1.4× the raw JSON token count.
  */
 export declare const DEFAULT_TOOL_TOKEN_MULTIPLIER = 1.4;
+/**
+ * Default ceiling on cooperative stream seals per run. Each seal costs one
+ * extra superstep, so this also sizes the recursion-limit headroom a
+ * preemption-enabled run reserves.
+ */
+export declare const DEFAULT_MAX_SEALS = 8;
+/**
+ * Per-hook timeout for `PreemptBoundary`, deliberately far above
+ * `DEFAULT_HOOK_TIMEOUT_MS`. A host drain has already popped its queue and
+ * persisted content by the time this fires, so a timeout does not cancel the
+ * work — it only loses the messages the run was about to inject.
+ */
+export declare const PREEMPT_BOUNDARY_HOOK_TIMEOUT_MS = 120000;
+/**
+ * Default LangGraph recursion limit for a run. Callers may override it via
+ * the stream config; a preemption-enabled run adds its seal budget on top.
+ */
+export declare const DEFAULT_RECURSION_LIMIT = 50;

package/dist/types/graphs/Graph.d.ts

@@ -46,6 +46,20 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
     reasoningStepHasDeltas: Set<string>;
     protected handlerDispatchedEventCounts: Map<string, number>;
     signal?: AbortSignal;
+    /**
+     * The abort signal the CALLER handed to the current `processStream` call,
+     * assigned unconditionally — including back to `undefined` — on every call.
+     *
+     * Kept separate from {@link signal} on purpose. That field is construction
+     * state with its own consumers (model-call config, subagent parentSignal),
+     * so adopting a per-call signal into it would leak one call's controller
+     * into the next — `clearHeavyState()` is skipped on HITL interrupts, so a
+     * host that aborts a finished request's controller would poison the resumed
+     * run's model calls and boundary drains with an already-aborted signal.
+     * Boundary dispatch composes the two instead; see
+     * `StandardGraph.dispatchPreemptBoundary`.
+     */
+    callerSignal?: AbortSignal;
     /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
     invokedToolIds?: Set<string>;
     handlerRegistry: HandlerRegistry | undefined;
@@ -178,6 +192,8 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     messages: BaseMessage[];
     /** Cached run messages preserved before clearHeavyState() so getRunMessages() works after cleanup. */
     private cachedRunMessages?;
+    /** Ids of AI turns the agent node returned THIS run; see isRunProducedMessage. */
+    protected runProducedAiMessageIds: Set<string>;
     /** Checkpoint scope whose messages match index-keyed tool snapshots. */
     private originalToolContentCheckpointScope?;
     runId: string | undefined;
@@ -203,9 +219,105 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     subagentUsageSink?: t.SubagentUsageSink;
     /** See {@link t.StandardGraphInput.subagentScope}. */
     subagentScope: boolean;
-    constructor({ runId, signal, agents, langfuse, tokenCounter, indexTokenCountMap, calibrationRatio, subagentUsageSink, subagentScope, }: t.StandardGraphInput);
+    /** See {@link t.StandardGraphInput.preemption}. */
+    preemption?: t.StreamPreemption;
+    /**
+     * Seals charged against `preemption.maxSeals`. Per-turn: cleared by both
+     * reset paths so a fresh turn gets a fresh budget, while a HITL resume —
+     * which skips `resetValues` — keeps what it had left.
+     */
+    private preemptSealBudgetUsed;
+    /**
+     * Seals honored over the graph's lifetime. Reported by
+     * {@link getPreemptStats}, so it deliberately SURVIVES `clearHeavyState()`
+     * — a host reads it after `processStream` returns, which is strictly after
+     * cleanup runs.
+     */
+    preemptSealCount: number;
+    /** Boundaries that produced nothing to inject, so the turn stopped early. */
+    preemptEmptyBoundaries: number;
+    /**
+     * Set between claiming a seal and resolving its boundary. `MultiAgentGraph`
+     * fans parallel agents through this one instance against a single host
+     * request, so without a one-at-a-time gate several streams would each seal
+     * for the same queued message and every loser would take the
+     * nothing-to-inject path and cut its answer short.
+     */
+    private preemptSealInFlight;
+    /**
+     * True when a seal ended the turn without a resume. The assistant turn is
+     * real and kept, but it is not the answer the model intended to finish —
+     * hosts persist it as unfinished rather than complete.
+     */
+    preemptIncomplete: boolean;
+    /**
+     * `stopReason` from a `PreemptBoundary` hook that halted the turn.
+     *
+     * Clearing the registry halt is what keeps the sealed turn alive, but the
+     * registry held the only copy of the reason — so it is captured here first.
+     * Without it `getHaltReason()` returns undefined and a host records a
+     * hook-halted turn as an ordinary completion.
+     */
+    preemptHaltReason: string | undefined;
+    /**
+     * Agent IDs whose next superstep must return to the agent node. Keyed by
+     * agent because `MultiAgentGraph` routes every parallel agent through this
+     * same instance, and a single field would let one agent's boundary resume
+     * another's turn.
+     */
+    pendingPreemptReturn: Set<string>;
+    constructor({ runId, signal, agents, langfuse, tokenCounter, indexTokenCountMap, calibrationRatio, subagentUsageSink, subagentScope, preemption, }: t.StandardGraphInput);
     resetValues(keepContent?: boolean, checkpointScope?: string): void;
     clearHeavyState(): void;
+    /**
+     * Per-turn seal budget and routing markers. Cleared by both reset paths so
+     * a new turn starts with a full budget and no stale resume marker.
+     *
+     * The REPORTED counters are deliberately not touched here — see
+     * {@link resetPreemptTotals}.
+     */
+    private resetPreemptTurnState;
+    /**
+     * Lifetime seal totals, cleared only when a genuinely new run starts.
+     * `clearHeavyState()` must NOT call this: it runs in `processStream`'s
+     * `finally`, so zeroing here would make {@link getPreemptStats} and
+     * `preemptIncomplete` unreadable for every caller of the method that just
+     * produced them.
+     */
+    private resetPreemptTotals;
+    /**
+     * True when the host has requested a cooperative seal AND this graph may
+     * honor it. Read once per streamed chunk, so it stays property reads plus
+     * one host callback — no I/O, no allocation.
+     *
+     * Non-mutating: a true result only means a seal is worth evaluating. The
+     * budget is taken by {@link claimPreemptSeal} once the accumulated chunk is
+     * known to be safe, so a chunk that cannot seal never spends budget.
+     *
+     * Subagent scopes never seal: a steer targets the top-level conversation,
+     * and a child run must finish so its parent sees a complete result.
+     */
+    /** Internal seal preconditions only — no host callback, no side effects. */
+    private canClaimPreemptSeal;
+    shouldPreemptStream(): boolean;
+    /**
+     * Takes the seal slot, or returns false if another stream already holds it.
+     *
+     * Assumes the caller already polled `shouldPreemptStream()` for THIS chunk,
+     * and deliberately does not poll the host again — `StreamPreemption`
+     * documents `shouldPreempt` as once per chunk, and a host that consumes a
+     * pending flag on read would lose the request to a second call.
+     *
+     * The guard and both mutations remain one synchronous body, which is what
+     * makes this safe under a parallel `MultiAgentGraph`: several agents share
+     * one graph and can each see the poll as true, but no `await` can split the
+     * claim, so only one takes the slot. The loser keeps streaming normally
+     * rather than sealing for a message it would never receive.
+     */
+    claimPreemptSeal(): boolean;
+    /** Releases the seal slot once its boundary has resolved, win or lose. */
+    releasePreemptSeal(): void;
+    getPreemptStats(): t.PreemptStats;
     getRunStep(stepId: string): t.RunStep | undefined;
     getAgentContext(metadata: Record<string, unknown> | undefined): AgentContext;
     getStepBaseKey(metadata: Record<string, unknown> | undefined): string;
@@ -217,6 +329,17 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     private getBaseKeyList;
     checkKeyList(keyList: (string | number | undefined)[]): boolean;
     getRunMessages(): BaseMessage[] | undefined;
+    /**
+     * True when THIS RUN produced `message` — the provenance the handoff cue
+     * gate needs. Tracked as an id set rather than inferred from `startIndex`
+     * arithmetic: summarization's remove-all compaction rewrites the live
+     * array and leaves `startIndex` stale, so index-based run/host
+     * discrimination silently breaks right after a mid-run summarize. Ids
+     * survive compaction (retained messages keep theirs), host-supplied
+     * prefill messages are never in the set, and membership is O(1) per
+     * model call.
+     */
+    isRunProducedMessage(message: BaseMessage): boolean;
     getContentParts(): t.MessageContentComplex[] | undefined;
     getCalibrationRatio(): number;
     getResolvedInstructionOverhead(): number | undefined;
@@ -256,6 +379,20 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
      */
     private beginOverflowRecovery;
     createCallModel(agentId?: string): (state: t.AgentSubgraphState, config?: RunnableConfig) => Promise<Partial<t.AgentSubgraphState>>;
+    /**
+     * Fires `PreemptBoundary` after a sealed turn and returns whatever the
+     * hooks asked to inject, converted through the same `convertInjectedMessages`
+     * the tool boundary uses so the two sites cannot emit different shapes.
+     *
+     * Never throws: a drain that fails or times out costs the injection, not the
+     * run. The caller treats an empty result as "nothing to resume with".
+     *
+     * `preventContinuation` is surfaced alongside the messages rather than left
+     * to the registry halt signal, which `processStream` only polls between
+     * stream events — by then the self-loop it was meant to prevent has already
+     * issued another model call, and a direct graph consumer never polls it.
+     */
+    private dispatchPreemptBoundary;
     createAgentNode(agentId: string): t.CompiledAgentWorfklow;
     createWorkflow(): t.CompiledStateWorkflow;
     /**

package/dist/types/hooks/HookRegistry.d.ts

@@ -120,5 +120,20 @@ export declare class HookRegistry {
     hasResultAlteringHooks(sessionId?: string): boolean;
     /** True if at least one matcher exists for `event` (global + session). */
     hasHookFor(event: HookEvent, sessionId?: string): boolean;
+    /**
+     * True when at least one matcher for `event` would actually DISPATCH on a
+     * query-less call — a wildcard pattern with a non-empty `hooks` array.
+     *
+     * `hasHookFor` answers "is one registered", which is not the same question:
+     * a matcher carrying a pattern is inert for events that supply no
+     * `matchQuery`, so a caller using registration as a proxy for "something
+     * will run" can act on a hook that never fires. Mirrors the two skips in
+     * `executeHooks` (pattern mismatch, empty `hooks`).
+     *
+     * Non-allocating on purpose — `StandardGraph.canClaimPreemptSeal` reads it
+     * once per streamed chunk, where `getMatchers`' defensive `slice()` would
+     * allocate on every delta.
+     */
+    hasDispatchableHookFor(event: HookEvent, sessionId?: string): boolean;
     private ensureSessionBucket;
 }

package/dist/types/hooks/index.d.ts

@@ -8,11 +8,22 @@ export { executeHooks, DEFAULT_HOOK_TIMEOUT_MS } from './executeHooks';
  * be consumed by an SDK version that would silently drop it.
  */
 export declare const HOOK_INJECTED_MESSAGES_CAPABLE = true;
+/**
+ * Feature probe for hosts: this SDK dispatches `PreemptBoundary`, so a
+ * cooperative mid-generation seal can drain into the run.
+ *
+ * Deliberately separate from {@link HOOK_INJECTED_MESSAGES_CAPABLE} — an SDK
+ * version can support `injectedMessages` at the tool boundary and know
+ * nothing about preemption. A host that probed the wrong flag would arm an
+ * interrupt control whose seal request is silently ignored, which reads to
+ * the user as a dead button rather than as an unsupported feature.
+ */
+export declare const HOOK_PREEMPT_BOUNDARY_CAPABLE = true;
 export { matchesQuery, hasNestedQuantifier, MAX_PATTERN_LENGTH, MAX_CACHE_SIZE, } from './matchers';
 export { createToolPolicyHook } from './createToolPolicyHook';
 export type { ToolPolicyMode, ToolPolicyConfig } from './createToolPolicyHook';
 export { createWorkspacePolicyHook } from './createWorkspacePolicyHook';
 export type { OutsideAccessPolicy, WorkspacePolicyConfig, PathExtractor, } from './createWorkspacePolicyHook';
 export { HOOK_EVENTS } from './types';
-export type { HookEvent, HookInput, HookOutput, HookCallback, HookMatcher, HooksByEvent, HookInputByEvent, HookOutputByEvent, BaseHookInput, BaseHookOutput, ToolDecision, StopDecision, AggregatedHookResult, RunStartHookInput, UserPromptSubmitHookInput, PreToolUseHookInput, PostToolUseHookInput, PostToolUseFailureHookInput, PostToolBatchHookInput, PostToolBatchEntry, PermissionDeniedHookInput, SubagentStartHookInput, SubagentStopHookInput, StopHookInput, StopFailureHookInput, PreCompactHookInput, PostCompactHookInput, RunStartHookOutput, UserPromptSubmitHookOutput, PreToolUseHookOutput, PostToolUseHookOutput, PostToolUseFailureHookOutput, PostToolBatchHookOutput, PermissionDeniedHookOutput, SubagentStartHookOutput, SubagentStopHookOutput, StopHookOutput, StopFailureHookOutput, PreCompactHookOutput, PostCompactHookOutput, } from './types';
+export type { HookEvent, HookInput, HookOutput, HookCallback, HookMatcher, HooksByEvent, HookInputByEvent, HookOutputByEvent, BaseHookInput, BaseHookOutput, ToolDecision, StopDecision, AggregatedHookResult, RunStartHookInput, UserPromptSubmitHookInput, PreToolUseHookInput, PostToolUseHookInput, PostToolUseFailureHookInput, PostToolBatchHookInput, PostToolBatchEntry, PreemptBoundaryHookInput, PermissionDeniedHookInput, SubagentStartHookInput, SubagentStopHookInput, StopHookInput, StopFailureHookInput, PreCompactHookInput, PostCompactHookInput, RunStartHookOutput, UserPromptSubmitHookOutput, PreToolUseHookOutput, PostToolUseHookOutput, PostToolUseFailureHookOutput, PostToolBatchHookOutput, PreemptBoundaryHookOutput, PermissionDeniedHookOutput, SubagentStartHookOutput, SubagentStopHookOutput, StopHookOutput, StopFailureHookOutput, PreCompactHookOutput, PostCompactHookOutput, } from './types';
 export type { ExecuteHooksOptions } from './executeHooks';