@librechat/agents 3.3.0 → 3.3.2

package/src/tools/__tests__/CodeApiAuthHeaders.test.ts

@@ -145,6 +145,38 @@ describe('CodeAPI auth header injection', () => {
     );
   });
 
+  it('maps dynamic auth-header failures to the safe authorization error', async () => {
+    const authHeaders = jest.fn(async () => {
+      throw new Error(
+        'credential helper failed for secret codeapi-signing-key in namespace internal-auth'
+      );
+    });
+    const tool = createProgrammaticToolCallingTool({ authHeaders });
+
+    const error = await tool
+      .invoke(
+        { code: 'print("hello")' },
+        {
+          toolCall: {
+            name: 'programmatic_code_execution',
+            args: {},
+            toolMap: toolMap(),
+            toolDefs,
+          },
+        }
+      )
+      .catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toContain(
+      'Code execution is not authorized. Verify access before trying again.'
+    );
+    expect((error as Error).message).not.toContain('Please retry');
+    expect((error as Error).message).not.toContain('codeapi-signing-key');
+    expect((error as Error).message).not.toContain('internal-auth');
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
   it('forwards Authorization for direct code execution', async () => {
     fetchMock.mockResolvedValueOnce(
       jsonResponse({ session_id: 'session_123', stdout: '1\n' })
@@ -202,12 +234,274 @@ describe('CodeAPI auth header injection', () => {
     ).not.toHaveProperty('authHeaders');
   });
 
-  it('includes the CodeAPI endpoint and response body on direct execution failures', async () => {
+  it('redacts the CodeAPI endpoint and response body on direct execution failures', async () => {
     fetchMock.mockResolvedValueOnce(errorResponse(404, 'Cannot POST /exec'));
     const tool = createBashExecutionTool();
 
-    await expect(tool.invoke({ command: 'echo 1' })).rejects.toThrow(
-      /CodeAPI request failed: POST .*\/exec returned 404, body: Cannot POST \/exec/
+    const error = await tool
+      .invoke({ command: 'echo 1' })
+      .catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toContain(
+      'Code execution is temporarily unavailable. Please retry.'
+    );
+    expect((error as Error).message).not.toContain('/exec');
+    expect((error as Error).message).not.toContain('Cannot POST');
+  });
+
+  it.each([401, 403])(
+    'reports CodeAPI HTTP %s authorization failures as non-retryable',
+    async (status) => {
+      fetchMock.mockResolvedValueOnce(
+        errorResponse(
+          status,
+          'Invalid bearer token for codeapi.internal.svc.cluster.local'
+        )
+      );
+      const tool = createBashExecutionTool();
+
+      const error = await tool
+        .invoke({ command: 'echo 1' })
+        .catch((caught: unknown) => caught);
+
+      expect(error).toBeInstanceOf(Error);
+      expect((error as Error).message).toContain(
+        'Code execution is not authorized. Verify access before trying again.'
+      );
+      expect((error as Error).message).not.toContain('Please retry');
+      expect((error as Error).message).not.toContain('svc.cluster.local');
+      expect((error as Error).message).not.toContain('Invalid bearer token');
+    }
+  );
+
+  it('preserves only a bounded retry delay from CodeAPI rate-limit failures', async () => {
+    fetchMock.mockResolvedValueOnce(
+      errorResponse(
+        429,
+        JSON.stringify({
+          error: 'rate_limited',
+          message:
+            'Too many CodeAPI execution requests from internal deployment details.',
+          retry_after_seconds: 8.2,
+        })
+      )
+    );
+    const tool = createBashExecutionTool();
+
+    const error = await tool
+      .invoke({ command: 'echo 1' })
+      .catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toContain(
+      'Code execution is temporarily rate-limited. Retry after 9 seconds.'
+    );
+    expect((error as Error).message).not.toContain('CodeAPI');
+    expect((error as Error).message).not.toContain('internal deployment');
+  });
+
+  it('redacts network details from direct execution failures', async () => {
+    fetchMock.mockRejectedValueOnce(
+      new Error(
+        'request to http://codeapi.internal.svc.cluster.local/exec failed: getaddrinfo ENOTFOUND'
+      )
+    );
+    const tool = createBashExecutionTool();
+
+    const error = await tool
+      .invoke({ command: 'echo 1' })
+      .catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toContain(
+      'Code execution is temporarily unavailable. Please retry.'
+    );
+    expect((error as Error).message).not.toContain('svc.cluster.local');
+    expect((error as Error).message).not.toContain('ENOTFOUND');
+  });
+
+  it('redacts network details from programmatic execution failures', async () => {
+    fetchMock.mockRejectedValueOnce(
+      new Error(
+        'request to http://codeapi.internal.svc.cluster.local/exec/programmatic failed'
+      )
+    );
+    const tool = createProgrammaticToolCallingTool();
+
+    const error = await tool
+      .invoke(
+        { code: 'print("hello")' },
+        {
+          toolCall: {
+            name: 'programmatic_code_execution',
+            args: {},
+            toolMap: toolMap(),
+            toolDefs,
+          },
+        }
+      )
+      .catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toContain(
+      'Code execution is temporarily unavailable. Please retry.'
+    );
+    expect((error as Error).message).not.toContain('svc.cluster.local');
+  });
+
+  it('redacts CodeAPI programmatic errors while preserving execution stderr', async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        status: 'error',
+        error:
+          'sandbox worker codeapi-runtime-7f9d failed in internal namespace',
+        stderr: 'NameError: tenant_variable is not defined',
+      })
+    );
+    const tool = createProgrammaticToolCallingTool();
+
+    const error = await tool
+      .invoke(
+        { code: 'print(tenant_variable)' },
+        {
+          toolCall: {
+            name: 'programmatic_code_execution',
+            args: {},
+            toolMap: toolMap(),
+            toolDefs,
+          },
+        }
+      )
+      .catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toContain('Code execution failed.');
+    expect((error as Error).message).toContain(
+      'NameError: tenant_variable is not defined'
+    );
+    expect((error as Error).message).not.toContain('codeapi-runtime');
+    expect((error as Error).message).not.toContain('internal namespace');
+  });
+
+  it('preserves an allowlisted programmatic execution error when stderr is absent', async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        status: 'error',
+        error: 'Time limit exceeded',
+      })
+    );
+    const tool = createProgrammaticToolCallingTool();
+
+    const error = await tool
+      .invoke(
+        { code: 'while True: pass' },
+        {
+          toolCall: {
+            name: 'programmatic_code_execution',
+            args: {},
+            toolMap: toolMap(),
+            toolDefs,
+          },
+        }
+      )
+      .catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toContain(
+      'Code execution failed. Execution exceeded the time limit.'
+    );
+  });
+
+  it('preserves an allowlisted execution error alongside stderr', async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        status: 'error',
+        error: 'Time limit exceeded',
+        stderr: 'processed 42 records before termination',
+      })
+    );
+    const tool = createProgrammaticToolCallingTool();
+
+    const error = await tool
+      .invoke(
+        { code: 'while True: process_next_record()' },
+        {
+          toolCall: {
+            name: 'programmatic_code_execution',
+            args: {},
+            toolMap: toolMap(),
+            toolDefs,
+          },
+        }
+      )
+      .catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toContain(
+      'Code execution failed. Execution exceeded the time limit.'
+    );
+    expect((error as Error).message).toContain(
+      'Stderr:\nprocessed 42 records before termination'
+    );
+  });
+
+  it('keeps arbitrary programmatic execution errors redacted when stderr is absent', async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        status: 'error',
+        error:
+          'sandbox worker codeapi-runtime-7f9d failed in internal namespace',
+      })
+    );
+    const tool = createProgrammaticToolCallingTool();
+
+    const error = await tool
+      .invoke(
+        { code: 'print("hello")' },
+        {
+          toolCall: {
+            name: 'programmatic_code_execution',
+            args: {},
+            toolMap: toolMap(),
+            toolDefs,
+          },
+        }
+      )
+      .catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toContain('Code execution failed.');
+    expect((error as Error).message).not.toContain('codeapi-runtime');
+    expect((error as Error).message).not.toContain('internal namespace');
+  });
+
+  it('preserves an allowlisted bash execution error when stderr is absent', async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        status: 'error',
+        error: 'Out of memory',
+      })
+    );
+    const tool = createBashProgrammaticToolCallingTool();
+
+    const error = await tool
+      .invoke(
+        { code: 'lookup_user "{}"' },
+        {
+          toolCall: {
+            name: 'bash_programmatic_code_execution',
+            args: {},
+            toolMap: toolMap(),
+            toolDefs,
+          },
+        }
+      )
+      .catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toContain(
+      'Code execution failed. Execution exceeded the memory limit.'
     );
   });
 

