Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import { logger } from '@librechat/data-schemas';
import { codeEnvironmentAdmissionSchema } from 'librechat-data-provider';
import type { WorkspaceToolRequest } from './workspace';
import type { CodeBridgeFetch } from './bridge';
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 () => {
const workspaceInstanceId = 'd'.repeat(64);
const fetchImpl = jest.fn().mockResolvedValue(
new Response(
JSON.stringify({
protocolVersion: 1,
operation: 'write_file',
workspaceId: 'primary',
path: 'notes.txt',
created: true,
bytesWritten: 5,
}),
{ status: 200, headers: { 'Content-Type': 'application/json' } },
),
);
await executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
request: {
protocolVersion: 1,
operation: 'write_file',
workspaceId: 'primary',
workspaceInstanceId,
path: 'notes.txt',
content: 'ready',
},
});
expect(JSON.parse(fetchImpl.mock.calls[0][1].body)).toMatchObject({ workspaceInstanceId });
});
test('rejects malformed workspace instance identifiers before transport', async () => {
const fetchImpl = jest.fn();
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
request: {
protocolVersion: 1,
operation: 'list_files',
workspaceId: 'primary',
workspaceInstanceId: 'conversation-1',
},
}),
).rejects.toBeInstanceOf(WorkspaceToolHttpError);
expect(fetchImpl).not.toHaveBeenCalled();
});
test('identifies definite pre-execution expiry without retrying the operation', async () => {
const fetchImpl = jest.fn().mockResolvedValue(
new Response(JSON.stringify({ code: 'WORKSPACE_QUEUE_TIMEOUT' }), {
status: 503,
headers: { 'Retry-After': '1' },
}),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
maxQueueWaitMs: 0,
request: {
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
command: 'echo test',
},
}),
).rejects.toThrow('The operation was not started');
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
test('keeps one tool call queued when capacity expires before admission', async () => {
const unavailable = () =>
new Response(JSON.stringify({ code: 'WORKSPACE_QUEUE_TIMEOUT' }), {
status: 503,
headers: { 'Retry-After': '0' },
});
const fetchImpl = jest
.fn()
.mockResolvedValueOnce(unavailable())
.mockResolvedValueOnce(unavailable())
.mockResolvedValueOnce(
new Response(
JSON.stringify({
protocolVersion: 1,
operation: 'edit_file',
workspaceId: 'primary',
path: 'src/app.ts',
replacements: 1,
bytesWritten: 24,
}),
{ status: 200, headers: { 'Content-Type': 'application/json' } },
),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
request: {
protocolVersion: 1,
operation: 'edit_file',
workspaceId: 'primary',
path: 'src/app.ts',
edits: [{ oldText: 'const old = true;', newText: 'const ready = true;' }],
},
}),
).resolves.toMatchObject({ operation: 'edit_file', replacements: 1 });
expect(fetchImpl).toHaveBeenCalledTimes(3);
expect(fetchImpl.mock.calls.map((call) => call[1]?.body)).toEqual([
fetchImpl.mock.calls[0][1]?.body,
fetchImpl.mock.calls[0][1]?.body,
fetchImpl.mock.calls[0][1]?.body,
]);
});
test('mints fresh credentials for every admission attempt', async () => {
let minted = 0;
const authHeaders = jest.fn(async () => ({ Authorization: `Bearer token-${++minted}` }));
const fetchImpl = jest
.fn()
.mockResolvedValueOnce(
new Response(JSON.stringify({ code: 'WORKSPACE_QUEUE_TIMEOUT' }), {
status: 503,
headers: { 'Retry-After': '0' },
}),
)
.mockResolvedValueOnce(
new Response(
JSON.stringify({
protocolVersion: 1,
operation: 'edit_file',
workspaceId: 'primary',
path: 'src/app.ts',
replacements: 1,
bytesWritten: 24,
}),
{ status: 200, headers: { 'Content-Type': 'application/json' } },
),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders,
fetchImpl,
request: {
protocolVersion: 1,
operation: 'edit_file',
workspaceId: 'primary',
path: 'src/app.ts',
edits: [{ oldText: 'const old = true;', newText: 'const ready = true;' }],
},
}),
).resolves.toMatchObject({ operation: 'edit_file' });
// A token minted before the first capacity window expires within the
// admission budget, so reusing it would fail the retry with a 401.
expect(authHeaders).toHaveBeenCalledTimes(2);
expect(
fetchImpl.mock.calls.map(
(call) => (call[1]?.headers as Record<string, string>).Authorization,
),
).toEqual(['Bearer token-1', 'Bearer token-2']);
});
test('never opens another admission window once the queue budget is spent', async () => {
jest.useFakeTimers();
try {
const fetchImpl = jest.fn().mockResolvedValue(
new Response(JSON.stringify({ code: 'WORKSPACE_QUEUE_TIMEOUT' }), {
status: 503,
headers: { 'Retry-After': '1' },
}),
);
const result = executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
maxQueueWaitMs: 150,
request: {
protocolVersion: 1,
operation: 'edit_file',
workspaceId: 'primary',
path: 'src/app.ts',
edits: [{ oldText: 'const old = true;', newText: 'const ready = true;' }],
},
}).catch((error: Error) => error);
await jest.advanceTimersByTimeAsync(150);
expect(await result).toMatchObject({
message: expect.stringContaining('The operation was not started'),
});
// The clamped wait lands on the deadline: a further dispatch could still be
// admitted and run a long command after the budget expired.
expect(fetchImpl).toHaveBeenCalledTimes(1);
} finally {
jest.useRealTimers();
}
});
test.each([true, false])(
'does not dispatch when cancelled before or during credential refresh (%s)',
async (beforeRefresh) => {
const controller = new AbortController();
const reason = new DOMException('Stopped', 'AbortError');
const authHeaders = jest.fn(async () => {
controller.abort(reason);
return {};
});
const fetchImpl = jest.fn();
if (beforeRefresh) controller.abort(reason);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders,
fetchImpl,
signal: controller.signal,
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'src/app.ts',
},
}),
).rejects.toBe(reason);
expect(fetchImpl).not.toHaveBeenCalled();
expect(authHeaders).toHaveBeenCalledTimes(beforeRefresh ? 0 : 1);
},
);
test('cancels a stalled credential refresh without opening a workspace admission window', async () => {
const controller = new AbortController();
const reason = new DOMException('Chat stopped', 'AbortError');
const fetchImpl = jest.fn();
let entered!: () => void;
const started = new Promise<void>((resolve) => {
entered = resolve;
});
const operation = executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: async () => {
entered();
return new Promise<Record<string, string>>(() => {});
},
request: {
protocolVersion: 1,
operation: 'edit_file',
workspaceId: 'primary',
path: 'src/app.ts',
edits: [{ oldText: 'a', newText: 'b' }],
},
signal: controller.signal,
maxRequestTimeoutMs: 125_000,
fetchImpl,
});
await started;
controller.abort(reason);
await expect(operation).rejects.toBe(reason);
expect(fetchImpl).not.toHaveBeenCalled();
});
test('does not dispatch a retry if credential refresh spends the remaining queue budget', async () => {
const now = jest.spyOn(Date, 'now').mockReturnValue(1000);
const authHeaders = jest
.fn()
.mockResolvedValueOnce({})
.mockImplementationOnce(async () => {
now.mockReturnValue(2000);
return {};
});
const fetchImpl = jest.fn().mockResolvedValueOnce(
new Response(JSON.stringify({ code: 'WORKSPACE_QUEUE_TIMEOUT' }), {
status: 503,
headers: { 'Retry-After': '0' },
}),
);
try {
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders,
fetchImpl,
maxQueueWaitMs: 1000,
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'src/app.ts',
},
}),
).rejects.toThrow('The operation was not started');
expect(authHeaders).toHaveBeenCalledTimes(2);
expect(fetchImpl).toHaveBeenCalledTimes(1);
} finally {
now.mockRestore();
}
});
test('stops waiting for capacity when the chat is cancelled', async () => {
const controller = new AbortController();
const reason = new DOMException('Stopped', 'AbortError');
const fetchImpl = jest.fn().mockResolvedValue(
new Response(JSON.stringify({ code: 'WORKSPACE_QUEUE_TIMEOUT' }), {
status: 503,
headers: { 'Retry-After': '1' },
}),
);
const request = executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
signal: controller.signal,
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'src/app.ts',
},
});
while (fetchImpl.mock.calls.length === 0) await Promise.resolve();
controller.abort(reason);
await expect(request).rejects.toBe(reason);
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
test('cancels a typed rate-limit wait without replaying the request', async () => {
jest.useFakeTimers();
try {
const controller = new AbortController();
const reason = new DOMException('Stopped', 'AbortError');
const fetchImpl = jest
.fn()
.mockResolvedValueOnce(
new Response(JSON.stringify({ error: 'rate_limited' }), {
status: 429,
headers: { 'Retry-After': '1' },
}),
)
.mockResolvedValueOnce(new Response('{}', { status: 504 }));
const request = executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
signal: controller.signal,
fetchImpl,
maxQueueWaitMs: 0,
request: { protocolVersion: 1, operation: 'read_file', workspaceId: 'primary', path: 'x' },
});
await jest.advanceTimersByTimeAsync(1);
controller.abort(reason);
await expect(request).rejects.toBe(reason);
await jest.advanceTimersByTimeAsync(1_000);
expect(fetchImpl).toHaveBeenCalledTimes(1);
} finally {
jest.useRealTimers();
}
});
test('retries a Code API rate limit, which rejects before the operation starts', async () => {
const rateLimited = () =>
new Response(
JSON.stringify({
error: 'rate_limited',
message: 'Too many CodeAPI execution requests. Please retry in 1 second.',
retry_after_seconds: 1,
}),
{ status: 429, headers: { 'Retry-After': '0' } },
);
const fetchImpl = jest
.fn()
.mockResolvedValueOnce(rateLimited())
.mockResolvedValueOnce(rateLimited())
.mockResolvedValueOnce(
new Response(
JSON.stringify({
protocolVersion: 1,
operation: 'edit_file',
workspaceId: 'primary',
path: 'src/app.ts',
replacements: 1,
bytesWritten: 24,
}),
{ status: 200, headers: { 'Content-Type': 'application/json' } },
),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
request: {
protocolVersion: 1,
operation: 'edit_file',
workspaceId: 'primary',
path: 'src/app.ts',
edits: [{ oldText: 'const old = true;', newText: 'const ready = true;' }],
},
}),
).resolves.toMatchObject({ operation: 'edit_file', replacements: 1 });
expect(fetchImpl).toHaveBeenCalledTimes(3);
const bodies = fetchImpl.mock.calls.map((call) => call[1]?.body);
expect(new Set(bodies).size).toBe(1);
});
test.each([
['missing', undefined],
['invalid', 'invalid'],
['overflowing', '9'.repeat(400)],
] as const)('uses the typed 429 body delay when Retry-After is %s', async (_case, retryAfter) => {
jest.useFakeTimers();
try {
const fetchImpl = jest
.fn()
.mockResolvedValueOnce(
new Response(JSON.stringify({ error: 'rate_limited', retry_after_seconds: 2 }), {
status: 429,
...(retryAfter ? { headers: { 'Retry-After': retryAfter } } : {}),
}),
)
.mockResolvedValueOnce(new Response('{}', { status: 504 }));
const result = executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
codeApiMaxRetryWaitMs: 3_000,
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'x',
},
}).catch((error: WorkspaceToolHttpError) => error);
await jest.advanceTimersByTimeAsync(1_999);
expect(fetchImpl).toHaveBeenCalledTimes(1);
await jest.advanceTimersByTimeAsync(1);
await expect(result).resolves.toMatchObject({ upstreamStatus: 504 });
expect(fetchImpl).toHaveBeenCalledTimes(2);
} finally {
jest.useRealTimers();
}
});
test.each([-1, 300_001, 1.5, Number.NaN])(
'rejects an invalid Code API retry limit of %p before transport',
async (codeApiMaxRetryWaitMs) => {
const fetchImpl = jest.fn();
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
codeApiMaxRetryWaitMs,
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'x',
},
}),
).rejects.toMatchObject({ reason: 'invalid' });
expect(fetchImpl).not.toHaveBeenCalled();
},
);
test.each([0, 150])('bounds typed 429 retries to the %i ms Code API budget', async (budget) => {
jest.useFakeTimers();
try {
const fetchImpl = jest.fn().mockImplementation(
() =>
new Response(JSON.stringify({ error: 'rate_limited', retry_after_seconds: 0 }), {
status: 429,
headers: { 'Retry-After': '0' },
}),
);
const result = executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
codeApiMaxRetryWaitMs: budget,
request: { protocolVersion: 1, operation: 'read_file', workspaceId: 'primary', path: 'x' },
}).catch((error: WorkspaceToolHttpError) => error);
await jest.advanceTimersByTimeAsync(budget);
await expect(result).resolves.toMatchObject({
upstreamStatus: 429,
message: expect.stringContaining('The operation was not started'),
});
expect(fetchImpl).toHaveBeenCalledTimes(budget === 0 ? 1 : 2);
} finally {
jest.useRealTimers();
}
});
test('does not wait when a 429 retry hint exceeds the Code API budget', async () => {
const fetchImpl = jest.fn().mockResolvedValue(
new Response(JSON.stringify({ error: 'rate_limited', retry_after_seconds: 30 }), {
status: 429,
}),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
request: { protocolVersion: 1, operation: 'read_file', workspaceId: 'primary', path: 'x' },
}),
).rejects.toMatchObject({ upstreamStatus: 429 });
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
test('keeps queue retries enabled when Code API rate-limit retries are disabled', async () => {
jest.useFakeTimers();
try {
const fetchImpl = jest
.fn()
.mockResolvedValueOnce(
new Response(JSON.stringify({ code: 'WORKSPACE_QUEUE_TIMEOUT' }), {
status: 503,
headers: { 'Retry-After': '0' },
}),
)
.mockResolvedValueOnce(
new Response(JSON.stringify({ error: 'rate_limited' }), { status: 429 }),
);
const result = executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
codeApiMaxRetryWaitMs: 0,
request: { protocolVersion: 1, operation: 'read_file', workspaceId: 'primary', path: 'x' },
}).catch((error: WorkspaceToolHttpError) => error);
await jest.advanceTimersByTimeAsync(100);
await expect(result).resolves.toMatchObject({ upstreamStatus: 429 });
expect(fetchImpl).toHaveBeenCalledTimes(2);
} finally {
jest.useRealTimers();
}
});
test('does not charge queue waits to the Code API rate-limit budget', async () => {
jest.useFakeTimers();
try {
const fetchImpl = jest
.fn()
.mockResolvedValueOnce(
new Response(JSON.stringify({ error: 'rate_limited' }), {
status: 429,
headers: { 'Retry-After': '0' },
}),
)
.mockResolvedValueOnce(
new Response(JSON.stringify({ code: 'WORKSPACE_QUEUE_TIMEOUT' }), {
status: 503,
headers: { 'Retry-After': '0' },
}),
)
.mockResolvedValueOnce(new Response('{}', { status: 504 }));
const result = executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
codeApiMaxRetryWaitMs: 100,
request: { protocolVersion: 1, operation: 'read_file', workspaceId: 'primary', path: 'x' },
}).catch((error: WorkspaceToolHttpError) => error);
await jest.advanceTimersByTimeAsync(200);
await expect(result).resolves.toMatchObject({ upstreamStatus: 504 });
expect(fetchImpl).toHaveBeenCalledTimes(3);
} finally {
jest.useRealTimers();
}
});
test.each([0, 50])(
'retries typed 429s after a %i ms queue horizon without re-enabling capacity retries',
async (maxQueueWaitMs) => {
jest.useFakeTimers();
try {
const fetchImpl = jest
.fn()
.mockResolvedValueOnce(
new Response(JSON.stringify({ error: 'rate_limited' }), {
status: 429,
headers: { 'Retry-After': '0' },
}),
)
.mockResolvedValueOnce(new Response('{}', { status: 504 }));
const result = executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
maxQueueWaitMs,
codeApiMaxRetryWaitMs: 100,
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'x',
},
}).catch((error: WorkspaceToolHttpError) => error);
await jest.advanceTimersByTimeAsync(100);
await expect(result).resolves.toMatchObject({ upstreamStatus: 504 });
expect(fetchImpl).toHaveBeenCalledTimes(2);
} finally {
jest.useRealTimers();
}
},
);
test('continues 429 recovery after a queue retry but never extends its capacity horizon', async () => {
jest.useFakeTimers();
try {
const fetchImpl = jest
.fn()
.mockResolvedValueOnce(
new Response(JSON.stringify({ code: 'WORKSPACE_QUEUE_TIMEOUT' }), {
status: 503,
headers: { 'Retry-After': '0' },
}),
)
.mockResolvedValueOnce(
new Response(JSON.stringify({ error: 'rate_limited' }), {
status: 429,
headers: { 'Retry-After': '0' },
}),
)
.mockResolvedValueOnce(new Response('{}', { status: 504 }));
const result = executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
maxQueueWaitMs: 150,
codeApiMaxRetryWaitMs: 100,
request: { protocolVersion: 1, operation: 'read_file', workspaceId: 'primary', path: 'x' },
}).catch((error: WorkspaceToolHttpError) => error);
await jest.advanceTimersByTimeAsync(200);
await expect(result).resolves.toMatchObject({ upstreamStatus: 504 });
expect(fetchImpl).toHaveBeenCalledTimes(3);
} finally {
jest.useRealTimers();
}
});
test('never borrows the rate-limit horizon to retry a later capacity timeout', async () => {
jest.useFakeTimers();
try {
const fetchImpl = jest
.fn()
.mockResolvedValueOnce(
new Response(JSON.stringify({ error: 'rate_limited' }), {
status: 429,
headers: { 'Retry-After': '0' },
}),
)
.mockResolvedValueOnce(
new Response(JSON.stringify({ code: 'WORKSPACE_QUEUE_TIMEOUT' }), {
status: 503,
headers: { 'Retry-After': '0' },
}),
)
.mockResolvedValueOnce(new Response('{}', { status: 504 }));
const result = executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
maxQueueWaitMs: 50,
codeApiMaxRetryWaitMs: 200,
request: { protocolVersion: 1, operation: 'read_file', workspaceId: 'primary', path: 'x' },
}).catch((error: WorkspaceToolHttpError) => error);
await jest.advanceTimersByTimeAsync(100);
await expect(result).resolves.toMatchObject({ upstreamStatus: 503 });
expect(fetchImpl).toHaveBeenCalledTimes(2);
} finally {
jest.useRealTimers();
}
});
test('retries after an authorized rate-limit wait despite timer jitter', async () => {
jest.useFakeTimers();
const startedAt = Date.now();
let currentTime = startedAt;
jest.spyOn(Date, 'now').mockImplementation(() => currentTime);
try {
const fetchImpl = jest
.fn()
.mockResolvedValueOnce(
new Response(JSON.stringify({ error: 'rate_limited' }), {
status: 429,
headers: { 'Retry-After': '0' },
}),
)
.mockResolvedValueOnce(new Response('{}', { status: 504 }));
const result = executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
maxQueueWaitMs: 0,
codeApiMaxRetryWaitMs: 100,
request: { protocolVersion: 1, operation: 'read_file', workspaceId: 'primary', path: 'x' },
}).catch((error: WorkspaceToolHttpError) => error);
await jest.advanceTimersByTimeAsync(0);
expect(fetchImpl).toHaveBeenCalledTimes(1);
currentTime += 101;
await jest.advanceTimersByTimeAsync(100);
await expect(result).resolves.toMatchObject({ upstreamStatus: 504 });
expect(fetchImpl).toHaveBeenCalledTimes(2);
} finally {
jest.useRealTimers();
}
});
test('charges an overslept 429 wait before considering another retry', async () => {
jest.useFakeTimers();
const startedAt = Date.now();
let currentTime = startedAt;
jest.spyOn(Date, 'now').mockImplementation(() => currentTime);
try {
const rateLimited = () =>
new Response(JSON.stringify({ error: 'rate_limited' }), {
status: 429,
headers: { 'Retry-After': '0' },
});
const fetchImpl = jest
.fn()
.mockResolvedValueOnce(rateLimited())
.mockResolvedValueOnce(rateLimited())
.mockResolvedValueOnce(new Response('{}', { status: 504 }));
const result = executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
maxQueueWaitMs: 0,
codeApiMaxRetryWaitMs: 200,
request: { protocolVersion: 1, operation: 'read_file', workspaceId: 'primary', path: 'x' },
}).catch((error: WorkspaceToolHttpError) => error);
await jest.advanceTimersByTimeAsync(0);
currentTime += 150;
await jest.advanceTimersByTimeAsync(100);
await expect(result).resolves.toMatchObject({ upstreamStatus: 429 });
expect(fetchImpl).toHaveBeenCalledTimes(2);
} finally {
jest.useRealTimers();
}
});
test('reserves the caller HTTP execution budget when capacity retries are disabled', async () => {
jest.useFakeTimers();
try {
const fetchImpl = jest.fn().mockResolvedValue(
new Response(JSON.stringify({ error: 'rate_limited' }), {
status: 429,
headers: { 'Retry-After': '0' },
}),
);
const result = executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
maxQueueWaitMs: 0,
codeApiMaxRetryWaitMs: 1_000,
maxRequestTimeoutMs: 35_050,
request: { protocolVersion: 1, operation: 'read_file', workspaceId: 'primary', path: 'x' },
}).catch((error: WorkspaceToolHttpError) => error);
await jest.advanceTimersByTimeAsync(50);
await expect(result).resolves.toMatchObject({ upstreamStatus: 429 });
expect(fetchImpl).toHaveBeenCalledTimes(1);
} finally {
jest.useRealTimers();
}
});
test('reports a rate limit as not started when its retry budget is disabled', async () => {
const fetchImpl = jest.fn().mockResolvedValue(
new Response(JSON.stringify({ error: 'rate_limited', retry_after_seconds: 1 }), {
status: 429,
headers: { 'Retry-After': '1' },
}),
);
const failure = executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
codeApiMaxRetryWaitMs: 0,
request: {
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
command: 'echo test',
},
});
await expect(failure).rejects.toThrow('The operation was not started');
await expect(failure).rejects.toMatchObject({ upstreamStatus: 429 });
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
test('never retries a 429 that does not carry the typed rate-limit body', async () => {
const fetchImpl = jest.fn().mockResolvedValue(
new Response('<html>Too Many Requests</html>', {
status: 429,
headers: { 'Retry-After': '0' },
}),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
request: {
protocolVersion: 1,
operation: 'edit_file',
workspaceId: 'primary',
path: 'src/app.ts',
edits: [{ oldText: 'const old = true;', newText: 'const ready = true;' }],
},
}),
).rejects.toMatchObject({ upstreamStatus: 429 });
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
test('never retries an ambiguous capacity-looking failure', async () => {
const fetchImpl = jest.fn().mockResolvedValue(
new Response('<html>Gateway unavailable</html>', {
status: 503,
headers: { 'Retry-After': '0' },
}),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
request: {
protocolVersion: 1,
operation: 'edit_file',
workspaceId: 'primary',
path: 'src/app.ts',
edits: [{ oldText: 'const old = true;', newText: 'const ready = true;' }],
},
}),
).rejects.toMatchObject({ upstreamStatus: 503 });
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
test.each([
[504, '{"code":"ASSIGNMENT_EXPIRED"}', false],
[503, '<html>Gateway unavailable</html>', false],
[503, '{"code":"WORKSPACE_QUEUE_TIMEOUT"}', true],
[503, 'null', false],
[503, '{"error":"rate_limited"}', false],
[429, '{"code":"WORKSPACE_QUEUE_TIMEOUT"}', false],
[429, '{"error":"rate_limited"}', true],
[429, '<html>Too Many Requests</html>', false],
] as const)(
'does not infer non-execution from an ambiguous response',
(status, body, truncated) => {
expect(new WorkspaceToolHttpError('rejected', status, body, truncated).message).not.toContain(
'not started',
);
},
);
});
describe('executeWorkspaceTool', () => {
test.each([0, 100])(
'preserves admitted command execution beyond a %i ms retry horizon',
async (maxQueueWaitMs) => {
const now = jest.spyOn(Date, 'now').mockReturnValue(1000);
const timeout = jest.spyOn(AbortSignal, 'timeout');
const fetchImpl = jest.fn(async (...[_url, init]: Parameters<CodeBridgeFetch>) => {
// The endpoint does not report admission separately. A successful command
// may finish after the client retry horizon without being cancelled.
now.mockReturnValue(2000);
expect(init?.signal?.aborted).toBe(false);
return new Response(
JSON.stringify({
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
stdout: 'ready',
stderr: '',
exitCode: 0,
timedOut: false,
truncated: false,
}),
{ status: 200 },
);
});
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
maxQueueWaitMs,
fetchImpl,
request: {
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
command: 'echo ready',
timeoutMs: 300000,
},
}),
).resolves.toMatchObject({ stdout: 'ready', exitCode: 0 });
expect(timeout).toHaveBeenCalledTimes(1);
expect(timeout).toHaveBeenCalledWith(340000);
expect(fetchImpl).toHaveBeenCalledTimes(1);
},
);
test.each<[WorkspaceToolRequest, number]>([
[
{ protocolVersion: 1, operation: 'read_file', workspaceId: 'primary', path: 'README.md' },
65_000,
],
[
{
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
command: 'echo ready',
},
70_000,
],
[
{
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
command: 'echo ready',
timeoutMs: 300_000,
},
340_000,
],
])('allows admission, execution and delivery time for %j', async (request, budget) => {
const timeout = jest.spyOn(AbortSignal, 'timeout');
const fetchImpl = jest
.fn()
.mockResolvedValue(
new Response(
JSON.stringify({ error: 'Older server deadline exceeded', code: 'ASSIGNMENT_EXPIRED' }),
{ status: 504 },
),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request,
fetchImpl,
}),
).rejects.toMatchObject({ upstreamStatus: 504 });
expect(timeout).toHaveBeenCalledWith(budget);
expect(fetchImpl.mock.calls[0][1].body).toBe(JSON.stringify(request));
const admissionMs = Number(
fetchImpl.mock.calls[0][1].headers['X-LibreChat-Workspace-Queue-Wait-Ms'],
);
expect(admissionMs).toBeGreaterThan(0);
expect(admissionMs).toBeLessThanOrEqual(30_000);
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
test.each<[WorkspaceToolRequest, number, number]>([
[
{ protocolVersion: 1, operation: 'read_file', workspaceId: 'primary', path: 'README.md' },
125_000,
90_000,
],
[
{ protocolVersion: 1, operation: 'execute_command', workspaceId: 'primary', command: 'pwd' },
125_000,
85_000,
],
[
{
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
command: 'pwd',
timeoutMs: 90_000,
},
125_000,
25_000,
],
[
{ protocolVersion: 1, operation: 'read_file', workspaceId: 'primary', path: 'README.md' },
60_000,
25_000,
],
[
{ protocolVersion: 1, operation: 'execute_command', workspaceId: 'primary', command: 'pwd' },
60_000,
20_000,
],
[
{
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
command: 'pwd',
timeoutMs: 300_000,
},
610_000,
300_000,
],
])(
'advertises only the remaining queue time for %j under a %i ms limit',
async (request, maxRequestTimeoutMs, allowanceMs) => {
jest.spyOn(Date, 'now').mockReturnValue(1_000);
const timeout = jest.spyOn(AbortSignal, 'timeout');
const fetchImpl = jest
.fn()
.mockResolvedValue(
new Response(JSON.stringify({ code: 'ASSIGNMENT_EXPIRED' }), { status: 504 }),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request,
maxRequestTimeoutMs,
fetchImpl,
}),
).rejects.toMatchObject({ upstreamStatus: 504 });
expect(timeout).toHaveBeenCalledWith(maxRequestTimeoutMs);
expect(fetchImpl.mock.calls[0][1].headers['X-LibreChat-Workspace-Queue-Wait-Ms']).toBe(
String(allowanceMs),
);
expect(fetchImpl).toHaveBeenCalledTimes(1);
},
);
test('accepts a result after 31 simulated seconds of admission with an explicit longer budget', async () => {
const now = jest.spyOn(Date, 'now').mockReturnValue(1_000);
const fetchImpl: CodeBridgeFetch = jest.fn(async (_url, init) => {
expect((init?.headers as Record<string, string>)['X-LibreChat-Workspace-Queue-Wait-Ms']).toBe(
'90000',
);
now.mockReturnValue(32_000);
expect(init?.signal?.aborted).toBe(false);
return Response.json({
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'README.md',
content: 'ready',
startLine: 1,
endLine: 1,
truncated: false,
});
});
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'README.md',
},
maxRequestTimeoutMs: 125_000,
fetchImpl,
}),
).resolves.toMatchObject({ content: 'ready' });
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
test('uses the earlier caller deadline rather than assuming the abort signal reveals it', async () => {
jest.spyOn(Date, 'now').mockReturnValue(1_000);
const timeout = jest.spyOn(AbortSignal, 'timeout');
const fetchImpl = jest.fn().mockResolvedValue(new Response('{}', { status: 504 }));
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'README.md',
},
maxRequestTimeoutMs: 125_000,
deadlineAtMs: 61_000,
fetchImpl,
}),
).rejects.toMatchObject({ upstreamStatus: 504 });
expect(timeout).toHaveBeenCalledWith(60_000);
expect(
new Headers(fetchImpl.mock.calls[0][1]?.headers).get('X-LibreChat-Workspace-Queue-Wait-Ms'),
).toBe('25000');
});
test('subtracts credential acquisition from the allowance before dispatching', async () => {
const now = jest.spyOn(Date, 'now').mockReturnValue(1_000);
const fetchImpl = jest.fn().mockResolvedValue(new Response('{}', { status: 504 }));
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: async () => {
now.mockReturnValue(20_000);
return {};
},
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'README.md',
},
maxRequestTimeoutMs: 125_000,
fetchImpl,
}),
).rejects.toMatchObject({ upstreamStatus: 504 });
expect(fetchImpl.mock.calls[0][1].headers['X-LibreChat-Workspace-Queue-Wait-Ms']).toBe('71000');
});
test.each<[WorkspaceToolRequest, number]>([
[
{
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
command: 'pwd',
timeoutMs: 300_000,
},
125_000,
],
[
{
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
command: 'pwd',
timeoutMs: 90_000,
},
60_000,
],
])(
'does not dispatch when %j cannot fit within the %i ms ingress limit',
async (request, maxRequestTimeoutMs) => {
const fetchImpl = jest.fn();
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request,
maxRequestTimeoutMs,
fetchImpl,
}),
).rejects.toMatchObject({
reason: 'insufficient_time',
message: expect.stringContaining('not started'),
});
expect(fetchImpl).not.toHaveBeenCalled();
},
);
test('keeps the retry horizon separate from one longer admission attempt', async () => {
jest.spyOn(Date, 'now').mockReturnValue(1_000);
const fetchImpl = jest
.fn()
.mockResolvedValue(
new Response(JSON.stringify({ code: 'WORKSPACE_QUEUE_TIMEOUT' }), { status: 503 }),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'README.md',
},
maxRequestTimeoutMs: 125_000,
maxQueueWaitMs: 0,
fetchImpl,
}),
).rejects.toThrow('The operation was not started');
expect(fetchImpl.mock.calls[0][1].headers['X-LibreChat-Workspace-Queue-Wait-Ms']).toBe('90000');
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
test('does not shorten a Retry-After hint to fit a shrinking total budget', async () => {
jest.useFakeTimers();
try {
const fetchImpl = jest
.fn()
.mockResolvedValueOnce(
new Response(JSON.stringify({ code: 'WORKSPACE_QUEUE_TIMEOUT' }), {
status: 503,
headers: { 'Retry-After': '300' },
}),
)
.mockResolvedValueOnce(new Response('{}', { status: 504 }));
const result = executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'README.md',
},
maxRequestTimeoutMs: 125_000,
fetchImpl,
}).catch((error: WorkspaceToolHttpError) => error);
await expect(result).resolves.toMatchObject({ upstreamStatus: 503 });
expect(fetchImpl).toHaveBeenCalledTimes(1);
} finally {
jest.useRealTimers();
}
});
test('never retries a post-dispatch timeout with an unknown mutation outcome', async () => {
const fetchImpl = jest
.fn()
.mockRejectedValue(new DOMException('response deadline', 'TimeoutError'));
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request: {
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
command: 'touch marker',
},
maxRequestTimeoutMs: 125_000,
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'timeout' });
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
test('sends an authenticated bounded read to the selected attached worker', async () => {
const fetchImpl = jest.fn().mockResolvedValue(
new Response(
JSON.stringify({
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'src/app.ts',
content: 'const ready = true;',
startLine: 1,
endLine: 1,
truncated: false,
}),
{ status: 200, headers: { 'Content-Type': 'application/json' } },
),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1/',
authHeaders: {
Authorization: 'Bearer jwt',
'X-LibreChat-Code-Worker-ID': 'user-worker',
},
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'src/app.ts',
startLine: 1,
maxLines: 200,
},
fetchImpl,
}),
).resolves.toMatchObject({ content: 'const ready = true;' });
expect(fetchImpl).toHaveBeenCalledWith(
'https://code.example.com/v1/workspace-tools/execute',
expect.objectContaining({
method: 'POST',
headers: expect.objectContaining({
Authorization: 'Bearer jwt',
'Content-Type': 'application/json',
'X-LibreChat-Code-Worker-ID': 'user-worker',
}),
}),
);
});
test('combines the caller abort signal with the workspace request timeout', async () => {
const controller = new AbortController();
let requestSignal: AbortSignal | undefined;
const fetchImpl: CodeBridgeFetch = jest.fn(async (_url, init) => {
requestSignal = init?.signal ?? undefined;
return new Response(
JSON.stringify({
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'notes.txt',
content: 'ready',
startLine: 1,
endLine: 1,
truncated: false,
}),
{ status: 200, headers: { 'Content-Type': 'application/json' } },
);
});
await executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
signal: controller.signal,
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'notes.txt',
},
fetchImpl,
});
expect(requestSignal?.aborted).toBe(false);
controller.abort();
expect(requestSignal?.aborted).toBe(true);
});
test('preserves caller cancellation instead of relabeling it as a transport failure', async () => {
const controller = new AbortController();
const fetchImpl: CodeBridgeFetch = jest.fn(
async (_url, init) =>
await new Promise<Response>((_resolve, reject) => {
init?.signal?.addEventListener('abort', () => reject(init.signal?.reason), {
once: true,
});
}),
);
const request = executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
signal: controller.signal,
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'notes.txt',
},
fetchImpl,
});
controller.abort();
await expect(request).rejects.toMatchObject({ name: 'AbortError' });
});
test('preserves caller cancellation while reading the response body', async () => {
const controller = new AbortController();
const fetchImpl: CodeBridgeFetch = jest.fn(async (_url, init) => {
const body = new ReadableStream<Uint8Array>({
start(streamController) {
init?.signal?.addEventListener(
'abort',
() => streamController.error(init.signal?.reason),
{ once: true },
);
},
});
return new Response(body, {
status: 200,
headers: { 'Content-Type': 'application/json' },
});
});
const request = executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
signal: controller.signal,
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'notes.txt',
},
fetchImpl,
});
await new Promise<void>((resolve) => setImmediate(resolve));
controller.abort();
await expect(request).rejects.toMatchObject({ name: 'AbortError' });
});
test('rejects a malformed worker result before it reaches the model', async () => {
const fetchImpl = jest.fn().mockResolvedValue(
new Response(
JSON.stringify({
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: '/Users/operator/.ssh/id_ed25519',
content: 'secret',
startLine: 1,
endLine: 1,
truncated: false,
}),
{ status: 200, headers: { 'Content-Type': 'application/json' } },
),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'src/app.ts',
},
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
});
test.each(['./src/app.ts', 'src/./app.ts', 'src//app.ts'])(
'rejects the non-canonical request path %s before dispatch',
async (path) => {
const fetchImpl = jest.fn();
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path,
},
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
expect(fetchImpl).not.toHaveBeenCalled();
},
);
test('rejects read content that exceeds its declared line range', async () => {
const fetchImpl = jest.fn().mockResolvedValue(
new Response(
JSON.stringify({
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'src/app.ts',
content: 'first\nsecond',
startLine: 1,
endLine: 1,
truncated: false,
}),
{ status: 200, headers: { 'Content-Type': 'application/json' } },
),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'src/app.ts',
maxLines: 1,
},
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
});
test('rejects unexpected result fields that could disclose worker metadata', async () => {
const fetchImpl = jest.fn().mockResolvedValue(
new Response(
JSON.stringify({
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'src/app.ts',
content: 'safe',
startLine: 1,
endLine: 1,
truncated: false,
root: '/Users/operator/private',
}),
{ status: 200, headers: { 'Content-Type': 'application/json' } },
),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'src/app.ts',
},
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
});
test('preserves the upstream status when the error body stalls', async () => {
const cancel = jest.fn();
const fetchImpl = jest.fn().mockResolvedValue(
new Response(
new ReadableStream({
cancel,
}),
{ status: 503 },
),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
request: {
protocolVersion: 1,
operation: 'search_text',
workspaceId: 'primary',
query: 'needle',
},
fetchImpl,
}),
).rejects.toMatchObject({
reason: 'rejected',
upstreamStatus: 503,
upstreamBodyTruncated: true,
});
expect(cancel).toHaveBeenCalledTimes(1);
});
test.each([400, 409, 503, 504])('preserves HTTP %i and its diagnostic body', async (status) => {
const body = JSON.stringify({ code: 'ASSIGNMENT_EXPIRED', error: 'Assignment expired' });
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com',
authHeaders: {},
request: { protocolVersion: 1, operation: 'list_files', workspaceId: 'primary' },
fetchImpl: jest.fn(async () => new Response(body, { status })),
}),
).rejects.toMatchObject({
reason: 'rejected',
upstreamStatus: status,
upstreamBody: body,
upstreamBodyTruncated: false,
message: expect.stringContaining(`upstreamStatus: ${status}`),
});
});
test.each([4095, 4096, 4097])(
'reports truncation correctly for a %i-byte error body',
async (size) => {
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com',
authHeaders: {},
request: { protocolVersion: 1, operation: 'list_files', workspaceId: 'primary' },
fetchImpl: jest.fn(async () => new Response('x'.repeat(size), { status: 503 })),
}),
).rejects.toMatchObject({
upstreamStatus: 503,
upstreamBody: 'x'.repeat(Math.min(size, 4096)),
upstreamBodyTruncated: size > 4096,
});
},
);
test('preserves caller cancellation during a rejected response body read', async () => {
const controller = new AbortController();
const cancel = jest.fn();
const request = executeWorkspaceTool({
baseURL: 'https://code.example.com',
authHeaders: {},
signal: controller.signal,
request: { protocolVersion: 1, operation: 'list_files', workspaceId: 'primary' },
fetchImpl: jest.fn(async () => new Response(new ReadableStream({ cancel }), { status: 503 })),
});
await new Promise<void>((resolve) => setImmediate(resolve));
controller.abort();
await expect(request).rejects.toBe(controller.signal.reason);
expect(cancel).toHaveBeenCalledTimes(1);
});
test('bounds a streaming error body and cancels the unread remainder', async () => {
const cancel = jest.fn();
const body = new ReadableStream<Uint8Array>({
start(controller) {
controller.enqueue(new TextEncoder().encode('x'.repeat(10_000)));
},
cancel,
});
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com',
authHeaders: {},
request: { protocolVersion: 1, operation: 'list_files', workspaceId: 'primary' },
fetchImpl: jest.fn(async () => new Response(body, { status: 504 })),
}),
).rejects.toMatchObject({
upstreamStatus: 504,
upstreamBody: 'x'.repeat(4096),
upstreamBodyTruncated: true,
});
expect(cancel).toHaveBeenCalledTimes(1);
});
test('retains HTTP status when reading the error body fails', async () => {
const body = new ReadableStream<Uint8Array>({
start(controller) {
controller.error(new Error('socket closed'));
},
});
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com',
authHeaders: {},
request: { protocolVersion: 1, operation: 'list_files', workspaceId: 'primary' },
fetchImpl: jest.fn(async () => new Response(body, { status: 503 })),
}),
).rejects.toMatchObject({ upstreamStatus: 503, upstreamBodyTruncated: true });
});
test('validates bounded search matches before returning them', async () => {
const fetchImpl = jest.fn().mockResolvedValue(
new Response(
JSON.stringify({
protocolVersion: 1,
operation: 'search_text',
workspaceId: 'primary',
matches: [
{
path: 'src/app.ts',
line: 7,
column: 3,
text: 'const needle = true;',
hostRoot: '/Users/operator/private',
},
],
truncated: false,
}),
{ status: 200, headers: { 'Content-Type': 'application/json' } },
),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
request: {
protocolVersion: 1,
operation: 'search_text',
workspaceId: 'primary',
query: 'needle',
maxResults: 20,
},
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
});
test('rejects non-canonical dot-segment request paths before dispatch', async () => {
const fetchImpl = jest.fn().mockResolvedValue(
Response.json({
protocolVersion: 1,
operation: 'search_text',
workspaceId: 'primary',
matches: [{ path: 'src/app.ts', line: 1, column: 1, text: 'needle' }],
truncated: false,
}),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
request: {
protocolVersion: 1,
operation: 'search_text',
workspaceId: 'primary',
query: 'needle',
path: './src',
},
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
expect(fetchImpl).not.toHaveBeenCalled();
});
test('validates bounded file listings within the requested subtree', async () => {
const fetchImpl = jest.fn().mockResolvedValue(
Response.json({
protocolVersion: 1,
operation: 'list_files',
workspaceId: 'primary',
paths: ['src/app.ts', 'src/worker.ts'],
truncated: true,
nextAfterPath: 'src/worker.ts',
}),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
request: {
protocolVersion: 1,
operation: 'list_files',
workspaceId: 'primary',
path: 'src',
afterPath: 'src/000.ts',
maxResults: 20,
},
fetchImpl,
}),
).resolves.toMatchObject({
paths: ['src/app.ts', 'src/worker.ts'],
nextAfterPath: 'src/worker.ts',
});
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
request: {
protocolVersion: 1,
operation: 'list_files',
workspaceId: 'primary',
path: './src',
maxResults: 20,
},
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
expect(fetchImpl).toHaveBeenCalledTimes(1);
fetchImpl.mockResolvedValueOnce(
Response.json({
protocolVersion: 1,
operation: 'list_files',
workspaceId: 'primary',
paths: ['outside.txt'],
truncated: false,
}),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
request: {
protocolVersion: 1,
operation: 'list_files',
workspaceId: 'primary',
path: 'src',
},
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
});
test('rejects newline-delimited paths returned by an attached worker', async () => {
const fetchImpl = jest.fn().mockResolvedValue(
Response.json({
protocolVersion: 1,
operation: 'list_files',
workspaceId: 'primary',
paths: ['src/safe.ts\nworkspace/src/injected.ts'],
truncated: false,
}),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
request: {
protocolVersion: 1,
operation: 'list_files',
workspaceId: 'primary',
},
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
});
test('rejects invalid workspace listing continuations on both sides of the bridge', async () => {
const fetchImpl = jest.fn();
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
request: {
protocolVersion: 1,
operation: 'list_files',
workspaceId: 'primary',
path: 'src',
afterPath: 'outside/file.ts',
},
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
expect(fetchImpl).not.toHaveBeenCalled();
fetchImpl.mockResolvedValueOnce(
Response.json({
protocolVersion: 1,
operation: 'list_files',
workspaceId: 'primary',
paths: ['src/worker.ts'],
truncated: true,
}),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
request: {
protocolVersion: 1,
operation: 'list_files',
workspaceId: 'primary',
path: 'src',
afterPath: 'src/app.ts',
},
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
});
test('rejects an oversized response before parsing worker-controlled JSON', async () => {
const cancel = jest.fn();
const json = jest.fn().mockResolvedValue({
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'src/app.ts',
content: 'safe',
startLine: 1,
endLine: 1,
truncated: false,
});
const fetchImpl = jest.fn().mockResolvedValue({
ok: true,
status: 200,
headers: new Headers({ 'Content-Length': String(5 * 1024 * 1024) }),
body: new ReadableStream({ cancel }),
json,
} as unknown as Response);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
request: {
protocolVersion: 1,
operation: 'read_file',
workspaceId: 'primary',
path: 'src/app.ts',
},
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
expect(json).not.toHaveBeenCalled();
expect(cancel).toHaveBeenCalledTimes(1);
});
test('rejects unrecognized workspace operations before dispatch', async () => {
const fetchImpl = jest.fn();
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
request: {
protocolVersion: 1,
operation: 'delete_file',
workspaceId: 'primary',
query: 'ignored',
} as never,
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
expect(fetchImpl).not.toHaveBeenCalled();
});
test('accepts a bounded command result from the selected attached worker', async () => {
const fetchImpl = jest.fn(async () =>
Response.json({
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
exitCode: 2,
stdout: '',
stderr: 'not found',
truncated: false,
timedOut: false,
}),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
request: {
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
command: 'test -f package.json',
maxOutputBytes: 256 * 1024,
},
fetchImpl,
}),
).resolves.toMatchObject({ exitCode: 2, stderr: 'not found' });
});
describe('lane git on command results', () => {
const commandResult = {
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
exitCode: 0,
stdout: '',
stderr: '',
truncated: false,
timedOut: false,
};
const run = (extra: Record<string, unknown>) =>
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request: {
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
command: 'git status',
},
fetchImpl: jest.fn(async () => Response.json({ ...commandResult, ...extra })),
});
const head40 = 'a'.repeat(40);
const head64 = 'b'.repeat(64);
test('passes a branch and head through unchanged', async () => {
await expect(
run({ laneGit: { branch: 'feat/pr-chip', head: head40 } }),
).resolves.toMatchObject({ laneGit: { branch: 'feat/pr-chip', head: head40 } });
});
test('accepts a null branch and head for a detached or empty lane', async () => {
await expect(run({ laneGit: { branch: null, head: null } })).resolves.toMatchObject({
laneGit: { branch: null, head: null },
});
});
test('accepts a 64 character head and a 256 character branch', async () => {
const branch = 'x'.repeat(256);
await expect(run({ laneGit: { branch, head: head64 } })).resolves.toMatchObject({
laneGit: { branch, head: head64 },
});
});
test('leaves laneGit absent when the worker did not send it', async () => {
const result = await run({});
expect(result).not.toHaveProperty('laneGit');
});
test.each<[string, unknown]>([
['an extra key', { branch: 'main', head: head40, path: '/srv/repo' }],
['a missing head', { branch: 'main' }],
['a missing branch', { head: head40 }],
['an empty branch', { branch: '', head: head40 }],
['a branch over 256 characters', { branch: 'x'.repeat(257), head: head40 }],
['a control character in the branch', { branch: 'main\nrm', head: head40 }],
['a DEL character in the branch', { branch: 'main\x7f', head: head40 }],
['an uppercase head', { branch: 'main', head: 'A'.repeat(40) }],
['a short head', { branch: 'main', head: 'a'.repeat(39) }],
['a non-hex head', { branch: 'main', head: 'g'.repeat(40) }],
['a numeric branch', { branch: 7, head: head40 }],
['an array', [null, null]],
['a string', 'main'],
['null', null],
])('rejects the result when laneGit has %s', async (_label, laneGit) => {
await expect(run({ laneGit })).rejects.toMatchObject({ reason: 'invalid' });
});
});
test('rejects command requests and results outside protocol limits', async () => {
const fetchImpl: CodeBridgeFetch = jest.fn(async () =>
Response.json({
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
exitCode: 0,
stdout: 'x'.repeat(9),
stderr: '',
truncated: false,
timedOut: false,
}),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request: {
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
command: 'printf x',
maxOutputBytes: 8,
},
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request: {
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
command: 'x'.repeat(32 * 1024 + 1),
},
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
});
test('validates atomic create-only workspace writes', async () => {
const fetchImpl = jest.fn(async () =>
Response.json({
protocolVersion: 1,
operation: 'write_file',
workspaceId: 'primary',
path: 'src/new.ts',
created: true,
bytesWritten: 5,
}),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: { Authorization: 'Bearer jwt' },
request: {
protocolVersion: 1,
operation: 'write_file',
workspaceId: 'primary',
path: 'src/new.ts',
content: 'ready',
overwrite: false,
},
fetchImpl,
}),
).resolves.toMatchObject({ created: true, bytesWritten: 5 });
fetchImpl.mockResolvedValueOnce(
Response.json({
protocolVersion: 1,
operation: 'write_file',
workspaceId: 'primary',
path: 'src/new.ts',
created: false,
bytesWritten: 5,
}),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request: {
protocolVersion: 1,
operation: 'write_file',
workspaceId: 'primary',
path: 'src/new.ts',
content: 'ready',
overwrite: false,
},
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
});
test('validates bounded atomic workspace edit batches', async () => {
const fetchImpl: CodeBridgeFetch = jest.fn(async () =>
Response.json({
protocolVersion: 1,
operation: 'edit_file',
workspaceId: 'primary',
path: 'src/app.ts',
replacements: 2,
bytesWritten: 18,
}),
);
const request = {
protocolVersion: 1 as const,
operation: 'edit_file' as const,
workspaceId: 'primary',
path: 'src/app.ts',
edits: [
{ oldText: 'false', newText: 'true' },
{ oldText: 'draft', newText: 'ready' },
],
};
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request,
fetchImpl,
}),
).resolves.toMatchObject({ replacements: 2 });
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request: { ...request, edits: [] },
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request: { ...request, edits: undefined } as unknown as typeof request,
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
test('requires per-edit match reports exactly when a request opts into them', async () => {
const legacyResult = {
protocolVersion: 1,
operation: 'edit_file',
workspaceId: 'primary',
path: 'src/app.ts',
replacements: 2,
bytesWritten: 18,
};
const matches = [
{ strategy: 'line-trimmed', occurrences: 1 },
{ strategy: 'exact', occurrences: 3 },
];
const optedIn = {
protocolVersion: 1 as const,
operation: 'edit_file' as const,
workspaceId: 'primary',
path: 'src/app.ts',
matching: 'tolerant' as const,
edits: [
{ oldText: 'draft ', newText: 'ready' },
{ oldText: 'false', newText: 'true', replaceAll: true },
],
};
const run = (request: WorkspaceToolRequest, result: object) =>
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request,
fetchImpl: jest.fn(async () => Response.json(result)),
});
await expect(run(optedIn, { ...legacyResult, matches })).resolves.toMatchObject({ matches });
await expect(run(optedIn, legacyResult)).rejects.toMatchObject({ reason: 'invalid' });
await expect(
run(optedIn, {
...legacyResult,
matches: [matches[0], { strategy: 'exact', occurrences: 0 }],
}),
).rejects.toMatchObject({ reason: 'invalid' });
await expect(
run(optedIn, {
...legacyResult,
matches: [{ strategy: 'exact', occurrences: 2 }, matches[1]],
}),
).rejects.toMatchObject({ reason: 'invalid' });
const legacyRequest = {
...optedIn,
edits: optedIn.edits.map(({ oldText, newText }) => ({ oldText, newText })),
};
delete (legacyRequest as { matching?: string }).matching;
await expect(run(legacyRequest, legacyResult)).resolves.toMatchObject({ replacements: 2 });
await expect(run(legacyRequest, { ...legacyResult, matches })).rejects.toMatchObject({
reason: 'invalid',
});
await expect(
run({ ...optedIn, matching: 'fuzzy' } as unknown as WorkspaceToolRequest, legacyResult),
).rejects.toMatchObject({ reason: 'invalid' });
await expect(
run(
{
...optedIn,
edits: [{ oldText: 'a', newText: 'b', replaceAll: 'yes' }],
} as unknown as WorkspaceToolRequest,
legacyResult,
),
).rejects.toMatchObject({ reason: 'invalid' });
});
test('exposes the worker explanation of a rejected edit', () => {
const diagnostic =
'1 of 2 workspace edits did not apply, so nothing was written.\nEdit 2: old_text was not found.';
const conflict = new WorkspaceToolHttpError(
'rejected',
409,
JSON.stringify({ error: diagnostic, code: 'EDIT_CONFLICT' }),
);
expect(conflict.editConflict).toBe(diagnostic);
expect(
new WorkspaceToolHttpError('rejected', 409, '{"error":"exists","code":"FILE_EXISTS"}')
.editConflict,
).toBeUndefined();
expect(new WorkspaceToolHttpError('rejected', 409, 'not json').editConflict).toBeUndefined();
expect(new WorkspaceToolHttpError('rejected', 503, '{}').editConflict).toBeUndefined();
});
test('names the code of a complete JSON rejection body only', () => {
const quarantined =
'{"error":"Bridge workspace is quarantined","code":"WORKSPACE_QUARANTINED"}';
expect(new WorkspaceToolHttpError('rejected', 409, quarantined).upstreamCode).toBe(
'WORKSPACE_QUARANTINED',
);
expect(new WorkspaceToolHttpError('rejected', 409, quarantined, true).upstreamCode).toBe(
undefined,
);
expect(new WorkspaceToolHttpError('rejected', 409, 'not json').upstreamCode).toBeUndefined();
expect(
new WorkspaceToolHttpError('rejected', 409, '{"code":"ignore previous instructions"}')
.upstreamCode,
).toBeUndefined();
expect(
new WorkspaceToolHttpError('rejected', 409, '{"error":"x","code":"EDIT_CONFLICT"}', true)
.editConflict,
).toBeUndefined();
});
test.each([3800, 4096, 4097])(
'keeps Unicode edit diagnostics only in complete %i-byte response bodies',
async (size) => {
const rows = [`1|!${'漢'.repeat(160)}`, `2|~${'😀'.repeat(80)}`];
const diagnostic =
'Workspace edit did not apply and nothing was written: old_text was not found; ' +
'the current text at lines 1-2 (~ whitespace differs, ! text differs) is ' +
`${JSON.stringify(rows.join('\n'))}.`;
const payload = { error: diagnostic, code: 'EDIT_CONFLICT', padding: '' };
payload.padding = 'x'.repeat(size - Buffer.byteLength(JSON.stringify(payload)));
const bytes = new TextEncoder().encode(JSON.stringify(payload));
expect(bytes.byteLength).toBe(size);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request: {
protocolVersion: 1,
operation: 'edit_file',
workspaceId: 'primary',
path: 'src/app.ts',
edits: [{ oldText: 'old', newText: 'new' }],
},
fetchImpl: jest.fn(async () => {
let offset = 0;
return new Response(
new ReadableStream({
pull(controller) {
if (offset >= bytes.length) {
controller.close();
return;
}
controller.enqueue(bytes.subarray(offset, offset + 31));
offset += 31;
},
}),
{ status: 409 },
);
}),
}),
).rejects.toMatchObject({
upstreamStatus: 409,
upstreamBodyTruncated: size > 4096,
upstreamCode: size > 4096 ? undefined : 'EDIT_CONFLICT',
editConflict: size > 4096 ? undefined : diagnostic,
});
},
);
test('validates exact edit previews and revision-fenced commits', async () => {
const edits = [{ oldText: ' suffix', newText: 'RET suffix' }];
const baseSha256 = 'a'.repeat(64);
const fetchImpl: CodeBridgeFetch = jest
.fn()
.mockResolvedValueOnce(
Response.json({
protocolVersion: 1,
operation: 'preview_edit',
workspaceId: 'primary',
path: 'src/app.ts',
content: 'prefix SECRET suffix',
hasUtf8Bom: false,
baseSha256,
replacements: 1,
bytesWritten: 20,
}),
)
.mockResolvedValueOnce(
Response.json({
protocolVersion: 1,
operation: 'edit_file',
workspaceId: 'primary',
path: 'src/app.ts',
replacements: 1,
bytesWritten: 20,
}),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request: {
protocolVersion: 1,
operation: 'preview_edit',
workspaceId: 'primary',
path: 'src/app.ts',
edits,
},
fetchImpl,
}),
).resolves.toMatchObject({ content: 'prefix SECRET suffix', baseSha256 });
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request: {
protocolVersion: 1,
operation: 'edit_file',
workspaceId: 'primary',
path: 'src/app.ts',
edits,
expectedBaseSha256: baseSha256,
},
fetchImpl,
}),
).resolves.toMatchObject({ replacements: 1 });
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example.com/v1',
authHeaders: {},
request: {
protocolVersion: 1,
operation: 'edit_file',
workspaceId: 'primary',
path: 'src/app.ts',
edits,
expectedBaseSha256: 'invalid',
},
fetchImpl,
}),
).rejects.toMatchObject({ reason: 'invalid' });
expect(fetchImpl).toHaveBeenCalledTimes(2);
});
});
describe('linked worktree lanes', () => {
const listing = (paths: string[]) =>
new Response(
JSON.stringify({
protocolVersion: 1,
operation: 'list_files',
workspaceId: 'librechat',
paths,
truncated: false,
}),
{ status: 200, headers: { 'Content-Type': 'application/json' } },
);
const request: WorkspaceToolRequest = {
protocolVersion: 1,
operation: 'list_files',
workspaceId: 'librechat',
path: '.worktrees/fix-a/src',
};
test('sends a worktree request and reports paths relative to the checkout', async () => {
const fetchImpl = jest.fn().mockResolvedValue(listing(['src/a.ts']));
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
request,
linkedWorktrees: true,
}),
).resolves.toMatchObject({ paths: ['.worktrees/fix-a/src/a.ts'] });
expect(JSON.parse(fetchImpl.mock.calls[0][1].body)).toEqual({
protocolVersion: 1,
operation: 'list_files',
workspaceId: 'librechat',
path: 'src',
worktree: 'fix-a',
});
});
test('keeps the checkout-scoped request when the worker has no lanes', async () => {
const fetchImpl = jest.fn().mockResolvedValue(listing(['.worktrees/fix-a/src/a.ts']));
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
request,
}),
).resolves.toMatchObject({ paths: ['.worktrees/fix-a/src/a.ts'] });
expect(JSON.parse(fetchImpl.mock.calls[0][1].body)).toEqual(request);
});
test('rejects lane results that escape the requested worktree scope', async () => {
const fetchImpl = jest.fn().mockResolvedValue(listing(['lib/a.ts']));
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
request,
linkedWorktrees: true,
}),
).rejects.toMatchObject({ reason: 'invalid' });
});
});
describe('workspace admission policy and independent budgets', () => {
const command: WorkspaceToolRequest = {
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
command: 'echo ready',
timeoutMs: 30_000,
};
const success = () =>
new Response(
JSON.stringify({
protocolVersion: 1,
operation: 'execute_command',
workspaceId: 'primary',
exitCode: 0,
stdout: 'ready',
stderr: '',
timedOut: false,
truncated: false,
}),
);
const queueTimeout = () =>
new Response(JSON.stringify({ code: 'WORKSPACE_QUEUE_TIMEOUT' }), {
status: 503,
headers: { 'Retry-After': '0' },
});
beforeEach(() => {
jest.useFakeTimers();
jest.setSystemTime(new Date('2026-10-04T00:00:00.000Z'));
});
afterEach(() => jest.useRealTimers());
test('keeps the full 30-second execution budget after 60 seconds waiting', async () => {
let attempts = 0;
const fetchImpl = jest.fn<ReturnType<CodeBridgeFetch>, Parameters<CodeBridgeFetch>>(
async (_url, init) => {
if (init == null) throw new Error('Missing request init');
attempts++;
if (attempts === 1) {
await new Promise((resolve) => setTimeout(resolve, 30_000));
return queueTimeout();
}
expect(Number(new Headers(init.headers).get('X-LibreChat-Workspace-Queue-Wait-Ms'))).toBe(
60_000,
);
await new Promise((resolve) => setTimeout(resolve, 59_900));
expect(init.signal?.aborted).toBe(false);
return success();
},
);
const result = executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
request: command,
maxRequestTimeoutMs: 100_000,
maxRunTimeoutMs: 180_000,
admission: codeEnvironmentAdmissionSchema.parse({ queueWaitMs: 60_000 }),
});
await jest.advanceTimersByTimeAsync(90_000);
await expect(result).resolves.toMatchObject({ stdout: 'ready' });
expect(fetchImpl).toHaveBeenCalledTimes(2);
expect(fetchImpl.mock.calls[1][1]?.body).toBe(fetchImpl.mock.calls[0][1]?.body);
});
test('bounds queue allowance by the transport reserve, not the larger run deadline', async () => {
const fetchImpl = jest.fn<ReturnType<CodeBridgeFetch>, Parameters<CodeBridgeFetch>>(async () =>
success(),
);
await executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
request: command,
maxRequestTimeoutMs: 65_000,
maxRunTimeoutMs: 180_000,
admission: codeEnvironmentAdmissionSchema.parse({ queueWaitMs: 180_000 }),
});
expect(
new Headers(fetchImpl.mock.calls[0][1]?.headers).get('X-LibreChat-Workspace-Queue-Wait-Ms'),
).toBe('25000');
});
test('honors an earlier caller deadline even when overall and transport budgets are larger', async () => {
const fetchImpl = jest.fn<ReturnType<CodeBridgeFetch>, Parameters<CodeBridgeFetch>>(async () =>
success(),
);
await expect(
executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
request: command,
maxRequestTimeoutMs: 100_000,
maxRunTimeoutMs: 180_000,
deadlineAtMs: Date.now() + 40_000,
}),
).rejects.toMatchObject({ reason: 'insufficient_time' });
expect(fetchImpl).not.toHaveBeenCalled();
});
test('adds exponential jitter only to whitelisted rejections and caps local backoff', async () => {
jest.spyOn(Math, 'random').mockReturnValue(1 - Number.EPSILON);
const fetchImpl = jest
.fn()
.mockResolvedValueOnce(new Response('{"code":"WORKSPACE_QUEUE_TIMEOUT"}', { status: 503 }))
.mockResolvedValueOnce(new Response('{"code":"WORKSPACE_QUEUE_TIMEOUT"}', { status: 503 }))
.mockResolvedValueOnce(new Response('{"code":"WORKSPACE_QUEUE_TIMEOUT"}', { status: 503 }))
.mockResolvedValueOnce(success());
const result = executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
request: command,
admission: codeEnvironmentAdmissionSchema.parse({
initialDelayMs: 1_000,
maxDelayMs: 3_000,
multiplier: 2,
jitterRatio: 0.5,
}),
});
await jest.advanceTimersByTimeAsync(1_499);
expect(fetchImpl).toHaveBeenCalledTimes(1);
await jest.advanceTimersByTimeAsync(1);
expect(fetchImpl).toHaveBeenCalledTimes(2);
await jest.advanceTimersByTimeAsync(3_000);
expect(fetchImpl).toHaveBeenCalledTimes(3);
await jest.advanceTimersByTimeAsync(3_000);
await expect(result).resolves.toMatchObject({ stdout: 'ready' });
expect(fetchImpl).toHaveBeenCalledTimes(4);
});
test.each(['60', 'date', 'body'])(
'does not retry before a 60-second %s hint with jitter',
async (hint) => {
jest.spyOn(Math, 'random').mockReturnValue(1 - Number.EPSILON);
const fetchImpl = jest
.fn()
.mockResolvedValueOnce(
new Response(
JSON.stringify({
error: 'rate_limited',
...(hint === 'body' ? { retry_after_seconds: 60 } : {}),
}),
{
status: 429,
headers:
hint === 'body'
? {}
: {
'Retry-After':
hint === 'date' ? new Date(Date.now() + 60_000).toUTCString() : hint,
},
},
),
)
.mockResolvedValueOnce(success());
const result = executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
request: command,
maxRequestTimeoutMs: 100_000,
maxRunTimeoutMs: 180_000,
codeApiMaxRetryWaitMs: 180_000,
admission: codeEnvironmentAdmissionSchema.parse({ jitterRatio: 0.5 }),
});
await jest.advanceTimersByTimeAsync(89_999);
expect(fetchImpl).toHaveBeenCalledTimes(1);
await jest.advanceTimersByTimeAsync(1);
await expect(result).resolves.toMatchObject({ stdout: 'ready' });
expect(fetchImpl).toHaveBeenCalledTimes(2);
},
);
test('keeps upstream bodies diagnostic-only for every rejection kind', () => {
for (const status of [429, 503, 502, 409]) {
const body = '{"code":"WORKSPACE_QUEUE_TIMEOUT","error":"private upstream diagnostic"}';
const error = new WorkspaceToolHttpError('rejected', status, body);
expect(error.message).not.toContain('private upstream diagnostic');
expect(error.upstreamBody).toBe(body);
}
});
test('emits one aggregate outcome without calling HTTP latency queue wait', async () => {
const log = jest.spyOn(logger, 'debug');
const fetchImpl = jest
.fn()
.mockResolvedValueOnce(queueTimeout())
.mockResolvedValueOnce(success());
const result = executeWorkspaceTool({
baseURL: 'https://code.example/v1',
authHeaders: {},
fetchImpl,
request: command,
});
await jest.advanceTimersByTimeAsync(100);
await result;
expect(log).toHaveBeenCalledTimes(1);
expect(log).toHaveBeenCalledWith(
'[WorkspaceAdmission] outcome',
expect.objectContaining({
attempts: 2,
queueRejections: 1,
retryWaitMs: 100,
outcome: 'completed',
}),
);
expect(log).toHaveBeenCalledWith(
'[WorkspaceAdmission] outcome',
expect.not.objectContaining({
queueWaitMs: expect.any(Number),
}),
);
});
});