@librechat/agents 3.3.5 → 3.3.7

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', {

package/src/tools/intentArg.ts

@@ -0,0 +1,357 @@
+/**
+ * @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`) or a tool-supplied span edit (`outcome_patch`). Absent either,
+ * the label is left exactly as the model wrote it: completion is a UI state
+ * (the shimmer stopping, the icon settling), not a tense change.
+ *
+ * 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 const INTENT_ARG = 'intent';
+
+/**
+ * Opening words of {@link INTENT_DESCRIPTION}, and the discriminator that
+ * tells the injected LABEL apart from a tool's own business parameter that
+ * merely shares the name `intent`.
+ *
+ * Exported because host applications reimplement the same strip/sanitize
+ * passes and would otherwise duplicate this as a string literal: if the two
+ * copies drift, the host silently stops recognizing SDK-native labels and
+ * fails OPEN (labels stay in schemas, opt-outs stop working) with no error.
+ * Any edit to the description must preserve this prefix verbatim.
+ */
+export const INTENT_LABEL_MARKER = 'ALWAYS write this field FIRST';
+
+/**
+ * Model-facing instruction for the injected `intent` property.
+ *
+ * Deliberately terse — it is repeated on every opted-in tool schema, on every
+ * request, so each sentence is paid for many times over. What remains is
+ * load-bearing: first-position placement (the entire streaming mechanism),
+ * the one-sentence present-progressive form, who reads it, and the sibling
+ * rule, without which models emit identical labels for parallel calls to one
+ * tool and defeat the feature's headline case.
+ */
+export const INTENT_DESCRIPTION =
+  `${INTENT_LABEL_MARKER}, before any other argument. One present-progressive ` +
+  'sentence saying what THIS call is about to do: "Searching for OAuth handling ' +
+  'in the callback router". Shown to the user as this call\'s live status. ' +
+  'Never name the tool. Sibling calls to one tool must differ.';
+
+/**
+ * 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 const INTENT_PROPERTY: JsonSchemaType = Object.freeze<JsonSchemaType>({
+  type: 'string',
+  description: INTENT_DESCRIPTION,
+});
+
+/**
+ * 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 function isIntentLabelProperty(property: unknown): boolean {
+  if (property == null || typeof property !== 'object') {
+    return false;
+  }
+  const record = property as { type?: unknown; description?: unknown };
+  return (
+    record.type === 'string' &&
+    typeof record.description === 'string' &&
+    record.description.startsWith(INTENT_LABEL_MARKER)
+  );
+}
+
+/**
+ * Schema shape accepted by {@link withoutIntent}.
+ *
+ * `required` is widened to `readonly string[]` because the SDK's own native
+ * schemas are declared `as const` — their `required` is a readonly tuple, and
+ * a mutable `string[]` parameter would reject the very schemas this helper
+ * exists for (TS2345), forcing embedders to cast to use the advertised API.
+ */
+export type IntentStrippableSchema = Omit<JsonSchemaType, 'required'> & {
+  required?: readonly string[];
+};
+
+/**
+ * Returns a copy of `parameters` without the injected intent LABEL — the
+ * opt-out for consumers that render no status label and should not pay for
+ * the property.
+ *
+ * The SDK's native schemas carry the label unconditionally, so without this
+ * an embedder has no lever at all: `withIntent` is applied at module scope.
+ * Marker-guarded, so a tool's own business parameter named `intent` is never
+ * removed. Returns the input unchanged when there is nothing to strip.
+ *
+ * `required` is pruned alongside the property: a schema that lists `intent`
+ * as required (strict-mode normalization does exactly that, since OpenAI
+ * strict function schemas require every property to appear in `required`)
+ * would otherwise be left naming a property it no longer declares, which is
+ * invalid JSON Schema and gets rejected by the provider instead of quietly
+ * opting out.
+ */
+export function withoutIntent(parameters?: IntentStrippableSchema): JsonSchemaType | undefined {
+  const props = parameters?.properties;
+  if (parameters == null || props == null || !isIntentLabelProperty(props[INTENT_ARG])) {
+    return parameters as JsonSchemaType | undefined;
+  }
+  const { [INTENT_ARG]: _omit, ...rest } = props;
+  const next: JsonSchemaType = {
+    ...(parameters as JsonSchemaType),
+    properties: rest,
+  };
+  if (parameters.required != null) {
+    const required = parameters.required.filter((key) => key !== INTENT_ARG);
+    if (required.length > 0) {
+      next.required = required;
+    } else {
+      delete next.required;
+    }
+  }
+  return next;
+}
+
+/**
+ * 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 function withIntent(parameters?: JsonSchemaType): JsonSchemaType {
+  const existingProps = parameters?.properties ?? {};
+  if (INTENT_ARG in existingProps) {
+    return parameters as JsonSchemaType;
+  }
+  return {
+    ...parameters,
+    type: 'object',
+    properties: { [INTENT_ARG]: { ...INTENT_PROPERTY }, ...existingProps },
+  };
+}
+
+/**
+ * Coerces tool-call args to an object, parsing a stringified JSON object
+ * (some providers deliver args as a string). Returns undefined otherwise.
+ */
+function coerceArgsObject(args: unknown): Record<string, unknown> | undefined {
+  if (typeof args === 'object' && args !== null && !Array.isArray(args)) {
+    return args as Record<string, unknown>;
+  }
+  if (typeof args === 'string' && args.trim().startsWith('{')) {
+    try {
+      const parsed = JSON.parse(args) as unknown;
+      if (parsed != null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        return parsed as Record<string, unknown>;
+      }
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Reads the model-authored intent from tool-call args (handles stringified
+ * args). Returns undefined when absent, empty, or not a string.
+ */
+export function readIntent(args: unknown): string | undefined {
+  const value = coerceArgsObject(args)?.[INTENT_ARG];
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed === '' ? undefined : trimmed;
+}
+
+/**
+ * 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 function stripIntent(args: unknown): unknown {
+  const obj = coerceArgsObject(args);
+  if (!obj || !(INTENT_ARG in obj)) {
+    return args;
+  }
+  const { [INTENT_ARG]: _omit, ...rest } = obj;
+  return rest;
+}
+
+/**
+ * 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. Otherwise the intent is returned UNCHANGED.
+ *
+ * There is deliberately no mechanical present-progressive→past-tense rewrite.
+ * Such a transform can only be a closed list of English verbs, which makes it
+ * wrong in three ways at once: it never fires for the non-English labels this
+ * feature expects (the model answers in the user's language), it fires for
+ * some sibling calls and not others inside one group — "Searched…" beside
+ * "Recording…" — and it quietly enumerates a vocabulary in a feature whose
+ * premise is that the sentence is free-form. Completion is conveyed by UI
+ * state (the shimmer stopping, the icon settling), which is language-neutral
+ * and always consistent; a tool that wants past tense says so explicitly via
+ * `outcome` or `outcome_patch`.
+ *
+ * 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 function applyOutcome(
+  intent: string | undefined,
+  result?: { outcome?: string; outcome_patch?: OutcomePatch },
+): string | undefined {
+  const outcome = result?.outcome;
+  if (typeof outcome === 'string' && outcome.trim() !== '') {
+    return outcome;
+  }
+  if (intent == null || intent === '') {
+    return undefined;
+  }
+  const patch = result?.outcome_patch;
+  if (patch != null && patch.from !== '' && intent.includes(patch.from)) {
+    /** Replacement callback keeps `to` verbatim — a direct string second
+     *  argument would interpret `$&`/`$'`-style tokens in tool-authored
+     *  text (e.g. labels derived from shell syntax). */
+    return intent.replace(patch.from, () => patch.to);
+  }
+  return intent;
+}
+
+/**
+ * Hard cap on an emitted outcome label. The label is a single progress line
+ * in UI chrome; a tool that derives it from data (or a malformed patch)
+ * must not be able to inflate completion events or persisted parts.
+ */
+const MAX_OUTCOME_CHARS = 256;
+
+function boundOutcomeLabel(label: string | undefined): string | undefined {
+  if (label == null) {
+    return undefined;
+  }
+  const singleLine = label.replace(/\s+/g, ' ').trim();
+  if (singleLine === '') {
+    return undefined;
+  }
+  if (singleLine.length <= MAX_OUTCOME_CHARS) {
+    return singleLine;
+  }
+  return `${singleLine.slice(0, MAX_OUTCOME_CHARS - 1)}…`;
+}
+
+/**
+ * Resolves the settled label to emit on a completion event: only when the
+ * tool actually authored `outcome`/`outcome_patch` fields. Returns undefined
+ * otherwise, so the wire never carries a label the host already has — a bare
+ * intent needs no settled form, because it is displayed unchanged and the UI
+ * conveys completion through its own state. Hosts must NOT rewrite it (see
+ * {@link applyOutcome} for why a tense transform is deliberately absent). 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 resolves to undefined rather than silently reusing the
+ * in-flight intent, so a failure is never labelled as though it succeeded.
+ */
+export function resolveToolOutcome(
+  args: unknown,
+  fields?: { outcome?: string; outcome_patch?: OutcomePatch } | null,
+  options?: { isError?: boolean },
+): string | undefined {
+  if (fields == null || (fields.outcome == null && fields.outcome_patch == null)) {
+    return undefined;
+  }
+  if (options?.isError !== true) {
+    return boundOutcomeLabel(applyOutcome(readIntent(args), fields));
+  }
+  const outcome = fields.outcome;
+  if (typeof outcome === 'string' && outcome.trim() !== '') {
+    return boundOutcomeLabel(outcome);
+  }
+  const intent = readIntent(args);
+  const patch = fields.outcome_patch;
+  if (
+    intent != null &&
+    patch != null &&
+    patch.from !== '' &&
+    intent.includes(patch.from)
+  ) {
+    return boundOutcomeLabel(intent.replace(patch.from, () => patch.to));
+  }
+  return 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 function outcomeFieldsFromResult(result: {
+  outcome?: string;
+  outcome_patch?: OutcomePatch;
+  artifact?: unknown;
+}): { outcome?: string; outcome_patch?: OutcomePatch } | undefined {
+  if (result.outcome != null || result.outcome_patch != null) {
+    return result;
+  }
+  return readOutcomeFields(result.artifact);
+}
+
+/**
+ * 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 function readOutcomeFields(
+  source: unknown,
+): { outcome?: string; outcome_patch?: OutcomePatch } | undefined {
+  if (source == null || typeof source !== 'object' || Array.isArray(source)) {
+    return undefined;
+  }
+  const record = source as Record<string, unknown>;
+  const outcome =
+    typeof record.outcome === 'string' && record.outcome.trim() !== ''
+      ? record.outcome
+      : undefined;
+  let outcome_patch: OutcomePatch | undefined;
+  const rawPatch = record.outcome_patch;
+  if (rawPatch != null && typeof rawPatch === 'object' && !Array.isArray(rawPatch)) {
+    const patch = rawPatch as Record<string, unknown>;
+    if (typeof patch.from === 'string' && typeof patch.to === 'string') {
+      outcome_patch = { from: patch.from, to: patch.to };
+    }
+  }
+  if (outcome == null && outcome_patch == null) {
+    return undefined;
+  }
+  return { outcome, outcome_patch };
+}

package/src/tools/local/CompileCheckTool.ts

@@ -27,7 +27,6 @@ import { resolve } from 'path';
 import { tool } from '@langchain/core/tools';
 import type { DynamicStructuredTool } from '@langchain/core/tools';
 import type { WorkspaceFS } from './workspaceFS';
-import { isWorkspaceClientTimeoutError } from './workspaceFS';
 import type * as t from '@/types';
 import {
   getLocalCwd,
@@ -36,12 +35,14 @@ import {
   truncateLocalOutput,
   validateBashCommand,
 } from './LocalExecutionEngine';
+import { isWorkspaceClientTimeoutError } from './workspaceFS';
+import { withIntent } from '@/tools/intentArg';
 import { Constants } from '@/common';
 
 /** Back-compat alias; canonical name lives on `Constants.COMPILE_CHECK`. */
 export const CompileCheckToolName = Constants.COMPILE_CHECK;
 
-const CompileCheckSchema: t.JsonSchemaType = {
+const CompileCheckSchema: t.JsonSchemaType = withIntent({
   type: 'object',
   properties: {
     command: {
@@ -55,7 +56,7 @@ const CompileCheckSchema: t.JsonSchemaType = {
         'Optional timeout in milliseconds. Defaults to 120000 (2 min).',
     },
   },
-};
+});
 
 type DetectedKind =
   | 'typescript'

package/src/tools/local/LocalCodingTools.ts

@@ -3,7 +3,6 @@ import { createTwoFilesPatch } from 'diff';
 import { tool } from '@langchain/core/tools';
 import type { DynamicStructuredTool } from '@langchain/core/tools';
 import type * as t from '@/types';
-import { isWorkspaceClientTimeoutError } from './workspaceFS';
 import {
   createLocalBashProgrammaticToolCallingTool,
   createLocalProgrammaticToolCallingTool,
@@ -25,9 +24,11 @@ import {
 } from './CompileCheckTool';
 import { classifyAttachment, imageAttachmentContent } from './attachments';
 import { createLocalFileCheckpointer } from './FileCheckpointer';
+import { isWorkspaceClientTimeoutError } from './workspaceFS';
 import { applyEdit, locateEdit } from './editStrategies';
 import { decodeFile, encodeFile } from './textEncoding';
 import { runPostEditSyntaxCheck } from './syntaxCheck';
+import { withIntent } from '@/tools/intentArg';
 import { Constants } from '@/common';
 
 const MAX_READ_CHARS = 256000;
@@ -47,7 +48,7 @@ export const LocalGrepSearchToolName = Constants.GREP_SEARCH;
 export const LocalGlobSearchToolName = Constants.GLOB_SEARCH;
 export const LocalListDirectoryToolName = Constants.LIST_DIRECTORY;
 
-export const LocalReadFileToolSchema: t.JsonSchemaType = {
+export const LocalReadFileToolSchema: t.JsonSchemaType = withIntent({
   type: 'object',
   properties: {
     path: {
@@ -65,9 +66,9 @@ export const LocalReadFileToolSchema: t.JsonSchemaType = {
     },
   },
   required: ['path'],
-};
+});
 
-export const LocalWriteFileToolSchema: t.JsonSchemaType = {
+export const LocalWriteFileToolSchema: t.JsonSchemaType = withIntent({
   type: 'object',
   properties: {
     path: {
@@ -81,9 +82,9 @@ export const LocalWriteFileToolSchema: t.JsonSchemaType = {
     },
   },
   required: ['path', 'content'],
-};
+});
 
-export const LocalEditFileToolSchema: t.JsonSchemaType = {
+export const LocalEditFileToolSchema: t.JsonSchemaType = withIntent({
   type: 'object',
   properties: {
     path: {
@@ -114,9 +115,9 @@ export const LocalEditFileToolSchema: t.JsonSchemaType = {
     },
   },
   required: ['path'],
-};
+});
 
-export const LocalGrepSearchToolSchema: t.JsonSchemaType = {
+export const LocalGrepSearchToolSchema: t.JsonSchemaType = withIntent({
   type: 'object',
   properties: {
     pattern: {
@@ -137,9 +138,9 @@ export const LocalGrepSearchToolSchema: t.JsonSchemaType = {
     },
   },
   required: ['pattern'],
-};
+});
 
-export const LocalGlobSearchToolSchema: t.JsonSchemaType = {
+export const LocalGlobSearchToolSchema: t.JsonSchemaType = withIntent({
   type: 'object',
   properties: {
     pattern: {
@@ -156,9 +157,9 @@ export const LocalGlobSearchToolSchema: t.JsonSchemaType = {
     },
   },
   required: ['pattern'],
-};
+});
 
-export const LocalListDirectoryToolSchema: t.JsonSchemaType = {
+export const LocalListDirectoryToolSchema: t.JsonSchemaType = withIntent({
   type: 'object',
   properties: {
     path: {
@@ -166,7 +167,7 @@ export const LocalListDirectoryToolSchema: t.JsonSchemaType = {
       description: 'Directory to list. Defaults to cwd.',
     },
   },
-};
+});
 
 function lineWindow(
   content: string,

package/src/tools/ptcTimeout.ts

@@ -1,3 +1,4 @@
+import type { JsonSchemaType } from '@/types';
 import { EnvVar } from '@/common';
 
 export const DEFAULT_CODE_API_RUN_TIMEOUT_MS = 15_000;
@@ -15,6 +16,7 @@ type TimeoutSchema = {
 export type ProgrammaticToolCallingJsonSchema = {
   type: 'object';
   properties: {
+    intent: JsonSchemaType;
     code: {
       type: 'string';
       minLength: number;

package/src/tools/search/outcome.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect } from '@jest/globals';
+import type * as t from './types';
+import { resolveSearchOutcome } from './tool';
+
+const data = (partial: Partial<t.SearchResultData>): t.SearchResultData =>
+  ({ turn: 0, ...partial }) as t.SearchResultData;
+
+describe('resolveSearchOutcome', () => {
+  it('authors a FAILURE label when the processor caught an error', () => {
+    expect(
+      resolveSearchOutcome(
+        data({ error: 'provider timeout', organic: [] }),
+        'oauth handling'
+      )
+    ).toBe('Search failed for "oauth handling"');
+  });
+
+  it('prefers the failure label over any partial results', () => {
+    expect(
+      resolveSearchOutcome(
+        data({
+          error: 'partial failure',
+          organic: [{ link: 'a' }] as t.SearchResultData['organic'],
+        }),
+        'oauth'
+      )
+    ).toBe('Search failed for "oauth"');
+  });
+
+  it('ignores an empty-string error', () => {
+    expect(
+      resolveSearchOutcome(
+        data({
+          error: '',
+          organic: [{ link: 'a' }] as t.SearchResultData['organic'],
+        }),
+        'oauth'
+      )
+    ).toBe('Found 1 result for "oauth"');
+  });
+
+  it('counts every rendered collection kind', () => {
+    expect(
+      resolveSearchOutcome(
+        data({
+          organic: [
+            { link: 'a' },
+            { link: 'b' },
+          ] as t.SearchResultData['organic'],
+          topStories: [{ link: 'c' }] as t.SearchResultData['topStories'],
+          images: [{ imageUrl: 'd' }] as t.SearchResultData['images'],
+          videos: [{ link: 'e' }] as t.SearchResultData['videos'],
+          places: [{ name: 'f' }] as t.SearchResultData['places'],
+          peopleAlsoAsk: [
+            { question: 'g' },
+          ] as t.SearchResultData['peopleAlsoAsk'],
+        }),
+        'oauth'
+      )
+    ).toBe('Found 7 results for "oauth"');
+  });
+
+  it('counts singleton structured results (knowledge graph / answer box)', () => {
+    expect(
+      resolveSearchOutcome(
+        data({
+          knowledgeGraph: {
+            title: 'OAuth',
+          } as t.SearchResultData['knowledgeGraph'],
+        }),
+        'oauth'
+      )
+    ).toBe('Found 1 result for "oauth"');
+    expect(
+      resolveSearchOutcome(
+        data({
+          answerBox: { snippet: 'x' } as t.SearchResultData['answerBox'],
+          knowledgeGraph: {
+            title: 'OAuth',
+          } as t.SearchResultData['knowledgeGraph'],
+        }),
+        'oauth'
+      )
+    ).toBe('Found 2 results for "oauth"');
+  });
+
+  it('leaves a genuine zero-result search unlabeled, so the intent stands', () => {
+    expect(resolveSearchOutcome(data({ organic: [] }), 'oauth')).toBeUndefined();
+  });
+});

package/src/tools/search/schema.ts

@@ -1,3 +1,5 @@
+import { INTENT_PROPERTY } from '@/tools/intentArg';
+
 export enum DATE_RANGE {
   PAST_HOUR = 'h',
   PAST_24_HOURS = 'd',
@@ -71,6 +73,7 @@ export const newsSchema = {
 export const WebSearchToolSchema = {
   type: 'object',
   properties: {
+    intent: { ...INTENT_PROPERTY },
     query: querySchema,
     date: dateSchema,
     country: countrySchema,