@librechat/agents 3.1.71-dev.1 → 3.1.72

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

@@ -1 +1 @@
-{"version":3,"file":"toolOutputReferences.mjs","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';\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 under our framework\n     * keys. Treat them as untrusted input and coerce defensively\n     * before any array operation — a malformed field on a single\n     * hydrated message must not crash `attemptInvoke` before the\n     * provider call.\n     */\n    const meta = m.additional_kwargs as Record<string, unknown> | undefined;\n    const hasRefKey = meta != null && '_refKey' in meta;\n    const hasRefScope = meta != null && '_refScope' in meta;\n    const hasUnresolvedField = meta != null && '_unresolvedRefs' in meta;\n    if (!hasRefKey && !hasRefScope && !hasUnresolvedField) continue;\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 (\n      annotates &&\n      Array.isArray(tm.content) &&\n      unresolved.length > 0\n    ) {\n      const warningBlock = {\n        type: 'text' as const,\n        text: `[unresolved refs: ${unresolved.join(', ')}]`,\n      };\n      nextContent = [\n        warningBlock,\n        ...tm.content,\n      ] as unknown as ToolMessage['content'];\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"],"names":[],"mappings":"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"}
+{"version":3,"file":"toolOutputReferences.mjs","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';\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\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 (\n      annotates &&\n      Array.isArray(tm.content) &&\n      unresolved.length > 0\n    ) {\n      const warningBlock = {\n        type: 'text' as const,\n        text: `[unresolved refs: ${unresolved.join(', ')}]`,\n      };\n      /**\n       * `as unknown as ToolMessage['content']` is unavoidable here:\n       * LangChain's content union (`MessageContentComplex[] |\n       * DataContentBlock[] | string`) does not accept a freshly built\n       * mixed array literal even though the structural shape is valid\n       * at runtime. The double-cast is structurally safe — we\n       * preserve every block from `tm.content` and prepend a single\n       * `{ type: 'text', text }` block that all providers accept.\n       */\n      nextContent = [\n        warningBlock,\n        ...tm.content,\n      ] as unknown as ToolMessage['content'];\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"],"names":[],"mappings":"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"}

package/dist/types/llm/invoke.d.ts

@@ -1,23 +1,40 @@
 import { AIMessageChunk } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseMessage } from '@langchain/core/messages';
+import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import type * as t from '@/types';
 import { ChatModelStreamHandler } from '@/stream';
 import { Providers } from '@/common';
 /**
- * Context passed to `attemptInvoke` for the default stream handler.
- * Matches the subset of Graph that `ChatModelStreamHandler.handle` needs.
+ * Context passed to `attemptInvoke`. Matches the subset of Graph that
+ * `ChatModelStreamHandler.handle` needs *plus* the explicit
+ * `getOrCreateToolOutputRegistry()` accessor that `attemptInvoke`
+ * itself calls to pull the run-scoped tool-output registry off the
+ * graph and project each relevant ToolMessage into a transient
+ * annotated copy before the provider call.
  *
- * `attemptInvoke` additionally calls `context?.getOrCreateToolOutputRegistry?.()`
- * (if defined) to pull the run-scoped tool output registry off the graph
- * so it can project each relevant `ToolMessage` into a transient
- * annotated copy right before sending to the provider — annotations
- * never persist back into graph state.
+ * The intersection is intentional: `Parameters<...>[3]` resolves
+ * indirectly through the stream handler's signature (which returns
+ * `StandardGraph` and already exposes the accessor since #117), but
+ * stating it explicitly here surfaces the contract at the call site —
+ * a developer reading `attemptInvoke` doesn't have to chase the
+ * upstream handler's parameter list to discover that
+ * `context?.getOrCreateToolOutputRegistry()` is a real thing. Single
+ * optional chain only — the method itself is required on the
+ * `StandardGraph` branch of the intersection, so the second `?.` is
+ * unnecessary at the call site.
+ *
+ * `NonNullable<...>` strips `undefined` from the upstream parameter
+ * type so the intersection doesn't collapse to `never` on the
+ * undefined branch; callers express optionality via `context?:
+ * InvokeContext` on the function signature instead.
  *
  * Callers without a registry (e.g. summarization) simply pass no
  * `context` and the transform safely no-ops.
  */
