@librechat/agents 3.1.84 → 3.1.86

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

@@ -13,6 +13,14 @@ import {
   makeRequest,
 } from '../ProgrammaticToolCalling';
 import { createBashProgrammaticToolCallingTool } from '../BashProgrammaticToolCalling';
+import {
+  clampCodeApiRunTimeoutMs,
+  createCodeApiRunTimeoutSchema,
+} from '../ptcTimeout';
+import {
+  createLocalProgrammaticToolCallingTool,
+  createLocalBashProgrammaticToolCallingTool,
+} from '../local/LocalProgrammaticToolCalling';
 
 jest.mock('node-fetch', () => ({
   __esModule: true,
@@ -23,8 +31,33 @@ 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,
@@ -203,6 +236,76 @@ describe('CodeAPI auth header injection', () => {
     }
   });
 
+  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' },

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}.`,
+  };
+}

package/src/types/tools.ts

@@ -900,6 +900,8 @@ export type ProgrammaticToolCallingParams = {
   baseUrl?: string;
   /** Safety limit for round-trips (default: 20) */
   maxRoundTrips?: number;
+  /** Maximum per-sandbox-run timeout for PTC's legacy `timeout` field. */
+  runTimeoutMs?: number;
   /** HTTP proxy URL */
   proxy?: string;
   /** Enable debug logging (or set PTC_DEBUG=true env var) */