mirror of
https://github.com/danny-avila/LibreChat.git
synced 2026-11-17 05:20:55 +00:00
🛻 feat: Route Bash Through Attached Workspaces (#15546)
* feat(code): Route bash through attached workspaces * fix(code): harden attached bash schema adapter
This commit is contained in:
parent
2656f44c03
commit
fddf7e31f2
9 changed files with 485 additions and 18 deletions
95
packages/api/src/code/command.spec.ts
Normal file
95
packages/api/src/code/command.spec.ts
Normal file
|
|
@ -0,0 +1,95 @@
|
|||
import type { CodeBridgeFetch } from './bridge';
|
||||
import { createAttachedWorkspaceBashTool } from './command';
|
||||
|
||||
function commandResponse(overrides: Record<string, unknown> = {}): Response {
|
||||
return new Response(
|
||||
JSON.stringify({
|
||||
protocolVersion: 1,
|
||||
operation: 'execute_command',
|
||||
workspaceId: 'primary',
|
||||
exitCode: 0,
|
||||
stdout: 'ready\n',
|
||||
stderr: '',
|
||||
truncated: false,
|
||||
timedOut: false,
|
||||
...overrides,
|
||||
}),
|
||||
{ status: 200, headers: { 'Content-Type': 'application/json' } },
|
||||
);
|
||||
}
|
||||
|
||||
describe('createAttachedWorkspaceBashTool', () => {
|
||||
test('executes in the attached default workspace with per-user bridge authentication', async () => {
|
||||
const fetchImpl: CodeBridgeFetch = jest.fn(async () => commandResponse());
|
||||
const authHeaders = jest.fn().mockResolvedValue({
|
||||
Authorization: 'Bearer jwt',
|
||||
'X-LibreChat-Code-Worker-ID': 'user-worker',
|
||||
});
|
||||
const bashTool = createAttachedWorkspaceBashTool({
|
||||
baseUrl: 'https://code.example.com/v1/',
|
||||
authHeaders,
|
||||
fetchImpl,
|
||||
});
|
||||
|
||||
await expect(bashTool.func({ command: 'pwd' }, undefined, {})).resolves.toEqual([
|
||||
'stdout:\nready\n\n[exit code: 0]',
|
||||
{},
|
||||
]);
|
||||
|
||||
expect(authHeaders).toHaveBeenCalledTimes(1);
|
||||
expect(fetchImpl).toHaveBeenCalledWith(
|
||||
'https://code.example.com/v1/workspace-tools/execute',
|
||||
expect.objectContaining({
|
||||
headers: expect.objectContaining({
|
||||
Authorization: 'Bearer jwt',
|
||||
'X-LibreChat-Code-Worker-ID': 'user-worker',
|
||||
}),
|
||||
}),
|
||||
);
|
||||
const request = JSON.parse(String((fetchImpl as jest.Mock).mock.calls[0][1]?.body));
|
||||
expect(request).toEqual({
|
||||
protocolVersion: 1,
|
||||
operation: 'execute_command',
|
||||
workspaceId: 'primary',
|
||||
command: 'pwd',
|
||||
maxOutputBytes: 256 * 1024,
|
||||
});
|
||||
});
|
||||
|
||||
test('preserves legacy positional args without interpolating shell metacharacters', async () => {
|
||||
const fetchImpl: CodeBridgeFetch = jest.fn(async () => commandResponse());
|
||||
const bashTool = createAttachedWorkspaceBashTool({
|
||||
baseUrl: 'https://code.example.com/v1',
|
||||
authHeaders: () => ({}),
|
||||
fetchImpl,
|
||||
});
|
||||
|
||||
await bashTool.func({ command: 'printf "%s" "$1"', args: ["a'b; echo unsafe"] }, undefined, {});
|
||||
|
||||
const request = JSON.parse(String((fetchImpl as jest.Mock).mock.calls[0][1]?.body));
|
||||
expect(request.command).toBe(`bash -c 'printf "%s" "$1"' -- 'a'"'"'b; echo unsafe'`);
|
||||
});
|
||||
|
||||
test('reports termination, timeouts, and truncation without hiding stderr', async () => {
|
||||
const fetchImpl: CodeBridgeFetch = jest.fn(async () =>
|
||||
commandResponse({
|
||||
exitCode: null,
|
||||
signal: 'SIGKILL',
|
||||
stdout: '',
|
||||
stderr: 'deadline reached',
|
||||
truncated: true,
|
||||
timedOut: true,
|
||||
}),
|
||||
);
|
||||
const bashTool = createAttachedWorkspaceBashTool({
|
||||
baseUrl: 'https://code.example.com/v1',
|
||||
authHeaders: () => ({}),
|
||||
fetchImpl,
|
||||
});
|
||||
|
||||
await expect(bashTool.func({ command: 'sleep 60' }, undefined, {})).resolves.toEqual([
|
||||
'stderr:\ndeadline reached\n[terminated by SIGKILL][timed out][output truncated]',
|
||||
{},
|
||||
]);
|
||||
});
|
||||
});
|
||||
111
packages/api/src/code/command.ts
Normal file
111
packages/api/src/code/command.ts
Normal file
|
|
@ -0,0 +1,111 @@
|
|||
import { tool } from '@librechat/agents/langchain/tools';
|
||||
import { BashExecutionToolDefinition, BashToolOutputReferencesGuide } from '@librechat/agents';
|
||||
import type { DynamicStructuredTool } from '@librechat/agents/langchain/tools';
|
||||
import type { LCTool } from '@librechat/agents';
|
||||
import type { WorkspaceExecuteCommandResult } from './workspace';
|
||||
import type { CodeBridgeFetch } from './bridge';
|
||||
import { executeWorkspaceTool } from './workspace';
|
||||
|
||||
const DEFAULT_WORKSPACE_ID = 'primary';
|
||||
const DEFAULT_OUTPUT_BYTES = 256 * 1024;
|
||||
|
||||
export const ATTACHED_WORKSPACE_BASH_DESCRIPTION = `Runs bash commands inside the selected attached environment and returns stdout/stderr. The workspace may be an existing project, a Git repository, or an empty directory; Git is not required.
|
||||
|
||||
Session behavior:
|
||||
- Files in the registered workspace persist between calls.
|
||||
- Each call runs in a fresh sandboxed process; shell variables, the working directory, temporary files, and background processes do not survive the call.
|
||||
- Network access follows the sandbox policy configured on the worker and may be unavailable.
|
||||
- Commands and file access remain confined by the worker's runtime policy.
|
||||
- Input code is already displayed to the user; do not repeat it unless asked.
|
||||
- Explicitly print every result the user should see.
|
||||
- Never use this tool to execute malicious commands.`;
|
||||
|
||||
const bashSchema = BashExecutionToolDefinition.schema as {
|
||||
properties?: NonNullable<LCTool['parameters']>['properties'];
|
||||
};
|
||||
const attachedCommandSchema: NonNullable<LCTool['parameters']> = {
|
||||
...bashSchema.properties?.command,
|
||||
type: 'string',
|
||||
description:
|
||||
'The bash command or script to execute from the attached workspace root. Files written in the workspace persist between calls, but each call starts a fresh process.',
|
||||
};
|
||||
|
||||
export const ATTACHED_WORKSPACE_BASH_SCHEMA: NonNullable<LCTool['parameters']> = Object.freeze({
|
||||
type: 'object',
|
||||
properties: {
|
||||
...bashSchema.properties,
|
||||
command: attachedCommandSchema,
|
||||
},
|
||||
required: ['command'],
|
||||
});
|
||||
|
||||
export function buildAttachedWorkspaceBashDescription(enableToolOutputReferences: boolean): string {
|
||||
return enableToolOutputReferences
|
||||
? `${ATTACHED_WORKSPACE_BASH_DESCRIPTION}\n\n${BashToolOutputReferencesGuide}`
|
||||
: ATTACHED_WORKSPACE_BASH_DESCRIPTION;
|
||||
}
|
||||
|
||||
function quoteShellArgument(value: string): string {
|
||||
return `'${value.replace(/'/g, `'"'"'`)}'`;
|
||||
}
|
||||
|
||||
function commandWithArguments(command: string, args: string[] | undefined): string {
|
||||
if (!args?.length) return command;
|
||||
return `bash -c ${quoteShellArgument(command)} -- ${args.map(quoteShellArgument).join(' ')}`;
|
||||
}
|
||||
|
||||
function formatCommandResult(result: WorkspaceExecuteCommandResult): 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`;
|
||||
if (output.length === 0) output = 'Command completed with no output.\n';
|
||||
if (result.exitCode != null) output += `[exit code: ${result.exitCode}]`;
|
||||
if (result.signal != null) output += `[terminated by ${result.signal}]`;
|
||||
if (result.timedOut) output += '[timed out]';
|
||||
if (result.truncated) output += '[output truncated]';
|
||||
return output;
|
||||
}
|
||||
|
||||
export function createAttachedWorkspaceBashTool({
|
||||
baseUrl,
|
||||
authHeaders,
|
||||
workspaceId = DEFAULT_WORKSPACE_ID,
|
||||
fetchImpl,
|
||||
}: {
|
||||
baseUrl: string;
|
||||
authHeaders: () => Promise<Record<string, string>> | Record<string, string>;
|
||||
workspaceId?: string;
|
||||
fetchImpl?: CodeBridgeFetch;
|
||||
}): DynamicStructuredTool {
|
||||
return tool(
|
||||
async (
|
||||
rawInput: { command: string; args?: string[]; intent?: string },
|
||||
config,
|
||||
): Promise<[string, Record<string, never>]> => {
|
||||
const command = commandWithArguments(rawInput.command, rawInput.args);
|
||||
const result = await executeWorkspaceTool({
|
||||
baseURL: baseUrl,
|
||||
authHeaders: await authHeaders(),
|
||||
request: {
|
||||
protocolVersion: 1,
|
||||
operation: 'execute_command',
|
||||
workspaceId,
|
||||
command,
|
||||
maxOutputBytes: DEFAULT_OUTPUT_BYTES,
|
||||
},
|
||||
signal: config?.signal,
|
||||
fetchImpl,
|
||||
});
|
||||
if (result.operation !== 'execute_command') {
|
||||
throw new Error('Attached workspace returned an unexpected command result.');
|
||||
}
|
||||
return [formatCommandResult(result), {}];
|
||||
},
|
||||
{
|
||||
name: BashExecutionToolDefinition.name,
|
||||
description: ATTACHED_WORKSPACE_BASH_DESCRIPTION,
|
||||
schema: ATTACHED_WORKSPACE_BASH_SCHEMA,
|
||||
responseFormat: 'content_and_artifact',
|
||||
},
|
||||
) as unknown as DynamicStructuredTool;
|
||||
}
|
||||
|
|
@ -4,3 +4,4 @@ export * from './config';
|
|||
export * from './bridge';
|
||||
export * from './lifecycle';
|
||||
export * from './workspace';
|
||||
export * from './command';
|
||||
|
|
|
|||
|
|
@ -560,4 +560,78 @@ describe('executeWorkspaceTool', () => {
|
|||
).rejects.toMatchObject({ reason: 'invalid' });
|
||||
expect(fetchImpl).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
test('accepts a bounded command result from the selected attached worker', async () => {
|
||||
const fetchImpl: CodeBridgeFetch = 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' });
|
||||
});
|
||||
|
||||
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' });
|
||||
});
|
||||
});
|
||||
|
|
|
|||
|
|
@ -8,6 +8,13 @@ const MAX_READ_LINES = 500;
|
|||
const MAX_SEARCH_RESULTS = 200;
|
||||
const MAX_SEARCH_TEXT_LENGTH = 2000;
|
||||
const MAX_LIST_RESULTS = 500;
|
||||
const MAX_COMMAND_BYTES = 32 * 1024;
|
||||
const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
|
||||
const MAX_COMMAND_TIMEOUT_MS = 5 * 60_000;
|
||||
const DEFAULT_COMMAND_OUTPUT_BYTES = 256 * 1024;
|
||||
const MAX_COMMAND_OUTPUT_BYTES = 1024 * 1024;
|
||||
const MAX_COMMAND_SIGNAL_LENGTH = 32;
|
||||
const WORKSPACE_COMMAND_TRANSPORT_GRACE_MS = 5_000;
|
||||
const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
|
||||
const READ_RESULT_KEYS = new Set([
|
||||
'protocolVersion',
|
||||
|
|
@ -36,6 +43,17 @@ const LIST_RESULT_KEYS = new Set([
|
|||
'truncated',
|
||||
'nextAfterPath',
|
||||
]);
|
||||
const COMMAND_RESULT_KEYS = new Set([
|
||||
'protocolVersion',
|
||||
'operation',
|
||||
'workspaceId',
|
||||
'exitCode',
|
||||
'signal',
|
||||
'stdout',
|
||||
'stderr',
|
||||
'truncated',
|
||||
'timedOut',
|
||||
]);
|
||||
|
||||
export interface WorkspaceReadRequest {
|
||||
protocolVersion: 1;
|
||||
|
|
@ -64,10 +82,21 @@ export interface WorkspaceListRequest {
|
|||
afterPath?: string;
|
||||
}
|
||||
|
||||
export interface WorkspaceExecuteCommandRequest {
|
||||
protocolVersion: 1;
|
||||
operation: 'execute_command';
|
||||
workspaceId: string;
|
||||
command: string;
|
||||
cwd?: string;
|
||||
timeoutMs?: number;
|
||||
maxOutputBytes?: number;
|
||||
}
|
||||
|
||||
export type WorkspaceToolRequest =
|
||||
| WorkspaceReadRequest
|
||||
| WorkspaceSearchRequest
|
||||
| WorkspaceListRequest;
|
||||
| WorkspaceListRequest
|
||||
| WorkspaceExecuteCommandRequest;
|
||||
|
||||
export interface WorkspaceReadResult {
|
||||
protocolVersion: 1;
|
||||
|
|
@ -98,7 +127,23 @@ export interface WorkspaceListResult {
|
|||
nextAfterPath?: string;
|
||||
}
|
||||
|
||||
export type WorkspaceToolResult = WorkspaceReadResult | WorkspaceSearchResult | WorkspaceListResult;
|
||||
export interface WorkspaceExecuteCommandResult {
|
||||
protocolVersion: 1;
|
||||
operation: 'execute_command';
|
||||
workspaceId: string;
|
||||
exitCode: number | null;
|
||||
signal?: string;
|
||||
stdout: string;
|
||||
stderr: string;
|
||||
truncated: boolean;
|
||||
timedOut: boolean;
|
||||
}
|
||||
|
||||
export type WorkspaceToolResult =
|
||||
| WorkspaceReadResult
|
||||
| WorkspaceSearchResult
|
||||
| WorkspaceListResult
|
||||
| WorkspaceExecuteCommandResult;
|
||||
|
||||
export class WorkspaceToolHttpError extends Error {
|
||||
constructor(
|
||||
|
|
@ -133,6 +178,14 @@ function isPositiveInteger(value: unknown, maximum: number): boolean {
|
|||
return Number.isSafeInteger(value) && Number(value) >= 1 && Number(value) <= maximum;
|
||||
}
|
||||
|
||||
function isUtf8StringWithinBytes(value: unknown, maximum: number): value is string {
|
||||
return (
|
||||
typeof value === 'string' &&
|
||||
Buffer.from(value).toString('utf8') === value &&
|
||||
new TextEncoder().encode(value).byteLength <= maximum
|
||||
);
|
||||
}
|
||||
|
||||
function hasOnlyKeys(value: Record<string, unknown>, allowed: ReadonlySet<string>): boolean {
|
||||
return Object.keys(value).every((key) => allowed.has(key));
|
||||
}
|
||||
|
|
@ -232,6 +285,17 @@ function isValidRequest(request: WorkspaceToolRequest): boolean {
|
|||
(request.maxResults == null || isPositiveInteger(request.maxResults, MAX_LIST_RESULTS))
|
||||
);
|
||||
}
|
||||
if (request.operation === 'execute_command') {
|
||||
return (
|
||||
isUtf8StringWithinBytes(request.command, MAX_COMMAND_BYTES) &&
|
||||
request.command.trim().length > 0 &&
|
||||
!request.command.includes('\0') &&
|
||||
(request.cwd == null || isSafePath(request.cwd)) &&
|
||||
(request.timeoutMs == null || isPositiveInteger(request.timeoutMs, MAX_COMMAND_TIMEOUT_MS)) &&
|
||||
(request.maxOutputBytes == null ||
|
||||
isPositiveInteger(request.maxOutputBytes, MAX_COMMAND_OUTPUT_BYTES))
|
||||
);
|
||||
}
|
||||
if (request.operation !== 'search_text') {
|
||||
return false;
|
||||
}
|
||||
|
|
@ -314,6 +378,32 @@ function isValidResult(
|
|||
? value.paths.length > 0 && value.nextAfterPath === value.paths[value.paths.length - 1]
|
||||
: value.nextAfterPath == null;
|
||||
}
|
||||
if (request.operation === 'execute_command') {
|
||||
const stdout = typeof value.stdout === 'string' ? value.stdout : null;
|
||||
const stderr = typeof value.stderr === 'string' ? value.stderr : null;
|
||||
const outputLimit = request.maxOutputBytes ?? DEFAULT_COMMAND_OUTPUT_BYTES;
|
||||
return (
|
||||
hasOnlyKeys(value, COMMAND_RESULT_KEYS) &&
|
||||
stdout != null &&
|
||||
stderr != null &&
|
||||
Buffer.from(stdout).toString('utf8') === stdout &&
|
||||
Buffer.from(stderr).toString('utf8') === stderr &&
|
||||
new TextEncoder().encode(stdout).byteLength + new TextEncoder().encode(stderr).byteLength <=
|
||||
outputLimit &&
|
||||
(value.exitCode === null ||
|
||||
(Number.isSafeInteger(value.exitCode) &&
|
||||
Number(value.exitCode) >= 0 &&
|
||||
Number(value.exitCode) <= 255)) &&
|
||||
(value.signal == null ||
|
||||
(typeof value.signal === 'string' &&
|
||||
value.signal.length <= MAX_COMMAND_SIGNAL_LENGTH &&
|
||||
/^SIG[A-Z0-9]+$/.test(value.signal))) &&
|
||||
typeof value.timedOut === 'boolean' &&
|
||||
(value.exitCode === null
|
||||
? value.timedOut === true || value.signal != null
|
||||
: value.timedOut === false && value.signal == null)
|
||||
);
|
||||
}
|
||||
const maxResults = request.maxResults ?? 50;
|
||||
return (
|
||||
hasOnlyKeys(value, SEARCH_RESULT_KEYS) &&
|
||||
|
|
@ -333,6 +423,11 @@ function isValidResult(
|
|||
);
|
||||
}
|
||||
|
||||
function getWorkspaceToolTimeoutMs(request: WorkspaceToolRequest): number {
|
||||
if (request.operation !== 'execute_command') return WORKSPACE_TOOL_TIMEOUT_MS;
|
||||
return (request.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS) + WORKSPACE_COMMAND_TRANSPORT_GRACE_MS;
|
||||
}
|
||||
|
||||
export async function executeWorkspaceTool({
|
||||
baseURL,
|
||||
authHeaders,
|
||||
|
|
@ -350,7 +445,7 @@ export async function executeWorkspaceTool({
|
|||
throw new WorkspaceToolHttpError('invalid');
|
||||
}
|
||||
try {
|
||||
const timeoutSignal = AbortSignal.timeout(WORKSPACE_TOOL_TIMEOUT_MS);
|
||||
const timeoutSignal = AbortSignal.timeout(getWorkspaceToolTimeoutMs(request));
|
||||
const requestSignal =
|
||||
signal != null && typeof AbortSignal.any === 'function'
|
||||
? AbortSignal.any([signal, timeoutSignal])
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue