@librechat/agents 3.3.6 → 3.3.7

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

@@ -4,6 +4,8 @@ import {
   INTENT_ARG,
   INTENT_PROPERTY,
   INTENT_DESCRIPTION,
+  INTENT_LABEL_MARKER,
+  withoutIntent,
   withIntent,
   readIntent,
   stripIntent,
@@ -11,6 +13,7 @@ import {
   readOutcomeFields,
   resolveToolOutcome,
 } from '../intentArg';
+import { ReadFileToolSchema } from '../ReadFile';
 
 describe('withIntent', () => {
   const base: JsonSchemaType = {
@@ -72,7 +75,83 @@ describe('withIntent', () => {
   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');
+    /** Sibling differentiation is the headline case; models emit identical
+     *  labels for parallel calls without it. */
+    expect(INTENT_DESCRIPTION).toContain('Sibling calls to one tool must differ');
+  });
+
+  it('opens with the exported marker so host strip passes can key on it', () => {
+    expect(INTENT_DESCRIPTION.startsWith(INTENT_LABEL_MARKER)).toBe(true);
+  });
+
+  it('stays terse — it is repeated per tool, per request', () => {
+    expect(INTENT_DESCRIPTION.length).toBeLessThanOrEqual(300);
+  });
+});
+
+describe('withoutIntent', () => {
+  it('removes the injected label — the opt-out for embedders that render none', () => {
+    const withLabel = withIntent({
+      type: 'object',
+      properties: { query: { type: 'string' } },
+      required: ['query'],
+    });
+    const stripped = withoutIntent(withLabel);
+    expect(Object.keys(stripped?.properties ?? {})).toEqual(['query']);
+    expect(stripped?.required).toEqual(['query']);
+  });
+
+  it('never removes a tool-owned business `intent` parameter', () => {
+    const business: JsonSchemaType = {
+      type: 'object',
+      properties: { intent: { type: 'string', description: 'CRM intent category' } },
+      required: ['intent'],
+    };
+    expect(withoutIntent(business)).toBe(business);
+  });
+
+  it('is a no-op on schemas without the label', () => {
+    const plain: JsonSchemaType = { type: 'object', properties: { q: { type: 'string' } } };
+    expect(withoutIntent(plain)).toBe(plain);
+    expect(withoutIntent(undefined)).toBeUndefined();
+  });
+
+  it('prunes intent from `required` too, so the schema stays valid', () => {
+    /** Strict-mode normalization lists every property in `required`; leaving
+     *  a dangling entry yields invalid JSON Schema the provider rejects. */
+    const strict: JsonSchemaType = {
+      type: 'object',
+      properties: { intent: { ...INTENT_PROPERTY }, path: { type: 'string' } },
+      required: ['intent', 'path'],
+    };
+    const stripped = withoutIntent(strict);
+    expect(Object.keys(stripped?.properties ?? {})).toEqual(['path']);
+    expect(stripped?.required).toEqual(['path']);
+  });
+
+  it('drops `required` entirely when intent was its only entry', () => {
+    const onlyIntent: JsonSchemaType = {
+      type: 'object',
+      properties: { intent: { ...INTENT_PROPERTY } },
+      required: ['intent'],
+    };
+    const stripped = withoutIntent(onlyIntent);
+    expect(stripped?.required).toBeUndefined();
+    expect(Object.keys(stripped?.properties ?? {})).toEqual([]);
+  });
+
+  it('accepts a readonly `as const` native schema without a cast', () => {
+    /** ReadFileToolSchema is declared `as const`, so `required` is a readonly
+     *  tuple — this call is the compile-time assertion that the advertised
+     *  opt-out is usable on the schemas it exists for. */
+    const stripped = withoutIntent(ReadFileToolSchema);
+    expect(Object.keys(stripped?.properties ?? {})).toEqual(['path']);
+    expect(stripped?.required).toEqual(['path']);
+  });
+
+  it('round-trips with withIntent', () => {
+    const base: JsonSchemaType = { type: 'object', properties: { q: { type: 'string' } } };
+    expect(withoutIntent(withIntent(base))).toEqual(base);
   });
 });
 
@@ -130,7 +209,7 @@ describe('applyOutcome', () => {
   });
 
   it('ignores a blank outcome', () => {
-    expect(applyOutcome(intent, { outcome: '  ' })).toBe('Searched for OAuth handling');
+    expect(applyOutcome(intent, { outcome: '  ' })).toBe(intent);
   });
 
   it('applies outcome_patch to the first occurrence only, case-sensitive', () => {
@@ -141,34 +220,31 @@ describe('applyOutcome', () => {
     ).toBe('Searched for Searching patterns');
     expect(
       applyOutcome(intent, { outcome_patch: { from: 'searching', to: 'searched' } })
-    ).toBe('Searched for OAuth handling');
+    ).toBe(intent);
   });
 
   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: '', to: 'x' } })).toBe(intent);
     expect(applyOutcome(intent, { outcome_patch: { from: 'Grepping', to: 'Grepped' } })).toBe(
-      'Searched for OAuth handling'
+      intent
     );
   });
 