-export type InvokeContext = Parameters<ChatModelStreamHandler['handle']>[3];
+export type InvokeContext = NonNullable<Parameters<ChatModelStreamHandler['handle']>[3]> & {
+    getOrCreateToolOutputRegistry?(): ToolOutputReferenceRegistry | undefined;
+};
 /**
  * Per-chunk callback for custom stream processing.
  * When provided, replaces the default `ChatModelStreamHandler`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.1.71-dev.1",
+  "version": "3.1.72",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/llm/invoke.test.ts

@@ -28,10 +28,17 @@ type StubModel = {
   ) => AsyncGenerator<AIMessageChunk>;
 };
 
-function buildCapturingModel(): {
+type CapturingModel = {
   invokeMessages: BaseMessage[][];
   model: StubModel;
-  } {
+};
+
+type StreamingCapturingModel = {
+  streamMessages: BaseMessage[][];
+  model: StubModel;
+};
+
+function buildCapturingModel(): CapturingModel {
   const invokeMessages: BaseMessage[][] = [];
   const responseMsg = new AIMessage({ content: 'ok' });
   const model: StubModel = {
@@ -43,10 +50,7 @@ function buildCapturingModel(): {
   return { invokeMessages, model };
 }
 
-function buildStreamingCapturingModel(): {
-  streamMessages: BaseMessage[][];
-  model: StubModel;
-  } {
+function buildStreamingCapturingModel(): StreamingCapturingModel {
   const streamMessages: BaseMessage[][] = [];
   const model: StubModel = {
     stream: jest.fn(async function* (

package/src/llm/invoke.ts

@@ -3,6 +3,7 @@ import { AIMessageChunk } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type { BaseMessage } from '@langchain/core/messages';
+import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import type * as t from '@/types';
 import { manualToolStreamProviders } from '@/llm/providers';
 import { annotateMessagesForLLM } from '@/tools/toolOutputReferences';
@@ -12,19 +13,37 @@ import { GraphEvents, Providers } from '@/common';
 import { initializeModel } from '@/llm/init';
 
 /**
- * Context passed to `attemptInvoke` for the default stream handler.
- * Matches the subset of Graph that `ChatModelStreamHandler.handle` needs.
+ * Context passed to `attemptInvoke`. Matches the subset of Graph that
+ * `ChatModelStreamHandler.handle` needs *plus* the explicit
+ * `getOrCreateToolOutputRegistry()` accessor that `attemptInvoke`
+ * itself calls to pull the run-scoped tool-output registry off the
+ * graph and project each relevant ToolMessage into a transient
+ * annotated copy before the provider call.
  *
- * `attemptInvoke` additionally calls `context?.getOrCreateToolOutputRegistry?.()`
- * (if defined) to pull the run-scoped tool output registry off the graph
- * so it can project each relevant `ToolMessage` into a transient
- * annotated copy right before sending to the provider — annotations
- * never persist back into graph state.
+ * The intersection is intentional: `Parameters<...>[3]` resolves
+ * indirectly through the stream handler's signature (which returns
+ * `StandardGraph` and already exposes the accessor since #117), but
+ * stating it explicitly here surfaces the contract at the call site —
+ * a developer reading `attemptInvoke` doesn't have to chase the
+ * upstream handler's parameter list to discover that
+ * `context?.getOrCreateToolOutputRegistry()` is a real thing. Single
+ * optional chain only — the method itself is required on the
+ * `StandardGraph` branch of the intersection, so the second `?.` is
+ * unnecessary at the call site.
+ *
+ * `NonNullable<...>` strips `undefined` from the upstream parameter
+ * type so the intersection doesn't collapse to `never` on the
+ * undefined branch; callers express optionality via `context?:
+ * InvokeContext` on the function signature instead.
  *
  * Callers without a registry (e.g. summarization) simply pass no
  * `context` and the transform safely no-ops.
  */
