@librechat/agents 3.3.5 → 3.3.6

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

@@ -1 +1 @@
-{"version":3,"file":"toolOutputReferences.mjs","names":[],"sources":["../../../src/tools/toolOutputReferences.ts"],"sourcesContent":["/**\n * Tool output reference registry.\n *\n * When enabled via `RunConfig.toolOutputReferences.enabled`, ToolNode\n * stores each successful tool output under a stable key\n * (`tool<idx>turn<turn>`) where `idx` is the tool's position within a\n * ToolNode batch and `turn` is the batch index within the run\n * (incremented once per ToolNode invocation).\n *\n * Subsequent tool calls can pipe a previous output into their args by\n * embedding `{{tool<idx>turn<turn>}}` inside any string argument;\n * {@link ToolOutputReferenceRegistry.resolve} walks the args and\n * substitutes the placeholders immediately before invocation.\n *\n * The registry stores the *raw, untruncated* tool output so a later\n * `{{…}}` substitution pipes the full payload into the next tool —\n * even when the LLM only saw a head+tail-truncated preview in\n * `ToolMessage.content`. Outputs are stored without any annotation\n * (the `_ref` key or the `[ref: ...]` prefix seen by the LLM is\n * strictly a UX signal attached to `ToolMessage.content`). Keeping the\n * registry pristine means downstream bash/jq piping receives the\n * complete, verbatim output with no injected fields.\n */\n\nimport { ToolMessage } from '@langchain/core/messages';\nimport type { BaseMessage } from '@langchain/core/messages';\nimport {\n  calculateMaxTotalToolOutputSize,\n  HARD_MAX_TOOL_RESULT_CHARS,\n  HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE,\n} from '@/utils/truncation';\nimport { isComputerCallOutputMessage } from '@/utils/toolContent';\n\n/**\n * Non-global matcher for a single `{{tool<i>turn<n>}}` placeholder.\n * Exported for consumers that want to detect references (e.g., syntax\n * highlighting, docs). The stateful `g` variant lives inside the\n * registry so nobody trips on `lastIndex`.\n */\nexport const TOOL_OUTPUT_REF_PATTERN = /\\{\\{(tool\\d+turn\\d+)\\}\\}/;\n\n/** Object key used when a parsed-object output has `_ref` injected. */\nexport const TOOL_OUTPUT_REF_KEY = '_ref';\n\n/**\n * Object key used to carry unresolved reference warnings on a parsed-\n * object output. Using a dedicated field instead of a trailing text\n * line keeps the annotated `ToolMessage.content` parseable as JSON for\n * downstream consumers that rely on the object shape.\n */\nexport const TOOL_OUTPUT_UNRESOLVED_KEY = '_unresolved_refs';\n\n/** Single-line prefix prepended to non-object tool outputs so the LLM sees the reference key. */\nexport function buildReferencePrefix(key: string): string {\n  return `[ref: ${key}]`;\n}\n\n/** Stable registry key for a tool output. */\nexport function buildReferenceKey(toolIndex: number, turn: number): string {\n  return `tool${toolIndex}turn${turn}`;\n}\n\nexport type ToolOutputReferenceRegistryOptions = {\n  /** Maximum characters stored per registered output. */\n  maxOutputSize?: number;\n  /** Maximum total characters retained across all registered outputs. */\n  maxTotalSize?: number;\n  /**\n   * Upper bound on the number of concurrently-tracked runs. When\n   * exceeded, the oldest run bucket is evicted (FIFO). Defaults to 32.\n   */\n  maxActiveRuns?: number;\n};\n\n/**\n * Result of resolving placeholders in tool args.\n */\nexport type ResolveResult<T> = {\n  /** Arguments with placeholders replaced. Same shape as the input. */\n  resolved: T;\n  /** Reference keys that were referenced but had no stored value. */\n  unresolved: string[];\n};\n\n/**\n * Read-only view over a frozen registry snapshot. Returned by\n * {@link ToolOutputReferenceRegistry.snapshot} for callers that need\n * to resolve placeholders against the registry state at a specific\n * point in time, ignoring any subsequent registrations.\n */\nexport interface ToolOutputResolveView {\n  resolve<T>(args: T): ResolveResult<T>;\n}\n\n/**\n * Pre-resolved arg map keyed by `toolCallId`. Used by the mixed\n * direct+event dispatch path to feed event calls' resolved args\n * (captured pre-batch) into the dispatcher without re-resolving\n * against the now-stale live registry.\n */\nexport type PreResolvedArgsMap = Map<\n  string,\n  { resolved: Record<string, unknown>; unresolved: string[] }\n>;\n\n/**\n * Per-call sink for resolved args, keyed by `toolCallId`. Threaded\n * as a per-batch local map so concurrent `ToolNode.run()` calls do\n * not race on shared sink state.\n */\nexport type ResolvedArgsByCallId = Map<string, Record<string, unknown>>;\n\nconst EMPTY_ENTRIES: ReadonlyMap<string, string> = new Map<string, string>();\n\n/**\n * Per-run state bucket held inside the registry. Each distinct\n * `run_id` gets its own bucket so overlapping concurrent runs on a\n * shared registry cannot leak outputs, turn counters, or warn-memos\n * into one another.\n */\nclass RunStateBucket {\n  entries: Map<string, string> = new Map();\n  totalSize: number = 0;\n  turnCounter: number = 0;\n  warnedNonStringTools: Set<string> = new Set();\n}\n\n/**\n * Anonymous (`run_id` absent) bucket key. Anonymous batches are\n * treated as fresh runs on every invocation — see `nextTurn`.\n */\nconst ANON_RUN_KEY = '\\0anon';\n\n/**\n * Default upper bound on the number of concurrently-tracked runs per\n * registry. When exceeded, the oldest run's bucket (by insertion\n * order) is evicted. Keeps memory bounded when a ToolNode is reused\n * across many runs without explicit `releaseRun` calls.\n */\nconst DEFAULT_MAX_ACTIVE_RUNS = 32;\n\n/**\n * Ordered map of reference-key → stored output, partitioned by run so\n * concurrent / interleaved runs sharing one registry cannot leak\n * outputs between each other.\n *\n * Each public method takes a `runId` which selects the run's bucket.\n * Hosts typically get one registry per run via `Graph`, in which\n * case only a single bucket is ever populated; the partitioning\n * exists so the registry also behaves correctly when a single\n * instance is reused directly.\n */\nexport class ToolOutputReferenceRegistry {\n  private runStates: Map<string, RunStateBucket> = new Map();\n  private readonly maxOutputSize: number;\n  private readonly maxTotalSize: number;\n  private readonly maxActiveRuns: number;\n  /**\n   * Local stateful matcher used only by `replaceInString`. Kept\n   * off-module so callers of the exported `TOOL_OUTPUT_REF_PATTERN`\n   * never see a stale `lastIndex`.\n   */\n  private static readonly PLACEHOLDER_MATCHER = /\\{\\{(tool\\d+turn\\d+)\\}\\}/g;\n\n  constructor(options: ToolOutputReferenceRegistryOptions = {}) {\n    /**\n     * Per-output default is the same ~400 KB budget as the standard\n     * tool-result truncation (`HARD_MAX_TOOL_RESULT_CHARS`). This\n     * keeps a single `{{…}}` substitution at a size that is safe to\n     * pass through typical shell `ARG_MAX` limits and matches what\n     * the LLM would otherwise have seen. Hosts that want larger per-\n     * output payloads (API consumers, long JSON streams) can raise\n     * the cap explicitly up to the 5 MB total budget.\n     */\n    const perOutput =\n      options.maxOutputSize != null && options.maxOutputSize > 0\n        ? options.maxOutputSize\n        : HARD_MAX_TOOL_RESULT_CHARS;\n    /**\n     * Clamp a caller-supplied `maxTotalSize` to\n     * `HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE` (5 MB) so the documented\n     * absolute cap is enforced regardless of host config —\n     * `calculateMaxTotalToolOutputSize` already applies the same\n     * upper bound on its computed default, but the user-provided\n     * branch was bypassing it.\n     */\n    const totalRaw =\n      options.maxTotalSize != null && options.maxTotalSize > 0\n        ? Math.min(options.maxTotalSize, HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE)\n        : calculateMaxTotalToolOutputSize(perOutput);\n    this.maxTotalSize = totalRaw;\n    /**\n     * The per-output cap can never exceed the per-run aggregate cap:\n     * if a single entry were allowed to be larger than `maxTotalSize`,\n     * the eviction loop would either blow the cap (to keep the entry)\n     * or self-evict a just-stored value. Clamping here turns\n     * `maxTotalSize` into a hard upper bound on *any* state the\n     * registry retains per run.\n     */\n    this.maxOutputSize = Math.min(perOutput, totalRaw);\n    this.maxActiveRuns =\n      options.maxActiveRuns != null && options.maxActiveRuns > 0\n        ? options.maxActiveRuns\n        : DEFAULT_MAX_ACTIVE_RUNS;\n  }\n\n  private keyFor(runId: string | undefined): string {\n    return runId ?? ANON_RUN_KEY;\n  }\n\n  private getOrCreate(runId: string | undefined): RunStateBucket {\n    const key = this.keyFor(runId);\n    let state = this.runStates.get(key);\n    if (state == null) {\n      state = new RunStateBucket();\n      this.runStates.set(key, state);\n      if (this.runStates.size > this.maxActiveRuns) {\n        const oldest = this.runStates.keys().next().value;\n        if (oldest != null && oldest !== key) {\n          this.runStates.delete(oldest);\n        }\n      }\n    }\n    return state;\n  }\n\n  /** Registers (or replaces) the output stored under `key` for `runId`. */\n  set(runId: string | undefined, key: string, value: string): void {\n    const bucket = this.getOrCreate(runId);\n    const clipped =\n      value.length > this.maxOutputSize\n        ? value.slice(0, this.maxOutputSize)\n        : value;\n    const existing = bucket.entries.get(key);\n    if (existing != null) {\n      bucket.totalSize -= existing.length;\n      bucket.entries.delete(key);\n    }\n    bucket.entries.set(key, clipped);\n    bucket.totalSize += clipped.length;\n    this.evictWithinBucket(bucket);\n  }\n\n  /** Returns the stored value for `key` in `runId`'s bucket, or `undefined`. */\n  get(runId: string | undefined, key: string): string | undefined {\n    return this.runStates.get(this.keyFor(runId))?.entries.get(key);\n  }\n\n  /**\n   * Returns `true` when `key` is currently stored in `runId`'s bucket.\n   * Used by {@link annotateMessagesForLLM} to gate transient annotation\n   * on whether the registry still owns the referenced output (a stale\n   * `_refKey` from a prior run silently no-ops here).\n   */\n  has(runId: string | undefined, key: string): boolean {\n    return this.runStates.get(this.keyFor(runId))?.entries.has(key) ?? false;\n  }\n\n  /** Total number of registered outputs across every run bucket. */\n  get size(): number {\n    let n = 0;\n    for (const bucket of this.runStates.values()) {\n      n += bucket.entries.size;\n    }\n    return n;\n  }\n\n  /** Maximum characters retained per output (post-clip). */\n  get perOutputLimit(): number {\n    return this.maxOutputSize;\n  }\n\n  /** Maximum total characters retained *per run*. */\n  get totalLimit(): number {\n    return this.maxTotalSize;\n  }\n\n  /** Drops every run's state. */\n  clear(): void {\n    this.runStates.clear();\n  }\n\n  /**\n   * Explicitly release `runId`'s state. Safe to call when a run has\n   * finished. Hosts sharing one registry across runs should call this\n   * to reclaim memory deterministically; otherwise LRU eviction kicks\n   * in when `maxActiveRuns` runs accumulate.\n   */\n  releaseRun(runId: string | undefined): void {\n    this.runStates.delete(this.keyFor(runId));\n  }\n\n  /**\n   * Claims the next batch turn synchronously from `runId`'s bucket.\n   *\n   * Must be called once at the start of each ToolNode batch before\n   * any `await`, so concurrent invocations within the same run see\n   * distinct turn values (reads are effectively atomic by JS's\n   * single-threaded execution of the sync prefix).\n   *\n   * If `runId` is missing the anonymous bucket is dropped and a\n   * fresh one created so each anonymous call behaves as its own run.\n   */\n  nextTurn(runId: string | undefined): number {\n    if (runId == null) {\n      this.runStates.delete(ANON_RUN_KEY);\n    }\n    const bucket = this.getOrCreate(runId);\n    return bucket.turnCounter++;\n  }\n\n  /**\n   * Records that `toolName` has been warned about in `runId` (returns\n   * `true` on the first call per run, `false` after). Used by\n   * ToolNode to emit one log line per offending tool per run when a\n   * `ToolMessage.content` isn't a string.\n   */\n  claimWarnOnce(runId: string | undefined, toolName: string): boolean {\n    const bucket = this.getOrCreate(runId);\n    if (bucket.warnedNonStringTools.has(toolName)) {\n      return false;\n    }\n    bucket.warnedNonStringTools.add(toolName);\n    return true;\n  }\n\n  /**\n   * Walks `args` and replaces every `{{tool<i>turn<n>}}` placeholder in\n   * string values with the stored output *from `runId`'s bucket*. Non-\n   * string values and object keys are left untouched. Unresolved\n   * references are left in-place and reported so the caller can\n   * surface them to the LLM. When no placeholder appears anywhere in\n   * the serialized args, the original input is returned without\n   * walking the tree.\n   */\n  resolve<T>(runId: string | undefined, args: T): ResolveResult<T> {\n    if (!hasAnyPlaceholder(args)) {\n      return { resolved: args, unresolved: [] };\n    }\n    const bucket = this.runStates.get(this.keyFor(runId));\n    return this.resolveAgainst(bucket?.entries ?? EMPTY_ENTRIES, args);\n  }\n\n  /**\n   * Captures a frozen snapshot of `runId`'s current entries and\n   * returns a view that resolves placeholders against *only* that\n   * snapshot. The snapshot is decoupled from the live registry, so\n   * subsequent `set()` calls (for example, same-turn direct outputs\n   * registering while an event branch is still in flight) are\n   * invisible to the snapshot's `resolve`. Used by the mixed\n   * direct+event dispatch path to preserve same-turn isolation when\n   * a `PreToolUse` hook rewrites event args after directs have\n   * completed.\n   */\n  snapshot(runId: string | undefined): ToolOutputResolveView {\n    const bucket = this.runStates.get(this.keyFor(runId));\n    const entries: ReadonlyMap<string, string> = bucket\n      ? new Map(bucket.entries)\n      : EMPTY_ENTRIES;\n    return {\n      resolve: <T>(args: T): ResolveResult<T> =>\n        this.resolveAgainst(entries, args),\n    };\n  }\n\n  private resolveAgainst<T>(\n    entries: ReadonlyMap<string, string>,\n    args: T\n  ): ResolveResult<T> {\n    if (!hasAnyPlaceholder(args)) {\n      return { resolved: args, unresolved: [] };\n    }\n    const unresolved = new Set<string>();\n    const resolved = this.transform(entries, args, unresolved) as T;\n    return { resolved, unresolved: Array.from(unresolved) };\n  }\n\n  private transform(\n    entries: ReadonlyMap<string, string>,\n    value: unknown,\n    unresolved: Set<string>\n  ): unknown {\n    if (typeof value === 'string') {\n      return this.replaceInString(entries, value, unresolved);\n    }\n    if (Array.isArray(value)) {\n      return value.map((item) => this.transform(entries, item, unresolved));\n    }\n    if (value !== null && typeof value === 'object') {\n      const source = value as Record<string, unknown>;\n      const next: Record<string, unknown> = {};\n      for (const [key, item] of Object.entries(source)) {\n        next[key] = this.transform(entries, item, unresolved);\n      }\n      return next;\n    }\n    return value;\n  }\n\n  private replaceInString(\n    entries: ReadonlyMap<string, string>,\n    input: string,\n    unresolved: Set<string>\n  ): string {\n    if (input.indexOf('{{tool') === -1) {\n      return input;\n    }\n    return input.replace(\n      ToolOutputReferenceRegistry.PLACEHOLDER_MATCHER,\n      (match, key: string) => {\n        const stored = entries.get(key);\n        if (stored == null) {\n          unresolved.add(key);\n          return match;\n        }\n        return stored;\n      }\n    );\n  }\n\n  private evictWithinBucket(bucket: RunStateBucket): void {\n    if (bucket.totalSize <= this.maxTotalSize) {\n      return;\n    }\n    for (const key of bucket.entries.keys()) {\n      if (bucket.totalSize <= this.maxTotalSize) {\n        return;\n      }\n      const entry = bucket.entries.get(key);\n      if (entry == null) {\n        continue;\n      }\n      bucket.totalSize -= entry.length;\n      bucket.entries.delete(key);\n    }\n  }\n}\n\n/**\n * Cheap pre-check: returns true if any string value in `args` contains\n * the `{{tool` substring. Lets `resolve()` skip the deep tree walk (and\n * its object allocations) for the common case of plain args.\n */\nfunction hasAnyPlaceholder(value: unknown): boolean {\n  if (typeof value === 'string') {\n    return value.indexOf('{{tool') !== -1;\n  }\n  if (Array.isArray(value)) {\n    for (const item of value) {\n      if (hasAnyPlaceholder(item)) {\n        return true;\n      }\n    }\n    return false;\n  }\n  if (value !== null && typeof value === 'object') {\n    for (const item of Object.values(value as Record<string, unknown>)) {\n      if (hasAnyPlaceholder(item)) {\n        return true;\n      }\n    }\n    return false;\n  }\n  return false;\n}\n\n/**\n * Annotates `content` with a reference key and/or unresolved-ref\n * warnings so the LLM sees both alongside the tool output.\n *\n * Behavior:\n *  - If `content` parses as a plain (non-array, non-null) JSON object\n *    and the object does not already have a conflicting `_ref` key,\n *    the reference key and (when present) `_unresolved_refs` array\n *    are injected as object fields, preserving JSON validity for\n *    downstream consumers that parse the output.\n *  - Otherwise (string output, JSON array/primitive, parse failure,\n *    or `_ref` collision), a `[ref: <key>]\\n` prefix line is\n *    prepended and unresolved refs are appended as a trailing\n *    `[unresolved refs: …]` line.\n *\n * The annotated string is what the LLM sees as `ToolMessage.content`.\n * The *original* (un-annotated) value is what gets stored in the\n * registry, so downstream piping remains pristine.\n *\n * @param content     Raw (post-truncation) tool output.\n * @param key         Reference key for this output, or undefined when\n *                    there is nothing to register (errors etc.).\n * @param unresolved  Reference keys that failed to resolve during\n *                    argument substitution. Surfaced so the LLM can\n *                    self-correct its next tool call.\n */\nexport function annotateToolOutputWithReference(\n  content: string,\n  key: string | undefined,\n  unresolved: string[] = []\n): string {\n  const hasRefKey = key != null;\n  const hasUnresolved = unresolved.length > 0;\n  if (!hasRefKey && !hasUnresolved) {\n    return content;\n  }\n  const trimmed = content.trimStart();\n  if (trimmed.startsWith('{')) {\n    const annotated = tryInjectRefIntoJsonObject(content, key, unresolved);\n    if (annotated != null) {\n      return annotated;\n    }\n  }\n  const prefix = hasRefKey ? `${buildReferencePrefix(key!)}\\n` : '';\n  const trailer = hasUnresolved\n    ? `\\n[unresolved refs: ${unresolved.join(', ')}]`\n    : '';\n  return `${prefix}${content}${trailer}`;\n}\n\nfunction tryInjectRefIntoJsonObject(\n  content: string,\n  key: string | undefined,\n  unresolved: string[]\n): string | null {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(content);\n  } catch {\n    return null;\n  }\n\n  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {\n    return null;\n  }\n\n  const obj = parsed as Record<string, unknown>;\n  const injectingRef = key != null;\n  const injectingUnresolved = unresolved.length > 0;\n\n  /**\n   * Reject the JSON-injection path (fall back to prefix form) when\n   * either of our keys collides with real payload data:\n   *  - `_ref` collision: existing value is non-null and differs from\n   *    the key we're about to inject.\n   *  - `_unresolved_refs` collision: existing value is non-null and\n   *    is not a deep-equal match for the array we'd inject.\n   * This keeps us from silently overwriting legitimate tool output.\n   */\n  if (\n    injectingRef &&\n    TOOL_OUTPUT_REF_KEY in obj &&\n    obj[TOOL_OUTPUT_REF_KEY] !== key &&\n    obj[TOOL_OUTPUT_REF_KEY] != null\n  ) {\n    return null;\n  }\n  if (\n    injectingUnresolved &&\n    TOOL_OUTPUT_UNRESOLVED_KEY in obj &&\n    obj[TOOL_OUTPUT_UNRESOLVED_KEY] != null &&\n    !arraysShallowEqual(obj[TOOL_OUTPUT_UNRESOLVED_KEY], unresolved)\n  ) {\n    return null;\n  }\n\n  /**\n   * Only strip the framework-owned key we're actually injecting —\n   * leave everything else (including a pre-existing `_ref` on the\n   * unresolved-only path, or a pre-existing `_unresolved_refs` on a\n   * plain-annotation path) untouched so we annotate rather than\n   * mutate downstream payload data. Our injected keys land first in\n   * the serialized JSON so the LLM sees them before the body.\n   */\n  const omitKeys = new Set<string>();\n  if (injectingRef) omitKeys.add(TOOL_OUTPUT_REF_KEY);\n  if (injectingUnresolved) omitKeys.add(TOOL_OUTPUT_UNRESOLVED_KEY);\n  const rest: Record<string, unknown> = {};\n  for (const [k, v] of Object.entries(obj)) {\n    if (!omitKeys.has(k)) {\n      rest[k] = v;\n    }\n  }\n  const injected: Record<string, unknown> = {};\n  if (injectingRef) {\n    injected[TOOL_OUTPUT_REF_KEY] = key;\n  }\n  if (injectingUnresolved) {\n    injected[TOOL_OUTPUT_UNRESOLVED_KEY] = unresolved;\n  }\n  Object.assign(injected, rest);\n\n  const pretty = /^\\{\\s*\\n/.test(content);\n  return pretty ? JSON.stringify(injected, null, 2) : JSON.stringify(injected);\n}\n\nfunction arraysShallowEqual(a: unknown, b: readonly string[]): boolean {\n  if (!Array.isArray(a) || a.length !== b.length) {\n    return false;\n  }\n  for (let i = 0; i < a.length; i++) {\n    if (a[i] !== b[i]) {\n      return false;\n    }\n  }\n  return true;\n}\n\n/**\n * Lazy projection that, given a registry and a runId, returns a new\n * `messages` array where each `ToolMessage` carrying ref metadata is\n * projected into a transient copy with annotated content (when the ref\n * is live in the registry) and with the framework-owned `additional_\n * kwargs` keys (`_refKey`, `_refScope`, `_unresolvedRefs`) stripped\n * regardless of whether annotation applied. The original input array\n * and its messages are never mutated.\n *\n * Annotation is gated on registry presence: a stale `_refKey` from a\n * prior run (e.g. one that survived in persisted history) silently\n * no-ops on the *content* side. The strip-metadata side still runs so\n * stale framework keys never leak onto the wire under any custom or\n * future provider serializer that might transmit `additional_kwargs`.\n * `_unresolvedRefs` is always meaningful and is not gated.\n *\n * **Feature-disabled fast path:** when the host hasn't enabled the\n * tool-output-reference feature, the registry is `undefined` and this\n * function returns the input array reference-equal *without iterating\n * a single message*. The loop is exclusive to the feature-enabled\n * code path.\n */\nexport function annotateMessagesForLLM(\n  messages: BaseMessage[],\n  registry: ToolOutputReferenceRegistry | undefined,\n  runId: string | undefined\n): BaseMessage[] {\n  if (registry == null) return messages;\n\n  /**\n   * Lazy-allocate the output array so the common case (no ToolMessage\n   * carries framework metadata) returns the input reference-equal with\n   * zero allocations beyond the per-message predicate checks.\n   */\n  let out: BaseMessage[] | undefined;\n  for (let i = 0; i < messages.length; i++) {\n    const m = messages[i];\n    if (m._getType() !== 'tool') continue;\n    /**\n     * `additional_kwargs` is untyped at the LangChain layer\n     * (`Record<string, unknown>`), so persisted or client-supplied\n     * ToolMessages can carry arbitrary shapes — including primitives\n     * (a malformed serializer might write a string, or `null`).\n     * Guard with a runtime object check before the `in` probes\n     * because the `in` operator throws `TypeError` on primitives.\n     * A single malformed message must never crash the provider call\n     * path; skip its annotation/strip and continue.\n     */\n    const rawMeta = m.additional_kwargs as unknown;\n    if (rawMeta == null || typeof rawMeta !== 'object') continue;\n    const meta = rawMeta as Record<string, unknown>;\n    const hasRefKey = '_refKey' in meta;\n    const hasRefScope = '_refScope' in meta;\n    const hasUnresolvedField = '_unresolvedRefs' in meta;\n    if (!hasRefKey && !hasRefScope && !hasUnresolvedField) continue;\n    if (isComputerCallOutputMessage(m)) {\n      out ??= messages.slice();\n      out[i] = cloneToolMessageWithContent(m as ToolMessage, m.content);\n      continue;\n    }\n\n    const refKey = readRefKey(meta);\n    const unresolved = readUnresolvedRefs(meta);\n\n    /**\n     * Prefer the message-stamped `_refScope` for the registry lookup.\n     * For named runs it equals the current `runId`; for anonymous\n     * invocations it carries the per-batch synthetic scope minted by\n     * ToolNode (`\\0anon-<n>`), which `runId` from config cannot\n     * recover. Falling back to `runId` keeps backward compatibility\n     * with messages stamped before this field existed.\n     */\n    const lookupScope = readRefScope(meta) ?? runId;\n    const liveRef =\n      refKey != null && registry.has(lookupScope, refKey) ? refKey : undefined;\n    const annotates = liveRef != null || unresolved.length > 0;\n\n    const tm = m as ToolMessage;\n    let nextContent: ToolMessage['content'] = tm.content;\n\n    if (annotates && typeof tm.content === 'string') {\n      nextContent = annotateToolOutputWithReference(\n        tm.content,\n        liveRef,\n        unresolved\n      );\n    } else if (annotates && Array.isArray(tm.content)) {\n      /**\n       * Array tool content. The string annotator can't run — this notably\n       * includes a tail tool result that prompt caching rewrote from a string\n       * into a text-block array to host its `cache_control` / `cachePoint`\n       * marker (the `_refKey` survives on `additional_kwargs`). Project the\n       * same markers the string path would, as leading text blocks: the live\n       * `[ref: …]` prefix and/or the unresolved-refs warning. Without this the\n       * common tool-result tail loses its reference marker once cached.\n       *\n       * `as unknown as ToolMessage['content']` is unavoidable: LangChain's\n       * content union does not accept a freshly built mixed array literal even\n       * though the structural shape is valid at runtime. The double-cast is\n       * structurally safe — every original block is preserved and only\n       * `{ type: 'text', text }` blocks (which all providers accept) are\n       * prepended.\n       */\n      const prefixBlocks: Array<{ type: 'text'; text: string }> = [];\n      if (liveRef != null) {\n        prefixBlocks.push({\n          type: 'text',\n          text: buildReferencePrefix(liveRef),\n        });\n      }\n      if (unresolved.length > 0) {\n        prefixBlocks.push({\n          type: 'text',\n          text: `[unresolved refs: ${unresolved.join(', ')}]`,\n        });\n      }\n      if (prefixBlocks.length > 0) {\n        nextContent = [\n          ...prefixBlocks,\n          ...tm.content,\n        ] as unknown as ToolMessage['content'];\n      }\n    }\n\n    /**\n     * Project unconditionally: even when no annotation applies (stale\n     * `_refKey` or non-annotatable content), `cloneToolMessageWithContent`\n     * runs `stripFrameworkRefMetadata` on `additional_kwargs` so the\n     * framework-owned keys never reach the wire.\n     */\n    out ??= messages.slice();\n    out[i] = cloneToolMessageWithContent(tm, nextContent);\n  }\n\n  return out ?? messages;\n}\n\n/**\n * Reads `_refKey` defensively from untyped `additional_kwargs`. Returns\n * undefined for non-string values so a malformed field cannot poison\n * the registry lookup or downstream string operations.\n */\nfunction readRefKey(\n  meta: Record<string, unknown> | undefined\n): string | undefined {\n  const v = meta?._refKey;\n  return typeof v === 'string' ? v : undefined;\n}\n\n/**\n * Reads `_refScope` defensively from untyped `additional_kwargs`.\n * Mirrors {@link readRefKey} — non-string scopes are dropped (the\n * caller falls back to the run-derived scope) rather than passed into\n * the registry as a malformed key.\n */\nfunction readRefScope(\n  meta: Record<string, unknown> | undefined\n): string | undefined {\n  const v = meta?._refScope;\n  return typeof v === 'string' ? v : undefined;\n}\n\n/**\n * Reads `_unresolvedRefs` defensively from untyped `additional_kwargs`.\n * Returns an empty array for any non-array value, and filters out\n * non-string entries from a real array. Without this guard, a hydrated\n * ToolMessage carrying e.g. `_unresolvedRefs: 'tool0turn0'` would crash\n * `attemptInvoke` on the eventual `.length` / `.join(...)` call.\n */\nfunction readUnresolvedRefs(\n  meta: Record<string, unknown> | undefined\n): string[] {\n  const v = meta?._unresolvedRefs;\n  if (!Array.isArray(v)) return [];\n  const out: string[] = [];\n  for (const item of v) {\n    if (typeof item === 'string') out.push(item);\n  }\n  return out;\n}\n\n/**\n * Builds a fresh `ToolMessage` that mirrors `tm`'s identity fields with\n * the supplied `content`. Every `ToolMessage` field but `content` is\n * carried over so the projection is structurally identical to the\n * original from a LangChain serializer's perspective.\n *\n * `additional_kwargs` is rebuilt with the framework-owned ref keys\n * stripped. Defensive: LangChain's standard provider serializers do not\n * transmit `additional_kwargs` to provider HTTP APIs, but a custom\n * adapter or future LangChain change could. Stripping keeps the\n * implementation correct under any serializer behavior at the cost of a\n * shallow object spread per annotated message.\n */\nfunction cloneToolMessageWithContent(\n  tm: ToolMessage,\n  content: ToolMessage['content']\n): ToolMessage {\n  return new ToolMessage({\n    id: tm.id,\n    name: tm.name,\n    status: tm.status,\n    artifact: tm.artifact,\n    tool_call_id: tm.tool_call_id,\n    response_metadata: tm.response_metadata,\n    additional_kwargs: stripFrameworkRefMetadata(tm.additional_kwargs),\n    content,\n  });\n}\n\n/**\n * Returns a copy of `kwargs` with `_refKey`, `_refScope`, and\n * `_unresolvedRefs` removed. Returns the input reference-equal when\n * none of those keys are present so the no-strip path stays cheap;\n * returns `undefined` when stripping leaves the object empty so the\n * caller can drop the field entirely.\n */\nfunction stripFrameworkRefMetadata(\n  kwargs: Record<string, unknown> | undefined\n): Record<string, unknown> | undefined {\n  if (kwargs == null) return undefined;\n  if (\n    !('_refKey' in kwargs) &&\n    !('_refScope' in kwargs) &&\n    !('_unresolvedRefs' in kwargs)\n  ) {\n    return kwargs;\n  }\n  const { _refKey, _refScope, _unresolvedRefs, ...rest } = kwargs as Record<\n    string,\n    unknown\n  > & {\n    _refKey?: unknown;\n    _refScope?: unknown;\n    _unresolvedRefs?: unknown;\n  };\n  void _refKey;\n  void _refScope;\n  void _unresolvedRefs;\n  return Object.keys(rest).length === 0 ? undefined : rest;\n}\n"],"mappings":"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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 (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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"}

