@librechat/agents 3.3.4 → 3.3.5

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

@@ -1400,7 +1400,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 +1873,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,
@@ -2284,8 +2314,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 +2343,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/ToolNode.ts

@@ -70,7 +70,7 @@ import {
 } from '@/tools/local';
 import { stripCodeSessionFileSummary } from '@/tools/CodeSessionFileSummary';
 import { Constants, GraphEvents, CODE_EXECUTION_TOOLS } from '@/common';
-import { toLangChainContent } from '@/messages/langchain';
+import { convertInjectedMessages } from '@/messages/injected';
 import { safeDispatchCustomEvent } from '@/utils/events';
 import { RunnableCallable } from '@/utils';
 import { executeHooks } from '@/hooks';
@@ -2934,7 +2934,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         if (result.injectedMessages && result.injectedMessages.length > 0) {
           try {
             injected.push(
-              ...this.convertInjectedMessages(result.injectedMessages)
+              ...convertInjectedMessages(result.injectedMessages)
             );
           } catch (e) {
             // eslint-disable-next-line no-console
@@ -3344,7 +3344,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
      */
     if (hookInjectedMessages.length > 0) {
       try {
-        injected.push(...this.convertInjectedMessages(hookInjectedMessages));
+        injected.push(...convertInjectedMessages(hookInjectedMessages));
       } catch (e) {
         // eslint-disable-next-line no-console
         console.warn(
@@ -3426,34 +3426,6 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     );
   }
 
-  /**
-   * Converts InjectedMessage instances to LangChain HumanMessage objects.
-   * Both 'user' and 'system' roles become HumanMessage to avoid provider
-   * rejections (Anthropic/Google reject non-leading SystemMessages).
-   * The original role is preserved in additional_kwargs for downstream consumers.
-   */
-  private convertInjectedMessages(
-    messages: t.InjectedMessage[]
-  ): BaseMessage[] {
-    const converted: BaseMessage[] = [];
-    for (const msg of messages) {
-      const additional_kwargs: Record<string, unknown> = {
-        role: msg.role,
-      };
-      if (msg.isMeta != null) additional_kwargs.isMeta = msg.isMeta;
-      if (msg.source != null) additional_kwargs.source = msg.source;
-      if (msg.skillName != null) additional_kwargs.skillName = msg.skillName;
-
-      converted.push(
-        new HumanMessage({
-          content: toLangChainContent(msg.content),
-          additional_kwargs,
-        })
-      );
-    }
-    return converted;
-  }
-
   /**
    * Execute a group of direct (in-process) tool calls with interrupt-safe
    * ordering, returning outputs aligned 1:1 with `directCalls`.

package/src/tools/search/keenable-scraper.test.ts

@@ -0,0 +1,153 @@
+import axios from 'axios';
+import { createKeenableScraper } from './keenable-scraper';
+
+jest.mock('axios');
+const mockedAxios = axios as jest.Mocked<typeof axios>;
+
+const sampleResponse = {
+  data: {
+    url: 'https://example.com/',
+    title: 'Example Domain',
+    content:
+      '# Example Domain\n\nThis domain is for use in documentation examples.',
+    description: 'An example page.',
+  },
+};
+
+describe('Keenable scraper', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    delete process.env.KEENABLE_API_KEY;
+    delete process.env.KEENABLE_FETCH_URL;
+  });
+
+  it('returns an error for empty URLs without calling the API', async () => {
+    const scraper = createKeenableScraper();
+    const [url, response] = await scraper.scrapeUrl('   ');
+
+    expect(url).toBe('   ');
+    expect(response.success).toBe(false);
+    expect(mockedAxios.get).not.toHaveBeenCalled();
+  });
+
+  it('hits the public endpoint and omits the API key header when keyless', async () => {
+    mockedAxios.get.mockResolvedValueOnce(sampleResponse);
+
+    const scraper = createKeenableScraper();
+    const [, response] = await scraper.scrapeUrl('https://example.com');
+
+    expect(mockedAxios.get).toHaveBeenCalledWith(
+      'https://api.keenable.ai/v1/fetch/public',
+      expect.objectContaining({
+        params: { url: 'https://example.com' },
+        headers: expect.objectContaining({ 'X-Keenable-Title': 'LibreChat' }),
+      })
+    );
+    const headers = mockedAxios.get.mock.calls[0][1]?.headers as Record<
+      string,
+      string
+    >;
+    expect(headers['X-API-Key']).toBeUndefined();
+    expect(response.success).toBe(true);
+    expect(response.data?.content).toContain('# Example Domain');
+  });
+
+  it('hits the keyed endpoint and sends the API key header when a key is set', async () => {
+    mockedAxios.get.mockResolvedValueOnce(sampleResponse);
+
+    const scraper = createKeenableScraper({ apiKey: 'secret-key' });
+    await scraper.scrapeUrl('https://example.com');
+
+    expect(mockedAxios.get).toHaveBeenCalledWith(
+      'https://api.keenable.ai/v1/fetch',
+      expect.objectContaining({
+        headers: expect.objectContaining({ 'X-API-Key': 'secret-key' }),
+      })
+    );
+  });
+
+  it('honors a custom attribution title and fetch URL override', async () => {
+    mockedAxios.get.mockResolvedValueOnce(sampleResponse);
+
+    const scraper = createKeenableScraper({
+      apiUrl: 'https://keenable.internal/v1/fetch/public',
+      attributionTitle: 'MyApp',
+    });
+    await scraper.scrapeUrl('https://example.com');
+
+    expect(mockedAxios.get).toHaveBeenCalledWith(
+      'https://keenable.internal/v1/fetch/public',
+      expect.objectContaining({
+        headers: expect.objectContaining({ 'X-Keenable-Title': 'MyApp' }),
+      })
+    );
+  });
+
+  it('reports failure when the API returns no content', async () => {
+    mockedAxios.get.mockResolvedValueOnce({
+      data: { url: 'https://x.test', content: '' },
+    });
+
+    const scraper = createKeenableScraper();
+    const [, response] = await scraper.scrapeUrl('https://x.test');
+
+    expect(response.success).toBe(false);
+    expect(response.error).toMatch(/no content/i);
+  });
+
+  it('reports failure with a message when the request throws', async () => {
+    mockedAxios.get.mockRejectedValueOnce(new Error('network down'));
+
+    const scraper = createKeenableScraper();
+    const [, response] = await scraper.scrapeUrl('https://x.test');
+
+    expect(response.success).toBe(false);
+    expect(response.error).toContain('network down');
+  });
+
+  it('scrapes multiple URLs concurrently', async () => {
+    mockedAxios.get
+      .mockResolvedValueOnce({ data: { content: 'a', url: 'https://a.test' } })
+      .mockResolvedValueOnce({ data: { content: 'b', url: 'https://b.test' } });
+
+    const scraper = createKeenableScraper();
+    const results = await scraper.scrapeUrls([
+      'https://a.test',
+      'https://b.test',
+    ]);
+
+    expect(results).toHaveLength(2);
+    expect(results[0][1].data?.content).toBe('a');
+    expect(results[1][1].data?.content).toBe('b');
+  });
+
+  it('extractContent returns the markdown with no structured references', () => {
+    const scraper = createKeenableScraper();
+    const [content, references] = scraper.extractContent({
+      success: true,
+      data: { content: '# Title\n\nBody' },
+    });
+
+    expect(content).toBe('# Title\n\nBody');
+    expect(references).toBeUndefined();
+  });
+
+  it('extractMetadata surfaces title, description and url', () => {
+    const scraper = createKeenableScraper();
+    const metadata = scraper.extractMetadata({
+      success: true,
+      data: {
+        content: 'x',
+        title: 'Example Domain',
+        description: 'An example page.',
+        url: 'https://example.com/',
+      },
+    });
+
+    expect(metadata).toEqual({
+      title: 'Example Domain',
+      description: 'An example page.',
+      url: 'https://example.com/',
+    });
+  });
+});