@librechat/agents 3.1.82 → 3.1.84

package/src/tools/ProgrammaticToolCalling.ts

@@ -5,7 +5,12 @@ import { HttpsProxyAgent } from 'https-proxy-agent';
 import { tool, DynamicStructuredTool } from '@langchain/core/tools';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type * as t from '@/types';
-import { emptyOutputMessage, getCodeBaseURL } from './CodeExecutor';
+import {
+  buildCodeApiHttpErrorMessage,
+  emptyOutputMessage,
+  getCodeBaseURL,
+  resolveCodeApiAuthHeaders,
+} from './CodeExecutor';
 import { Constants } from '@/common';
 
 config();
@@ -147,6 +152,113 @@ const PYTHON_KEYWORDS = new Set([
   'yield',
 ]);
 
+export type FetchSessionFilesScope =
+  | { kind: 'skill'; id: string; version: number }
+  | { kind: 'agent' | 'user'; id: string; version?: never };
+
+type CodeApiSessionFileWire = {
+  id?: unknown;
+  name?: unknown;
+  metadata?: unknown;
+  resource_id?: unknown;
+  storage_session_id?: unknown;
+};
+
+type CodeApiSessionFileMetadata = {
+  'original-filename'?: unknown;
+};
+
+function isFetchSessionFilesScope(
+  value: unknown
+): value is FetchSessionFilesScope {
+  if (value == null || typeof value !== 'object') {
+    return false;
+  }
+  const scope = value as { kind?: unknown; id?: unknown; version?: unknown };
+  if (
+    (scope.kind === 'agent' || scope.kind === 'user') &&
+    typeof scope.id === 'string'
+  ) {
+    return true;
+  }
+  return (
+    scope.kind === 'skill' &&
+    typeof scope.id === 'string' &&
+    typeof scope.version === 'number'
+  );
+}
+
+function isCodeApiAuthHeaders(
+  value: string | t.CodeApiAuthHeaders | undefined
+): value is t.CodeApiAuthHeaders {
+  return value != null && typeof value !== 'string';
+}
+
+function isCodeApiSessionFileWire(
+  value: unknown
+): value is CodeApiSessionFileWire {
+  return value != null && typeof value === 'object';
+}
+
+function isCodeApiSessionFileMetadata(
+  value: unknown
+): value is CodeApiSessionFileMetadata {
+  return value != null && typeof value === 'object';
+}
+
+function normalizeSessionFile(
+  file: CodeApiSessionFileWire,
+  sessionId: string,
+  scope?: FetchSessionFilesScope
+): t.CodeEnvFile {
+  const metadata = isCodeApiSessionFileMetadata(file.metadata)
+    ? file.metadata
+    : undefined;
+  const rawName = typeof file.name === 'string' ? file.name : '';
+  const nameParts = rawName.split('/');
+  const fallbackId = nameParts.length > 1 ? nameParts[1].split('.')[0] : '';
+  const id =
+    typeof file.id === 'string' && file.id !== '' ? file.id : fallbackId;
+  const originalFilename = metadata?.['original-filename'];
+  const name =
+    typeof originalFilename === 'string' ? originalFilename : rawName;
+  const storage_session_id =
+    typeof file.storage_session_id === 'string'
+      ? file.storage_session_id
+      : sessionId;
+  const resource_id =
+    typeof file.resource_id === 'string' && file.resource_id !== ''
+      ? file.resource_id
+      : (scope?.id ?? id);
+
+  if (scope?.kind === 'skill') {
+    return {
+      storage_session_id,
+      kind: 'skill',
+      id,
+      resource_id,
+      name,
+      version: scope.version,
+    };
+  }
+  if (scope != null) {
+    return {
+      storage_session_id,
+      kind: scope.kind,
+      id,
+      resource_id,
+      name,
+    };
+  }
+  return {
+    storage_session_id,
+    kind: 'user',
+    id,
+    resource_id: id,
+    name,
+  };
+}
+
 /**
  * Normalizes a tool name to Python identifier format.
  * Must match the Code API's `normalizePythonFunctionName` exactly:
@@ -250,20 +362,62 @@ export function filterToolsByUsage(
  * Files are returned as CodeEnvFile references to be included in the request.
  * @param baseUrl - The base URL for the Code API
  * @param sessionId - The session ID to fetch files from
+ * @param scope - Resource scope used by CodeAPI to authorize the session
  * @param proxy - Optional HTTP proxy URL
  * @returns Array of CodeEnvFile references, or empty array if fetch fails
  */
 export async function fetchSessionFiles(
   baseUrl: string,
   sessionId: string,
-  proxy?: string
+  proxy?: string,
+  authHeaders?: t.CodeApiAuthHeaders
+): Promise<t.CodeEnvFile[]>;
+export async function fetchSessionFiles(
+  baseUrl: string,
+  sessionId: string,
+  scope: FetchSessionFilesScope,
+  proxyOrAuthHeaders?: string | t.CodeApiAuthHeaders,
+  authHeaders?: t.CodeApiAuthHeaders
+): Promise<t.CodeEnvFile[]>;
+export async function fetchSessionFiles(
+  baseUrl: string,
+  sessionId: string,
+  scopeOrProxy?: FetchSessionFilesScope | string,
+  proxyOrAuthHeaders?: string | t.CodeApiAuthHeaders,
+  scopedAuthHeaders?: t.CodeApiAuthHeaders
 ): Promise<t.CodeEnvFile[]> {
   try {
-    const filesEndpoint = `${baseUrl}/files/${sessionId}?detail=full`;
+    const scope = isFetchSessionFilesScope(scopeOrProxy)
+      ? scopeOrProxy
+      : undefined;
+    let proxy: string | undefined;
+    let authHeaders: t.CodeApiAuthHeaders | undefined;
+    if (scope == null) {
+      proxy = typeof scopeOrProxy === 'string' ? scopeOrProxy : undefined;
+      authHeaders = isCodeApiAuthHeaders(proxyOrAuthHeaders)
+        ? proxyOrAuthHeaders
+        : undefined;
+    } else if (typeof proxyOrAuthHeaders === 'string') {
+      proxy = proxyOrAuthHeaders;
+      authHeaders = scopedAuthHeaders;
+    } else {
+      authHeaders = proxyOrAuthHeaders ?? scopedAuthHeaders;
+    }
+    const query = new URLSearchParams({ detail: 'full' });
+    if (scope != null) {
+      query.set('kind', scope.kind);
+      query.set('id', scope.id);
+      if (scope.kind === 'skill') {
+        query.set('version', String(scope.version));
+      }
+    }
+    const filesEndpoint = `${baseUrl}/files/${encodeURIComponent(sessionId)}?${query.toString()}`;
+    const resolvedAuthHeaders = await resolveCodeApiAuthHeaders(authHeaders);
     const fetchOptions: RequestInit = {
       method: 'GET',
       headers: {
         'User-Agent': 'LibreChat/1.0',
+        ...resolvedAuthHeaders,
       },
     };
 
@@ -273,7 +427,9 @@ export async function fetchSessionFiles(
 
     const response = await fetch(filesEndpoint, fetchOptions);
     if (!response.ok) {
-      throw new Error(`Failed to fetch files for session: ${response.status}`);
+      throw new Error(
+        await buildCodeApiHttpErrorMessage('GET', filesEndpoint, response)
+      );
     }
 
     const files = await response.json();
@@ -281,25 +437,9 @@ export async function fetchSessionFiles(
       return [];
     }
 
-    return files.map((file: Record<string, unknown>) => {
-      // Extract the ID from the file name (part after session ID prefix and before extension)
-      const nameParts = (file.name as string).split('/');
-      const id = nameParts.length > 1 ? nameParts[1].split('.')[0] : '';
-
-      return {
-        storage_session_id: sessionId,
-        /* `/files` fallback returns code-output files belonging to
-         * the user; tag them user-private. */
-        kind: 'user' as const,
-        id,
-        /* `resource_id` informational for `kind: 'user'` —
-         * codeapi derives sessionKey from auth context. */
-        resource_id: id,
-        name: (file.metadata as Record<string, unknown>)[
-          'original-filename'
-        ] as string,
-      };
-    });
+    return files
+      .filter(isCodeApiSessionFileWire)
+      .map((file) => normalizeSessionFile(file, sessionId, scope));
   } catch (error) {
     // eslint-disable-next-line no-console
     console.warn(
@@ -319,13 +459,16 @@ export async function fetchSessionFiles(
 export async function makeRequest(
   endpoint: string,
   body: Record<string, unknown>,
-  proxy?: string
+  proxy?: string,
+  authHeaders?: t.CodeApiAuthHeaders
 ): Promise<t.ProgrammaticExecutionResponse> {
+  const resolvedAuthHeaders = await resolveCodeApiAuthHeaders(authHeaders);
   const fetchOptions: RequestInit = {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
       'User-Agent': 'LibreChat/1.0',
+      ...resolvedAuthHeaders,
     },
     body: JSON.stringify(body),
   };
@@ -337,9 +480,8 @@ export async function makeRequest(
   const response = await fetch(endpoint, fetchOptions);
 
   if (!response.ok) {
-    const errorText = await response.text();
     throw new Error(
-      `HTTP error! status: ${response.status}, body: ${errorText}`
+      await buildCodeApiHttpErrorMessage('POST', endpoint, response)
     );
   }
 
@@ -486,7 +628,8 @@ export function unwrapToolResponse(
  */
 export async function executeTools(
   toolCalls: t.PTCToolCall[],
-  toolMap: t.ToolMap
+  toolMap: t.ToolMap,
+  programmaticToolName = Constants.PROGRAMMATIC_TOOL_CALLING
 ): Promise<t.PTCToolResult[]> {
   const executions = toolCalls.map(async (call): Promise<t.PTCToolResult> => {
     const tool = toolMap.get(call.name);
@@ -502,7 +645,7 @@ export async function executeTools(
 
     try {
       const result = await tool.invoke(call.input, {
-        metadata: { [Constants.PROGRAMMATIC_TOOL_CALLING]: true },
+        metadata: { [programmaticToolName]: true },
       });
 
       const isMCPTool = tool.mcp === true;
@@ -661,7 +804,8 @@ export function createProgrammaticToolCallingTool(
             timeout,
             ...(files && files.length > 0 ? { files } : {}),
           },
-          proxy
+          proxy,
+          initParams.authHeaders
         );
 
         // ====================================================================
@@ -697,7 +841,8 @@ export function createProgrammaticToolCallingTool(
               continuation_token: response.continuation_token,
               tool_results: toolResults,
             },
-            proxy
+            proxy,
+            initParams.authHeaders
           );
         }
 

package/src/tools/ToolNode.ts

@@ -844,10 +844,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           // Plumb the hook context into the programmatic-tool path so
           // inner tool calls made via the in-process bridge can run
           // through `PreToolUse` (deny / updatedInput) before reaching
-          // the underlying tool. Without this, `run_tools_with_code`
-          // bypassed every PreToolUse hook the host registered for
-          // the tools it dispatches — including HITL gates on
-          // `write_file` / `edit_file` (manual review finding A).
+          // the underlying tool. Without this, programmatic tool calls
+          // bypass every PreToolUse hook the host registered for the tools
+          // they dispatch — including HITL gates on `write_file` / `edit_file`.
           hookContext: {
             registry: this.hookRegistry,
             runId: (config.configurable?.run_id as string | undefined) ?? '',

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

@@ -0,0 +1,321 @@
+import fetch from 'node-fetch';
+import { beforeEach, describe, expect, it, jest } from '@jest/globals';
+import type { RequestInit } from 'node-fetch';
+import type * as t from '@/types';
+import {
+  createCodeExecutionTool,
+  resolveCodeApiAuthHeaders,
+} from '../CodeExecutor';
+import { createBashExecutionTool } from '../BashExecutor';
+import {
+  createProgrammaticToolCallingTool,
+  fetchSessionFiles,
+  makeRequest,
+} from '../ProgrammaticToolCalling';
+import { createBashProgrammaticToolCallingTool } from '../BashProgrammaticToolCalling';
+
+jest.mock('node-fetch', () => ({
+  __esModule: true,
+  default: jest.fn(),
+}));
+
+type FetchMock = jest.MockedFunction<
+  (url: unknown, init?: unknown) => Promise<unknown>
+>;
+
+const fetchMock = fetch as unknown as FetchMock;
+
+function jsonResponse(body: unknown): unknown {
+  return {
+    ok: true,
+    json: jest.fn(async () => body),
+    text: jest.fn(async () => JSON.stringify(body)),
+  };
+}
+
+function completedResponse(stdout = 'ok'): unknown {
+  return jsonResponse({
+    status: 'completed',
+    session_id: 'session_123',
+    stdout,
+  });
+}
+
+function errorResponse(status: number, body: string): unknown {
+  return {
+    ok: false,
+    status,
+    text: jest.fn(async () => body),
+  };
+}
+
+const toolDefs = [
+  {
+    name: 'lookup_user',
+    description: 'Lookup a user',
+    parameters: {
+      type: 'object',
+      properties: {},
+    },
+  },
+] as unknown as t.LCTool[];
+
+function toolMap(): t.ToolMap {
+  return new Map([
+    [
+      'lookup_user',
+      {
+        name: 'lookup_user',
+        invoke: jest.fn(async () => ({ id: 'user_123' })),
+      },
+    ],
+  ]) as unknown as t.ToolMap;
+}
+
+describe('CodeAPI auth header injection', () => {
+  beforeEach(() => {
+    fetchMock.mockReset();
+    fetchMock.mockResolvedValue(completedResponse());
+  });
+
+  it('resolves static and dynamic auth header params', async () => {
+    await expect(
+      resolveCodeApiAuthHeaders({ Authorization: 'Bearer static' })
+    ).resolves.toEqual({
+      Authorization: 'Bearer static',
+    });
+    await expect(
+      resolveCodeApiAuthHeaders(async () => ({
+        Authorization: 'Bearer dynamic',
+      }))
+    ).resolves.toEqual({
+      Authorization: 'Bearer dynamic',
+    });
+    await expect(resolveCodeApiAuthHeaders()).resolves.toEqual({});
+  });
+
+  it('keeps the no-auth request path unchanged', async () => {
+    await makeRequest('https://code.example.com/exec/programmatic', {
+      code: 'print(1)',
+    });
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://code.example.com/exec/programmatic',
+      expect.objectContaining({
+        headers: expect.not.objectContaining({
+          Authorization: expect.any(String),
+        }),
+      })
+    );
+  });
+
+  it('forwards Authorization for direct code execution', async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ session_id: 'session_123', stdout: '1\n' })
+    );
+    const tool = createCodeExecutionTool({
+      authHeaders: async () => ({ Authorization: 'Bearer code-token' }),
+    });
+
+    await tool.invoke({ lang: 'py', code: 'print(1)' });
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: 'Bearer code-token',
+        }),
+      })
+    );
+    expect(
+      JSON.parse((fetchMock.mock.calls[0]?.[1] as RequestInit).body as string)
+    ).not.toHaveProperty('authHeaders');
+  });
+
+  it('forwards Authorization for bash execution', async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ session_id: 'session_123', stdout: '1\n' })
+    );
+    const tool = createBashExecutionTool({
+      authHeaders: { Authorization: 'Bearer bash-token' },
+    });
+
+    await tool.invoke({ command: 'echo 1' });
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: 'Bearer bash-token',
+        }),
+      })
+    );
+    expect(
+      JSON.parse((fetchMock.mock.calls[0]?.[1] as RequestInit).body as string)
+    ).not.toHaveProperty('authHeaders');
+  });
+
+  it('includes 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/
+    );
+  });
+
+  it('forwards Authorization on programmatic initial and continuation requests', async () => {
+    fetchMock
+      .mockResolvedValueOnce(
+        jsonResponse({
+          status: 'tool_call_required',
+          continuation_token: 'continue_123',
+          tool_calls: [{ id: 'call_1', name: 'lookup_user', input: {} }],
+        })
+      )
+      .mockResolvedValueOnce(completedResponse('done'));
+
+    const tool = createProgrammaticToolCallingTool({
+      authHeaders: () => ({ Authorization: 'Bearer ptc-token' }),
+    });
+
+    await tool.invoke(
+      { code: 'result = await lookup_user()\nprint(result)' },
+      {
+        toolCall: {
+          name: 'programmatic_code_execution',
+          args: {},
+          toolMap: toolMap(),
+          toolDefs,
+        },
+      }
+    );
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    for (const call of fetchMock.mock.calls) {
+      expect(call[1]).toEqual(
+        expect.objectContaining({
+          headers: expect.objectContaining({
+            Authorization: 'Bearer ptc-token',
+          }),
+        })
+      );
+    }
+  });
+
+  it('forwards Authorization for bash programmatic requests', async () => {
+    const tool = createBashProgrammaticToolCallingTool({
+      authHeaders: { Authorization: 'Bearer bash-ptc-token' },
+    });
+
+    await tool.invoke(
+      { code: 'lookup_user "{}"' },
+      {
+        toolCall: {
+          name: 'bash_programmatic_code_execution',
+          args: {},
+          toolMap: toolMap(),
+          toolDefs,
+        },
+      }
+    );
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: 'Bearer bash-ptc-token',
+        }),
+      })
+    );
+  });
+
+  it('fetches session files with the CodeAPI resource scope and auth headers', async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse([
+        {
+          id: 'file-1',
+          resource_id: 'skill-1',
+          storage_session_id: 'session_123',
+          name: 'skill/file.txt',
+          kind: 'skill',
+          version: 7,
+        },
+      ])
+    );
+
+    const files = await fetchSessionFiles(
+      'https://code.example.com',
+      'session_123',
+      { kind: 'skill', id: 'skill-1', version: 7 },
+      undefined,
+      { Authorization: 'Bearer files-token' }
+    );
+
+    expect(files).toHaveLength(1);
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://code.example.com/files/session_123?detail=full&kind=skill&id=skill-1&version=7',
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: 'Bearer files-token',
+        }),
+      })
+    );
+  });
+
+  it('fetches scoped session files with auth headers and no proxy placeholder', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse([]));
+
+    await fetchSessionFiles(
+      'https://code.example.com',
+      'session_123',
+      { kind: 'skill', id: 'skill-1', version: 7 },
+      { Authorization: 'Bearer scoped-files-token' }
+    );
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://code.example.com/files/session_123?detail=full&kind=skill&id=skill-1&version=7',
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: 'Bearer scoped-files-token',
+        }),
+      })
+    );
+  });
+
+  it('preserves the legacy fetchSessionFiles proxy/auth argument order', async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse([
+        {
+          name: 'session_123/file-1.txt',
+          metadata: { 'original-filename': 'file.txt' },
+        },
+      ])
+    );
+
+    const files = await fetchSessionFiles(
+      'https://code.example.com',
+      'session_123',
+      '',
+      { Authorization: 'Bearer legacy-files-token' }
+    );
+
+    expect(files).toEqual([
+      {
+        storage_session_id: 'session_123',
+        kind: 'user',
+        id: 'file-1',
+        resource_id: 'file-1',
+        name: 'file.txt',
+      },
+    ]);
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://code.example.com/files/session_123?detail=full',
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: 'Bearer legacy-files-token',
+        }),
+      })
+    );
+  });
+});

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

