@librechat/agents 3.1.83 → 3.1.85

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

@@ -0,0 +1,424 @@
+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';
+import {
+  clampCodeApiRunTimeoutMs,
+  createCodeApiRunTimeoutSchema,
+} from '../ptcTimeout';
+import {
+  createLocalProgrammaticToolCallingTool,
+  createLocalBashProgrammaticToolCallingTool,
+} from '../local/LocalProgrammaticToolCalling';
+
+jest.mock('node-fetch', () => ({
+  __esModule: true,
+  default: jest.fn(),
+}));
+
+type FetchMock = jest.MockedFunction<
+  (url: unknown, init?: unknown) => Promise<unknown>
+>;
+
+type CodeApiRequestBody = {
+  timeout?: number;
+};
+
+type TimeoutSchemaForTest = {
+  default: number;
+  maximum: number;
+  description: string;
+};
+
+type ToolSchemaForTest = {
+  properties: {
+    timeout: TimeoutSchemaForTest;
+  };
+};
+
+const fetchMock = fetch as unknown as FetchMock;
+
+function requestBodyAt(callIndex: number): CodeApiRequestBody {
+  const init = fetchMock.mock.calls[callIndex]?.[1] as RequestInit;
+  return JSON.parse(init.body as string) as CodeApiRequestBody;
+}
+
+function timeoutSchemaForTest(toolSchema: unknown): TimeoutSchemaForTest {
+  return (toolSchema as ToolSchemaForTest).properties.timeout;
+}
+
+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('defaults programmatic timeout to the configured CodeAPI run cap', async () => {
+    const tool = createProgrammaticToolCallingTool({
+      runTimeoutMs: 15000,
+    });
+
+    await tool.invoke(
+      { code: 'result = await lookup_user()\nprint(result)' },
+      {
+        toolCall: {
+          name: 'programmatic_code_execution',
+          args: {},
+          toolMap: toolMap(),
+          toolDefs,
+        },
+      }
+    );
+
+    expect(requestBodyAt(0).timeout).toBe(15000);
+  });
+
+  it('defaults bash programmatic timeout to the configured CodeAPI run cap', async () => {
+    const tool = createBashProgrammaticToolCallingTool({
+      runTimeoutMs: 15000,
+    });
+
+    await tool.invoke(
+      { code: 'lookup_user "{}"' },
+      {
+        toolCall: {
+          name: 'bash_programmatic_code_execution',
+          args: {},
+          toolMap: toolMap(),
+          toolDefs,
+        },
+      }
+    );
+
+    expect(requestBodyAt(0).timeout).toBe(15000);
+  });
+
+  it('describes the PTC timeout as a single sandbox run cap', () => {
+    const schema = createCodeApiRunTimeoutSchema(15000);
+
+    expect(clampCodeApiRunTimeoutMs(60000, 15000)).toBe(15000);
+    expect(schema.default).toBe(15000);
+    expect(schema.maximum).toBe(15000);
+    expect(schema.description).toContain('one sandbox run');
+    expect(schema.description).toContain('not the total multi-round-trip');
+  });
+
+  it('keeps local programmatic timeout schemas aligned with local execution defaults', () => {
+    const pythonTimeout = timeoutSchemaForTest(
+      createLocalProgrammaticToolCallingTool().schema
+    );
+    const bashTimeout = timeoutSchemaForTest(
+      createLocalBashProgrammaticToolCallingTool().schema
+    );
+    const configuredTimeout = timeoutSchemaForTest(
+      createLocalProgrammaticToolCallingTool({ timeoutMs: 120000 }).schema
+    );
+
+    expect(pythonTimeout.default).toBe(60000);
+    expect(pythonTimeout.maximum).toBe(300000);
+    expect(pythonTimeout.description).toContain('local execution time');
+    expect(bashTimeout.default).toBe(60000);
+    expect(bashTimeout.maximum).toBe(300000);
+    expect(configuredTimeout.default).toBe(120000);
+    expect(configuredTimeout.maximum).toBe(300000);
+  });
+
+  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/tools/local/LocalProgrammaticToolCalling.ts

