@librechat/agents 3.3.5 → 3.3.6

package/dist/types/tools/search/schema.d.ts

@@ -36,6 +36,15 @@ export declare const newsSchema: {
 export declare const WebSearchToolSchema: {
     readonly type: "object";
     readonly properties: {
+        readonly intent: {
+            readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+            readonly enum?: string[];
+            readonly items?: import("../..").JsonSchemaType;
+            readonly properties?: Record<string, import("../..").JsonSchemaType>;
+            readonly required?: string[];
+            readonly description?: string;
+            readonly additionalProperties?: boolean | import("../..").JsonSchemaType;
+        };
         readonly query: {
             readonly type: "string";
             readonly description: string;
@@ -72,6 +81,15 @@ export declare const WebSearchToolDefinition: {
     readonly schema: {
         readonly type: "object";
         readonly properties: {
+            readonly intent: {
+                readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+                readonly enum?: string[];
+                readonly items?: import("../..").JsonSchemaType;
+                readonly properties?: Record<string, import("../..").JsonSchemaType>;
+                readonly required?: string[];
+                readonly description?: string;
+                readonly additionalProperties?: boolean | import("../..").JsonSchemaType;
+            };
             readonly query: {
                 readonly type: "string";
                 readonly description: string;

package/dist/types/tools/search/tool.d.ts

@@ -2,6 +2,24 @@ import { DynamicStructuredTool } from '@langchain/core/tools';
 import type * as t from './types';
 import { DATE_RANGE } from './schema';
 import { createSearchAPI } from './search';
+/**
+ * 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, and a bare intent would
+ * otherwise settle mechanically from "Searching…" to "Searched…" and present
+ * a failed search as a successful one.
+ *
+ * Returns undefined for a genuine zero-result search, leaving the host's
+ * mechanical past-tense transform to label it.
+ */
+export declare function resolveSearchOutcome(data: t.SearchResultData, query: string): string | undefined;
 /**
  * Executes parallel searches and merges the results,
  * deduplicating top stories by link

package/dist/types/tools/toolOutputReferences.d.ts

@@ -69,8 +69,18 @@ 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
@@ -166,7 +176,7 @@ export declare 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>;
     /**
      * Captures a frozen snapshot of `runId`'s current entries and
      * returns a view that resolves placeholders against *only* that

package/dist/types/types/stream.d.ts

@@ -98,6 +98,13 @@ 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. Only present when the tool authored one — hosts apply
+     * the mechanical intent transform themselves when absent.
+     */
+    outcome?: string;
 };
 export type ProcessedContent = {
     type: ContentType;
@@ -265,6 +272,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/dist/types/types/tools.d.ts

@@ -224,8 +224,16 @@ 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';
@@ -486,6 +494,16 @@ export type InjectedMessage = {
     /** Only set when source is 'skill', for compaction preservation */
     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 */
@@ -498,6 +516,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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.3.5",
+  "version": "3.3.6",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/index.ts

@@ -26,6 +26,7 @@ export * from './tools/ReadFile';
 export * from './tools/skillCatalog';
 export * from './tools/ToolSearch';
 export * from './tools/ToolNode';
+export * from './tools/intentArg';
 export * from './tools/schema';
 export * from './tools/handlers';
 export * from './tools/local';

package/src/llm/openai/index.ts

@@ -51,6 +51,7 @@ import {
   projectOpenAIResponsesToolMessageContent,
   projectToolStreamContentForProvider,
 } from '@/messages/core';
+import { INTENT_ARG, isIntentLabelProperty } from '@/tools/intentArg';
 import { isReasoningModel, _convertMessagesToOpenAIParams } from './utils';
 import { dropRepeatedScalarMetadata } from './streamMetadata';
 
@@ -1003,6 +1004,65 @@ function createAbortHandler(controller: AbortController): () => void {
  * @param {Object} [fields] Additional fields to add to the OpenAI tool.
  * @returns {ToolDefinition} The inputted tool in OpenAI tool format.
  */
+/**
+ * OpenAI strict function schemas require every property to appear in
+ * `required`. The optional `intent` label (see `tools/intentArg.ts`) is
+ * deliberately NOT required — the same schema is callable from programmatic
+ * tool calling — so a tool auto-marked `strict: true` (the non-streaming
+ * `json_schema` structured-output path) would be rejected as invalid before
+ * execution. That path never streams a live label anyway, so the
+ * marker-identified property is dropped there; every other path keeps it.
+ */
+function stripIntentFromStrictTools<T extends object>(params: T): T {
+  const record = params as { tools?: unknown[] };
+  const tools = record.tools;
+  if (!Array.isArray(tools) || tools.length === 0) {
+    return params;
+  }
+  const nextTools = tools.map((tool) => {
+    const candidate = tool as {
+      strict?: boolean;
+      parameters?: { properties?: Record<string, unknown>; required?: unknown };
+      function?: {
+        strict?: boolean;
+        parameters?: {
+          properties?: Record<string, unknown>;
+          required?: unknown;
+        };
+      };
+    };
+    /** Chat-completions tools nest under `function`; responses-API tools are flat. */
+    const holder = candidate.function ?? candidate;
+    if (holder.strict !== true) {
+      return tool;
+    }
+    const parameters = holder.parameters;
+    const properties = parameters?.properties;
+    if (properties == null || !isIntentLabelProperty(properties[INTENT_ARG])) {
+      return tool;
+    }
+    const required = Array.isArray(parameters?.required)
+      ? (parameters.required as unknown[])
+      : [];
+    if (required.includes(INTENT_ARG)) {
+      return tool;
+    }
+    const { [INTENT_ARG]: _omit, ...restProps } = properties;
+    const nextParams = { ...parameters, properties: restProps };
+    if (candidate.function != null) {
+      return {
+        ...candidate,
+        function: { ...candidate.function, parameters: nextParams },
+      };
+    }
+    return { ...candidate, parameters: nextParams };
+  });
+  if (nextTools.every((tool, index) => tool === tools[index])) {
+    return params;
+  }
+  return { ...params, tools: nextTools } as T;
+}
+
 export function _convertToOpenAITool(
   tool: BindToolsInput,
   fields?: {
@@ -1184,10 +1244,12 @@ class LibreChatOpenAICompletions extends OriginalChatOpenAICompletions {
     options?: this['ParsedCallOptions'],
     extra?: { streaming?: boolean }
   ): ReturnType<OriginalChatOpenAICompletions['invocationParams']> {
-    return applyManagedRequestParams(super.invocationParams(options, extra), {
-      promptCacheExplicit: this.promptCacheExplicit,
-      safetyIdentifier: this.safetyIdentifier,
-    });
+    return stripIntentFromStrictTools(
+      applyManagedRequestParams(super.invocationParams(options, extra), {
+        promptCacheExplicit: this.promptCacheExplicit,
+        safetyIdentifier: this.safetyIdentifier,
+      })
+    );
   }
 
   protected _getReasoningParams(
@@ -1640,7 +1702,7 @@ class LibreChatOpenAIResponses extends OriginalChatOpenAIResponses {
         ]),
       ];
     }
-    return params;
+    return stripIntentFromStrictTools(params);
   }
 
   async completionWithRetry(
@@ -1741,10 +1803,12 @@ class LibreChatAzureOpenAICompletions extends OriginalAzureChatOpenAICompletions
     options?: this['ParsedCallOptions'],
     extra?: { streaming?: boolean }
   ): ReturnType<OriginalAzureChatOpenAICompletions['invocationParams']> {
-    return applyManagedRequestParams(super.invocationParams(options, extra), {
-      promptCacheExplicit: this.promptCacheExplicit,
-      safetyIdentifier: this.safetyIdentifier,
-    });
+    return stripIntentFromStrictTools(
+      applyManagedRequestParams(super.invocationParams(options, extra), {
+        promptCacheExplicit: this.promptCacheExplicit,
+        safetyIdentifier: this.safetyIdentifier,
+      })
+    );
   }
 
   protected _getReasoningParams(
@@ -1888,7 +1952,7 @@ class LibreChatAzureOpenAIResponses extends OriginalAzureChatOpenAIResponses {
         ]),
       ];
     }
-    return params;
+    return stripIntentFromStrictTools(params);
   }
 
   async completionWithRetry(

package/src/llm/openai/llm.spec.ts

@@ -1206,6 +1206,111 @@ describe('ChatOpenAICompletions strict tools for structured output', () => {
       toolStrict({ response_format: { type: 'json_object' } })
     ).toBeUndefined();
   });
+
+  describe('optional intent labels under strict mode', () => {
+    const intentTool = {
+      type: 'function' as const,
+      function: {
+        name: 'search_mcp_docs',
+        description: 'Search docs',
+        parameters: {
+          type: 'object',
+          properties: {
+            intent: {
+              type: 'string',
+              description:
+                'ALWAYS write this field FIRST, before any other argument. One short sentence…',
+            },
+            query: { type: 'string' },
+          },
+          required: ['query'],
+        },
+      },
+    };
+
+    function toolProperties(options: Record<string, unknown>): string[] {
+      const model = new ChatOpenAI({ model: 'gpt-4', apiKey: 'test-key' });
+      const completions = completionsOf<InvocationParamsDelegate>(model);
+      const params = completions.invocationParams({
+        tools: [intentTool],
+        ...options,
+      }) as unknown as {
+        tools?: { function: { parameters: { properties: object } } }[];
+      };
+      return Object.keys(params.tools?.[0]?.function.parameters.properties ?? {});
+    }
+
+    it('drops the optional label when strict is auto-enabled (invalid otherwise)', () => {
+      expect(toolProperties({ response_format: jsonSchemaResponseFormat })).toEqual(['query']);
+    });
+
+    it('keeps the label on non-strict requests', () => {
+      expect(toolProperties({})).toEqual(['intent', 'query']);
+    });
+
+    /**
+     * The Responses API flattens tools to `{type, name, parameters, strict}`
+     * and does NOT infer strict from a `json_schema` response_format the way
+     * Completions does — an explicit `strict` (per-call option or on the tool)
+     * is what turns it on there.
+     */
+    function responsesToolProperties(
+      options: Record<string, unknown>
+    ): string[] {
+      const model = new ChatOpenAI({ model: 'gpt-4', apiKey: 'test-key' });
+      const responses = (
+        model as unknown as {
+          responses: {
+            invocationParams: (o: Record<string, unknown>) => {
+              tools?: { parameters?: { properties?: object } }[];
+            };
+          };
+        }
+      ).responses;
+      const params = responses.invocationParams({
+        tools: [intentTool],
+        ...options,
+      });
+      return Object.keys(params.tools?.[0]?.parameters?.properties ?? {});
+    }
+
+    it('drops the label on the RESPONSES delegate under strict too', () => {
+      expect(responsesToolProperties({ strict: true })).toEqual(['query']);
+    });
+
+    it('keeps the label on a non-strict RESPONSES request', () => {
+      expect(responsesToolProperties({})).toEqual(['intent', 'query']);
+    });
+
+    it('spares a business `intent` param even under strict', () => {
+      const businessTool = {
+        type: 'function' as const,
+        function: {
+          name: 'create_record',
+          parameters: {
+            type: 'object',
+            properties: {
+              intent: { type: 'string', description: 'CRM intent category' },
+              title: { type: 'string' },
+            },
+            required: ['intent', 'title'],
+          },
+        },
+      };
+      const model = new ChatOpenAI({ model: 'gpt-4', apiKey: 'test-key' });
+      const completions = completionsOf<InvocationParamsDelegate>(model);
+      const params = completions.invocationParams({
+        tools: [businessTool],
+        response_format: jsonSchemaResponseFormat,
+      }) as unknown as {
+        tools?: { function: { parameters: { properties: object } } }[];
+      };
+      expect(Object.keys(params.tools?.[0]?.function.parameters.properties ?? {})).toEqual([
+        'intent',
+        'title',
+      ]);
+    });
+  });
 });
 
 describe('ChatOpenAI._streamChatModelEvents (native, fork)', () => {

package/src/stream.ts

@@ -39,6 +39,7 @@ import {
   calculateMaxToolResultChars,
   truncateToolResultContent,
 } from '@/utils/truncation';
+import { resolveToolOutcome, outcomeFieldsFromResult } from '@/tools/intentArg';
 import { TOOL_OUTPUT_REF_PATTERN } from '@/tools/toolOutputReferences';
 import { safeDispatchCustomEvent } from '@/utils/events';
 import { isGoogleLike } from '@/utils/llm';
@@ -859,6 +860,11 @@ async function dispatchEagerToolCompletions(args: {
         maxToolResultChars
       ).content;
     }
+    const outcome = resolveToolOutcome(
+      record.request.args,
+      outcomeFieldsFromResult(result),
+      { isError: result.status === 'error' }
+    );
 
     try {
       const dispatched = await safeDispatchCustomEvent(
@@ -878,6 +884,7 @@ async function dispatchEagerToolCompletions(args: {
               id: result.toolCallId,
               output,
               progress: 1,
+              ...(outcome != null && { outcome }),
             } as t.ProcessedToolCall,
           },
         },
@@ -2160,7 +2167,7 @@ export function createContentAggregator(): t.ContentAggregatorResult {
         toolCallContentIndexMap.delete(existingToolCallId);
       }
 
-      const newToolCall: ToolCall & t.PartMetadata = {
+      const newToolCall: ToolCall & t.PartMetadata & { outcome?: string } = {
         id,
         name,
         args,
@@ -2180,6 +2187,10 @@ export function createContentAggregator(): t.ContentAggregatorResult {
       if (finalUpdate) {
         newToolCall.progress = 1;
         newToolCall.output = contentPart.tool_call.output;
+        const outcome = (contentPart.tool_call as t.ToolCallPart).outcome;
+        if (outcome != null) {
+          newToolCall.outcome = outcome;
+        }
       }
 
       contentParts[index] = {

package/src/tools/BashExecutor.ts

@@ -16,6 +16,7 @@ import {
   normalizeCodeApiRequestError,
   resolveCodeApiAuthHeaders,
 } from './CodeExecutor';
+import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { Constants } from '@/common';
 
 config();
@@ -26,6 +27,7 @@ const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
 export const BashExecutionToolSchema = {
   type: 'object',
   properties: {
+    intent: { ...INTENT_PROPERTY },
     command: {
       type: 'string',
       description: `The bash command or script to execute.
@@ -187,16 +189,20 @@ function createBashExecutionTool(
       /* Drop any model-supplied `runtime_session_hint` from the raw args: the
        * hint must only come from ToolNode's injected `_runtime_session_hint`
        * (below), never from the tool call itself. */
+      /* `intent` is a UI display label — never part of the wire body. */
       const {
         command,
+        intent: _ignoredIntent,
         runtime_session_hint: _ignoredModelHint,
         ...rest
       } = rawInput as {
         command: string;
+        intent?: unknown;
         runtime_session_hint?: unknown;
         args?: string[];
       };
       void _ignoredModelHint;
+      void _ignoredIntent;
       const { session_id, _injected_files, _runtime_session_hint } =
         (config.toolCall ?? {}) as {
           session_id?: string;

package/src/tools/BashProgrammaticToolCalling.ts

@@ -21,6 +21,7 @@ import {
   executeTools,
   formatCompletedResponse,
 } from './ProgrammaticToolCalling';
+import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { Constants } from '@/common';
 
 config();
@@ -115,6 +116,7 @@ export function createBashProgrammaticToolCallingSchema(
   return {
     type: 'object',
     properties: {
+      intent: { ...INTENT_PROPERTY },
       code: {
         type: 'string',
         minLength: 1,

package/src/tools/CodeExecutor.ts

@@ -5,6 +5,7 @@ import { getEnvironmentVariable } from '@langchain/core/utils/env';
 import { tool, DynamicStructuredTool } from '@langchain/core/tools';
 import type * as t from '@/types';
 import { appendCodeSessionFileSummary } from '@/tools/CodeSessionFileSummary';
+import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { EnvVar, Constants } from '@/common';
 
 export {
@@ -75,6 +76,7 @@ const SUPPORTED_LANGUAGES = [
 export const CodeExecutionToolSchema = {
   type: 'object',
   properties: {
+    intent: { ...INTENT_PROPERTY },
     lang: {
       type: 'string',
       enum: SUPPORTED_LANGUAGES,
@@ -346,18 +348,22 @@ function createCodeExecutionTool(
        * injected `_runtime_session_hint` (below). Spreading `...rest` into
        * postData would otherwise let a tool call opt itself into / pick a
        * stateful runtime even when statefulSessions is off. */
+      /* `intent` is a UI display label — never part of the wire body. */
       const {
         lang,
         code,
+        intent: _ignoredIntent,
         runtime_session_hint: _ignoredModelHint,
         ...rest
       } = rawInput as {
         lang: SupportedLanguage;
         code: string;
+        intent?: unknown;
         runtime_session_hint?: unknown;
         args?: string[];
       };
       void _ignoredModelHint;
+      void _ignoredIntent;
       /**
        * Extract session context from config.toolCall (injected by ToolNode).
        * - session_id: associates with the previous run.

package/src/tools/ProgrammaticToolCalling.ts

@@ -24,6 +24,7 @@ import {
   createCodeApiRunTimeoutSchema,
   resolveCodeApiRunTimeoutMs,
 } from './ptcTimeout';
+import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { Constants } from '@/common';
 
 config();
@@ -89,6 +90,7 @@ export function createProgrammaticToolCallingSchema(
   return {
     type: 'object',
     properties: {
+      intent: { ...INTENT_PROPERTY },
       code: {
         type: 'string',
         minLength: 1,

package/src/tools/ReadFile.ts

@@ -1,4 +1,5 @@
 // src/tools/ReadFile.ts
+import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { Constants } from '@/common';
 
 export const ReadFileToolName = Constants.READ_FILE;
@@ -22,6 +23,7 @@ CONSTRAINTS:
 export const ReadFileToolSchema = {
   type: 'object',
   properties: {
+    intent: { ...INTENT_PROPERTY },
     path: {
       type: 'string',
       description:

package/src/tools/SkillTool.ts

@@ -1,4 +1,5 @@
 // src/tools/SkillTool.ts
+import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { Constants } from '@/common';
 
 export const SkillToolName = Constants.SKILL_TOOL;
@@ -26,6 +27,7 @@ CONSTRAINTS:
 export const SkillToolSchema = {
   type: 'object',
   properties: {
+    intent: { ...INTENT_PROPERTY },
     skillName: {
       type: 'string',
       description:

package/src/tools/SubagentTool.ts

@@ -1,5 +1,6 @@
 import type { JsonSchemaType, LCTool } from '@/types/tools';
 import type { SubagentConfig } from '@/types';
+import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { Constants } from '@/common';
 
 export const SubagentToolName = Constants.SUBAGENT;
@@ -29,6 +30,7 @@ const SUBAGENT_TYPE_PROP_DESCRIPTION =
 export const SubagentToolSchema = {
   type: 'object',
   properties: {
+    intent: { ...INTENT_PROPERTY },
     description: {
       type: 'string',
       description: DESCRIPTION_PROP_DESCRIPTION,
@@ -67,6 +69,7 @@ export function buildSubagentToolParams(configs: SubagentConfig[]): {
     schema: {
       type: 'object',
       properties: {
+        intent: { ...INTENT_PROPERTY },
         description: {
           type: 'string',
           description: DESCRIPTION_PROP_DESCRIPTION,