-export type InvokeContext = Parameters<ChatModelStreamHandler['handle']>[3];
+export type InvokeContext = NonNullable<
+  Parameters<ChatModelStreamHandler['handle']>[3]
+> & {
+  getOrCreateToolOutputRegistry?(): ToolOutputReferenceRegistry | undefined;
+};
 
 /**
  * Per-chunk callback for custom stream processing.

package/src/tools/BashExecutor.ts

@@ -66,7 +66,9 @@ Referencing previous tool outputs:
 - Every successful tool result is tagged with a reference key of the form \`tool<idx>turn<turn>\` (e.g., \`tool0turn0\`). The key appears either as a \`[ref: tool0turn0]\` prefix line or, when the output is a JSON object, as a \`_ref\` field on the object.
 - To pipe a previous tool output into this tool, embed the placeholder \`{{tool<idx>turn<turn>}}\` literally anywhere in the \`command\` string (or any string arg). It will be substituted with the stored output verbatim before the command runs.
 - The substituted value is the original output string (no \`[ref: …]\` prefix, no \`_ref\` key), so it is safe to pipe directly into \`jq\`, \`grep\`, \`awk\`, etc.
-- Example: \`echo '{{tool0turn0}}' | jq '.foo'\` takes the full output of the first tool from the first turn and pipes it into jq.
+- Example (simple ASCII output): \`echo '{{tool0turn0}}' | jq '.foo'\` takes the full output of the first tool from the first turn and pipes it into jq.
+- For payloads that may contain quotes, parentheses, backticks, or arbitrary bytes (random/binary data, JSON with embedded quotes, multi-line strings), prefer a quoted-delimiter heredoc over \`echo '…'\`. The heredoc body is not interpreted by the shell, so substituted payloads pass through unchanged.
+- Heredoc example: \`wc -c << 'EOF'\\n{{tool0turn0}}\\nEOF\` (the quotes around \`'EOF'\` disable interpolation inside the body).
 - Unknown reference keys are left in place and surfaced as \`[unresolved refs: …]\` after the output.
 `.trim();
 

package/src/tools/ToolNode.ts

@@ -996,9 +996,21 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           turn,
         };
 
+        /**
+         * Emit `codeSessionContext` for any tool whose host handler may need
+         * to reach into the code-execution sandbox:
+         *   - `CODE_EXECUTION_TOOLS` — direct executors that POST to /exec.
+         *   - `SKILL_TOOL` — skill files live alongside code-env state.
+         *   - `READ_FILE` — when the requested path is a code-env artifact
+         *     (e.g. `/mnt/data/...`) the host falls back to reading via the
+         *     same sandbox session; without the seeded `session_id` /
+         *     `_injected_files` here, that fallback can't see prior-turn
+         *     artifacts on the very first call of a turn.
+         */
         if (
           CODE_EXECUTION_TOOLS.has(entry.call.name) ||
-          entry.call.name === Constants.SKILL_TOOL
+          entry.call.name === Constants.SKILL_TOOL ||
+          entry.call.name === Constants.READ_FILE
         ) {
           request.codeSessionContext = this.getCodeSessionContext();
         }

package/src/tools/__tests__/BashExecutor.test.ts

@@ -27,6 +27,19 @@ describe('buildBashExecutionToolDescription', () => {
     expect(composed).toContain('{{tool<idx>turn<turn>}}');
   });
 
