nexus-ai-pro 2.2.0 → 2.4.0

package/dist/agent/sandbox.js

@@ -0,0 +1,257 @@
+export class SandboxPathError extends Error {
+    path;
+    code = 'SANDBOX_PATH';
+    constructor(path) {
+        super(`"${path}" is outside the sandbox`);
+        this.path = path;
+        this.name = 'SandboxPathError';
+    }
+}
+export function processSandbox(options) {
+    const ready = (async () => {
+        const [{ spawn }, fs, { dirname, isAbsolute, relative, resolve }] = await Promise.all([
+            import('node:child_process'),
+            import('node:fs/promises'),
+            import('node:path'),
+        ]);
+        const root = resolve(options.root);
+        await fs.mkdir(root, { recursive: true });
+        const inside = (file) => {
+            const resolved = resolve(root, file);
+            const fromRoot = relative(root, resolved);
+            if (fromRoot.startsWith('..') || isAbsolute(fromRoot))
+                throw new SandboxPathError(file);
+            return resolved;
+        };
+        return { spawn, fs, dirname, root, inside };
+    })();
+    ready.catch(() => undefined);
+    const maxOutput = options.maxOutputBytes ?? 1_048_576;
+    return {
+        name: 'process (development only)',
+        isolation: { filesystem: false, network: false, processes: false },
+        async exec(command, execOptions = {}) {
+            const { spawn, root, inside } = await ready;
+            const started = Date.now();
+            const cwd = inside(execOptions.cwd ?? '.');
+            const env = {
+                PATH: process.env.PATH ?? '',
+                ...(process.platform === 'win32' && process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {}),
+                HOME: root,
+                ...options.env,
+                ...execOptions.env,
+            };
+            return new Promise((resolve) => {
+                const child = spawn(command, {
+                    cwd,
+                    env,
+                    shell: true,
+                    windowsHide: true,
+                    detached: process.platform !== 'win32',
+                });
+                let stdout = '';
+                let stderr = '';
+                let timedOut = false;
+                let settled = false;
+                const keep = (current, chunk) => current.length >= maxOutput ? current : (current + chunk.toString('utf8')).slice(0, maxOutput);
+                child.stdout?.on('data', (chunk) => {
+                    stdout = keep(stdout, chunk);
+                });
+                child.stderr?.on('data', (chunk) => {
+                    stderr = keep(stderr, chunk);
+                });
+                const stop = () => killTree(spawn, child.pid);
+                const limit = execOptions.timeoutMs ?? options.timeoutMs ?? 30_000;
+                const timer = setTimeout(() => {
+                    timedOut = true;
+                    stop();
+                }, limit);
+                const onAbort = () => stop();
+                execOptions.signal?.addEventListener('abort', onAbort, { once: true });
+                const finish = (exitCode) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    execOptions.signal?.removeEventListener('abort', onAbort);
+                    resolve({ exitCode: timedOut ? null : exitCode, stdout, stderr, timedOut, durationMs: Date.now() - started });
+                };
+                child.on('error', (error) => {
+                    stderr += error.message;
+                    finish(null);
+                });
+                child.on('close', (code) => finish(code));
+                if (execOptions.stdin !== undefined)
+                    child.stdin?.end(execOptions.stdin);
+                else
+                    child.stdin?.end();
+            });
+        },
+        async readFile(file) {
+            const { fs, inside } = await ready;
+            return fs.readFile(inside(file), 'utf8');
+        },
+        async writeFile(file, content) {
+            const { fs, dirname, inside } = await ready;
+            const target = inside(file);
+            await fs.mkdir(dirname(target), { recursive: true });
+            await fs.writeFile(target, content, 'utf8');
+        },
+        async listFiles(directory = '.') {
+            const { fs, inside } = await ready;
+            return (await fs.readdir(inside(directory))).sort();
+        },
+        async removeFile(file) {
+            const { fs, root, inside } = await ready;
+            const target = inside(file);
+            if (target === root)
+                throw new SandboxPathError(file);
+            await fs.rm(target, { recursive: true, force: true });
+        },
+    };
+}
+function killTree(spawn, pid) {
+    if (pid === undefined)
+        return;
+    try {
+        if (process.platform === 'win32') {
+            spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' });
+        }
+        else {
+            process.kill(-pid, 'SIGKILL');
+        }
+    }
+    catch {
+    }
+}
+export function sandboxTools(sandbox, options = {}) {
+    const mount = (options.mount ?? '/workspace').replace(/\/+$/, '');
+    const local = (file) => {
+        const unified = String(file ?? '.').replace(/\\/g, '/');
+        const relative = unified === mount ? '.' : unified.startsWith(`${mount}/`) ? unified.slice(mount.length + 1) : unified;
+        return relative.replace(/^\/+/, '') || '.';
+    };
+    const mounted = (file) => `${mount}/${local(file)}`;
+    const tools = [];
+    if (options.shell !== false) {
+        tools.push({
+            name: 'run_command',
+            description: 'Runs a shell command in the sandbox and returns its exit code and output.',
+            parameters: {
+                type: 'object',
+                properties: { command: { type: 'string', description: 'The command line to run' } },
+                required: ['command'],
+            },
+            capabilities: (args) => [`shell:${String(args.command ?? '')}`],
+            execute: async (args) => {
+                const result = await sandbox.exec(String(args.command ?? ''), {
+                    ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+                });
+                return { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr, timedOut: result.timedOut };
+            },
+        });
+    }
+    if (options.files !== false) {
+        tools.push({
+            name: 'read_file',
+            description: `Reads a text file in the sandbox. Paths are relative to ${mount}.`,
+            parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+            capabilities: (args) => [`filesystem:read:${mounted(args.path)}`],
+            execute: async (args) => sandbox.readFile(local(args.path)),
+        }, {
+            name: 'write_file',
+            description: `Writes a text file in the sandbox, creating its directory. Paths are relative to ${mount}.`,
+            parameters: {
+                type: 'object',
+                properties: { path: { type: 'string' }, content: { type: 'string' } },
+                required: ['path', 'content'],
+            },
+            capabilities: (args) => [`filesystem:write:${mounted(args.path)}`],
+            execute: async (args) => {
+                await sandbox.writeFile(local(args.path), String(args.content ?? ''));
+                return { written: local(args.path) };
+            },
+        });
+        if (sandbox.listFiles) {
+            const list = sandbox.listFiles.bind(sandbox);
+            tools.push({
+                name: 'list_files',
+                description: 'Lists the entries of a directory in the sandbox.',
+                parameters: { type: 'object', properties: { path: { type: 'string' } } },
+                capabilities: (args) => [`filesystem:read:${mounted(args.path)}`],
+                execute: async (args) => list(local(args.path)),
+            });
+        }
+    }
+    return tools;
+}
+export async function runSandboxConformance(create, options = {}) {
+    const node = options.node ?? 'node';
+    const js = (code) => `${node} -e "${code}"`;
+    const checks = [];
+    let name = 'sandbox';
+    const check = async (label, run) => {
+        const sandbox = await create();
+        name = sandbox.name;
+        try {
+            const problem = await run(sandbox);
+            checks.push(problem ? { name: label, ok: false, detail: problem } : { name: label, ok: true });
+        }
+        catch (error) {
+            checks.push({ name: label, ok: false, detail: error instanceof Error ? error.message : String(error) });
+        }
+        finally {
+            await sandbox.dispose?.();
+        }
+    };
+    const expect = (actual, expected, what) => actual === expected ? undefined : `${what}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`;
+    await check('a command reports its output and a zero exit code', async (sandbox) => {
+        const result = await sandbox.exec(js("process.stdout.write('ok')"));
+        return expect(result.stdout, 'ok', 'stdout') ?? expect(result.exitCode, 0, 'exit code');
+    });
+    await check('a failing command reports its exit code and its errors', async (sandbox) => {
+        const result = await sandbox.exec(js("process.stderr.write('bad'); process.exit(3)"));
+        return expect(result.exitCode, 3, 'exit code') ?? expect(result.stderr, 'bad', 'stderr');
+    });
+    await check('a command reads its standard input', async (sandbox) => {
+        const result = await sandbox.exec(js('process.stdin.pipe(process.stdout)'), { stdin: 'piped' });
+        return expect(result.stdout, 'piped', 'stdout');
+    });
+    await check('a command gets the variables it is given, and none of the host', async (sandbox) => {
+        process.env.NEXUS_SANDBOX_HOST_SECRET = 'host-only';
+        try {
+            const result = await sandbox.exec(js("process.stdout.write((process.env.NEXUS_SANDBOX_GIVEN || '') + '|' + (process.env.NEXUS_SANDBOX_HOST_SECRET || ''))"), { env: { NEXUS_SANDBOX_GIVEN: 'given' } });
+            return expect(result.stdout, 'given|', 'environment');
+        }
+        finally {
+            delete process.env.NEXUS_SANDBOX_HOST_SECRET;
+        }
+    });
+    await check('a command past its timeout is stopped', async (sandbox) => {
+        const limit = options.timeoutMs ?? 300;
+        const result = await sandbox.exec(js('setTimeout(() => {}, 20000)'), { timeoutMs: limit });
+        if (!result.timedOut)
+            return 'the command was not reported as timed out';
+        if (result.durationMs > limit + 5_000)
+            return `the command ran ${result.durationMs} ms past a ${limit} ms timeout`;
+        return undefined;
+    });
+    await check('files round-trip, and commands run where they are', async (sandbox) => {
+        await sandbox.writeFile('conformance/note.txt', 'here');
+        const read = await sandbox.readFile('conformance/note.txt');
+        const seen = await sandbox.exec(js("process.stdout.write(require('fs').readFileSync('conformance/note.txt', 'utf8'))"));
+        const listed = sandbox.listFiles ? await sandbox.listFiles('conformance') : ['note.txt'];
+        return (expect(read, 'here', 'readFile') ??
+            expect(seen.stdout, 'here', 'a command reading the file') ??
+            (listed.includes('note.txt') ? undefined : `listFiles did not list note.txt: ${JSON.stringify(listed)}`));
+    });
+    await check('a path outside the sandbox is refused', async (sandbox) => {
+        for (const attempt of ['../outside.txt', 'conformance/../../outside.txt']) {
+            const refused = await sandbox.writeFile(attempt, 'escaped').then(() => false, () => true);
+            if (!refused)
+                return `writeFile("${attempt}") was allowed`;
+        }
+        return undefined;
+    });
+    return { sandbox: name, passed: checks.every((item) => item.ok), checks };
+}

