@librechat/agents 3.1.84 → 3.1.85

package/src/tools/BashProgrammaticToolCalling.ts

@@ -1,6 +1,7 @@
 import { config } from 'dotenv';
 import { tool, DynamicStructuredTool } from '@langchain/core/tools';
 import type { ToolCall } from '@langchain/core/messages/tool';
+import type { ProgrammaticToolCallingJsonSchema } from './ptcTimeout';
 import type * as t from '@/types';
 import {
   makeRequest,
@@ -8,6 +9,11 @@ import {
   formatCompletedResponse,
 } from './ProgrammaticToolCalling';
 import { getCodeBaseURL } from './CodeExecutor';
+import {
+  clampCodeApiRunTimeoutMs,
+  createCodeApiRunTimeoutSchema,
+  resolveCodeApiRunTimeoutMs,
+} from './ptcTimeout';
 import { Constants } from '@/common';
 
 config();
@@ -17,7 +23,7 @@ config();
 // ============================================================================
 
 const DEFAULT_MAX_ROUND_TRIPS = 20;
-const DEFAULT_TIMEOUT = 60000;
+const DEFAULT_RUN_TIMEOUT_MS = resolveCodeApiRunTimeoutMs();
 
 /** Bash reserved words that get `_tool` suffix when used as function names */
 const BASH_RESERVED = new Set([
@@ -60,7 +66,8 @@ const CORE_RULES = `Rules:
 - Tools are pre-defined as bash functions—DO NOT redefine them
 - Each tool function accepts a JSON string argument
 - Only echo/printf output returns to the model
-- Generated files are automatically available in /mnt/data/ for subsequent executions`;
+- Generated files are automatically available in /mnt/data/ for subsequent executions
+- timeout caps one sandbox run/replay iteration, not the total multi-round-trip workflow`;
 
 const ADDITIONAL_RULES =
   '- Tool names normalized: hyphens→underscores, reserved words get `_tool` suffix';
@@ -92,25 +99,25 @@ ${CORE_RULES}`;
 // Schema
 // ============================================================================
 
-export const BashProgrammaticToolCallingSchema = {
-  type: 'object',
-  properties: {
-    code: {
-      type: 'string',
-      minLength: 1,
-      description: CODE_PARAM_DESCRIPTION,
-    },
-    timeout: {
-      type: 'integer',
-      minimum: 1000,
-      maximum: 300000,
-      default: DEFAULT_TIMEOUT,
-      description:
-        'Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.',
+export function createBashProgrammaticToolCallingSchema(
+  maxRunTimeoutMs = DEFAULT_RUN_TIMEOUT_MS
+): ProgrammaticToolCallingJsonSchema {
+  return {
+    type: 'object',
+    properties: {
+      code: {
+        type: 'string',
+        minLength: 1,
+        description: CODE_PARAM_DESCRIPTION,
+      },
+      timeout: createCodeApiRunTimeoutSchema(maxRunTimeoutMs),
     },
-  },
-  required: ['code'],
-} as const;
+    required: ['code'],
+  } as const;
+}
+
+export const BashProgrammaticToolCallingSchema =
+  createBashProgrammaticToolCallingSchema();
 
 export const BashProgrammaticToolCallingName =
   Constants.BASH_PROGRAMMATIC_TOOL_CALLING;
@@ -242,6 +249,7 @@ export function createBashProgrammaticToolCallingTool(
 ): DynamicStructuredTool {
   const baseUrl = initParams.baseUrl ?? getCodeBaseURL();
   const maxRoundTrips = initParams.maxRoundTrips ?? DEFAULT_MAX_ROUND_TRIPS;
+  const maxRunTimeoutMs = resolveCodeApiRunTimeoutMs(initParams.runTimeoutMs);
   const proxy = initParams.proxy ?? process.env.PROXY;
   const debug = initParams.debug ?? process.env.BASH_PTC_DEBUG === 'true';
   const EXEC_ENDPOINT = `${baseUrl}/exec/programmatic`;
@@ -249,7 +257,8 @@ export function createBashProgrammaticToolCallingTool(
   return tool(
     async (rawParams, config) => {
       const params = rawParams as { code: string; timeout?: number };
-      const { code, timeout = DEFAULT_TIMEOUT } = params;
+      const { code } = params;
+      const timeout = clampCodeApiRunTimeoutMs(params.timeout, maxRunTimeoutMs);
 
       const toolCall = (config.toolCall ?? {}) as ToolCall &
         Partial<t.ProgrammaticCache> & {
@@ -382,7 +391,7 @@ export function createBashProgrammaticToolCallingTool(
     {
       name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
       description: BashProgrammaticToolCallingDescription,
-      schema: BashProgrammaticToolCallingSchema,
+      schema: createBashProgrammaticToolCallingSchema(maxRunTimeoutMs),
       responseFormat: Constants.CONTENT_AND_ARTIFACT,
     }
   );

package/src/tools/ProgrammaticToolCalling.ts

@@ -4,6 +4,7 @@ import fetch, { RequestInit } from 'node-fetch';
 import { HttpsProxyAgent } from 'https-proxy-agent';
 import { tool, DynamicStructuredTool } from '@langchain/core/tools';
 import type { ToolCall } from '@langchain/core/messages/tool';
+import type { ProgrammaticToolCallingJsonSchema } from './ptcTimeout';
 import type * as t from '@/types';
 import {
   buildCodeApiHttpErrorMessage,
@@ -11,6 +12,11 @@ import {
   getCodeBaseURL,
   resolveCodeApiAuthHeaders,
 } from './CodeExecutor';
+import {
+  clampCodeApiRunTimeoutMs,
+  createCodeApiRunTimeoutSchema,
+  resolveCodeApiRunTimeoutMs,
+} from './ptcTimeout';
 import { Constants } from '@/common';
 
 config();
@@ -18,8 +24,7 @@ config();
 /** Default max round-trips to prevent infinite loops */
 const DEFAULT_MAX_ROUND_TRIPS = 20;
 
-/** Default execution timeout in milliseconds */
-const DEFAULT_TIMEOUT = 60000;
+const DEFAULT_RUN_TIMEOUT_MS = resolveCodeApiRunTimeoutMs();
 
 // ============================================================================
 // Description Components (Single Source of Truth)
@@ -35,7 +40,8 @@ const CORE_RULES = `Rules:
 - Just write code with await—auto-wrapped in async context
 - DO NOT define async def main() or call asyncio.run()
 - Tools are pre-defined—DO NOT write function definitions
-- Only print() output returns to the model`;
+- Only print() output returns to the model
+- timeout caps one sandbox run/replay iteration, not the total multi-round-trip workflow`;
 
 const ADDITIONAL_RULES = `- Generated files are automatically available in /mnt/data/ for subsequent executions
 - Tool names normalized: hyphens→underscores, keywords get \`_tool\` suffix`;
@@ -68,25 +74,25 @@ ${EXAMPLES}
 
 ${CORE_RULES}`;
 
-export const ProgrammaticToolCallingSchema = {
-  type: 'object',
-  properties: {
-    code: {
-      type: 'string',
-      minLength: 1,
-      description: CODE_PARAM_DESCRIPTION,
-    },
-    timeout: {
-      type: 'integer',
-      minimum: 1000,
-      maximum: 300000,
-      default: DEFAULT_TIMEOUT,
-      description:
-        'Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.',
+export function createProgrammaticToolCallingSchema(
+  maxRunTimeoutMs = DEFAULT_RUN_TIMEOUT_MS
+): ProgrammaticToolCallingJsonSchema {
+  return {
+    type: 'object',
+    properties: {
+      code: {
+        type: 'string',
+        minLength: 1,
+        description: CODE_PARAM_DESCRIPTION,
+      },
+      timeout: createCodeApiRunTimeoutSchema(maxRunTimeoutMs),
     },
-  },
-  required: ['code'],
-} as const;
+    required: ['code'],
+  } as const;
+}
+
+export const ProgrammaticToolCallingSchema =
+  createProgrammaticToolCallingSchema();
 
 export const ProgrammaticToolCallingName = Constants.PROGRAMMATIC_TOOL_CALLING;
 
@@ -731,6 +737,7 @@ export function createProgrammaticToolCallingTool(
 ): DynamicStructuredTool {
   const baseUrl = initParams.baseUrl ?? getCodeBaseURL();
   const maxRoundTrips = initParams.maxRoundTrips ?? DEFAULT_MAX_ROUND_TRIPS;
+  const maxRunTimeoutMs = resolveCodeApiRunTimeoutMs(initParams.runTimeoutMs);
   const proxy = initParams.proxy ?? process.env.PROXY;
   const debug = initParams.debug ?? process.env.PTC_DEBUG === 'true';
   const EXEC_ENDPOINT = `${baseUrl}/exec/programmatic`;
@@ -738,7 +745,8 @@ export function createProgrammaticToolCallingTool(
   return tool(
     async (rawParams, config) => {
       const params = rawParams as { code: string; timeout?: number };
-      const { code, timeout = DEFAULT_TIMEOUT } = params;
+      const { code } = params;
+      const timeout = clampCodeApiRunTimeoutMs(params.timeout, maxRunTimeoutMs);
 
       // Extra params injected by ToolNode (follows web_search pattern).
       const toolCall = (config.toolCall ?? {}) as ToolCall &
@@ -873,7 +881,7 @@ export function createProgrammaticToolCallingTool(
     {
       name: Constants.PROGRAMMATIC_TOOL_CALLING,
       description: ProgrammaticToolCallingDescription,
-      schema: ProgrammaticToolCallingSchema,
+      schema: createProgrammaticToolCallingSchema(maxRunTimeoutMs),
       responseFormat: Constants.CONTENT_AND_ARTIFACT,
     }
   );

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) */