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

* feat: configure attached command and read defaults

* fix: separate programmatic timeout defaults from ceilings

* fix: retain attached programmatic schema instructions

* fix: honor explicit skill and sandbox read ranges

* fix: remove duplicate command imports after rebase

* fix: retrieve complete sandbox text before paging

---------

Co-authored-by: Lia <lia@librechat.ai>
This commit is contained in:
lia-by-librechat[bot] 2026-10-01 19:57:08 -04:00 • committed by GitHub
parent 92432e95d5
commit 59b772f132
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
23 changed files with 1751 additions and 135 deletions

View file

@ -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(() => ''),

View file

@ -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,

View file

@ -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({

View file

@ -2351,6 +2351,8 @@ async function loadToolsForExecution({
codeExecutionContext.codeEnvironmentConfigSchema,
codeExecutionContext.codeWorkspace?.maxCommandTimeoutMs,
),
defaultTimeoutMs:
codeExecutionContext.codeEnvironmentConfigSchema?.limits?.defaultCommandTimeoutMs,
maxQueueWaitMs: resolveAttachedWorkspaceQueueWaitMs(
codeExecutionContext.codeEnvironmentConfigSchema,
),

View file

@ -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,

View file

@ -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

View file

@ -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`

View file

@ -7212,6 +7212,345 @@ describe('createToolExecuteHandler', () => {
});
});
describe('read_file explicit skill text ranges', () => {
const sources = ['body', 'cached', 'streamed', 'sandbox'] as const;
const text = Array.from({ length: 660 }, (_, i) => `catalogue line ${i + 1}`).join('\n');
function readFixture(source: (typeof sources)[number], content = text, req?: never) {
const paths = {
body: 'skills/codegraph/SKILL.md',
cached: 'skills/codegraph/references/shapes.sql',
streamed: 'skills/codegraph/references/shapes.sql',
sandbox: '/mnt/data/catalogue.sql',
};
const path = paths[source];
const getSkillByName = jest.fn(async () => ({
_id: '507f1f77bcf86cd799439011' as unknown as never,
name: 'codegraph',
body: content,
fileCount: 1,
version: 1,
}));
const getSkillFileByPath = jest.fn(async () => ({
file_id: 'revision-a',
mimeType: 'text/plain',
bytes: Buffer.byteLength(content),
filepath: '/storage/codegraph/shapes.sql',
source: 'local',
relativePath: 'references/shapes.sql',
...(source === 'cached' ? { content, isBinary: false } : {}),
}));
const getDownloadStream = jest.fn(async () => Readable.from([Buffer.from(content)]));
const updateSkillFileContent = jest.fn(async () => undefined);
const readSandboxFile: NonNullable<ToolExecuteOptions['readSandboxFile']> = jest.fn(
async ({ maxBytes }) => {
if (maxBytes != null && Buffer.byteLength(content) > maxBytes) {
return {
tooLarge: true as const,
reason: 'size' as const,
bytes: Buffer.byteLength(content),
};
}
return { content, ...(maxBytes == null ? {} : { complete: true as const }) };
},
);
const handler = createToolExecuteHandler({
loadTools: async () => ({
loadedTools: [],
configurable: {
req: req ?? { user: { id: 'user-1' }, config: {} },
accessibleSkillIds: skillsInScope(),
activeSkillNames: new Set(['codegraph']),
codeEnvAvailable: source === 'sandbox',
},
}),
getSkillByName,
getSkillFileByPath,
getStrategyFunctions: () => ({ getDownloadStream }),
updateSkillFileContent,
readSandboxFile,
});
const read = async (range: { start_line?: number; max_lines?: number } = {}) => {
const [result] = await invokeHandler(handler, [
{ id: 'ranged-read', name: Constants.READ_FILE, args: { path, ...range } },
]);
return result;
};
return { path, read, getDownloadStream, updateSkillFileContent };
}
it.each(sources)(
'returns exactly lines 100–159 with continuation for %s text',
async (source) => {
const { read, path, updateSkillFileContent } = readFixture(source);
const result = await read({ start_line: 100, max_lines: 60 });
expect(result.status).toBe('success');
const numbered = String(result.content)
.split('\n')
.filter((line) => /^\s*\d+ \| /.test(line));
expect(numbered).toEqual(
Array.from({ length: 60 }, (_, i) => `${100 + i} | catalogue line ${100 + i}`),
);
expect(result.content).toContain(
`call read_file again with path "${path}" and start_line 160`,
);
expect(result.content).not.toContain('660 | catalogue line 660');
if (source === 'streamed') {
expect(updateSkillFileContent).toHaveBeenCalledWith(
expect.anything(),
'references/shapes.sql',
{ content: text, isBinary: false },
'revision-a',
);
}
},
);
it.each(sources)('preserves a no-range full read for %s text', async (source) => {
const { read, path } = readFixture(source);
const result = await read();
const numbered = text
.split('\n')
.map((line, i) => `${String(i + 1).padStart(3, ' ')} | ${line}`)
.join('\n');
let header = '';
if (source === 'body') header = `File: ${path}\n\n`;
else if (source !== 'sandbox')
header = `File: ${path} (${Buffer.byteLength(text)} bytes)\n\n`;
expect(result.content).toBe(header + numbered);
expect(result.content).not.toContain('more content');
});
it.each(sources)(
'uses 200 lines only when %s text supplies a partial range',
async (source) => {
const { read } = readFixture(source);
const startOnly = await read({ start_line: 100 });
expect(
String(startOnly.content)
.split('\n')
.filter((line) => /^\s*\d+ \| /.test(line)),
).toHaveLength(200);
expect(startOnly.content).toContain('start_line 300');
const limitOnly = await read({ max_lines: 2 });
expect(limitOnly.content).toContain('1 | catalogue line 1\n2 | catalogue line 2');
expect(limitOnly.content).toContain('start_line 3');
},
);
it.each(
sources.flatMap((source) => [
{ source, range: { start_line: 0 } },
{ source, range: { max_lines: 501 } },
{ source, range: { start_line: 1.5 } },
{ source, range: { max_lines: -1 } },
]),
)('rejects an invalid range for $source: $range', async ({ source, range }) => {
const result = await readFixture(source).read(range);
expect(result.status).toBe('error');
expect(result.errorMessage).toBe(
'start_line must be positive and max_lines must be between 1 and 500.',
);
});
it.each(sources)(
'reports the final and beyond-EOF pages without phantom lines for %s text',
async (source) => {
const { read } = readFixture(source);
const last = await read({ start_line: 650, max_lines: 60 });
expect(
String(last.content)
.split('\n')
.filter((line) => /^\s*\d+ \| /.test(line)),
).toHaveLength(11);
expect(last.content).not.toContain('more content');
const beyond = await read({ start_line: 700, max_lines: 60 });
expect(beyond.status).toBe('success');
expect(beyond.content).not.toMatch(/\d+ \| /);
expect(beyond.content).not.toContain('more content');
},
);
it.each(['body', 'cached', 'streamed'] as const)(
'blocks the full %s skill text before slicing a clean page',
async (source) => {
const req = {
user: { id: 'user-1' },
config: {
filters: {
skills: {
pii: {
fields: ['instructions', 'file_text'],
starterPatterns: [],
customPatterns: [{ id: 'secret', label: 'secret', regex: 'PROTECTED-SECRET' }],
},
},
},
},
} as never;
const result = await readFixture(
source,
`clean first line\nPROTECTED-SECRET\nlast`,
req,
).read({ start_line: 1, max_lines: 1 });
expect(result.status).toBe('error');
expect(result.errorMessage).toContain('content_filter_block');
expect(result.content).not.toContain('clean first line');
expect(result.errorMessage).not.toContain('PROTECTED-SECRET');
},
);
it.each(['cached', 'streamed', 'sandbox'] as const)(
'blocks full %s file text under the files policy before slicing',
async (source) => {
const req = {
user: { id: 'user-1' },
config: {
filters: {
files: {
pii: {
fields: ['content'],
starterPatterns: [],
customPatterns: [{ id: 'secret', label: 'secret', regex: 'PROTECTED-SECRET' }],
},
},
},
},
} as never;
const result = await readFixture(source, `clean first line\nPROTECTED-SECRET`, req).read({
max_lines: 1,
});
expect(result.status).toBe('error');
expect(result.errorMessage).toContain('content_filter_block');
expect(result.content).not.toContain('clean first line');
},
);
it.each(['body', 'cached'] as const)(
'bounds UTF-8 %s range output and continues at the first omitted line',
async (source) => {
const content = ['skip', '界'.repeat(80_000), '界'.repeat(10_000)].join('\n');
const result = await readFixture(source, content).read({ start_line: 2, max_lines: 2 });
expect(result.status).toBe('success');
expect(result.content).toContain('2 | ');
expect(result.content).not.toContain('3 | ');
expect(result.content).toContain('truncated at 262144 bytes');
expect(result.content).toContain('start_line 3');
expect(Buffer.byteLength(String(result.content), 'utf8')).toBeLessThan(262_450);
},
);
it.each(['body', 'cached'] as const)(
'does not advertise a non-progressing continuation for an oversized %s line',
async (source) => {
const result = await readFixture(source, '界'.repeat(100_000)).read({ max_lines: 1 });
expect(result.status).toBe('success');
expect(result.content).toContain('cannot be paged by line');
expect(result.content).not.toContain('call read_file again');
expect(result.content).not.toContain('<27>');
},
);
it('leaves skill binary metadata and image artifacts unchanged when range parameters are present', async () => {
const image = Buffer.from(
'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
'base64',
);
const bytesByPath = { 'chart.png': image, 'data.bin': Buffer.from([0, 1, 2]) };
const handler = createToolExecuteHandler({
loadTools: async () => ({
loadedTools: [],
configurable: {
req: { user: { id: 'user-1' }, config: {} },
accessibleSkillIds: skillsInScope(),
},
}),
getSkillByName: async () => ({
_id: '507f1f77bcf86cd799439011' as unknown as never,
name: 'binary-skill',
body: '# Binary',
fileCount: 2,
version: 1,
}),
getSkillFileByPath: async (_id, relativePath) => ({
mimeType: relativePath === 'chart.png' ? 'image/png' : 'application/octet-stream',
bytes: bytesByPath[relativePath as keyof typeof bytesByPath].length,
isBinary: true,
filepath: `/storage/${relativePath}`,
source: 'local',
relativePath,
}),
getStrategyFunctions: () => ({
getDownloadStream: async (_req, path) =>
Readable.from(bytesByPath[path.split('/').pop() as keyof typeof bytesByPath]),
}),
});
for (const path of ['skills/binary-skill/chart.png', 'skills/binary-skill/data.bin']) {
const results = await invokeHandler(handler, [
{ id: 'binary-full', name: Constants.READ_FILE, args: { path } },
{
id: 'binary-ranged',
name: Constants.READ_FILE,
args: { path, start_line: 100, max_lines: 60 },
},
]);
expect(results[1].status).toBe(results[0].status);
expect(results[1].content).toEqual(results[0].content);
expect(results[1].artifact).toEqual(results[0].artifact);
}
});
it('refuses incomplete or oversized sandbox text instead of reporting a false EOF', async () => {
const original = text;
const readSandboxFile: NonNullable<ToolExecuteOptions['readSandboxFile']> = jest.fn(
async () => ({ content: original.slice(0, 100) }),
);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [], configurable: { codeEnvAvailable: true } }),
readSandboxFile,
});
const [result] = await invokeHandler(handler, [
{
id: 'incomplete-prefix',
name: Constants.READ_FILE,
args: { path: '/mnt/data/catalogue.txt', start_line: 650, max_lines: 1 },
},
]);
expect(result.status).toBe('error');
expect(result.errorMessage).toContain('retrieval was incomplete');
expect(result.content).toBe('');
expect(readSandboxFile).toHaveBeenCalledWith(expect.objectContaining({ maxBytes: 262_144 }));
const tooLarge = await readFixture('sandbox', 'x'.repeat(262_145)).read({
start_line: 100,
max_lines: 1,
});
expect(tooLarge.status).toBe('error');
expect(tooLarge.errorMessage).toContain('retrieved completely');
expect(tooLarge.content).toBe('');
});
it('preserves streamed oversized-file metadata and avoids a download even with an explicit range', async () => {
const { read, getDownloadStream } = readFixture('streamed', 'x'.repeat(262_145));
for (const range of [{}, { start_line: 1, max_lines: 1 }]) {
expect((await read(range)).content).toContain('too large to read directly');
}
expect(getDownloadStream).not.toHaveBeenCalled();
});
it.each(sources)(
'keeps blank lines and trailing-newline numbering unchanged for a no-range %s read',
async (source) => {
const { read } = readFixture(source, 'first\n\nlast\n');
const full = await read();
expect(full.content).toContain('1 | first\n2 | \n3 | last\n4 | ');
const page = await read({ start_line: 2, max_lines: 2 });
expect(page.content).toContain('2 | \n3 | last');
expect(page.content).not.toContain('4 | ');
expect(page.content).not.toContain('more content');
},
);
});
describe('read_file sandbox fallback (code-env paths + non-skill segments)', () => {
function makeReadFileHandler(params: {
codeEnvAvailable?: boolean;
@ -7319,6 +7658,73 @@ describe('createToolExecuteHandler', () => {
});
});
it.each([200, 500])(
'reads the configured %i-line window and preserves explicit pagination',
async (defaultReadFileLines) => {
const lines = Array.from({ length: 450 }, (_, i) => `line ${i + 1}`);
const readWorkspaceFile = jest.fn<
ReturnType<NonNullable<ToolExecuteOptions['readWorkspaceFile']>>,
Parameters<NonNullable<ToolExecuteOptions['readWorkspaceFile']>>
>(async ({ start_line = 1, max_lines = 200 }) => {
const selected = lines.slice(start_line - 1, start_line - 1 + max_lines);
const endLine = start_line + selected.length - 1;
return {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'notes.txt',
content: selected.join('\n'),
startLine: start_line,
endLine,
truncated: endLine < lines.length,
...(endLine < lines.length ? { nextStartLine: endLine + 1 } : {}),
};
});
const handler = makeReadFileHandler({
codeEnvAvailable: true,
readWorkspaceFile,
codeExecutionContext: {
baseUrl: 'https://code.example.com/v1',
codeSessionKey: 'execute_code:stateful:attached',
executionProfile: 'stateful',
environmentType: 'attached',
statefulSessions: true,
codeEnvironmentConfigSchema: { limits: { defaultReadFileLines } },
},
});
const [result] = await invokeHandler(handler, [
{
id: 'call_configured_window',
name: Constants.READ_FILE,
args: { path: 'workspace/notes.txt' },
},
]);
expect(readWorkspaceFile).toHaveBeenCalledWith(
expect.objectContaining({ start_line: 1, max_lines: defaultReadFileLines }),
);
expect(result.status).toBe('success');
if (defaultReadFileLines === 500) {
expect(result.content).toContain('450 | line 450');
expect(result.content).not.toContain('more content');
} else {
expect(result.content).toContain('200 | line 200');
expect(result.content).toContain('start_line 201');
}
const [page] = await invokeHandler(handler, [
{
id: 'call_explicit_window',
name: Constants.READ_FILE,
args: { path: 'workspace/notes.txt', start_line: 10, max_lines: 2 },
},
]);
expect(readWorkspaceFile).toHaveBeenLastCalledWith(
expect.objectContaining({ start_line: 10, max_lines: 2 }),
);
expect(page.content).toContain('10 | line 10\n11 | line 11');
expect(page.content).toContain('start_line 12');
},
);
it('forwards the run abort signal to attached workspace reads', async () => {
const readWorkspaceFile = jest.fn(async () => ({
protocolVersion: 1 as const,

View file

@ -8,6 +8,8 @@ import {
} from '@librechat/data-schemas';
import {
AGENT_BACKGROUND_COMPLETION_RESULT_MAX_CHARS_DEFAULT,
CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES,
CODE_ENVIRONMENT_READ_FILE_HARD_MAX_LINES,
hasActivePiiFields,
hasActivePiiPatterns,
hasToolCallErrorPrefix,
@ -53,6 +55,7 @@ import type {
import type { SkillFileRecord, PrimeSkillFilesResult } from './skillFiles';
import type { ArtifactDeliveryFailure } from '~/files/code';
import type { BackgroundToolResultState } from './harvest';
import type { SandboxTextReader } from '~/files/code/text';
import type { WorkspaceEditMatching } from '~/code/edits';
import type { CodeExecutionContext } from './execution';
import type { TextContentFragment } from '~/protection';
@ -99,6 +102,12 @@ import {
isCodeSessionToolName,
isFileResourceToolName,
} from './tools';
import {
resolveAttachedWorkspaceReadFileLines,
WorkspaceToolHttpError,
WORKSPACE_EDIT_MAX_COUNT,
WORKSPACE_WRITE_MAX_BYTES,
} from '~/code/workspace';
import {
BACKGROUND_TASK_ABORT_GRACE_MS,
BACKGROUND_TASK_SHUTDOWN_MESSAGE,
@ -122,11 +131,6 @@ import {
contentFilterModelBoundBlockResponse,
isContentFilterError,
} from '~/middleware/contentFilter';
import {
WorkspaceToolHttpError,
WORKSPACE_EDIT_MAX_COUNT,
WORKSPACE_WRITE_MAX_BYTES,
} from '~/code/workspace';
import {
hasIntentArg,
stripIntentArg,
@ -685,29 +689,8 @@ export interface ToolExecuteOptions {
maxRequestTimeoutMs?: number;
deadlineAtMs?: number;
}) => Promise<WorkspaceEditResult>;
/**
* Reads a code-execution sandbox file by shelling `cat` through the
* sandbox `/exec` endpoint. The host implementation supplies the
* codeapi base URL + auth and forwards the seeded `session_id` and
* `files` so the read lands in the same sandbox session that holds
* the agent's prior-turn artifacts. Returns `null` when codeapi is
* unavailable; throws on transport errors so the handler can surface
* a meaningful error message to the model.
*/
readSandboxFile?: (params: {
file_path: string;
session_id?: string;
files?: SandboxFileRef[];
/** Per-conversation stateful runtime-session hint (thread_id); forwarded so a
* host file op that is the first sandbox call joins the same runtime session
* as bash_tool instead of the Code API's default session. */
runtime_session_hint?: string;
codeApiBaseUrl?: string;
executionProfile?: CodeExecutionContext['executionProfile'];
bridgeWorkerId?: string;
executionRouteKey?: string;
req?: ServerRequest;
}) => Promise<{ content: string } | null>;
/** Bounded reads return complete text; omitted maxBytes retains the legacy stdout path. */
readSandboxFile?: SandboxTextReader;
/**
* Reads a small image file out of the code-execution sandbox as base64 so
* `read_file` can surface it to vision-capable models. The `readSandboxFile`
@ -1055,6 +1038,97 @@ function addLineNumbers(content: string, startLine = 1): string {
.join('\n');
}
type ReadFileRangeArguments = { start_line?: number; max_lines?: number };
type ReadFileRange = { startLine: number; maxLines: number };
const READ_FILE_RANGE_ERROR =
'start_line must be positive and max_lines must be between 1 and 500.';
function resolveReadFileRange(
args: ReadFileRangeArguments,
defaultMaxLines = CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES,
): ReadFileRange | null {
const startLine = args.start_line ?? 1;
const maxLines = args.max_lines ?? defaultMaxLines;
return Number.isSafeInteger(startLine) &&
startLine >= 1 &&
Number.isSafeInteger(maxLines) &&
maxLines >= 1 &&
maxLines <= CODE_ENVIRONMENT_READ_FILE_HARD_MAX_LINES
? { startLine, maxLines }
: null;
}
/** Full local files are sliced once; a worker page is already offset and bounded. */
function formatReadFileText(
content: string,
path: string,
range?: ReadFileRange,
page?: { startLine: number; nextStartLine?: number },
): string {
let payload = content;
const startLine = page?.startLine ?? range?.startLine ?? 1;
let nextStartLine = page?.nextStartLine;
if (range != null && page == null) {
let start = 0;
for (let line = 1; line < range.startLine; line++) {
const newline = content.indexOf('\n', start);
if (newline < 0) return '';
start = newline + 1;
}
if (start >= content.length) return '';
let end = content.length;
let cursor = start;
for (let count = 1; count <= range.maxLines; count++) {
const newline = content.indexOf('\n', cursor);
if (newline < 0) break;
if (count === range.maxLines || newline === content.length - 1) {
end = newline;
if (newline < content.length - 1) nextStartLine = startLine + count;
break;
}
cursor = newline + 1;
}
payload = content.slice(start, end);
}
let locallyTruncated = false;
let localNextStartLine: number | undefined;
if ((range != null || page != null) && Buffer.byteLength(payload, 'utf8') > MAX_READABLE_BYTES) {
payload = truncateUtf8(payload, MAX_READABLE_BYTES);
locallyTruncated = true;
const lastCompleteLine = payload.lastIndexOf('\n');
if (lastCompleteLine >= 0) {
payload = payload.slice(0, lastCompleteLine);
localNextStartLine = startLine + payload.split('\n').length;
}
}
let numbered = addLineNumbers(payload, startLine);
if (locallyTruncated) {
numbered +=
localNextStartLine != null
? `\n\n[truncated at ${MAX_READABLE_BYTES} bytes; more content is available; call read_file again with path "${path}" and start_line ${localNextStartLine}]`
: `\n\n[the line was truncated at ${MAX_READABLE_BYTES} bytes and cannot be paged by line]`;
} else if (nextStartLine != null) {
numbered += `\n\n[more content is available; call read_file again with path "${path}" and start_line ${nextStartLine}]`;
}
return numbered;
}
function localTextReadResult(
tc: ToolCallRequest,
path: string,
content: string,
header = '',
): ToolExecuteResult {
const args = tc.args as ReadFileRangeArguments;
const range =
args.start_line === undefined && args.max_lines === undefined
? undefined
: resolveReadFileRange(args);
if (range === null) return errorResult(tc, READ_FILE_RANGE_ERROR);
return successResult(tc, header + formatReadFileText(content, path, range));
}
type AuthoringSkill = NonNullable<
Awaited<ReturnType<NonNullable<ToolExecuteOptions['getSkillByName']>>>
>;
@ -2529,6 +2603,10 @@ async function handleSandboxFileFallback(
};
}
const rangeArgs = tc.args as ReadFileRangeArguments;
const ranged = rangeArgs.start_line !== undefined || rangeArgs.max_lines !== undefined;
if (ranged && resolveReadFileRange(rangeArgs) == null)
return errorResult(tc, READ_FILE_RANGE_ERROR);
const ctx = tc.codeSessionContext as SandboxSessionContext | undefined;
try {
const result = await readSandboxFile({
@ -2537,7 +2615,20 @@ async function handleSandboxFileFallback(
files: ctx?.files,
...codeExecutionRequestParams(codeExecutionContext),
...(req ? { req } : {}),
...(ranged ? { maxBytes: MAX_READABLE_BYTES, ...(signal ? { signal } : {}) } : {}),
});
if (result != null && 'tooLarge' in result) {
return errorResult(
tc,
`Sandbox file could not be retrieved completely within the ${MAX_READABLE_BYTES}-byte read budget. Use bash_tool to inspect it.`,
);
}
if (ranged && result != null && result.complete !== true) {
return errorResult(
tc,
'Sandbox text retrieval was incomplete. Use bash_tool to inspect the file.',
);
}
if (!result || result.content == null) {
return {
toolCallId: tc.id,
@ -2567,13 +2658,18 @@ async function handleSandboxFileFallback(
* and surface the truncation to the model so it can use
* `bash_tool head` / `tail` for the rest.
*/
if (ranged) {
const rangedResult = localTextReadResult(tc, filePath, result.content);
if (rangedResult.status === 'success') onSuccess?.();
return rangedResult;
}
let payload = result.content;
let truncated = false;
if (payload.length > MAX_READABLE_BYTES) {
payload = payload.slice(0, MAX_READABLE_BYTES);
truncated = true;
}
let numbered = addLineNumbers(payload);
let numbered = formatReadFileText(payload, filePath);
if (truncated) {
numbered += `\n\n[truncated at ${MAX_READABLE_BYTES} bytes — use \`bash_tool\` (e.g. \`head -c\` / \`tail\`) to read the rest of "${filePath}"]`;
}
@ -2584,6 +2680,7 @@ async function handleSandboxFileFallback(
content: numbered,
};
} catch (error) {
if (signal?.aborted === true && isAbortError(error)) throw error;
const message = error instanceof Error ? error.message : String(error);
logger.warn('[handleReadFileCall] Sandbox fallback failed', getSafeErrorMetadata(error));
return {
@ -2615,8 +2712,10 @@ async function handleWorkspaceFileRead(
const workspaceId = selectedWorkspaceId(codeExecutionContext, 'read_file');
if (!workspaceId) return unavailableWorkspaceOperation(tc, 'read_file');
const args = tc.args as { start_line?: number; max_lines?: number };
const startLine = args.start_line ?? 1;
const maxLines = args.max_lines ?? 200;
const range = resolveReadFileRange(
args,
resolveAttachedWorkspaceReadFileLines(codeExecutionContext.codeEnvironmentConfigSchema),
);
if (filePath.length === 0) {
return {
toolCallId: tc.id,
@ -2625,20 +2724,7 @@ async function handleWorkspaceFileRead(
errorMessage: 'A relative path after workspace/ is required.',
};
}
if (
!Number.isSafeInteger(startLine) ||
startLine < 1 ||
!Number.isSafeInteger(maxLines) ||
maxLines < 1 ||
maxLines > 500
) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: 'start_line must be positive and max_lines must be between 1 and 500.',
};
}
if (range == null) return errorResult(tc, READ_FILE_RANGE_ERROR);
const filteredName = filteredFileNameResult(tc, req, filePath);
if (filteredName != null) {
return filteredName;
@ -2652,8 +2738,8 @@ async function handleWorkspaceFileRead(
? { workspace_instance_id: codeExecutionContext.codeWorkspace.workspaceInstanceId }
: {}),
...(codeExecutionContext.codeWorkspace?.linkedWorktrees ? { linked_worktrees: true } : {}),
start_line: startLine,
max_lines: maxLines,
start_line: range.startLine,
max_lines: range.maxLines,
codeApiBaseUrl: codeExecutionContext.baseUrl,
...attachedWorkspaceRequestLimits(codeExecutionContext),
executionProfile: codeExecutionContext.executionProfile,
@ -2675,32 +2761,15 @@ async function handleWorkspaceFileRead(
errorMessage: `"${filePath}" appears to be a binary file and cannot be read as text.`,
};
}
let payload = result.content;
let locallyTruncated = false;
let localNextStartLine: number | undefined;
if (Buffer.byteLength(payload, 'utf8') > MAX_READABLE_BYTES) {
payload = truncateUtf8(payload, MAX_READABLE_BYTES);
locallyTruncated = true;
const lastCompleteLine = payload.lastIndexOf('\n');
if (lastCompleteLine >= 0) {
payload = payload.slice(0, lastCompleteLine);
localNextStartLine = result.startLine + payload.split('\n').length;
}
}
let numbered = addLineNumbers(payload, result.startLine);
if (locallyTruncated) {
numbered +=
localNextStartLine != null
? `\n\n[truncated at ${MAX_READABLE_BYTES} bytes; more content is available; call read_file again with path "workspace/${filePath}" and start_line ${localNextStartLine}]`
: `\n\n[the line was truncated at ${MAX_READABLE_BYTES} bytes and cannot be paged by line]`;
} else if (result.truncated && result.nextStartLine != null) {
numbered += `\n\n[more content is available; call read_file again with path "workspace/${filePath}" and start_line ${result.nextStartLine}]`;
}
return {
toolCallId: tc.id,
status: 'success',
content: numbered,
};
return successResult(
tc,
formatReadFileText(result.content, `workspace/${filePath}`, undefined, {
startLine: result.startLine,
...(result.truncated && result.nextStartLine != null
? { nextStartLine: result.nextStartLine }
: {}),
}),
);
} catch (error) {
if (error instanceof WorkspaceToolHttpError) throw error;
if (signal?.aborted === true && isAbortError(error)) throw error;
@ -3080,6 +3149,12 @@ async function loadSandboxTextForAuthoring({
...codeExecutionRequestParams(codeExecutionContext),
...(req ? { req } : {}),
});
if (result != null && 'tooLarge' in result) {
return {
status: 'error',
message: 'Sandbox file could not be retrieved completely. Use bash_tool to inspect it.',
};
}
if (!result || result.content == null) {
return {
status: 'error',
@ -5121,11 +5196,7 @@ async function handleReadFileCall(
if (filtered != null) {
return filtered;
}
return {
toolCallId: tc.id,
status: 'success',
content: `File: ${args.path}\n\n${addLineNumbers(skill.body)}`,
};
return localTextReadResult(tc, args.path, skill.body, `File: ${args.path}\n\n`);
}
/* Bundled skill files are primed into the sandbox under the `skills/`
@ -5187,11 +5258,12 @@ async function handleReadFileCall(
if (fileFiltered != null) {
return fileFiltered;
}
return {
toolCallId: tc.id,
status: 'success',
content: `File: ${args.path} (${file.bytes} bytes)\n\n${addLineNumbers(file.content)}`,
};
return localTextReadResult(
tc,
args.path,
file.content,
`File: ${args.path} (${file.bytes} bytes)\n\n`,
);
}
// Early size check from DB metadata before streaming
@ -5340,11 +5412,12 @@ async function handleReadFileCall(
};
}
return {
toolCallId: tc.id,
status: 'success',
content: `File: ${args.path} (${buffer.length} bytes)\n\n${addLineNumbers(text)}`,
};
return localTextReadResult(
tc,
args.path,
text,
`File: ${args.path} (${buffer.length} bytes)\n\n`,
);
} catch (error) {
return {
toolCallId: tc.id,

View file

@ -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,

View file

@ -440,6 +440,8 @@ export interface InjectSkillCatalogParams {
workspaceOperations?: ReadonlySet<CodeWorkspaceOperation>;
/** Deployment ceiling advertised on attached Bash tool definitions. */
workspaceCommandTimeoutMaxMs?: number;
workspaceCommandTimeoutDefaultMs?: number;
workspaceReadFileDefaultLines?: number;
workspaceEnvironment?: CodeWorkspaceDescriptor['environment'];
/** The worker runs `.worktrees/<name>` in its own lane; advertise `cwd` routing to the model. */
workspaceLinkedWorktrees?: boolean;
@ -678,6 +680,8 @@ export async function injectSkillCatalog(
workspaceTools,
workspaceOperations,
workspaceCommandTimeoutMaxMs,
workspaceCommandTimeoutDefaultMs,
workspaceReadFileDefaultLines,
workspaceEnvironment,
workspaceLinkedWorktrees,
userId,
@ -865,6 +869,8 @@ export async function injectSkillCatalog(
workspaceTools: workspaceTools === true,
workspaceOperations,
workspaceCommandTimeoutMaxMs,
workspaceCommandTimeoutDefaultMs,
workspaceReadFileDefaultLines,
workspaceEnvironment,
workspaceLinkedWorktrees,
});

View file

@ -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(),

View file

@ -1,10 +1,3 @@
import {
Tools,
Constants,
normalizeActionToolName,
normalizeServerName,
splitMCPToolKey,
} from 'librechat-data-provider';
import {
Constants as AgentConstants,
CODE_EXECUTION_TOOLS,
@ -13,6 +6,15 @@ import {
SkillToolDefinition,
buildBashExecutionToolDescription,
} from '@librechat/agents';
import {
Tools,
Constants,
CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES,
CODE_ENVIRONMENT_READ_FILE_HARD_MAX_LINES,
normalizeActionToolName,
normalizeServerName,
splitMCPToolKey,
} from 'librechat-data-provider';
import type {
AgentToolOptions,
CodeWorkspaceOperation,
@ -438,6 +440,8 @@ export interface RegisterCodeExecutionToolsParams {
workspaceOperations?: ReadonlySet<CodeWorkspaceOperation>;
/** Deployment ceiling advertised on attached Bash tool definitions. */
workspaceCommandTimeoutMaxMs?: number;
workspaceCommandTimeoutDefaultMs?: number;
workspaceReadFileDefaultLines?: number;
workspaceEnvironment?: CodeWorkspaceDescriptor['environment'];
/** The worker runs `.worktrees/<name>` in its own lane; advertise `cwd` routing to the model. */
workspaceLinkedWorktrees?: boolean;
@ -488,22 +492,43 @@ export interface RegisterFileAuthoringToolsParams {
workspaceOperations?: ReadonlySet<CodeWorkspaceOperation>;
}
/**
* Hoisted module-level definition for skill-aware `read_file` so
* `registerCodeExecutionTools` doesn't re-allocate on every call. The
* shape is derived from a static `@librechat/agents` export — no
* per-request state — so a single frozen object is safe to share across
* every agent init.
*/
/** Locally extends SDK read parameters without changing the SDK path or intent contract. */
const READ_FILE_RANGE_PROPERTIES = Object.freeze({
start_line: {
type: 'integer',
minimum: 1,
description: 'Optional one-based starting line for a skill, sandbox, or workspace text file.',
},
max_lines: {
type: 'integer',
minimum: 1,
maximum: CODE_ENVIRONMENT_READ_FILE_HARD_MAX_LINES,
description: `Optional line limit for a skill, sandbox, or workspace text file. Defaults to ${CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES} when either range parameter is supplied for skill or sandbox text; the byte budget may truncate sooner.`,
},
});
const READ_FILE_RANGE_INSTRUCTIONS = `Omit both range parameters for full skill/sandbox reads; range defaults: 1/${CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES}.`;
const SKILL_READ_FILE_PARAMETERS = Object.freeze({
...ReadFileToolDefinition.parameters,
required: [...(ReadFileToolDefinition.parameters.required ?? ['path'])],
properties: {
...ReadFileToolDefinition.parameters.properties,
...READ_FILE_RANGE_PROPERTIES,
},
}) as LCTool['parameters'];
const SKILL_READ_FILE_DESCRIPTION = `${ReadFileToolDefinition.description}
Also accepts authored skill file paths using "skills/{skillName}/...", including "skills/{skillName}/SKILL.md".`;
Also accepts authored skill file paths using "skills/{skillName}/...", including "skills/{skillName}/SKILL.md".
${READ_FILE_RANGE_INSTRUCTIONS}`;
const READ_FILE_DEF: LCTool = Object.freeze({
name: ReadFileToolDefinition.name,
toolType: 'builtin',
description: SKILL_READ_FILE_DESCRIPTION,
parameters: ReadFileToolDefinition.parameters as unknown as LCTool['parameters'],
parameters: SKILL_READ_FILE_PARAMETERS,
responseFormat: ReadFileToolDefinition.responseFormat,
}) as LCTool;
@ -511,13 +536,17 @@ const CODE_READ_FILE_DESCRIPTION = `Read a known code-sandbox file. Text is line
Use paths returned by tool output, just written, or under /mnt/data/. Do not run ls/find to rediscover known paths. Use bash_tool for binary or large files, transforms, metadata, and filesystem discovery.
For managed execution, only retained files under /mnt/data reach later calls. $HOME, /tmp, $TMPDIR, shell/environment state, cwd, global installs, and background processes are call-local.`;
For managed execution, only retained files under /mnt/data reach later calls. $HOME, /tmp, $TMPDIR, shell/environment state, cwd, global installs, and background processes are call-local.
${READ_FILE_RANGE_INSTRUCTIONS}`;
const ATTACHED_WORKSPACE_READ_FILE_INSTRUCTIONS = `For an attached environment, read registered files as "workspace/{relativePath}". Use a canonical relative path without empty, ".", or ".." segments; the worker's host path stays private. Only the registered workspace persists for attached commands. Project dependencies stored there persist, while $HOME and global/system packages are operator-managed. Use start_line and max_lines for bounded pagination.`;
const CODE_READ_FILE_PARAMETERS: LCTool['parameters'] = Object.freeze({
...SKILL_READ_FILE_PARAMETERS,
type: 'object',
properties: {
...SKILL_READ_FILE_PARAMETERS?.properties,
path: {
type: 'string',
description:
@ -527,24 +556,23 @@ const CODE_READ_FILE_PARAMETERS: LCTool['parameters'] = Object.freeze({
required: ['path'],
}) as LCTool['parameters'];
function attachedReadFileLineDescription(defaultReadFileLines: number): string {
return `Optional line limit for a skill, sandbox, or workspace text file. Defaults to ${defaultReadFileLines} for workspace reads and ${CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES} for explicit skill or sandbox ranges. Omit both range parameters for a full skill or sandbox read. The byte budget may truncate the result sooner.`;
}
const ATTACHED_WORKSPACE_READ_FILE_PARAMETERS: LCTool['parameters'] = Object.freeze({
...SKILL_READ_FILE_PARAMETERS,
type: 'object',
properties: {
...SKILL_READ_FILE_PARAMETERS?.properties,
path: {
type: 'string',
description:
'Use "workspace/{relativePath}" with a canonical relative path (no empty, ".", or ".." segments) for a file in the attached worker workspace directory, or a code-execution sandbox path such as "/mnt/data/result.csv".',
},
start_line: {
type: 'integer',
minimum: 1,
description: 'Optional one-based line at which to start reading a workspace text file.',
},
max_lines: {
type: 'integer',
minimum: 1,
maximum: 500,
description: 'Optional maximum number of workspace text-file lines to return.',
...READ_FILE_RANGE_PROPERTIES.max_lines,
description: attachedReadFileLineDescription(CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES),
},
},
required: ['path'],
@ -558,7 +586,10 @@ const CODE_READ_FILE_DEF: LCTool = Object.freeze({
responseFormat: ReadFileToolDefinition.responseFormat,
}) as LCTool;
function createAttachedWorkspaceReadFileDef(includeSkillFileInstructions: boolean): LCTool {
function createAttachedWorkspaceReadFileDef(
includeSkillFileInstructions: boolean,
defaultReadFileLines: number = CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES,
): LCTool {
const baseDescription = includeSkillFileInstructions
? SKILL_READ_FILE_DESCRIPTION
: CODE_READ_FILE_DESCRIPTION;
@ -566,7 +597,19 @@ function createAttachedWorkspaceReadFileDef(includeSkillFileInstructions: boolea
name: ReadFileToolDefinition.name,
toolType: 'builtin',
description: `${baseDescription}\n\n${ATTACHED_WORKSPACE_READ_FILE_INSTRUCTIONS}`,
parameters: ATTACHED_WORKSPACE_READ_FILE_PARAMETERS,
parameters:
defaultReadFileLines === CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES
? ATTACHED_WORKSPACE_READ_FILE_PARAMETERS
: {
...ATTACHED_WORKSPACE_READ_FILE_PARAMETERS,
properties: {
...ATTACHED_WORKSPACE_READ_FILE_PARAMETERS?.properties,
max_lines: {
...ATTACHED_WORKSPACE_READ_FILE_PARAMETERS?.properties?.max_lines,
description: attachedReadFileLineDescription(defaultReadFileLines),
},
},
},
responseFormat: ReadFileToolDefinition.responseFormat,
}) as LCTool;
}
@ -970,8 +1013,15 @@ const ATTACHED_SKILL_EDIT_FILE_DEF: LCTool = Object.freeze({
parameters: attachedFileAuthoringParameters(SKILL_EDIT_FILE_PARAMETERS, true),
}) as LCTool;
function buildReadFileDef(includeSkillFileInstructions: boolean, workspaceTools: boolean): LCTool {
function buildReadFileDef(
includeSkillFileInstructions: boolean,
workspaceTools: boolean,
defaultReadFileLines: number = CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES,
): LCTool {
if (workspaceTools) {
if (defaultReadFileLines !== CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES) {
return createAttachedWorkspaceReadFileDef(includeSkillFileInstructions, defaultReadFileLines);
}
return includeSkillFileInstructions
? ATTACHED_SKILL_READ_FILE_DEF
: ATTACHED_CODE_READ_FILE_DEF;
@ -1055,6 +1105,7 @@ function createBashToolDef(
workspaceCommandTimeoutMaxMs?: number,
workspaceEnvironment?: CodeWorkspaceDescriptor['environment'],
workspaceLinkedWorktrees = false,
workspaceCommandTimeoutDefaultMs?: number,
): LCTool {
/* Passed as a variable (not an inline literal) so the extra
* `statefulSessions` key stays assignable against pinned SDK versions
@ -1071,6 +1122,7 @@ function createBashToolDef(
workspaceCommandTimeoutMaxMs,
workspaceEnvironment,
workspaceLinkedWorktrees,
workspaceCommandTimeoutDefaultMs,
)
: BashExecutionToolDefinition.schema) as unknown as LCTool['parameters'],
}) as LCTool;
@ -1084,6 +1136,7 @@ function buildBashToolDef(opts: {
statefulSessions?: boolean;
workspaceTools?: boolean;
workspaceCommandTimeoutMaxMs?: number;
workspaceCommandTimeoutDefaultMs?: number;
workspaceEnvironment?: CodeWorkspaceDescriptor['environment'];
/** The worker runs `.worktrees/<name>` in its own lane; advertise `cwd` routing to the model. */
workspaceLinkedWorktrees?: boolean;
@ -1098,6 +1151,7 @@ function buildBashToolDef(opts: {
opts.workspaceCommandTimeoutMaxMs,
opts.workspaceEnvironment,
opts.workspaceLinkedWorktrees === true,
opts.workspaceCommandTimeoutDefaultMs,
);
}
return opts.enableToolOutputReferences
@ -1130,6 +1184,8 @@ export function registerCodeExecutionTools(
workspaceTools = false,
workspaceOperations,
workspaceCommandTimeoutMaxMs,
workspaceCommandTimeoutDefaultMs,
workspaceReadFileDefaultLines,
workspaceEnvironment,
workspaceLinkedWorktrees,
enableToolOutputReferences = false,
@ -1140,7 +1196,9 @@ export function registerCodeExecutionTools(
!workspaceTools || workspaceOperations?.has(operation) === true;
const candidates: LCTool[] = [];
if (!workspaceTools || supportsWorkspaceOperation('read_file')) {
candidates.push(buildReadFileDef(includeSkillFileInstructions, workspaceTools));
candidates.push(
buildReadFileDef(includeSkillFileInstructions, workspaceTools, workspaceReadFileDefaultLines),
);
} else if (includeSkillFileInstructions) {
candidates.push(buildReadFileDef(true, false));
}
@ -1151,6 +1209,7 @@ export function registerCodeExecutionTools(
statefulSessions,
workspaceTools,
workspaceCommandTimeoutMaxMs,
workspaceCommandTimeoutDefaultMs,
workspaceEnvironment,
workspaceLinkedWorktrees,
}),

View file

@ -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<string, unknown> = {}): Response {
}
describe('createAttachedWorkspaceBashTool', () => {
test.each([
[60_000, 80_000, undefined, 60_000],
[120_000, 80_000, undefined, 80_000],
[60_000, 80_000, 65_000, 45_000],
[60_000, 5_000, undefined, 5_000],
[1, 80_000, undefined, 1],
])(
'bounds foreground default %i by ceiling %i and HTTP budget %s',
async (defaultTimeoutMs, maxTimeoutMs, maxRequestTimeoutMs, expected) => {
const fetchImpl: CodeBridgeFetch = jest.fn(async () => commandResponse());
const bashTool = createAttachedWorkspaceBashTool({
baseUrl: 'https://code.example.com/v1',
authHeaders: () => ({}),
workspaceId: 'project-a',
defaultTimeoutMs,
maxTimeoutMs,
maxRequestTimeoutMs,
fetchImpl,
});
await bashTool.invoke({ command: 'npm test' });
expect(JSON.parse(String((fetchImpl as jest.Mock).mock.calls[0][1]?.body))).toMatchObject({
timeoutMs: expected,
});
expect(bashTool.schema).toMatchObject({
properties: {
timeoutMs: {
description: expect.stringContaining(`Defaults to ${expected} for foreground calls`),
},
},
});
},
);
test('keeps explicit and background timeouts independent of the foreground default', async () => {
const fetchImpl: CodeBridgeFetch = jest.fn(async () => commandResponse());
const bashTool = createAttachedWorkspaceBashTool({
baseUrl: 'https://code.example.com/v1',
authHeaders: () => ({}),
workspaceId: 'project-a',
defaultTimeoutMs: 60_000,
maxTimeoutMs: 80_000,
fetchImpl,
});
await bashTool.invoke({ command: 'npm test', timeoutMs: 10_000 });
await bashTool.invoke(
{ command: 'npm test' },
{ configurable: { [BACKGROUND_TOOL_INVOCATION_CONFIG_KEY]: true } },
);
await bashTool.invoke(
{ command: 'npm test', timeoutMs: 20_000 },
{ configurable: { [BACKGROUND_TOOL_INVOCATION_CONFIG_KEY]: true } },
);
expect(
(fetchImpl as jest.Mock).mock.calls.map(
([, init]) => JSON.parse(String(init?.body)).timeoutMs,
),
).toEqual([10_000, 80_000, 20_000]);
});
test.each([0, -1, 1.5, NaN, Infinity])(
'falls back safely for invalid foreground default %s',
(defaultTimeoutMs) => {
expect(resolveAttachedWorkspaceCommandTimeoutDefault(defaultTimeoutMs, 80_000)).toBe(30_000);
},
);
test('does not raise the command ceiling when only a foreground default is configured', () => {
const maxTimeoutMs = resolveAttachedWorkspaceCommandTimeoutMax({
limits: { defaultCommandTimeoutMs: 60_000 },
});
expect(maxTimeoutMs).toBe(30_000);
expect(resolveAttachedWorkspaceCommandTimeoutDefault(60_000, maxTimeoutMs)).toBe(30_000);
const upstreamMax = resolveAttachedWorkspaceCommandTimeoutMax(
{ limits: { defaultCommandTimeoutMs: 60_000 } },
50_000,
);
expect(resolveAttachedWorkspaceCommandTimeoutDefault(60_000, upstreamMax)).toBe(50_000);
});
test('honors a zero Code API rate-limit retry budget', async () => {
const fetchImpl: CodeBridgeFetch = jest.fn(
async () => new Response(JSON.stringify({ error: 'rate_limited' }), { status: 429 }),
@ -729,6 +1050,31 @@ describe('createAttachedWorkspaceBashTool', () => {
expect(request.command).not.toContain('git config');
});
test('reports the requested timeout and effective retry ceiling after HTTP-budget clamping', async () => {
const fetchImpl: CodeBridgeFetch = jest.fn(async () =>
commandResponse({ exitCode: null, timedOut: true, stdout: 'partial work', stderr: '' }),
);
const bashTool = createAttachedWorkspaceBashTool({
baseUrl: 'https://code.example.com/v1',
authHeaders: () => ({}),
workspaceId: 'project-a',
defaultTimeoutMs: 60_000,
maxTimeoutMs: 80_000,
maxRequestTimeoutMs: 90_000,
fetchImpl,
});
const [content] = await bashTool.func(
{ command: 'npm test', timeoutMs: 10_000 },
undefined,
{},
);
expect(content).toContain('partial work');
expect(content).toContain('timeoutMs: 10000');
expect(content).toContain('up to 70000 milliseconds');
expect(content).not.toContain('up to 80000');
expect(content).toContain('partial side effects');
});
test('reports termination, timeouts, and truncation without hiding stderr', async () => {
const fetchImpl: CodeBridgeFetch = jest.fn(async () =>
commandResponse({
@ -748,7 +1094,7 @@ describe('createAttachedWorkspaceBashTool', () => {
});
await expect(bashTool.func({ command: 'sleep 60' }, undefined, {})).resolves.toEqual([
'stderr:\ndeadline reached\n[terminated by SIGKILL][timed out][output truncated]',
'stderr:\ndeadline reached\n[terminated by SIGKILL][timed out][output truncated]\nCommand reached timeoutMs: 30000. Before retrying, check for partial side effects. Set timeoutMs explicitly up to 30000 milliseconds, or use run_in_background: true if available. Background execution uses the same timeout ceiling.',
{},
]);
});

View file

@ -11,6 +11,7 @@ import type {
CodeEnvironmentUserConfigSchema,
CodeWorkspaceDescriptor,
} from 'librechat-data-provider';
import type { createBashProgrammaticToolCallingSchema } from '@librechat/agents';
import type { DynamicStructuredTool } from '@librechat/agents/langchain/tools';
import type { LCTool } from '@librechat/agents';
import type { WorkspaceExecuteCommandResult } from './workspace';
@ -108,8 +109,14 @@ interface BoundedTimeoutSchema {
description: string;
}
function buildAttachedTimeoutSchema(maxTimeoutMs: number): BoundedTimeoutSchema {
const defaultTimeoutMs = Math.min(WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS, maxTimeoutMs);
function buildAttachedTimeoutSchema(
maxTimeoutMs: number,
foregroundTimeoutMs: number,
): BoundedTimeoutSchema {
const defaultTimeoutMs = resolveAttachedWorkspaceCommandTimeoutDefault(
foregroundTimeoutMs,
maxTimeoutMs,
);
return {
type: 'integer',
minimum: 1,
@ -125,6 +132,17 @@ function normalizeAttachedWorkspaceCommandTimeoutMax(maxTimeoutMs: number): numb
return Math.min(WORKSPACE_COMMAND_MAX_TIMEOUT_MS, maxTimeoutMs);
}
/** Foreground defaults never raise the negotiated execution ceiling. */
export function resolveAttachedWorkspaceCommandTimeoutDefault(
defaultTimeoutMs: number = WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS,
maxTimeoutMs: number = WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS,
): number {
return Math.min(
normalizeAttachedWorkspaceCommandTimeoutMax(defaultTimeoutMs),
normalizeAttachedWorkspaceCommandTimeoutMax(maxTimeoutMs),
);
}
export function resolveAttachedWorkspaceCommandTimeoutMax(
configSchema?: CodeEnvironmentUserConfigSchema,
upstreamMaxTimeoutMs?: number,
@ -161,13 +179,18 @@ function fitCommandTimeoutMaxToBudget(
/**
* Programmatic calls do not currently carry the detached-invocation marker.
* Preserve their historical foreground default while still enforcing both an
* explicit administrator override and the live upstream ceiling.
* The SDK's runTimeoutMs is a ceiling, not an omission-only default. When the
* environment configures a foreground default, resolve its ceiling separately;
* otherwise retain the legacy maxCommandTimeoutMs behavior on this SDK route.
*/
export function resolveAttachedWorkspaceProgrammaticTimeout(
configSchema?: CodeEnvironmentUserConfigSchema,
upstreamMaxTimeoutMs?: number,
): number {
const defaultTimeoutMs = configSchema?.limits?.defaultCommandTimeoutMs;
if (defaultTimeoutMs != null) {
return resolveAttachedWorkspaceCommandTimeoutMax(configSchema, upstreamMaxTimeoutMs);
}
const configured = configSchema?.limits?.maxCommandTimeoutMs;
const requested =
configured == null
@ -219,6 +242,7 @@ export function buildAttachedWorkspaceBashSchema(
maxTimeoutMs: number = WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS,
environment?: CodeWorkspaceDescriptor['environment'],
linkedWorktrees = false,
defaultTimeoutMs: number = WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS,
): NonNullable<LCTool['parameters']> {
const effectiveMaxTimeoutMs = normalizeAttachedWorkspaceCommandTimeoutMax(maxTimeoutMs);
return {
@ -230,7 +254,7 @@ export function buildAttachedWorkspaceBashSchema(
linkedWorktrees === true
? linkedWorktreeWorkingDirectorySchema
: attachedWorkingDirectorySchema,
timeoutMs: buildAttachedTimeoutSchema(effectiveMaxTimeoutMs),
timeoutMs: buildAttachedTimeoutSchema(effectiveMaxTimeoutMs, defaultTimeoutMs),
...(environment?.actions.length
? {
environmentAction: {
@ -326,7 +350,35 @@ export function createContextProgrammaticBashTool(
}
: {}),
};
return createGitIdentityProgrammaticBashTool(options, attached ? identity : undefined);
const bashTool = createGitIdentityProgrammaticBashTool(options, attached ? identity : undefined);
const configuredDefault = attached
? context.codeEnvironmentConfigSchema?.limits?.defaultCommandTimeoutMs
: undefined;
if (configuredDefault == null) return bashTool;
const maxTimeoutMs = options.runTimeoutMs ?? WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS;
const schema = structuredClone(bashTool.schema) as ReturnType<
typeof createBashProgrammaticToolCallingSchema
>;
const minimumTimeoutMs = schema.properties.timeout.minimum;
if (maxTimeoutMs < minimumTimeoutMs) {
throw new Error(
`Attached programmatic execution requires a timeout ceiling of at least ${minimumTimeoutMs} milliseconds. Use bash_tool for shorter command budgets.`,
);
}
const defaultTimeoutMs = Math.max(
minimumTimeoutMs,
resolveAttachedWorkspaceCommandTimeoutDefault(configuredDefault, maxTimeoutMs),
);
schema.properties.timeout.default = defaultTimeoutMs;
schema.properties.timeout.description = `Maximum wall-clock time in milliseconds for one sandbox run or replay iteration, not the total multi-round-trip task budget. Default: ${defaultTimeoutMs} milliseconds when timeout is omitted. Accepted values above the configured cap are clamped before execution. Configured cap: ${maxTimeoutMs} milliseconds.`;
bashTool.schema = schema;
const execute = bashTool.func.bind(bashTool);
bashTool.func = (input, ...args) => {
const params = input as { timeout?: number };
return execute({ ...params, timeout: params.timeout ?? defaultTimeoutMs }, ...args);
};
return bashTool;
}
/** Apply authorship before the SDK prepares the script and its replay requests. */
@ -344,7 +396,11 @@ export function createGitIdentityProgrammaticBashTool(
return bashTool;
}
function formatCommandResult(result: WorkspaceExecuteCommandResult): string {
function formatCommandResult(
result: WorkspaceExecuteCommandResult,
timeoutMs: number,
maxTimeoutMs: number,
): string {
let output = '';
if (result.stdout.length > 0) output += `stdout:\n${result.stdout}\n`;
if (result.stderr.length > 0) output += `stderr:\n${result.stderr}\n`;
@ -353,6 +409,9 @@ function formatCommandResult(result: WorkspaceExecuteCommandResult): string {
if (result.signal != null) output += `[terminated by ${result.signal}]`;
if (result.timedOut) output += '[timed out]';
if (result.truncated) output += '[output truncated]';
if (result.timedOut) {
output += `\nCommand reached timeoutMs: ${timeoutMs}. Before retrying, check for partial side effects. Set timeoutMs explicitly up to ${maxTimeoutMs} milliseconds, or use run_in_background: true if available. Background execution uses the same timeout ceiling.`;
}
return output;
}
@ -364,6 +423,7 @@ export function createAttachedWorkspaceBashTool({
environment,
gitIdentity,
maxTimeoutMs = WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS,
defaultTimeoutMs = WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS,
maxQueueWaitMs,
codeApiMaxRetryWaitMs,
maxRequestTimeoutMs,
@ -381,6 +441,8 @@ export function createAttachedWorkspaceBashTool({
gitIdentity?: AgentGitIdentity | null;
/** Effective admin/upstream ceiling already intersected with the protocol hard cap. */
maxTimeoutMs?: number;
/** Foreground timeout when omitted by the model; bounded by the effective ceiling. */
defaultTimeoutMs?: number;
/** Retry horizon across typed queue expirations, not an admission budget. */
maxQueueWaitMs?: number;
codeApiMaxRetryWaitMs?: number;
@ -395,8 +457,17 @@ export function createAttachedWorkspaceBashTool({
maxRequestTimeoutMs,
minCommandAdmissionMs,
);
const effectiveDefaultTimeoutMs = resolveAttachedWorkspaceCommandTimeoutDefault(
defaultTimeoutMs,
effectiveMaxTimeoutMs,
);
const schema = structuredClone(
buildAttachedWorkspaceBashSchema(effectiveMaxTimeoutMs, environment, linkedWorktrees),
buildAttachedWorkspaceBashSchema(
effectiveMaxTimeoutMs,
environment,
linkedWorktrees,
effectiveDefaultTimeoutMs,
),
);
const actions = environment?.actions ?? [];
const bashTool = tool(
@ -437,7 +508,7 @@ export function createAttachedWorkspaceBashTool({
rawInput.timeoutMs ??
(config?.configurable?.[BACKGROUND_TOOL_INVOCATION_CONFIG_KEY] === true
? effectiveMaxTimeoutMs
: Math.min(WORKSPACE_COMMAND_DEFAULT_TIMEOUT_MS, effectiveMaxTimeoutMs));
: effectiveDefaultTimeoutMs);
const signal = config?.signal;
const trace = {
runId: config?.metadata?.run_id,
@ -478,7 +549,7 @@ export function createAttachedWorkspaceBashTool({
throw new Error('Attached workspace returned an unexpected command result.');
}
logger.debug('[BYOMCommand] transport completed', trace);
return [formatCommandResult(result), {}];
return [formatCommandResult(result, timeoutMs, effectiveMaxTimeoutMs), {}];
} finally {
signal?.removeEventListener('abort', onAbort);
logger.debug('[BYOMCommand] transport settled', {

View file

@ -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 () => {

View file

@ -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,

View file

@ -12,3 +12,4 @@ export * from './priming';
export * from './process';
export * from './publication';
export * from './snapshot';
export * from './text';

View file

@ -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);
});

View file

@ -0,0 +1,59 @@
import type { CodeApiExecutionProfile, FileRefs } from '@librechat/agents';
import type { SandboxImageReadResult } from './image';
import type { ServerRequest } from '~/types';
export interface SandboxTextReadParams {
file_path: string;
session_id?: string;
files?: Array<FileRefs[number] & { session_id?: string }>;
runtime_session_hint?: string;
codeApiBaseUrl?: string;
executionProfile?: CodeApiExecutionProfile;
bridgeWorkerId?: string;
executionRouteKey?: string;
req?: ServerRequest;
/** Requests the complete file within this byte budget, not a truncated prefix. */
maxBytes?: number;
signal?: AbortSignal;
}
export type SandboxTextReadResult =
| { content: string; complete?: true }
| { tooLarge: true; reason: 'size' | 'round_trips'; bytes: number }
| null;
export type SandboxTextReader = (params: SandboxTextReadParams) => Promise<SandboxTextReadResult>;
/** Reuses windowed byte transport; omission preserves the legacy text-read contract. */
export function createSandboxTextReader({
readFile,
readBytes,
}: {
readFile: (params: SandboxTextReadParams) => Promise<{ content: string } | null>;
readBytes: (params: SandboxTextReadParams) => Promise<SandboxImageReadResult>;
}): SandboxTextReader {
return async (params) => {
if (params.maxBytes == null) return readFile(params);
if (!Number.isSafeInteger(params.maxBytes) || params.maxBytes < 1) {
throw new Error('Invalid sandbox text-read byte budget.');
}
params.signal?.throwIfAborted();
const result = await readBytes(params);
params.signal?.throwIfAborted();
if (result == null) return null;
if ('tooLarge' in result) return result;
const buffer = Buffer.from(result.base64, 'base64');
if (
buffer.length !== result.bytes ||
buffer.length > params.maxBytes ||
buffer.toString('base64') !== result.base64
) {
throw new Error('Sandbox text retrieval was incomplete. Use bash_tool to inspect the file.');
}
const content = buffer.toString('utf8');
if (!Buffer.from(content, 'utf8').equals(buffer)) {
throw new Error('Sandbox file is not UTF-8 text. Use bash_tool to process it.');
}
return { content, complete: true };
};
}

View file

@ -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();

View file

@ -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) => {

View file

@ -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