nexus-ai-pro 2.2.0 → 2.4.0

package/dist-cjs/agent/sandbox.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The sandbox contract: where an agent's commands and code run, and where its files live.
+ *
+ * The package ships the contract and a conformance suite, not the isolation: a container, a VM, a
+ * remote interpreter, or a hosted sandbox fills the `Sandbox` interface. `processSandbox()` is a
+ * reference for development, which runs commands as ordinary processes; it says so in its
+ * `isolation`, and is never a security boundary.
+ */
+import type { ToolDefinition } from '../types/messages.js';
+/** Options for one command. */
+export interface SandboxExecOptions {
+    /** The working directory, inside the sandbox. Defaults to its root. */
+    cwd?: string;
+    /** Environment variables for the command. The host's own are never passed through. */
+    env?: Record<string, string>;
+    /** Sent to the command's standard input. */
+    stdin?: string;
+    /** Stops the command after this many milliseconds. */
+    timeoutMs?: number;
+    /** Stops the command when aborted. */
+    signal?: AbortSignal;
+}
+/** What a command did. */
+export interface SandboxExecResult {
+    /** Its exit code, or `null` when it was stopped. */
+    exitCode: number | null;
+    /** What it wrote to standard output. */
+    stdout: string;
+    /** What it wrote to standard error. */
+    stderr: string;
+    /** True when it was stopped by its timeout. */
+    timedOut: boolean;
+    /** How long it ran, in milliseconds. */
+    durationMs: number;
+}
+/** What a sandbox claims to isolate. The conformance suite checks the claims it can observe. */
+export interface SandboxIsolation {
+    /** Commands cannot read or write the host's files. */
+    filesystem: boolean;
+    /** Commands cannot reach the network, or only what the sandbox allows. */
+    network: boolean;
+    /** Commands cannot see or signal the host's processes. */
+    processes: boolean;
+}
+/** Where an agent's commands, code, and files go. The application provides one. */
+export interface Sandbox {
+    /** Names the sandbox in reports. */
+    readonly name: string;
+    /** What it isolates. */
+    readonly isolation: SandboxIsolation;
+    /** Runs a command line in the sandbox. */
+    exec(command: string, options?: SandboxExecOptions): Promise<SandboxExecResult>;
+    /** Reads a file, by a path inside the sandbox. */
+    readFile(file: string): Promise<string>;
+    /** Writes a file, creating its directory. */
+    writeFile(file: string, content: string): Promise<void>;
+    /** Lists a directory's entries. */
+    listFiles?(directory?: string): Promise<string[]>;
+    /** Removes a file or directory. */
+    removeFile?(file: string): Promise<void>;
+    /** Releases the sandbox. */
+    dispose?(): Promise<void>;
+}
+/** Raised when a path would leave the sandbox. */
+export declare class SandboxPathError extends Error {
+    /** The path that was refused. */
+    readonly path: string;
+    /** Always `SANDBOX_PATH`. */
+    readonly code = "SANDBOX_PATH";
+    constructor(
+    /** The path that was refused. */
+    path: string);
+}
+/** Options for `processSandbox()`. */
+export interface ProcessSandboxOptions {
+    /** The directory commands run in and files live under. Created when missing. */
+    root: string;
+    /** Environment variables every command gets, on top of a minimal `PATH`. */
+    env?: Record<string, string>;
+    /** Timeout for a command that sets none. Defaults to 30 seconds. */
+    timeoutMs?: number;
+    /** Output kept per stream, in bytes. Defaults to 1 MB. */
+    maxOutputBytes?: number;
+}
+/**
+ * A sandbox that runs commands as ordinary processes in a directory, for development and tests only.
+ *
+ * Its file methods refuse any path outside `root`, and commands get only `PATH` and the variables
+ * given, never the host's environment. But a command it runs can read and write anything the user
+ * can, and reach any host: `isolation` says so. Use a container or a VM in production.
+ */
+export declare function processSandbox(options: ProcessSandboxOptions): Sandbox;
+/** Options for `sandboxTools()`. */
+export interface SandboxToolsOptions {
+    /** Offer `run_command`. Defaults to true. */
+    shell?: boolean;
+    /** Offer `read_file`, `write_file`, and `list_files`. Defaults to true. */
+    files?: boolean;
+    /**
+     * The path a permission policy sees the sandbox's files under. Defaults to `/workspace`, so a
+     * policy granting `/workspace/**` grants the sandbox.
+     */
+    mount?: string;
+    /** Timeout for each command. */
+    timeoutMs?: number;
+}
+/**
+ * Tools that act through a sandbox, each declaring exactly what one call does: `run_command`
+ * declares `shell:<the command>`, and the file tools declare `filesystem:read` or
+ * `filesystem:write` with the path under `mount`. A permission policy can therefore grant a
+ * workspace, a few commands, and nothing else.
+ */
+export declare function sandboxTools(sandbox: Sandbox, options?: SandboxToolsOptions): ToolDefinition[];
+/** One conformance check's result. */
+export interface SandboxConformanceCheck {
+    /** What was checked. */
+    name: string;
+    /** Whether it held. */
+    ok: boolean;
+    /** What went wrong, when it did not. */
+    detail?: string;
+}
+/** What `runSandboxConformance()` found. */
+export interface SandboxConformanceReport {
+    /** The sandbox's name. */
+    sandbox: string;
+    /** True when every check held. */
+    passed: boolean;
+    /** Every check, in order. */
+    checks: SandboxConformanceCheck[];
+}
+/** Options for `runSandboxConformance()`. */
+export interface SandboxConformanceOptions {
+    /** The command that runs JavaScript inside the sandbox. Defaults to `node`. */
+    node?: string;
+    /** The timeout the timeout check sets, in milliseconds. Defaults to 300. */
+    timeoutMs?: number;
+}
+/**
+ * Checks a sandbox against the contract, without a test framework, so any sandbox — a container
+ * runner, a VM, a hosted service — can prove itself the same way:
+ *
+ * - commands report their output, errors, and exit code, take standard input and the variables
+ *   given, and never see the host's environment;
+ * - a command past its timeout is stopped and reported as timed out;
+ * - commands run where the files are, and files round-trip;
+ * - a path outside the sandbox is refused.
+ *
+ * Every check runs on a fresh sandbox from `create`, which is disposed afterwards.
+ */
+export declare function runSandboxConformance(create: () => Sandbox | Promise<Sandbox>, options?: SandboxConformanceOptions): Promise<SandboxConformanceReport>;

