@capybara-hq/kernel 0.1.0-rc.3 → 0.1.0-rc.5

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

@@ -1,4 +1,7 @@
-import { clip, display, inSandbox, runBudgetNote, runTimeLeftMs, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+import { 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). */
@@ -16,7 +19,8 @@ const SPEC = {
         "filesystem. The working directory is /workspace; 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, " +
+        "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 " +
         "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 " +
@@ -24,7 +28,17 @@ const SPEC = {
         "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 /workspace/.capybara/tasks. 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.",
     inputSchema: {
         type: "object",
         properties: {
@@ -42,7 +56,11 @@ const SPEC = {
             timeout: {
                 type: "integer",
                 minimum: 1,
-                description: `Milliseconds before the command is stopped. Default ${BASH_DEFAULT_TIMEOUT_SECONDS * 1000}; the deployment sets a maximum (7200000 by default); a larger value is lowered to it.`,
+                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"],
@@ -79,6 +97,218 @@ export function formatExec(r, seconds, budgetClamped = false) {
     }
     return parts.join("\n");
 }
+/** 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.");
+    }
+    if (!sandbox.available)
+        throw noSandboxError();
+    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);
+    }
+    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");
+        }
+    };
+    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."
+        : "";
+    // 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 }) => {
+            // 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)}`, {
+                    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: "/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,
+                });
+                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 (large === "" || 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}`);
+        }
+    }
+    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}`);
+    }
+    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) + 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 {
@@ -89,10 +319,17 @@ export function sandboxBashTool(deps) {
         // 命令自己的超时先到（提供方停掉命令、返回 timedOut），管线的时限再留出等锁与创建 / 恢复的余量
         timeoutMs: (input) => {
             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 msFor(input, max) + sandboxBaseTimeoutMs(cfg);
         },
         async run(input, ctx) {
+            if (input.run_in_background === true) {
+                return runInBackground(deps, ctx, input);
+            }
             const { command, description } = input;
             const max = deps.config.get().sandbox.limits.maxCommandSeconds;
             const requested = input.timeout;

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

@@ -1,40 +1,73 @@
-import { type SandboxHandle, type SandboxProvider } from "@capybara-hq/plugin-sdk";
+import { type SandboxHandle, 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 ConversationEnvironments } from "../../../environments/conversation-environments.js";
 import type { KernelConfigService } from "../../../infra/config/kernel-config.service.js";
-import { type SandboxService } from "../../../sandbox/sandbox.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";
 /** 沙箱工具的依赖（都按调用时取，多副本下无进程内状态）。 */
 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, "available" | "withSandbox"> & Partial<Pick<SandboxService, "pathLease" | "currentInstance" | "ifRunning">>;
+    /** The environment a call enters: the root conversation's, checked for its owner every call. */
+    environments: Pick<ConversationEnvironments, "forTool">;
+    /** 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">;
+    storage: Pick<StorageService, "kernel" | "deployment" | "available">;
     /** `publishChanged`: `Deliver` announces `changed: files` (UI refresh B). */
     eventLog: Pick<EventLog, "append" | "latestFileState"> & Partial<Pick<EventLog, "publishChanged">>;
     config: Pick<KernelConfigService, "get">;
 }
-/** 回调拿到的沙箱：句柄、提供方与「调用 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;
+    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. */
+export declare const SANDBOX_STARTED_NOTICE = "Environment started (first use in this conversation); the working directory is /workspace, shared with the environment's other conversations.";
+/** 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 and /tmp are gone.";
 /** 没有沙箱提供方时「工具不可用」的原因（进提醒，内核在后面补句号）：与调用时的错误同一句话。 */
 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;
+/** The directory of attachments in the environment (each conversation has a subdirectory). */
+export declare const ATTACHMENTS_ROOT = "/workspace/attachments";
+/**
+ * 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: (rootConversationId: string) => string;
+/** The conversation's marker of synced attachments: `{ <attachment id>: <file name> }`. */
+export declare const syncMarkerPath: (rootConversationId: string) => string;
+/** Whether a path, or a Grep output line starting with one, belongs to a sync marker (hidden from Glob / Grep). */
+export declare const isSyncMarkerEntry: (pathOrLine: string) => boolean;
 /** 附件文件名的上限（UTF-8 字节，常见文件系统单个文件名上限 255 字节，留出 `-N` 后缀的余量）。 */
 export declare const ATTACHMENT_NAME_MAX_BYTES = 200;
 /**
@@ -93,25 +126,34 @@ export declare function assignAttachmentNames(items: readonly {
     id: string;
     name: string;
 }[], used: ReadonlySet<string>): Map<string, string>;
+/** 沙箱服务的错误 → 给模型的可执行说明；其余原样抛出（管线按「工具失败」处理）。 */
+export declare function mapSandboxError(e: unknown): unknown;
 /**
- * 在本对话的沙箱上执行 `fn`（`SandboxService.withSandbox`：懒创建、恢复、重建）：先同步附件，
- * 再执行；返回结果与要加在结果开头的状态说明（首次使用 / 重建 / 新复制的附件）。
- * `withSandbox` 遇到实例不在时会重建并再调用一次回调，说明按最后一次调用的为准。
+ * 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.
  */
 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">, ctx: BuiltinCallContext, path: string, signal: AbortSignal, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
+export declare function withPathLease<T>(deps: Pick<SandboxToolDeps, "sandbox">, s: Pick<SandboxSession, "environmentId">, 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">) => (_ctx?: {
+    orgId: string;
+}) => string | null;
 /** 读出的字节是否像二进制（开头 8 KB 里有 NUL）。 */
 export declare function looksBinary(data: Uint8Array): boolean;