+  it('nudges the model toward heredoc when payloads may contain shell metacharacters', () => {
+    /**
+     * Real-world failure observed against ClickHouse + bash piping:
+     * the model emitted `echo '{{ref}}' | wc -c` and the substituted
+     * binary payload contained literal single quotes, breaking the
+     * shell. The model self-corrected to a heredoc on retry. Surface
+     * the heredoc pattern upfront so the round-trip isn't burned to
+     * rediscover it.
+     */
+    expect(BashToolOutputReferencesGuide).toContain('heredoc');
+    expect(BashToolOutputReferencesGuide).toContain('<< \'EOF\'');
+  });
+
   it('separates base and guide with a blank line', () => {
     const composed = buildBashExecutionToolDescription({
       enableToolOutputReferences: true,

package/src/tools/__tests__/ToolNode.session.test.ts

@@ -1,11 +1,12 @@
 import { z } from 'zod';
 import { tool } from '@langchain/core/tools';
 import { AIMessage } from '@langchain/core/messages';
-import { describe, it, expect } from '@jest/globals';
+import { describe, it, expect, jest, afterEach } from '@jest/globals';
 import type { StructuredToolInterface } from '@langchain/core/tools';
 import type * as t from '@/types';
 import { ToolNode } from '../ToolNode';
 import { Constants } from '@/common';
+import * as events from '@/utils/events';
 
 /**
  * Creates a mock execute_code tool that captures the toolCall config it receives.
@@ -233,7 +234,9 @@ describe('ToolNode code execution session management', () => {
             status: 'success',
           },
         ],
-        new Map([['tc1', { id: 'tc1', name: Constants.EXECUTE_CODE, args: {} }]])
+        new Map([
+          ['tc1', { id: 'tc1', name: Constants.EXECUTE_CODE, args: {} }],
+        ])
       );
 
       const stored = sessions.get(
@@ -279,7 +282,9 @@ describe('ToolNode code execution session management', () => {
             status: 'success',
           },
         ],
-        new Map([['tc2', { id: 'tc2', name: Constants.EXECUTE_CODE, args: {} }]])
+        new Map([
+          ['tc2', { id: 'tc2', name: Constants.EXECUTE_CODE, args: {} }],
+        ])
       );
 
       const stored = sessions.get(
@@ -329,7 +334,9 @@ describe('ToolNode code execution session management', () => {
             status: 'success',
           },
         ],
-        new Map([['tc3', { id: 'tc3', name: Constants.EXECUTE_CODE, args: {} }]])
+        new Map([
+          ['tc3', { id: 'tc3', name: Constants.EXECUTE_CODE, args: {} }],
+        ])
       );
 
       const stored = sessions.get(
@@ -379,7 +386,9 @@ describe('ToolNode code execution session management', () => {
             status: 'success',
           },
         ],
-        new Map([['tc4', { id: 'tc4', name: Constants.EXECUTE_CODE, args: {} }]])
+        new Map([
+          ['tc4', { id: 'tc4', name: Constants.EXECUTE_CODE, args: {} }],
+        ])
       );
 
       const stored = sessions.get(
@@ -456,10 +465,150 @@ describe('ToolNode code execution session management', () => {
             errorMessage: 'execution failed',
           },
         ],
-        new Map([['tc6', { id: 'tc6', name: Constants.EXECUTE_CODE, args: {} }]])
+        new Map([
+          ['tc6', { id: 'tc6', name: Constants.EXECUTE_CODE, args: {} }],
+        ])
       );
 
       expect(sessions.has(Constants.EXECUTE_CODE)).toBe(false);
     });
   });
+
+  describe('codeSessionContext emission gate (event-driven request building)', () => {
+    /**
+     * Captures the `ToolExecuteBatchRequest` dispatched on ON_TOOL_EXECUTE so
+     * we can assert which `request.name`s receive `codeSessionContext`. Returns
+     * the captured requests; resolves the dispatched event with empty results
+     * to let `dispatchToolEvents` complete.
+     */
+    function captureBatchRequests(): {
+      capturedRequests: t.ToolCallRequest[];
+      } {
+      const capturedRequests: t.ToolCallRequest[] = [];
+      jest
+        .spyOn(events, 'safeDispatchCustomEvent')
+        .mockImplementation(async (_event, data) => {
+          const batch = data as t.ToolExecuteBatchRequest;
+          if (Array.isArray(batch.toolCalls)) {
+            capturedRequests.push(...batch.toolCalls);
+          }
+          if (typeof batch.resolve === 'function') {
+            batch.resolve(
+              batch.toolCalls.map((tc) => ({
+                toolCallId: tc.id,
+                content: '',
+                status: 'success' as const,
+              }))
+            );
+          }
+        });
+      return { capturedRequests };
+    }
+
+    const createDummyTool = (name: string): StructuredToolInterface =>
+      tool(async () => 'ok', {
+        name,
+        description: 'dummy',
+        schema: z.object({ x: z.string().optional() }),
+      }) as unknown as StructuredToolInterface;
+
+    afterEach(() => {
+      jest.restoreAllMocks();
+    });
+
+    it('attaches codeSessionContext to read_file requests so the host can fall back to the code-env sandbox', async () => {
+      const sessions: t.ToolSessionMap = new Map();
+      sessions.set(Constants.EXECUTE_CODE, {
+        session_id: 'rf-session',
+        files: [{ id: 'rf1', name: 'data.csv', session_id: 'rf-session' }],
+        lastUpdated: Date.now(),
+      } satisfies t.CodeSessionContext);
+
+      const { capturedRequests } = captureBatchRequests();
+
+      const toolNode = new ToolNode({
+        tools: [createDummyTool(Constants.READ_FILE)],
+        sessions,
+        eventDrivenMode: true,
+        toolCallStepIds: new Map([['call_rf', 'step_rf']]),
+      });
+
+      const aiMsg = new AIMessage({
+        content: '',
+        tool_calls: [
+          {
+            id: 'call_rf',
+            name: Constants.READ_FILE,
+            args: { file_path: '/mnt/data/data.csv' },
+          },
+        ],
+      });
+
+      await toolNode.invoke({ messages: [aiMsg] });
+
+      expect(capturedRequests).toHaveLength(1);
+      expect(capturedRequests[0].name).toBe(Constants.READ_FILE);
+      expect(capturedRequests[0].codeSessionContext).toEqual({
+        session_id: 'rf-session',
+        files: [{ session_id: 'rf-session', id: 'rf1', name: 'data.csv' }],
+      });
+    });
+
+    it('does not attach codeSessionContext to read_file when no session exists yet', async () => {
+      const { capturedRequests } = captureBatchRequests();
+
+      const toolNode = new ToolNode({
+        tools: [createDummyTool(Constants.READ_FILE)],
+        sessions: new Map(),
+        eventDrivenMode: true,
+        toolCallStepIds: new Map([['call_rf2', 'step_rf2']]),
+      });
+
+      const aiMsg = new AIMessage({
+        content: '',
+        tool_calls: [
+          {
+            id: 'call_rf2',
+            name: Constants.READ_FILE,
+            args: { file_path: 'some-skill/notes.md' },
+          },
+        ],
+      });
+
+      await toolNode.invoke({ messages: [aiMsg] });
+
+      expect(capturedRequests).toHaveLength(1);
+      expect(capturedRequests[0].name).toBe(Constants.READ_FILE);
+      expect(capturedRequests[0].codeSessionContext).toBeUndefined();
+    });
+
+    it('does not attach codeSessionContext to unrelated tools', async () => {
+      const sessions: t.ToolSessionMap = new Map();
+      sessions.set(Constants.EXECUTE_CODE, {
+        session_id: 'unrelated-session',
+        files: [],
+        lastUpdated: Date.now(),
+      } satisfies t.CodeSessionContext);
+
+      const { capturedRequests } = captureBatchRequests();
+
+      const toolNode = new ToolNode({
+        tools: [createDummyTool('web_search')],
+        sessions,
+        eventDrivenMode: true,
+        toolCallStepIds: new Map([['call_ws', 'step_ws']]),
+      });
+
+      const aiMsg = new AIMessage({
+        content: '',
+        tool_calls: [{ id: 'call_ws', name: 'web_search', args: { x: 'q' } }],
+      });
+
+      await toolNode.invoke({ messages: [aiMsg] });
+
+      expect(capturedRequests).toHaveLength(1);
+      expect(capturedRequests[0].name).toBe('web_search');
+      expect(capturedRequests[0].codeSessionContext).toBeUndefined();
+    });
+  });
 });