package/dist/agent/tool.d.ts

@@ -1,11 +1,14 @@
-import type { ContentPart, Message, ToolDefinition, ToolOutput } from '../types/messages.js';
+import type { ContentPart, Message, ToolContext, ToolDefinition, ToolOutput } from '../types/messages.js';
 import type { ToolExecutionResult } from '../types/agent.js';
 /** Defines a tool the model can call, typing its arguments. */
 export declare function tool<TArgs extends Record<string, unknown> = Record<string, unknown>>(definition: {
     name: string;
     description: string;
     parameters: Record<string, unknown>;
-    execute: (args: TArgs) => Promise<unknown> | unknown;
+    /** Runs the tool. In an agent, `context` says who the run is for and carries its signal and store. */
+    execute: (args: TArgs, context: ToolContext) => Promise<unknown> | unknown;
+    /** What the tool does to the world, for a permission policy; see `ToolDefinition.capabilities`. */
+    capabilities?: readonly string[] | ((args: TArgs) => readonly string[]);
 }): ToolDefinition;
 /**
  * Builds a tool's result as content: text, images, and asset references, in order. A string becomes
@@ -28,8 +31,10 @@ export declare class ToolExecutor {
     register(toolDefinition: ToolDefinition): this;
     /** Whether a tool is registered. */
     has(name: string): boolean;
