@capybara-hq/kernel 0.1.0-rc.8 → 0.1.0-rc.9

package/dist/sandbox/sandbox.service.js

@@ -8,7 +8,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { randomUUID } from "node:crypto";
-import { isFileSystemGoneError, isSandboxGoneError, } from "@capybara-hq/plugin-sdk";
+import { isFileSystemGoneError, isSandboxGoneError, rootsOf, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql, } from "kysely";
 import { BackgroundTaskStore } from "../background/store.js";
@@ -21,7 +21,7 @@ import { KERNEL_LOGGER, REDIS } from "../infra/tokens.js";
 import { effectiveSandboxEgress, effectiveSandboxLimits, readOrgSettings, } from "../orgs/settings.service.js";
 import { canonicalJson } from "../tools/canonical-json.js";
 import { SandboxLeases, SandboxLockLostError, sandboxBusy, } from "./leases.js";
-import { SandboxProviders } from "./providers.js";
+import { DEVICE_PROVIDER, providerForEnvironment, SandboxProviders, } from "./providers.js";
 // Moved to leases.ts (phase C); re-exported for existing importers
 export { SANDBOX_LOCK_PREFIX, SANDBOX_LOCK_TTL_MS, SandboxLockLostError, sandboxBusy, } from "./leases.js";
 /** Margin (ms) of a holder record's TTL beyond the longest command: by then the in-sandbox limit has ended its commands. */
