@librechat/agents 3.3.6 → 3.3.8

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/activityLabel.ts

@@ -38,6 +38,14 @@ export type RunActivityLabelOptions = {
   thinkingExcerpts?: string[];
   /** Assistant's last text before the block (~200 chars), as intent context. */
   lastAssistantText?: string;
+  /**
+   * Headers already committed for earlier batches in this run (run order,
+   * most recent last). Continuity context: the prompt shows them so the new
+   * header extends the run's story instead of restating a line already on
+   * screen. Hosts should pass only COMMITTED labels — a pending slot's text
+   * is empty and a dropped fill never surfaced to the user.
+   */
+  previousLabels?: string[];
   /** Override for the default label system prompt. */
   prompt?: string;
   /** Per-entry serialization cap for the prompt. Default 600. */

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;
 };
@@ -295,10 +301,30 @@ export type SummaryBoundary = {
   contentIndex: number;
 };
 
+/**
+ * Semantic extent of a summary: the first source message compaction retained
+ * verbatim, meaning everything before it is covered. Distinct from `boundary`,
+ * which records where the block was emitted — a retained recency tail sits
+ * *before* the block's own position, so position alone cannot say what the
+ * summary replaced.
+ *
+ * Anchored to the retained side rather than the covered side so that a source
+ * message expanding into several messages (a steer splits an assistant entry
+ * into pre-steer, steer, and post-steer entries sharing one ID) stays whole:
+ * such a message is the retained anchor and survives intact.
+ */
+export type SummaryCoverage = {
+  retainedFromMessageId: string;
+};
+
 export type SummaryContentBlock = {
   type: ContentTypes.SUMMARY;
   content?: MessageContentComplex[];
+  /** Injection budget: provider output-token space when usage was reported, plus
+   *  the wrapper added at injection time. Not comparable with per-message counts
+   *  such as `indexTokenCountMap`, which are in the consumer's own tokenizer. */
   tokenCount?: number;
+  coverage?: SummaryCoverage;
   boundary?: SummaryBoundary;
   summaryVersion?: number;
   model?: string;