@@ -3,8 +3,9 @@
  * Unit tests for Programmatic Tool Calling.
  * Tests manual invocation with mock tools and Code API responses.
  */
-import { describe, it, expect, beforeEach } from '@jest/globals';
+import { describe, it, expect, jest, beforeEach } from '@jest/globals';
 import type * as t from '@/types';
+import { Constants } from '@/common';
 import {
   createProgrammaticToolCallingTool,
   formatCompletedResponse,
@@ -56,6 +57,35 @@ describe('ProgrammaticToolCalling', () => {
       });
     });
 
+    it('marks bash PTC inner tool invocations with bash metadata', async () => {
+      const invoke = jest.fn<
+        (_input: unknown, _config: unknown) => Promise<{ ok: boolean }>
+          >(async () => ({ ok: true }));
+      const customTool = {
+        name: 'custom_tool',
+        invoke,
+      } as unknown as t.GenericTool;
+      const customToolMap: t.ToolMap = new Map([['custom_tool', customTool]]);
+      const toolCalls: t.PTCToolCall[] = [
+        {
+          id: 'call_001',
+          name: 'custom_tool',
+          input: { value: 1 },
+        },
+      ];
+
+      await executeTools(
+        toolCalls,
+        customToolMap,
+        Constants.BASH_PROGRAMMATIC_TOOL_CALLING
+      );
+
+      expect(invoke).toHaveBeenCalledWith(
+        { value: 1 },
+        { metadata: { [Constants.BASH_PROGRAMMATIC_TOOL_CALLING]: true } }
+      );
+    });
+
     it('executes multiple tools in parallel', async () => {
       const toolCalls: t.PTCToolCall[] = [
         {

package/src/types/tools.ts

@@ -219,8 +219,16 @@ export type CodeExecutionToolParams =
       session_id?: string;
       user_id?: string;
       files?: CodeEnvFile[];
+      /** Optional host-supplied Code API auth headers. */
+      authHeaders?: CodeApiAuthHeaders;
     };
 
+export type CodeApiAuthHeaderMap = Record<string, string>;
+
+export type CodeApiAuthHeaders =
+  | CodeApiAuthHeaderMap
+  | (() => CodeApiAuthHeaderMap | Promise<CodeApiAuthHeaderMap>);
+
 export type FileRef = {
   /**
    * Storage file id (the per-file uuid). See `CodeEnvFile.id` for
@@ -896,6 +904,8 @@ export type ProgrammaticToolCallingParams = {
   proxy?: string;
   /** Enable debug logging (or set PTC_DEBUG=true env var) */
   debug?: boolean;
+  /** Optional host-supplied Code API auth headers. */
+  authHeaders?: CodeApiAuthHeaders;
 };
 
 // ============================================================================