@@ -47,8 +47,14 @@ const opSignal = (lease) => AbortSignal.any([lease.signal, AbortSignal.timeout(S
 export const environmentResourceName = (environmentId) => `cap-env-${environmentId}`;
 /** The environment is missing, deleted, or not in the caller's org (404; ids cannot be probed). */
 export const environmentNotFound = () => new ApiError("environment.not_found", "This environment does not exist or was deleted.");
-/** The environment's file system is gone at the provider (409); never replaced silently. */
-export const environmentFilesLost = () => new ApiError("environment.files_lost", "The environment's files are gone; reset its files from the environments page to start with an empty workspace.");
+/**
+ * The environment's file system is gone at the provider (409); never replaced silently. On a
+ * connected machine (`device`, details `[{ source: "device" }]`) the directory is the machine
+ * owner's: `capybara-device logout`, then `login` into the environment, recreates it (ruling R24).
+ */
+export const environmentFilesLost = (device = false) => device
+    ? new ApiError("environment.files_lost", "The environment's directory is gone from its connected machine; run capybara-device logout, then capybara-device login into this environment, on that machine to recreate it.", [{ source: "device" }])
+    : new ApiError("environment.files_lost", "The environment's files are gone; reset its files from the environments page to start with an empty workspace.");
 /**
  * The row still records the instance `gone` (same handle and same `created_at`). Handles compare
  * canonically: a jsonb round trip reorders a multi-key handle's keys (final review m9).
@@ -185,11 +191,18 @@ async function inPool(items, limit, fn) {
  *   row's `created_at` (set by the fenced write after each `create`); the handle alone is the same
  *   after a rebuild on providers whose handle is the instance name (sandbox-docker).
  *
+ * - **Provider per environment** (environments spec §6): each call resolves the provider from
+ *   the environment's `environments.provider` ({@link providerForEnvironment}): a `device`
+ *   environment runs on the kernel-internal `@device` provider (never the cloud one), a cloud
+ *   environment on the loaded `sandbox@2` extension. A `@device` instance is never suspended or
+ *   destroyed for inactivity; a deleted `@device` environment (or one of a deleted org) is
+ *   destroyed by the sweep like any other.
+ *
  * Files kept by another provider than the current one make the environment unusable
  * (`environment.unavailable`) until that provider is back; deleting it still works while that
- * provider is loaded ({@link SandboxProviders.lookup}). Without a provider {@link available} is false and
- * uses throw `sandbox.unavailable` (503). No in-process state: replicas share it through PG and
- * Redis.
+ * provider is loaded ({@link SandboxProviders.forName}). Without the environment's provider
+ * {@link availableFor} is false and uses throw `sandbox.unavailable` (503). No in-process state:
+ * replicas share it through PG and Redis.
  */
 let SandboxService = class SandboxService {
     db;
@@ -202,7 +215,7 @@ let SandboxService = class SandboxService {
     constructor(db, 
     /** The record of the instance each holder last used (`capk:sandbox-seen:…`). */
     redis, leases, 
-    /** The `sandbox@2` provider (read at every call: providers are ready after the extension load). */
+    /** The providers (read at every call: providers are ready after the extension load). */
     providers, config, log, 
     /** Background tasks lost while their process may live on (killed after a resume). */
     background) {
@@ -218,9 +231,38 @@ let SandboxService = class SandboxService {
     get pollMs() {
         return this.leases.pollMs;
     }
-    /** Whether there is a sandbox provider. */
-    get available() {
-        return this.providers.current() !== undefined;
+    /**
+     * Whether there is a cloud sandbox provider (a loaded `sandbox@2` extension). For gates that have
+     * no environment yet (tool listing, skill files); a call on an environment asks
+     * {@link availableFor}.
+     */
+    get cloudAvailable() {
+        return this.providers.cloud() !== undefined;
+    }
+    /** Whether the environment's provider is there (`@device` registered, or a cloud provider). */
+    async availableFor(environmentId) {
+        return (await this.providerOf(environmentId)) !== undefined;
+    }
+    /**
+     * The provider the environment works with, read from its row ({@link providerForEnvironment});
+     * a missing row (or one of another org, with `orgId`) reads as a cloud environment, whose use
+     * then fails as not found.
+     */
+    async providerOf(environmentId, orgId) {
+        const row = await this.db
+            .selectFrom("environments")
+            .select("provider")
+            .where("id", "=", environmentId)
+            .$if(orgId !== undefined, (q) => q.where("org_id", "=", orgId))
+            .executeTakeFirst();
+        return providerForEnvironment(this.providers, row?.provider ?? null);
+    }
+    /** {@link providerOf}, or `sandbox.unavailable` (503) without it. */
+    async require(environmentId, orgId) {
+        const p = await this.providerOf(environmentId, orgId);
+        if (!p)
+            throw sandboxUnavailable();
+        return p;
     }
     /** Concurrent holders of one environment (`sandbox.maxConcurrentCommands`, read at every use). */
     get cap() {
@@ -290,7 +332,7 @@ let SandboxService = class SandboxService {
      * too) are thrown as they are.
      */
     async ifRunning(environmentId, instance, fn, signal = new AbortController().signal) {
-        const p = this.require();
+        const p = await this.require(environmentId);
         const env = environmentId;
         const deadline = Date.now() + this.config.get().sandbox.lockWaitSeconds * 1000;
         const token = randomUUID();
@@ -319,7 +361,14 @@ let SandboxService = class SandboxService {
                     try {
                         const impl = tagged(p.impl, lease.token, undefined, () => this.register(env, lease.token));
                         const sig = AbortSignal.any([signal, lease.signal]);
-                        return { kind: "ran", value: await fn(impl, e.handle, sig) };
+                        try {
+                            return { kind: "ran", value: await fn(impl, e.handle, sig) };
+                        }
+                        catch (err) {
+                            if (isFileSystemGoneError(err))
+                                throw await this.filesGone(env, p, e);
+                            throw err;
+                        }
                     }
                     finally {
                         await this.leave(env, e);
@@ -353,12 +402,13 @@ let SandboxService = class SandboxService {
      * - When `fn` throws `SandboxGoneError` (the instance is gone) the instance is rebuilt on the
      *   kept files (or the one another holder rebuilt is taken) and `fn` runs once more with
      *   `restarted: true`; a second `gone` is thrown. Other errors are thrown as they are.
-     * - Lost files throw `environment.files_lost` (409).
+     * - Lost files throw `environment.files_lost` (409), also when `fn` throws
+     *   `FileSystemGoneError` (the files are then recorded lost, ruling R24).
      * - When `ctx.holderConversationId` last used another instance (another holder rebuilt it
      *   meanwhile), `info.restarted` is true, so it learns its processes are gone (final review m5).
      */
     async withSandbox(ctx, fn, signal) {
-        const p = this.require();
+        const p = await this.require(ctx.environmentId, ctx.orgId);
         const env = ctx.environmentId;
         const holder = ctx.holderConversationId;
         let e = await this.seenBy(env, holder, await this.enter(ctx, p, signal, null));
@@ -367,6 +417,8 @@ let SandboxService = class SandboxService {
                 return await this.runAs(e, ctx, p, fn, signal);
             }
             catch (err) {
+                if (isFileSystemGoneError(err))
+                    throw await this.filesGone(env, p, e);
                 if (!isSandboxGoneError(err))
                     throw err;
                 this.log.info("sandbox instance is gone during use; recreating", { environmentId: env });
@@ -374,13 +426,47 @@ let SandboxService = class SandboxService {
                 const prev = e;
                 await this.leave(env, prev);
                 e = await this.seenBy(env, holder, await this.enter(ctx, p, signal, gone));
-                return await this.runAs({ ...e, info: { fresh: true, restarted: true } }, ctx, p, fn, signal);
+                try {
+                    return await this.runAs({ ...e, info: { fresh: true, restarted: true } }, ctx, p, fn, signal);
+                }
+                catch (err2) {
+                    if (isFileSystemGoneError(err2))
+                        throw await this.filesGone(env, p, e);
+                    throw err2;
+                }
             }
         }
         finally {
             await this.leave(env, e);
         }
     }
+    /**
+     * Ruling R24: an operation on the held instance `e` found its file system gone. Records
+     * `fs_status = 'lost'` while the row still records that instance on its file system (the
+     * instance handle stays, so a reset still destroys it), moving the fence on, and returns
+     * `environment.files_lost` to throw. Uses then fail until the files are reset (a connected
+     * machine: until a new login, which resets the row). A failed write only logs.
+     */
+    async filesGone(env, p, e) {
+        this.log.warn("environment file system is gone at the provider; its files are lost", {
+            environmentId: env,
+            provider: p.plugin,
+        });
+        try {
+            await this.db
+                .updateTable("environment_instances")
+                .set((eb) => ({ fs_status: "lost", generation: eb("generation", "+", 1) }))
+                .where("environment_id", "=", env)
+                .where("fs_status", "=", "ready")
+                // `createdAt` is the row's value read back in milliseconds
+                .where(sql `date_trunc('milliseconds', created_at)`, "=", new Date(e.createdAt))
+                .execute();
+        }
+        catch (err) {
+            this.log.warn("cannot record lost environment files", { environmentId: env, err });
+        }
+        return environmentFilesLost(p.plugin === DEVICE_PROVIDER);
+    }
     /**
      * Records that `holder` uses the instance of `e` (`capk:sandbox-seen:<env>:<holder>` =
      * `<created_at>:<file system id>`, with a TTL of the inactivity destruction plus a day). When the
@@ -415,7 +501,7 @@ let SandboxService = class SandboxService {
         const sig = AbortSignal.any([signal, e.lease.signal]);
         const env = ctx.environmentId;
         const impl = tagged(p.impl, e.lease.token, ctx.actor, () => this.register(env, e.lease.token));
-        return fn(e.handle, impl, e.info, sig);
+        return fn(e.handle, impl, { ...e.info, roots: rootsOf(e.handle) }, sig);
     }
     /**
      * Becomes a holder: loops until it has a shared lease on a running instance, or `sandbox.busy`.
@@ -480,10 +566,14 @@ let SandboxService = class SandboxService {
     foreign(_ctx) {
         return environmentNotFound();
     }
-    /** Recorded running with the current provider, and not the instance found gone. */
+    /**
+     * Recorded running with the current provider on files not lost (lost ones go through the
+     * exclusive path, which refuses them), and not the instance found gone.
+     */
     usable(row, p, gone) {
         return (row !== undefined &&
             row.status === "running" &&
+            row.fs_status !== "lost" &&
             row.provider === p.plugin &&
             row.handle !== null &&
             !isInstance(row, gone));
@@ -624,7 +714,8 @@ let SandboxService = class SandboxService {
      * many it suspended. Called every minute by the `sandbox-suspend-idle` cron.
      */
     async suspendIdle(now) {
-        const p = this.providers.current();
+        // cloud only: suspendDue keeps to this provider's rows, so `@device` is never suspended here
+        const p = this.providers.cloud();
         if (!p)
             return 0;
         const due = this.suspendDue(now, p.plugin);
@@ -666,31 +757,45 @@ let SandboxService = class SandboxService {
      * (the instance only; the file system is kept and the next use builds a new instance on it); an
      * environment that was deleted, or whose org was deleted, loses its instance and its file system
      * and its row is deleted (as {@link destroyEnvironment} does). Environments with any holder are
-     * skipped. Returns how many it destroyed. Called hourly by the `sandbox-destroy-inactive` cron.
+     * skipped. Inactivity never destroys a `@device` instance; a gone `@device` environment is
+     * destroyed like any other while `@device` is registered. Returns how many it destroyed. Called
+     * hourly by the `sandbox-destroy-inactive` cron.
      */
     async destroyInactive(now) {
-        const p = this.providers.current();
-        if (!p)
-            return 0;
+        const p = this.providers.cloud();
+        const device = this.providers.forName(DEVICE_PROVIDER) !== undefined;
         let n = 0;
-        const gone = (eb) => this.environmentGone(eb);
-        await inPool(await this.candidates(gone), SWEEP_CONCURRENCY, async ({ environment_id: id }) => {
-            const done = await this.tryLocked(id, async (lease) => {
-                const row = await this.db
-                    .selectFrom("environment_instances")
-                    .selectAll()
-                    .where("environment_id", "=", id)
-                    .where(gone)
-                    .executeTakeFirst();
-                if (!row)
-                    return false;
-                await this.destroyRow(row, p, lease, "environment");
-                return true;
+        // Gone environments (deleted, or of a deleted org) on every provider that is here, `@device`
+        // too (its destroy calls never need the machine online); rows whose provider is missing wait.
+        const here = (eb) => eb.or([
+            ...(p ? [this.cloudRow(eb)] : []),
+            ...(device ? [eb("provider", "=", DEVICE_PROVIDER)] : []),
+        ]);
+        const gone = (eb) => eb.and([here(eb), this.environmentGone(eb)]);
+        if (p || device) {
+            await inPool(await this.candidates(gone), SWEEP_CONCURRENCY, async ({ environment_id: id }) => {
+                const done = await this.tryLocked(id, async (lease) => {
+                    const row = await this.db
+                        .selectFrom("environment_instances")
+                        .selectAll()
+                        .where("environment_id", "=", id)
+                        .where(gone)
+                        .executeTakeFirst();
+                    const owner = row && this.rowProvider(row);
+                    if (!row || !owner)
+                        return false;
+                    await this.destroyRow(row, owner, lease, "environment");
+                    return true;
+                });
+                if (done)
+                    n++;
             });
-            if (done)
-                n++;
-        });
-        const idle = this.instanceDue(now);
+        }
+        // inactivity destroys cloud instances only: `@device` instances are never swept
+        if (!p)
+            return n;
+        const due = this.instanceDue(now);
+        const idle = (eb) => eb.and([this.cloudRow(eb), due(eb)]);
         await inPool(await this.candidates(idle), SWEEP_CONCURRENCY, async ({ environment_id: id }) => {
             const done = await this.tryLocked(id, async (lease) => {
                 const row = await this.db
@@ -712,9 +817,11 @@ let SandboxService = class SandboxService {
     /**
      * Destroys the environment's instance, then its file system, then deletes its instance row
      * (environment deletion, offboarding); nothing to do without a row. Waits for the exclusive lease
-     * (with intent, so running commands finish and new ones wait) up to 10 minutes. Without a
-     * provider it only warns (the destruction sweep finishes a deleted environment later). Files kept
-     * by another provider that is not loaded cannot be destroyed: it throws and the row stays.
+     * (with intent, so running commands finish and new ones wait) up to 10 minutes. Without the
+     * environment's provider it throws and the row stays, marked `sweep_failed_at` (the job is
+     * retried, and the destruction sweep finishes a deleted environment once the provider is back).
+     * Files kept by another provider that is not loaded cannot be destroyed: it throws and the row
+     * stays.
      */
     async destroyEnvironment(environmentId) {
         const row = await this.db
@@ -724,10 +831,15 @@ let SandboxService = class SandboxService {
             .executeTakeFirst();
         if (!row)
             return;
-        const p = this.providers.current();
+        const p = await this.providerOf(environmentId);
         if (!p) {
-            this.log.warn("cannot destroy environment: no sandbox provider", { environmentId });
-            return;
+            await this.db
+                .updateTable("environment_instances")
+                .set({ sweep_failed_at: sql `now()` })
+                .where("environment_id", "=", environmentId)
+                .execute();
+            throw new Error(`cannot destroy environment ${environmentId}: its sandbox provider is not there; ` +
+                "the destruction sweep retries it");
         }
         const lease = await this.leases.acquireExclusive(environmentId, AbortSignal.timeout(EXCLUSIVE_WAIT_MS), undefined, { intent: true });
         try {
@@ -750,7 +862,7 @@ let SandboxService = class SandboxService {
      * creates a new one. Nothing to do without a row. Throws `sandbox.unavailable` without a provider.
      */
     async resetFileSystem(environmentId) {
-        const p = this.require();
+        const p = await this.require(environmentId);
         const lease = await this.leases.acquireExclusive(environmentId, AbortSignal.timeout(EXCLUSIVE_WAIT_MS), undefined, { intent: true });
         try {
             const row = await this.db
@@ -839,12 +951,6 @@ let SandboxService = class SandboxService {
         }
         await this.background.clearKill(cleared.map((r) => r.id));
     }
-    require() {
-        const p = this.providers.current();
-        if (!p)
-            throw sandboxUnavailable();
-        return p;
-    }
     /**
      * A fenced write: only while the lease holds and the row's generation is still the one read
      * under it (and incremented); otherwise {@link SandboxLockLostError}.
@@ -968,7 +1074,7 @@ let SandboxService = class SandboxService {
         // kept running (a stalled sweep) then fails its next write.
         await this.fenced(held, id, fence, {});
         if (row.fs_status === "lost")
-            throw environmentFilesLost();
+            throw environmentFilesLost(p.plugin === DEVICE_PROVIDER);
         if (row.provider !== null &&
             row.provider !== p.plugin &&
             (row.fs_status !== "none" || row.handle !== null)) {
@@ -1080,7 +1186,7 @@ let SandboxService = class SandboxService {
                 provider: p.plugin,
             });
             await this.fenced(held, id, fence, { fs_status: "lost", status: "none" });
-            throw environmentFilesLost();
+            throw environmentFilesLost(p.plugin === DEVICE_PROVIDER);
         }
         let createdAt;
         try {
@@ -1115,7 +1221,7 @@ let SandboxService = class SandboxService {
      * usable; an abort is thrown.
      */
     async dropUnrecordedFiles(id, provider, signal) {
-        const old = this.providers.lookup(provider);
+        const old = this.providers.forName(provider)?.impl;
         if (!old) {
             this.log.warn("environment file system may have been made by a provider that is not loaded; it may leak", { environmentId: id, provider });
             return;
@@ -1138,7 +1244,7 @@ let SandboxService = class SandboxService {
      * false; otherwise warns and returns true (the record must be kept).
      */
     async retire(id, provider, handle, signal) {
-        const old = this.providers.lookup(provider);
+        const old = this.providers.forName(provider)?.impl;
         if (old) {
             try {
                 await old.destroy(handle, AbortSignal.any([signal, AbortSignal.timeout(SWEEP_OP_TIMEOUT_MS)]));
@@ -1175,7 +1281,7 @@ let SandboxService = class SandboxService {
         }
         else if (!row.handle && row.status === "creating") {
             // the provider may have built it already: only the name finds it
-            const impl = owner === p.plugin ? p.impl : this.providers.lookup(owner);
+            const impl = owner === p.plugin ? p.impl : this.providers.forName(owner)?.impl;
             await impl?.destroyByName(environmentResourceName(id), signal);
         }
         if (row.prev_handle && row.prev_provider && !("prev_handle" in prev)) {
@@ -1194,7 +1300,7 @@ let SandboxService = class SandboxService {
     async destroyFiles(row, p, signal, lenient = false) {
         const id = row.environment_id;
         const owner = row.provider ?? p.plugin;
-        const impl = owner === p.plugin ? p.impl : this.providers.lookup(owner);
+        const impl = owner === p.plugin ? p.impl : this.providers.forName(owner)?.impl;
         if (!impl) {
             if (row.fs_handle === null)
                 return;
@@ -1256,6 +1362,17 @@ let SandboxService = class SandboxService {
             eb.or([eb("last_used_at", "<", idleBefore), eb("running_since", "<", runningBefore)]),
         ]);
     }
+    /** The provider of an instance row: an internal one (`@device`) by name, else the cloud one. */
+    rowProvider(row) {
+        return providerForEnvironment(this.providers, row.provider);
+    }
+    /**
+     * A row the idle sweeps may touch: not on a kernel-internal provider (`@device` instances live on
+     * people's machines and are never suspended or destroyed for inactivity).
+     */
+    cloudRow(eb) {
+        return eb.or([eb("provider", "is", null), eb("provider", "not like", "@%")]);
+    }
     /** The environment was deleted, or its org was: the instance and the files go. */
     environmentGone(eb) {
         return eb.or([

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

@@ -9,8 +9,8 @@ export declare const BASH_DESCRIPTION_MAX_CHARS = 120;
 export declare const BASH_SPILL_CHARS = 30000;
 /**
  * 命令结果 → 给模型的文本。`budgetClamped`：运行的时限把超时收紧到了 `seconds`（Ruling M20），超时说明改为
- * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeout。
+ * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeout。`workspace`: the instance's workspace root.
  */
-export declare function formatExec(r: ExecResult, seconds: number, budgetClamped?: boolean): string;
+export declare function formatExec(r: ExecResult, seconds: number, budgetClamped?: boolean, workspace?: string): string;
 /** 内置工具 `Bash`：在本对话的沙箱里执行命令。 */
 export declare function sandboxBashTool(deps: SandboxToolDeps): BuiltinTool;

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

@@ -1,4 +1,4 @@
-import { ToolError } from "@capybara-hq/plugin-sdk";
+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";
@@ -14,14 +14,14 @@ const SPEC = {
     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 copied to /workspace/attachments/<conversation>/ " +
-        "(the result names the paths), " +
-        "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 ReadToolOutput. A command that runs longer than " +
         "timeout milliseconds is stopped. Prefer Read, Write, Edit, Glob and " +
@@ -32,13 +32,13 @@ const SPEC = {
         "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 /workspace/.capybara/tasks. Read the output with TaskOutput (or Read) and stop the " +
+        "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 /workspace.",
+        "sandbox.limits.maxRunningMinutes), so keep its results in files under the workspace directory.",
     inputSchema: {
         type: "object",
         properties: {
@@ -71,9 +71,9 @@ const SPEC = {
 const msFor = (input, maxSeconds) => Math.min(input.timeout ?? BASH_DEFAULT_TIMEOUT_SECONDS * 1000, maxSeconds * 1000);
 /**
  * 命令结果 → 给模型的文本。`budgetClamped`：运行的时限把超时收紧到了 `seconds`（Ruling M20），超时说明改为
- * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeout。
+ * 指向 `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$/, ""));
@@ -82,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 timeout in milliseconds (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.]");
@@ -136,8 +136,6 @@ async function runInBackground(deps, ctx, input) {
     if (ctx.runId === undefined) {
         throw new ToolError("Background tasks can only be started from an agent run; call Bash without run_in_background.");
     }
-    if (!sandbox.available)
-        throw noSandboxError();
     const currentInstance = sandbox.currentInstance.bind(sandbox);
     const cfg = deps.config.get();
     const maxMs = backgroundMaxSeconds(cfg) * 1000;
@@ -152,6 +150,8 @@ async function runInBackground(deps, ctx, input) {
     catch (e) {
         throw mapSandboxError(e);
     }
+    if (!(await sandbox.availableFor(environmentId)))
+        throw noSandboxError();
     const maxTasks = cfg.sandbox.background.maxTasks;
     const id = newTaskId();
     const description = input.description ?? clip(input.command, 120);
@@ -185,22 +185,26 @@ async function runInBackground(deps, ctx, input) {
             await deps.eventLog.publishChanged(c, "background");
         }
     };
-    const large = Math.ceil(Buffer.byteLength(input.command, "utf8") / 3) * 4 > LARGE_COMMAND_BASE64_BYTES
-        ? " 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."
+    // 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, p, signal }) => {
+        ({ 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, `/workspace/${taskSidPath(id)}`, {
+                    .readFile(h, `${roots.workspace}/${taskSidPath(id)}`, {
                     maxBytes: 64,
                     signal: AbortSignal.timeout(KILL_SESSION_TIMEOUT_MS),
                 })
@@ -212,7 +216,7 @@ async function runInBackground(deps, ctx, input) {
             try {
                 r = await p.exec(h, {
                     command: launchScript(id, input.command, seconds),
-                    cwd: "/workspace",
+                    cwd: roots.workspace,
                     timeoutMs: LAUNCH_EXEC_TIMEOUT_MS,
                     maxOutputBytes: LAUNCH_MAX_OUTPUT_BYTES,
                     signal,
@@ -240,6 +244,7 @@ async function runInBackground(deps, ctx, input) {
                 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");
@@ -275,15 +280,15 @@ async function runInBackground(deps, ctx, input) {
             const why = e instanceof Error ? e.message : String(e);
             await background.failLaunch(id, `launch failed: ${why}`).catch(() => undefined);
             await announce();
-            if (large === "" || e instanceof ToolError)
+            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.${large}`);
+            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.${large}`);
+        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();
@@ -303,7 +308,12 @@ async function runInBackground(deps, ctx, input) {
         : "";
     const shown = clip(input.command, 120);
     return {
-        content: [{ type: "text", text: withNotices(notices, startedText(id, description) + lowered) }],
+        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}`),
@@ -338,12 +348,14 @@ export function sandboxBashTool(deps) {
             // 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;
-            const { value: r, notices } = await inSandbox(deps, ctx, ({ h, p, signal }) => {
+            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",
+                    cwd: roots.workspace,
                     timeoutMs: ms,
                     maxOutputBytes: MAX_OUTPUT_BYTES,
                     signal,
@@ -355,7 +367,7 @@ export function sandboxBashTool(deps) {
             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) + lowered;
+            const text = formatExec(r, seconds, clamped, workspace) + lowered;
             return {
                 content: [{ type: "text", text: withNotices(notices, text) }],
                 isError: r.timedOut || r.exitCode === null,