Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🥽 feat: Configure Attached Defaults and Honor Skill Read Ranges (#16540)

lia-by-librechat[bot]59b772f132ef
diff --git a/api/server/services/Files/Code/__tests__/process-traversal.spec.js b/api/server/services/Files/Code/__tests__/process-traversal.spec.js
index 99404f5404..b7ff244611 100644
--- a/api/server/services/Files/Code/__tests__/process-traversal.spec.js
+++ b/api/server/services/Files/Code/__tests__/process-traversal.spec.js
@@ -22,6 +22,7 @@ jest.mock('@librechat/api', () => {
const https = require('https');
return {
processCodeOutput: jest.requireActual('@librechat/api').processCodeOutput,
+ createSandboxTextReader: jest.requireActual('@librechat/api').createSandboxTextReader,
resolveDownloadPath: (file) => file.storageKey || file.filepath,
logAxiosError: jest.fn(),
getBasePath: jest.fn(() => ''),
diff --git a/api/server/services/Files/Code/process.js b/api/server/services/Files/Code/process.js
index 2f1afdbf2f..a50987755c 100644
--- a/api/server/services/Files/Code/process.js
+++ b/api/server/services/Files/Code/process.js
@@ -17,6 +17,7 @@ const {
isMissingSandboxPathError,
parseSandboxImageChunk,
readWindowedSandboxImage,
+ createSandboxTextReader,
createCodeApiRateLimitBudget,
codeServerHttpAgent,
codeServerHttpsAgent,
@@ -1641,7 +1642,10 @@ module.exports = {
writeWorkspaceFile,
previewWorkspaceEdit,
editWorkspaceFile,
- readSandboxFile,
+ readSandboxFile: createSandboxTextReader({
+ readFile: readSandboxFile,
+ readBytes: readSandboxImage,
+ }),
readSandboxImage,
writeSandboxFile,
runPreviewFinalize,
diff --git a/api/server/services/Files/Code/process.spec.js b/api/server/services/Files/Code/process.spec.js
index c6969d7dc6..4257741ae9 100644
--- a/api/server/services/Files/Code/process.spec.js
+++ b/api/server/services/Files/Code/process.spec.js
@@ -65,6 +65,7 @@ const passthroughWithTimeout = async (promise) => promise;
jest.mock('@librechat/api', () => {
return {
processCodeOutput: jest.requireActual('@librechat/api').processCodeOutput,
+ createSandboxTextReader: jest.requireActual('@librechat/api').createSandboxTextReader,
prepareCodeOutputBufferForInspection:
jest.requireActual('@librechat/api').prepareCodeOutputBufferForInspection,
getCodeFileContextLine: jest.requireActual('@librechat/api').getCodeFileContextLine,
@@ -2596,6 +2597,193 @@ describe('Code Process', () => {
});
});
+ describe('complete text for ranged reads', () => {
+ beforeEach(() => {
+ const actual = jest.requireActual('@librechat/api');
+ require('@librechat/api').readWindowedSandboxImage.mockImplementation(
+ actual.readWindowedSandboxImage,
+ );
+ mockParseSandboxImageChunk.mockImplementation(actual.parseSandboxImageChunk);
+ });
+ afterEach(() => {
+ require('@librechat/api').readWindowedSandboxImage.mockImplementation(({ readChunk }) =>
+ readChunk({ code: 'read-one-window' }),
+ );
+ mockParseSandboxImageChunk.mockImplementation((response) => response);
+ mockAxios.mockReset();
+ });
+
+ const fullText = Array.from(
+ { length: 900 },
+ (_, i) => `${String(i + 1).padStart(4, '0')}: ${'x'.repeat(93)}`,
+ ).join('\n');
+
+ function cappedExecResponse(code, content = fullText, cap = 65_536) {
+ let stdout;
+ if (code.startsWith('cat ')) stdout = content;
+ else {
+ const payload = /payload = ("[^"\n]+")/.exec(code);
+ if (!payload) throw new Error('Expected the production bounded reader script');
+ const { offset, chunk, limit } = JSON.parse(
+ Buffer.from(JSON.parse(payload[1]), 'base64').toString('utf8'),
+ );
+ const bytes = Buffer.from(content);
+ const window = bytes.subarray(offset, offset + chunk);
+ stdout =
+ JSON.stringify(
+ bytes.length > limit
+ ? { too_large: true, bytes: bytes.length }
+ : { total: bytes.length, n: window.length, b64: window.toString('base64') },
+ ) + '\n';
+ }
+ const overflow = stdout.length > cap;
+ return {
+ data: {
+ stdout: stdout.slice(0, cap),
+ stderr: overflow ? 'Output limit exceeded' : '',
+ status: overflow ? 'OL' : 'success',
+ },
+ };
+ }
+
+ it('retrieves the complete 900-line text before the handler selects line 850', async () => {
+ const actual = jest.requireActual('@librechat/api');
+ const { readWindowedSandboxImage } = require('@librechat/api');
+ readWindowedSandboxImage.mockImplementationOnce(actual.readWindowedSandboxImage);
+ mockParseSandboxImageChunk.mockImplementation(actual.parseSandboxImageChunk);
+ mockAxios.mockImplementation(async ({ data }) => cappedExecResponse(data.code));
+ const result = await readSandboxFile({
+ file_path: '/mnt/data/catalogue.txt',
+ maxBytes: 262_144,
+ });
+ expect(result.content).toBe(fullText);
+ expect(result.complete).toBe(true);
+ expect(mockAxios.mock.calls.length).toBeGreaterThan(1);
+ const handler = actual.createToolExecuteHandler({
+ loadTools: async () => ({ loadedTools: [], configurable: { codeEnvAvailable: true } }),
+ readSandboxFile: async () => result,
+ });
+ const [page] = await new Promise((resolve, reject) =>
+ handler.handle('on_tool_execute', {
+ toolCalls: [
+ {
+ id: 'capped-range',
+ name: 'read_file',
+ args: { path: '/mnt/data/catalogue.txt', start_line: 850, max_lines: 1 },
+ },
+ ],
+ resolve,
+ reject,
+ }),
+ );
+ expect(page.status).toBe('success');
+ expect(page.content).toContain('850 | 0850: ');
+ expect(page.content).toContain('start_line 851');
+ });
+ it('still filters protected text beyond the stdout prefix before serving a clean range', async () => {
+ const actual = jest.requireActual('@librechat/api');
+ const content = fullText + '\nPROTECTED-TAIL';
+ mockAxios.mockImplementation(async ({ data }) => cappedExecResponse(data.code, content));
+ const handler = actual.createToolExecuteHandler({
+ loadTools: async () => ({
+ loadedTools: [],
+ configurable: {
+ codeEnvAvailable: true,
+ req: {
+ config: {
+ filters: {
+ files: {
+ pii: {
+ fields: ['content'],
+ starterPatterns: [],
+ customPatterns: [
+ { id: 'protected', label: 'protected', regex: 'PROTECTED-TAIL' },
+ ],
+ },
+ },
+ },
+ },
+ },
+ },
+ }),
+ readSandboxFile,
+ });
+ const [page] = await new Promise((resolve, reject) =>
+ handler.handle('on_tool_execute', {
+ toolCalls: [
+ {
+ id: 'filtered-full-read',
+ name: 'read_file',
+ args: { path: '/mnt/data/catalogue.txt', max_lines: 1 },
+ },
+ ],
+ resolve,
+ reject,
+ }),
+ );
+ expect(page.status).toBe('error');
+ expect(page.errorMessage).toContain('content_filter_block');
+ expect(page.content).toBe('');
+ });
+
+ it('narrows a smaller runner cap without accepting its incomplete stdout', async () => {
+ mockAxios.mockImplementation(async ({ data }) =>
+ cappedExecResponse(data.code, fullText, 16_384),
+ );
+ const result = await readSandboxFile({
+ file_path: '/mnt/data/catalogue.txt',
+ codeApiBaseUrl: 'https://small-text.example.com',
+ maxBytes: 262_144,
+ });
+ expect(result).toEqual({ content: fullText, complete: true });
+ expect(mockAxios.mock.calls.length).toBeGreaterThan(2);
+ });
+
+ it('refuses oversized files without transferring a prefix', async () => {
+ mockAxios.mockImplementation(async ({ data }) =>
+ cappedExecResponse(data.code, 'x'.repeat(262_145)),
+ );
+ const result = await readSandboxFile({
+ file_path: '/mnt/data/catalogue.txt',
+ maxBytes: 262_144,
+ });
+ expect(result).toEqual({ tooLarge: true, reason: 'size', bytes: 262_145 });
+ expect(mockAxios).toHaveBeenCalledTimes(1);
+ });
+
+ it('forwards the execution identity and cancellation signal on every chunk', async () => {
+ mockAxios.mockImplementation(async ({ data }) => cappedExecResponse(data.code));
+ const controller = new AbortController();
+ const files = [{ id: 'file-a', name: 'catalogue.txt', session_id: 'session-a' }];
+ const params = {
+ file_path: '/mnt/data/catalogue.txt',
+ maxBytes: 262_144,
+ session_id: 'session-a',
+ runtime_session_hint: 'runtime-a',
+ codeApiBaseUrl: 'https://stateful-code.example.com',
+ executionProfile: 'stateful',
+ bridgeWorkerId: 'worker-a',
+ files,
+ req: mockReq,
+ signal: controller.signal,
+ };
+ const result = await readSandboxFile(params);
+ expect(result.complete).toBe(true);
+ for (const [call] of mockAxios.mock.calls) {
+ expect(call).toMatchObject({
+ url: 'https://stateful-code.example.com/exec',
+ signal: controller.signal,
+ data: { session_id: 'session-a', runtime_session_hint: 'runtime-a', files },
+ headers: {
+ 'X-CodeAPI-Expected-Profile': 'stateful',
+ 'X-LibreChat-Code-Worker-ID': 'worker-a',
+ },
+ });
+ }
+ expect(getCodeApiAuthHeaders).toHaveBeenCalledWith(mockReq, 'worker-a');
+ });
+ });
+
describe('response handling', () => {
it('returns { content: stdout } on success', async () => {
mockAxios.mockResolvedValueOnce({
diff --git a/api/server/services/ToolService.js b/api/server/services/ToolService.js
index 5a85e7ff22..b426000b5a 100644
--- a/api/server/services/ToolService.js
+++ b/api/server/services/ToolService.js
@@ -2351,6 +2351,8 @@ async function loadToolsForExecution({
codeExecutionContext.codeEnvironmentConfigSchema,
codeExecutionContext.codeWorkspace?.maxCommandTimeoutMs,
),
+ defaultTimeoutMs:
+ codeExecutionContext.codeEnvironmentConfigSchema?.limits?.defaultCommandTimeoutMs,
maxQueueWaitMs: resolveAttachedWorkspaceQueueWaitMs(
codeExecutionContext.codeEnvironmentConfigSchema,
),
diff --git a/api/server/services/__tests__/ToolService.spec.js b/api/server/services/__tests__/ToolService.spec.js
index aa7cdef494..238c297b9f 100644
--- a/api/server/services/__tests__/ToolService.spec.js
+++ b/api/server/services/__tests__/ToolService.spec.js
@@ -3059,6 +3059,7 @@ describe('ToolService - Action Capability Gating', () => {
codeEnvironmentConfigSchema: {
limits: {
maxCommandTimeoutMs: 80_000,
+ defaultCommandTimeoutMs: 60_000,
maxQueueWaitMs: 0,
maxRequestTimeoutMs: 90_000,
minCommandAdmissionMs: 15_000,
@@ -3090,6 +3091,7 @@ describe('ToolService - Action Capability Gating', () => {
workspaceId: 'project-a',
gitIdentity: { name: 'LibreChat Agent', email: '[email protected]' },
maxTimeoutMs: 65_000,
+ defaultTimeoutMs: 60_000,
maxQueueWaitMs: 0,
codeApiMaxRetryWaitMs: 0,
maxRequestTimeoutMs: 90_000,
diff --git a/librechat.example.yaml b/librechat.example.yaml
index ddd55f2c1b..226f3d5431 100644
--- a/librechat.example.yaml
+++ b/librechat.example.yaml
@@ -818,6 +818,17 @@ endpoints:
# # Maximum Bash execution budget the model may request per call.
# # Omit to preserve the historical 30-second limit. Hard cap: 300000.
# maxCommandTimeoutMs: 120000
+ # # Foreground Bash default when timeoutMs is omitted. Omit to keep 30000.
+ # # Clamped to the effective admin, worker, and verified HTTP ceilings.
+ # # Background calls still default to the effective maximum.
+ # # Programmatic Bash uses this only when timeout is omitted; explicit
+ # # values keep the same negotiated ceiling. Its SDK has a 1000 ms floor
+ # # and cannot run under a smaller ceiling; use bash_tool for those budgets.
+ # # defaultCommandTimeoutMs: 60000
+ # # Attached read_file window when max_lines is omitted. Omit to keep 200.
+ # # Valid range: 1–500 lines; the existing byte budget still applies.
+ # # defaultReadFileLines: 500
+ # # New strict fields require all LibreChat API replicas to be updated first.
# # Optional total HTTP budget per workspace tool call, including
# # admission, retries, worst-case execution, settlement, and delivery.
# # Do NOT enable until every LibreChat API replica recognizes this
diff --git a/packages/api/src/agents/__tests__/skills.test.ts b/packages/api/src/agents/__tests__/skills.test.ts
index 25c761a28a..7fda03560f 100644
--- a/packages/api/src/agents/__tests__/skills.test.ts
+++ b/packages/api/src/agents/__tests__/skills.test.ts
@@ -1310,6 +1310,38 @@ describe('injectSkillCatalog', () => {
expect(definedNames).not.toContain('skill');
});
+ it('carries attached defaults when the skill catalog registers tools first', async () => {
+ const listSkillsByAccess = buildPager([[makeSkill('attached-defaults')]]);
+ const result = await injectSkillCatalog(
+ baseParams({
+ listSkillsByAccess,
+ codeEnvAvailable: true,
+ workspaceTools: true,
+ workspaceOperations: new Set(['read_file', 'execute_command']),
+ workspaceCommandTimeoutMaxMs: 80_000,
+ workspaceCommandTimeoutDefaultMs: 60_000,
+ workspaceReadFileDefaultLines: 500,
+ }),
+ );
+ expect(
+ result.toolDefinitions?.find(({ name }) => name === 'read_file')?.parameters,
+ ).toMatchObject({
+ properties: {
+ max_lines: { maximum: 500, description: expect.stringContaining('Defaults to 500') },
+ },
+ });
+ expect(
+ result.toolDefinitions?.find(({ name }) => name === 'bash_tool')?.parameters,
+ ).toMatchObject({
+ properties: {
+ timeoutMs: {
+ maximum: 80_000,
+ description: expect.stringContaining('Defaults to 60000 for foreground calls'),
+ },
+ },
+ });
+ });
+
it('registers bash_tool with the tool-output reference syntax guide when codeEnvAvailable', async () => {
/**
* Symmetry check with `initializeAgent`'s call: `injectSkillCatalog`
diff --git a/packages/api/src/agents/handlers.spec.ts b/packages/api/src/agents/handlers.spec.ts
index 09a3bb7c86..c9aed0897d 100644
--- a/packages/api/src/agents/handlers.spec.ts
+++ b/packages/api/src/agents/handlers.spec.ts
@@ -7212,6 +7212,345 @@ describe('createToolExecuteHandler', () => {
});
});
+ describe('read_file explicit skill text ranges', () => {
+ const sources = ['body', 'cached', 'streamed', 'sandbox'] as const;
+ const text = Array.from({ length: 660 }, (_, i) => `catalogue line ${i + 1}`).join('\n');
+
+ function readFixture(source: (typeof sources)[number], content = text, req?: never) {
+ const paths = {
+ body: 'skills/codegraph/SKILL.md',
+ cached: 'skills/codegraph/references/shapes.sql',
+ streamed: 'skills/codegraph/references/shapes.sql',
+ sandbox: '/mnt/data/catalogue.sql',
+ };
+ const path = paths[source];
+ const getSkillByName = jest.fn(async () => ({
+ _id: '507f1f77bcf86cd799439011' as unknown as never,
+ name: 'codegraph',
+ body: content,
+ fileCount: 1,
+ version: 1,
+ }));
+ const getSkillFileByPath = jest.fn(async () => ({
+ file_id: 'revision-a',
+ mimeType: 'text/plain',
+ bytes: Buffer.byteLength(content),
+ filepath: '/storage/codegraph/shapes.sql',
+ source: 'local',
+ relativePath: 'references/shapes.sql',
+ ...(source === 'cached' ? { content, isBinary: false } : {}),
+ }));
+ const getDownloadStream = jest.fn(async () => Readable.from([Buffer.from(content)]));
+ const updateSkillFileContent = jest.fn(async () => undefined);
+ const readSandboxFile: NonNullable<ToolExecuteOptions['readSandboxFile']> = jest.fn(
+ async ({ maxBytes }) => {
+ if (maxBytes != null && Buffer.byteLength(content) > maxBytes) {
+ return {
+ tooLarge: true as const,
+ reason: 'size' as const,
+ bytes: Buffer.byteLength(content),
+ };
+ }
+ return { content, ...(maxBytes == null ? {} : { complete: true as const }) };
+ },
+ );
+ const handler = createToolExecuteHandler({
+ loadTools: async () => ({
+ loadedTools: [],
+ configurable: {
+ req: req ?? { user: { id: 'user-1' }, config: {} },
+ accessibleSkillIds: skillsInScope(),
+ activeSkillNames: new Set(['codegraph']),
+ codeEnvAvailable: source === 'sandbox',
+ },
+ }),
+ getSkillByName,
+ getSkillFileByPath,
+ getStrategyFunctions: () => ({ getDownloadStream }),
+ updateSkillFileContent,
+ readSandboxFile,
+ });
+ const read = async (range: { start_line?: number; max_lines?: number } = {}) => {
+ const [result] = await invokeHandler(handler, [
+ { id: 'ranged-read', name: Constants.READ_FILE, args: { path, ...range } },
+ ]);
+ return result;
+ };
+ return { path, read, getDownloadStream, updateSkillFileContent };
+ }
+
+ it.each(sources)(
+ 'returns exactly lines 100–159 with continuation for %s text',
+ async (source) => {
+ const { read, path, updateSkillFileContent } = readFixture(source);
+ const result = await read({ start_line: 100, max_lines: 60 });
+ expect(result.status).toBe('success');
+ const numbered = String(result.content)
+ .split('\n')
+ .filter((line) => /^\s*\d+ \| /.test(line));
+ expect(numbered).toEqual(
+ Array.from({ length: 60 }, (_, i) => `${100 + i} | catalogue line ${100 + i}`),
+ );
+ expect(result.content).toContain(
+ `call read_file again with path "${path}" and start_line 160`,
+ );
+ expect(result.content).not.toContain('660 | catalogue line 660');
+ if (source === 'streamed') {
+ expect(updateSkillFileContent).toHaveBeenCalledWith(
+ expect.anything(),
+ 'references/shapes.sql',
+ { content: text, isBinary: false },
+ 'revision-a',
+ );
+ }
+ },
+ );
+
+ it.each(sources)('preserves a no-range full read for %s text', async (source) => {
+ const { read, path } = readFixture(source);
+ const result = await read();
+ const numbered = text
+ .split('\n')
+ .map((line, i) => `${String(i + 1).padStart(3, ' ')} | ${line}`)
+ .join('\n');
+ let header = '';
+ if (source === 'body') header = `File: ${path}\n\n`;
+ else if (source !== 'sandbox')
+ header = `File: ${path} (${Buffer.byteLength(text)} bytes)\n\n`;
+ expect(result.content).toBe(header + numbered);
+ expect(result.content).not.toContain('more content');
+ });
+
+ it.each(sources)(
+ 'uses 200 lines only when %s text supplies a partial range',
+ async (source) => {
+ const { read } = readFixture(source);
+ const startOnly = await read({ start_line: 100 });
+ expect(
+ String(startOnly.content)
+ .split('\n')
+ .filter((line) => /^\s*\d+ \| /.test(line)),
+ ).toHaveLength(200);
+ expect(startOnly.content).toContain('start_line 300');
+ const limitOnly = await read({ max_lines: 2 });
+ expect(limitOnly.content).toContain('1 | catalogue line 1\n2 | catalogue line 2');
+ expect(limitOnly.content).toContain('start_line 3');
+ },
+ );
+
+ it.each(
+ sources.flatMap((source) => [
+ { source, range: { start_line: 0 } },
+ { source, range: { max_lines: 501 } },
+ { source, range: { start_line: 1.5 } },
+ { source, range: { max_lines: -1 } },
+ ]),
+ )('rejects an invalid range for $source: $range', async ({ source, range }) => {
+ const result = await readFixture(source).read(range);
+ expect(result.status).toBe('error');
+ expect(result.errorMessage).toBe(
+ 'start_line must be positive and max_lines must be between 1 and 500.',
+ );
+ });
+
+ it.each(sources)(
+ 'reports the final and beyond-EOF pages without phantom lines for %s text',
+ async (source) => {
+ const { read } = readFixture(source);
+ const last = await read({ start_line: 650, max_lines: 60 });
+ expect(
+ String(last.content)
+ .split('\n')
+ .filter((line) => /^\s*\d+ \| /.test(line)),
+ ).toHaveLength(11);
+ expect(last.content).not.toContain('more content');
+ const beyond = await read({ start_line: 700, max_lines: 60 });
+ expect(beyond.status).toBe('success');
+ expect(beyond.content).not.toMatch(/\d+ \| /);
+ expect(beyond.content).not.toContain('more content');
+ },
+ );
+
+ it.each(['body', 'cached', 'streamed'] as const)(
+ 'blocks the full %s skill text before slicing a clean page',
+ async (source) => {
+ const req = {
+ user: { id: 'user-1' },
+ config: {
+ filters: {
+ skills: {
+ pii: {
+ fields: ['instructions', 'file_text'],
+ starterPatterns: [],
+ customPatterns: [{ id: 'secret', label: 'secret', regex: 'PROTECTED-SECRET' }],
+ },
+ },
+ },
+ },
+ } as never;
+ const result = await readFixture(
+ source,
+ `clean first line\nPROTECTED-SECRET\nlast`,
+ req,
+ ).read({ start_line: 1, max_lines: 1 });
+ expect(result.status).toBe('error');
+ expect(result.errorMessage).toContain('content_filter_block');
+ expect(result.content).not.toContain('clean first line');
+ expect(result.errorMessage).not.toContain('PROTECTED-SECRET');
+ },
+ );
+
+ it.each(['cached', 'streamed', 'sandbox'] as const)(
+ 'blocks full %s file text under the files policy before slicing',
+ async (source) => {
+ const req = {
+ user: { id: 'user-1' },
+ config: {
+ filters: {
+ files: {
+ pii: {
+ fields: ['content'],
+ starterPatterns: [],
+ customPatterns: [{ id: 'secret', label: 'secret', regex: 'PROTECTED-SECRET' }],
+ },
+ },
+ },
+ },
+ } as never;
+ const result = await readFixture(source, `clean first line\nPROTECTED-SECRET`, req).read({
+ max_lines: 1,
+ });
+ expect(result.status).toBe('error');
+ expect(result.errorMessage).toContain('content_filter_block');
+ expect(result.content).not.toContain('clean first line');
+ },
+ );
+
+ it.each(['body', 'cached'] as const)(
+ 'bounds UTF-8 %s range output and continues at the first omitted line',
+ async (source) => {
+ const content = ['skip', '界'.repeat(80_000), '界'.repeat(10_000)].join('\n');
+ const result = await readFixture(source, content).read({ start_line: 2, max_lines: 2 });
+ expect(result.status).toBe('success');
+ expect(result.content).toContain('2 | ');
+ expect(result.content).not.toContain('3 | ');
+ expect(result.content).toContain('truncated at 262144 bytes');
+ expect(result.content).toContain('start_line 3');
+ expect(Buffer.byteLength(String(result.content), 'utf8')).toBeLessThan(262_450);
+ },
+ );
+
+ it.each(['body', 'cached'] as const)(
+ 'does not advertise a non-progressing continuation for an oversized %s line',
+ async (source) => {
+ const result = await readFixture(source, '界'.repeat(100_000)).read({ max_lines: 1 });
+ expect(result.status).toBe('success');
+ expect(result.content).toContain('cannot be paged by line');
+ expect(result.content).not.toContain('call read_file again');
+ expect(result.content).not.toContain('�');
+ },
+ );
+
+ it('leaves skill binary metadata and image artifacts unchanged when range parameters are present', async () => {
+ const image = Buffer.from(
+ 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
+ 'base64',
+ );
+ const bytesByPath = { 'chart.png': image, 'data.bin': Buffer.from([0, 1, 2]) };
+ const handler = createToolExecuteHandler({
+ loadTools: async () => ({
+ loadedTools: [],
+ configurable: {
+ req: { user: { id: 'user-1' }, config: {} },
+ accessibleSkillIds: skillsInScope(),
+ },
+ }),
+ getSkillByName: async () => ({
+ _id: '507f1f77bcf86cd799439011' as unknown as never,
+ name: 'binary-skill',
+ body: '# Binary',
+ fileCount: 2,
+ version: 1,
+ }),
+ getSkillFileByPath: async (_id, relativePath) => ({
+ mimeType: relativePath === 'chart.png' ? 'image/png' : 'application/octet-stream',
+ bytes: bytesByPath[relativePath as keyof typeof bytesByPath].length,
+ isBinary: true,
+ filepath: `/storage/${relativePath}`,
+ source: 'local',
+ relativePath,
+ }),
+ getStrategyFunctions: () => ({
+ getDownloadStream: async (_req, path) =>
+ Readable.from(bytesByPath[path.split('/').pop() as keyof typeof bytesByPath]),
+ }),
+ });
+ for (const path of ['skills/binary-skill/chart.png', 'skills/binary-skill/data.bin']) {
+ const results = await invokeHandler(handler, [
+ { id: 'binary-full', name: Constants.READ_FILE, args: { path } },
+ {
+ id: 'binary-ranged',
+ name: Constants.READ_FILE,
+ args: { path, start_line: 100, max_lines: 60 },
+ },
+ ]);
+ expect(results[1].status).toBe(results[0].status);
+ expect(results[1].content).toEqual(results[0].content);
+ expect(results[1].artifact).toEqual(results[0].artifact);
+ }
+ });
+
+ it('refuses incomplete or oversized sandbox text instead of reporting a false EOF', async () => {
+ const original = text;
+ const readSandboxFile: NonNullable<ToolExecuteOptions['readSandboxFile']> = jest.fn(
+ async () => ({ content: original.slice(0, 100) }),
+ );
+ const handler = createToolExecuteHandler({
+ loadTools: async () => ({ loadedTools: [], configurable: { codeEnvAvailable: true } }),
+ readSandboxFile,
+ });
+ const [result] = await invokeHandler(handler, [
+ {
+ id: 'incomplete-prefix',
+ name: Constants.READ_FILE,
+ args: { path: '/mnt/data/catalogue.txt', start_line: 650, max_lines: 1 },
+ },
+ ]);
+ expect(result.status).toBe('error');
+ expect(result.errorMessage).toContain('retrieval was incomplete');
+ expect(result.content).toBe('');
+ expect(readSandboxFile).toHaveBeenCalledWith(expect.objectContaining({ maxBytes: 262_144 }));
+ const tooLarge = await readFixture('sandbox', 'x'.repeat(262_145)).read({
+ start_line: 100,
+ max_lines: 1,
+ });
+ expect(tooLarge.status).toBe('error');
+ expect(tooLarge.errorMessage).toContain('retrieved completely');
+ expect(tooLarge.content).toBe('');
+ });
+
+ it('preserves streamed oversized-file metadata and avoids a download even with an explicit range', async () => {
+ const { read, getDownloadStream } = readFixture('streamed', 'x'.repeat(262_145));
+ for (const range of [{}, { start_line: 1, max_lines: 1 }]) {
+ expect((await read(range)).content).toContain('too large to read directly');
+ }
+ expect(getDownloadStream).not.toHaveBeenCalled();
+ });
+
+ it.each(sources)(
+ 'keeps blank lines and trailing-newline numbering unchanged for a no-range %s read',
+ async (source) => {
+ const { read } = readFixture(source, 'first\n\nlast\n');
+ const full = await read();
+ expect(full.content).toContain('1 | first\n2 | \n3 | last\n4 | ');
+ const page = await read({ start_line: 2, max_lines: 2 });
+ expect(page.content).toContain('2 | \n3 | last');
+ expect(page.content).not.toContain('4 | ');
+ expect(page.content).not.toContain('more content');
+ },
+ );
+ });
+
describe('read_file sandbox fallback (code-env paths + non-skill segments)', () => {
function makeReadFileHandler(params: {
codeEnvAvailable?: boolean;
@@ -7319,6 +7658,73 @@ describe('createToolExecuteHandler', () => {
});
});
+ it.each([200, 500])(
+ 'reads the configured %i-line window and preserves explicit pagination',
+ async (defaultReadFileLines) => {
+ const lines = Array.from({ length: 450 }, (_, i) => `line ${i + 1}`);
+ const readWorkspaceFile = jest.fn<
+ ReturnType<NonNullable<ToolExecuteOptions['readWorkspaceFile']>>,
+ Parameters<NonNullable<ToolExecuteOptions['readWorkspaceFile']>>
+ >(async ({ start_line = 1, max_lines = 200 }) => {
+ const selected = lines.slice(start_line - 1, start_line - 1 + max_lines);
+ const endLine = start_line + selected.length - 1;
+ return {
+ protocolVersion: 1,
+ operation: 'read_file',
+ workspaceId: 'primary',
+ path: 'notes.txt',
+ content: selected.join('\n'),
+ startLine: start_line,
+ endLine,
+ truncated: endLine < lines.length,
+ ...(endLine < lines.length ? { nextStartLine: endLine + 1 } : {}),
+ };
+ });
+ const handler = makeReadFileHandler({
+ codeEnvAvailable: true,
+ readWorkspaceFile,
+ codeExecutionContext: {
+ baseUrl: 'https://code.example.com/v1',
+ codeSessionKey: 'execute_code:stateful:attached',
+ executionProfile: 'stateful',
+ environmentType: 'attached',
+ statefulSessions: true,
+ codeEnvironmentConfigSchema: { limits: { defaultReadFileLines } },
+ },
+ });
+ const [result] = await invokeHandler(handler, [
+ {
+ id: 'call_configured_window',
+ name: Constants.READ_FILE,
+ args: { path: 'workspace/notes.txt' },
+ },
+ ]);
+ expect(readWorkspaceFile).toHaveBeenCalledWith(
+ expect.objectContaining({ start_line: 1, max_lines: defaultReadFileLines }),
+ );
+ expect(result.status).toBe('success');
+ if (defaultReadFileLines === 500) {
+ expect(result.content).toContain('450 | line 450');
+ expect(result.content).not.toContain('more content');
+ } else {
+ expect(result.content).toContain('200 | line 200');
+ expect(result.content).toContain('start_line 201');
+ }
+ const [page] = await invokeHandler(handler, [
+ {
+ id: 'call_explicit_window',
+ name: Constants.READ_FILE,
+ args: { path: 'workspace/notes.txt', start_line: 10, max_lines: 2 },
+ },
+ ]);
+ expect(readWorkspaceFile).toHaveBeenLastCalledWith(
+ expect.objectContaining({ start_line: 10, max_lines: 2 }),
+ );
+ expect(page.content).toContain('10 | line 10\n11 | line 11');
+ expect(page.content).toContain('start_line 12');
+ },
+ );
+
it('forwards the run abort signal to attached workspace reads', async () => {
const readWorkspaceFile = jest.fn(async () => ({
protocolVersion: 1 as const,
diff --git a/packages/api/src/agents/handlers.ts b/packages/api/src/agents/handlers.ts
index aef42fda5b..670296a101 100644
--- a/packages/api/src/agents/handlers.ts
+++ b/packages/api/src/agents/handlers.ts
@@ -8,6 +8,8 @@ import {
} from '@librechat/data-schemas';
import {
AGENT_BACKGROUND_COMPLETION_RESULT_MAX_CHARS_DEFAULT,
+ CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES,
+ CODE_ENVIRONMENT_READ_FILE_HARD_MAX_LINES,
hasActivePiiFields,
hasActivePiiPatterns,
hasToolCallErrorPrefix,
@@ -53,6 +55,7 @@ import type {
import type { SkillFileRecord, PrimeSkillFilesResult } from './skillFiles';
import type { ArtifactDeliveryFailure } from '~/files/code';
import type { BackgroundToolResultState } from './harvest';
+import type { SandboxTextReader } from '~/files/code/text';
import type { WorkspaceEditMatching } from '~/code/edits';
import type { CodeExecutionContext } from './execution';
import type { TextContentFragment } from '~/protection';
@@ -99,6 +102,12 @@ import {
isCodeSessionToolName,
isFileResourceToolName,
} from './tools';
+import {
+ resolveAttachedWorkspaceReadFileLines,
+ WorkspaceToolHttpError,
+ WORKSPACE_EDIT_MAX_COUNT,
+ WORKSPACE_WRITE_MAX_BYTES,
+} from '~/code/workspace';
import {
BACKGROUND_TASK_ABORT_GRACE_MS,
BACKGROUND_TASK_SHUTDOWN_MESSAGE,
@@ -122,11 +131,6 @@ import {
contentFilterModelBoundBlockResponse,
isContentFilterError,
} from '~/middleware/contentFilter';
-import {
- WorkspaceToolHttpError,
- WORKSPACE_EDIT_MAX_COUNT,
- WORKSPACE_WRITE_MAX_BYTES,
-} from '~/code/workspace';
import {
hasIntentArg,
stripIntentArg,
@@ -685,29 +689,8 @@ export interface ToolExecuteOptions {
maxRequestTimeoutMs?: number;
deadlineAtMs?: number;
}) => Promise<WorkspaceEditResult>;
- /**
- * Reads a code-execution sandbox file by shelling `cat` through the
- * sandbox `/exec` endpoint. The host implementation supplies the
- * codeapi base URL + auth and forwards the seeded `session_id` and
- * `files` so the read lands in the same sandbox session that holds
- * the agent's prior-turn artifacts. Returns `null` when codeapi is
- * unavailable; throws on transport errors so the handler can surface
- * a meaningful error message to the model.
- */
- readSandboxFile?: (params: {
- file_path: string;
- session_id?: string;
- files?: SandboxFileRef[];
- /** Per-conversation stateful runtime-session hint (thread_id); forwarded so a
- * host file op that is the first sandbox call joins the same runtime session
- * as bash_tool instead of the Code API's default session. */
- runtime_session_hint?: string;
- codeApiBaseUrl?: string;
- executionProfile?: CodeExecutionContext['executionProfile'];
- bridgeWorkerId?: string;
- executionRouteKey?: string;
- req?: ServerRequest;
- }) => Promise<{ content: string } | null>;
+ /** Bounded reads return complete text; omitted maxBytes retains the legacy stdout path. */
+ readSandboxFile?: SandboxTextReader;
/**
* Reads a small image file out of the code-execution sandbox as base64 so
* `read_file` can surface it to vision-capable models. The `readSandboxFile`
@@ -1055,6 +1038,97 @@ function addLineNumbers(content: string, startLine = 1): string {
.join('\n');
}
+type ReadFileRangeArguments = { start_line?: number; max_lines?: number };
+type ReadFileRange = { startLine: number; maxLines: number };
+const READ_FILE_RANGE_ERROR =
+ 'start_line must be positive and max_lines must be between 1 and 500.';
+
+function resolveReadFileRange(
+ args: ReadFileRangeArguments,
+ defaultMaxLines = CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES,
+): ReadFileRange | null {
+ const startLine = args.start_line ?? 1;
+ const maxLines = args.max_lines ?? defaultMaxLines;
+ return Number.isSafeInteger(startLine) &&
+ startLine >= 1 &&
+ Number.isSafeInteger(maxLines) &&
+ maxLines >= 1 &&
+ maxLines <= CODE_ENVIRONMENT_READ_FILE_HARD_MAX_LINES
+ ? { startLine, maxLines }
+ : null;
+}
+
+/** Full local files are sliced once; a worker page is already offset and bounded. */
+function formatReadFileText(
+ content: string,
+ path: string,
+ range?: ReadFileRange,
+ page?: { startLine: number; nextStartLine?: number },
+): string {
+ let payload = content;
+ const startLine = page?.startLine ?? range?.startLine ?? 1;
+ let nextStartLine = page?.nextStartLine;
+ if (range != null && page == null) {
+ let start = 0;
+ for (let line = 1; line < range.startLine; line++) {
+ const newline = content.indexOf('\n', start);
+ if (newline < 0) return '';
+ start = newline + 1;
+ }
+ if (start >= content.length) return '';
+ let end = content.length;
+ let cursor = start;
+ for (let count = 1; count <= range.maxLines; count++) {
+ const newline = content.indexOf('\n', cursor);
+ if (newline < 0) break;
+ if (count === range.maxLines || newline === content.length - 1) {
+ end = newline;
+ if (newline < content.length - 1) nextStartLine = startLine + count;
+ break;
+ }
+ cursor = newline + 1;
+ }
+ payload = content.slice(start, end);
+ }
+
+ let locallyTruncated = false;
+ let localNextStartLine: number | undefined;
+ if ((range != null || page != null) && Buffer.byteLength(payload, 'utf8') > MAX_READABLE_BYTES) {
+ payload = truncateUtf8(payload, MAX_READABLE_BYTES);
+ locallyTruncated = true;
+ const lastCompleteLine = payload.lastIndexOf('\n');
+ if (lastCompleteLine >= 0) {
+ payload = payload.slice(0, lastCompleteLine);
+ localNextStartLine = startLine + payload.split('\n').length;
+ }
+ }
+ let numbered = addLineNumbers(payload, startLine);
+ if (locallyTruncated) {
+ numbered +=
+ localNextStartLine != null
+ ? `\n\n[truncated at ${MAX_READABLE_BYTES} bytes; more content is available; call read_file again with path "${path}" and start_line ${localNextStartLine}]`
+ : `\n\n[the line was truncated at ${MAX_READABLE_BYTES} bytes and cannot be paged by line]`;
+ } else if (nextStartLine != null) {
+ numbered += `\n\n[more content is available; call read_file again with path "${path}" and start_line ${nextStartLine}]`;
+ }
+ return numbered;
+}
+
+function localTextReadResult(
+ tc: ToolCallRequest,
+ path: string,
+ content: string,
+ header = '',
+): ToolExecuteResult {
+ const args = tc.args as ReadFileRangeArguments;
+ const range =
+ args.start_line === undefined && args.max_lines === undefined
+ ? undefined
+ : resolveReadFileRange(args);
+ if (range === null) return errorResult(tc, READ_FILE_RANGE_ERROR);
+ return successResult(tc, header + formatReadFileText(content, path, range));
+}
+
type AuthoringSkill = NonNullable<
Awaited<ReturnType<NonNullable<ToolExecuteOptions['getSkillByName']>>>
>;
@@ -2529,6 +2603,10 @@ async function handleSandboxFileFallback(
};
}
+ const rangeArgs = tc.args as ReadFileRangeArguments;
+ const ranged = rangeArgs.start_line !== undefined || rangeArgs.max_lines !== undefined;
+ if (ranged && resolveReadFileRange(rangeArgs) == null)
+ return errorResult(tc, READ_FILE_RANGE_ERROR);
const ctx = tc.codeSessionContext as SandboxSessionContext | undefined;
try {
const result = await readSandboxFile({
@@ -2537,7 +2615,20 @@ async function handleSandboxFileFallback(
files: ctx?.files,
...codeExecutionRequestParams(codeExecutionContext),
...(req ? { req } : {}),
+ ...(ranged ? { maxBytes: MAX_READABLE_BYTES, ...(signal ? { signal } : {}) } : {}),
});
+ if (result != null && 'tooLarge' in result) {
+ return errorResult(
+ tc,
+ `Sandbox file could not be retrieved completely within the ${MAX_READABLE_BYTES}-byte read budget. Use bash_tool to inspect it.`,
+ );
+ }
+ if (ranged && result != null && result.complete !== true) {
+ return errorResult(
+ tc,
+ 'Sandbox text retrieval was incomplete. Use bash_tool to inspect the file.',
+ );
+ }
if (!result || result.content == null) {
return {
toolCallId: tc.id,
@@ -2567,13 +2658,18 @@ async function handleSandboxFileFallback(
* and surface the truncation to the model so it can use
* `bash_tool head` / `tail` for the rest.
*/
+ if (ranged) {
+ const rangedResult = localTextReadResult(tc, filePath, result.content);
+ if (rangedResult.status === 'success') onSuccess?.();
+ return rangedResult;
+ }
let payload = result.content;
let truncated = false;
if (payload.length > MAX_READABLE_BYTES) {
payload = payload.slice(0, MAX_READABLE_BYTES);
truncated = true;
}
- let numbered = addLineNumbers(payload);
+ let numbered = formatReadFileText(payload, filePath);
if (truncated) {
numbered += `\n\n[truncated at ${MAX_READABLE_BYTES} bytes — use \`bash_tool\` (e.g. \`head -c\` / \`tail\`) to read the rest of "${filePath}"]`;
}
@@ -2584,6 +2680,7 @@ async function handleSandboxFileFallback(
content: numbered,
};
} catch (error) {
+ if (signal?.aborted === true && isAbortError(error)) throw error;
const message = error instanceof Error ? error.message : String(error);
logger.warn('[handleReadFileCall] Sandbox fallback failed', getSafeErrorMetadata(error));
return {
@@ -2615,8 +2712,10 @@ async function handleWorkspaceFileRead(
const workspaceId = selectedWorkspaceId(codeExecutionContext, 'read_file');
if (!workspaceId) return unavailableWorkspaceOperation(tc, 'read_file');
const args = tc.args as { start_line?: number; max_lines?: number };
- const startLine = args.start_line ?? 1;
- const maxLines = args.max_lines ?? 200;
+ const range = resolveReadFileRange(
+ args,
+ resolveAttachedWorkspaceReadFileLines(codeExecutionContext.codeEnvironmentConfigSchema),
+ );
if (filePath.length === 0) {
return {
toolCallId: tc.id,
@@ -2625,20 +2724,7 @@ async function handleWorkspaceFileRead(
errorMessage: 'A relative path after workspace/ is required.',
};
}
- if (
- !Number.isSafeInteger(startLine) ||
- startLine < 1 ||
- !Number.isSafeInteger(maxLines) ||
- maxLines < 1 ||
- maxLines > 500
- ) {
- return {
- toolCallId: tc.id,
- status: 'error',
- content: '',
- errorMessage: 'start_line must be positive and max_lines must be between 1 and 500.',
- };
- }
+ if (range == null) return errorResult(tc, READ_FILE_RANGE_ERROR);
const filteredName = filteredFileNameResult(tc, req, filePath);
if (filteredName != null) {
return filteredName;
@@ -2652,8 +2738,8 @@ async function handleWorkspaceFileRead(
? { workspace_instance_id: codeExecutionContext.codeWorkspace.workspaceInstanceId }
: {}),
...(codeExecutionContext.codeWorkspace?.linkedWorktrees ? { linked_worktrees: true } : {}),
- start_line: startLine,
- max_lines: maxLines,
+ start_line: range.startLine,
+ max_lines: range.maxLines,
codeApiBaseUrl: codeExecutionContext.baseUrl,
...attachedWorkspaceRequestLimits(codeExecutionContext),
executionProfile: codeExecutionContext.executionProfile,
@@ -2675,32 +2761,15 @@ async function handleWorkspaceFileRead(
errorMessage: `"${filePath}" appears to be a binary file and cannot be read as text.`,
};
}
- let payload = result.content;
- let locallyTruncated = false;
- let localNextStartLine: number | undefined;
- if (Buffer.byteLength(payload, 'utf8') > MAX_READABLE_BYTES) {
- payload = truncateUtf8(payload, MAX_READABLE_BYTES);
- locallyTruncated = true;
- const lastCompleteLine = payload.lastIndexOf('\n');
- if (lastCompleteLine >= 0) {
- payload = payload.slice(0, lastCompleteLine);
- localNextStartLine = result.startLine + payload.split('\n').length;
- }
- }
- let numbered = addLineNumbers(payload, result.startLine);
- if (locallyTruncated) {
- numbered +=
- localNextStartLine != null
- ? `\n\n[truncated at ${MAX_READABLE_BYTES} bytes; more content is available; call read_file again with path "workspace/${filePath}" and start_line ${localNextStartLine}]`
- : `\n\n[the line was truncated at ${MAX_READABLE_BYTES} bytes and cannot be paged by line]`;
- } else if (result.truncated && result.nextStartLine != null) {
- numbered += `\n\n[more content is available; call read_file again with path "workspace/${filePath}" and start_line ${result.nextStartLine}]`;
- }
- return {
- toolCallId: tc.id,
- status: 'success',
- content: numbered,
- };
+ return successResult(
+ tc,
+ formatReadFileText(result.content, `workspace/${filePath}`, undefined, {
+ startLine: result.startLine,
+ ...(result.truncated && result.nextStartLine != null
+ ? { nextStartLine: result.nextStartLine }
+ : {}),
+ }),
+ );
} catch (error) {
if (error instanceof WorkspaceToolHttpError) throw error;
if (signal?.aborted === true && isAbortError(error)) throw error;
@@ -3080,6 +3149,12 @@ async function loadSandboxTextForAuthoring({
...codeExecutionRequestParams(codeExecutionContext),
...(req ? { req } : {}),
});
+ if (result != null && 'tooLarge' in result) {
+ return {
+ status: 'error',
+ message: 'Sandbox file could not be retrieved completely. Use bash_tool to inspect it.',
+ };
+ }
if (!result || result.content == null) {
return {
status: 'error',
@@ -5121,11 +5196,7 @@ async function handleReadFileCall(
if (filtered != null) {
return filtered;
}
- return {
- toolCallId: tc.id,
- status: 'success',
- content: `File: ${args.path}\n\n${addLineNumbers(skill.body)}`,
- };
+ return localTextReadResult(tc, args.path, skill.body, `File: ${args.path}\n\n`);
}
/* Bundled skill files are primed into the sandbox under the `skills/`
@@ -5187,11 +5258,12 @@ async function handleReadFileCall(
if (fileFiltered != null) {
return fileFiltered;
}
- return {
- toolCallId: tc.id,
- status: 'success',
- content: `File: ${args.path} (${file.bytes} bytes)\n\n${addLineNumbers(file.content)}`,
- };
+ return localTextReadResult(
+ tc,
+ args.path,
+ file.content,
+ `File: ${args.path} (${file.bytes} bytes)\n\n`,
+ );
}
// Early size check from DB metadata before streaming
@@ -5340,11 +5412,12 @@ async function handleReadFileCall(
};
}
- return {
- toolCallId: tc.id,
- status: 'success',
- content: `File: ${args.path} (${buffer.length} bytes)\n\n${addLineNumbers(text)}`,
- };
+ return localTextReadResult(
+ tc,
+ args.path,
+ text,
+ `File: ${args.path} (${buffer.length} bytes)\n\n`,
+ );
} catch (error) {
return {
toolCallId: tc.id,
diff --git a/packages/api/src/agents/initialize.ts b/packages/api/src/agents/initialize.ts
index 9f277241cb..1fc8862453 100644
--- a/packages/api/src/agents/initialize.ts
+++ b/packages/api/src/agents/initialize.ts
@@ -109,6 +109,10 @@ import {
splitMCPToolKey,
normalizeAgentToolKeys,
} from '~/mcp/utils';
+import {
+ resolveAttachedWorkspaceCommandTimeoutMax,
+ resolveAttachedWorkspaceCommandTimeoutDefault,
+} from '~/code/command';
import {
formatChatProjectInstructions,
hydrateChatProjectContextResources,
@@ -121,8 +125,8 @@ import { assertChatProjectInstructions, ChatProjectResourcesChangedError } from
import { extractAgentContent, extractSkillContent } from '../protection/adapters/submissions';
import { createConfiguredContentInspector, inspectContent } from '../protection/runtime';
import { assertAgentAttachmentLimits, isModelBoundAttachmentFile } from './attachments';
-import { resolveAttachedWorkspaceCommandTimeoutMax } from '~/code/command';
import { assertModelBoundContent } from '../middleware/modelBoundContent';
+import { resolveAttachedWorkspaceReadFileLines } from '~/code/workspace';
import { isImplicitStatefulCodeRouteAvailable } from '../code/config';
import { PARTIAL_RESOLVED_CONVERSATION } from './conversationSymbols';
import { registerMemoryTools, memoryToolUsageGuard } from './memory';
@@ -2172,6 +2176,19 @@ export async function initializeAgent(
trustedCodeExecutionContext.codeWorkspace?.maxCommandTimeoutMs,
)
: undefined;
+ const attachedWorkspaceCommandTimeoutDefaultMs =
+ trustedCodeExecutionContext.environmentType === 'attached'
+ ? resolveAttachedWorkspaceCommandTimeoutDefault(
+ trustedCodeExecutionContext.codeEnvironmentConfigSchema?.limits?.defaultCommandTimeoutMs,
+ attachedWorkspaceCommandTimeoutMaxMs,
+ )
+ : undefined;
+ const attachedWorkspaceReadFileDefaultLines =
+ trustedCodeExecutionContext.environmentType === 'attached'
+ ? resolveAttachedWorkspaceReadFileLines(
+ trustedCodeExecutionContext.codeEnvironmentConfigSchema,
+ )
+ : undefined;
if (
attachedWorkspaceOperations &&
!attachedWorkspaceOperations.has('preview_edit') &&
@@ -2255,6 +2272,8 @@ export async function initializeAgent(
workspaceTools: attachedWorkspaceTools,
workspaceOperations: attachedWorkspaceOperations,
workspaceCommandTimeoutMaxMs: attachedWorkspaceCommandTimeoutMaxMs,
+ workspaceCommandTimeoutDefaultMs: attachedWorkspaceCommandTimeoutDefaultMs,
+ workspaceReadFileDefaultLines: attachedWorkspaceReadFileDefaultLines,
workspaceEnvironment: trustedCodeExecutionContext.codeWorkspace?.environment,
workspaceLinkedWorktrees: trustedCodeExecutionContext.codeWorkspace?.linkedWorktrees,
});
@@ -2308,6 +2327,8 @@ export async function initializeAgent(
workspaceTools: attachedWorkspaceTools,
workspaceOperations: attachedWorkspaceOperations,
workspaceCommandTimeoutMaxMs: attachedWorkspaceCommandTimeoutMaxMs,
+ workspaceCommandTimeoutDefaultMs: attachedWorkspaceCommandTimeoutDefaultMs,
+ workspaceReadFileDefaultLines: attachedWorkspaceReadFileDefaultLines,
});
toolDefinitions = skillReadResult.toolDefinitions;
recordCapabilityToolNames(AgentCapabilities.skills, skillReadResult.toolNames);
@@ -2501,6 +2522,8 @@ export async function initializeAgent(
workspaceOperations: attachedWorkspaceOperations,
userId: user?.id,
workspaceCommandTimeoutMaxMs: attachedWorkspaceCommandTimeoutMaxMs,
+ workspaceCommandTimeoutDefaultMs: attachedWorkspaceCommandTimeoutDefaultMs,
+ workspaceReadFileDefaultLines: attachedWorkspaceReadFileDefaultLines,
workspaceEnvironment: trustedCodeExecutionContext.codeWorkspace?.environment,
workspaceLinkedWorktrees: trustedCodeExecutionContext.codeWorkspace?.linkedWorktrees,
skillStates: params.skillStates,
diff --git a/packages/api/src/agents/skills.ts b/packages/api/src/agents/skills.ts
index f74fee50ea..6b3842af42 100644
--- a/packages/api/src/agents/skills.ts
+++ b/packages/api/src/agents/skills.ts
@@ -440,6 +440,8 @@ export interface InjectSkillCatalogParams {
workspaceOperations?: ReadonlySet<CodeWorkspaceOperation>;
/** Deployment ceiling advertised on attached Bash tool definitions. */
workspaceCommandTimeoutMaxMs?: number;
+ workspaceCommandTimeoutDefaultMs?: number;
+ workspaceReadFileDefaultLines?: number;
workspaceEnvironment?: CodeWorkspaceDescriptor['environment'];
/** The worker runs `.worktrees/<name>` in its own lane; advertise `cwd` routing to the model. */
workspaceLinkedWorktrees?: boolean;
@@ -678,6 +680,8 @@ export async function injectSkillCatalog(
workspaceTools,
workspaceOperations,
workspaceCommandTimeoutMaxMs,
+ workspaceCommandTimeoutDefaultMs,
+ workspaceReadFileDefaultLines,
workspaceEnvironment,
workspaceLinkedWorktrees,
userId,
@@ -865,6 +869,8 @@ export async function injectSkillCatalog(
workspaceTools: workspaceTools === true,
workspaceOperations,
workspaceCommandTimeoutMaxMs,
+ workspaceCommandTimeoutDefaultMs,
+ workspaceReadFileDefaultLines,
workspaceEnvironment,
workspaceLinkedWorktrees,
});
diff --git a/packages/api/src/agents/tools.spec.ts b/packages/api/src/agents/tools.spec.ts
index 1852ea5a1a..685e6ad8ac 100644
--- a/packages/api/src/agents/tools.spec.ts
+++ b/packages/api/src/agents/tools.spec.ts
@@ -13,11 +13,13 @@ jest.mock('@librechat/agents', () => ({
parameters: {
type: 'object',
properties: {
+ intent: { type: 'string', description: 'SDK read intent' },
path: {
type: 'string',
description: 'For skill files: "{skillName}/{path}".',
},
},
+ required: ['path'],
},
responseFormat: 'content',
},
@@ -69,7 +71,7 @@ CONSTRAINTS:
import fs from 'fs';
import path from 'path';
-import { CODE_EXECUTION_TOOLS } from '@librechat/agents';
+import { CODE_EXECUTION_TOOLS, ReadFileToolDefinition } from '@librechat/agents';
import type { LCTool, LCToolRegistry } from '@librechat/agents';
import { CODE_WORKSPACE_OPERATIONS, Constants } from 'librechat-data-provider';
import {
@@ -780,6 +782,45 @@ describe('registerCodeExecutionTools', () => {
expect(JSON.stringify(readFile?.parameters)).not.toContain('{skillName}');
});
+ it.each([false, true])(
+ 'extends the skill read schema locally, workspaceTools=%s',
+ (workspaceTools) => {
+ const result = registerCodeExecutionTools({
+ toolRegistry: makeRegistry(),
+ toolDefinitions: [],
+ includeBash: false,
+ includeSkillFileInstructions: true,
+ workspaceTools,
+ workspaceOperations: new Set(CODE_WORKSPACE_OPERATIONS),
+ });
+ const def = result.toolDefinitions.find(({ name }) => name === 'read_file');
+ expect(def?.parameters).toMatchObject({
+ properties: {
+ start_line: {
+ type: 'integer',
+ minimum: 1,
+ description: expect.stringContaining('skill'),
+ },
+ max_lines: {
+ type: 'integer',
+ minimum: 1,
+ maximum: 500,
+ description: expect.stringContaining('skill'),
+ },
+ },
+ });
+ expect(def?.description).toContain('Omit both range parameters');
+ expect(def?.parameters?.properties?.path).toBeDefined();
+ expect(def?.parameters?.properties?.intent).toEqual({
+ type: 'string',
+ description: 'SDK read intent',
+ });
+ expect(def?.parameters?.required).toEqual(['path']);
+ expect(ReadFileToolDefinition.parameters).not.toHaveProperty('properties.start_line');
+ expect(ReadFileToolDefinition.parameters).not.toHaveProperty('properties.max_lines');
+ },
+ );
+
it('advertises explicit workspace paths and pagination for attached environments', () => {
const result = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
@@ -869,6 +910,66 @@ describe('registerCodeExecutionTools', () => {
});
});
+ it('advertises configured defaults without changing shared definitions or skill upgrades', () => {
+ const toolRegistry = makeRegistry();
+ const options = {
+ toolRegistry,
+ includeBash: true,
+ includeSkillFileInstructions: false,
+ workspaceTools: true,
+ workspaceOperations: new Set(CODE_WORKSPACE_OPERATIONS),
+ workspaceCommandTimeoutMaxMs: 80_000,
+ workspaceCommandTimeoutDefaultMs: 60_000,
+ workspaceReadFileDefaultLines: 500,
+ };
+ const configured = registerCodeExecutionTools({ ...options, toolDefinitions: [] });
+ const upgraded = registerCodeExecutionTools({
+ ...options,
+ toolDefinitions: configured.toolDefinitions,
+ includeBash: false,
+ includeSkillFileInstructions: true,
+ });
+ const readFile = upgraded.toolDefinitions.find(({ name }) => name === 'read_file');
+ expect(readFile?.description).toContain('skills/{skillName}/');
+ expect(readFile?.parameters).toMatchObject({
+ properties: {
+ max_lines: { maximum: 500, description: expect.stringContaining('Defaults to 500') },
+ },
+ });
+ expect(toolRegistry.get('read_file')).toBe(readFile);
+ expect(
+ upgraded.toolDefinitions.find(({ name }) => name === 'bash_tool')?.parameters,
+ ).toMatchObject({
+ properties: {
+ timeoutMs: {
+ maximum: 80_000,
+ description: expect.stringContaining('Defaults to 60000 for foreground calls'),
+ },
+ },
+ });
+ const legacy = registerCodeExecutionTools({
+ toolRegistry: makeRegistry(),
+ toolDefinitions: [],
+ includeBash: true,
+ workspaceTools: true,
+ workspaceOperations: new Set(CODE_WORKSPACE_OPERATIONS),
+ });
+ expect(
+ legacy.toolDefinitions.find(({ name }) => name === 'read_file')?.parameters,
+ ).toMatchObject({
+ properties: { max_lines: { description: expect.stringContaining('Defaults to 200') } },
+ });
+ expect(
+ legacy.toolDefinitions.find(({ name }) => name === 'bash_tool')?.parameters,
+ ).toMatchObject({
+ properties: {
+ timeoutMs: {
+ description: expect.stringContaining('Defaults to 30000 for foreground calls'),
+ },
+ },
+ });
+ });
+
it('registers only operations advertised by the selected workspace', () => {
const result = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
diff --git a/packages/api/src/agents/tools.ts b/packages/api/src/agents/tools.ts
index 2b61d84104..598cf5747a 100644
--- a/packages/api/src/agents/tools.ts
+++ b/packages/api/src/agents/tools.ts
@@ -1,10 +1,3 @@
-import {
- Tools,
- Constants,
- normalizeActionToolName,
- normalizeServerName,
- splitMCPToolKey,
-} from 'librechat-data-provider';
import {
Constants as AgentConstants,
CODE_EXECUTION_TOOLS,
@@ -13,6 +6,15 @@ import {
SkillToolDefinition,
buildBashExecutionToolDescription,
} from '@librechat/agents';
+import {
+ Tools,
+ Constants,
+ CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES,
+ CODE_ENVIRONMENT_READ_FILE_HARD_MAX_LINES,
+ normalizeActionToolName,
+ normalizeServerName,
+ splitMCPToolKey,
+} from 'librechat-data-provider';
import type {
AgentToolOptions,
CodeWorkspaceOperation,
@@ -438,6 +440,8 @@ export interface RegisterCodeExecutionToolsParams {
workspaceOperations?: ReadonlySet<CodeWorkspaceOperation>;
/** Deployment ceiling advertised on attached Bash tool definitions. */
workspaceCommandTimeoutMaxMs?: number;
+ workspaceCommandTimeoutDefaultMs?: number;
+ workspaceReadFileDefaultLines?: number;
workspaceEnvironment?: CodeWorkspaceDescriptor['environment'];
/** The worker runs `.worktrees/<name>` in its own lane; advertise `cwd` routing to the model. */
workspaceLinkedWorktrees?: boolean;
@@ -488,22 +492,43 @@ export interface RegisterFileAuthoringToolsParams {
workspaceOperations?: ReadonlySet<CodeWorkspaceOperation>;
}
-/**
- * Hoisted module-level definition for skill-aware `read_file` so
- * `registerCodeExecutionTools` doesn't re-allocate on every call. The
- * shape is derived from a static `@librechat/agents` export — no
- * per-request state — so a single frozen object is safe to share across
- * every agent init.
- */
+/** Locally extends SDK read parameters without changing the SDK path or intent contract. */
+const READ_FILE_RANGE_PROPERTIES = Object.freeze({
+ start_line: {
+ type: 'integer',
+ minimum: 1,
+ description: 'Optional one-based starting line for a skill, sandbox, or workspace text file.',
+ },
+ max_lines: {
+ type: 'integer',
+ minimum: 1,
+ maximum: CODE_ENVIRONMENT_READ_FILE_HARD_MAX_LINES,
+ description: `Optional line limit for a skill, sandbox, or workspace text file. Defaults to ${CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES} when either range parameter is supplied for skill or sandbox text; the byte budget may truncate sooner.`,
+ },
+});
+
+const READ_FILE_RANGE_INSTRUCTIONS = `Omit both range parameters for full skill/sandbox reads; range defaults: 1/${CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES}.`;
+
+const SKILL_READ_FILE_PARAMETERS = Object.freeze({
+ ...ReadFileToolDefinition.parameters,
+ required: [...(ReadFileToolDefinition.parameters.required ?? ['path'])],
+ properties: {
+ ...ReadFileToolDefinition.parameters.properties,
+ ...READ_FILE_RANGE_PROPERTIES,
+ },
+}) as LCTool['parameters'];
+
const SKILL_READ_FILE_DESCRIPTION = `${ReadFileToolDefinition.description}
-Also accepts authored skill file paths using "skills/{skillName}/...", including "skills/{skillName}/SKILL.md".`;
+Also accepts authored skill file paths using "skills/{skillName}/...", including "skills/{skillName}/SKILL.md".
+
+${READ_FILE_RANGE_INSTRUCTIONS}`;
const READ_FILE_DEF: LCTool = Object.freeze({
name: ReadFileToolDefinition.name,
toolType: 'builtin',
description: SKILL_READ_FILE_DESCRIPTION,
- parameters: ReadFileToolDefinition.parameters as unknown as LCTool['parameters'],
+ parameters: SKILL_READ_FILE_PARAMETERS,
responseFormat: ReadFileToolDefinition.responseFormat,
}) as LCTool;
@@ -511,13 +536,17 @@ const CODE_READ_FILE_DESCRIPTION = `Read a known code-sandbox file. Text is line
Use paths returned by tool output, just written, or under /mnt/data/. Do not run ls/find to rediscover known paths. Use bash_tool for binary or large files, transforms, metadata, and filesystem discovery.
-For managed execution, only retained files under /mnt/data reach later calls. $HOME, /tmp, $TMPDIR, shell/environment state, cwd, global installs, and background processes are call-local.`;
+For managed execution, only retained files under /mnt/data reach later calls. $HOME, /tmp, $TMPDIR, shell/environment state, cwd, global installs, and background processes are call-local.
+
+${READ_FILE_RANGE_INSTRUCTIONS}`;
const ATTACHED_WORKSPACE_READ_FILE_INSTRUCTIONS = `For an attached environment, read registered files as "workspace/{relativePath}". Use a canonical relative path without empty, ".", or ".." segments; the worker's host path stays private. Only the registered workspace persists for attached commands. Project dependencies stored there persist, while $HOME and global/system packages are operator-managed. Use start_line and max_lines for bounded pagination.`;
const CODE_READ_FILE_PARAMETERS: LCTool['parameters'] = Object.freeze({
+ ...SKILL_READ_FILE_PARAMETERS,
type: 'object',
properties: {
+ ...SKILL_READ_FILE_PARAMETERS?.properties,
path: {
type: 'string',
description:
@@ -527,24 +556,23 @@ const CODE_READ_FILE_PARAMETERS: LCTool['parameters'] = Object.freeze({
required: ['path'],
}) as LCTool['parameters'];
+function attachedReadFileLineDescription(defaultReadFileLines: number): string {
+ return `Optional line limit for a skill, sandbox, or workspace text file. Defaults to ${defaultReadFileLines} for workspace reads and ${CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES} for explicit skill or sandbox ranges. Omit both range parameters for a full skill or sandbox read. The byte budget may truncate the result sooner.`;
+}
+
const ATTACHED_WORKSPACE_READ_FILE_PARAMETERS: LCTool['parameters'] = Object.freeze({
+ ...SKILL_READ_FILE_PARAMETERS,
type: 'object',
properties: {
+ ...SKILL_READ_FILE_PARAMETERS?.properties,
path: {
type: 'string',
description:
'Use "workspace/{relativePath}" with a canonical relative path (no empty, ".", or ".." segments) for a file in the attached worker workspace directory, or a code-execution sandbox path such as "/mnt/data/result.csv".',
},
- start_line: {
- type: 'integer',
- minimum: 1,
- description: 'Optional one-based line at which to start reading a workspace text file.',
- },
max_lines: {
- type: 'integer',
- minimum: 1,
- maximum: 500,
- description: 'Optional maximum number of workspace text-file lines to return.',
+ ...READ_FILE_RANGE_PROPERTIES.max_lines,
+ description: attachedReadFileLineDescription(CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES),
},
},
required: ['path'],
@@ -558,7 +586,10 @@ const CODE_READ_FILE_DEF: LCTool = Object.freeze({
responseFormat: ReadFileToolDefinition.responseFormat,
}) as LCTool;
-function createAttachedWorkspaceReadFileDef(includeSkillFileInstructions: boolean): LCTool {
+function createAttachedWorkspaceReadFileDef(
+ includeSkillFileInstructions: boolean,
+ defaultReadFileLines: number = CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES,
+): LCTool {
const baseDescription = includeSkillFileInstructions
? SKILL_READ_FILE_DESCRIPTION
: CODE_READ_FILE_DESCRIPTION;
@@ -566,7 +597,19 @@ function createAttachedWorkspaceReadFileDef(includeSkillFileInstructions: boolea
name: ReadFileToolDefinition.name,
toolType: 'builtin',
description: `${baseDescription}\n\n${ATTACHED_WORKSPACE_READ_FILE_INSTRUCTIONS}`,
- parameters: ATTACHED_WORKSPACE_READ_FILE_PARAMETERS,
+ parameters:
+ defaultReadFileLines === CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES
+ ? ATTACHED_WORKSPACE_READ_FILE_PARAMETERS
+ : {
+ ...ATTACHED_WORKSPACE_READ_FILE_PARAMETERS,
+ properties: {
+ ...ATTACHED_WORKSPACE_READ_FILE_PARAMETERS?.properties,
+ max_lines: {
+ ...ATTACHED_WORKSPACE_READ_FILE_PARAMETERS?.properties?.max_lines,
+ description: attachedReadFileLineDescription(defaultReadFileLines),
+ },
+ },
+ },
responseFormat: ReadFileToolDefinition.responseFormat,
}) as LCTool;
}
@@ -970,8 +1013,15 @@ const ATTACHED_SKILL_EDIT_FILE_DEF: LCTool = Object.freeze({
parameters: attachedFileAuthoringParameters(SKILL_EDIT_FILE_PARAMETERS, true),
}) as LCTool;
-function buildReadFileDef(includeSkillFileInstructions: boolean, workspaceTools: boolean): LCTool {
+function buildReadFileDef(
+ includeSkillFileInstructions: boolean,
+ workspaceTools: boolean,
+ defaultReadFileLines: number = CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES,
+): LCTool {
if (workspaceTools) {
+ if (defaultReadFileLines !== CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES) {
+ return createAttachedWorkspaceReadFileDef(includeSkillFileInstructions, defaultReadFileLines);
+ }
return includeSkillFileInstructions
? ATTACHED_SKILL_READ_FILE_DEF
: ATTACHED_CODE_READ_FILE_DEF;
@@ -1055,6 +1105,7 @@ function createBashToolDef(
workspaceCommandTimeoutMaxMs?: number,
workspaceEnvironment?: CodeWorkspaceDescriptor['environment'],
workspaceLinkedWorktrees = false,
+ workspaceCommandTimeoutDefaultMs?: number,
): LCTool {
/* Passed as a variable (not an inline literal) so the extra
* `statefulSessions` key stays assignable against pinned SDK versions
@@ -1071,6 +1122,7 @@ function createBashToolDef(
workspaceCommandTimeoutMaxMs,
workspaceEnvironment,
workspaceLinkedWorktrees,
+ workspaceCommandTimeoutDefaultMs,
)
: BashExecutionToolDefinition.schema) as unknown as LCTool['parameters'],
}) as LCTool;
@@ -1084,6 +1136,7 @@ function buildBashToolDef(opts: {
statefulSessions?: boolean;
workspaceTools?: boolean;
workspaceCommandTimeoutMaxMs?: number;
+ workspaceCommandTimeoutDefaultMs?: number;
workspaceEnvironment?: CodeWorkspaceDescriptor['environment'];
/** The worker runs `.worktrees/<name>` in its own lane; advertise `cwd` routing to the model. */
workspaceLinkedWorktrees?: boolean;
@@ -1098,6 +1151,7 @@ function buildBashToolDef(opts: {
opts.workspaceCommandTimeoutMaxMs,
opts.workspaceEnvironment,
opts.workspaceLinkedWorktrees === true,
+ opts.workspaceCommandTimeoutDefaultMs,
);
}
return opts.enableToolOutputReferences
@@ -1130,6 +1184,8 @@ export function registerCodeExecutionTools(
workspaceTools = false,
workspaceOperations,
workspaceCommandTimeoutMaxMs,
+ workspaceCommandTimeoutDefaultMs,
+ workspaceReadFileDefaultLines,
workspaceEnvironment,
workspaceLinkedWorktrees,
enableToolOutputReferences = false,
@@ -1140,7 +1196,9 @@ export function registerCodeExecutionTools(
!workspaceTools || workspaceOperations?.has(operation) === true;
const candidates: LCTool[] = [];
if (!workspaceTools || supportsWorkspaceOperation('read_file')) {
- candidates.push(buildReadFileDef(includeSkillFileInstructions, workspaceTools));
+ candidates.push(
+ buildReadFileDef(includeSkillFileInstructions, workspaceTools, workspaceReadFileDefaultLines),
+ );
} else if (includeSkillFileInstructions) {
candidates.push(buildReadFileDef(true, false));
}
@@ -1151,6 +1209,7 @@ export function registerCodeExecutionTools(
statefulSessions,
workspaceTools,
workspaceCommandTimeoutMaxMs,
+ workspaceCommandTimeoutDefaultMs,
workspaceEnvironment,
workspaceLinkedWorktrees,
}),
diff --git a/packages/api/src/code/command.spec.ts b/packages/api/src/code/command.spec.ts
index 7a625819a6..2b058d63de 100644
--- a/packages/api/src/code/command.spec.ts
+++ b/packages/api/src/code/command.spec.ts
@@ -1,14 +1,19 @@
import { once } from 'node:events';
import { createServer } from 'node:http';
+import { createBashProgrammaticToolCallingTool } from '@librechat/agents';
+import type { createBashProgrammaticToolCallingSchema } from '@librechat/agents';
import type { AddressInfo } from 'node:net';
+import type { CodeExecutionContext } from '~/agents/execution';
import type { CodeBridgeFetch } from './bridge';
import {
ATTACHED_WORKSPACE_BASH_DESCRIPTION,
ATTACHED_WORKSPACE_BASH_SCHEMA,
buildAttachedWorkspaceBashSchema,
createAttachedWorkspaceBashTool,
+ createContextProgrammaticBashTool,
createGitIdentityProgrammaticBashTool,
resolveAttachedWorkspaceCommandTimeoutMax,
+ resolveAttachedWorkspaceCommandTimeoutDefault,
resolveAttachedWorkspaceProgrammaticTimeout,
resolveAttachedWorkspaceQueueWaitMs,
resolveAttachedWorkspaceRequestTimeoutMs,
@@ -129,6 +134,243 @@ describe('programmatic Bash Git identity', () => {
}
});
+ test.each([false, true])(
+ 'preserves the complete attached SDK schema with configured defaults and identity=%s',
+ (withIdentity) => {
+ const context: CodeExecutionContext = {
+ baseUrl: 'http://127.0.0.1:9999/v1',
+ codeSessionKey: 'execute_code:stateful:attached',
+ executionProfile: 'stateful',
+ environmentType: 'attached',
+ statefulSessions: true,
+ codeWorkspace: {
+ environmentId: 'machine',
+ workspaceId: 'project-a',
+ workspaceInstanceId: 'a'.repeat(64),
+ operations: ['execute_command'],
+ maxCommandTimeoutMs: 80_000,
+ },
+ codeEnvironmentConfigSchema: {
+ limits: { defaultCommandTimeoutMs: 60_000, maxCommandTimeoutMs: 80_000 },
+ },
+ };
+ const baseline = createBashProgrammaticToolCallingTool({
+ baseUrl: context.baseUrl,
+ authHeaders: () => ({}),
+ executionProfile: context.executionProfile,
+ workspaceId: context.codeWorkspace?.workspaceId,
+ workspaceInstanceId: context.codeWorkspace?.workspaceInstanceId,
+ runTimeoutMs: 80_000,
+ });
+ const originalSchema = structuredClone(baseline.schema) as ReturnType<
+ typeof createBashProgrammaticToolCallingSchema
+ >;
+ const configured = createContextProgrammaticBashTool(
+ () => ({}),
+ context,
+ withIdentity ? { name: 'Lia', email: '[email protected]' } : undefined,
+ );
+ const schema = configured.schema as ReturnType<
+ typeof createBashProgrammaticToolCallingSchema
+ >;
+ expect(schema.properties.code).toEqual(originalSchema.properties.code);
+ expect(schema.properties.code.description).toContain('ATTACHED WORKSPACE EXECUTION');
+ expect(schema.properties.code.description).toContain('${LIBRECHAT_CODE_DATA_DIR:-/mnt/data}');
+ expect(schema).toEqual({
+ ...originalSchema,
+ properties: {
+ ...originalSchema.properties,
+ timeout: {
+ ...originalSchema.properties.timeout,
+ default: 60_000,
+ description: expect.stringContaining('when timeout is omitted'),
+ },
+ },
+ });
+ expect(configured.description).toBe(baseline.description);
+ expect(configured.schema).not.toBe(baseline.schema);
+ expect(baseline.schema).toEqual(originalSchema);
+ expect(
+ createContextProgrammaticBashTool(() => ({}), {
+ ...context,
+ codeEnvironmentConfigSchema: { limits: { maxCommandTimeoutMs: 80_000 } },
+ }).schema,
+ ).toEqual(originalSchema);
+ },
+ );
+
+ test('uses the foreground default only when the real SDK programmatic call omits timeout', async () => {
+ const received: { timeout: number; code: string }[] = [];
+ const server = createServer(async (req, res) => {
+ let body = '';
+ for await (const chunk of req) body += chunk;
+ received.push(JSON.parse(body));
+ res.setHeader('Content-Type', 'application/json');
+ res.end(JSON.stringify({ status: 'completed', stdout: 'done', stderr: '', files: [] }));
+ });
+ server.listen(0, '127.0.0.1');
+ await once(server, 'listening');
+ const { port } = server.address() as AddressInfo;
+ try {
+ const bashTool = createContextProgrammaticBashTool(
+ () => ({}),
+ {
+ baseUrl: `http://127.0.0.1:${port}/v1`,
+ codeSessionKey: 'execute_code:stateful:attached',
+ executionProfile: 'stateful',
+ environmentType: 'attached',
+ statefulSessions: true,
+ codeWorkspace: {
+ environmentId: 'machine',
+ workspaceId: 'project-a',
+ operations: ['execute_command'],
+ maxCommandTimeoutMs: 80_000,
+ },
+ codeEnvironmentConfigSchema: {
+ limits: { defaultCommandTimeoutMs: 60_000, maxCommandTimeoutMs: 80_000 },
+ },
+ },
+ { name: 'Lia', email: '[email protected]' },
+ );
+ const invocationConfig = {
+ tags: [],
+ toolCall: { name: 'run_tools_with_bash', args: {}, toolDefs: [] },
+ };
+ for (const timeout of [undefined, 75_000, 10_000, 90_000]) {
+ await bashTool.invoke(
+ { code: 'printf done', tool_manifest: [], ...(timeout == null ? {} : { timeout }) },
+ invocationConfig,
+ );
+ }
+ expect(received.map(({ timeout }) => timeout)).toEqual([60_000, 75_000, 10_000, 80_000]);
+ expect(received.every(({ code }) => code.includes("GIT_AUTHOR_NAME='Lia'"))).toBe(true);
+ expect(bashTool.schema).toMatchObject({
+ properties: {
+ timeout: {
+ default: 60_000,
+ description: expect.stringContaining('Default: 60000 milliseconds'),
+ },
+ },
+ });
+ expect(bashTool.schema).toMatchObject({
+ properties: {
+ timeout: { description: expect.stringContaining('Configured cap: 80000 milliseconds') },
+ },
+ });
+ } finally {
+ server.close();
+ await once(server, 'close');
+ }
+ });
+
+ test.each([
+ [60_000, 80_000, 50_000, undefined, 50_000, 50_000],
+ [60_000, 80_000, 80_000, 65_000, 45_000, 45_000],
+ [120_000, 80_000, 80_000, undefined, 80_000, 75_000],
+ [1, 80_000, 80_000, undefined, 1_000, 75_000],
+ [undefined, 80_000, 80_000, undefined, 80_000, 75_000],
+ [undefined, undefined, 90_000, undefined, 30_000, 30_000],
+ ])(
+ 'keeps real SDK defaults and explicit calls within admin/worker/HTTP ceilings (%s, %s, %s, %s)',
+ async (
+ defaultCommandTimeoutMs,
+ maxCommandTimeoutMs,
+ upstreamMaxTimeoutMs,
+ maxRequestTimeoutMs,
+ expectedDefault,
+ expectedExplicit,
+ ) => {
+ const received: { timeout: number }[] = [];
+ const server = createServer(async (req, res) => {
+ let body = '';
+ for await (const chunk of req) body += chunk;
+ received.push(JSON.parse(body));
+ res.setHeader('Content-Type', 'application/json');
+ res.end(JSON.stringify({ status: 'completed', stdout: 'done', stderr: '', files: [] }));
+ });
+ server.listen(0, '127.0.0.1');
+ await once(server, 'listening');
+ const { port } = server.address() as AddressInfo;
+ try {
+ const bashTool = createContextProgrammaticBashTool(() => ({}), {
+ baseUrl: `http://127.0.0.1:${port}/v1`,
+ codeSessionKey: 'execute_code:stateful:attached',
+ executionProfile: 'stateful',
+ environmentType: 'attached',
+ statefulSessions: true,
+ codeWorkspace: {
+ environmentId: 'machine',
+ workspaceId: 'project-a',
+ operations: ['execute_command'],
+ maxCommandTimeoutMs: upstreamMaxTimeoutMs,
+ },
+ codeEnvironmentConfigSchema: {
+ limits: { defaultCommandTimeoutMs, maxCommandTimeoutMs, maxRequestTimeoutMs },
+ },
+ });
+ const config = { tags: [], toolCall: { toolDefs: [] } };
+ await bashTool.func({ code: 'printf done', tool_manifest: [] }, undefined, config);
+ await bashTool.func(
+ { code: 'printf done', tool_manifest: [], timeout: 75_000 },
+ undefined,
+ config,
+ );
+ expect(received.map(({ timeout }) => timeout)).toEqual([expectedDefault, expectedExplicit]);
+ expect(bashTool.schema).toMatchObject({
+ properties: { timeout: { default: expectedDefault } },
+ });
+ } finally {
+ server.close();
+ await once(server, 'close');
+ }
+ },
+ );
+
+ test('refuses a newly configured programmatic ceiling below the SDK floor instead of raising it', () => {
+ expect(() =>
+ createContextProgrammaticBashTool(() => ({}), {
+ baseUrl: 'http://127.0.0.1:9999/v1',
+ codeSessionKey: 'execute_code:stateful:attached',
+ executionProfile: 'stateful',
+ environmentType: 'attached',
+ statefulSessions: true,
+ codeEnvironmentConfigSchema: {
+ limits: { defaultCommandTimeoutMs: 1, maxCommandTimeoutMs: 500 },
+ },
+ }),
+ ).toThrow('requires a timeout ceiling of at least 1000 milliseconds');
+ });
+
+ test('resolves the programmatic ceiling independently of the foreground default', () => {
+ expect(
+ resolveAttachedWorkspaceProgrammaticTimeout(
+ { limits: { defaultCommandTimeoutMs: 60_000, maxCommandTimeoutMs: 80_000 } },
+ 70_000,
+ ),
+ ).toBe(70_000);
+ expect(
+ resolveAttachedWorkspaceProgrammaticTimeout(
+ { limits: { defaultCommandTimeoutMs: 60_000, maxCommandTimeoutMs: 80_000 } },
+ 50_000,
+ ),
+ ).toBe(50_000);
+ expect(
+ resolveAttachedWorkspaceProgrammaticTimeout({ limits: { defaultCommandTimeoutMs: 60_000 } }),
+ ).toBe(30_000);
+ expect(
+ resolveAttachedWorkspaceProgrammaticTimeout(
+ {
+ limits: {
+ defaultCommandTimeoutMs: 60_000,
+ maxCommandTimeoutMs: 80_000,
+ maxRequestTimeoutMs: 65_000,
+ },
+ },
+ 80_000,
+ ),
+ ).toBe(45_000);
+ });
+
test('preserves the foreground timeout while bounding an explicit admin override', () => {
expect(resolveAttachedWorkspaceProgrammaticTimeout(undefined, 90_000)).toBe(30_000);
expect(
@@ -164,6 +406,85 @@ function commandResponse(overrides: Record<string, unknown> = {}): Response {
}
describe('createAttachedWorkspaceBashTool', () => {
+ test.each([
+ [60_000, 80_000, undefined, 60_000],
+ [120_000, 80_000, undefined, 80_000],
+ [60_000, 80_000, 65_000, 45_000],
+ [60_000, 5_000, undefined, 5_000],
+ [1, 80_000, undefined, 1],
+ ])(
+ 'bounds foreground default %i by ceiling %i and HTTP budget %s',
+ async (defaultTimeoutMs, maxTimeoutMs, maxRequestTimeoutMs, expected) => {
+ const fetchImpl: CodeBridgeFetch = jest.fn(async () => commandResponse());
+ const bashTool = createAttachedWorkspaceBashTool({
+ baseUrl: 'https://code.example.com/v1',
+ authHeaders: () => ({}),
+ workspaceId: 'project-a',
+ defaultTimeoutMs,
+ maxTimeoutMs,
+ maxRequestTimeoutMs,
+ fetchImpl,
+ });
+ await bashTool.invoke({ command: 'npm test' });
+ expect(JSON.parse(String((fetchImpl as jest.Mock).mock.calls[0][1]?.body))).toMatchObject({
+ timeoutMs: expected,
+ });
+ expect(bashTool.schema).toMatchObject({
+ properties: {
+ timeoutMs: {
+ description: expect.stringContaining(`Defaults to ${expected} for foreground calls`),
+ },
+ },
+ });
+ },
+ );
+
+ test('keeps explicit and background timeouts independent of the foreground default', async () => {
+ const fetchImpl: CodeBridgeFetch = jest.fn(async () => commandResponse());
+ const bashTool = createAttachedWorkspaceBashTool({
+ baseUrl: 'https://code.example.com/v1',
+ authHeaders: () => ({}),
+ workspaceId: 'project-a',
+ defaultTimeoutMs: 60_000,
+ maxTimeoutMs: 80_000,
+ fetchImpl,
+ });
+ await bashTool.invoke({ command: 'npm test', timeoutMs: 10_000 });
+ await bashTool.invoke(
+ { command: 'npm test' },
+ { configurable: { [BACKGROUND_TOOL_INVOCATION_CONFIG_KEY]: true } },
+ );
+ await bashTool.invoke(
+ { command: 'npm test', timeoutMs: 20_000 },
+ { configurable: { [BACKGROUND_TOOL_INVOCATION_CONFIG_KEY]: true } },
+ );
+ expect(
+ (fetchImpl as jest.Mock).mock.calls.map(
+ ([, init]) => JSON.parse(String(init?.body)).timeoutMs,
+ ),
+ ).toEqual([10_000, 80_000, 20_000]);
+ });
+
+ test.each([0, -1, 1.5, NaN, Infinity])(
+ 'falls back safely for invalid foreground default %s',
+ (defaultTimeoutMs) => {
+ expect(resolveAttachedWorkspaceCommandTimeoutDefault(defaultTimeoutMs, 80_000)).toBe(30_000);
+ },
+ );
+
+ test('does not raise the command ceiling when only a foreground default is configured', () => {
+ const maxTimeoutMs = resolveAttachedWorkspaceCommandTimeoutMax({
+ limits: { defaultCommandTimeoutMs: 60_000 },
+ });
+ expect(maxTimeoutMs).toBe(30_000);
+ expect(resolveAttachedWorkspaceCommandTimeoutDefault(60_000, maxTimeoutMs)).toBe(30_000);
+ const upstreamMax = resolveAttachedWorkspaceCommandTimeoutMax(
+ { limits: { defaultCommandTimeoutMs: 60_000 } },
+ 50_000,
+ );
+ expect(resolveAttachedWorkspaceCommandTimeoutDefault(60_000, upstreamMax)).toBe(50_000);
+ });
+
test('honors a zero Code API rate-limit retry budget', async () => {
const fetchImpl: CodeBridgeFetch = jest.fn(
async () => new Response(JSON.stringify({ error: 'rate_limited' }), { status: 429 }),
@@ -729,6 +1050,31 @@ describe('createAttachedWorkspaceBashTool', () => {
expect(request.command).not.toContain('git config');
});
+ test('reports the requested timeout and effective retry ceiling after HTTP-budget clamping', async () => {
+ const fetchImpl: CodeBridgeFetch = jest.fn(async () =>
+ commandResponse({ exitCode: null, timedOut: true, stdout: 'partial work', stderr: '' }),
+ );
+ const bashTool = createAttachedWorkspaceBashTool({
+ baseUrl: 'https://code.example.com/v1',
+ authHeaders: () => ({}),
+ workspaceId: 'project-a',
+ defaultTimeoutMs: 60_000,
+ maxTimeoutMs: 80_000,
+ maxRequestTimeoutMs: 90_000,
+ fetchImpl,
+ });
+ const [content] = await bashTool.func(
+ { command: 'npm test', timeoutMs: 10_000 },
+ undefined,
+ {},
+ );
+ expect(content).toContain('partial work');
+ expect(content).toContain('timeoutMs: 10000');
+ expect(content).toContain('up to 70000 milliseconds');
+ expect(content).not.toContain('up to 80000');
+ expect(content).toContain('partial side effects');
+ });
+
test('reports termination, timeouts, and truncation without hiding stderr', async () => {
const fetchImpl: CodeBridgeFetch = jest.fn(async () =>
commandResponse({
@@ -748,7 +1094,7 @@ describe('createAttachedWorkspaceBashTool', () => {
});
await expect(bashTool.func({ command: 'sleep 60' }, undefined, {})).resolves.toEqual([
- 'stderr:\ndeadline reached\n[terminated by SIGKILL][timed out][output truncated]',
+ 'stderr:\ndeadline reached\n[terminated by SIGKILL][timed out][output truncated]\nCommand reached timeoutMs: 30000. Before retrying, check for partial side effects. Set timeoutMs explicitly up to 30000 milliseconds, or use run_in_background: true if available. Background execution uses the same timeout ceiling.',
{},
]);
});
diff --git a/packages/api/src/code/command.ts b/packages/api/src/code/command.ts
index 66c94e29d5..5cb3ee42ab 100644
--- a/packages/api/src/code/command.ts
+++ b/packages/api/src/code/command.ts
@@ -11,6 +11,7 @@ import type {
CodeEnvironmentUserConfigSchema,
CodeWorkspaceDescriptor,
} from 'librechat-data-provider';
+import type { createBashProgrammaticToolCallingSchema } from '@librechat/agents';
import type { DynamicStructuredTool } from '@librechat/agents/langchain/tools';
import type { LCTool } from '@librechat/agents';
import type { WorkspaceExecuteCommandResult } from './workspace';
@@ -108,8 +109,14 @@ interface BoundedTimeoutSchema {
description: string;
}
-function buildAttachedTimeoutSchema(maxTimeoutMs: number): BoundedTimeoutSchema {
- const defaultTimeoutMs = Math.min(WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS, maxTimeoutMs);
+function buildAttachedTimeoutSchema(
+ maxTimeoutMs: number,
+ foregroundTimeoutMs: number,
+): BoundedTimeoutSchema {
+ const defaultTimeoutMs = resolveAttachedWorkspaceCommandTimeoutDefault(
+ foregroundTimeoutMs,
+ maxTimeoutMs,
+ );
return {
type: 'integer',
minimum: 1,
@@ -125,6 +132,17 @@ function normalizeAttachedWorkspaceCommandTimeoutMax(maxTimeoutMs: number): numb
return Math.min(WORKSPACE_COMMAND_MAX_TIMEOUT_MS, maxTimeoutMs);
}
+/** Foreground defaults never raise the negotiated execution ceiling. */
+export function resolveAttachedWorkspaceCommandTimeoutDefault(
+ defaultTimeoutMs: number = WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS,
+ maxTimeoutMs: number = WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS,
+): number {
+ return Math.min(
+ normalizeAttachedWorkspaceCommandTimeoutMax(defaultTimeoutMs),
+ normalizeAttachedWorkspaceCommandTimeoutMax(maxTimeoutMs),
+ );
+}
+
export function resolveAttachedWorkspaceCommandTimeoutMax(
configSchema?: CodeEnvironmentUserConfigSchema,
upstreamMaxTimeoutMs?: number,
@@ -161,13 +179,18 @@ function fitCommandTimeoutMaxToBudget(
/**
* Programmatic calls do not currently carry the detached-invocation marker.
- * Preserve their historical foreground default while still enforcing both an
- * explicit administrator override and the live upstream ceiling.
+ * The SDK's runTimeoutMs is a ceiling, not an omission-only default. When the
+ * environment configures a foreground default, resolve its ceiling separately;
+ * otherwise retain the legacy maxCommandTimeoutMs behavior on this SDK route.
*/
export function resolveAttachedWorkspaceProgrammaticTimeout(
configSchema?: CodeEnvironmentUserConfigSchema,
upstreamMaxTimeoutMs?: number,
): number {
+ const defaultTimeoutMs = configSchema?.limits?.defaultCommandTimeoutMs;
+ if (defaultTimeoutMs != null) {
+ return resolveAttachedWorkspaceCommandTimeoutMax(configSchema, upstreamMaxTimeoutMs);
+ }
const configured = configSchema?.limits?.maxCommandTimeoutMs;
const requested =
configured == null
@@ -219,6 +242,7 @@ export function buildAttachedWorkspaceBashSchema(
maxTimeoutMs: number = WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS,
environment?: CodeWorkspaceDescriptor['environment'],
linkedWorktrees = false,
+ defaultTimeoutMs: number = WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS,
): NonNullable<LCTool['parameters']> {
const effectiveMaxTimeoutMs = normalizeAttachedWorkspaceCommandTimeoutMax(maxTimeoutMs);
return {
@@ -230,7 +254,7 @@ export function buildAttachedWorkspaceBashSchema(
linkedWorktrees === true
? linkedWorktreeWorkingDirectorySchema
: attachedWorkingDirectorySchema,
- timeoutMs: buildAttachedTimeoutSchema(effectiveMaxTimeoutMs),
+ timeoutMs: buildAttachedTimeoutSchema(effectiveMaxTimeoutMs, defaultTimeoutMs),
...(environment?.actions.length
? {
environmentAction: {
@@ -326,7 +350,35 @@ export function createContextProgrammaticBashTool(
}
: {}),
};
- return createGitIdentityProgrammaticBashTool(options, attached ? identity : undefined);
+ const bashTool = createGitIdentityProgrammaticBashTool(options, attached ? identity : undefined);
+ const configuredDefault = attached
+ ? context.codeEnvironmentConfigSchema?.limits?.defaultCommandTimeoutMs
+ : undefined;
+ if (configuredDefault == null) return bashTool;
+
+ const maxTimeoutMs = options.runTimeoutMs ?? WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS;
+ const schema = structuredClone(bashTool.schema) as ReturnType<
+ typeof createBashProgrammaticToolCallingSchema
+ >;
+ const minimumTimeoutMs = schema.properties.timeout.minimum;
+ if (maxTimeoutMs < minimumTimeoutMs) {
+ throw new Error(
+ `Attached programmatic execution requires a timeout ceiling of at least ${minimumTimeoutMs} milliseconds. Use bash_tool for shorter command budgets.`,
+ );
+ }
+ const defaultTimeoutMs = Math.max(
+ minimumTimeoutMs,
+ resolveAttachedWorkspaceCommandTimeoutDefault(configuredDefault, maxTimeoutMs),
+ );
+ schema.properties.timeout.default = defaultTimeoutMs;
+ schema.properties.timeout.description = `Maximum wall-clock time in milliseconds for one sandbox run or replay iteration, not the total multi-round-trip task budget. Default: ${defaultTimeoutMs} milliseconds when timeout is omitted. Accepted values above the configured cap are clamped before execution. Configured cap: ${maxTimeoutMs} milliseconds.`;
+ bashTool.schema = schema;
+ const execute = bashTool.func.bind(bashTool);
+ bashTool.func = (input, ...args) => {
+ const params = input as { timeout?: number };
+ return execute({ ...params, timeout: params.timeout ?? defaultTimeoutMs }, ...args);
+ };
+ return bashTool;
}
/** Apply authorship before the SDK prepares the script and its replay requests. */
@@ -344,7 +396,11 @@ export function createGitIdentityProgrammaticBashTool(
return bashTool;
}
-function formatCommandResult(result: WorkspaceExecuteCommandResult): string {
+function formatCommandResult(
+ result: WorkspaceExecuteCommandResult,
+ timeoutMs: number,
+ maxTimeoutMs: number,
+): string {
let output = '';
if (result.stdout.length > 0) output += `stdout:\n${result.stdout}\n`;
if (result.stderr.length > 0) output += `stderr:\n${result.stderr}\n`;
@@ -353,6 +409,9 @@ function formatCommandResult(result: WorkspaceExecuteCommandResult): string {
if (result.signal != null) output += `[terminated by ${result.signal}]`;
if (result.timedOut) output += '[timed out]';
if (result.truncated) output += '[output truncated]';
+ if (result.timedOut) {
+ output += `\nCommand reached timeoutMs: ${timeoutMs}. Before retrying, check for partial side effects. Set timeoutMs explicitly up to ${maxTimeoutMs} milliseconds, or use run_in_background: true if available. Background execution uses the same timeout ceiling.`;
+ }
return output;
}
@@ -364,6 +423,7 @@ export function createAttachedWorkspaceBashTool({
environment,
gitIdentity,
maxTimeoutMs = WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS,
+ defaultTimeoutMs = WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS,
maxQueueWaitMs,
codeApiMaxRetryWaitMs,
maxRequestTimeoutMs,
@@ -381,6 +441,8 @@ export function createAttachedWorkspaceBashTool({
gitIdentity?: AgentGitIdentity | null;
/** Effective admin/upstream ceiling already intersected with the protocol hard cap. */
maxTimeoutMs?: number;
+ /** Foreground timeout when omitted by the model; bounded by the effective ceiling. */
+ defaultTimeoutMs?: number;
/** Retry horizon across typed queue expirations, not an admission budget. */
maxQueueWaitMs?: number;
codeApiMaxRetryWaitMs?: number;
@@ -395,8 +457,17 @@ export function createAttachedWorkspaceBashTool({
maxRequestTimeoutMs,
minCommandAdmissionMs,
);
+ const effectiveDefaultTimeoutMs = resolveAttachedWorkspaceCommandTimeoutDefault(
+ defaultTimeoutMs,
+ effectiveMaxTimeoutMs,
+ );
const schema = structuredClone(
- buildAttachedWorkspaceBashSchema(effectiveMaxTimeoutMs, environment, linkedWorktrees),
+ buildAttachedWorkspaceBashSchema(
+ effectiveMaxTimeoutMs,
+ environment,
+ linkedWorktrees,
+ effectiveDefaultTimeoutMs,
+ ),
);
const actions = environment?.actions ?? [];
const bashTool = tool(
@@ -437,7 +508,7 @@ export function createAttachedWorkspaceBashTool({
rawInput.timeoutMs ??
(config?.configurable?.[BACKGROUND_TOOL_INVOCATION_CONFIG_KEY] === true
? effectiveMaxTimeoutMs
- : Math.min(WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS, effectiveMaxTimeoutMs));
+ : effectiveDefaultTimeoutMs);
const signal = config?.signal;
const trace = {
runId: config?.metadata?.run_id,
@@ -478,7 +549,7 @@ export function createAttachedWorkspaceBashTool({
throw new Error('Attached workspace returned an unexpected command result.');
}
logger.debug('[BYOMCommand] transport completed', trace);
- return [formatCommandResult(result), {}];
+ return [formatCommandResult(result, timeoutMs, effectiveMaxTimeoutMs), {}];
} finally {
signal?.removeEventListener('abort', onAbort);
logger.debug('[BYOMCommand] transport settled', {
diff --git a/packages/api/src/code/workspace.spec.ts b/packages/api/src/code/workspace.spec.ts
index 8e4258386f..db89c3fa9f 100644
--- a/packages/api/src/code/workspace.spec.ts
+++ b/packages/api/src/code/workspace.spec.ts
@@ -1,6 +1,28 @@
import type { WorkspaceToolRequest } from './workspace';
import type { CodeBridgeFetch } from './bridge';
-import { executeWorkspaceTool, WorkspaceToolHttpError } from './workspace';
+import {
+ executeWorkspaceTool,
+ WorkspaceToolHttpError,
+ resolveAttachedWorkspaceReadFileLines,
+} from './workspace';
+
+describe('attached read window defaults', () => {
+ test('preserves the legacy read window unless configured', () => {
+ expect(resolveAttachedWorkspaceReadFileLines()).toBe(200);
+ expect(resolveAttachedWorkspaceReadFileLines({ limits: {} })).toBe(200);
+ expect(resolveAttachedWorkspaceReadFileLines({ limits: { defaultReadFileLines: 500 } })).toBe(
+ 500,
+ );
+ expect(resolveAttachedWorkspaceReadFileLines({ limits: { defaultReadFileLines: 1 } })).toBe(1);
+ });
+
+ test.each([0, -1, 1.5, 501, NaN, Infinity])(
+ 'falls back safely for an invalid read window %s',
+ (defaultReadFileLines) => {
+ expect(resolveAttachedWorkspaceReadFileLines({ limits: { defaultReadFileLines } })).toBe(200);
+ },
+ );
+});
describe('workspace admission feedback', () => {
test('forwards a valid conversation workspace instance unchanged', async () => {
diff --git a/packages/api/src/code/workspace.ts b/packages/api/src/code/workspace.ts
index 19e9217891..ede726261d 100644
--- a/packages/api/src/code/workspace.ts
+++ b/packages/api/src/code/workspace.ts
@@ -1,9 +1,13 @@
import {
CODE_ENVIRONMENT_ADMISSION_MAX_MS,
+ CODE_ENVIRONMENT_COMMAND_TIMEOUT_DEFAULT_MS,
+ CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES,
+ CODE_ENVIRONMENT_READ_FILE_HARD_MAX_LINES,
CODE_ENVIRONMENT_COMMAND_ADMISSION_DEFAULT_MS,
CODE_ENVIRONMENT_QUEUE_WAIT_DEFAULT_MS,
CODE_ENVIRONMENT_REQUEST_TIMEOUT_HARD_MAX_MS,
} from 'librechat-data-provider';
+import type { CodeEnvironmentUserConfigSchema } from 'librechat-data-provider';
import type { WorkspaceEditMatch, WorkspaceEditMatching } from './edits';
import type { CodeBridgeFetch } from './bridge';
import { CODE_API_RATE_LIMIT_WAIT_DEFAULT_MS } from './limits';
@@ -13,7 +17,7 @@ const WORKSPACE_TOOL_TIMEOUT_MS = 30_000;
const MAX_PATH_LENGTH = 4096;
const MAX_QUERY_LENGTH = 4096;
const MAX_READ_BYTES = 1024 * 1024;
-const MAX_READ_LINES = 500;
+const MAX_READ_LINES = CODE_ENVIRONMENT_READ_FILE_HARD_MAX_LINES;
const MAX_SEARCH_RESULTS = 200;
const MAX_SEARCH_TEXT_LENGTH = 2000;
const MAX_LIST_RESULTS = 500;
@@ -21,7 +25,8 @@ export const WORKSPACE_WRITE_MAX_BYTES: number = 1024 * 1024;
export const WORKSPACE_EDIT_MAX_COUNT: number = 100;
const MAX_COMMAND_BYTES = 32 * 1024;
/** Keep aligned with data-provider's deployment schema defaults and hard cap. */
-export const WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS: number = 30_000;
+export const WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS: number =
+ CODE_ENVIRONMENT_COMMAND_TIMEOUT_DEFAULT_MS;
export const WORKSPACE_COMMAND_MAX_TIMEOUT_MS: number = 5 * 60_000;
const DEFAULT_COMMAND_OUTPUT_BYTES = 256 * 1024;
const MAX_COMMAND_OUTPUT_BYTES = 1024 * 1024;
@@ -1071,6 +1076,19 @@ export function fromLinkedWorktreeResult(
}
}
+/** Resolves a bounded read window without changing the protocol-v1 byte or line ceilings. */
+export function resolveAttachedWorkspaceReadFileLines(
+ configSchema?: CodeEnvironmentUserConfigSchema,
+): number {
+ const configured = configSchema?.limits?.defaultReadFileLines;
+ return configured != null &&
+ Number.isSafeInteger(configured) &&
+ configured >= 1 &&
+ configured <= MAX_READ_LINES
+ ? configured
+ : CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES;
+}
+
export async function executeWorkspaceTool({
baseURL,
authHeaders,
diff --git a/packages/api/src/files/code/index.ts b/packages/api/src/files/code/index.ts
index 78b3eabb11..31029d3315 100644
--- a/packages/api/src/files/code/index.ts
+++ b/packages/api/src/files/code/index.ts
@@ -12,3 +12,4 @@ export * from './priming';
export * from './process';
export * from './publication';
export * from './snapshot';
+export * from './text';
diff --git a/packages/api/src/files/code/text.spec.ts b/packages/api/src/files/code/text.spec.ts
new file mode 100644
index 0000000000..9b34090ab4
--- /dev/null
+++ b/packages/api/src/files/code/text.spec.ts
@@ -0,0 +1,101 @@
+import type { SandboxImageReadResult } from './image';
+import { createSandboxTextReader } from './text';
+
+const params = { file_path: '/mnt/data/catalogue.txt', maxBytes: 262_144 };
+
+function fileResult(content: string): SandboxImageReadResult {
+ const bytes = Buffer.from(content);
+ return { base64: bytes.toString('base64'), bytes: bytes.length };
+}
+
+it('preserves the legacy no-budget reader, including errors and request identity', async () => {
+ const readFile = jest.fn(async () => ({ content: 'legacy prefix' }));
+ const readBytes = jest.fn(async () => fileResult('complete'));
+ const read = createSandboxTextReader({ readFile, readBytes });
+ const request = { file_path: params.file_path, session_id: 'session-a' };
+ expect(await read(request)).toEqual({ content: 'legacy prefix' });
+ expect(readFile).toHaveBeenCalledWith(request);
+ expect(readBytes).not.toHaveBeenCalled();
+ const failure = new Error('transport failed');
+ readFile.mockRejectedValueOnce(failure);
+ await expect(read(request)).rejects.toBe(failure);
+});
+
+it.each(['', 'first\nlast\n', '界'.repeat(60_000)])(
+ 'decodes complete bounded bytes once for text length %i',
+ async (content) => {
+ const readFile = jest.fn(async () => null);
+ const readBytes = jest.fn(async () => fileResult(content));
+ const read = createSandboxTextReader({ readFile, readBytes });
+ expect(await read(params)).toEqual({ content, complete: true });
+ expect(readBytes).toHaveBeenCalledWith(params);
+ expect(readFile).not.toHaveBeenCalled();
+ },
+);
+
+it.each([
+ { base64: 'eA==', bytes: 2 },
+ { base64: 'invalid!', bytes: 5 },
+ { base64: 'eA==junk', bytes: 4 },
+ { base64: Buffer.alloc(262_145).toString('base64'), bytes: 262_145 },
+])('refuses malformed, shortened, or over-budget byte retrieval', async (result) => {
+ const read = createSandboxTextReader({
+ readFile: async () => null,
+ readBytes: async () => result,
+ });
+ await expect(read(params)).rejects.toThrow('retrieval was incomplete');
+});
+
+it('refuses non-UTF-8 bytes instead of filtering replacement text', async () => {
+ const result = { base64: Buffer.from([0xff, 0xfe]).toString('base64'), bytes: 2 };
+ const read = createSandboxTextReader({
+ readFile: async () => null,
+ readBytes: async () => result,
+ });
+ await expect(read(params)).rejects.toThrow('not UTF-8 text');
+});
+
+it.each(['size', 'round_trips'] as const)(
+ 'propagates %s limits without treating them as EOF',
+ async (reason) => {
+ const result = { tooLarge: true as const, reason, bytes: 262_145 };
+ const read = createSandboxTextReader({
+ readFile: async () => null,
+ readBytes: async () => result,
+ });
+ expect(await read(params)).toEqual(result);
+ },
+);
+
+it('keeps transport absence distinct from complete empty content', async () => {
+ const read = createSandboxTextReader({ readFile: async () => null, readBytes: async () => null });
+ expect(await read(params)).toBeNull();
+});
+
+it.each([0, -1, 1.5, NaN, Infinity])(
+ 'rejects an invalid byte budget %s before dispatch',
+ async (maxBytes) => {
+ const readBytes = jest.fn(async () => null);
+ const read = createSandboxTextReader({ readFile: async () => null, readBytes });
+ await expect(read({ ...params, maxBytes })).rejects.toThrow(
+ 'Invalid sandbox text-read byte budget',
+ );
+ expect(readBytes).not.toHaveBeenCalled();
+ },
+);
+
+it('does not dispatch an already-aborted ranged read or return bytes after cancellation', async () => {
+ const controller = new AbortController();
+ const failure = new Error('cancelled');
+ const readBytes = jest.fn(async () => fileResult('complete'));
+ const read = createSandboxTextReader({ readFile: async () => null, readBytes });
+ controller.abort(failure);
+ await expect(read({ ...params, signal: controller.signal })).rejects.toBe(failure);
+ expect(readBytes).not.toHaveBeenCalled();
+ const inFlight = new AbortController();
+ readBytes.mockImplementationOnce(async () => {
+ inFlight.abort(failure);
+ return fileResult('complete');
+ });
+ await expect(read({ ...params, signal: inFlight.signal })).rejects.toBe(failure);
+});
diff --git a/packages/api/src/files/code/text.ts b/packages/api/src/files/code/text.ts
new file mode 100644
index 0000000000..a86c827c85
--- /dev/null
+++ b/packages/api/src/files/code/text.ts
@@ -0,0 +1,59 @@
+import type { CodeApiExecutionProfile, FileRefs } from '@librechat/agents';
+import type { SandboxImageReadResult } from './image';
+import type { ServerRequest } from '~/types';
+
+export interface SandboxTextReadParams {
+ file_path: string;
+ session_id?: string;
+ files?: Array<FileRefs[number] & { session_id?: string }>;
+ runtime_session_hint?: string;
+ codeApiBaseUrl?: string;
+ executionProfile?: CodeApiExecutionProfile;
+ bridgeWorkerId?: string;
+ executionRouteKey?: string;
+ req?: ServerRequest;
+ /** Requests the complete file within this byte budget, not a truncated prefix. */
+ maxBytes?: number;
+ signal?: AbortSignal;
+}
+
+export type SandboxTextReadResult =
+ | { content: string; complete?: true }
+ | { tooLarge: true; reason: 'size' | 'round_trips'; bytes: number }
+ | null;
+
+export type SandboxTextReader = (params: SandboxTextReadParams) => Promise<SandboxTextReadResult>;
+
+/** Reuses windowed byte transport; omission preserves the legacy text-read contract. */
+export function createSandboxTextReader({
+ readFile,
+ readBytes,
+}: {
+ readFile: (params: SandboxTextReadParams) => Promise<{ content: string } | null>;
+ readBytes: (params: SandboxTextReadParams) => Promise<SandboxImageReadResult>;
+}): SandboxTextReader {
+ return async (params) => {
+ if (params.maxBytes == null) return readFile(params);
+ if (!Number.isSafeInteger(params.maxBytes) || params.maxBytes < 1) {
+ throw new Error('Invalid sandbox text-read byte budget.');
+ }
+ params.signal?.throwIfAborted();
+ const result = await readBytes(params);
+ params.signal?.throwIfAborted();
+ if (result == null) return null;
+ if ('tooLarge' in result) return result;
+ const buffer = Buffer.from(result.base64, 'base64');
+ if (
+ buffer.length !== result.bytes ||
+ buffer.length > params.maxBytes ||
+ buffer.toString('base64') !== result.base64
+ ) {
+ throw new Error('Sandbox text retrieval was incomplete. Use bash_tool to inspect the file.');
+ }
+ const content = buffer.toString('utf8');
+ if (!Buffer.from(content, 'utf8').equals(buffer)) {
+ throw new Error('Sandbox file is not UTF-8 text. Use bash_tool to process it.');
+ }
+ return { content, complete: true };
+ };
+}
diff --git a/packages/api/src/tools/classification.spec.ts b/packages/api/src/tools/classification.spec.ts
index 517e7d360e..5ca9b0faab 100644
--- a/packages/api/src/tools/classification.spec.ts
+++ b/packages/api/src/tools/classification.spec.ts
@@ -637,6 +637,9 @@ describe('classification.ts', () => {
environmentType: 'attached',
environmentId: 'attached',
bridgeWorkerId: workerId,
+ codeEnvironmentConfigSchema: {
+ limits: { defaultCommandTimeoutMs: 60_000, maxCommandTimeoutMs: 80_000 },
+ },
...(selected
? {
codeWorkspace: {
@@ -670,6 +673,26 @@ describe('classification.ts', () => {
result.toolDefinitions.find((tool) => tool.name === 'run_tools_with_bash')
?.description,
).toContain('selected persistent workspace');
+ const definition = result.toolDefinitions.find(
+ (tool) => tool.name === 'run_tools_with_bash',
+ );
+ expect(definition?.parameters).toMatchObject({
+ properties: {
+ code: { description: expect.stringContaining('ATTACHED WORKSPACE EXECUTION') },
+ timeout: {
+ default: 60_000,
+ description: expect.stringContaining('Configured cap: 80000 milliseconds'),
+ },
+ },
+ });
+ expect(definition?.parameters?.properties?.code?.description).toContain(
+ '${LIBRECHAT_CODE_DATA_DIR:-/mnt/data}',
+ );
+ if (!definitionsOnly) {
+ expect(
+ result.additionalTools.find((tool) => tool.name === 'run_tools_with_bash')?.schema,
+ ).toEqual(definition?.parameters);
+ }
} else expect(fetchSpy).not.toHaveBeenCalled();
} finally {
fetchSpy.mockRestore();
diff --git a/packages/data-provider/src/config.spec.ts b/packages/data-provider/src/config.spec.ts
index 0b8d43e383..72e479c429 100644
--- a/packages/data-provider/src/config.spec.ts
+++ b/packages/data-provider/src/config.spec.ts
@@ -711,6 +711,53 @@ describe('Agent Management authentication config', () => {
});
describe('attached code environment user config schema', () => {
+ it.each([1, 60_000, 300_000])(
+ 'accepts a foreground default of %i ms',
+ (defaultCommandTimeoutMs) => {
+ expect(
+ codeEnvironmentUserConfigSchema.parse({ limits: { defaultCommandTimeoutMs } }),
+ ).toEqual({
+ limits: { defaultCommandTimeoutMs },
+ });
+ },
+ );
+
+ it.each([0, -1, 0.5, 300_001, NaN, Infinity])(
+ 'rejects an invalid foreground default of %s',
+ (defaultCommandTimeoutMs) => {
+ expect(
+ codeEnvironmentUserConfigSchema.safeParse({ limits: { defaultCommandTimeoutMs } }).success,
+ ).toBe(false);
+ },
+ );
+
+ it.each([1, 200, 500])('accepts a default read window of %i lines', (defaultReadFileLines) => {
+ expect(codeEnvironmentUserConfigSchema.parse({ limits: { defaultReadFileLines } })).toEqual({
+ limits: { defaultReadFileLines },
+ });
+ });
+
+ it.each([0, -1, 0.5, 501, NaN, Infinity])(
+ 'rejects an invalid default read window of %s',
+ (defaultReadFileLines) => {
+ expect(
+ codeEnvironmentUserConfigSchema.safeParse({ limits: { defaultReadFileLines } }).success,
+ ).toBe(false);
+ },
+ );
+
+ it('keeps defaults optional and accepts a foreground default above the configured ceiling for runtime clamping', () => {
+ expect(codeEnvironmentUserConfigSchema.parse({})).toEqual({});
+ expect(codeEnvironmentUserConfigSchema.parse({ limits: {} })).toEqual({ limits: {} });
+ expect(
+ codeEnvironmentUserConfigSchema.parse({
+ limits: { defaultCommandTimeoutMs: 60_000, maxCommandTimeoutMs: 5_000 },
+ }),
+ ).toEqual({
+ limits: { defaultCommandTimeoutMs: 60_000, maxCommandTimeoutMs: 5_000 },
+ });
+ });
+
it.each([0, 1200, 300000])(
'preserves an admission budget of %i milliseconds',
(maxQueueWaitMs) => {
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index 597caeb977..cda40946ac 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -1231,6 +1231,10 @@ const codeEnvironmentPermissionFieldSchema = z
export const CODE_ENVIRONMENT_COMMAND_TIMEOUT_DEFAULT_MS = 30_000;
/** Protocol-level ceiling; deployments may only lower this value. */
export const CODE_ENVIRONMENT_COMMAND_TIMEOUT_HARD_MAX_MS = 5 * 60_000;
+/** Historical line window for attached workspace reads. */
+export const CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES = 200;
+/** Protocol-v1 read ceiling supported by existing workers. */
+export const CODE_ENVIRONMENT_READ_FILE_HARD_MAX_LINES = 500;
/**
* Client retry horizon across Code API admission windows. Also the hard cap:
* deployments may only lower it. `0` disables client retries, not the server's
@@ -1265,6 +1269,22 @@ export const codeEnvironmentUserConfigSchema = z
.optional(),
limits: z
.object({
+ /** Foreground Bash timeout when the call omits timeoutMs. Omission keeps 30 seconds;
+ * the effective command ceiling may lower this value. */
+ defaultCommandTimeoutMs: z
+ .number()
+ .int()
+ .min(1)
+ .max(CODE_ENVIRONMENT_COMMAND_TIMEOUT_HARD_MAX_MS)
+ .optional(),
+ /** Attached read_file line window when max_lines is omitted. Omission keeps 200 lines;
+ * the existing byte budget can truncate the result sooner. */
+ defaultReadFileLines: z
+ .number()
+ .int()
+ .min(1)
+ .max(CODE_ENVIRONMENT_READ_FILE_HARD_MAX_LINES)
+ .optional(),
/** Maximum timeout a Bash invocation may request. Omission preserves
* the historical 30-second command budget. */
maxCommandTimeoutMs: z