package/dist/types/index.d.ts

@@ -17,6 +17,7 @@ export * from './tools/ReadFile';
 export * from './tools/skillCatalog';
 export * from './tools/ToolSearch';
 export * from './tools/ToolNode';
+export * from './tools/intentArg';
 export * from './tools/schema';
 export * from './tools/handlers';
 export * from './tools/local';

package/dist/types/llm/openai/index.d.ts

@@ -42,17 +42,6 @@ export declare function shouldIncludeEncryptedReasoning(model: string, params: {
     reasoning?: unknown;
 }): boolean;
 export declare function emitStreamChunkCallback(chunk: ChatGenerationChunk, runManager?: CallbackManagerForLLMRun): Promise<void>;
-/**
- * Formats a tool in either OpenAI format, or LangChain structured tool format
- * into an OpenAI tool format. If the tool is already in OpenAI format, return without
- * any changes. If it is in LangChain structured tool format, convert it to OpenAI tool format
- * using OpenAI's `zodFunction` util, falling back to `convertToOpenAIFunction` if the parameters
- * returned from the `zodFunction` util are not defined.
- *
- * @param {BindToolsInput} tool The tool to convert to an OpenAI tool.
- * @param {Object} [fields] Additional fields to add to the OpenAI tool.
- * @returns {ToolDefinition} The inputted tool in OpenAI tool format.
- */
 export declare function _convertToOpenAITool(tool: BindToolsInput, fields?: {
     /**
      * If `true`, model output is guaranteed to exactly match the JSON Schema

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

@@ -4,6 +4,15 @@ import { Constants } from '@/common';
 export declare const BashExecutionToolSchema: {
     readonly type: "object";
     readonly properties: {
+        readonly intent: {
+            readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+            readonly enum?: string[];
+            readonly items?: t.JsonSchemaType;
+            readonly properties?: Record<string, t.JsonSchemaType>;
+            readonly required?: string[];
+            readonly description?: string;
+            readonly additionalProperties?: boolean | t.JsonSchemaType;
+        };
         readonly command: {
             readonly type: "string";
             readonly description: "The bash command or script to execute.\n- The environment is stateless; variables and state don't persist between executions.\n- Prior /mnt/data files are available and can be modified in place.\n- Persist handoff artifacts in `/mnt/data` with standard extensions (.json/.txt/.csv/.tsv/.log/.parquet/.png/.jpg/.pdf/.xlsx); failed executions do not register new files; `/tmp` and odd extensions are same-call scratch only, not later-call storage.\n- Bash: multi-line files use heredoc/printf; run Python via python3 -c/heredoc, not bare Python.\n- Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.\n- Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.\n- IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.\n- Use `echo`, `printf`, or `cat` for all outputs.";
@@ -71,6 +80,15 @@ export declare const BashExecutionToolDefinition: {
     readonly schema: {
         readonly type: "object";
         readonly properties: {
+            readonly intent: {
+                readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+                readonly enum?: string[];
+                readonly items?: t.JsonSchemaType;
+                readonly properties?: Record<string, t.JsonSchemaType>;
+                readonly required?: string[];
+                readonly description?: string;
+                readonly additionalProperties?: boolean | t.JsonSchemaType;
+            };
             readonly command: {
                 readonly type: "string";
                 readonly description: "The bash command or script to execute.\n- The environment is stateless; variables and state don't persist between executions.\n- Prior /mnt/data files are available and can be modified in place.\n- Persist handoff artifacts in `/mnt/data` with standard extensions (.json/.txt/.csv/.tsv/.log/.parquet/.png/.jpg/.pdf/.xlsx); failed executions do not register new files; `/tmp` and odd extensions are same-call scratch only, not later-call storage.\n- Bash: multi-line files use heredoc/printf; run Python via python3 -c/heredoc, not bare Python.\n- Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.\n- Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.\n- IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.\n- Use `echo`, `printf`, or `cat` for all outputs.";

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

@@ -13,6 +13,15 @@ export declare function appendFailedExecutionFileReminder(output: string, code:
 export declare const CodeExecutionToolSchema: {
     readonly type: "object";
     readonly properties: {
+        readonly intent: {
+            readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+            readonly enum?: string[];
+            readonly items?: t.JsonSchemaType;
+            readonly properties?: Record<string, t.JsonSchemaType>;
+            readonly required?: string[];
+            readonly description?: string;
+            readonly additionalProperties?: boolean | t.JsonSchemaType;
+        };
         readonly lang: {
             readonly type: "string";
             readonly enum: readonly ["py", "js", "ts", "c", "cpp", "java", "php", "rs", "go", "d", "f90", "r", "bash"];
@@ -74,6 +83,15 @@ export declare const CodeExecutionToolDefinition: {
     readonly schema: {
         readonly type: "object";
         readonly properties: {
+            readonly intent: {
+                readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+                readonly enum?: string[];
+                readonly items?: t.JsonSchemaType;
+                readonly properties?: Record<string, t.JsonSchemaType>;
+                readonly required?: string[];
+                readonly description?: string;
+                readonly additionalProperties?: boolean | t.JsonSchemaType;
+            };
             readonly lang: {
                 readonly type: "string";
                 readonly enum: readonly ["py", "js", "ts", "c", "cpp", "java", "php", "rs", "go", "d", "f90", "r", "bash"];

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

@@ -4,6 +4,15 @@ export declare const ReadFileToolDescription = "Read the contents of a file. Ret
 export declare const ReadFileToolSchema: {
     readonly type: "object";
     readonly properties: {
+        readonly intent: {
+            readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+            readonly enum?: string[];
+            readonly items?: import("..").JsonSchemaType;
+            readonly properties?: Record<string, import("..").JsonSchemaType>;
+            readonly required?: string[];
+            readonly description?: string;
+            readonly additionalProperties?: boolean | import("..").JsonSchemaType;
+        };
         readonly path: {
             readonly type: "string";
             readonly description: "Path to the file. For skill files: \"{skillName}/{path}\" (e.g. \"pdf-analyzer/src/utils.py\"). For code execution output: the path as returned by the execution tool.";
@@ -17,6 +26,15 @@ export declare const ReadFileToolDefinition: {
     readonly parameters: {
         readonly type: "object";
         readonly properties: {
+            readonly intent: {
+                readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+                readonly enum?: string[];
+                readonly items?: import("..").JsonSchemaType;
+                readonly properties?: Record<string, import("..").JsonSchemaType>;
+                readonly required?: string[];
+                readonly description?: string;
+                readonly additionalProperties?: boolean | import("..").JsonSchemaType;
+            };
             readonly path: {
                 readonly type: "string";
                 readonly description: "Path to the file. For skill files: \"{skillName}/{path}\" (e.g. \"pdf-analyzer/src/utils.py\"). For code execution output: the path as returned by the execution tool.";

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

@@ -9,6 +9,15 @@ export declare const SkillToolDescription = "Invoke a skill from the user's libr
 export declare const SkillToolSchema: {
     readonly type: "object";
     readonly properties: {
+        readonly intent: {
+            readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+            readonly enum?: string[];
+            readonly items?: import("..").JsonSchemaType;
+            readonly properties?: Record<string, import("..").JsonSchemaType>;
+            readonly required?: string[];
+            readonly description?: string;
+            readonly additionalProperties?: boolean | import("..").JsonSchemaType;
+        };
         readonly skillName: {
             readonly type: "string";
             readonly description: "The kebab-case identifier of the skill to invoke (e.g. \"financial-analyzer\", \"meeting-notes\"). Must match a name from the \"Available Skills\" section.";
@@ -26,6 +35,15 @@ export declare const SkillToolDefinition: {
     readonly parameters: {
         readonly type: "object";
         readonly properties: {
+            readonly intent: {
+                readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+                readonly enum?: string[];
+                readonly items?: import("..").JsonSchemaType;
+                readonly properties?: Record<string, import("..").JsonSchemaType>;
+                readonly required?: string[];
+                readonly description?: string;
+                readonly additionalProperties?: boolean | import("..").JsonSchemaType;
+            };
             readonly skillName: {
                 readonly type: "string";
                 readonly description: "The kebab-case identifier of the skill to invoke (e.g. \"financial-analyzer\", \"meeting-notes\"). Must match a name from the \"Available Skills\" section.";

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

@@ -6,6 +6,15 @@ export declare const SubagentToolDescription = "Delegate a task to a specialized
 export declare const SubagentToolSchema: {
     readonly type: "object";
     readonly properties: {
+        readonly intent: {
+            readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+            readonly enum?: string[];
+            readonly items?: JsonSchemaType;
+            readonly properties?: Record<string, JsonSchemaType>;
+            readonly required?: string[];
+            readonly description?: string;
+            readonly additionalProperties?: boolean | JsonSchemaType;
+        };
         readonly description: {
             readonly type: "string";
             readonly description: "Complete task description for the subagent. This is the ONLY information it receives — include all necessary context, requirements, and constraints.";

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

@@ -57,7 +57,32 @@ type RunToolBatchContext<T = unknown> = {
      * which relies on `node:async_hooks` and is browser-incompatible).
      */
     runInput?: T;
+    /** Batch-local error-completion ownership (see {@link ToolErrorOwnership}). */
+    errorOwnership?: ToolErrorOwnership;
 };
+/**
+ * Batch-local record of who owns each failed call's completion event.
+ *
+ * Kept per invocation rather than on the instance: tool-call ids are
+ * provider-scoped (and synthetic ids can repeat), so concurrent `run()`s on
+ * one ToolNode would otherwise share and cross-consume these markers — one
+ * invocation's thrown-error marker suppressing another's only completion,
+ * or leaving a stale marker behind when an interrupt aborts a batch before
+ * the output loop reads it.
+ *
+ * - `handlerOwned`: the errorHandler ran and dispatched (or threw — a throw
+ *   is not proof it didn't dispatch). The output loop must skip these.
+ * - `undispatched`: the handler explicitly reported it could NOT dispatch,
+ *   so the output loop owns the completion instead.
+ *
+ * A call in NEITHER set returned an error `ToolMessage` without ever
+ * entering the catch path, so the output loop owns it too.
+ */
+export type ToolErrorOwnership = {
+    handlerOwned: Set<string>;
+    undispatched: Set<string>;
+};
+export declare function createToolErrorOwnership(): ToolErrorOwnership;
 export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private toolMap;
     private loadRuntimeTools?;
@@ -68,12 +93,12 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     toolCallStepIds?: Map<string, string>;
     errorHandler?: t.ToolNodeConstructorParams['errorHandler'];
     /**
-     * Tool call ids whose `errorHandler` did NOT dispatch the error completion
-     * event (it returned `false` or threw). The output loop must dispatch the
-     * completion for these itself — skipping them there would strand the
-     * client's tool-call part without a terminal event.
+     * Fallback error-completion ownership for calls that reach `runTool`
+     * outside a batch context (direct `runTool` use in tests / embedders).
+     * Batch-scoped ownership is threaded via `RunToolBatchContext` instead —
+     * see {@link ToolErrorOwnership} for why per-invocation scoping matters.
      */
-    private undispatchedToolErrors;
+    private looseErrorOwnership;
     private toolUsageCount;
     /** Maps toolCallId → turn captured in runTool, used by handleRunToolCompletions */
     private toolCallTurns;
@@ -392,6 +417,13 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * those arrays and consumes them right after this returns.
      */
     private dispatchPostToolBatchAndInjectContext;
+    /**
+     * Whether `name`'s own schema declares a BUSINESS parameter called
+     * `intent` (declared, and not the injected label contract — see
+     * `isIntentLabelProperty`). Such a parameter must keep participating in
+     * `{{tool…}}` placeholder substitution; only the display label is exempt.
+     */
+    private toolDeclaresBusinessIntent;
     private dispatchStepCompleted;
     /**
      * Emits the completed run step for a single host-reported result before

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

@@ -6,6 +6,15 @@ export declare const ToolSearchToolDescription = "Searches deferred tools using
 export declare const ToolSearchToolSchema: {
     readonly type: "object";
     readonly properties: {
+        readonly intent: {
+            readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+            readonly enum?: string[];
+            readonly items?: t.JsonSchemaType;
+            readonly properties?: Record<string, t.JsonSchemaType>;
+            readonly required?: string[];
+            readonly description?: string;
+            readonly additionalProperties?: boolean | t.JsonSchemaType;
+        };
         readonly query: {
             readonly type: "string";
             readonly maxLength: 200;
@@ -48,6 +57,15 @@ export declare const ToolSearchToolDefinition: {
     readonly schema: {
         readonly type: "object";
         readonly properties: {
+            readonly intent: {
+                readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+                readonly enum?: string[];
+                readonly items?: t.JsonSchemaType;
+                readonly properties?: Record<string, t.JsonSchemaType>;
+                readonly required?: string[];
+                readonly description?: string;
+                readonly additionalProperties?: boolean | t.JsonSchemaType;
+            };
             readonly query: {
                 readonly type: "string";
                 readonly maxLength: 200;

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

@@ -0,0 +1,119 @@
+/**
+ * @fileoverview Tool intent labels.
+ *
+ * Lets a tool declare, as the FIRST property of its input schema, an `intent`
+ * string: one model-authored sentence stating what that specific call is about
+ * to do ("Searching for OAuth handling in the callback router"). Because the
+ * property is first, it is the first key providers stream in the tool-call
+ * args, so a host UI can render it as the call's live status label before the
+ * rest of the args exist. When the call settles, {@link applyOutcome} edits
+ * the sentence in place into its outcome form — a tool-supplied replacement
+ * (`outcome`), a tool-supplied span edit (`outcome_patch`), or a mechanical
+ * present-progressive→past-tense transform of the leading verb.
+ *
+ * The arg is always optional (never listed in `required`): the same schemas
+ * are callable from programmatic tool calling, where no UI renders a label
+ * and forcing generated code to fabricate one would be pure cost. Tool bodies
+ * must call {@link stripIntent} before using their args so no tool receives a
+ * parameter it did not declare.
+ */
+import type { JsonSchemaType, OutcomePatch } from '@/types';
+/** Argument carrying the model-authored label for a tool call. */
+export declare const INTENT_ARG = "intent";
+/** Model-facing instruction for the injected `intent` property. */
+export declare const INTENT_DESCRIPTION: string;
+/**
+ * Canonical (frozen) shape of the injected property. Always embed a COPY
+ * (`{ ...INTENT_PROPERTY }`): LangChain's JSON-schema validator stamps a
+ * `__absolute_uri__` marker onto every subschema it dereferences, which
+ * throws on a frozen object — and a single shared instance would be stamped
+ * with one schema's URI while embedded in many.
+ */
+export declare const INTENT_PROPERTY: JsonSchemaType;
+/**
+ * Discriminates the intent LABEL property from a tool's own business
+ * parameter that merely shares the name: the label contract always opens
+ * with the same instruction. Removal/sanitize passes must never strip a
+ * parameter the tool actually needs.
+ */
+export declare function isIntentLabelProperty(property: unknown): boolean;
+/**
+ * Returns a copy of the parameters schema with `intent` prepended as the
+ * FIRST property (object key order is insertion order and every provider
+ * serializer preserves it — first key in the schema means first key in the
+ * streamed input). Never mutates the input; no-op when the schema already
+ * declares `intent`. The property is not added to `required`.
+ */
+export declare function withIntent(parameters?: JsonSchemaType): JsonSchemaType;
+/**
+ * Reads the model-authored intent from tool-call args (handles stringified
+ * args). Returns undefined when absent, empty, or not a string.
+ */
+export declare function readIntent(args: unknown): string | undefined;
+/**
+ * Returns the args without the `intent` key so downstream consumers that did
+ * not declare it never receive it. Parses stringified JSON object args;
+ * returns the value unchanged when the key is absent.
+ */
+export declare function stripIntent(args: unknown): unknown;
+/**
+ * Resolves the settled label for a call from its model-authored `intent` and
+ * the tool's result fields, in precedence order:
+ *
+ *  1. `outcome` — full replacement authored by the tool.
+ *  2. `outcome_patch` — first occurrence of `from` in the intent replaced
+ *     with `to` (case-sensitive); no-op when `from` is absent or empty.
+ *  3. Mechanical transform — the leading word mapped present-progressive →
+ *     past tense; an unknown leading word leaves the intent unchanged.
+ *
+ * Returns undefined when there is neither an intent nor an outcome, so
+ * callers fall back to their default label. Pure and dependency-free — host
+ * UIs needing identical logic can import or mirror it.
+ */
+export declare function applyOutcome(intent: string | undefined, result?: {
+    outcome?: string;
+    outcome_patch?: OutcomePatch;
+}): string | undefined;
+/**
+ * Resolves the settled label to emit on a completion event: only when the
+ * tool actually authored `outcome`/`outcome_patch` fields. Returns undefined
+ * otherwise — the mechanical transform of a bare intent is left to the host
+ * so the wire never carries a label the host can derive itself. The result
+ * is collapsed to a bounded single line before emission.
+ *
+ * For failed calls (`isError`), only tool-AUTHORED text may label the call:
+ * an explicit `outcome`, or a patch whose `from` actually matches the
+ * intent. An unmatched patch must not fall through to the mechanical
+ * past-tense transform — wording drift in a failure patch would otherwise
+ * render a success-looking label for an error.
+ */
+export declare function resolveToolOutcome(args: unknown, fields?: {
+    outcome?: string;
+    outcome_patch?: OutcomePatch;
+} | null, options?: {
+    isError?: boolean;
+}): string | undefined;
+/**
+ * Reads the outcome fields off a tool-execution result: the typed
+ * `outcome`/`outcome_patch` fields when present, else the artifact channel
+ * (see {@link readOutcomeFields}) — so a `content_and_artifact` tool authors
+ * its label the same way on the direct and event-driven paths.
+ */
+export declare function outcomeFieldsFromResult(result: {
+    outcome?: string;
+    outcome_patch?: OutcomePatch;
+    artifact?: unknown;
+}): {
+    outcome?: string;
+    outcome_patch?: OutcomePatch;
+} | undefined;
+/**
+ * Extracts validated `outcome`/`outcome_patch` fields from an arbitrary
+ * value — the artifact channel through which an in-process
+ * `content_and_artifact` tool authors its settled label. Returns undefined
+ * when neither field is usable.
+ */
+export declare function readOutcomeFields(source: unknown): {
+    outcome?: string;
+    outcome_patch?: OutcomePatch;
+} | undefined;

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

@@ -1,3 +1,4 @@
+import type { JsonSchemaType } from '@/types';
 export declare const DEFAULT_CODE_API_RUN_TIMEOUT_MS = 15000;
 export declare const MIN_CODE_API_RUN_TIMEOUT_MS = 1000;
 export declare const MAX_CODE_API_RUN_TIMEOUT_SCHEMA_MS = 300000;
@@ -11,6 +12,7 @@ type TimeoutSchema = {
 export type ProgrammaticToolCallingJsonSchema = {
     type: 'object';
     properties: {
+        intent: JsonSchemaType;
         code: {
             type: 'string';
             minLength: number;