@librechat/agents 3.4.0 → 3.4.2

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';\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":"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"}
+{"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 (\n      parsed != null &&\n      typeof parsed === 'object' &&\n      !Array.isArray(parsed)\n    ) {\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\nexport interface ToolOutputReferenceState {\n  entries: Array<{ key: string; value: string }>;\n  turnCounter: number;\n  warnedNonStringTools: string[];\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  /** Captures the checkpoint-safe state needed to resume one run bucket. */\n  snapshotState(runId: string | undefined): ToolOutputReferenceState {\n    const bucket = this.runStates.get(this.keyFor(runId));\n    return {\n      entries: [...(bucket?.entries ?? EMPTY_ENTRIES)].map(([key, value]) => ({\n        key,\n        value,\n      })),\n      turnCounter: bucket?.turnCounter ?? 0,\n      warnedNonStringTools: [...(bucket?.warnedNonStringTools ?? [])],\n    };\n  }\n\n  /** Restores a checkpointed run bucket under the current resume scope. */\n  restoreState(\n    runId: string | undefined,\n    state: ToolOutputReferenceState\n  ): void {\n    this.releaseRun(runId);\n    const bucket = this.getOrCreate(runId);\n    for (const { key, value } of state.entries) {\n      this.set(runId, key, value);\n    }\n    bucket.turnCounter = state.turnCounter;\n    for (const toolName of state.warnedNonStringTools) {\n      bucket.warnedNonStringTools.add(toolName);\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,IACE,UAAU,QACV,OAAO,WAAW,YAClB,CAAC,MAAM,QAAQ,MAAM,GAErB,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;AAqEA,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;;CAGA,cAAc,OAAqD;EACjE,MAAM,SAAS,KAAK,UAAU,IAAI,KAAK,OAAO,KAAK,CAAC;EACpD,OAAO;GACL,SAAS,CAAC,GAAI,QAAQ,WAAW,aAAc,CAAC,CAAC,KAAK,CAAC,KAAK,YAAY;IACtE;IACA;GACF,EAAE;GACF,aAAa,QAAQ,eAAe;GACpC,sBAAsB,CAAC,GAAI,QAAQ,wBAAwB,CAAC,CAAE;EAChE;CACF;;CAGA,aACE,OACA,OACM;EACN,KAAK,WAAW,KAAK;EACrB,MAAM,SAAS,KAAK,YAAY,KAAK;EACrC,KAAK,MAAM,EAAE,KAAK,WAAW,MAAM,SACjC,KAAK,IAAI,OAAO,KAAK,KAAK;EAE5B,OAAO,cAAc,MAAM;EAC3B,KAAK,MAAM,YAAY,MAAM,sBAC3B,OAAO,qBAAqB,IAAI,QAAQ;CAE5C;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/esm/utils/index.mjs

@@ -1,11 +1,11 @@
 import "./misc.mjs";
 import "./truncation.mjs";
 import "./tokens.mjs";
-import "./llm.mjs";
-import "./errors.mjs";
 import "./graph.mjs";
+import "./llm.mjs";
 import "./proxy.mjs";
 import "./handlers.mjs";
 import "./run.mjs";
 import "./schema.mjs";
+import "./errors.mjs";
 export {};

package/dist/types/agents/AgentContext.d.ts

@@ -101,7 +101,7 @@ export declare class AgentContext {
     /** Original AgentInputs used to create this context — used for self-spawn subagent resolution. */
     _sourceInputs?: t.AgentInputs;
     /** Subagent configurations for hierarchical delegation. */
-    subagentConfigs?: t.SubagentConfig[];
+    subagentConfigs?: t.SubagentConfigEntry[];
     /** Maximum subagent nesting depth. */
     maxSubagentDepth?: number;
     /** Instructions for this agent */

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

@@ -2,16 +2,20 @@ import { ToolNode } from '@langchain/langgraph/prebuilt';
 import { RunnableConfig } from '@langchain/core/runnables';
 import type { UsageMetadata, BaseMessage } from '@langchain/core/messages';
 import type { ToolCall } from '@langchain/core/messages/tool';
+import type { SubagentGraphResumeState, SubagentToolNodeResumeState } from '@/tools/subagent/SubagentReplay';
 import type { ResolvedStreamLimits, RunBreakerScope, StreamedToolCallArgTally, StreamDeltaEventTally } from '@/llm/streamLimits';
+import type { GraphFactoryDependencies } from '@/graphs/graphFactory';
 import type { HookRegistry } from '@/hooks';
 import type * as t from '@/types';
-import { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import { StreamLimitExceededError } from '@/llm/streamLimits';
+import { SubagentExecutor } from '@/tools/subagent';
+import { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import { ToolNode as CustomToolNode } from '@/tools/ToolNode';
 import { AgentContext } from '@/agents/AgentContext';
 import { HandlerRegistry } from '@/events';
 export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphState, _TNodeName extends string = string> {
     abstract resetValues(keepContent?: boolean, checkpointScope?: string): void;
+    restoreCheckpointMessages(_messages: BaseMessage[], _pendingMessages?: BaseMessage[]): void;
     abstract initializeTools({ currentTools, currentToolMap, }: {
         currentTools?: t.GraphTools;
         currentToolMap?: t.ToolMap;
@@ -159,7 +163,14 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
      */
     protected registerCompiledToolNode(node: {
         clearDirectPathTurns(): void;
+        createSubagentResumeState(): SubagentToolNodeResumeState;
+        restoreSubagentResumeState(state: SubagentToolNodeResumeState): void;
     }): void;
+    protected registerSubagentExecutor(executor: SubagentExecutor): void;
+    protected resetSubagentCheckpointThreadIds(): void;
+    getChildCheckpointThreadIds(): string[];
+    createSubagentResumeState(runId: string): SubagentGraphResumeState;
+    restoreSubagentResumeState(state: SubagentGraphResumeState, runId: string): void;
     /**
      * Returns the shared `ToolOutputReferenceRegistry` for this run,
      * constructing it on first access. Returns `undefined` when the
@@ -194,16 +205,21 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
      * across Runs if a provider reuses call ids (Codex P2 #33).
      */
     private _compiledToolNodes;
+    private _subagentExecutors;
     getOrCreateFileCheckpointer(): t.LocalFileCheckpointer | undefined;
 }
 export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     overrideModel?: t.ChatModel;
     private subagentModelOverride?;
+    private readonly graphFactory;
+    private readonly supportsMultiAgentChildren;
     /** Optional compile options passed into workflow.compile() */
     compileOptions?: t.CompileOptions | undefined;
     /** Whether the workflow was actually compiled with a checkpointer. */
     hasCompiledCheckpointer: boolean;
     messages: BaseMessage[];
+    /** Whether a rebuilt resume seeded the message baseline from its checkpoint. */
+    private hasRestoredCheckpointMessages;
     /** Cached run messages preserved before clearHeavyState() so getRunMessages() works after cleanup. */
     private cachedRunMessages?;
     /** Per-agent discovery snapshots preserved before contexts are reset on cleanup. */
@@ -245,6 +261,8 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     subagentUsageSink?: t.SubagentUsageSink;
     /** See {@link t.StandardGraphInput.subagentScope}. */
     subagentScope: boolean;
+    /** See {@link t.StandardGraphInput.subagentExecutionContext}. */
+    private readonly subagentExecutionContext?;
     /** See {@link t.StandardGraphInput.preemption}. */
     preemption?: t.StreamPreemption;
     /**
@@ -342,8 +360,10 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
      * another's turn.
      */
     pendingPreemptReturn: Set<string>;
-    constructor({ runId, signal, agents, langfuse, tokenCounter, indexTokenCountMap, calibrationRatio, subagentUsageSink, subagentScope, preemption, streamLimits, }: t.StandardGraphInput);
+    constructor({ runId, signal, agents, langfuse, tokenCounter, indexTokenCountMap, calibrationRatio, subagentUsageSink, subagentScope, subagentExecutionContext, preemption, streamLimits, }: t.StandardGraphInput, dependencies?: GraphFactoryDependencies);
     resetValues(keepContent?: boolean, checkpointScope?: string): void;
+    /** Seeds the sidecar message view that checkpoint restoration bypasses. */
+    restoreCheckpointMessages(messages: BaseMessage[], pendingMessages?: BaseMessage[]): void;
     clearHeavyState(): void;
     /**
      * Per-turn seal budget and routing markers. Cleared by both reset paths so

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

@@ -1,3 +1,4 @@
+import type { GraphFactoryDependencies } from '@/graphs/graphFactory';
 import type * as t from '@/types';
 import { StandardGraph } from './Graph';
 /**
@@ -19,6 +20,9 @@ export declare class MultiAgentGraph extends StandardGraph {
     private startingNodes;
     private directEdges;
     private handoffEdges;
+    private handoffSourceIds;
+    private readonly resultAgentId?;
+    private readonly memberRecursionLimit?;
     private handoffPromptLabels;
     /**
      * Map of agentId to parallel group info.
@@ -31,7 +35,7 @@ export declare class MultiAgentGraph extends StandardGraph {
      * - summarizer: undefined (sequential, order 2)
      */
     private agentParallelGroups;
-    constructor(input: t.MultiAgentGraphInput);
+    constructor(input: t.MultiAgentGraphInput, dependencies?: GraphFactoryDependencies);
     /**
      * Fails fast when an edge references an agent that is not in
      * `agentContexts`. Without this check, the underlying LangGraph
@@ -48,6 +52,8 @@ export declare class MultiAgentGraph extends StandardGraph {
      * Categorize edges into handoff and direct types
      */
     private categorizeEdges;
+    /** Static waiting/prompt edges cannot also be driven by Command routing. */
+    private validateCommandRoutedDirectEdges;
     /**
      * Analyze graph structure to determine starting nodes and connections
      */

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

@@ -0,0 +1,3 @@
+import type { StandardGraph } from './Graph';
+export type GraphRuntimeConfig = Pick<StandardGraph, 'hookRegistry' | 'humanInTheLoop' | 'toolOutputReferences' | 'eagerEventToolExecution' | 'codeSessionToolNames' | 'interruptingToolNames' | 'toolExecution'>;
+export declare function applyGraphRuntimeConfig(graph: StandardGraph, config: GraphRuntimeConfig): void;

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

@@ -0,0 +1,13 @@
+import type { GraphFactoryRequest } from '@/graphs/graphFactory';
+import type { MultiAgentGraphInput, StandardGraphInput } from '@/types';
+import { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
+import { StandardGraph } from '@/graphs/Graph';
+export declare function createGraph(request: {
+    kind: 'standard';
+    input: StandardGraphInput;
+}): StandardGraph;
+export declare function createGraph(request: {
+    kind: 'multi-agent';
+    input: MultiAgentGraphInput;
+}): MultiAgentGraph;
+export declare function createGraph(request: GraphFactoryRequest): StandardGraph;

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

@@ -0,0 +1,13 @@
+import type { StandardGraph } from './Graph';
+import type * as t from '@/types';
+export type GraphFactoryRequest = {
+    kind: 'standard';
+    input: t.StandardGraphInput;
+} | {
+    kind: 'multi-agent';
+    input: t.MultiAgentGraphInput;
+};
+export type GraphFactory = (request: GraphFactoryRequest) => StandardGraph;
+export type GraphFactoryDependencies = {
+    graphFactory: GraphFactory;
+};

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

@@ -1,2 +1,4 @@
 export * from './Graph';
 export * from './MultiAgentGraph';
+export * from './createGraph';
+export type * from './graphFactory';

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

@@ -1,4 +1,4 @@
-import type { HookEvent, HookMatcher } from './types';
+import type { HookEvent, HookMatcher, ToolApprovalReplayKey, ToolApprovalReplaySnapshot, AggregatedHookResult } from './types';
 /**
  * Snapshot of a halt request raised by a hook returning
  * `preventContinuation: true`. The SDK's run loop polls for this between
@@ -45,6 +45,8 @@ export declare class HookRegistry {
      * O(1) insertion in hot paths, no spread-on-write.
      */
     private readonly haltSignals;
+    /** One-shot hook contributions retained until approval is consumed. */
+    private readonly pendingToolApprovals;
     /**
      * Register a matcher for the lifetime of this registry (= one Run).
      * Returns an unregister function that removes the matcher by reference.
@@ -75,6 +77,13 @@ export declare class HookRegistry {
      * cannot leak into the next session on the same registry.
      */
     clearSession(sessionId: string): void;
+    /** Copies session-scoped policy into a rebuilt or branched Run. */
+    copySession(sourceSessionId: string, targetSessionId: string): void;
+    getPendingToolApproval(sessionId: string, key: ToolApprovalReplayKey): AggregatedHookResult | undefined;
+    setPendingToolApproval(sessionId: string, key: ToolApprovalReplayKey, result: AggregatedHookResult): void;
+    clearPendingToolApproval(sessionId: string, key: ToolApprovalReplayKey): void;
+    snapshotPendingToolApprovals(sessionId: string, executionScope: string): ToolApprovalReplaySnapshot[];
+    restorePendingToolApprovals(sessionId: string, targetExecutionScope: string, snapshots: ReadonlyArray<ToolApprovalReplaySnapshot>): void;
     /**
      * Raise a halt signal scoped to `sessionId` (= the run id the hook
      * fired under). The SDK's run loop polls for this between stream

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

@@ -1,5 +1,5 @@
 import type { Logger } from 'winston';
-import type { HookInput, AggregatedHookResult } from './types';
+import type { HookInput, ToolApprovalReplayKey, AggregatedHookResult } from './types';
 import type { HookRegistry } from './HookRegistry';
 /** Default per-hook timeout when a matcher doesn't set its own. */
 export declare const DEFAULT_HOOK_TIMEOUT_MS = 30000;
@@ -15,6 +15,10 @@ export interface ExecuteHooksOptions {
     sessionId?: string;
     /** Query string matched against each matcher's pattern (tool name, etc.). */
     matchQuery?: string;
+    /** Stable tool-call key for replaying consumed one-shot contributions. */
+    onceReplayKey?: ToolApprovalReplayKey;
+    /** Storage scope for replay state when it must outlive or branch from the hook session. */
+    onceReplaySessionId?: string;
     /** Parent AbortSignal — combined with per-hook timeout into the hook signal. */
     signal?: AbortSignal;
     /** Default per-hook timeout; overridden by `matcher.timeout` when present. */

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

@@ -24,6 +24,6 @@ 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, 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 { HOOK_EVENTS, TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY } from './types';
+export type { HookEvent, HookInput, HookOutput, HookCallback, HookMatcher, HooksByEvent, HookInputByEvent, HookOutputByEvent, BaseHookInput, BaseHookOutput, ToolDecision, StopDecision, ToolApprovalReplayKey, ToolApprovalReplaySnapshot, 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';

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

@@ -9,6 +9,7 @@ import type { InjectedMessage } from '@/types/tools';
  * `@librechat/agents` emission points.
  */
 export declare const HOOK_EVENTS: readonly ["RunStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "PreemptBoundary", "PermissionDenied", "SubagentStart", "SubagentStop", "Stop", "StopFailure", "PreCompact", "PostCompact"];
+export declare const TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY = "__librechat_tool_approval_execution_scope";
 export type HookEvent = (typeof HOOK_EVENTS)[number];
 /** Tool-gating decision; executeHooks folds with `deny > ask > allow` precedence. */
 export type ToolDecision = 'allow' | 'deny' | 'ask';
@@ -331,6 +332,17 @@ export interface PreToolUseHookOutput extends BaseHookOutput {
      */
     allowedDecisions?: ReadonlyArray<'approve' | 'reject' | 'edit' | 'respond'>;
 }
+/** Stable identity for replaying a consumed one-shot tool approval. */
+export interface ToolApprovalReplayKey {
+    executionScope: string;
+    agentId: string;
+    toolUseId: string;
+}
+/** Checkpoint-safe copy of a consumed one-shot approval contribution. */
+export interface ToolApprovalReplaySnapshot {
+    key: ToolApprovalReplayKey;
+    result: AggregatedHookResult;
+}
 export interface PostToolUseHookOutput extends BaseHookOutput {
     /**
      * Replacement tool output. Flows through the aggregated result so the

package/dist/types/run.d.ts

@@ -1,8 +1,9 @@
+import { BaseMessage } from '@langchain/core/messages';
 import { Command } from '@langchain/langgraph';
-import type { MessageContentComplex, BaseMessage } from '@langchain/core/messages';
+import type { MessageContentComplex } from '@langchain/core/messages';
+import type { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
+import type { StandardGraph } from '@/graphs/Graph';
 import type * as t from '@/types';
-import { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
-import { StandardGraph } from '@/graphs/Graph';
 export declare const defaultOmitOptions: Set<string>;
 export declare class Run<_T extends t.BaseGraphState> {
     id: string;
@@ -103,6 +104,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     private runPreStreamHooks;
     static create<T extends t.BaseGraphState>(config: t.RunConfig): Promise<Run<T>>;
     getRunMessages(): BaseMessage[] | undefined;
+    getChildCheckpointThreadIds(): string[];
     /**
      * Returns a defensive snapshot of tools discovered by the current run.
      * Pass an agent id for that context, or omit it for the ordered union across
@@ -220,6 +222,7 @@ export declare class Run<_T extends t.BaseGraphState> {
      */
     resume<TResume = t.ToolApprovalDecision[] | t.ToolApprovalDecisionMap>(resumeValue: TResume, callerConfig: t.RunStreamConfig, streamOptions?: t.EventStreamOptions, commandOptions?: Pick<ConstructorParameters<typeof Command>[0], 'update' | 'goto'>): Promise<MessageContentComplex[] | undefined>;
     private resolveInterruptResumeConfig;
+    private restoreInterruptFromCheckpoint;
     private createSystemCallback;
     getCallbacks(clientCallbacks: t.ClientCallbacks): t.SystemCallbacks;
     generateTitle({ provider, inputText, contentParts, titlePrompt, clientOptions, chainOptions, skipLanguage, titleMethod, titlePromptTemplate, }: t.RunTitleOptions): Promise<{

package/dist/types/session/AgentSession.d.ts

@@ -16,6 +16,7 @@ export declare class AgentSession {
     getLatestCheckpoint(options?: AgentSessionCheckpointLookupOptions): Promise<AgentSessionCheckpointReference | undefined>;
     private hasCheckpointState;
     private recordCheckpoint;
+    private recordChildCheckpointThreads;
     private getCheckpointThreadIds;
     private resetCheckpointThreads;
     private runInternal;

package/dist/types/tools/SubagentTool.d.ts

@@ -2,7 +2,7 @@ import type { JsonSchemaType, LCTool } from '@/types/tools';
 import type { SubagentConfig } from '@/types';
 import { Constants } from '@/common';
 export declare const SubagentToolName = Constants.SUBAGENT;
-export declare const SubagentToolDescription = "Delegate a task to a specialized subagent that runs in an isolated context window. The subagent executes independently and returns only its final text result \u2014 all intermediate tool calls, reasoning, and context stay isolated.\n\nWHEN TO USE:\n- The task is self-contained and can be described in a single prompt.\n- You want to offload verbose or exploratory work without bloating your own context.\n- A specialized subagent is available for the task domain.\n\nWHAT HAPPENS:\n- A fresh agent is created with the task description as its only input.\n- The subagent runs to completion using its own tools and context.\n- Only the final text response is returned to you.\n\nCONSTRAINTS:\n- subagent_type must match one of the available types listed below.\n- The subagent cannot see your conversation history.";
+export declare const SubagentToolDescription = "Delegate a task to a specialized subagent or bounded agent team that runs in an isolated context window. The delegated execution returns only its designated final text result \u2014 all intermediate tool calls, reasoning, and context stay isolated.\n\nWHEN TO USE:\n- The task is self-contained and can be described in a single prompt.\n- You want to offload verbose or exploratory work without bloating your own context.\n- A specialized subagent is available for the task domain.\n\nWHAT HAPPENS:\n- A fresh agent or configured agent graph is created with the task description as its only input.\n- The delegated agent or team runs to completion using isolated tools and context.\n- Only the single agent's final response or the graph's designated result-agent response is returned to you.\n\nCONSTRAINTS:\n- subagent_type must match one of the available types listed below.\n- The subagent cannot see your conversation history.";
 export declare const SubagentToolSchema: {
     readonly type: "object";
     readonly properties: {

package/dist/types/tools/ToolNode.d.ts

@@ -3,6 +3,7 @@ import { END, Command, MessagesAnnotation } from '@langchain/langgraph';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { ToolOutputResolveView, ResolvedArgsByCallId } from '@/tools/toolOutputReferences';
+import type { SubagentToolNodeResumeState } from '@/tools/subagent/SubagentReplay';
 import type * as t from '@/types';
 import { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import { RunnableCallable } from '@/utils';
@@ -50,6 +51,8 @@ type RunToolBatchContext<T = unknown> = {
      * contract for hosts relying on it for policy / recovery guidance.
      */
     additionalContextsSink?: string[];
+    /** Stable identity of the assistant tool-call batch across HITL replay. */
+    replayBatchKey?: string;
     /**
      * Graph state the ToolNode was invoked with, threaded from `run()`
      * so `tool.invoke` can forward it as langgraph 1.4's `runtime.state`
@@ -113,6 +116,10 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * the Run ends.
      */
     private directPathTurns;
+    /** Terminal results from interrupting siblings that must survive a
+     * LangGraph replay of the containing ToolNode. Includes the sidecar data
+     * the fresh batch needs for hook-context injection and completion events. */
+    private settledInterruptingResults;
     /** Tool registry for filtering (lazy computation of programmatic maps) */
     private toolRegistry?;
     /** Cached programmatic tools (computed once on first PTC call) */
@@ -240,12 +247,11 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private shouldHandleUnknownHandoffLocally;
     private getUnknownToolErrorMessage;
     /**
-     * Flush the per-Run direct-path turn cache. Called by the Graph at
-     * end-of-Run via `clearHeavyState`. The map intentionally survives
-     * `run()` re-entry so an interrupt + resume reuses the original
-     * slot (Codex P2 #30), but it would otherwise grow linearly with
-     * tool calls and could collide across Runs if a provider reused
-     * call IDs (Codex P2 #33). Hosts can also call this directly if
+     * Flush per-Run direct replay state. Called by the Graph at end-of-Run via
+     * `clearHeavyState`. The state intentionally survives `run()` re-entry so
+     * interrupt + resume keeps both original turn slots and terminal sibling
+     * outputs, but it would otherwise grow linearly and could collide across
+     * Runs if a provider reused call IDs. Hosts can also call this directly if
      * they reuse a ToolNode across batches outside of a Graph.
      */
     clearDirectPathTurns(): void;
@@ -259,6 +265,8 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * @returns A ReadonlyMap where keys are tool names and values are their usage counts.
      */
     getToolUsageCounts(): ReadonlyMap<string, number>;
+    createSubagentResumeState(): SubagentToolNodeResumeState;
+    restoreSubagentResumeState(state: SubagentToolNodeResumeState): void;
     private recordToolUsageTurn;
     private recordEventToolPlanningTurn;
     /**
@@ -296,9 +304,9 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      *       `blockDirectCall`, `respond` returns the host-supplied
      *       `responseText` as a synthetic success ToolMessage,
      *       `edit` re-runs with edited args. LangGraph re-enters
-     *       ToolNode.run from the start on resume; the hook fires
-     *       again and the resume value distinguishes "first ask" from
-     *       "second pass with decision".
+     *       ToolNode.run from the start on resume. Reusable hooks fire
+     *       again; a consumed one-shot hook replays its pending approval
+     *       result. In both cases `interrupt()` consumes the resume value.
      *     • When HITL is off: collapses to a fail-closed deny (matches
      *       the rest of the SDK's HITL-disabled default). One-time
      *       warning logged so hosts notice the gap.
@@ -465,16 +473,16 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * call throws a `GraphInterrupt`, the `await` below rejects and unwinds the
      * whole ToolNode *before* any non-interrupting sibling has started — so a
      * sibling with real side effects (send_email, billing) never executes on
-     * the first pass. On the resume pass LangGraph re-runs the batch from the
-     * top; the interrupting tool resolves with the host's answer instead of
-     * throwing, and the siblings execute for the FIRST time, exactly once.
+     * the first pass. Terminal interrupting siblings are cached by call id, so
+     * LangGraph replay reuses their complete lifecycle output instead of
+     * repeating model calls, hooks, or side effects.
      *
      * Without this ordering, a flat `Promise.all` starts every sibling
      * concurrently, so a non-idempotent sibling can complete its side effect
      * before the interrupt unwinds and then run a SECOND time on resume — the
-     * duplicate side effect this method exists to prevent. Interrupting tools
-     * are expected to be side-effect-free (they only suspend), so running them
-     * as a group and re-running them on resume is harmless.
+     * duplicate side effect this method exists to prevent. A tool that actually
+     * suspends re-enters until it reaches a terminal result; siblings that
+     * already settled do not re-enter.
      *
      * `batchIndices[i]` is `directCalls[i]`'s position within the parent
      * ToolNode batch (used for `{{tool<i>turn<n>}}` registration); it is