@librechat/agents 3.3.5 → 3.3.7

package/src/tools/search/tool.ts

@@ -17,6 +17,7 @@ import { createKeenableScraper } from './keenable-scraper';
 import { createSerperScraper } from './serper-scraper';
 import { createTavilyScraper } from './tavily-scraper';
 import { createFirecrawlScraper } from './firecrawl';
+import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { createCrwScraper } from './crw-scraper';
 import { expandHighlights } from './highlights';
 import { formatResultsForLLM } from './format';
@@ -24,6 +25,46 @@ import { createDefaultLogger } from './utils';
 import { createReranker } from './rerankers';
 import { Constants } from '@/common';
 
+/**
+ * Settled label for a `web_search` call's intent (see `intentArg.ts`).
+ *
+ * Counts the result kinds `formatResultsForLLM` actually renders —
+ * `references` only tracks links embedded in extracted highlights, so it
+ * undercounts ordinary results and can overcount when one highlight embeds
+ * several links.
+ *
+ * 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, 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
+ * model-authored intent to stand unchanged as the label.
+ */
+export function resolveSearchOutcome(
+  data: t.SearchResultData,
+  query: string
+): string | undefined {
+  if (data.error != null && data.error !== '') {
+    return `Search failed for "${query}"`;
+  }
+  const count =
+    (data.organic?.length ?? 0) +
+    (data.topStories?.length ?? 0) +
+    (data.news?.length ?? 0) +
+    (data.images?.length ?? 0) +
+    (data.videos?.length ?? 0) +
+    (data.places?.length ?? 0) +
+    (data.peopleAlsoAsk?.length ?? 0) +
+    (data.knowledgeGraph != null ? 1 : 0) +
+    (data.answerBox != null ? 1 : 0);
+  if (count === 0) {
+    return undefined;
+  }
+  return `Found ${count} result${count === 1 ? '' : 's'} for "${query}"`;
+}
+
 /**
  * Executes parallel searches and merges the results,
  * deduplicating top stories by link
@@ -335,7 +376,11 @@ function createTool({
         maxOutputChars
       );
       const data: t.SearchResultData = { turn, ...searchResult, references };
-      return [output, { [Constants.WEB_SEARCH]: data }];
+      const outcome = resolveSearchOutcome(data, query);
+      return [
+        output,
+        { [Constants.WEB_SEARCH]: data, ...(outcome != null && { outcome }) },
+      ];
     },
     {
       name: WebSearchToolName,
@@ -421,6 +466,7 @@ export const createSearchTool = (
       : tavilySearchOptions;
 
   const schemaProperties: Record<string, unknown> = {
+    intent: { ...INTENT_PROPERTY },
     query: querySchema,
     date: dateSchema,
     images: imagesSchema,

package/src/tools/subagent/SubagentExecutor.ts

@@ -115,7 +115,7 @@ type SanitizedStepCompleted =
     };
 
 type SanitizedProcessedToolCall = Partial<
-  Pick<ProcessedToolCall, 'args' | 'id' | 'name' | 'output' | 'progress'>
+  Pick<ProcessedToolCall, 'args' | 'id' | 'name' | 'output' | 'progress' | 'outcome'>
 >;
 
 type SanitizedRunStepCompleted = {
@@ -1195,6 +1195,7 @@ function sanitizeProcessedToolCall(
     sanitized.args = call.args;
   }
   assignString(sanitized, 'output', call.output);
+  assignString(sanitized, 'outcome', call.outcome);
   assignNumber(sanitized, 'progress', call.progress);
   return sanitized;
 }

package/src/tools/toolOutputReferences.ts

@@ -30,6 +30,25 @@ import {
   HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE,
 } from '@/utils/truncation';
 import { isComputerCallOutputMessage } from '@/utils/toolContent';
+import { INTENT_ARG } from '@/tools/intentArg';
+
+/** Parses a stringified JSON object arg; undefined for anything else. */
+function parseStringifiedArgsObject(
+  value: string
+): Record<string, unknown> | undefined {
+  if (!value.trim().startsWith('{')) {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    if (parsed != null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
 
 /**
  * Non-global matcher for a single `{{tool<i>turn<n>}}` placeholder.
@@ -89,9 +108,20 @@ export type ResolveResult<T> = {
  * point in time, ignoring any subsequent registrations.
  */
 export interface ToolOutputResolveView {
-  resolve<T>(args: T): ResolveResult<T>;
+  resolve<T>(args: T, options?: ResolveOptions): ResolveResult<T>;
 }
 
+/**
+ * Per-call resolution options. `substituteIntentKey` opts the top-level
+ * `intent` key back INTO placeholder substitution: the exemption protects
+ * the injected display label, but a tool whose own schema declares a
+ * business parameter named `intent` (the injectors skip such tools) still
+ * needs references piped into it like any other argument.
+ */
+export type ResolveOptions = {
+  substituteIntentKey?: boolean;
+};
+
 /**
  * Pre-resolved arg map keyed by `toolCallId`. Used by the mixed
  * direct+event dispatch path to feed event calls' resolved args
@@ -333,12 +363,16 @@ export class ToolOutputReferenceRegistry {
    * the serialized args, the original input is returned without
    * walking the tree.
    */
-  resolve<T>(runId: string | undefined, args: T): ResolveResult<T> {
+  resolve<T>(
+    runId: string | undefined,
+    args: T,
+    options?: ResolveOptions
+  ): ResolveResult<T> {
     if (!hasAnyPlaceholder(args)) {
       return { resolved: args, unresolved: [] };
     }
     const bucket = this.runStates.get(this.keyFor(runId));
-    return this.resolveAgainst(bucket?.entries ?? EMPTY_ENTRIES, args);
+    return this.resolveAgainst(bucket?.entries ?? EMPTY_ENTRIES, args, options);
   }
 
   /**
@@ -358,27 +392,52 @@ export class ToolOutputReferenceRegistry {
       ? new Map(bucket.entries)
       : EMPTY_ENTRIES;
     return {
-      resolve: <T>(args: T): ResolveResult<T> =>
-        this.resolveAgainst(entries, args),
+      resolve: <T>(args: T, options?: ResolveOptions): ResolveResult<T> =>
+        this.resolveAgainst(entries, args, options),
     };
   }
 
   private resolveAgainst<T>(
     entries: ReadonlyMap<string, string>,
-    args: T
+    args: T,
+    options?: ResolveOptions
   ): ResolveResult<T> {
     if (!hasAnyPlaceholder(args)) {
       return { resolved: args, unresolved: [] };
     }
+    const exemptIntentKey = options?.substituteIntentKey !== true;
     const unresolved = new Set<string>();
-    const resolved = this.transform(entries, args, unresolved) as T;
+    /**
+     * Providers may deliver the args OBJECT as a JSON string. A plain
+     * string-root transform would expand placeholders inside the `intent`
+     * label too, bypassing the top-level exclusion below — parse, transform
+     * key-aware, and re-serialize so the label stays verbatim while every
+     * other field still substitutes. Only taken when an `intent` key is
+     * actually present; other strings keep the fast raw-string path.
+     */
+    if (exemptIntentKey && typeof args === 'string') {
+      const parsedRoot = parseStringifiedArgsObject(args);
+      if (parsedRoot != null && INTENT_ARG in parsedRoot) {
+        const resolved = JSON.stringify(
+          this.transform(entries, parsedRoot, unresolved, true)
+        ) as T;
+        return { resolved, unresolved: Array.from(unresolved) };
+      }
+    }
+    const resolved = this.transform(
+      entries,
+      args,
+      unresolved,
+      exemptIntentKey
+    ) as T;
     return { resolved, unresolved: Array.from(unresolved) };
   }
 
   private transform(
     entries: ReadonlyMap<string, string>,
     value: unknown,
-    unresolved: Set<string>
+    unresolved: Set<string>,
+    exemptRootIntent = false
   ): unknown {
     if (typeof value === 'string') {
       return this.replaceInString(entries, value, unresolved);
@@ -390,7 +449,16 @@ export class ToolOutputReferenceRegistry {
       const source = value as Record<string, unknown>;
       const next: Record<string, unknown> = {};
       for (const [key, item] of Object.entries(source)) {
-        next[key] = this.transform(entries, item, unresolved);
+        /**
+         * The top-level `intent` arg is a display label, never a data
+         * channel: expanding a `{{tool<i>turn<n>}}` placeholder there would
+         * dump a stored output (up to the registry cap) into a single-line
+         * UI label and persist it with the message. Left verbatim instead.
+         */
+        next[key] =
+          exemptRootIntent && key === INTENT_ARG
+            ? item
+            : this.transform(entries, item, unresolved);
       }
       return next;
     }

package/src/types/stream.ts

@@ -142,6 +142,19 @@ export type ProcessedToolCall = {
   id: string;
   output: string;
   progress: number;
+  /**
+   * Settled label for the call, resolved from the tool-supplied
+   * `outcome`/`outcome_patch` result fields against the model-authored
+   * `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;
 };
 
 export type ProcessedContent = {
@@ -336,6 +349,11 @@ export type ToolCallPart = {
   id?: string;
   /** If provided, the output of the tool call */
   output?: ToolResultContent['content'];
+  /**
+   * Tool-authored settled label for the call (see `ProcessedToolCall.outcome`),
+   * preserved through aggregation so it survives persistence/reload.
+   */
+  outcome?: string;
   /** Auth URL */
   auth?: string;
   /** Expiration time */

package/src/types/tools.ts

@@ -236,8 +236,12 @@ export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
 export type ToolEndEvent = {
   /** The Step Id of the Tool Call */
   id: string;
-  /** The Completed Tool Call */
-  tool_call: ToolCall;
+  /**
+   * The Completed Tool Call. Carries the tool-authored `outcome` label when
+   * present (see `ProcessedToolCall.outcome`) so `ON_RUN_STEP_COMPLETED`
+   * consumers can read it without an unsafe cast.
+   */
+  tool_call: ToolCall & { output?: string; progress?: number; outcome?: string };
   /** The content index of the tool call */
   index: number;
   type?: 'tool_call';
@@ -521,6 +525,17 @@ export type InjectedMessage = {
   skillName?: string;
 };
 
+/**
+ * In-place edit of a call's model-authored `intent` label: the first
+ * occurrence of `from` in the intent is replaced with `to` (case-sensitive).
+ * Lets a tool settle the label while preserving the model's own phrasing,
+ * e.g. `{ from: 'Searching', to: 'Searched' }`.
+ */
+export type OutcomePatch = {
+  from: string;
+  to: string;
+};
+
 /** Result for a single tool call in event-driven execution */
 export type ToolExecuteResult = {
   /** Matches ToolCallRequest.id */
@@ -533,6 +548,13 @@ export type ToolExecuteResult = {
   status: 'success' | 'error';
   /** Error message if status is 'error' */
   errorMessage?: string;
+  /**
+   * Settled human-readable label for this call, replacing the model-authored
+   * `intent` arg in the UI. Full replacement; wins over `outcome_patch`.
+   */
+  outcome?: string;
+  /** In-place edit of the model-authored `intent` label (see {@link OutcomePatch}). */
+  outcome_patch?: OutcomePatch;
   /**
    * Messages to inject into graph state after the ToolMessage for this call.
    * Placed after tool results to respect provider message ordering (tool_call -> tool_result adjacency).