@librechat/agents 3.3.4 → 3.3.6

package/src/specs/preemptSeal.test.ts

@@ -0,0 +1,309 @@
+// src/specs/preemptSeal.test.ts
+/**
+ * End-to-end cooperative seal flow through a real `Run`: fake model streams,
+ * the host requests a preempt, the stream seals at a safe chunk, the
+ * `PreemptBoundary` drain decides what happens next. Everything below runs
+ * the dispatch-synchronous loop in `attemptInvoke` (no registered
+ * CHAT_MODEL_STREAM handler), which is the only loop allowed to seal.
+ */
+import { HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import { RunnableBinding } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import { Providers } from '@/common';
+import { HookRegistry } from '@/hooks/HookRegistry';
+import type { HookCallback } from '@/hooks/types';
+import { FakeChatModel } from '@/llm/fake';
+import { Run } from '@/run';
+
+const FULL_RESPONSE = 'Alpha beta gamma delta epsilon zeta';
+const RESUMED_RESPONSE = 'Continuing after the steer.';
+
+const streamConfig = {
+  configurable: { thread_id: 'preempt-seal-e2e' },
+  streamMode: 'values' as const,
+  version: 'v2' as const,
+};
+
+async function createSealRun(options: {
+  runId: string;
+  hook: HookCallback<'PreemptBoundary'>;
+  responses: string[];
+  stopHook?: HookCallback<'Stop'>;
+  modelCallbacks?: FakeChatModel['callbacks'];
+}): Promise<Run<t.IState>> {
+  const registry = new HookRegistry();
+  registry.register('PreemptBoundary', { hooks: [options.hook] });
+  if (options.stopHook) {
+    registry.register('Stop', { hooks: [options.stopHook] });
+  }
+  const run = await Run.create<t.IState>({
+    runId: options.runId,
+    graphConfig: {
+      type: 'standard',
+      llmConfig: {
+        provider: Providers.OPENAI,
+        model: 'gpt-4o-mini',
+        apiKey: 'test-key',
+      },
+      instructions: 'Answer plainly.',
+    },
+    hooks: registry,
+    preemption: { shouldPreempt: () => true, maxSeals: 1 },
+    returnContent: true,
+    skipCleanup: true,
+  });
+  if (!run.Graph) {
+    throw new Error('Expected graph to be initialized');
+  }
+  const model = new FakeChatModel({
+    responses: options.responses,
+  });
+  if (options.modelCallbacks != null) {
+    model.callbacks = options.modelCallbacks;
+  }
+  /**
+   * Wrapped, not bare, when the test watches model-level callbacks: with
+   * tools bound, production hands `attemptInvoke` a `RunnableBinding` (and a
+   * system runnable pipes a sequence on top), while `clientOptions.callbacks`
+   * lives on the chat model at the bottom. A bare override would let a
+   * naive `model.callbacks` property read pass the detector while missing
+   * every real tool-enabled run.
+   */
+  run.Graph.overrideModel = (
+    options.modelCallbacks != null
+      ? new RunnableBinding({ bound: model, kwargs: {}, config: {} })
+      : model
+  ) as typeof model;
+  return run;
+}
+
+class CountingChatModel extends FakeChatModel {
+  invocations = 0;
+
+  override async *_streamResponseChunks(
+    ...args: Parameters<FakeChatModel['_streamResponseChunks']>
+  ): ReturnType<FakeChatModel['_streamResponseChunks']> {
+    this.invocations += 1;
+    yield* super._streamResponseChunks(...args);
+  }
+}
+
+const aiContents = (messages: BaseMessage[]): string[] =>
+  messages
+    .filter((message) => message.getType() === 'ai')
+    .map((message) =>
+      typeof message.content === 'string'
+        ? message.content
+        : JSON.stringify(message.content)
+    );
+
+describe('cooperative seal (end-to-end via Run)', () => {
+  jest.setTimeout(15000);
+
+  it('surfaces an empty boundary as preempt_incomplete instead of a natural finish', async () => {
+    const run = await createSealRun({
+      runId: 'seal-empty-boundary',
+      hook: async () => ({}),
+      responses: [FULL_RESPONSE],
+    });
+
+    await run.processStream(
+      { messages: [new HumanMessage('hello there')] },
+      streamConfig
+    );
+
+    /**
+     * The answer really was cut short: the host asked to preempt, the seal
+     * took the budget, and the drain had nothing to resume with. A terminal
+     * consumer reading only completion events would persist a truncated
+     * answer as finished — `getHaltReason()` is the channel that prevents
+     * that (AgentSession emits `run.halted` off it).
+     */
+    expect(run.getHaltReason()).toBe('preempt_incomplete');
+    expect(run.Graph?.preemptIncomplete).toBe(true);
+    expect(run.Graph?.preemptEmptyBoundaries).toBe(1);
+
+    const contents = aiContents(run.getRunMessages() ?? []);
+    expect(contents).toHaveLength(1);
+    expect(contents[0].length).toBeGreaterThan(0);
+    expect(contents[0].length).toBeLessThan(FULL_RESPONSE.length);
+    expect(FULL_RESPONSE.startsWith(contents[0])).toBe(true);
+  });
+
+  it('forwards a halting hook\'s own stopReason to Stop hooks and getHaltReason', async () => {
+    let stopReasonSeen: string | undefined;
+    const run = await createSealRun({
+      runId: 'seal-halt-reason',
+      hook: async () => ({
+        preventContinuation: true,
+        stopReason: 'host_policy_stop',
+      }),
+      responses: [FULL_RESPONSE],
+      stopHook: async (input) => {
+        stopReasonSeen = input.stopReason;
+        return {};
+      },
+    });
+
+    await run.processStream(
+      { messages: [new HumanMessage('hello there')] },
+      streamConfig
+    );
+
+    /**
+     * The hook-supplied reason must win end to end: a persistence/audit Stop
+     * hook records the actual cause, not the generic preempt_incomplete
+     * label, and getHaltReason() reports the same string afterward. A
+     * halting boundary that injected nothing also counts as an empty
+     * boundary in the truncated-seal telemetry.
+     */
+    expect(stopReasonSeen).toBe('host_policy_stop');
+    expect(run.getHaltReason()).toBe('host_policy_stop');
+    expect(run.Graph?.preemptIncomplete).toBe(true);
+    expect(run.Graph?.preemptEmptyBoundaries).toBe(1);
+  });
+
+  it('closes model-level callbacks for the sealed run, not just config-level ones', async () => {
+    let starts = 0;
+    let ends = 0;
+    const run = await createSealRun({
+      runId: 'seal-model-callbacks',
+      hook: async () => ({
+        injectedMessages: [
+          { role: 'user' as const, content: 'Shorter.', source: 'steer' },
+        ],
+      }),
+      responses: [FULL_RESPONSE, RESUMED_RESPONSE],
+      /**
+       * A handler supplied on the MODEL (clientOptions.callbacks) gets
+       * handleChatModelStart from the real run, so the sealed turn's
+       * synthetic close must reach it too — otherwise its span for the
+       * sealed run never closes. Two runs (sealed + resumed): both must
+       * balance.
+       */
+      modelCallbacks: [
+        {
+          handleChatModelStart: (): void => {
+            starts += 1;
+          },
+          handleLLMEnd: (): void => {
+            ends += 1;
+          },
+        },
+      ],
+    });
+
+    await run.processStream(
+      { messages: [new HumanMessage('hello there')] },
+      streamConfig
+    );
+
+    expect(run.Graph?.preemptSealCount).toBe(1);
+    expect(starts).toBe(2);
+    expect(ends).toBe(2);
+  });
+
+  it('a halting boundary stops multi-agent successors, not just the sealed subgraph', async () => {
+    const registry = new HookRegistry();
+    registry.register('PreemptBoundary', {
+      hooks: [
+        async () => ({
+          preventContinuation: true,
+          stopReason: 'stop_everything',
+        }),
+      ],
+    });
+    const run = await Run.create<t.IState>({
+      runId: 'seal-halt-multiagent',
+      graphConfig: {
+        type: 'multi-agent',
+        agents: [
+          {
+            agentId: 'agent_a',
+            provider: Providers.OPENAI,
+            clientOptions: { model: 'gpt-4o-mini', apiKey: 'test-key' },
+            instructions: 'You are agent A.',
+          },
+          {
+            agentId: 'agent_b',
+            provider: Providers.OPENAI,
+            clientOptions: { model: 'gpt-4o-mini', apiKey: 'test-key' },
+            instructions: 'You are agent B.',
+          },
+        ],
+        edges: [{ from: 'agent_a', to: 'agent_b', edgeType: 'direct' }],
+      },
+      hooks: registry,
+      preemption: { shouldPreempt: () => true, maxSeals: 1 },
+      returnContent: true,
+      skipCleanup: true,
+    });
+    if (!run.Graph) {
+      throw new Error('Expected graph to be initialized');
+    }
+    const model = new CountingChatModel({
+      responses: [FULL_RESPONSE, 'agent B should never say this'],
+    });
+    run.Graph.overrideModel = model;
+
+    await run.processStream(
+      { messages: [new HumanMessage('hello there')] },
+      streamConfig
+    );
+
+    /**
+     * The registry halt is cleared to protect the sealed commit, so nothing
+     * in processStream's poll stops the outer workflow — the createCallModel
+     * entry guard is what keeps the direct-edge successor from taking a
+     * model turn after the halting boundary.
+     */
+    expect(model.invocations).toBe(1);
+    expect(run.getHaltReason()).toBe('stop_everything');
+    expect(run.Graph.preemptIncomplete).toBe(true);
+    const contents = aiContents(run.getRunMessages() ?? []);
+    expect(contents.some((c) => c.includes('agent B should never'))).toBe(
+      false
+    );
+  });
+
+  it('resumes after an injecting boundary and completes without a halt reason', async () => {
+    const run = await createSealRun({
+      runId: 'seal-inject-resume',
+      hook: async () => ({
+        injectedMessages: [
+          { role: 'user' as const, content: 'Make it shorter.', source: 'steer' },
+        ],
+      }),
+      responses: [FULL_RESPONSE, RESUMED_RESPONSE],
+    });
+
+    await run.processStream(
+      { messages: [new HumanMessage('hello there')] },
+      streamConfig
+    );
+
+    expect(run.getHaltReason()).toBeUndefined();
+    expect(run.Graph?.preemptIncomplete).toBe(false);
+    expect(run.Graph?.preemptSealCount).toBe(1);
+
+    const messages = run.getRunMessages() ?? [];
+    const steer = messages.find(
+      (message) => message.additional_kwargs.source === 'steer'
+    );
+    expect(steer).toBeDefined();
+    expect(steer?.content).toBe('Make it shorter.');
+
+    /**
+     * Two assistant turns: the sealed partial and the post-steer
+     * continuation, which must have run to completion — the seal budget was
+     * spent, so the second stream cannot seal again even though
+     * `shouldPreempt` still answers true.
+     */
+    const contents = aiContents(messages);
+    expect(contents).toHaveLength(2);
+    expect(FULL_RESPONSE.startsWith(contents[0])).toBe(true);
+    expect(contents[0].length).toBeLessThan(FULL_RESPONSE.length);
+    expect(contents[1]).toBe(RESUMED_RESPONSE);
+  });
+});

package/src/stream.dispatch.test.ts

@@ -0,0 +1,63 @@
+import type * as t from '@/types';
+import {
+  ChatModelStreamHandler,
+  dispatchesChatModelStream,
+  SDK_STREAM_DISPATCH,
+} from '@/stream';
+import { composeEventHandlers } from '@/events';
+import { GraphEvents } from '@/common';
+
+const inert: t.EventHandler = {
+  handle: (): void => {
+    /* renders nothing */
+  },
+};
+
+describe('dispatchesChatModelStream', () => {
+  it('recognizes the dispatcher itself', () => {
+    expect(dispatchesChatModelStream(new ChatModelStreamHandler())).toBe(true);
+  });
+
+  it('is false for a handler that owns no content-part dispatch', () => {
+    expect(dispatchesChatModelStream(inert)).toBe(false);
+  });
+
+  it('is false for nothing registered', () => {
+    expect(dispatchesChatModelStream(undefined)).toBe(false);
+  });
+
+  /**
+   * The reason identity is not a usable test: hosts wrap handlers, and every
+   * wrapper fails `instanceof` while still driving the same dispatch. A run
+   * that seals on that basis would be sealing against its own contract.
+   */
+  it('sees through a composed wrapper in either position', () => {
+    const first = composeEventHandlers(
+      { [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler() },
+      { [GraphEvents.CHAT_MODEL_STREAM]: inert }
+    )[GraphEvents.CHAT_MODEL_STREAM];
+    const second = composeEventHandlers(
+      { [GraphEvents.CHAT_MODEL_STREAM]: inert },
+      { [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler() }
+    )[GraphEvents.CHAT_MODEL_STREAM];
+
+    expect(first).not.toBeInstanceOf(ChatModelStreamHandler);
+    expect(second).not.toBeInstanceOf(ChatModelStreamHandler);
+    expect(dispatchesChatModelStream(first)).toBe(true);
+    expect(dispatchesChatModelStream(second)).toBe(true);
+  });
+
+  it('does not brand a composition of inert handlers', () => {
+    const composed = composeEventHandlers(
+      { [GraphEvents.CHAT_MODEL_STREAM]: inert },
+      { [GraphEvents.CHAT_MODEL_STREAM]: inert }
+    )[GraphEvents.CHAT_MODEL_STREAM];
+    expect(dispatchesChatModelStream(composed)).toBe(false);
+  });
+
+  it('exposes the brand as a cross-realm-safe registered symbol', () => {
+    expect(SDK_STREAM_DISPATCH).toBe(
+      Symbol.for('@librechat/agents:chatModelStreamDispatch')
+    );
+  });
+});

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,
           },
         },
@@ -1400,7 +1407,34 @@ function shouldSkipLateOpenRouterReasoningChunk({
   );
 }
 
+/**
+ * Brands a handler as one that dispatches content parts for the SDK — either
+ * `ChatModelStreamHandler` itself or a wrapper forwarding to one.
+ *
+ * Identity alone is not a usable contract here. Hosts compose and wrap
+ * handlers (`composeEventHandlers`, `createRunHandlers`), and every wrapper
+ * fails `instanceof` while still driving the same dispatch. A brand survives
+ * wrapping, so "does this handler own content-part dispatch" can be answered
+ * about a value the SDK did not construct.
+ */
+export const SDK_STREAM_DISPATCH = Symbol.for(
+  '@librechat/agents:chatModelStreamDispatch'
+);
+
+/** True when `handler` is, or forwards to, the SDK's stream dispatcher. */
+export function dispatchesChatModelStream(handler?: t.EventHandler): boolean {
+  if (handler == null) {
+    return false;
+  }
+  if (handler instanceof ChatModelStreamHandler) {
+    return true;
+  }
+  return Reflect.get(handler, SDK_STREAM_DISPATCH) === true;
+}
+
 export class ChatModelStreamHandler implements t.EventHandler {
+  readonly [SDK_STREAM_DISPATCH] = true;
+
   async handle(
     event: string,
     data: t.StreamEventData,
@@ -1846,13 +1880,16 @@ export function createContentAggregator(): t.ContentAggregatorResult {
     number,
     { agentId?: string; groupId?: number }
   >();
-  const getFirstContentPart = (
+  /** A delta's content may carry several parts (e.g. Google server-side tool
+   *  chunks emit multiple reasoning entries at once); every entry must reach
+   *  the step's slot, in order, or streamed text is silently lost. */
+  const getDeltaContentParts = (
     content?: t.MessageDelta['content'] | t.MessageContentComplex
-  ): t.MessageContentComplex | undefined => {
+  ): t.MessageContentComplex[] => {
     if (content == null) {
-      return undefined;
+      return [];
     }
-    return Array.isArray(content) ? content[0] : content;
+    return Array.isArray(content) ? content : [content];
   };
   const indexContentPart = (
     index: number,
@@ -2130,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,
@@ -2150,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] = {
@@ -2284,8 +2325,7 @@ export function createContentAggregator(): t.ContentAggregatorResult {
         return;
       }
 
-      const contentPart = getFirstContentPart(messageDelta.delta.content);
-      if (contentPart != null) {
+      for (const contentPart of getDeltaContentParts(messageDelta.delta.content)) {
         updateContent(runStep.index, contentPart);
       }
     } else if (
@@ -2314,8 +2354,7 @@ export function createContentAggregator(): t.ContentAggregatorResult {
         return;
       }
 
-      const contentPart = getFirstContentPart(reasoningDelta.delta.content);
-      if (contentPart != null) {
+      for (const contentPart of getDeltaContentParts(reasoningDelta.delta.content)) {
         updateContent(runStep.index, contentPart);
       }
     } else if (event === GraphEvents.ON_RUN_STEP_DELTA) {

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,