@librechat/agents 3.3.4 → 3.3.6

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

@@ -560,3 +560,177 @@ describe('ToolNode per-call onResult completion emission', () => {
     );
   });
 });
+
+describe('ToolNode returned-error completions', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  /**
+   * A tool that RETURNS an error ToolMessage never enters the catch path, so
+   * the errorHandler never runs and cannot have dispatched. The output loop
+   * must therefore emit the completion — and with it the tool's authored
+   * failure label — instead of assuming the handler owned it.
+   */
+  it('emits a completion (and authored outcome) for a RETURNED error ToolMessage', async () => {
+    const completions: Array<{
+      result: { tool_call: { id: string; outcome?: string } };
+    }> = [];
+    jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async (event, data): Promise<void> => {
+        if (event === GraphEvents.ON_RUN_STEP_COMPLETED) {
+          completions.push(
+            data as { result: { tool_call: { id: string; outcome?: string } } }
+          );
+        }
+      });
+
+    const returnsError = tool(
+      async () =>
+        new ToolMessage({
+          content: 'boom',
+          tool_call_id: 'call_fail',
+          status: 'error',
+          artifact: { outcome: 'Search failed for OAuth' },
+        }),
+      {
+        name: 'failing',
+        description: 'returns an error message',
+        schema: z.object({}).passthrough(),
+      }
+    ) as unknown as StructuredToolInterface;
+
+    const errorHandler = jest.fn(async () => true);
+    const toolNode = new ToolNode({
+      tools: [returnsError],
+      toolCallStepIds: new Map([['call_fail', 'step_fail']]),
+      errorHandler: errorHandler as unknown as t.ToolNodeConstructorParams['errorHandler'],
+    });
+
+    await toolNode.invoke({
+      messages: [
+        createAIMessageWithToolCalls([
+          {
+            id: 'call_fail',
+            name: 'failing',
+            args: { intent: 'Searching for OAuth handling' },
+          },
+        ]),
+      ],
+    });
+    await flushAsync();
+
+    expect(errorHandler).not.toHaveBeenCalled();
+    const completion = completions.find(
+      (c) => c.result.tool_call.id === 'call_fail'
+    );
+    expect(completion).toBeDefined();
+    expect(completion?.result.tool_call.outcome).toBe('Search failed for OAuth');
+  });
+});
+
+describe('ToolNode error-ownership scoping', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  /**
+   * Tool-call ids are provider-scoped and synthetic ids can repeat, so
+   * ownership markers kept on the INSTANCE cross-consume between that
+   * instance's concurrent invocations.
+   *
+   * Interleaving that exposes it: invocation 1 batches a throwing call
+   * (whose handler claims ownership) alongside a slow call that keeps the
+   * batch — and therefore its output loop — pending. While it is parked,
+   * invocation 2 reuses the same id and RETURNS an error message. With
+   * instance-scoped markers, invocation 2's output loop consumes the
+   * marker invocation 1 set and drops its only completion.
+   */
+  it('does not let a pending invocation\'s marker suppress a concurrent call reusing the id', async () => {
+    const completions: string[] = [];
+    jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async (event, data): Promise<void> => {
+        if (event === GraphEvents.ON_RUN_STEP_COMPLETED) {
+          completions.push(
+            (data as { result: { tool_call: { id: string } } }).result.tool_call
+              .id
+          );
+        }
+      });
+
+    const shared = 'call_shared';
+    let releaseSlow: (() => void) | undefined;
+    const slowGate = new Promise<void>((resolve) => {
+      releaseSlow = resolve;
+    });
+
+    const thrower = tool(
+      async () => {
+        throw new Error('boom');
+      },
+      { name: 'thrower', description: 'throws', schema: z.object({}).passthrough() }
+    ) as unknown as StructuredToolInterface;
+    const slow = tool(
+      async () => {
+        await slowGate;
+        return 'done';
+      },
+      { name: 'slow', description: 'parks the batch', schema: z.object({}).passthrough() }
+    ) as unknown as StructuredToolInterface;
+    const returner = tool(
+      async () =>
+        new ToolMessage({
+          content: 'failed',
+          tool_call_id: shared,
+          status: 'error',
+        }),
+      {
+        name: 'returner',
+        description: 'returns an error message',
+        schema: z.object({}).passthrough(),
+      }
+    ) as unknown as StructuredToolInterface;
+
+    /** ONE instance — the shared state the finding is about. */
+    const node = new ToolNode({
+      tools: [thrower, slow, returner],
+      toolCallStepIds: new Map([
+        [shared, 'step_shared'],
+        ['call_slow', 'step_slow'],
+      ]),
+      errorHandler: (async () =>
+        true) as unknown as t.ToolNodeConstructorParams['errorHandler'],
+    });
+
+    // Invocation 1: throws (claiming ownership of `shared`) and parks.
+    const pending = node.invoke({
+      messages: [
+        createAIMessageWithToolCalls([
+          { id: shared, name: 'thrower', args: {} },
+          { id: 'call_slow', name: 'slow', args: {} },
+        ]),
+      ],
+    }) as Promise<unknown>;
+    await flushAsync();
+
+    // Invocation 2, while invocation 1 is still parked.
+    const before = completions.length;
+    await node.invoke({
+      messages: [
+        createAIMessageWithToolCalls([
+          { id: shared, name: 'returner', args: {} },
+        ]),
+      ],
+    });
+    await flushAsync();
+    const emittedBySecond = completions.slice(before);
+
+    releaseSlow?.();
+    await pending;
+    await flushAsync();
+
+    expect(emittedBySecond).toContain(shared);
+  });
+});

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