package/src/types/llm.ts

@@ -137,10 +137,17 @@ export type SharedLLMConfig = {
   _lc_stream_delay?: number;
 };
 
+export interface FallbackConfig {
+  provider: Providers;
+  clientOptions?: ClientOptions;
+  /** Context window used to corroborate ambiguous fallback overflow errors. */
+  maxContextTokens?: number;
+}
+
 export type LLMConfig = SharedLLMConfig &
   ClientOptions & {
     /** Optional provider fallbacks in order of attempt */
-    fallbacks?: Array<{ provider: Providers; clientOptions?: ClientOptions }>;
+    fallbacks?: FallbackConfig[];
   };
 
 export type ProviderOptionsMap = {

package/src/types/stream.ts

@@ -68,13 +68,14 @@ export type RunStep = {
   runId?: string; // #new
   agentId?: string; // #new - tracks which agent this step belongs to
   /**
-   * Group ID - incrementing number (1, 2, 3...) reflecting execution order.
-   * Agents with the same groupId run in parallel and should be rendered together.
-   * undefined means the agent runs sequentially (not part of any parallel group).
+   * Opaque positive safe-integer identifier for parallel execution.
+   * Agents with the same groupId should be rendered together.
+   * Consumers must use content indexes, not groupId ordering, for execution order.
+   * undefined means the agent runs sequentially (not part of a parallel group).
    *
    * Example for: researcher -> [analyst1, analyst2, analyst3] -> summarizer
    * - researcher: undefined (sequential)
-   * - analyst1, analyst2, analyst3: 1 (first parallel group)
+   * - analyst1, analyst2, analyst3: the same groupId (parallel group)
    * - summarizer: undefined (sequential)
    */
   groupId?: number; // #new

package/src/types/summarize.ts

@@ -63,6 +63,28 @@ export interface SummarizeResult {
 export interface SummarizationNodeInput {
   remainingContextTokens: number;
   agentId: string;
+  /**
+   * Why the detour was requested.
+   *
+   * - `trigger` (default): the configured summarization trigger fired during
+   *   the pre-call budget check.
+   * - `overflow`: the provider rejected the prompt as too large and the run
+   *   is compacting to recover. When summarization is not enabled, this
+   *   variant performs no model call — the corrected budget alone is what the
+   *   retry needs.
+   */
+  reason?: 'trigger' | 'overflow';
+  /**
+   * Whether an overflow recovery may spend a summarization model call.
+   *
+   * The first recovery deliberately does not: re-pruning against the
+   * corrected budget raises context pressure, which drives the pruner's
+   * existing tool-output compression and masking. That is cheaper, needs no
+   * model call, and cannot lose message content the way a summary can. Only
+   * when deterministic compression proves insufficient does the next attempt
+   * allow the summarizer to run.
+   */
+  allowSummarization?: boolean;
 }
 
 export interface SummarizeStartEvent {

package/src/utils/__tests__/errors.test.ts

@@ -0,0 +1,270 @@
+import { describe, expect, it } from '@jest/globals';
+import {
+  getContextOverflowInfo,
+  isLikelyContextOverflowError,
+  isContextOverflowError,
+  extractErrorMessage,
+} from '@/utils/errors';
+import {
+  OVERFLOW_SIGNATURES,
+  NON_OVERFLOW_SIGNATURES,
+} from './fixtures/contextOverflowSignatures';
+import { Providers } from '@/common';
+
+/** Enough pressure to satisfy the corroboration gate for ambiguous errors. */
+const UNDER_PRESSURE = {
+  estimatedPromptTokens: 190_000,
+  maxContextTokens: 200_000,
+};
+
+describe('getContextOverflowInfo — captured provider signatures', () => {
+  for (const signature of OVERFLOW_SIGNATURES) {
+    const label = `${signature.provider}/${signature.model} (${signature.thrownAs})`;
+
+    it(`classifies ${label}`, () => {
+      const info = getContextOverflowInfo(signature.error, {
+        provider: signature.provider,
+        ...(signature.requiresContextPressure === true ? UNDER_PRESSURE : {}),
+      });
+
+      expect(info).not.toBeNull();
+      expect(info?.kind).toBe(signature.expected.kind);
+      expect(info?.provider).toBe(signature.provider);
+      expect(info?.limitTokens).toBe(signature.expected.limitTokens);
+      expect(info?.requestedTokens).toBe(signature.expected.requestedTokens);
+    });
+  }
+
+  it('covers every provider the SDK ships a client for, or records why not', () => {
+    const covered = new Set(OVERFLOW_SIGNATURES.map((s) => s.provider));
+    /**
+     * Azure and Moonshot reuse the OpenAI client verbatim, and MistralAI is
+     * the same client as Mistral, so the captured OpenAI/Mistral signatures
+     * apply unchanged. Every other provider has its own captured entry.
+     */
+    const byOpenAIClient = new Set([
+      Providers.AZURE,
+      Providers.MOONSHOT,
+      Providers.MISTRALAI,
+    ]);
+    for (const provider of Object.values(Providers)) {
+      expect(covered.has(provider) || byOpenAIClient.has(provider)).toBe(true);
+    }
+  });
+});
+
+describe('getContextOverflowInfo — errors compaction cannot fix', () => {
+  for (const signature of NON_OVERFLOW_SIGNATURES) {
+    it(`ignores ${signature.label}`, () => {
+      expect(getContextOverflowInfo(signature.error)).toBeNull();
+      expect(isContextOverflowError(signature.error)).toBe(false);
+    });
+  }
+
+  it('ignores an unrelated error entirely', () => {
+    expect(getContextOverflowInfo(new Error('socket hang up'))).toBeNull();
+    expect(getContextOverflowInfo(undefined)).toBeNull();
+    expect(getContextOverflowInfo(null)).toBeNull();
+  });
+});
+
+describe('token-bucket rejections', () => {
+  const requestTooLarge = OVERFLOW_SIGNATURES.find(
+    (s) => s.expected.kind === 'request_too_large'
+  );
+
+  it('treats a request that alone overruns the bucket as recoverable', () => {
+    const info = getContextOverflowInfo(requestTooLarge?.error);
+    expect(info?.kind).toBe('request_too_large');
+    expect(info?.requestedTokens).toBeGreaterThan(info?.limitTokens ?? 0);
+  });
+
+  it('treats an exactly-filling request as throttling, not overflow', () => {
+    /** It fits an empty bucket, so waiting can succeed — compaction would lose context needlessly. */
+    const exactFit = {
+      name: 'Error',
+      status: 429,
+      code: 'rate_limit_exceeded',
+      type: 'tokens',
+      message:
+        '429 Request too large for gpt-4o on tokens per min (TPM): Limit 30000, Requested 30000.',
+    };
+    expect(getContextOverflowInfo(exactFit)).toBeNull();
+  });
+
+  it('leaves ordinary throttling alone even when phrased with the same fields', () => {
+    const throttled = {
+      name: 'Error',
+      status: 429,
+      code: 'rate_limit_exceeded',
+      type: 'tokens',
+      message:
+        '429 Request too large for gpt-4o on tokens per min (TPM): Limit 30000, Requested 900.',
+    };
+    expect(getContextOverflowInfo(throttled)).toBeNull();
+  });
+});
+
+describe('ambiguous signatures require corroboration', () => {
+  const vertex = OVERFLOW_SIGNATURES.find(
+    (s) => s.requiresContextPressure === true
+  );
+
+  it('does not fire without a caller-side pressure signal', () => {
+    expect(
+      getContextOverflowInfo(vertex?.error, { provider: Providers.VERTEXAI })
+    ).toBeNull();
+  });
+
+  it('does not fire when the prompt was comfortably inside the budget', () => {
+    expect(
+      getContextOverflowInfo(vertex?.error, {
+        provider: Providers.VERTEXAI,
+        estimatedPromptTokens: 20_000,
+        maxContextTokens: 200_000,
+      })
+    ).toBeNull();
+  });
+
+  it('fires once the prompt is near the budget', () => {
+    expect(
+      getContextOverflowInfo(vertex?.error, {
+        provider: Providers.VERTEXAI,
+        ...UNDER_PRESSURE,
+      })
+    ).not.toBeNull();
+  });
+
+  it('still reports a Vertex error that did carry a reason', () => {
+    const withBody = {
+      name: 'Error',
+      message:
+        'Google request failed with status code 400: {"error":{"code":400,"message":"The input token count exceeds the maximum number of tokens allowed (1048576).","status":"INVALID_ARGUMENT"}}',
+    };
+    const info = getContextOverflowInfo(withBody, {
+      provider: Providers.VERTEXAI,
+    });
+    expect(info?.limitTokens).toBe(1_048_576);
+  });
+});
+
+describe('prompt size is separated from completion-inclusive totals', () => {
+  it('reads the input-only figure out of OpenRouter’s breakdown', () => {
+    const openrouter = OVERFLOW_SIGNATURES.find(
+      (s) => s.provider === Providers.OPENROUTER
+    );
+    const info = getContextOverflowInfo(openrouter?.error);
+    expect(info?.requestedTokens).toBe(56_827);
+    /** 56,811 of text input; the remaining 16 were the output allowance. */
+    expect(info?.promptTokens).toBe(56_811);
+  });
+
+  it('reads the input-only figure out of DeepSeek’s breakdown', () => {
+    const deepseek = OVERFLOW_SIGNATURES.find(
+      (s) => s.provider === Providers.DEEPSEEK
+    );
+    const info = getContextOverflowInfo(deepseek?.error);
+    expect(info?.requestedTokens).toBe(1_179_668);
+    expect(info?.promptTokens).toBe(1_179_652);
+  });
+
+  it('treats an unqualified input-only count as the prompt', () => {
+    const anthropic = OVERFLOW_SIGNATURES.find(
+      (s) => s.provider === Providers.ANTHROPIC
+    );
+    const info = getContextOverflowInfo(anthropic?.error);
+    expect(info?.promptTokens).toBe(info?.requestedTokens);
+  });
+
+  it('refuses to read a token-bucket total as a prompt measurement', () => {
+    const openai = OVERFLOW_SIGNATURES.find(
+      (s) => s.expected.kind === 'request_too_large'
+    );
+    const info = getContextOverflowInfo(openai?.error);
+    /** "Requested 480002" folds in the completion allowance. */
+    expect(info?.requestedTokens).toBe(480_002);
+    expect(info?.promptTokens).toBeUndefined();
+  });
+
+  it('refuses to read xAI’s request total as a prompt measurement', () => {
+    const xai = OVERFLOW_SIGNATURES.find((s) => s.provider === Providers.XAI);
+    const info = getContextOverflowInfo(xai?.error);
+    expect(info?.requestedTokens).toBe(332_986);
+    expect(info?.promptTokens).toBeUndefined();
+  });
+});
+
+describe('reported numbers are usable for recalibration', () => {
+  it('reads the true ceiling even when it differs from what we configured', () => {
+    const deepseek = OVERFLOW_SIGNATURES.find(
+      (s) => s.provider === Providers.DEEPSEEK
+    );
+    const info = getContextOverflowInfo(deepseek?.error);
+    expect(info?.limitTokens).toBe(1_048_565);
+  });
+
+  it('reads the provider-side count of the prompt we sent', () => {
+    const bedrock = OVERFLOW_SIGNATURES.find(
+      (s) => s.model === 'us.anthropic.claude-haiku-4-5-20251001-v1:0'
+    );
+    const info = getContextOverflowInfo(bedrock?.error);
+    expect(info?.requestedTokens).toBe(207_848);
+    expect(info?.limitTokens).toBe(200_000);
+  });
+});
+
+describe('back-compatible helpers', () => {
+  it('accepts a bare message string', () => {
+    expect(
+      isContextOverflowError(
+        'prompt is too long: 274468 tokens > 200000 maximum'
+      )
+    ).toBe(true);
+    expect(isContextOverflowError('connection reset')).toBe(false);
+  });
+
+  it('retains the legacy space-separated context overflow signature', () => {
+    expect(isContextOverflowError('context length exceeded')).toBe(true);
+  });
+
+  it('retains the legacy input-too-long signature', () => {
+    expect(getContextOverflowInfo(new Error('Input too long'))).not.toBeNull();
+    expect(isContextOverflowError('Input too long')).toBe(true);
+  });
+
+  it('reads structured overflow reason fields alongside generic messages', () => {
+    expect(
+      isContextOverflowError({
+        message: 'Bad Request',
+        code: 'context_length_exceeded',
+      })
+    ).toBe(true);
+    expect(
+      isContextOverflowError({
+        message: 'Bad Request',
+        error: { type: 'context_length_exceeded' },
+      })
+    ).toBe(true);
+  });
+
+  it('treats body-size rejections as likely overflow only in the loose check', () => {
+    const payload = { status: 413, message: 'request entity too large' };
+    expect(isContextOverflowError(payload)).toBe(false);
+    expect(isLikelyContextOverflowError(payload)).toBe(true);
+  });
+
+  it('keeps the loose check away from throttling and auth', () => {
+    for (const signature of NON_OVERFLOW_SIGNATURES) {
+      expect(isLikelyContextOverflowError(signature.error)).toBe(false);
+    }
+  });
+
+  it('extracts messages from nested provider shapes', () => {
+    expect(extractErrorMessage(new Error('boom'))).toBe('boom');
+    expect(extractErrorMessage({ error: { message: 'nested' } })).toBe(
+      'nested'
+    );
+    expect(extractErrorMessage('raw')).toBe('raw');
+    expect(extractErrorMessage(null)).toBe('');
+  });
+});