mirror of
https://github.com/danny-avila/LibreChat.git
synced 2026-11-21 23:43:35 +00:00
📝 docs: Describe Attached-Workspace Lanes, Sandbox Scratch, and Skill Files in Tool Descriptions (#16702)
* 📝 docs: Describe Attached-Workspace Lanes, Sandbox Scratch, and Skill Files in Tool Descriptions - Lane-mode `cwd` now states that any call outside `.worktrees/<name>` (with or without cwd, and file tools on such paths) is checkout-wide: it waits for running worktree calls and blocks new ones until it finishes, so checkout-wide calls are reserved for creating, pruning or removing worktrees. - `command`/`cwd` state that the command starts in cwd, so the model does not also cd into it; the lane-mode cd hint says the call ran checkout-wide. - Workers advertising the native SRT sandbox profile (`anthropic-srt`, `anthropic-srt:<preset>`) get a bash bullet that / and /tmp are read-only and scratch files belong in $TMPDIR or the workspace. Carried as `codeWorkspace.nativeSandbox` into tool definitions and the bash tool. - The attached skill-aware `read_file` description says skill files are not on the attached machine and must be written into the workspace to run there. - Tightened the attached bash description so the native variant stays within the 1024-character tool description limit. * 📝 fix: Keep the Skill-Copy Warning on the Command-Only Workspace's Skill read_file A workspace that offers execute_command but not read_file falls back to the skill-only read_file definition. It now carries the same sentence as the attached skill-aware definition, so the model knows bash_tool cannot reach skill files by path there. * 📝 fix: Name bash_tool in the Skill-File Warning Only When It Is Registered The skill-copy sentence on attached read_file definitions now depends on the attached bash_tool being registered beside it (includeBash and an advertised execute_command), for the attached skill-aware definition, its custom line-limit variant, and the skill-only fallback. Workspaces without commands keep the plain skill description.
This commit is contained in:
parent
ab086a6616
commit
76fcf0a6eb
11 changed files with 359 additions and 31 deletions
|
|
@ -3,6 +3,7 @@ import type { AppConfig } from '@librechat/data-schemas';
|
|||
import type { CodeExecutionContext, CodeEnvironmentConfig } from '~/agents/execution';
|
||||
import {
|
||||
CodeWorkspaceSelectionError,
|
||||
isNativeSandboxProfile,
|
||||
resolveCodeExecutionWorkspaceContext,
|
||||
supportsProgrammaticCodeExecution,
|
||||
} from './capabilities';
|
||||
|
|
@ -430,6 +431,32 @@ describe('resolveCodeExecutionWorkspaceContext', () => {
|
|||
]);
|
||||
});
|
||||
|
||||
it.each([
|
||||
{ sandboxProfile: 'anthropic-srt', nativeSandbox: true },
|
||||
{ sandboxProfile: 'anthropic-srt:trusted-vm', nativeSandbox: true },
|
||||
{ sandboxProfile: 'anthropic-srt-custom', nativeSandbox: undefined },
|
||||
{ sandboxProfile: 'native-srt', nativeSandbox: undefined },
|
||||
{ sandboxProfile: 'oci-docker', nativeSandbox: undefined },
|
||||
])(
|
||||
'marks the native sandbox only for its advertised profile: $sandboxProfile',
|
||||
async ({ sandboxProfile, nativeSandbox }) => {
|
||||
const response = workspaceStatus([{ id: 'docs' }]);
|
||||
const body = await response.json();
|
||||
body.capabilities.sandboxProfile = sandboxProfile;
|
||||
jest.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(JSON.stringify(body)));
|
||||
|
||||
const resolved = await resolveCodeExecutionWorkspaceContext({
|
||||
context,
|
||||
requestedSelections: [{ environmentId: 'personal', workspaceId: 'docs' }],
|
||||
environments,
|
||||
getAppConfig,
|
||||
});
|
||||
|
||||
expect(resolved.codeWorkspace?.nativeSandbox).toBe(nativeSandbox);
|
||||
expect(isNativeSandboxProfile(sandboxProfile)).toBe(nativeSandbox === true);
|
||||
},
|
||||
);
|
||||
|
||||
it('carries validated project metadata from the selected workspace', async () => {
|
||||
const environment = {
|
||||
fingerprint: 'a'.repeat(64),
|
||||
|
|
|
|||
|
|
@ -22,6 +22,20 @@ export type CodeCapabilityConfigLoader = ReturnType<typeof createAppConfigServic
|
|||
|
||||
const pollWorkerStatus = createCodeBridgeStatusPoller();
|
||||
|
||||
/** The worker's default label for native SRT workspace commands, optionally `:<command-policy-preset>`. */
|
||||
const NATIVE_SANDBOX_PROFILE = 'anthropic-srt';
|
||||
|
||||
/**
|
||||
* Whether the worker reports the native SRT command sandbox, whose filesystem is
|
||||
* read-only outside the workspace and a private `$TMPDIR`. A custom operator
|
||||
* label is not recognized, so its description omits the claim.
|
||||
*/
|
||||
export function isNativeSandboxProfile(profile: string | undefined): boolean {
|
||||
return (
|
||||
profile === NATIVE_SANDBOX_PROFILE || profile?.startsWith(`${NATIVE_SANDBOX_PROFILE}:`) === true
|
||||
);
|
||||
}
|
||||
|
||||
function canonicalWorkspaceSelections(
|
||||
selections: CodeWorkspaceSelection[],
|
||||
): CodeWorkspaceSelection[] {
|
||||
|
|
@ -169,6 +183,7 @@ export async function resolveCodeExecutionWorkspaceContext({
|
|||
!usesIsolation
|
||||
? { linkedWorktrees: true }
|
||||
: {}),
|
||||
...(isNativeSandboxProfile(status.sandboxProfile) ? { nativeSandbox: true } : {}),
|
||||
...(status.maxCommandTimeoutMs == null
|
||||
? {}
|
||||
: { maxCommandTimeoutMs: status.maxCommandTimeoutMs }),
|
||||
|
|
|
|||
|
|
@ -11,8 +11,10 @@ import type { WorkspaceExecuteCommandRequest } from './workspace';
|
|||
import type { CodeExecutionContext } from '~/agents/execution';
|
||||
import type { CodeBridgeFetch } from './bridge';
|
||||
import {
|
||||
ATTACHED_WORKSPACE_NATIVE_SANDBOX_BASH_DESCRIPTION,
|
||||
ATTACHED_WORKSPACE_BASH_DESCRIPTION,
|
||||
ATTACHED_WORKSPACE_BASH_SCHEMA,
|
||||
buildAttachedWorkspaceBashDescription,
|
||||
buildAttachedWorkspaceBashSchema,
|
||||
createAttachedWorkspaceBashTool,
|
||||
createContextProgrammaticBashTool,
|
||||
|
|
@ -30,14 +32,66 @@ describe('attached workspace Bash contract', () => {
|
|||
expect(ATTACHED_WORKSPACE_BASH_DESCRIPTION).toContain(
|
||||
'Only registered-workspace files persist',
|
||||
);
|
||||
expect(ATTACHED_WORKSPACE_BASH_DESCRIPTION).toContain('Install project dependencies there');
|
||||
expect(ATTACHED_WORKSPACE_BASH_DESCRIPTION).toContain('install project dependencies there');
|
||||
expect(ATTACHED_WORKSPACE_BASH_DESCRIPTION).toContain('$HOME');
|
||||
expect(ATTACHED_WORKSPACE_BASH_DESCRIPTION).toContain('/tmp, $TMPDIR');
|
||||
expect(ATTACHED_WORKSPACE_BASH_DESCRIPTION).toContain('global/system packages');
|
||||
expect(ATTACHED_WORKSPACE_BASH_DESCRIPTION).toContain('background processes do not survive');
|
||||
expect(ATTACHED_WORKSPACE_BASH_DESCRIPTION).toContain('not the final directory');
|
||||
expect(ATTACHED_WORKSPACE_BASH_DESCRIPTION).toContain(
|
||||
'Scripts are not automatically rewritten',
|
||||
'temp files, and background processes are not durable',
|
||||
);
|
||||
expect(ATTACHED_WORKSPACE_BASH_DESCRIPTION).toContain('global/system packages');
|
||||
expect(ATTACHED_WORKSPACE_BASH_DESCRIPTION).toContain('not the final one');
|
||||
expect(ATTACHED_WORKSPACE_BASH_DESCRIPTION).toContain('scripts are not rewritten');
|
||||
});
|
||||
|
||||
test('describes the read-only native sandbox filesystem only when the worker advertises it', () => {
|
||||
const scratch =
|
||||
'/ and /tmp are read-only; write scratch files to $TMPDIR or the workspace. Programs that hardcode /tmp fail.';
|
||||
expect(ATTACHED_WORKSPACE_BASH_DESCRIPTION).not.toContain('read-only');
|
||||
expect(ATTACHED_WORKSPACE_NATIVE_SANDBOX_BASH_DESCRIPTION).toContain(scratch);
|
||||
expect(ATTACHED_WORKSPACE_NATIVE_SANDBOX_BASH_DESCRIPTION.replace(`- ${scratch}\n`, '')).toBe(
|
||||
ATTACHED_WORKSPACE_BASH_DESCRIPTION,
|
||||
);
|
||||
expect(buildAttachedWorkspaceBashDescription(false)).toBe(ATTACHED_WORKSPACE_BASH_DESCRIPTION);
|
||||
expect(
|
||||
buildAttachedWorkspaceBashDescription(true, undefined, true).startsWith(
|
||||
`${ATTACHED_WORKSPACE_NATIVE_SANDBOX_BASH_DESCRIPTION}\n\n`,
|
||||
),
|
||||
).toBe(true);
|
||||
const tool = (nativeSandbox?: boolean): string =>
|
||||
createAttachedWorkspaceBashTool({
|
||||
baseUrl: 'https://code.example.com/v1',
|
||||
authHeaders: () => ({}),
|
||||
workspaceId: 'project-a',
|
||||
nativeSandbox,
|
||||
}).description;
|
||||
expect(tool(true)).toBe(ATTACHED_WORKSPACE_NATIVE_SANDBOX_BASH_DESCRIPTION);
|
||||
expect(tool(false)).toBe(ATTACHED_WORKSPACE_BASH_DESCRIPTION);
|
||||
expect(tool()).toBe(ATTACHED_WORKSPACE_BASH_DESCRIPTION);
|
||||
});
|
||||
|
||||
test('states that commands start in cwd so the model does not also cd into it', () => {
|
||||
const { properties } = buildAttachedWorkspaceBashSchema();
|
||||
expect(properties?.command?.description).toContain(
|
||||
'It starts in cwd, or in the workspace root when cwd is omitted.',
|
||||
);
|
||||
expect(properties?.cwd?.description).toContain(
|
||||
'The command starts there; do not also cd into it.',
|
||||
);
|
||||
expect(properties?.cwd?.description).not.toContain('checkout-wide');
|
||||
expect(properties?.cwd?.description).not.toContain('.worktrees');
|
||||
});
|
||||
|
||||
test('describes checkout-wide root calls only in linked-worktree lane mode', () => {
|
||||
const laneCwd = buildAttachedWorkspaceBashSchema(undefined, undefined, true).properties?.cwd
|
||||
?.description;
|
||||
expect(laneCwd).toContain('The command starts there; do not also cd into it.');
|
||||
expect(laneCwd).toContain(
|
||||
'Pass a linked worktree directory here (e.g. ".worktrees/fix-auth") rather than cd into it: different worktrees run in parallel.',
|
||||
);
|
||||
expect(laneCwd).toContain(
|
||||
'Any other call, with or without cwd, is checkout-wide: it waits for all running worktree calls and blocks new ones until it finishes, as do file tools on paths outside .worktrees/<name>.',
|
||||
);
|
||||
expect(laneCwd).toContain(
|
||||
'Reserve checkout-wide calls for creating, pruning or removing worktrees, batching any git fetch they need into the same call.',
|
||||
);
|
||||
});
|
||||
|
||||
|
|
@ -707,7 +761,9 @@ describe('createAttachedWorkspaceBashTool', () => {
|
|||
const content = await bashTool.invoke({ command });
|
||||
expect(content).toContain('[starting directory: "workspace/"]');
|
||||
expect(content).toContain('pass cwd instead of a leading cd');
|
||||
expect(content).toContain('does not select a linked-worktree lane');
|
||||
expect(content).toContain(
|
||||
'does not select a linked-worktree lane, so this call ran checkout-wide.',
|
||||
);
|
||||
expect(content).toContain('This command was not rewritten; do not rerun it');
|
||||
const request = JSON.parse(String((fetchImpl as jest.Mock).mock.calls[0][1]?.body));
|
||||
expect(request.command).toBe(command);
|
||||
|
|
|
|||
|
|
@ -65,20 +65,31 @@ export function stampCommandExecutor(
|
|||
}
|
||||
}
|
||||
|
||||
export const ATTACHED_WORKSPACE_BASH_DESCRIPTION = `Runs bash commands inside the selected attached environment and returns stdout/stderr. The workspace may be a project, Git repo, or empty directory.
|
||||
const ATTACHED_WORKSPACE_BASH_INTRO = `Runs bash in the selected attached environment and returns stdout/stderr. The workspace may be a project, Git repo, or empty directory.
|
||||
|
||||
Session behavior:
|
||||
- Start a new command, not an existing task. Inspect background_task_id with check_background_task; never pass it here.
|
||||
- Only registered-workspace files persist. Install project dependencies there.
|
||||
- Every call is a fresh process. Shell state, exports, cwd, /tmp, $TMPDIR, and background processes do not survive.
|
||||
- Results show the starting workspace-relative directory, not the final directory. Scripts are not automatically rewritten.
|
||||
- Never pass background_task_id here; inspect it with check_background_task.
|
||||
- Only registered-workspace files persist; install project dependencies there. $HOME, global/system packages, and services are operator-managed.
|
||||
- Each call is a fresh process; shell state, exports, cwd, temp files, and background processes are not durable.`;
|
||||
|
||||
/** Native SRT workers make the host filesystem read-only outside the workspace and a private `$TMPDIR`. */
|
||||
const ATTACHED_WORKSPACE_NATIVE_SANDBOX_SCRATCH =
|
||||
'- / and /tmp are read-only; write scratch files to $TMPDIR or the workspace. Programs that hardcode /tmp fail.';
|
||||
|
||||
const ATTACHED_WORKSPACE_BASH_RULES = `- Results show the starting directory, not the final one; scripts are not rewritten.
|
||||
- Use cwd for directory-scoped commands; keep cd for shell state or root access.
|
||||
- $HOME, global/system packages, and services are operator-managed, not session storage.
|
||||
- Network access follows the sandbox policy; file access too. Network may be unavailable.
|
||||
- Network and file access follow the sandbox policy; network may be unavailable.
|
||||
- Input code is already displayed; do not repeat unless asked.
|
||||
- Explicitly print every result the user should see.
|
||||
- Never execute malicious commands.`;
|
||||
|
||||
export const ATTACHED_WORKSPACE_BASH_DESCRIPTION: string = `${ATTACHED_WORKSPACE_BASH_INTRO}
|
||||
${ATTACHED_WORKSPACE_BASH_RULES}`;
|
||||
|
||||
export const ATTACHED_WORKSPACE_NATIVE_SANDBOX_BASH_DESCRIPTION: string = `${ATTACHED_WORKSPACE_BASH_INTRO}
|
||||
${ATTACHED_WORKSPACE_NATIVE_SANDBOX_SCRATCH}
|
||||
${ATTACHED_WORKSPACE_BASH_RULES}`;
|
||||
|
||||
const bashSchema = BashExecutionToolDefinition.schema as {
|
||||
properties?: NonNullable<LCTool['parameters']>['properties'];
|
||||
};
|
||||
|
|
@ -86,7 +97,7 @@ const attachedCommandSchema: NonNullable<LCTool['parameters']> = {
|
|||
...bashSchema.properties?.command,
|
||||
type: 'string',
|
||||
description:
|
||||
'The bash command or script to execute from the attached workspace root. Only files written inside the workspace persist between calls. Each call starts a fresh process; $HOME, temporary files, shell state, global installs, and background processes are not durable.',
|
||||
'The bash command or script to execute. It starts in cwd, or in the workspace root when cwd is omitted. Only files written inside the workspace persist between calls. Each call starts a fresh process; $HOME, temporary files, shell state, global installs, and background processes are not durable.',
|
||||
};
|
||||
|
||||
/** `maxLength` is valid JSON Schema, but the SDK's schema type omits it. */
|
||||
|
|
@ -100,7 +111,7 @@ const attachedWorkingDirectorySchema: BoundedWorkingDirectorySchema = {
|
|||
type: 'string',
|
||||
maxLength: 4096,
|
||||
description:
|
||||
'Optional working directory relative to the selected workspace root, such as "packages/api". Absolute paths and parent traversal are rejected.',
|
||||
'Optional working directory relative to the selected workspace root, such as "packages/api". The command starts there; do not also cd into it. Absolute paths and parent traversal are rejected.',
|
||||
};
|
||||
|
||||
/** Numeric bounds are valid JSON Schema, but the SDK's schema type omits them. */
|
||||
|
|
@ -235,9 +246,14 @@ export function resolveAttachedWorkspaceRequestTimeoutMs(
|
|||
return configured;
|
||||
}
|
||||
|
||||
/**
|
||||
* Code API schedules each `.worktrees/<name>` as its own lane beneath the
|
||||
* checkout. Every request that is not routed into a lane is checkout-wide: it
|
||||
* waits for the running lanes and, while queued, holds back newer ones.
|
||||
*/
|
||||
const linkedWorktreeWorkingDirectorySchema: BoundedWorkingDirectorySchema = {
|
||||
...attachedWorkingDirectorySchema,
|
||||
description: `${attachedWorkingDirectorySchema.description} To work in a linked worktree, pass its directory here (for example ".worktrees/fix-auth") instead of running cd inside the command: commands in different .worktrees/<name> directories then run in parallel, while a cd from the workspace root waits for all of them.`,
|
||||
description: `${attachedWorkingDirectorySchema.description} Pass a linked worktree directory here (e.g. ".worktrees/fix-auth") rather than cd into it: different worktrees run in parallel. Any other call, with or without cwd, is checkout-wide: it waits for all running worktree calls and blocks new ones until it finishes, as do file tools on paths outside .worktrees/<name>. Reserve checkout-wide calls for creating, pruning or removing worktrees, batching any git fetch they need into the same call.`,
|
||||
};
|
||||
|
||||
export function buildAttachedWorkspaceBashSchema(
|
||||
|
|
@ -284,10 +300,14 @@ export const ATTACHED_WORKSPACE_BASH_SCHEMA: NonNullable<LCTool['parameters']> =
|
|||
export function buildAttachedWorkspaceBashDescription(
|
||||
enableToolOutputReferences: boolean,
|
||||
environment?: CodeWorkspaceDescriptor['environment'],
|
||||
nativeSandbox = false,
|
||||
): string {
|
||||
const description = enableToolOutputReferences
|
||||
? `${ATTACHED_WORKSPACE_BASH_DESCRIPTION}\n\n${BashToolOutputReferencesGuide}`
|
||||
const base = nativeSandbox
|
||||
? ATTACHED_WORKSPACE_NATIVE_SANDBOX_BASH_DESCRIPTION
|
||||
: ATTACHED_WORKSPACE_BASH_DESCRIPTION;
|
||||
const description = enableToolOutputReferences
|
||||
? `${base}\n\n${BashToolOutputReferencesGuide}`
|
||||
: base;
|
||||
return (
|
||||
description +
|
||||
(environment
|
||||
|
|
@ -432,6 +452,7 @@ export function createAttachedWorkspaceBashTool({
|
|||
maxRequestTimeoutMs,
|
||||
minCommandAdmissionMs,
|
||||
linkedWorktrees = false,
|
||||
nativeSandbox = false,
|
||||
fetchImpl,
|
||||
}: {
|
||||
baseUrl: string;
|
||||
|
|
@ -440,6 +461,8 @@ export function createAttachedWorkspaceBashTool({
|
|||
workspaceInstanceId?: string;
|
||||
/** The worker runs each `.worktrees/<name>` in its own lane; a matching `cwd` is routed there. */
|
||||
linkedWorktrees?: boolean;
|
||||
/** The worker advertises its native SRT sandbox profile; describe its read-only filesystem. */
|
||||
nativeSandbox?: boolean;
|
||||
environment?: CodeWorkspaceDescriptor['environment'];
|
||||
gitIdentity?: AgentGitIdentity | null;
|
||||
/** Effective admin/upstream ceiling already intersected with the protocol hard cap. */
|
||||
|
|
@ -557,7 +580,7 @@ export function createAttachedWorkspaceBashTool({
|
|||
content +=
|
||||
'\n[directory hint: For future commands scoped to a workspace subdirectory, pass cwd instead of a leading cd.' +
|
||||
(linkedWorktrees
|
||||
? ' A cd inside the script does not select a linked-worktree lane.'
|
||||
? ' A cd inside the script does not select a linked-worktree lane, so this call ran checkout-wide.'
|
||||
: '') +
|
||||
' Keep cd for scripts that depend on shell state or need root access. This command was not rewritten; do not rerun it just to change cwd.]';
|
||||
}
|
||||
|
|
@ -572,7 +595,7 @@ export function createAttachedWorkspaceBashTool({
|
|||
},
|
||||
{
|
||||
name: BashExecutionToolDefinition.name,
|
||||
description: buildAttachedWorkspaceBashDescription(false, environment),
|
||||
description: buildAttachedWorkspaceBashDescription(false, environment, nativeSandbox),
|
||||
schema,
|
||||
responseFormat: 'content_and_artifact',
|
||||
},
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue