@librechat/agents 3.3.3 → 3.3.5

package/src/llm/preempt.test.ts

@@ -0,0 +1,323 @@
+import { AIMessageChunk } from '@langchain/core/messages';
+import { canSealPreempt, resolveMaxSeals } from './preempt';
+
+/**
+ * The budget is read by two consumers that interpret it differently — a
+ * numeric comparison in the seal gate, and an addition into the graph's
+ * recursion limit. Normalizing once keeps them in agreement.
+ */
+describe('resolveMaxSeals', () => {
+  it('defaults when unset', () => {
+    expect(resolveMaxSeals(undefined)).toBe(8);
+  });
+
+  it('passes a sane whole number through', () => {
+    expect(resolveMaxSeals(3)).toBe(3);
+  });
+
+  it('floors a fractional budget so both readers agree', () => {
+    expect(resolveMaxSeals(1.5)).toBe(1);
+  });
+
+  it('honors zero as a deliberate never-seal', () => {
+    expect(resolveMaxSeals(0)).toBe(0);
+  });
+
+  it('clamps a negative budget to never-seal', () => {
+    expect(resolveMaxSeals(-4)).toBe(0);
+  });
+
+  it('falls back rather than poisoning the recursion limit', () => {
+    expect(resolveMaxSeals(NaN)).toBe(8);
+    expect(resolveMaxSeals(Infinity)).toBe(8);
+    expect(resolveMaxSeals(-Infinity)).toBe(8);
+  });
+});
+
+function chunk(fields: Partial<AIMessageChunk>): AIMessageChunk {
+  return new AIMessageChunk({
+    content: '',
+    ...fields,
+  } as ConstructorParameters<typeof AIMessageChunk>[0]);
+}
+
+describe('canSealPreempt', () => {
+  describe('refuses to seal', () => {
+    it('on a missing chunk', () => {
+      expect(canSealPreempt(undefined)).toBe(false);
+    });
+
+    it('on empty string content', () => {
+      expect(canSealPreempt(chunk({ content: '' }))).toBe(false);
+    });
+
+    it('on whitespace-only string content', () => {
+      expect(canSealPreempt(chunk({ content: '  \n\t ' }))).toBe(false);
+    });
+
+    it('on an empty content array', () => {
+      expect(canSealPreempt(chunk({ content: [] }))).toBe(false);
+    });
+
+    it('on whitespace-only text blocks', () => {
+      expect(
+        canSealPreempt(chunk({ content: [{ type: 'text', text: '   ' }] }))
+      ).toBe(false);
+    });
+
+    it('when the only content is thinking', () => {
+      expect(
+        canSealPreempt(
+          chunk({
+            content: [
+              { type: 'thinking', thinking: 'Let me work through this.' },
+            ],
+          })
+        )
+      ).toBe(false);
+    });
+
+    it('when the only content is reasoning', () => {
+      expect(
+        canSealPreempt(
+          chunk({
+            content: [{ type: 'reasoning', reasoning: 'Considering.' }],
+          })
+        )
+      ).toBe(false);
+    });
+
+    it('when the only content is redacted_thinking', () => {
+      expect(
+        canSealPreempt(
+          chunk({ content: [{ type: 'redacted_thinking', data: 'xxx' }] })
+        )
+      ).toBe(false);
+    });
+
+    it('with a resolved tool call present', () => {
+      expect(
+        canSealPreempt(
+          chunk({
+            content: 'Looking that up.',
+            tool_calls: [{ id: 'c1', name: 'search', args: {} }],
+          })
+        )
+      ).toBe(false);
+    });
+
+    it('with a partial tool call still streaming', () => {
+      expect(
+        canSealPreempt(
+          chunk({
+            content: 'Looking that up.',
+            tool_call_chunks: [
+              { id: 'c1', name: 'search', args: '{"q"', index: 0 },
+            ],
+          })
+        )
+      ).toBe(false);
+    });
+
+    /**
+     * Assigned after construction on purpose: `AIMessageChunk` derives
+     * `invalid_tool_calls` from `tool_call_chunks` and drops a directly
+     * supplied array, so this is the only way to exercise the guard on its
+     * own rather than through the `tool_call_chunks` check above it.
+     */
+    it('with an invalid tool call present', () => {
+      const c = chunk({ content: 'Looking that up.' });
+      c.invalid_tool_calls = [
+        { id: 'c1', name: 'search', args: '{oops', error: 'bad json' },
+      ];
+      expect(canSealPreempt(c)).toBe(false);
+    });
+
+    /**
+     * Anthropic emits a `tool_call_chunk` alongside every `server_tool_use`
+     * content block, and `concat` keeps it on the accumulated message for the
+     * rest of the turn. So a web-search turn is refused by the tool-call gate,
+     * both while the search is in flight and after its result has landed —
+     * this pins that invariant rather than a content-block check.
+     */
+    it('while an Anthropic server tool is in flight', () => {
+      expect(
+        canSealPreempt(
+          chunk({
+            content: [
+              { type: 'text', text: 'Searching the web for that.' },
+              {
+                type: 'server_tool_use',
+                id: 'srvtoolu_1',
+                name: 'web_search',
+                input: { query: 'x' },
+              },
+            ],
+            tool_call_chunks: [
+              { id: 'srvtoolu_1', name: 'web_search', args: '', index: 0 },
+            ],
+          })
+        )
+      ).toBe(false);
+    });
+
+    /**
+     * Gemini server-side tools land as `toolCall` / `toolResponse` content
+     * blocks and never populate `tool_calls` or `tool_call_chunks`, so the
+     * tool-call gates above cannot see them.
+     */
+    it('while a Google server tool call is unanswered', () => {
+      expect(
+        canSealPreempt(
+          chunk({
+            content: [
+              { type: 'text', text: 'Let me look that up.' },
+              { type: 'toolCall', id: 'gcall_1', name: 'google_search' },
+            ],
+          })
+        )
+      ).toBe(false);
+    });
+
+    it('with more Google server tool calls than responses', () => {
+      expect(
+        canSealPreempt(
+          chunk({
+            content: [
+              { type: 'text', text: 'Checking two things.' },
+              { type: 'toolCall', id: 'gcall_1', name: 'google_search' },
+              { type: 'toolResponse', id: 'gcall_1', response: {} },
+              { type: 'toolCall', id: 'gcall_2', name: 'google_search' },
+            ],
+          })
+        )
+      ).toBe(false);
+    });
+
+    it('while one of several server tool calls is still unanswered', () => {
+      expect(
+        canSealPreempt(
+          chunk({
+            content: [
+              { type: 'text', text: 'Checking two sources.' },
+              {
+                type: 'web_search_tool_result',
+                tool_use_id: 'srvtoolu_1',
+                content: [],
+              },
+            ],
+            tool_call_chunks: [
+              { id: 'srvtoolu_1', name: 'web_search', args: '', index: 0 },
+              { id: 'srvtoolu_2', name: 'web_search', args: '', index: 1 },
+            ],
+          })
+        )
+      ).toBe(false);
+    });
+  });
+
+  describe('seals', () => {
+    it('on non-empty string content', () => {
+      expect(canSealPreempt(chunk({ content: 'The migration has' }))).toBe(
+        true
+      );
+    });
+
+    it('on a non-empty text block', () => {
+      expect(
+        canSealPreempt(
+          chunk({ content: [{ type: 'text', text: 'The migration has' }] })
+        )
+      ).toBe(true);
+    });
+
+    it('on text that follows signed thinking', () => {
+      expect(
+        canSealPreempt(
+          chunk({
+            content: [
+              {
+                type: 'thinking',
+                thinking: 'Working it out.',
+                signature: 'sig',
+              },
+              { type: 'text', text: 'The migration has' },
+            ],
+          })
+        )
+      ).toBe(true);
+    });
+
+    it('with empty tool-call arrays present', () => {
+      expect(
+        canSealPreempt(
+          chunk({
+            content: 'The migration has',
+            tool_calls: [],
+            tool_call_chunks: [],
+            invalid_tool_calls: [],
+          })
+        )
+      ).toBe(true);
+    });
+
+    it('once every Google server tool call has been answered', () => {
+      expect(
+        canSealPreempt(
+          chunk({
+            content: [
+              { type: 'text', text: 'Here is what I found.' },
+              { type: 'toolCall', id: 'gcall_1', name: 'google_search' },
+              { type: 'toolResponse', id: 'gcall_1', response: {} },
+            ],
+          })
+        )
+      ).toBe(true);
+    });
+
+    /**
+     * Provider-side tools never reach `ToolNode`, so no `PostToolBatch`
+     * boundary exists to drain into. Refusing forever after a search would
+     * defer a queued message to the end of the turn rather than to the next
+     * tool step, so a call whose result has landed counts as settled.
+     */
+    it('once an Anthropic server tool result has landed', () => {
+      expect(
+        canSealPreempt(
+          chunk({
+            content: [
+              { type: 'text', text: 'Here is what I found.' },
+              {
+                type: 'server_tool_use',
+                id: 'srvtoolu_1',
+                name: 'web_search',
+                input: { query: 'x' },
+              },
+              {
+                type: 'web_search_tool_result',
+                tool_use_id: 'srvtoolu_1',
+                content: [],
+              },
+            ],
+            tool_call_chunks: [
+              { id: 'srvtoolu_1', name: 'web_search', args: '', index: 0 },
+            ],
+          })
+        )
+      ).toBe(true);
+    });
+
+    it('on a non-text block that carries no tool call', () => {
+      expect(
+        canSealPreempt(
+          chunk({
+            content: [
+              { type: 'text', text: 'Here is the diagram.' },
+              { type: 'image_url', image_url: { url: 'https://x/y.png' } },
+            ],
+          })
+        )
+      ).toBe(true);
+    });
+  });
+});

package/src/llm/preempt.ts

@@ -0,0 +1,178 @@
+// src/llm/preempt.ts
+import type { AIMessageChunk } from '@langchain/core/messages';
+import { ContentTypes, DEFAULT_MAX_SEALS } from '@/common';
+
+/**
+ * Normalizes a host-supplied seal budget.
+ *
+ * Read in two places that interpret it differently — a numeric comparison in
+ * the seal gate and an addition into the recursion limit — so a value like
+ * `1.5` would permit two seals while reserving fractional headroom, `NaN`
+ * would poison the recursion limit outright, and `Infinity` would remove both
+ * bounds at once. Normalizing once keeps the two readings in agreement.
+ *
+ * `0` is honored as a deliberate "never seal"; anything not finite falls back
+ * to the default rather than silently disabling the feature.
+ */
+export function resolveMaxSeals(maxSeals: number | undefined): number {
+  if (maxSeals == null || !Number.isFinite(maxSeals)) {
+    return DEFAULT_MAX_SEALS;
+  }
+  const whole = Math.floor(maxSeals);
+  return whole > 0 ? whole : 0;
+}
+
+/**
+ * True when the accumulated content carries at least one non-whitespace text
+ * block. `thinking` / `reasoning` blocks deliberately do not count: they are
+ * stripped or signed on several providers and cannot stand in for the visible
+ * assistant turn a sealed sequence needs.
+ */
+function hasNonEmptyTextContent(content: AIMessageChunk['content']): boolean {
+  if (typeof content === 'string') {
+    return content.trim() !== '';
+  }
+  for (const block of content) {
+    if (block.type !== ContentTypes.TEXT) {
+      continue;
+    }
+    const text = block[ContentTypes.TEXT];
+    if (typeof text === 'string' && text.trim() !== '') {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * True while a Gemini server-side tool call is still awaiting its response.
+ *
+ * Google's server-side tools (Search, URL context) never populate
+ * `tool_calls` or `tool_call_chunks` — those are derived from `functionCall`
+ * parts only, while a server-side invocation arrives as a `toolCall` CONTENT
+ * block and its result as a later `toolResponse` block. The tool-call gates
+ * cannot see it, so sealing between the two would replay a model turn holding
+ * an unanswered server-side call.
+ *
+ * Counted rather than id-matched: Google answers calls in order, and counting
+ * stays correct when a part omits its id.
+ */
+function hasOpenGoogleServerToolCall(
+  content: AIMessageChunk['content']
+): boolean {
+  if (typeof content === 'string') {
+    return false;
+  }
+  let calls = 0;
+  let responses = 0;
+  for (const block of content) {
+    if (block.type === 'toolCall') {
+      calls += 1;
+    } else if (block.type === 'toolResponse') {
+      responses += 1;
+    }
+  }
+  return calls > responses;
+}
+
+/**
+ * Ids of Anthropic server-side tool calls whose paired result block is already
+ * on the accumulated content. Those calls are answered and cannot be orphaned
+ * by a seal.
+ */
+function settledServerToolCallIds(
+  content: AIMessageChunk['content']
+): Set<string> {
+  const settled = new Set<string>();
+  if (typeof content === 'string') {
+    return settled;
+  }
+  for (const block of content) {
+    if (block.type !== 'web_search_tool_result') {
+      continue;
+    }
+    const id = block.tool_use_id;
+    if (typeof id === 'string') {
+      settled.add(id);
+    }
+  }
+  return settled;
+}
+
+/** Tool calls still awaiting an answer, ignoring ones already settled. */
+function countOpenToolCalls(
+  calls: ReadonlyArray<{ id?: string }> | undefined,
+  settled: Set<string>
+): number {
+  if (calls == null || calls.length === 0) {
+    return 0;
+  }
+  if (settled.size === 0) {
+    return calls.length;
+  }
+  let open = 0;
+  for (const call of calls) {
+    if (call.id == null || !settled.has(call.id)) {
+      open += 1;
+    }
+  }
+  return open;
+}
+
+/**
+ * Cooperative mid-generation seal gate. Returns true ONLY when sealing here
+ * yields a message sequence valid on EVERY supported provider:
+ *  - non-whitespace TEXT content, so the FIRST injected user turn is preceded
+ *    by a non-empty assistant turn — no empty-content 400s. Note this says
+ *    nothing about adjacency AMONG several injected turns: a boundary that
+ *    drains two steers emits two consecutive user messages, which strict
+ *    providers reject. That is normalized at the provider-facing hop by
+ *    `coalesceAdjacentUserTurns`, not here;
+ *  - no tool call in flight, so no `tool_use` can be orphaned AND no eagerly
+ *    prestarted execution can be stripped out from under the model.
+ *
+ * Anthropic's server-side tools need no check of their own. Every
+ * `server_tool_use` content block also emits a `tool_call_chunk`
+ * (`_makeMessageChunkFromAnthropicEvent`), and `concat` keeps that chunk on
+ * the accumulated message for the remainder of the turn, so the tool-call
+ * gates below already cover it. The practical consequence is worth stating
+ * plainly: once a turn starts a web search it is no longer preemptible, and
+ * a queued message waits for the ordinary tool boundary instead.
+ *
+ * Nothing is stripped and nothing is repaired: when the accumulated shape is
+ * not already safe the stream simply runs on, and whatever the host queued
+ * lands at the next tool boundary instead. Chunks accumulate monotonically
+ * through `concat`, so an unsafe shape can never be observed at a seal point.
+ */
+export function canSealPreempt(chunk: AIMessageChunk | undefined): boolean {
+  if (chunk == null) {
+    return false;
+  }
+  /**
+   * Anthropic's server-side tools run inside the provider, so unlike a client
+   * tool they never reach `ToolNode` and never produce a `PostToolBatch`
+   * boundary. `concat` also keeps their `server_tool_use` chunk on the
+   * accumulated message for the rest of the turn. Together that means a naive
+   * tool-call gate makes a turn permanently unsealable the moment a web
+   * search starts, with no later boundary to drain into — the queued message
+   * waits for the whole turn to finish rather than for the next tool step.
+   *
+   * So calls whose paired result block has already landed are treated as
+   * settled: they cannot be orphaned, because the provider has already
+   * answered them.
+   */
+  const settled = settledServerToolCallIds(chunk.content);
+  if (countOpenToolCalls(chunk.tool_calls, settled) > 0) {
+    return false;
+  }
+  if (countOpenToolCalls(chunk.tool_call_chunks, settled) > 0) {
+    return false;
+  }
+  if ((chunk.invalid_tool_calls?.length ?? 0) > 0) {
+    return false;
+  }
+  if (hasOpenGoogleServerToolCall(chunk.content)) {
+    return false;
+  }
+  return hasNonEmptyTextContent(chunk.content);
+}

package/src/messages/__tests__/observationMasking.test.ts

@@ -1,12 +1,15 @@
 import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { TokenCounter } from '@/types/run';
-import { maskConsumedToolResults } from '@/messages/prune';
+import {
+  maskConsumedToolResults,
+  ORIGINAL_CONTENT_MAX_CHARS,
+} from '@/messages/prune';
 
 const charCounter: TokenCounter = (msg) => {
   const raw = msg.content;
   if (typeof raw === 'string') return raw.length;
-  return 0;
+  return JSON.stringify(raw).length;
 };
 
 function toolMsg(
@@ -209,6 +212,94 @@ describe('maskConsumedToolResults', () => {
     expect(map[2]).toBe((messages[2].content as string).length);
   });
 
+  it('masks consumed structured tool results with a bounded text preview', () => {
+    const tcId = 'tc-structured';
+    const toolMessage = new ToolMessage({
+      content: [
+        {
+          type: 'json',
+          rows: Array.from({ length: 20 }, (_, index) => ({
+            id: index,
+            value: `${'x'.repeat(100)}-${index}`,
+          })),
+        },
+      ],
+      tool_call_id: tcId,
+      name: 'run_select_query',
+      status: 'success',
+      artifact: { source: 'clickhouse' },
+    });
+    const messages: BaseMessage[] = [
+      new HumanMessage('query the table'),
+      aiToolCall(tcId, 'run_select_query'),
+      toolMessage,
+      aiWithText('The query returned 20 rows.'),
+    ];
+    const map: Record<string, number | undefined> = {
+      0: 5,
+      1: 20,
+      2: 0,
+      3: 30,
+    };
+    const originalContentStore = new Map<number, string>();
+    const originalContent = JSON.stringify(toolMessage.content);
+
+    const count = maskConsumedToolResults({
+      messages,
+      indexTokenCountMap: map,
+      tokenCounter: charCounter,
+      originalContentStore,
+    });
+
+    expect(count).toBe(1);
+    expect(typeof messages[2].content).toBe('string');
+    expect(messages[2].content).toContain('truncated');
+    expect((messages[2].content as string).length).toBeLessThanOrEqual(300);
+    const masked = messages[2] as ToolMessage;
+    expect(masked.tool_call_id).toBe(tcId);
+    expect(masked.name).toBe('run_select_query');
+    expect(masked.status).toBe('success');
+    expect(masked.artifact).toEqual({ source: 'clickhouse' });
+    expect(map[2]).toBe(charCounter(masked));
+    expect(originalContentStore.get(2)).toBe(originalContent);
+  });
+
+  it('bounds stored structured originals without invoking custom toJSON', () => {
+    const tcId = 'tc-large-structured';
+    const toJSON = jest.fn(() => ({ expanded: 'should not run' }));
+    const messages: BaseMessage[] = [
+      new HumanMessage('query the table'),
+      aiToolCall(tcId, 'run_select_query'),
+      new ToolMessage({
+        content: [
+          {
+            type: 'json',
+            payload: 'x'.repeat(ORIGINAL_CONTENT_MAX_CHARS + 1_000),
+            toJSON,
+          },
+        ],
+        tool_call_id: tcId,
+        name: 'run_select_query',
+      }),
+      aiWithText('The query completed.'),
+    ];
+    const originalContentStore = new Map<number, string>();
+
+    const count = maskConsumedToolResults({
+      messages,
+      indexTokenCountMap: { 0: 1, 1: 1, 2: 1, 3: 1 },
+      tokenCounter: () => 1,
+      originalContentStore,
+    });
+
+    expect(count).toBe(1);
+    expect(toJSON).not.toHaveBeenCalled();
+    expect(originalContentStore.get(2)?.length).toBeLessThanOrEqual(
+      ORIGINAL_CONTENT_MAX_CHARS
+    );
+    expect(originalContentStore.get(2)).toContain('truncated');
+  });
+
   it('handles empty messages array', () => {
     const map: Record<string, number | undefined> = {};
     const count = maskConsumedToolResults({