@librechat/agents 3.2.68 → 3.3.1

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/activityLabel.ts

@@ -0,0 +1,55 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { ClientOptions } from '@/types/llm';
+import type { Providers } from '@/common';
+
+/** One tool call's contribution to the label payload (host-assembled). */
+export type ActivityLabelToolEntry = {
+  toolName: string;
+  toolInput: unknown;
+  toolOutput?: unknown;
+  error?: string;
+  status: 'success' | 'error';
+};
+
+/**
+ * Options for `Run.generateActivityLabel`. The payload deliberately contains
+ * NO human messages: intent context comes from the assistant's own last text
+ * (Claude Code's pattern) and the block's reasoning excerpts (claude.ai's
+ * pattern) — user text stays out of this low-scrutiny pathway entirely.
+ *
+ * This SDK defines NO activity-label graph event and never dispatches one.
+ * Label lifecycle streaming is entirely host-owned: a host claims its own
+ * content slots and emits on its own transport, with a payload shape only
+ * it defines. The SDK surface here is exactly this method plus the
+ * `activity_label` content type's formatter exclusions.
+ */
+export type RunActivityLabelOptions = {
+  provider: Providers;
+  clientOptions?: ClientOptions;
+  /**
+   * Agent that executed the labeled batch. Selects that agent's Langfuse
+   * overlay (trace metadata AND tool-output redaction policy) instead of
+   * the graph default — a stricter per-agent policy must not be bypassed
+   * by labeling work the default agent never performed.
+   */
+  agentId?: string;
+  entries: ActivityLabelToolEntry[];
+  /** Truncated reasoning excerpts from the block being labeled. */
+  thinkingExcerpts?: string[];
+  /** Assistant's last text before the block (~200 chars), as intent context. */
+  lastAssistantText?: string;
+  /** Override for the default label system prompt. */
+  prompt?: string;
+  /** Per-entry serialization cap for the prompt. Default 600. */
+  charLimit?: number;
+  /** LangChain runnable config carrier (signal, callbacks, thread/user ids). */
+  chainOptions?: Partial<RunnableConfig> & {
+    configurable?: Record<string, unknown>;
+  };
+  /**
+   * Seed for deterministic Langfuse trace ids (e.g. `${runId}-${slotIndex}`)
+   * so each batch's label gets a distinct, reproducible trace. When omitted,
+   * a per-run sequence keeps batches from collapsing into one trace.
+   */
+  traceSeed?: string;
+};

package/src/types/index.ts

@@ -8,3 +8,4 @@ export * from './skill';
 export * from './stream';
 export * from './tools';
 export * from './summarize';
+export * from './activityLabel';

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
@@ -191,6 +192,8 @@ export interface ExtendedMessageContent {
   type?: string;
   text?: string;
   input?: string;
+  /** Tool-call arguments on a v1 standard-content `tool_call` block. */
+  args?: ToolCallPart['args'];
   index?: string | number;
   id?: string;
   name?: string;

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 {