@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/tools/builtins/sandbox/bash.js

@@ -1,31 +1,44 @@
-import { ToolError } from "@capybara-hq/plugin-sdk";
-import { clip, display, inSandbox, runBudgetNote, runTimeLeftMs, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
-/** 不给 `timeoutSeconds` 时的命令超时（秒），不超过 `sandbox.limits.maxCommandSeconds`。 */
+import { DEFAULT_SANDBOX_ROOTS, ToolError, } from "@capybara-hq/plugin-sdk";
+import { backgroundMaxSeconds, LAUNCH_EXEC_TIMEOUT_MS, launchScript, newTaskId, startedText, taskOutputPath, taskSidPath, } from "../../../background/launch.js";
+import { KILL_SESSION_TIMEOUT_MS, killSession, SID_RE } from "../../../background/session.js";
+import { clip, display, inSandbox, mapSandboxError, noSandboxError, runBudgetNote, runTimeLeftMs, sandboxBaseTimeoutMs, sandboxConversationOf, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+/** The command timeout in seconds when `timeout` is not given, at most `sandbox.limits.maxCommandSeconds`. */
 export const BASH_DEFAULT_TIMEOUT_SECONDS = 120;
 /** The longest `description` (the shell row shows it instead of the command). */
 export const BASH_DESCRIPTION_MAX_CHARS = 120;
-/** bash 结果超过这么多字符即转存（走现有输出存档，模型用 read_tool_output 分页读）。 */
+/** bash 结果超过这么多字符即转存（走现有输出存档，模型用 ReadToolOutput 分页读）。 */
 export const BASH_SPILL_CHARS = 30_000;
 /** 一次命令最多收集的输出字节（stdout + stderr）；超出的丢弃并在结果里说明。 */
 const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
 const SPEC = {
-    name: "sandbox_bash",
+    name: "Bash",
     // Display only (the tool row; not in the fingerprint, never sent to the model).
     keyArgs: ["command"],
-    description: "Run a shell command (bash) in this conversation's sandbox, an isolated Linux machine. " +
+    description: "Run a shell command (bash) in this conversation's sandbox, an isolated machine. " +
         "Use it to run programs and scripts, install packages, process files and inspect the " +
-        "filesystem. The working directory is /workspace; files persist between calls in the same " +
+        "filesystem. The working directory is the workspace directory; files persist between calls in the same " +
         "conversation, but background processes may not: when the sandbox is suspended after a period " +
-        "without use they can be stopped and /tmp cleared, so keep results in files under /workspace. " +
-        "Files the user attached to the conversation are under /workspace/attachments, " +
-        "and skill files under /skills (read-only). Each call runs in a fresh shell (no state such as " +
+        "without use they can be stopped and the temporary files directory cleared, so keep results in " +
+        "files under the workspace directory. Files the user attached to the conversation are copied to " +
+        "attachments/<conversation>/ in the workspace directory (the result names the paths), " +
+        "and skill files to the skills directory (read-only). Each call runs in a fresh shell (no state such as " +
         "cd or environment variables carries over). The result has stdout, stderr and the exit code; " +
-        "long output is saved and can be paged with read_tool_output. A command that runs longer than " +
-        "timeoutSeconds is stopped. Prefer sandbox_read, sandbox_write, sandbox_edit, sandbox_glob and " +
-        "sandbox_grep for reading, writing and searching files. To give a file to the user, use " +
-        "sandbox_deliver. Other sub-agents of this conversation may run commands in this sandbox at " +
+        "long output is saved and can be paged with ReadToolOutput. A command that runs longer than " +
+        "timeout milliseconds is stopped. Prefer Read, Write, Edit, Glob and " +
+        "Grep for reading, writing and searching files. To give a file to the user, use " +
+        "Deliver. Other sub-agents of this conversation may run commands in this sandbox at " +
         "the same time. Always pass description: a few words saying what the command is for; the " +
-        "user sees it instead of the command.",
+        "user sees it instead of the command.\n\n" +
+        "You can use the run_in_background parameter to run the command in the background, which " +
+        "allows you to continue working while the command runs, e.g. a dev server, a long build or a " +
+        "test suite. The call returns at once with a task id and the command's output goes to a file " +
+        "under .capybara/tasks in the workspace directory. Read the output with TaskOutput (or Read) and stop the " +
+        "task with TaskStop; you will be told when it finishes. You do not need to use '&' at the end " +
+        "of the command when using this parameter. In the background, timeout defaults to the " +
+        "deployment's background maximum (7200000 by default). A background task ends when its " +
+        "command exits, and processes it left running are stopped. A background task is lost if the " +
+        "sandbox is suspended (it is suspended after it has been running for a while, " +
+        "sandbox.limits.maxRunningMinutes), so keep its results in files under the workspace directory.",
     inputSchema: {
         type: "object",
         properties: {
@@ -40,23 +53,27 @@ const SPEC = {
                 maxLength: BASH_DESCRIPTION_MAX_CHARS,
                 description: 'What this command does, in a few words (e.g. "Generate the final PDF"). Shown to the user.',
             },
-            timeoutSeconds: {
+            timeout: {
                 type: "integer",
                 minimum: 1,
-                description: `Seconds before the command is stopped. Default ${BASH_DEFAULT_TIMEOUT_SECONDS}; the deployment sets a maximum (7200 by default).`,
+                description: `Milliseconds before the command is stopped. Default ${BASH_DEFAULT_TIMEOUT_SECONDS * 1000} (in the background: the background maximum); the deployment sets a maximum (7200000 by default); a larger value is lowered to it.`,
+            },
+            run_in_background: {
+                type: "boolean",
+                description: "Set to true to run this command in the background. Use TaskOutput to read the output later.",
             },
         },
         required: ["command", "description"],
         additionalProperties: false,
     },
 };
-/** 本次命令的超时（秒）：给定的值，或默认值（不超过上限）。 */
-const secondsFor = (input, max) => input.timeoutSeconds ?? Math.min(BASH_DEFAULT_TIMEOUT_SECONDS, max);
+/** This command's timeout in milliseconds: the given value or the default, at most the maximum. */
+const msFor = (input, maxSeconds) => Math.min(input.timeout ?? BASH_DEFAULT_TIMEOUT_SECONDS * 1000, maxSeconds * 1000);
 /**
  * 命令结果 → 给模型的文本。`budgetClamped`：运行的时限把超时收紧到了 `seconds`（Ruling M20），超时说明改为
- * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeoutSeconds。
+ * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeout。`workspace`: the instance's workspace root.
  */
-export function formatExec(r, seconds, budgetClamped = false) {
+export function formatExec(r, seconds, budgetClamped = false, workspace = DEFAULT_SANDBOX_ROOTS.workspace) {
     const parts = [];
     if (r.stdout !== "")
         parts.push(r.stdout.replace(/\n$/, ""));
@@ -65,10 +82,10 @@ export function formatExec(r, seconds, budgetClamped = false) {
     if (r.truncated)
         parts.push(`[Output truncated: only the first ${MAX_OUTPUT_BYTES} bytes were kept.]`);
     if (r.timedOut && budgetClamped) {
-        parts.push(`[timedOut: the command did not finish within ${seconds}s and was stopped. ${runBudgetNote(seconds)} The sandbox is still usable; split the work into shorter steps that save progress to files under /workspace, or run long jobs in the background and check on them in a later run.]`);
+        parts.push(`[timedOut: the command did not finish within ${seconds}s and was stopped. ${runBudgetNote(seconds)} The sandbox is still usable; split the work into shorter steps that save progress to files under ${workspace}, or run long jobs in the background and check on them in a later run.]`);
     }
     else if (r.timedOut) {
-        parts.push(`[timedOut: the command did not finish within ${seconds}s and was stopped. The sandbox is still usable; pass a larger timeoutSeconds (up to the deployment maximum), or split the work into shorter steps that save progress to files under /workspace.]`);
+        parts.push(`[timedOut: the command did not finish within ${seconds}s and was stopped. The sandbox is still usable; pass a larger timeout in milliseconds (up to the deployment maximum), or split the work into shorter steps that save progress to files under ${workspace}.]`);
     }
     else if (r.exitCode === null) {
         parts.push("[The command was stopped before it finished; its effects may be partial. Check the sandbox state before retrying.]");
@@ -80,7 +97,229 @@ export function formatExec(r, seconds, budgetClamped = false) {
     }
     return parts.join("\n");
 }
-/** 内置工具 `sandbox_bash`：在本对话的沙箱里执行命令。 */
+/** The most output the launch exec keeps (it prints only the session id, or an error). */
+const LAUNCH_MAX_OUTPUT_BYTES = 64 * 1024;
+/** Above about this many bytes of base64, a provider may refuse the launch exec's command. */
+const LARGE_COMMAND_BASE64_BYTES = 96 * 1024;
+/** Why a launch exec did not start the command, for the model and the row's reason. */
+function launchFailure(r) {
+    if (r.timedOut)
+        return `the launch did not finish within ${LAUNCH_EXEC_TIMEOUT_MS / 1000}s`;
+    if (r.exitCode === null)
+        return "the launch was stopped before it finished";
+    const said = clip(r.stderr || (r.exitCode === 0 ? "" : r.stdout), 500).replace(/\.$/, "");
+    if (said !== "")
+        return said;
+    return r.exitCode === 0
+        ? "the launch printed no session id"
+        : `the launch exited with code ${r.exitCode}`;
+}
+/**
+ * `Bash` with `run_in_background` (spec 2026-11-05-background-bash-design §2.1, §4.2):
+ * 1. reserves the task's row (`BackgroundTaskStore.reserve`: `running`, no `sid`), refused once
+ *    the sandbox runs `sandbox.background.maxTasks` tasks; the count and the insert are one step
+ *    under the sandbox's launch lock;
+ * 2. runs one short launch exec under the call's shared lease, and in the same lease records the
+ *    session id and the instance (`markStarted`); a command that started but could not be
+ *    recorded is killed there (`pkill -KILL -s <sid>`), so no process runs untracked;
+ * 3. any failure finishes the row as `failed` with the reason (`failLaunch`);
+ * 4. a stop that claimed the reservation meanwhile (`markStarted` answers `stopping`) has the
+ *    command killed at once and the row finished `stopped` (`finishStoppedLaunch`).
+ * The command runs in a session of its own under its own `timeout` (default and maximum
+ * {@link backgroundMaxSeconds}).
+ */
+async function runInBackground(deps, ctx, input) {
+    const { background, sandbox } = deps;
+    if (!background || !sandbox.currentInstance) {
+        throw new ToolError("Background tasks are not available here; call Bash without run_in_background.");
+    }
+    if (ctx.runId === undefined) {
+        throw new ToolError("Background tasks can only be started from an agent run; call Bash without run_in_background.");
+    }
+    const currentInstance = sandbox.currentInstance.bind(sandbox);
+    const cfg = deps.config.get();
+    const maxMs = backgroundMaxSeconds(cfg) * 1000;
+    const requested = input.timeout;
+    const seconds = Math.max(1, Math.ceil(Math.min(requested ?? maxMs, maxMs) / 1000));
+    const root = sandboxConversationOf(ctx);
+    // the environment the task will run in (the root conversation's, bound for good)
+    let environmentId;
+    try {
+        environmentId = await deps.environments.forTool(ctx.orgId, root);
+    }
+    catch (e) {
+        throw mapSandboxError(e, deps.log);
+    }
+    if (!(await sandbox.availableFor(environmentId)))
+        throw noSandboxError();
+    const maxTasks = cfg.sandbox.background.maxTasks;
+    const id = newTaskId();
+    const description = input.description ?? clip(input.command, 120);
+    const startedAt = new Date();
+    const reserved = await background.reserve({
+        id,
+        orgId: ctx.orgId,
+        conversationId: ctx.conversationId,
+        sandboxConversationId: root,
+        environmentId,
+        runId: ctx.runId,
+        callId: ctx.callId,
+        // the run's trigger account (the pipeline passes `runs.trigger_account_id` as `accountId`)
+        triggerAccountId: ctx.accountId,
+        description,
+        command: input.command,
+        outputPath: taskOutputPath(id),
+        startedAt,
+        deadlineAt: new Date(startedAt.getTime() + seconds * 1000),
+    }, maxTasks);
+    if (!reserved) {
+        throw new ToolError(`${maxTasks} background tasks are already running; stop one with TaskStop or wait for one to finish, then retry`);
+    }
+    // the conversation's background panel lists the task live (a sub-agent's task shows in its
+    // parent's panel too): announced when it starts and when its launch ends it (failed, stopped),
+    // since a client may have listed the reservation as running meanwhile; a failed publish only logs
+    const announce = async () => {
+        if (!deps.eventLog.publishChanged)
+            return;
+        for (const c of new Set([ctx.conversationId, root])) {
+            await deps.eventLog.publishChanged(c, "background");
+        }
+    };
+    // the instance's workspace once the call entered it (the default until then)
+    let workspace = DEFAULT_SANDBOX_ROOTS.workspace;
+    const isLarge = Math.ceil(Buffer.byteLength(input.command, "utf8") / 3) * 4 > LARGE_COMMAND_BASE64_BYTES;
+    const largeText = () => isLarge
+        ? ` A very large command (over about 96 KB after base64) cannot be started in the background; write it to a script under ${workspace} and run that instead.`
+        : "";
+    // set once the row has its sid: from then on the task runs and is tracked, whatever follows
+    let started = false;
+    let launch;
+    let notices;
+    try {
+        ({ value: launch, notices } = await inSandbox(deps, ctx, async ({ h, roots, p, signal }) => {
+            workspace = roots.workspace;
+            // right after the launch a process may fork while it is killed: killSession repeats
+            const kill = (sid) => killSession(p, h, sid);
+            // the session id the launch wrote before printing it: the launch may have ended (aborted,
+            // timed out, thrown) after starting the command but before its output came back
+            const sidFile = async () => {
+                const f = await p
+                    .readFile(h, `${roots.workspace}/${taskSidPath(id)}`, {
+                    maxBytes: 64,
+                    signal: AbortSignal.timeout(KILL_SESSION_TIMEOUT_MS),
+                })
+                    .catch(() => null);
+                const v = f ? new TextDecoder().decode(f.data).trim() : "";
+                return SID_RE.test(v) ? v : null;
+            };
+            let r;
+            try {
+                r = await p.exec(h, {
+                    command: launchScript(id, input.command, seconds),
+                    cwd: roots.workspace,
+                    timeoutMs: LAUNCH_EXEC_TIMEOUT_MS,
+                    maxOutputBytes: LAUNCH_MAX_OUTPUT_BYTES,
+                    signal,
+                });
+            }
+            catch (e) {
+                const sid = await sidFile();
+                if (sid !== null)
+                    await kill(sid);
+                throw e;
+            }
+            const out = r.stdout.trim();
+            if (r.exitCode !== 0 || !SID_RE.test(out)) {
+                const sid = SID_RE.test(out) ? out : await sidFile();
+                if (sid !== null)
+                    await kill(sid);
+                return { kind: "not_started", why: launchFailure(r) };
+            }
+            const sid = out;
+            try {
+                // under the shared lease: no rebuild can come between the launch and this read
+                const instance = await currentInstance(environmentId);
+                if (instance === null)
+                    throw new Error("the sandbox instance could not be read");
+                const marked = await background.markStarted(id, {
+                    sid,
+                    sandboxCreatedAt: instance.createdAt,
+                    outputPath: `${roots.workspace}/${taskOutputPath(id)}`,
+                });
+                if (!marked)
+                    throw new Error("its task record was finished meanwhile");
+                started = true;
+                if (marked === "stopping") {
+                    // a stop claimed the reservation before the command started: kill it at once
+                    if (await kill(sid)) {
+                        await background.finishStoppedLaunch(id);
+                        return { kind: "stopped" };
+                    }
+                    // not confirmed: the task runs on and is tracked like any other (the poller checks it)
+                    await background.releaseStop(id);
+                }
+                return { kind: "started" };
+            }
+            catch (e) {
+                const stopped = await kill(sid);
+                const why = e instanceof Error ? e.message : String(e);
+                return { kind: "unrecorded", why, stopped };
+            }
+        }));
+    }
+    catch (e) {
+        if (started) {
+            // the task runs and its row has its sid: an error after that (releasing the lease, say)
+            // does not undo the launch
+            launch = { kind: "started" };
+            notices = [];
+        }
+        else {
+            // no sandbox, a busy or lost lease, an abort, a provider error: nothing started (or what
+            // did was killed above, when its session id could be read)
+            const why = e instanceof Error ? e.message : String(e);
+            await background.failLaunch(id, `launch failed: ${why}`).catch(() => undefined);
+            await announce();
+            if (!isLarge || e instanceof ToolError)
+                throw e;
+            throw new ToolError(`The background task was not started: ${clip(why, 500).replace(/\.$/, "")}. Check the sandbox, or call Bash without run_in_background.${largeText()}`);
+        }
+    }
+    if (launch.kind === "not_started") {
+        await background.failLaunch(id, launch.why);
+        await announce();
+        throw new ToolError(`The background task was not started: ${launch.why}. Check the sandbox, or call Bash without run_in_background.${largeText()}`);
+    }
+    if (launch.kind === "stopped") {
+        await announce();
+        throw new ToolError(`Background task ${id} ("${description}") was stopped while it was starting, so nothing runs. Call Bash again if it is still needed.`);
+    }
+    if (launch.kind === "unrecorded") {
+        await background.failLaunch(id, `started but not recorded: ${launch.why}`);
+        await announce();
+        if (launch.stopped) {
+            throw new ToolError(`The background command started but could not be recorded (${launch.why}), so it was stopped. Retry, or call Bash without run_in_background.`);
+        }
+        throw new ToolError(`The background command started but could not be recorded (${launch.why}); an attempt to stop it failed, so it ends at its timeout. Check the sandbox before you retry, or call Bash without run_in_background.`);
+    }
+    await announce();
+    const lowered = requested !== undefined && requested > maxMs
+        ? `\n[timeout ${requested} ms is over the background task maximum; it was lowered to ${maxMs} ms.]`
+        : "";
+    const shown = clip(input.command, 120);
+    return {
+        content: [
+            {
+                type: "text",
+                text: withNotices(notices, startedText(id, description, workspace) + lowered),
+            },
+        ],
+        isError: false,
+        view: { kind: "command", description, exitCode: null, timedOut: false },
+        display: display(`后台运行命令：${shown}`, `Started in the background: ${shown}`),
+    };
+}
+/** 内置工具 `Bash`：在本对话的沙箱里执行命令。 */
 export function sandboxBashTool(deps) {
     return {
         spec: SPEC,
@@ -89,35 +328,48 @@ export function sandboxBashTool(deps) {
         unavailable: unavailableWhenNoSandbox(deps),
         // 命令自己的超时先到（提供方停掉命令、返回 timedOut），管线的时限再留出等锁与创建 / 恢复的余量
         timeoutMs: (input) => {
-            const cfg = deps.config();
+            const cfg = deps.config.get();
+            // a background call is only the short launch; the task's own timeout runs in the sandbox
+            if (input.run_in_background === true) {
+                return LAUNCH_EXEC_TIMEOUT_MS + sandboxBaseTimeoutMs(cfg);
+            }
             const max = cfg.sandbox.limits.maxCommandSeconds;
-            return Math.min(secondsFor(input, max), max) * 1000 + sandboxBaseTimeoutMs(cfg);
+            return msFor(input, max) + sandboxBaseTimeoutMs(cfg);
         },
         async run(input, ctx) {
-            const { command, description } = input;
-            const max = deps.config().sandbox.limits.maxCommandSeconds;
-            const req = input.timeoutSeconds;
-            if (req !== undefined && req > max) {
-                throw new ToolError(`timeoutSeconds ${req} is over the limit of ${max} seconds; pass a value of at most ${max}.`);
+            if (input.run_in_background === true) {
+                return runInBackground(deps, ctx, input);
             }
-            const asked = secondsFor(input, max);
-            // 运行截止前命令要自己超时（Ruling M20）：在拿到沙箱之后算，等锁与恢复用掉的时间一并扣掉
-            let seconds = asked;
-            const { value: r, notices } = await inSandbox(deps, ctx, ({ h, p, signal }) => {
-                const left = Math.floor(runTimeLeftMs(ctx.runDeadline) / 1000);
-                seconds = Math.max(1, Math.min(asked, left));
+            const { command, description } = input;
+            const max = deps.config.get().sandbox.limits.maxCommandSeconds;
+            const requested = input.timeout;
+            const maxMs = max * 1000;
+            const askedMs = msFor(input, max);
+            // The run's deadline makes the command time out itself first (Ruling M20): counted after the
+            // sandbox is obtained, so the time spent waiting for the lock and resuming is deducted
+            let ms = askedMs;
+            let workspace = DEFAULT_SANDBOX_ROOTS.workspace;
+            const { value: r, notices } = await inSandbox(deps, ctx, ({ h, roots, p, signal }) => {
+                const left = Math.floor(runTimeLeftMs(ctx.runDeadline) / 1000) * 1000;
+                ms = Math.max(1000, Math.min(askedMs, left));
+                workspace = roots.workspace;
                 return p.exec(h, {
                     command,
-                    cwd: "/workspace",
-                    timeoutMs: seconds * 1000,
+                    cwd: roots.workspace,
+                    timeoutMs: ms,
                     maxOutputBytes: MAX_OUTPUT_BYTES,
                     signal,
                 });
             });
-            const clamped = seconds < asked;
+            const seconds = ms / 1000;
+            const clamped = ms < askedMs;
             const shown = clip(command, 120);
+            const lowered = requested !== undefined && requested > maxMs
+                ? `\n[timeout ${requested} ms is over the deployment maximum; it was lowered to ${maxMs} ms.]`
+                : "";
+            const text = formatExec(r, seconds, clamped, workspace) + lowered;
             return {
-                content: [{ type: "text", text: withNotices(notices, formatExec(r, seconds, clamped)) }],
+                content: [{ type: "text", text: withNotices(notices, text) }],
                 isError: r.timedOut || r.exitCode === null,
                 // display only: a non-zero exit shows as failed on the row, `isError` stays as it was
                 view: {

package/dist/tools/builtins/sandbox/common.d.ts

@@ -1,45 +1,112 @@
-import { type SandboxHandle, type SandboxProvider } from "@capybara-hq/plugin-sdk";
+import { type Logger, type SandboxHandle, type SandboxRoots, ToolError } from "@capybara-hq/plugin-sdk";
+import type { BackgroundTaskFinisher } from "../../../background/finish.js";
+import type { BackgroundTaskStopper } from "../../../background/stop.js";
+import type { BackgroundTaskStore } from "../../../background/store.js";
 import type { KernelConfig } from "../../../config/schema.js";
 import type { AttachmentsService } from "../../../conversations/attachments.service.js";
 import type { EventLog } from "../../../conversations/event-log.js";
-import { type SandboxService } from "../../../sandbox/sandbox.service.js";
+import { type ConversationEnvironments } from "../../../environments/conversation-environments.js";
+import type { KernelConfigService } from "../../../infra/config/kernel-config.service.js";
+import { type HeldProvider, type SandboxService } from "../../../sandbox/sandbox.service.js";
 import type { StorageService } from "../../../storage/storage.service.js";
-import type { BuiltinCallContext } from "../../registry.js";
+import type { BuiltinCallContext, ToolListingScope } from "../../registry.js";
 /** 沙箱工具的依赖（都按调用时取，多副本下无进程内状态）。 */
 export interface SandboxToolDeps {
-    /** `pathLease` may be absent (test stubs): the kernel's own file writes then take no path lease. */
-    sandbox: Pick<SandboxService, "available" | "withSandbox"> & Partial<Pick<SandboxService, "pathLease">>;
+    /**
+     * `pathLease` may be absent (test stubs): the kernel's own file writes then take no path lease.
+     * `currentInstance` too: a background `Bash` launch records the instance it started in; and
+     * `ifRunning`, which `TaskOutput` reads a task through.
+     */
+    sandbox: Pick<SandboxService, "cloudAvailable" | "availableFor" | "withSandbox"> & Partial<Pick<SandboxService, "pathLease" | "currentInstance" | "ifRunning">>;
+    /**
+     * The environment a call enters: the root conversation's, checked for its owner every call.
+     * `usableNow` (absent in test stubs: only the cloud provider counts) tells a listing whether a
+     * conversation's environment can run without a cloud provider (ruling R8).
+     */
+    environments: Pick<ConversationEnvironments, "forTool"> & Partial<Pick<ConversationEnvironments, "usableNow">>;
+    /** Background `Bash` tasks; absent in test stubs, where `run_in_background` is refused. */
+    background?: Pick<BackgroundTaskStore, "reserve" | "markStarted" | "failLaunch" | "finishStoppedLaunch" | "releaseStop" | "get" | "advanceOffset">;
+    /**
+     * What `TaskOutput` and `TaskStop` finish and stop tasks with; absent in test stubs, where both
+     * answer that background tasks are not available.
+     */
+    tasks?: {
+        finisher: Pick<BackgroundTaskFinisher, "finish">;
+        stopper: Pick<BackgroundTaskStopper, "stop">;
+    };
     attachments: Pick<AttachmentsService, "listForConversation" | "openForConversation">;
-    storage: Pick<StorageService, "kernel" | "available">;
-    /** `publishChanged`: `sandbox_deliver` announces `changed: files` (UI refresh B). */
-    eventLog: Pick<EventLog, "append"> & Partial<Pick<EventLog, "publishChanged">>;
-    config: () => KernelConfig;
+    storage: Pick<StorageService, "kernel" | "deployment" | "available">;
+    /**
+     * `publishChanged`: `Deliver` announces `changed: files` (UI refresh B). `latestOfType` reads the
+     * conversation's latest `environment_paths` (absent in test stubs, which record none).
+     */
+    eventLog: Pick<EventLog, "append" | "latestFileState"> & Partial<Pick<EventLog, "publishChanged" | "latestOfType">>;
+    config: Pick<KernelConfigService, "get">;
+    /** Where a mapped provider failure keeps its raw error (warn); absent in test stubs. */
+    log?: Pick<Logger, "warn">;
 }
-/** 回调拿到的沙箱：句柄、提供方与「调用 signal + 锁丢失」合并后的 signal（每个提供方调用都传它）。 */
+/**
+ * The sandbox a callback gets: the instance handle, the provider (every `exec` carries the
+ * holder's tag and the call's actor) and the call's signal combined with the lease's (pass it to
+ * every provider call).
+ */
 export interface SandboxSession {
+    /** The environment the call runs in (path leases are taken on it). */
+    environmentId: string;
     h: SandboxHandle;
-    p: SandboxProvider;
+    /** The instance's roots: every path the call builds or checks is under one of them. */
+    roots: SandboxRoots;
+    p: HeldProvider;
     signal: AbortSignal;
-    /** 本次是新建 / 重建的沙箱（之前复制进去的文件都已不在）。 */
-    reset: boolean;
 }
-/** 没有沙箱提供方时「工具不可用」的原因（进提醒与调用结果）。 */
-/** 本对话第一次用沙箱。 */
-export declare const SANDBOX_STARTED_NOTICE = "Sandbox started for this conversation (first use); the working directory is /workspace.";
-/** 沙箱被重建（之前的实例已销毁或不在了）。 */
-export declare const SANDBOX_RECREATED_NOTICE = "Sandbox was recreated; previous files are gone.";
+/** This conversation's first use of its environment (in the instance's workspace). */
+export declare const sandboxStartedNotice: (roots: SandboxRoots) => string;
+/** {@link sandboxStartedNotice} of an instance with the default roots. */
+export declare const SANDBOX_STARTED_NOTICE: string;
+/** A new instance came up on the environment's kept files. */
+export declare const SANDBOX_RESTARTED_NOTICE = "The environment's instance was restarted; files are kept, running processes are gone and temporary files may be gone.";
+/**
+ * The environment's files were reset (on request, or after they were lost) since this conversation
+ * last used it.
+ */
+export declare const sandboxFilesResetNotice: (roots: SandboxRoots) => string;
+/** {@link sandboxFilesResetNotice} of an instance with the default roots. */
+export declare const SANDBOX_FILES_RESET_NOTICE: string;
 /** 没有沙箱提供方时「工具不可用」的原因（进提醒，内核在后面补句号）：与调用时的错误同一句话。 */
 export declare const SANDBOX_UNAVAILABLE_REASON: string;
-/** 沙箱里附件所在目录。 */
-export declare const ATTACHMENTS_DIR = "/workspace/attachments";
-/** 已同步附件的标记文件：`{ <附件 id>: <文件名> }`。 */
-export declare const SYNC_MARKER = "/workspace/attachments/.capybara-sync.json";
+/** The error of a sandbox call in a deployment without a sandbox provider. */
+export declare function noSandboxError(): ToolError;
+/**
+ * A provider call that never connected (refused, unknown host, unreachable network): the request
+ * did not reach the provider, so the call did nothing in the sandbox.
+ */
+export declare const SANDBOX_UNREACHABLE_TEXT = "The sandbox provider can't be reached (the connection failed), so this call did nothing in the sandbox; retrying won't help until a super admin checks the sandbox extension's configuration (Admin console \u2192 Extensions). Continue without the sandbox, or ask the person to have a super admin check it.";
+/** A provider connection that broke during the call: the provider may have acted before it broke. */
+export declare const SANDBOX_CONNECTION_DROPPED_TEXT = "The connection to the sandbox provider broke during this call, so it may or may not have taken effect; check the sandbox state before retrying. If it fails again, continue without the sandbox and ask the person to have a super admin check the sandbox extension's configuration (Admin console \u2192 Extensions).";
+/** The directory of attachments in the environment (each conversation has a subdirectory). */
+export declare const attachmentsRoot: (roots: SandboxRoots) => string;
+/** {@link attachmentsRoot} of an instance with the default roots. */
+export declare const ATTACHMENTS_ROOT: string;
+/**
+ * One conversation's attachment directory: the first 12 hex digits of the root conversation's
+ * UUID, so conversations sharing an environment do not overwrite each other's files.
+ */
+export declare const attachmentsDir: (roots: SandboxRoots, rootConversationId: string) => string;
+/** The conversation's marker of synced attachments: `{ <attachment id>: <file name> }`. */
+export declare const syncMarkerPath: (roots: SandboxRoots, rootConversationId: string) => string;
+/**
+ * Whether a path, or a Grep output line starting with one, belongs to a sync marker of the
+ * instance with `roots` (hidden from Glob / Grep). Build it once per call and test every entry.
+ */
+export declare function syncMarkerMatcher(roots?: SandboxRoots): (pathOrLine: string) => boolean;
 /** 附件文件名的上限（UTF-8 字节，常见文件系统单个文件名上限 255 字节，留出 `-N` 后缀的余量）。 */
 export declare const ATTACHMENT_NAME_MAX_BYTES = 200;
 /**
- * 沙箱工具时限里额外留出的余量（毫秒）：创建 / 恢复沙箱，以及命令超时后停命令的兜底——E2B 杀进程脚本没跑完时
- * 重启沙箱（杀进程最多约 20 秒，加 pause + 冷启动 connect 最多 120 秒，约 160 秒）。首次创建时拉取镜像不在其内
- * （部署时应预先拉好 `sandbox.image`，见 plugins/sandbox-docker/README.md）。
+ * Extra margin (ms) on top of a sandbox tool's time limit: creating / resuming the sandbox, and the
+ * fallback for stopping a command after its timeout (when the E2B kill script does not finish, the
+ * sandbox is restarted: up to about 20 s to kill, plus pause and a cold connect of up to 120 s, about
+ * 160 s). Pulling the image on first creation is not included (deployments pre-pull
+ * `sandbox.image`; see the sandbox-docker plugin's README in capybara-hq/plugins).
  */
 export declare const SANDBOX_SETUP_MARGIN_MS = 180000;
 /**
@@ -75,10 +142,20 @@ export declare function display(zh: string, en: string): {
 export declare function clip(s: string, max: number): string;
 /** 结果正文前加上沙箱状态说明。 */
 export declare function withNotices(notices: readonly string[], text: string): string;
-/** 校验沙箱内路径（`validateSandboxPath`）；不合法抛给模型可执行的错误。 */
-export declare function checkPath(path: string, field?: string): string;
-/** 写入类工具的路径：`/skills` 是技能文件的只读副本。 */
-export declare function checkWritable(path: string): string;
+/**
+ * The root-independent checks of a path (`validateSandboxPathShape`: non-empty, absolute, no
+ * control characters, no empty or `..` segments), run before the call enters its environment, so
+ * a malformed path never creates or resumes an instance; root membership is checked inside
+ * ({@link checkPath}).
+ */
+export declare function checkPathShape(path: string, field?: string): void;
+/**
+ * Checks a path inside the instance with `roots` (`validateSandboxPath`: absolute, under one of its
+ * roots); an invalid one throws an error the model can act on, naming the instance's roots.
+ */
+export declare function checkPath(path: string, roots: SandboxRoots, field?: string): string;
+/** A writing tool's `file_path`: the skills root is the read-only copy of the skill files. */
+export declare function checkWritable(path: string, roots: SandboxRoots): string;
 /** POSIX shell 单引号转义。 */
 export declare function shellQuote(s: string): string;
 /**
@@ -91,24 +168,49 @@ export declare function assignAttachmentNames(items: readonly {
     name: string;
 }[], used: ReadonlySet<string>): Map<string, string>;
 /**
- * 在本对话的沙箱上执行 `fn`（`SandboxService.withSandbox`：懒创建、恢复、重建）：先同步附件，
- * 再执行；返回结果与要加在结果开头的状态说明（首次使用 / 重建 / 新复制的附件）。
- * `withSandbox` 遇到实例不在时会重建并再调用一次回调，说明按最后一次调用的为准。
+ * Sandbox service errors → actionable text for the model; anything else is returned unchanged
+ * (the pipeline reports a generic tool failure). A provider that cannot be reached becomes a
+ * fixed text (providers never write model-visible text) with `kind: "unavailable"`, and its raw
+ * error is logged to `log` as a warning (the pipeline logs only errors it did not get as a
+ * `ToolError`).
+ */
+export declare function mapSandboxError(e: unknown, log: Pick<Logger, "warn"> | undefined): unknown;
+/**
+ * Runs `fn` in the environment of the call's conversation (a sub-agent: its root's): resolves and
+ * checks the environment for the conversation's owner (binding an unbound conversation to the
+ * owner's default first), then `SandboxService.withSandbox` (the instance created, resumed or
+ * rebuilt on the kept files as needed, every `exec` carrying the call's actor). Attachments are
+ * synced first. Returns the value and the notices to put before the result (first use, a new
+ * instance, newly copied attachments). When `withSandbox` rebuilds a gone instance and calls
+ * `fn` again, the notices are the last call's. The instance's roots are recorded for the model
+ * on the conversation's first call and whenever they change ({@link recordEnvironmentPaths}).
  */
 export declare function inSandbox<T>(deps: SandboxToolDeps, ctx: BuiltinCallContext, fn: (s: SandboxSession) => Promise<T>): Promise<{
     value: T;
     notices: string[];
 }>;
-/** The conversation whose sandbox a call uses (the parent's for a sub-agent). */
+/** The conversation whose environment a call uses (the root conversation's for a sub-agent). */
 export declare const sandboxConversationOf: (ctx: BuiltinCallContext) => string;
 /**
- * Runs `fn` under the per-path lease of `path` in the call's sandbox (spec §10.4: the kernel's own
- * read-modify-write of one file never loses another holder's update). `fn` gets `signal` combined
- * with the path lease's: pass it to every provider call, so a lost path lease stops the write.
- * Without `pathLease` (test stubs) it just runs `fn` with `signal`.
+ * Runs `fn` under the per-path lease of `path` in the session's environment (spec §10.4: the
+ * kernel's own read-modify-write of one file never loses another holder's update, from any
+ * conversation sharing the environment). `fn` gets `signal` combined with the path lease's: pass
+ * it to every provider call, so a lost path lease stops the write. Without `pathLease` (test
+ * stubs) it just runs `fn` with `signal`.
+ */
+export declare function withPathLease<T>(deps: Pick<SandboxToolDeps, "sandbox">, s: Pick<SandboxSession, "environmentId">, path: string, signal: AbortSignal, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
+/**
+ * Whether a sandbox tool call of the conversation tree rooted at `conversationId` can run: a
+ * cloud provider is loaded, or (ruling R8) the conversation's environment runs on a registered
+ * kernel provider (`@device`). Without a conversation only the cloud provider counts.
+ */
+export declare function sandboxUsable(deps: Pick<SandboxToolDeps, "sandbox" | "environments">, orgId: string, conversationId: string | undefined): Promise<boolean>;
+/**
+ * The reason the registry reports the sandbox tools unavailable with, or null when they can run
+ * ({@link sandboxUsable}; the listing passes the root conversation of the run). An eval replay
+ * lists them as available (`replay`: its calls are never executed). `memo` (one per listing)
+ * makes every sandbox tool of a listing share one answer.
  */
-export declare function withPathLease<T>(deps: Pick<SandboxToolDeps, "sandbox">, ctx: BuiltinCallContext, path: string, signal: AbortSignal, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
-/** 本部署是否有沙箱：没有时返回「不可用」原因（注册表据此把沙箱工具报为不可用）。 */
-export declare const unavailableWhenNoSandbox: (deps: Pick<SandboxToolDeps, "sandbox">) => () => string | null;
+export declare const unavailableWhenNoSandbox: (deps: Pick<SandboxToolDeps, "sandbox" | "environments">) => (ctx: ToolListingScope) => Promise<string | null>;
 /** 读出的字节是否像二进制（开头 8 KB 里有 NUL）。 */
 export declare function looksBinary(data: Uint8Array): boolean;