@@ -0,0 +1,281 @@
+import { describe, it, expect } from '@jest/globals';
+import type { JsonSchemaType } from '@/types';
+import {
+  INTENT_ARG,
+  INTENT_PROPERTY,
+  INTENT_DESCRIPTION,
+  withIntent,
+  readIntent,
+  stripIntent,
+  applyOutcome,
+  readOutcomeFields,
+  resolveToolOutcome,
+} from '../intentArg';
+
+describe('withIntent', () => {
+  const base: JsonSchemaType = {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Search query' },
+      limit: { type: 'number' },
+    },
+    required: ['query'],
+  };
+
+  it('prepends intent as the FIRST property key', () => {
+    const next = withIntent(base);
+    expect(Object.keys(next.properties ?? {})).toEqual(['intent', 'query', 'limit']);
+    expect(next.properties?.[INTENT_ARG]).toEqual(INTENT_PROPERTY);
+    /**
+     * Must be a copy, not the frozen canonical instance: LangChain's
+     * JSON-schema validator stamps `__absolute_uri__` onto subschemas,
+     * which throws on a frozen object.
+     */
+    expect(next.properties?.[INTENT_ARG]).not.toBe(INTENT_PROPERTY);
+    expect(Object.isFrozen(next.properties?.[INTENT_ARG])).toBe(false);
+  });
+
+  it('never mutates the input schema', () => {
+    const frozen = Object.freeze<JsonSchemaType>({
+      type: 'object',
+      properties: Object.freeze({ query: { type: 'string' } }),
+    }) as JsonSchemaType;
+    const next = withIntent(frozen);
+    expect(next).not.toBe(frozen);
+    expect(Object.keys(frozen.properties ?? {})).toEqual(['query']);
+    expect(Object.keys(next.properties ?? {})).toEqual(['intent', 'query']);
+  });
+
+  it('does not add intent to required', () => {
+    const next = withIntent(base);
+    expect(next.required).toEqual(['query']);
+  });
+
+  it('is idempotent when intent already exists (position preserved)', () => {
+    const once = withIntent(base);
+    const twice = withIntent(once);
+    expect(twice).toBe(once);
+    expect(Object.keys(twice.properties ?? {})[0]).toBe('intent');
+  });
+
+  it('handles a schema with no properties', () => {
+    const next = withIntent({ type: 'object', properties: {} });
+    expect(Object.keys(next.properties ?? {})).toEqual(['intent']);
+  });
+
+  it('handles an undefined schema', () => {
+    const next = withIntent(undefined);
+    expect(next.type).toBe('object');
+    expect(Object.keys(next.properties ?? {})).toEqual(['intent']);
+  });
+
+  it('carries the model-facing instruction', () => {
+    expect(INTENT_PROPERTY.description).toBe(INTENT_DESCRIPTION);
+    expect(INTENT_DESCRIPTION).toContain('FIRST');
+    expect(INTENT_DESCRIPTION).toContain('distinguish that call from its siblings');
+  });
+});
+
+describe('readIntent', () => {
+  it('reads from object args', () => {
+    expect(readIntent({ intent: 'Searching for OAuth handling' })).toBe(
+      'Searching for OAuth handling'
+    );
+  });
+
+  it('reads from stringified JSON args', () => {
+    expect(readIntent('{"intent":"Searching for OAuth handling","query":"oauth"}')).toBe(
+      'Searching for OAuth handling'
+    );
+  });
+
+  it('returns undefined for absent, empty, or non-string intents', () => {
+    expect(readIntent({ query: 'oauth' })).toBeUndefined();
+    expect(readIntent({ intent: '' })).toBeUndefined();
+    expect(readIntent({ intent: '   ' })).toBeUndefined();
+    expect(readIntent({ intent: 42 })).toBeUndefined();
+    expect(readIntent(undefined)).toBeUndefined();
+    expect(readIntent('not json')).toBeUndefined();
+    expect(readIntent('{"intent": broken')).toBeUndefined();
+  });
+});
+
+describe('stripIntent', () => {
+  it('removes the key from object args', () => {
+    expect(stripIntent({ intent: 'Searching', query: 'oauth' })).toEqual({ query: 'oauth' });
+  });
+
+  it('parses and strips stringified args', () => {
+    expect(stripIntent('{"intent":"Searching","query":"oauth"}')).toEqual({ query: 'oauth' });
+  });
+
+  it('returns args unchanged when the key is absent', () => {
+    const args = { query: 'oauth' };
+    expect(stripIntent(args)).toBe(args);
+    expect(stripIntent('plain string')).toBe('plain string');
+    expect(stripIntent(undefined)).toBeUndefined();
+  });
+});
+
+describe('applyOutcome', () => {
+  const intent = 'Searching for OAuth handling';
+
+  it('prefers a tool-supplied outcome (full replacement)', () => {
+    expect(
+      applyOutcome(intent, {
+        outcome: 'Found 12 results for OAuth handling',
+        outcome_patch: { from: 'Searching', to: 'Searched' },
+      })
+    ).toBe('Found 12 results for OAuth handling');
+  });
+
+  it('ignores a blank outcome', () => {
+    expect(applyOutcome(intent, { outcome: '  ' })).toBe('Searched for OAuth handling');
+  });
+
+  it('applies outcome_patch to the first occurrence only, case-sensitive', () => {
+    expect(
+      applyOutcome('Searching for Searching patterns', {
+        outcome_patch: { from: 'Searching', to: 'Searched' },
+      })
+    ).toBe('Searched for Searching patterns');
+    expect(
+      applyOutcome(intent, { outcome_patch: { from: 'searching', to: 'searched' } })
+    ).toBe('Searched for OAuth handling');
+  });
+
+  it('ignores a patch whose from is empty or absent from the intent', () => {
+    expect(applyOutcome(intent, { outcome_patch: { from: '', to: 'x' } })).toBe(
+      'Searched for OAuth handling'
+    );
+    expect(applyOutcome(intent, { outcome_patch: { from: 'Grepping', to: 'Grepped' } })).toBe(
+      'Searched for OAuth handling'
+    );
+  });
+
+  it('mechanically transforms the leading verb', () => {
+    expect(applyOutcome('Reading the callback router')).toBe('Read the callback router');
+    expect(applyOutcome('Writing the zod schema')).toBe('Wrote the zod schema');
+    expect(applyOutcome('Delegating the OAuth audit')).toBe('Delegated the OAuth audit');
+  });
+
+  it('preserves a lowercase leading verb', () => {
+    expect(applyOutcome('searching for OAuth handling')).toBe('searched for OAuth handling');
+  });
+
+  it('leaves an unknown leading word unchanged', () => {
+    expect(applyOutcome('Refactoring the zod schema')).toBe('Refactoring the zod schema');
+  });
+
+  it('handles a single-word intent', () => {
+    expect(applyOutcome('Searching')).toBe('Searched');
+  });
+
+  it('returns undefined with neither intent nor outcome', () => {
+    expect(applyOutcome(undefined)).toBeUndefined();
+    expect(applyOutcome('')).toBeUndefined();
+    expect(applyOutcome(undefined, { outcome_patch: { from: 'a', to: 'b' } })).toBeUndefined();
+  });
+
+  it('returns the outcome even without an intent', () => {
+    expect(applyOutcome(undefined, { outcome: 'Found 12 results' })).toBe('Found 12 results');
+  });
+});
+
+describe('resolveToolOutcome', () => {
+  const args = { intent: 'Searching for OAuth handling', query: 'oauth' };
+
+  it('returns undefined when the tool authored no outcome fields', () => {
+    expect(resolveToolOutcome(args)).toBeUndefined();
+    expect(resolveToolOutcome(args, {})).toBeUndefined();
+    expect(resolveToolOutcome(args, null)).toBeUndefined();
+  });
+
+  it('resolves a tool-supplied outcome', () => {
+    expect(resolveToolOutcome(args, { outcome: 'Found 12 results' })).toBe('Found 12 results');
+  });
+
+  it('resolves a patch against the intent read from args', () => {
+    expect(
+      resolveToolOutcome(args, { outcome_patch: { from: 'Searching', to: 'Searched' } })
+    ).toBe('Searched for OAuth handling');
+  });
+
+  it('returns undefined for a patch with no intent in the args', () => {
+    expect(
+      resolveToolOutcome({ query: 'oauth' }, { outcome_patch: { from: 'a', to: 'b' } })
+    ).toBeUndefined();
+  });
+
+  it('collapses the label to a bounded single line', () => {
+    expect(
+      resolveToolOutcome(args, { outcome: 'Found 12 results\n  for   "OAuth handling"' })
+    ).toBe('Found 12 results for "OAuth handling"');
+    const oversized = resolveToolOutcome(args, { outcome: `Found ${'x'.repeat(500)}` });
+    expect(oversized?.length).toBe(256);
+    expect(oversized?.endsWith('…')).toBe(true);
+    expect(resolveToolOutcome(args, { outcome: ' \n \t ' })).toBe(
+      'Searched for OAuth handling'
+    );
+  });
+
+  it('keeps $-token replacement text literal', () => {
+    expect(
+      resolveToolOutcome(args, {
+        outcome_patch: { from: 'Searching', to: 'Found $& via $\' and $$' },
+      })
+    ).toBe('Found $& via $\' and $$ for OAuth handling');
+  });
+
+  it('labels failed calls only with tool-authored text', () => {
+    expect(resolveToolOutcome(args, { outcome: 'Search failed for OAuth' }, { isError: true })).toBe(
+      'Search failed for OAuth'
+    );
+    expect(
+      resolveToolOutcome(
+        args,
+        { outcome_patch: { from: 'Searching', to: 'Search failed' } },
+        { isError: true }
+      )
+    ).toBe('Search failed for OAuth handling');
+  });
+
+  it('never falls back to the mechanical transform on a failed call', () => {
+    expect(
+      resolveToolOutcome(
+        args,
+        { outcome_patch: { from: 'searching', to: 'searched' } },
+        { isError: true }
+      )
+    ).toBeUndefined();
+    expect(
+      resolveToolOutcome(
+        { query: 'oauth' },
+        { outcome_patch: { from: 'Searching', to: 'Searched' } },
+        { isError: true }
+      )
+    ).toBeUndefined();
+  });
+});
+
+describe('readOutcomeFields', () => {
+  it('reads valid fields from an artifact-shaped object', () => {
+    expect(readOutcomeFields({ outcome: 'Found 12 results', other: 1 })).toEqual({
+      outcome: 'Found 12 results',
+      outcome_patch: undefined,
+    });
+    expect(readOutcomeFields({ outcome_patch: { from: 'a', to: 'b' } })).toEqual({
+      outcome: undefined,
+      outcome_patch: { from: 'a', to: 'b' },
+    });
+  });
+
+  it('rejects malformed fields', () => {
+    expect(readOutcomeFields(undefined)).toBeUndefined();
+    expect(readOutcomeFields('outcome')).toBeUndefined();
+    expect(readOutcomeFields({ outcome: 42 })).toBeUndefined();
+    expect(readOutcomeFields({ outcome: '  ' })).toBeUndefined();
+    expect(readOutcomeFields({ outcome_patch: { from: 'a' } })).toBeUndefined();
+    expect(readOutcomeFields({ outcome_patch: 'Searched' })).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,139 @@
+import { describe, it, expect } from '@jest/globals';
+import type { CloudflareSandboxRuntime } from '@/types';
+import {
+  CLOUDFLARE_CODING_TOOL_NAMES,
+  createCloudflareCodingTools,
+} from '../cloudflare/CloudflareSandboxTools';
+import {
+  createLocalCodingTools,
+  createLocalCodingToolDefinitions,
+} from '../local/LocalCodingTools';
+import {
+  BashExecutionToolSchema,
+  buildBashExecutionToolSchema,
+} from '../BashExecutor';
+import {
+  CodeExecutionToolSchema,
+  buildCodeExecutionToolSchema,
+} from '../CodeExecutor';
+import {
+  SubagentToolSchema,
+  createSubagentToolDefinition,
+} from '../SubagentTool';
+import { BashProgrammaticToolCallingSchema } from '../BashProgrammaticToolCalling';
+import { ProgrammaticToolCallingSchema } from '../ProgrammaticToolCalling';
+import { WebSearchToolSchema } from '../search/schema';
+import { LOCAL_CODING_BUNDLE_NAMES } from '@/common';
+import { ReadFileToolDefinition } from '../ReadFile';
+import { ToolSearchToolSchema } from '../ToolSearch';
+import { SkillToolDefinition } from '../SkillTool';
+import { createSearchTool } from '../search/tool';
+import { INTENT_ARG } from '../intentArg';
+
+type SchemaLike = {
+  properties?: Record<string, unknown>;
+  required?: readonly string[];
+};
+
+function firstKey(schema: SchemaLike | undefined): string | undefined {
+  return Object.keys(schema?.properties ?? {})[0];
+}
+
+function expectIntentFirst(name: string, schema: SchemaLike | undefined): void {
+  expect(`${name}:${firstKey(schema)}`).toBe(`${name}:${INTENT_ARG}`);
+  expect(schema?.required ?? []).not.toContain(INTENT_ARG);
+}
+
+const stubSandbox: CloudflareSandboxRuntime = {
+  exec: () => Promise.reject(new Error('schema-only stub')),
+  readFile: () => Promise.reject(new Error('schema-only stub')),
+  writeFile: () => Promise.reject(new Error('schema-only stub')),
+  mkdir: () => Promise.reject(new Error('schema-only stub')),
+  listFiles: () => Promise.reject(new Error('schema-only stub')),
+  deleteFile: () => Promise.reject(new Error('schema-only stub')),
+};
+
+/**
+ * Coverage pin for the tool-intent capability: every native coding tool, on
+ * every engine, must emit `intent` as the FIRST schema property (and never
+ * require it). Mirrors the `LOCAL_CODING_BUNDLE_NAMES` pin so "did we get
+ * them all" is a failing test rather than a review question.
+ */
+describe('intent coverage', () => {
+  it('every local bundle tool emits intent as its first schema property', () => {
+    const tools = createLocalCodingTools();
+    expect(tools.map((tool) => tool.name).sort()).toEqual(
+      [...LOCAL_CODING_BUNDLE_NAMES].sort()
+    );
+    for (const tool of tools) {
+      expectIntentFirst(tool.name, tool.schema as SchemaLike);
+    }
+  });
+
+  it('every local registry definition emits intent first', () => {
+    for (const def of createLocalCodingToolDefinitions()) {
+      expectIntentFirst(def.name, def.parameters);
+    }
+  });
+
+  it('every cloudflare bundle tool emits intent first', () => {
+    const tools = createCloudflareCodingTools({ sandbox: stubSandbox });
+    expect(tools.map((tool) => tool.name).sort()).toEqual(
+      [...CLOUDFLARE_CODING_TOOL_NAMES].sort()
+    );
+    for (const tool of tools) {
+      expectIntentFirst(tool.name, tool.schema as SchemaLike);
+    }
+  });
+
+  it('shared execution schemas emit intent first (all engines)', () => {
+    expectIntentFirst('bash_tool', BashExecutionToolSchema);
+    expectIntentFirst('execute_code', CodeExecutionToolSchema);
+    expectIntentFirst(
+      'bash_tool:stateful',
+      buildBashExecutionToolSchema({ statefulSessions: true })
+    );
+    expectIntentFirst(
+      'execute_code:stateful',
+      buildCodeExecutionToolSchema({ statefulSessions: true })
+    );
+    expectIntentFirst(
+      'run_tools_with_code',
+      ProgrammaticToolCallingSchema
+    );
+    expectIntentFirst(
+      'run_tools_with_bash',
+      BashProgrammaticToolCallingSchema
+    );
+  });
+
+  it('read_file, skill, subagent, tool_search, and web_search emit intent first', () => {
+    expectIntentFirst('read_file', ReadFileToolDefinition.parameters);
+    expectIntentFirst('skill', SkillToolDefinition.parameters);
+    expectIntentFirst('subagent', SubagentToolSchema);
+    expectIntentFirst(
+      'subagent:runtime',
+      createSubagentToolDefinition([
+        { type: 'researcher', name: 'Researcher', description: 'Researches' },
+      ]).parameters
+    );
+    expectIntentFirst('tool_search', ToolSearchToolSchema);
+    expectIntentFirst('web_search', WebSearchToolSchema);
+  });
+
+  it('the createSearchTool FACTORY emits intent first (runtime schema, not the static def)', () => {
+    const serperTool = createSearchTool({
+      searchProvider: 'serper',
+      scraperProvider: 'serper',
+      serperApiKey: 'test-key',
+    });
+    expectIntentFirst('web_search:serper', serperTool.schema as SchemaLike);
+    const searxngTool = createSearchTool({
+      searchProvider: 'searxng',
+      scraperProvider: 'serper',
+      serperApiKey: 'test-key',
+      searxngInstanceUrl: 'http://localhost:8080',
+    });
+    expectIntentFirst('web_search:searxng', searxngTool.schema as SchemaLike);
+  });
+});

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

@@ -187,6 +187,89 @@ describe('ToolOutputReferenceRegistry', () => {
       expect(resolved).toBe('nothing to see here');
     });
 
+    it('leaves the top-level intent arg verbatim (display label, not a data channel)', () => {
+      const reg = new ToolOutputReferenceRegistry();
+      reg.set('r', 'tool0turn0', 'HUGE-STORED-OUTPUT');
+      const { resolved } = reg.resolve('r', {
+        intent: 'Reusing {{tool0turn0}} for the next step',
+        command: 'cat {{tool0turn0}}',
+        nested: { intent: 'not top-level {{tool0turn0}}' },
+      });
+      expect(resolved).toEqual({
+        intent: 'Reusing {{tool0turn0}} for the next step',
+        command: 'cat HUGE-STORED-OUTPUT',
+        nested: { intent: 'not top-level HUGE-STORED-OUTPUT' },
+      });
+    });
+
+    it('preserves the intent key inside STRINGIFIED object args too', () => {
+      const reg = new ToolOutputReferenceRegistry();
+      reg.set('r', 'tool0turn0', 'HUGE-STORED-OUTPUT');
+      const { resolved } = reg.resolve(
+        'r',
+        '{"intent":"Reusing {{tool0turn0}}","command":"cat {{tool0turn0}}"}'
+      );
+      expect(JSON.parse(resolved as string)).toEqual({
+        intent: 'Reusing {{tool0turn0}}',
+        command: 'cat HUGE-STORED-OUTPUT',
+      });
+    });
+
+    it('keeps plain (non-object) string args on the raw substitution path', () => {
+      const reg = new ToolOutputReferenceRegistry();
+      reg.set('r', 'tool0turn0', 'DATA');
+      const { resolved } = reg.resolve('r', 'echo {{tool0turn0}} intent');
+      expect(resolved).toBe('echo DATA intent');
+    });
+
+    it('substitutes a BUSINESS intent arg when the caller opts in', () => {
+      const reg = new ToolOutputReferenceRegistry();
+      reg.set('r', 'tool0turn0', 'STORED');
+      const { resolved } = reg.resolve(
+        'r',
+        { intent: 'category {{tool0turn0}}', title: 'x {{tool0turn0}}' },
+        { substituteIntentKey: true }
+      );
+      expect(resolved).toEqual({
+        intent: 'category STORED',
+        title: 'x STORED',
+      });
+    });
+
+    it('substitutes a business intent inside stringified args when opted in', () => {
+      const reg = new ToolOutputReferenceRegistry();
+      reg.set('r', 'tool0turn0', 'STORED');
+      const { resolved } = reg.resolve(
+        'r',
+        '{"intent":"category {{tool0turn0}}"}',
+        { substituteIntentKey: true }
+      );
+      expect(resolved).toBe('{"intent":"category STORED"}');
+    });
+
+    it('reports unresolved references from a business intent arg', () => {
+      const reg = new ToolOutputReferenceRegistry();
+      const { unresolved } = reg.resolve(
+        'r',
+        { intent: 'category {{tool9turn9}}' },
+        { substituteIntentKey: true }
+      );
+      expect(unresolved).toEqual(['tool9turn9']);
+    });
+
+    it('snapshot views honor the opt-in too', () => {
+      const reg = new ToolOutputReferenceRegistry();
+      reg.set('r', 'tool0turn0', 'STORED');
+      const view = reg.snapshot('r');
+      expect(view.resolve({ intent: 'x {{tool0turn0}}' }).resolved).toEqual({
+        intent: 'x {{tool0turn0}}',
+      });
+      expect(
+        view.resolve({ intent: 'x {{tool0turn0}}' }, { substituteIntentKey: true })
+          .resolved
+      ).toEqual({ intent: 'x STORED' });
+    });
+
     it('passes through primitive values untouched', () => {
       const reg = new ToolOutputReferenceRegistry();
       const { resolved } = reg.resolve('r', {