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: 'agent@example.com' }, 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 = 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 = 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>, + Parameters> + >(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; - /** - * 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>> >; @@ -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; /** Deployment ceiling advertised on attached Bash tool definitions. */ workspaceCommandTimeoutMaxMs?: number; + workspaceCommandTimeoutDefaultMs?: number; + workspaceReadFileDefaultLines?: number; workspaceEnvironment?: CodeWorkspaceDescriptor['environment']; /** The worker runs `.worktrees/` 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; /** Deployment ceiling advertised on attached Bash tool definitions. */ workspaceCommandTimeoutMaxMs?: number; + workspaceCommandTimeoutDefaultMs?: number; + workspaceReadFileDefaultLines?: number; workspaceEnvironment?: CodeWorkspaceDescriptor['environment']; /** The worker runs `.worktrees/` in its own lane; advertise `cwd` routing to the model. */ workspaceLinkedWorktrees?: boolean; @@ -488,22 +492,43 @@ export interface RegisterFileAuthoringToolsParams { workspaceOperations?: ReadonlySet; } -/** - * 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/` 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: 'lia@example.com' } : 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: 'lia@example.com' }, + ); + 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 = {}): 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 { 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; + 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; + +/** 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; +}): 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