package/dist-cjs/agent/sandbox.js

@@ -0,0 +1,297 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SandboxPathError = void 0;
+exports.processSandbox = processSandbox;
+exports.sandboxTools = sandboxTools;
+exports.runSandboxConformance = runSandboxConformance;
+class SandboxPathError extends Error {
+    path;
+    code = 'SANDBOX_PATH';
+    constructor(path) {
+        super(`"${path}" is outside the sandbox`);
+        this.path = path;
+        this.name = 'SandboxPathError';
+    }
+}
+exports.SandboxPathError = SandboxPathError;
+function processSandbox(options) {
+    const ready = (async () => {
+        const [{ spawn }, fs, { dirname, isAbsolute, relative, resolve }] = await Promise.all([
+            Promise.resolve().then(() => __importStar(require('node:child_process'))),
+            Promise.resolve().then(() => __importStar(require('node:fs/promises'))),
+            Promise.resolve().then(() => __importStar(require('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 {
+    }
+}
+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;
+}
+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-cjs/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-cjs/agent/tool.js

@@ -6,11 +6,19 @@ exports.toolOutput = toolOutput;
 exports.isToolOutput = isToolOutput;
 exports.toolMessageContent = toolMessageContent;
 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,
+            }),
     };
 }
 function toolOutput(...content) {
@@ -44,10 +52,13 @@ 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` };
@@ -56,7 +67,7 @@ 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-cjs/core/secure-stream.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.protectStreamOutput = protectStreamOutput;
+const ids_js_1 = require("../utils/ids.js");
 const output_guard_js_1 = require("../security/output-guard.js");
 const MAX_BUFFERED_STREAM_BYTES = 1_048_576;
 const MAX_BUFFERED_STREAM_CHUNKS = 100_000;
@@ -24,13 +25,13 @@ function protectStreamOutput(stream, security, requestSignal) {
                 }
                 if (chunk.type === 'text' && chunk.content) {
                     bufferedText += chunk.content;
-                    bufferedBytes += Buffer.byteLength(chunk.content);
+                    bufferedBytes += (0, ids_js_1.utf8Length)(chunk.content);
                 }
                 else if (chunk.type === 'error' && chunk.error) {
-                    bufferedBytes += Buffer.byteLength(chunk.error);
+                    bufferedBytes += (0, ids_js_1.utf8Length)(chunk.error);
                 }
                 else if (chunk.type === 'tool_call' && chunk.toolCall) {
-                    bufferedBytes += Buffer.byteLength(chunk.toolCall.function.arguments);
+                    bufferedBytes += (0, ids_js_1.utf8Length)(chunk.toolCall.function.arguments);
                     bufferedToolCalls.push(chunk.toolCall);
                 }
                 if (bufferedBytes > MAX_BUFFERED_STREAM_BYTES) {

package/dist-cjs/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;