+    /** A registered tool, or `undefined`. */
+    get(name: string): ToolDefinition | undefined;
     /** Every registered tool. */
     list(): ToolDefinition[];
     /** Runs a tool. An unknown name or a thrown error comes back as a failed result. */
-    execute(name: string, args: Record<string, unknown>): Promise<ToolExecutionResult>;
+    execute(name: string, args: Record<string, unknown>, context?: ToolContext): Promise<ToolExecutionResult>;
 }

package/dist/agent/tool.js

@@ -1,9 +1,17 @@
 export function tool(definition) {
+    const capabilities = definition.capabilities;
     return {
         name: definition.name,
         description: definition.description,
         parameters: definition.parameters,
-        execute: async (args) => definition.execute(args),
+        execute: async (args, context) => definition.execute(args, context ?? {}),
+        ...(capabilities === undefined
+            ? {}
+            : {
+                capabilities: typeof capabilities === 'function'
+                    ? (args) => capabilities(args)
+                    : capabilities,
+            }),
     };
 }
 export function toolOutput(...content) {
@@ -37,10 +45,13 @@ export class ToolExecutor {
     has(name) {
         return this.tools.has(name);
     }
+    get(name) {
+        return this.tools.get(name);
+    }
     list() {
         return [...this.tools.values()];
     }
-    async execute(name, args) {
+    async execute(name, args, context) {
         const toolDefinition = this.tools.get(name);
         if (!toolDefinition) {
             return { ok: false, error: `Tool "${name}" is not registered` };
@@ -49,7 +60,7 @@ export class ToolExecutor {
             return { ok: false, error: `Tool "${name}" does not have an execute function` };
         }
         try {
-            const result = await toolDefinition.execute(args);
+            const result = await toolDefinition.execute(args, context);
             return { ok: true, result };
         }
         catch (err) {

package/dist/core/secure-stream.js

@@ -1,3 +1,4 @@
+import { utf8Length } from '../utils/ids.js';
 import { redactSensitiveText } from '../security/output-guard.js';
 const MAX_BUFFERED_STREAM_BYTES = 1_048_576;
 const MAX_BUFFERED_STREAM_CHUNKS = 100_000;
@@ -21,13 +22,13 @@ export function protectStreamOutput(stream, security, requestSignal) {
                 }
                 if (chunk.type === 'text' && chunk.content) {
                     bufferedText += chunk.content;
-                    bufferedBytes += Buffer.byteLength(chunk.content);
+                    bufferedBytes += utf8Length(chunk.content);
                 }
                 else if (chunk.type === 'error' && chunk.error) {
-                    bufferedBytes += Buffer.byteLength(chunk.error);
+                    bufferedBytes += utf8Length(chunk.error);
                 }
                 else if (chunk.type === 'tool_call' && chunk.toolCall) {
-                    bufferedBytes += Buffer.byteLength(chunk.toolCall.function.arguments);
+                    bufferedBytes += utf8Length(chunk.toolCall.function.arguments);
                     bufferedToolCalls.push(chunk.toolCall);
                 }
                 if (bufferedBytes > MAX_BUFFERED_STREAM_BYTES) {

package/dist/deep-agent/index.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Deep agents: agents for long, multi-step work — a plan, a workspace, helpers to delegate to, skills
+ * to load when needed, and a context that stays small however long the work runs.
+ *
+ * A preset, not an engine: `createDeepAgent()` composes `createAgent()` with its tools and middleware,
+ * and returns the same compiled graph, with the same checkpoints, approvals, events, and server
+ * support as any agent.
+ */
+import { type AgentGraph, type AgentMiddleware, type CreateAgentOptions } from '../agent/create-agent.js';
+import { type ContextEditorOptions } from '../agent/middleware/context-editor.js';
+import { type ContextOffloadOptions } from '../agent/middleware/filesystem.js';
+import { type ToolSelectorOptions } from '../agent/middleware/tool-selector.js';
+import { type PermissionPolicyLike } from '../agent/permissions.js';
+import { type Sandbox } from '../agent/sandbox.js';
+/** A helper the deep agent can hand a self-contained piece of work to, with a fresh context. */
+export interface DeepSubagent {
+    /** Its name, as the agent delegates to it. */
+    name: string;
+    /** What it is for, written for the model that decides when to delegate. */
+    description: string;
+    /** Its own instructions. */
+    instructions: string;
+    /**
+     * The tools it may use, by name, from the deep agent's own. Defaults to all of them except
+     * `delegate`, so a helper cannot delegate in turn. A tool named in `interruptOn` is never a
+     * helper's: a helper keeps no checkpoints, so it could not pause for the approval.
+     */
+    tools?: readonly string[];
+    /** Its model. Defaults to the deep agent's. */
+    model?: string;
+    /** Model calls it may make. Defaults to 20. */
+    maxIterations?: number;
+}
+/** Instructions the agent loads only when a task needs them: a procedure, a checklist, a house style. */
+export interface DeepSkill {
+    /** Its name, as the agent asks for it. */
+    name: string;
+    /** When it applies, written for the model. Only this is in the agent's context until it is loaded. */
+    description: string;
+    /** The instructions themselves. */
+    instructions?: string;
+    /** A file in the sandbox that holds them, read when the skill is loaded, instead of `instructions`. */
+    file?: string;
+}
+/** Options for `createDeepAgent()`. Everything `createAgent()` takes, and the parts of a deep agent. */
+export interface DeepAgentOptions extends Omit<CreateAgentOptions, 'systemPrompt' | 'permissions'> {
+    /** What this agent is for. Placed before the deep agent's own working instructions. */
+    instructions?: string;
+    /**
+     * The workspace the agent reads, writes, and runs commands in, through `sandboxTools()`, mounted
+     * at `/workspace`. Without one, the agent has no filesystem and no offloading.
+     */
+    sandbox?: Sandbox;
+    /**
+     * Commands the agent may run in the sandbox, as prefixes a permission policy grants: `node`,
+     * `npm test`, `git status`. Without any, there is no `run_command` tool.
+     */
+    commands?: readonly string[];
+    /** Records a plan with `write_todos` and keeps it current. Defaults to true. */
+    planning?: boolean;
+    /** Helpers the agent can delegate to through one `delegate` tool. */
+    subagents?: readonly DeepSubagent[];
+    /** Skills the agent can load through `load_skill`. */
+    skills?: readonly DeepSkill[];
+    /** Instruction files from the sandbox the model sees on every call. Defaults to `AGENTS.md`. */
+    include?: readonly string[];
+    /**
+     * Writes tool results longer than the limit to `.context/` in the sandbox, leaving a preview and the
+     * path. Defaults to results over 20,000 characters; `false` keeps them whole.
+     */
+    offload?: ContextOffloadOptions | false;
+    /**
+     * Clears old tool results from what the model is sent once the request grows. Defaults to past
+     * 60,000 estimated tokens, never clearing the plan; `false` turns it off.
+     */
+    contextEditing?: ContextEditorOptions | false;
+    /**
+     * Sends the model only the tools relevant to the turn, for an agent with many. The deep agent's own
+     * tools are always sent. Off unless given.
+     */
+    toolSelection?: ToolSelectorOptions;
+    /**
+     * Decides every tool call. Defaults to a policy that grants the workspace, the `commands`, the plan,
+     * delegation, and skills, and denies everything else, so a tool of your own needs a grant here or
+     * its own policy. `false` runs every call.
+     */
+    permissions?: PermissionPolicyLike | false;
+    /** Middleware run after the deep agent's own. */
+    middleware?: AgentMiddleware[];
+}
+/**
+ * Builds a deep agent: `createAgent()` with a plan, a sandboxed workspace, subagents, skills, context
+ * offloading, optional tool selection, and a permission policy.
+ *
+ * ```ts
+ * const agent = createDeepAgent({
+ *   client: ai,
+ *   model: 'claude-sonnet-5-5',
+ *   instructions: 'You maintain this repository.',
+ *   sandbox,
+ *   commands: ['node', 'npm test', 'git diff'],
+ *   subagents: [{ name: 'reviewer', description: 'Reviews a change', instructions: 'Review the diff for bugs.' }],
+ *   skills: [{ name: 'release-notes', description: 'Writing release notes', file: 'skills/release-notes.md' }],
+ *   checkpointer,
+ * });
+ * const run = await agent.invoke(agentInput('Fix the failing test'), { threadId });
+ * ```
+ */
+export declare function createDeepAgent(options: DeepAgentOptions): AgentGraph;

package/dist/deep-agent/index.js

@@ -0,0 +1,216 @@
+import { agentInput, createAgent, } from '../agent/create-agent.js';
+import { contextEditor } from '../agent/middleware/context-editor.js';
+import { filesystemContext } from '../agent/middleware/filesystem.js';
+import { toolSelector } from '../agent/middleware/tool-selector.js';
+import { permissionPolicy } from '../agent/permissions.js';
+import { sandboxTools } from '../agent/sandbox.js';
+import { tool } from '../agent/tool.js';
+const MOUNT = '/workspace';
+const CORE_TOOLS = [
+    'write_todos',
+    'delegate',
+    'load_skill',
+    'read_file',
+    'write_file',
+    'edit_file',
+    'list_files',
+    'run_command',
+];
+export function createDeepAgent(options) {
+    const { instructions, sandbox, commands = [], planning = true, subagents = [], skills = [], include = ['AGENTS.md'], offload, contextEditing, toolSelection, permissions, middleware = [], tools: extraTools = [], ...agentOptions } = options;
+    const workspace = sandbox
+        ? [...sandboxTools(sandbox, { shell: commands.length > 0, mount: MOUNT }), editFileTool(sandbox)]
+        : [];
+    const own = [
+        ...(planning ? [writeTodosTool()] : []),
+        ...(skills.length > 0 ? [loadSkillTool(skills, sandbox)] : []),
+        ...workspace,
+        ...extraTools,
+    ];
+    const helpers = new Map();
+    const approved = new Set(Object.keys(agentOptions.interruptOn ?? {}));
+    const { interruptOn: _approvals, ...helperOptions } = agentOptions;
+    for (const helper of subagents) {
+        const allowed = helper.tools ? new Set(helper.tools) : undefined;
+        helpers.set(helper.name, createAgent({
+            ...helperOptions,
+            name: `${options.name ?? 'deep-agent'}.${helper.name}`,
+            ...(helper.model ? { model: helper.model } : {}),
+            maxIterations: helper.maxIterations ?? 20,
+            systemPrompt: `${helper.instructions}\n\n${WORKSPACE_NOTE}`,
+            tools: own.filter((candidate) => !approved.has(candidate.name) && (allowed ? allowed.has(candidate.name) : true)),
+            ...(permissions === false ? {} : { permissions: permissions ?? defaultPolicy(commands) }),
+            checkpointer: false,
+        }));
+    }
+    const tools = [...own, ...(helpers.size > 0 ? [delegateTool(subagents, helpers)] : [])];
+    const kit = [
+        ...(sandbox && (include.length > 0 || offload !== false)
+            ? [
+                filesystemContext({
+                    source: sandbox,
+                    include,
+                    ...(offload === false ? {} : { offload: { overChars: 20_000, ...offload } }),
+                }),
+            ]
+            : []),
+        ...(contextEditing === false
+            ? []
+            : [
+                contextEditor({
+                    triggerTokens: 60_000,
+                    ...contextEditing,
+                    exclude: ['write_todos', ...(contextEditing?.exclude ?? [])],
+                }),
+            ]),
+        ...(toolSelection
+            ? [toolSelector({ ...toolSelection, always: [...CORE_TOOLS, ...(toolSelection.always ?? [])] })]
+            : []),
+    ];
+    return createAgent({
+        maxIterations: 40,
+        ...agentOptions,
+        systemPrompt: systemPrompt(instructions, { planning, sandbox: Boolean(sandbox), commands, subagents, skills }),
+        tools,
+        middleware: [...kit, ...middleware],
+        ...(permissions === false ? {} : { permissions: permissions ?? defaultPolicy(commands) }),
+    });
+}
+function defaultPolicy(commands) {
+    return permissionPolicy({
+        filesystem: { write: [`${MOUNT}/**`] },
+        shell: { allow: commands },
+        tools: { write_todos: 'allow', delegate: 'allow', load_skill: 'allow' },
+    });
+}
+const WORKSPACE_NOTE = `Files live in ${MOUNT}; paths are relative to it.`;
+function systemPrompt(instructions, parts) {
+    const lines = [];
+    if (instructions)
+        lines.push(instructions, '');
+    lines.push('Work through the task step by step, checking each step before the next.');
+    if (parts.planning) {
+        lines.push('For any task of more than two steps, first record a plan with write_todos, then keep it current: mark a step in_progress when you start it and completed when it is done.');
+    }
+    if (parts.sandbox) {
+        lines.push(`${WORKSPACE_NOTE} Read before you change a file; prefer edit_file to rewriting a whole file. A large result may be saved to a file and shown as a preview: read the file when you need the rest.`);
+        if (parts.commands.length > 0)
+            lines.push(`You may run these commands: ${parts.commands.join(', ')}.`);
+    }
+    if (parts.subagents.length > 0) {
+        lines.push('', 'Delegate a self-contained piece of work with delegate, to one of:');
+        for (const helper of parts.subagents)
+            lines.push(`- ${helper.name}: ${helper.description}`);
+    }
+    if (parts.skills.length > 0) {
+        lines.push('', 'Skills you can load with load_skill when a task calls for one:');
+        for (const skill of parts.skills)
+            lines.push(`- ${skill.name}: ${skill.description}`);
+    }
+    return lines.join('\n');
+}
+function writeTodosTool() {
+    return tool({
+        name: 'write_todos',
+        description: 'Records the plan for this task as a list of steps, each pending, in_progress, or completed. Send the whole list each time.',
+        parameters: {
+            type: 'object',
+            properties: {
+                todos: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            content: { type: 'string' },
+                            status: { type: 'string', enum: ['pending', 'in_progress', 'completed'] },
+                        },
+                        required: ['content', 'status'],
+                    },
+                },
+            },
+            required: ['todos'],
+        },
+        capabilities: [],
+        execute: ({ todos }) => {
+            const list = Array.isArray(todos) ? todos : [];
+            const mark = { pending: '[ ]', in_progress: '[~]', completed: '[x]' };
+            const done = list.filter((todo) => todo.status === 'completed').length;
+            return `Plan (${done}/${list.length} done):\n${list.map((todo) => `${mark[todo.status] ?? '[ ]'} ${todo.content}`).join('\n')}`;
+        },
+    });
+}
+function editFileTool(sandbox) {
+    const local = (file) => String(file ?? '')
+        .replace(/\\/g, '/')
+        .replace(new RegExp(`^${MOUNT}/`), '')
+        .replace(/^\/+/, '');
+    return tool({
+        name: 'edit_file',
+        description: `Replaces one exact occurrence of old_text with new_text in a file. Paths are relative to ${MOUNT}.`,
+        parameters: {
+            type: 'object',
+            properties: { path: { type: 'string' }, old_text: { type: 'string' }, new_text: { type: 'string' } },
+            required: ['path', 'old_text', 'new_text'],
+        },
+        capabilities: (args) => [`filesystem:write:${MOUNT}/${local(args.path)}`],
+        execute: async ({ path, old_text: oldText, new_text: newText }) => {
+            const file = local(path);
+            const text = await sandbox.readFile(file);
+            const count = text.split(String(oldText)).length - 1;
+            if (count === 0)
+                throw new Error(`old_text was not found in ${file}`);
+            if (count > 1)
+                throw new Error(`old_text appears ${count} times in ${file}; include more context so it appears once`);
+            await sandbox.writeFile(file, text.replace(String(oldText), () => String(newText)));
+            return { edited: file };
+        },
+    });
+}
+function loadSkillTool(skills, sandbox) {
+    const byName = new Map(skills.map((skill) => [skill.name, skill]));
+    return tool({
+        name: 'load_skill',
+        description: 'Loads the instructions of a skill by name.',
+        parameters: {
+            type: 'object',
+            properties: { name: { type: 'string', enum: skills.map((skill) => skill.name) } },
+            required: ['name'],
+        },
+        capabilities: [],
+        execute: async ({ name }) => {
+            const skill = byName.get(String(name));
+            if (!skill)
+                throw new Error(`No skill named "${String(name)}"`);
+            if (skill.instructions !== undefined)
+                return skill.instructions;
+            if (skill.file && sandbox)
+                return sandbox.readFile(skill.file);
+            throw new Error(`Skill "${skill.name}" has no instructions`);
+        },
+    });
+}
+function delegateTool(subagents, helpers) {
+    return tool({
+        name: 'delegate',
+        description: 'Hands a self-contained task to a helper, which works in a fresh context and returns its answer.',
+        parameters: {
+            type: 'object',
+            properties: {
+                agent: { type: 'string', enum: subagents.map((helper) => helper.name) },
+                task: { type: 'string', description: 'Everything the helper needs to know: it sees nothing else.' },
+            },
+            required: ['agent', 'task'],
+        },
+        capabilities: [],
+        execute: async ({ agent, task }, context) => {
+            const helper = helpers.get(String(agent));
+            if (!helper)
+                throw new Error(`No helper named "${String(agent)}"`);
+            const result = await helper.invoke(agentInput(String(task)), {
+                ...(context.principal ? { principal: context.principal } : {}),
+                ...(context.signal ? { signal: context.signal } : {}),
+            });
+            return (result.state.answer || `The ${String(agent)} helper finished without an answer (${result.state.stopReason}).`);
+        },
+    });
+}