@@ -30,19 +30,100 @@ import {
 import { Constants } from '@/common';
 
 const DEFAULT_TIMEOUT = 60000;
-const LocalProgrammaticToolCallingSchema = {
-  ...ProgrammaticToolCallingSchema,
-  properties: {
-    ...ProgrammaticToolCallingSchema.properties,
+const LOCAL_MIN_TIMEOUT = 1000;
+const LOCAL_MAX_TIMEOUT = 300000;
+
+type LocalTimeoutSchema = {
+  type: 'integer';
+  minimum: number;
+  maximum: number;
+  default: number;
+  description: string;
+};
+
+type LocalProgrammaticToolCallingJsonSchema = {
+  type: 'object';
+  properties: typeof ProgrammaticToolCallingSchema.properties & {
+    timeout: LocalTimeoutSchema;
     lang: {
-      type: 'string',
-      enum: ['py', 'python', 'bash', 'sh'],
-      default: 'bash',
-      description:
-        'Local engine runtime for orchestration code. Defaults to bash; use py/python for Python orchestration.',
+      type: 'string';
+      enum: readonly ['py', 'python', 'bash', 'sh'];
+      default: 'bash';
+      description: string;
+    };
+  };
+  required: readonly ['code'];
+};
+
+type LocalBashProgrammaticToolCallingJsonSchema = {
+  type: 'object';
+  properties: typeof BashProgrammaticToolCallingSchema.properties & {
+    timeout: LocalTimeoutSchema;
+  };
+  required: readonly ['code'];
+};
+
+function normalizeLocalTimeout(timeoutMs: number | undefined): number {
+  if (timeoutMs == null || !Number.isFinite(timeoutMs)) {
+    return DEFAULT_TIMEOUT;
+  }
+
+  return Math.max(LOCAL_MIN_TIMEOUT, Math.floor(timeoutMs));
+}
+
+function formatLocalTimeout(timeoutMs: number): string {
+  return timeoutMs % 1000 === 0
+    ? `${timeoutMs / 1000} seconds`
+    : `${timeoutMs} milliseconds`;
+}
+
+function createLocalTimeoutSchema(timeoutMs?: number): LocalTimeoutSchema {
+  const defaultTimeout = normalizeLocalTimeout(timeoutMs);
+  const maxTimeout = Math.max(LOCAL_MAX_TIMEOUT, defaultTimeout);
+  const formattedDefault = formatLocalTimeout(defaultTimeout);
+  const formattedMax = formatLocalTimeout(maxTimeout);
+
+  return {
+    type: 'integer',
+    minimum: LOCAL_MIN_TIMEOUT,
+    maximum: maxTimeout,
+    default: defaultTimeout,
+    description:
+      'Maximum local execution time in milliseconds. ' +
+      `Default: ${formattedDefault}. Max: ${formattedMax}.`,
+  };
+}
+
+function createLocalProgrammaticToolCallingSchema(
+  localConfig: t.LocalExecutionConfig = {}
+): LocalProgrammaticToolCallingJsonSchema {
+  return {
+    ...ProgrammaticToolCallingSchema,
+    properties: {
+      ...ProgrammaticToolCallingSchema.properties,
+      timeout: createLocalTimeoutSchema(localConfig.timeoutMs),
+      lang: {
+        type: 'string',
+        enum: ['py', 'python', 'bash', 'sh'],
+        default: 'bash',
+        description:
+          'Local engine runtime for orchestration code. Defaults to bash; use py/python for Python orchestration.',
+      },
     },
-  },
-} as const;
+  } as const;
+}
+
+function createLocalBashProgrammaticToolCallingSchema(
+  localConfig: t.LocalExecutionConfig = {}
+): LocalBashProgrammaticToolCallingJsonSchema {
+  return {
+    ...BashProgrammaticToolCallingSchema,
+    properties: {
+      ...BashProgrammaticToolCallingSchema.properties,
+      timeout: createLocalTimeoutSchema(localConfig.timeoutMs),
+    },
+  } as const;
+}
 
 type ToolBridge = {
   url: string;
@@ -582,7 +663,7 @@ export function createLocalProgrammaticToolCallingTool(
     {
       name: ProgrammaticToolCallingName,
       description: `${ProgrammaticToolCallingDescription}\n\nLocal engine: runs bash by default, or Python when \`lang\` is \`py\` or \`python\`, on the host machine and calls tools through an in-process localhost bridge.`,
-      schema: LocalProgrammaticToolCallingSchema,
+      schema: createLocalProgrammaticToolCallingSchema(localConfig),
       responseFormat: Constants.CONTENT_AND_ARTIFACT,
     }
   );
@@ -604,7 +685,7 @@ export function createLocalBashProgrammaticToolCallingTool(
     {
       name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
       description: `${BashProgrammaticToolCallingDescription}\n\nLocal engine: runs this bash orchestration code on the host machine and calls tools through an in-process localhost bridge.`,
-      schema: BashProgrammaticToolCallingSchema,
+      schema: createLocalBashProgrammaticToolCallingSchema(localConfig),
       responseFormat: Constants.CONTENT_AND_ARTIFACT,
     }
   );

package/src/tools/ptcTimeout.ts

@@ -0,0 +1,89 @@
+import { EnvVar } from '@/common';
+
+export const DEFAULT_CODE_API_RUN_TIMEOUT_MS = 15_000;
+export const MIN_CODE_API_RUN_TIMEOUT_MS = 1_000;
+
+type TimeoutSchema = {
+  type: 'integer';
+  minimum: number;
+  maximum: number;
+  default: number;
+  description: string;
+};
+
+export type ProgrammaticToolCallingJsonSchema = {
+  type: 'object';
+  properties: {
+    code: {
+      type: 'string';
+      minLength: number;
+      description: string;
+    };
+    timeout: TimeoutSchema;
+  };
+  required: readonly ['code'];
+};
+
+function normalizeTimeoutMs(value: number | undefined): number | undefined {
+  if (value == null || !Number.isFinite(value)) {
+    return undefined;
+  }
+
+  return Math.max(MIN_CODE_API_RUN_TIMEOUT_MS, Math.floor(value));
+}
+
+function parseTimeoutMs(value: string | undefined): number | undefined {
+  if (value == null || value.trim() === '') {
+    return undefined;
+  }
+
+  return normalizeTimeoutMs(Number(value));
+}
+
+function formatTimeout(timeoutMs: number): string {
+  return timeoutMs % 1000 === 0
+    ? `${timeoutMs / 1000} seconds`
+    : `${timeoutMs} milliseconds`;
+}
+
+export function resolveCodeApiRunTimeoutMs(override?: number): number {
+  return (
+    normalizeTimeoutMs(override) ??
+    parseTimeoutMs(process.env[EnvVar.CODE_API_RUN_TIMEOUT_MS]) ??
+    DEFAULT_CODE_API_RUN_TIMEOUT_MS
+  );
+}
+
+export function clampCodeApiRunTimeoutMs(
+  timeoutMs: number | undefined,
+  maxRunTimeoutMs = resolveCodeApiRunTimeoutMs()
+): number {
+  const normalizedMaxRunTimeoutMs =
+    normalizeTimeoutMs(maxRunTimeoutMs) ?? DEFAULT_CODE_API_RUN_TIMEOUT_MS;
+  const normalizedTimeoutMs = normalizeTimeoutMs(timeoutMs);
+
+  if (normalizedTimeoutMs == null) {
+    return normalizedMaxRunTimeoutMs;
+  }
+
+  return Math.min(normalizedTimeoutMs, normalizedMaxRunTimeoutMs);
+}
+
+export function createCodeApiRunTimeoutSchema(
+  maxRunTimeoutMs = resolveCodeApiRunTimeoutMs()
+): TimeoutSchema {
+  const normalizedMaxRunTimeoutMs =
+    normalizeTimeoutMs(maxRunTimeoutMs) ?? DEFAULT_CODE_API_RUN_TIMEOUT_MS;
+  const formattedTimeout = formatTimeout(normalizedMaxRunTimeoutMs);
+
+  return {
+    type: 'integer',
+    minimum: MIN_CODE_API_RUN_TIMEOUT_MS,
+    maximum: normalizedMaxRunTimeoutMs,
+    default: normalizedMaxRunTimeoutMs,
+    description:
+      'Maximum wall-clock time in milliseconds for one sandbox run or replay iteration. ' +
+      'This is not the total multi-round-trip task budget. ' +
+      `Default: ${formattedTimeout}. Max: ${formattedTimeout}.`,
+  };
+}