-  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');
+  /**
+   * There is no mechanical tense rewrite: a closed English verb list would
+   * never fire for non-English labels, and would fire for some siblings but
+   * not others inside one group. Completion is a UI state, not a tense.
+   */
+  it('returns the intent unchanged when the tool authored no outcome', () => {
+    for (const label of [
+      'Reading the callback router',
+      'Recording the OAuth callback location',
+      'searching for OAuth handling',
+      'Buscando el manejo de OAuth',
+      'Searching',
+    ]) {
+      expect(applyOutcome(label)).toBe(label);
+    }
   });
 
   it('returns undefined with neither intent nor outcome', () => {
@@ -215,7 +291,7 @@ describe('resolveToolOutcome', () => {
     expect(oversized?.length).toBe(256);
     expect(oversized?.endsWith('…')).toBe(true);
     expect(resolveToolOutcome(args, { outcome: ' \n \t ' })).toBe(
-      'Searched for OAuth handling'
+      'Searching for OAuth handling'
     );
   });
 
@@ -240,7 +316,7 @@ describe('resolveToolOutcome', () => {
     ).toBe('Search failed for OAuth handling');
   });
 
-  it('never falls back to the mechanical transform on a failed call', () => {
+  it('never reuses the in-flight intent as a failed call\'s settled label', () => {
     expect(
       resolveToolOutcome(
         args,

package/src/tools/intentArg.ts

@@ -8,8 +8,9 @@
  * 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.
+ * (`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
@@ -23,15 +24,34 @@ import type { JsonSchemaType, OutcomePatch } from '@/types';
 /** Argument carrying the model-authored label for a tool call. */
 export const INTENT_ARG = 'intent';
 
-/** Model-facing instruction for the injected `intent` property. */
+/**
+ * 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 =
-  'ALWAYS write this field FIRST, before any other argument. One short sentence, ' +
-  'present progressive, stating what this specific call is about to do: ' +
-  '"Searching for OAuth handling in the callback router". It is shown to the user ' +
-  'as the live status label for this call while it runs, so write it for a human ' +
-  'reading a progress line. Do not restate the tool name. Do not exceed one sentence. ' +
-  'When you make several calls to the same tool in one turn, each intent must ' +
-  'distinguish that call from its siblings.';
+  `${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
@@ -59,10 +79,60 @@ export function isIntentLabelProperty(property: unknown): boolean {
   return (
     record.type === 'string' &&
     typeof record.description === 'string' &&
-    record.description.startsWith('ALWAYS write this field FIRST')
+    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
@@ -130,53 +200,6 @@ export function stripIntent(args: unknown): unknown {
   return rest;
 }
 
-/**
- * Leading-verb map for the mechanical outcome transform, keyed by the
- * lowercased first word of the intent. Deliberately small: an unknown leading
- * word leaves the intent unchanged rather than mangling it.
- */
-const OUTCOME_VERB_MAP: ReadonlyMap<string, string> = new Map([
-  ['searching', 'Searched'],
-  ['reading', 'Read'],
-  ['writing', 'Wrote'],
-  ['editing', 'Edited'],
-  ['running', 'Ran'],
-  ['creating', 'Created'],
-  ['checking', 'Checked'],
-  ['fetching', 'Fetched'],
-  ['listing', 'Listed'],
-  ['looking', 'Looked'],
-  ['building', 'Built'],
-  ['deleting', 'Deleted'],
-  ['updating', 'Updated'],
-  ['adding', 'Added'],
-  ['removing', 'Removed'],
-  ['verifying', 'Verified'],
-  ['analyzing', 'Analyzed'],
-  ['generating', 'Generated'],
-  ['delegating', 'Delegated'],
-  ['spawning', 'Spawned'],
-  ['compiling', 'Compiled'],
-  ['grepping', 'Grepped'],
-]);
-
-function matchLeadingCase(replacement: string, original: string): string {
-  if (original.charAt(0) === original.charAt(0).toLowerCase()) {
-    return replacement.charAt(0).toLowerCase() + replacement.slice(1);
-  }
-  return replacement;
-}
-
-function transformLeadingVerb(intent: string): string {
-  const spaceIdx = intent.search(/\s/);
-  const leading = spaceIdx === -1 ? intent : intent.slice(0, spaceIdx);
-  const mapped = OUTCOME_VERB_MAP.get(leading.toLowerCase());
-  if (mapped == null) {
-    return intent;
-  }
-  return matchLeadingCase(mapped, leading) + intent.slice(leading.length);
-}
-
 /**
  * Resolves the settled label for a call from its model-authored `intent` and
  * the tool's result fields, in precedence order:
@@ -184,8 +207,18 @@ function transformLeadingVerb(intent: string): string {
  *  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.
+ *  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
@@ -209,7 +242,7 @@ export function applyOutcome(
      *  text (e.g. labels derived from shell syntax). */
     return intent.replace(patch.from, () => patch.to);
   }
-  return transformLeadingVerb(intent);
+  return intent;
 }
 
 /**
@@ -236,15 +269,16 @@ function boundOutcomeLabel(label: string | undefined): 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.
+ * 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 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.
+ * 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,

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

@@ -84,7 +84,7 @@ describe('resolveSearchOutcome', () => {
     ).toBe('Found 2 results for "oauth"');
   });
 
-  it('leaves a genuine zero-result search to the mechanical transform', () => {
+  it('leaves a genuine zero-result search unlabeled, so the intent stands', () => {
     expect(resolveSearchOutcome(data({ organic: [] }), 'oauth')).toBeUndefined();
   });
 });

package/src/tools/search/tool.ts

@@ -35,12 +35,12 @@ import { Constants } from '@/common';
  *
  * A caught provider or processing failure is reported through `data.error`
  * while the tool still returns NORMALLY, so that case must author its own
- * label: the `ToolMessage` carries success status, and a bare intent would
- * otherwise settle mechanically from "Searching…" to "Searched…" and present
- * a failed search as a successful one.
+ * label: the `ToolMessage` carries success status, so without an authored
+ * outcome the in-flight intent ("Searching…") would stand as the settled
+ * label and present a failed search as an ordinary one.
  *
- * Returns undefined for a genuine zero-result search, leaving the host's
- * mechanical past-tense transform to label it.
+ * Returns undefined for a genuine zero-result search, leaving the
+ * model-authored intent to stand unchanged as the label.
  */
 export function resolveSearchOutcome(
   data: t.SearchResultData,

package/src/types/stream.ts

@@ -145,8 +145,14 @@ export type ProcessedToolCall = {
   /**
    * Settled label for the call, resolved from the tool-supplied
    * `outcome`/`outcome_patch` result fields against the model-authored
-   * `intent` arg. Only present when the tool authored one — hosts apply
-   * the mechanical intent transform themselves when absent.
+   * `intent` arg. Present ONLY when the tool authored one.
+   *
+   * When absent, display the `intent` arg unchanged — do NOT rewrite its
+   * tense. A gerund→past-tense rewrite can only be a closed list of English
+   * verbs, so it never fires for the non-English labels this feature expects
+   * and fires for some sibling calls but not others within one group.
+   * Completion belongs to UI state (the shimmer stopping, the icon settling),
+   * which is language-neutral and always consistent.
    */
   outcome?: string;
 };