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

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

@@ -1,23 +1,42 @@
 import { isSandboxGoneError, ToolError, validateSandboxPath, } from "@capybara-hq/plugin-sdk";
+import { ANONYMOUS_NO_ENVIRONMENT, } from "../../../environments/conversation-environments.js";
 import { ApiError } from "../../../errors.js";
 import { SandboxPathBusyError } from "../../../sandbox/leases.js";
-import { SandboxLockLostError } from "../../../sandbox/sandbox.service.js";
+import { SandboxLockLostError, } from "../../../sandbox/sandbox.service.js";
 // ---- 模型可见文案（英文） ----
 /** 没有沙箱提供方时「工具不可用」的原因（进提醒与调用结果）。 */
-/** 本对话第一次用沙箱。 */
-export const SANDBOX_STARTED_NOTICE = "Sandbox started for this conversation (first use); the working directory is /workspace.";
-/** 沙箱被重建（之前的实例已销毁或不在了）。 */
-export const SANDBOX_RECREATED_NOTICE = "Sandbox was recreated; previous files are gone.";
-const BUSY_TEXT = "The sandbox is busy with another command in this conversation; wait for it to finish and retry.";
+/** This conversation's first use of its environment. */
+export 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 const SANDBOX_RESTARTED_NOTICE = "The environment's instance was restarted; files are kept, running processes and /tmp are gone.";
+const BUSY_TEXT = "The environment is busy: all its command slots are taken by commands of this or another conversation sharing it; wait for one to finish and retry.";
 const NO_SANDBOX_TEXT = "No sandbox is configured in this deployment; ask an administrator to install a sandbox plugin, or do the task without the sandbox.";
 /** 没有沙箱提供方时「工具不可用」的原因（进提醒，内核在后面补句号）：与调用时的错误同一句话。 */
 export const SANDBOX_UNAVAILABLE_REASON = NO_SANDBOX_TEXT.slice(0, -1);
-const PATH_BUSY_TEXT = "Another sub-agent is writing this file; wait a moment and retry.";
+/** The error of a sandbox call in a deployment without a sandbox provider. */
+export function noSandboxError() {
+    return new ToolError(NO_SANDBOX_TEXT);
+}
+const PATH_BUSY_TEXT = "Another sub-agent or another conversation in this environment is writing this file; wait a moment and retry.";
+const ANONYMOUS_TEXT = "The sandbox is not available to anonymous IM senders; do the task without the sandbox, or ask the person to link their account and start a new conversation.";
+const ENV_NOT_FOUND_TEXT = "This conversation's environment was deleted or its owner can no longer use it; ask the user to start a new conversation in another environment.";
+const ENV_FORBIDDEN_TEXT = "This conversation's owner may no longer use its environment; ask the user to start a new conversation in an environment they can use.";
+const ENV_UNAVAILABLE_TEXT = "This conversation's environment is kept by a sandbox provider that is not active in this deployment; ask the user to start a new conversation in another environment, or an administrator to re-enable that provider.";
+const ENV_FILES_LOST_TEXT = "This environment's files are gone. Ask the user to reset its files on the environments page, then retry.";
 const LOCK_LOST_TEXT = "The sandbox operation was interrupted because the sandbox lock was lost; check the sandbox state and retry.";
-/** 沙箱里附件所在目录。 */
-export const ATTACHMENTS_DIR = "/workspace/attachments";
-/** 已同步附件的标记文件：`{ <附件 id>: <文件名> }`。 */
-export const SYNC_MARKER = `${ATTACHMENTS_DIR}/.capybara-sync.json`;
+/** The directory of attachments in the environment (each conversation has a subdirectory). */
+export 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 const attachmentsDir = (rootConversationId) => `${ATTACHMENTS_ROOT}/${rootConversationId.replaceAll("-", "").slice(0, 12)}`;
+/** The conversation's marker of synced attachments: `{ <attachment id>: <file name> }`. */
+export const syncMarkerPath = (rootConversationId) => `${attachmentsDir(rootConversationId)}/.capybara-sync.json`;
+const SYNC_MARKER_NAME = ".capybara-sync.json";
+const SYNC_MARKER_RE = new RegExp(`^${ATTACHMENTS_ROOT}/[^/]+/${SYNC_MARKER_NAME.replaceAll(".", "\\.")}(?=$|[:-])`);
+/** Whether a path, or a Grep output line starting with one, belongs to a sync marker (hidden from Glob / Grep). */
+export const isSyncMarkerEntry = (pathOrLine) => SYNC_MARKER_RE.test(pathOrLine);
 const MARKER_MAX_BYTES = 1024 * 1024;
 /** 附件文件名的上限（UTF-8 字节，常见文件系统单个文件名上限 255 字节，留出 `-N` 后缀的余量）。 */
 export const ATTACHMENT_NAME_MAX_BYTES = 200;
@@ -129,11 +148,11 @@ function sanitizeName(raw) {
  */
 export function assignAttachmentNames(items, used) {
     const taken = new Set(used);
-    taken.add(SYNC_MARKER.slice(ATTACHMENTS_DIR.length + 1));
+    taken.add(SYNC_MARKER_NAME);
     const out = new Map();
     for (const a of items) {
         let base = sanitizeName(a.name);
-        if (validateSandboxPath(`${ATTACHMENTS_DIR}/${base}`).length > 0) {
+        if (validateSandboxPath(`${ATTACHMENTS_ROOT}/${base}`).length > 0) {
             base = `attachment-${a.id.slice(0, 8)}`;
         }
         let name = base;
@@ -167,35 +186,36 @@ function copyFailureReason(e) {
     return "a temporary error occurred; it will be retried on the next sandbox call";
 }
 /**
- * 把本对话已 ready 的附件复制到 `/workspace/attachments/<name>`，标记文件记下已复制的（不重复复制）。
- * `reset`（新建 / 重建的沙箱，文件已不在）时忽略标记文件全部重新复制。对象已不在的附件跳过（下次再试）。
+ * 把本对话已 ready 的附件复制到 `/workspace/attachments/<conversation>/<name>`（{@link attachmentsDir}），
+ * 标记文件记下已复制的（不重复复制）。对象已不在的附件跳过（下次再试）。
  * 每复制一个就更新标记文件：中途超时 / 中止，下次从停下的地方继续。
  * 单个附件失败（存储故障等）只跳过它并给出说明，不让工具调用失败；signal 已中止或实例已不在时照常抛出。
  * 返回本次复制的沙箱路径与失败说明。
  */
-async function syncAttachments(deps, ctx, s, reset) {
+async function syncAttachments(deps, ctx, s) {
     const none = { copied: [], failures: [] };
     const conv = sandboxConversationOf(ctx);
     const list = await deps.attachments.listForConversation(ctx.orgId, conv);
     if (list.length === 0)
         return none;
     // nothing to copy (the usual case): no path lease, so calls do not queue on the marker
-    if (!reset) {
-        const marker = await readSyncMarker(s);
-        if (list.every((a) => Object.hasOwn(marker, a.id)))
-            return none;
-    }
+    const marker = await readSyncMarker(s, conv);
+    if (list.every((a) => Object.hasOwn(marker, a.id)))
+        return none;
     // the sync marker is read, changed and written: one holder at a time
-    return withPathLease(deps, ctx, SYNC_MARKER, s.signal, (signal) => copyAttachments(deps, ctx, { ...s, signal }, reset, conv, list));
+    return withPathLease(deps, s, syncMarkerPath(conv), s.signal, (signal) => copyAttachments(deps, ctx, { ...s, signal }, conv, list));
 }
 /** The sync marker's entries (`{}` when it is missing, too large or unreadable). */
-async function readSyncMarker(s) {
-    const m = await s.p.readFile(s.h, SYNC_MARKER, { maxBytes: MARKER_MAX_BYTES, signal: s.signal });
+async function readSyncMarker(s, conv) {
+    const m = await s.p.readFile(s.h, syncMarkerPath(conv), {
+        maxBytes: MARKER_MAX_BYTES,
+        signal: s.signal,
+    });
     return m && !m.truncated ? parseMarker(m.data) : {};
 }
-async function copyAttachments(deps, ctx, s, reset, conv, list) {
+async function copyAttachments(deps, ctx, s, conv, list) {
     const none = { copied: [], failures: [] };
-    let marker = reset ? {} : await readSyncMarker(s);
+    let marker = await readSyncMarker(s, conv);
     const pending = list.filter((a) => !Object.hasOwn(marker, a.id));
     if (pending.length === 0)
         return none;
@@ -204,7 +224,7 @@ async function copyAttachments(deps, ctx, s, reset, conv, list) {
     const failures = [];
     for (const a of pending) {
         const name = names.get(a.id);
-        const path = `${ATTACHMENTS_DIR}/${name}`;
+        const path = `${attachmentsDir(conv)}/${name}`;
         try {
             const opened = await deps.attachments.openForConversation(ctx.orgId, conv, a.id);
             if (!opened)
@@ -224,7 +244,7 @@ async function copyAttachments(deps, ctx, s, reset, conv, list) {
         copied.push(path);
         const next = { ...marker, [a.id]: name };
         try {
-            await s.p.writeFile(s.h, SYNC_MARKER, utf8.encode(JSON.stringify(next)), s.signal);
+            await s.p.writeFile(s.h, syncMarkerPath(conv), utf8.encode(JSON.stringify(next)), s.signal);
             marker = next;
         }
         catch (e) {
@@ -235,12 +255,24 @@ async function copyAttachments(deps, ctx, s, reset, conv, list) {
     return { copied, failures };
 }
 /** 沙箱服务的错误 → 给模型的可执行说明；其余原样抛出（管线按「工具失败」处理）。 */
-function mapError(e) {
+export function mapSandboxError(e) {
     if (e instanceof ApiError) {
         if (e.code === "sandbox.busy")
             return new ToolError(BUSY_TEXT);
-        if (e.code === "sandbox.unavailable")
+        if (e.code === "sandbox.unavailable") {
+            const reason = e.details?.[0]?.reason;
+            if (reason === ANONYMOUS_NO_ENVIRONMENT)
+                return new ToolError(ANONYMOUS_TEXT);
             return new ToolError(NO_SANDBOX_TEXT);
+        }
+        if (e.code === "environment.not_found")
+            return new ToolError(ENV_NOT_FOUND_TEXT);
+        if (e.code === "environment.forbidden")
+            return new ToolError(ENV_FORBIDDEN_TEXT);
+        if (e.code === "environment.unavailable")
+            return new ToolError(ENV_UNAVAILABLE_TEXT);
+        if (e.code === "environment.files_lost")
+            return new ToolError(ENV_FILES_LOST_TEXT);
     }
     if (e instanceof SandboxLockLostError)
         return new ToolError(LOCK_LOST_TEXT);
@@ -249,25 +281,31 @@ function mapError(e) {
     return e;
 }
 /**
- * 在本对话的沙箱上执行 `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 async function inSandbox(deps, ctx, fn) {
     try {
+        const environmentId = await deps.environments.forTool(ctx.orgId, sandboxConversationOf(ctx));
         return await deps.sandbox.withSandbox({
             orgId: ctx.orgId,
-            conversationId: sandboxConversationOf(ctx),
-            // a sub-agent is told when another holder rebuilt the shared sandbox (final review m5)
+            environmentId,
+            // a sub-agent is told when another holder rebuilt the shared instance (final review m5)
             holderConversationId: ctx.conversationId,
+            actor: { accountId: ctx.accountId, conversationId: ctx.conversationId },
         }, async (h, p, info, signal) => {
-            const s = { h, p, signal, reset: info.fresh || info.recreated };
+            const s = { environmentId, h, p, signal };
             const notices = [];
-            if (info.recreated)
-                notices.push(SANDBOX_RECREATED_NOTICE);
+            if (info.restarted)
+                notices.push(SANDBOX_RESTARTED_NOTICE);
             else if (info.fresh)
                 notices.push(SANDBOX_STARTED_NOTICE);
-            const { copied, failures } = await syncAttachments(deps, ctx, s, s.reset);
+            const { copied, failures } = await syncAttachments(deps, ctx, s);
             if (copied.length > 0) {
                 notices.push(`Attachments copied into the sandbox: ${copied.join(", ")}.`);
             }
@@ -276,21 +314,22 @@ export async function inSandbox(deps, ctx, fn) {
         }, ctx.signal);
     }
     catch (e) {
-        throw mapError(e);
+        throw mapSandboxError(e);
     }
 }
-/** 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 const sandboxConversationOf = (ctx) => ctx.sandboxConversationId ?? ctx.conversationId;
 /**
- * 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 async function withPathLease(deps, ctx, path, signal, fn) {
+export async function withPathLease(deps, s, path, signal, fn) {
     if (!deps.sandbox.pathLease)
         return fn(signal);
-    const lease = await deps.sandbox.pathLease(sandboxConversationOf(ctx), path, signal);
+    const lease = await deps.sandbox.pathLease(s.environmentId, path, signal);
     try {
         return await fn(AbortSignal.any([signal, lease.signal]));
     }
@@ -299,7 +338,7 @@ export async function withPathLease(deps, ctx, path, signal, fn) {
     }
 }
 /** 本部署是否有沙箱：没有时返回「不可用」原因（注册表据此把沙箱工具报为不可用）。 */
-export const unavailableWhenNoSandbox = (deps) => () => deps.sandbox.available ? null : SANDBOX_UNAVAILABLE_REASON;
+export const unavailableWhenNoSandbox = (deps) => (_ctx) => deps.sandbox.available ? null : SANDBOX_UNAVAILABLE_REASON;
 /** 读出的字节是否像二进制（开头 8 KB 里有 NUL）。 */
 export function looksBinary(data) {
     return data.subarray(0, 8192).includes(0);

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

@@ -96,7 +96,7 @@ export function sandboxDeliverTool(deps) {
         spec: SPEC,
         defaultPolicy: "allow",
         // 没有沙箱或没有对象存储都交付不了（先报沙箱的原因）
-        unavailable: () => unavailableWhenNoSandbox(deps)() ?? (deps.storage.available ? null : NO_STORAGE_REASON),
+        unavailable: (ctx) => unavailableWhenNoSandbox(deps)(ctx) ?? (deps.storage.available ? null : NO_STORAGE_REASON),
         timeoutMs: () => 2 * sandboxBaseTimeoutMs(deps.config.get()),
         async run(input, ctx) {
             // 存储在调用前就核对：不为一个交付不了的文件去 stat / 读沙箱

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

@@ -56,9 +56,9 @@ export function sandboxEditTool(deps) {
             const path = checkWritable(input.file_path);
             if (old_string === new_string)
                 throw new ToolError(SAME_TEXT);
-            const { value: edit, notices } = await inSandbox(deps, ctx, ({ h, p, signal }) => 
+            const { value: edit, notices } = await inSandbox(deps, ctx, ({ environmentId, h, p, signal }) => 
             // read, replace, write: one holder at a time per file
-            withPathLease(deps, ctx, path, signal, async (signal) => {
+            withPathLease(deps, { environmentId }, path, signal, async (signal) => {
                 const st = await p.stat(h, path, signal);
                 if (st === null)
                     throw new ToolError(notFound(path));

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

@@ -1,5 +1,5 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
-import { checkPath, clip, display, inSandbox, SYNC_MARKER, sandboxBaseTimeoutMs, searchTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+import { checkPath, clip, display, inSandbox, isSyncMarkerEntry, sandboxBaseTimeoutMs, searchTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
 import { compileGlob, GlobPatternError } from "./glob-match.js";
 /** 最多列出的文件数。 */
 const MAX_RESULTS = 1000;
@@ -82,7 +82,7 @@ export function sandboxGlobTool(deps) {
                     .map((l) => l.slice(2))
                     .filter((rel) => matches(rel))
                     .map((rel) => `${base}/${rel}`)
-                    .filter((abs) => abs !== SYNC_MARKER)
+                    .filter((abs) => !isSyncMarkerEntry(abs))
                     .sort()
                     // 文件名里的换行显示为 `\n`（与 Grep 一致），一行一个文件
                     .map((abs) => abs.replace(/\n/g, "\\n")));

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

@@ -1,5 +1,5 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
-import { checkPath, clip, display, inSandbox, SYNC_MARKER, sandboxBaseTimeoutMs, searchTimeoutMs, shellQuote, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+import { checkPath, clip, display, inSandbox, isSyncMarkerEntry, sandboxBaseTimeoutMs, searchTimeoutMs, shellQuote, unavailableWhenNoSandbox, withNotices, } from "./common.js";
 /** The most output entries (lines, files or counts) returned in one call, whatever `head_limit` says. */
 const MAX_MATCHES = 500;
 /** `head_limit` when the model gives none. */
@@ -207,9 +207,7 @@ export function sandboxGrepTool(deps) {
                     : mode === "count"
                         ? parseCounts(r.stdout, base)
                         : parseGrepNull(r.stdout, base, numbered);
-                const entries = all.filter((l) => l !== SYNC_MARKER &&
-                    !l.startsWith(`${SYNC_MARKER}:`) &&
-                    !l.startsWith(`${SYNC_MARKER}-`));
+                const entries = all.filter((l) => !isSyncMarkerEntry(l));
                 // 退出码 2 = 有错误（如个别文件不可读）；有输出时照常返回（可能为空：只匹配到隐藏的标记文件）并附上说明
                 if (r.exitCode !== 0 && all.length === 0)
                     throw new ToolError(failed(r.stderr));

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

@@ -2,11 +2,13 @@ import type { BuiltinTool } from "../../registry.js";
 import type { SandboxToolDeps } from "./common.js";
 export { SANDBOX_ASK_TOOL_NAMES, SANDBOX_TOOL_NAMES } from "../../builtin-names.js";
 export { BASH_SPILL_CHARS, formatExec } from "./bash.js";
-export { assignAttachmentNames, RUN_DEADLINE_MARGIN_MS, runTimeLeftMs, SANDBOX_RECREATED_NOTICE, SANDBOX_SETUP_MARGIN_MS, SANDBOX_STARTED_NOTICE, SANDBOX_UNAVAILABLE_REASON, type SandboxToolDeps, sandboxBaseTimeoutMs, searchTimeoutMs, shellQuote, } from "./common.js";
+export { assignAttachmentNames, RUN_DEADLINE_MARGIN_MS, runTimeLeftMs, SANDBOX_RESTARTED_NOTICE, SANDBOX_SETUP_MARGIN_MS, SANDBOX_STARTED_NOTICE, SANDBOX_UNAVAILABLE_REASON, type SandboxToolDeps, sandboxBaseTimeoutMs, searchTimeoutMs, shellQuote, } from "./common.js";
 export { compileGlob, GlobPatternError, MAX_GLOB_STARS } from "./glob-match.js";
 /**
  * 沙箱内置工具（M5 T8）：bash / read / write / edit / glob / grep / deliver，都在本对话的沙箱上执行
  * （`SandboxService.withSandbox`），执行前同步附件到 `/workspace/attachments`。没有沙箱提供方时报不可用。
  * 默认 allow；组织设置 `sandboxToolPolicy` 为 ask 时除 read / glob / grep 外需要审批（见 policy.ts）。
+ * `TaskOutput` and `TaskStop` read and stop background `Bash` tasks through
+ * `SandboxService.ifRunning` (never creating or resuming a sandbox); always allowed.
  */
 export declare function sandboxTools(deps: SandboxToolDeps): BuiltinTool[];

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

@@ -4,15 +4,19 @@ import { sandboxEditTool } from "./edit.js";
 import { sandboxGlobTool } from "./glob.js";
 import { sandboxGrepTool } from "./grep.js";
 import { sandboxReadTool } from "./read.js";
+import { taskOutputTool } from "./task-output.js";
+import { taskStopTool } from "./task-stop.js";
 import { sandboxWriteTool } from "./write.js";
 export { SANDBOX_ASK_TOOL_NAMES, SANDBOX_TOOL_NAMES } from "../../builtin-names.js";
 export { BASH_SPILL_CHARS, formatExec } from "./bash.js";
-export { assignAttachmentNames, RUN_DEADLINE_MARGIN_MS, runTimeLeftMs, SANDBOX_RECREATED_NOTICE, SANDBOX_SETUP_MARGIN_MS, SANDBOX_STARTED_NOTICE, SANDBOX_UNAVAILABLE_REASON, sandboxBaseTimeoutMs, searchTimeoutMs, shellQuote, } from "./common.js";
+export { assignAttachmentNames, RUN_DEADLINE_MARGIN_MS, runTimeLeftMs, SANDBOX_RESTARTED_NOTICE, SANDBOX_SETUP_MARGIN_MS, SANDBOX_STARTED_NOTICE, SANDBOX_UNAVAILABLE_REASON, sandboxBaseTimeoutMs, searchTimeoutMs, shellQuote, } from "./common.js";
 export { compileGlob, GlobPatternError, MAX_GLOB_STARS } from "./glob-match.js";
 /**
  * 沙箱内置工具（M5 T8）：bash / read / write / edit / glob / grep / deliver，都在本对话的沙箱上执行
  * （`SandboxService.withSandbox`），执行前同步附件到 `/workspace/attachments`。没有沙箱提供方时报不可用。
  * 默认 allow；组织设置 `sandboxToolPolicy` 为 ask 时除 read / glob / grep 外需要审批（见 policy.ts）。
+ * `TaskOutput` and `TaskStop` read and stop background `Bash` tasks through
+ * `SandboxService.ifRunning` (never creating or resuming a sandbox); always allowed.
  */
 export function sandboxTools(deps) {
     return [
@@ -23,5 +27,7 @@ export function sandboxTools(deps) {
         sandboxGlobTool(deps),
         sandboxGrepTool(deps),
         sandboxDeliverTool(deps),
+        taskOutputTool(deps),
+        taskStopTool(deps),
     ];
 }

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

@@ -13,7 +13,7 @@ const SPEC = {
     // Display only (the tool row; not in the fingerprint, never sent to the model).
     keyArgs: ["file_path"],
     description: "Read a text file from this conversation's sandbox, with line numbers. Use it to look at " +
-        "source code, data files, logs and files the user attached (under /workspace/attachments). " +
+        "source code, data files, logs and files the user attached (under /workspace/attachments/<conversation>/). " +
         "Paths are absolute, under /workspace, /skills or /tmp. Lines are numbered from 1; pass " +
         "offset and limit to read part of a long file. Binary files are not shown; use Bash " +
         "to inspect them. Do not use it to list directories; use Glob instead. Read a file before you " +

package/dist/tools/builtins/sandbox/task-output.d.ts

@@ -0,0 +1,74 @@
+import { type SandboxHandle } from "@capybara-hq/plugin-sdk";
+import type { BackgroundTaskRow } from "../../../background/store.js";
+import type { HeldProvider, IfRunningResult, SandboxService } from "../../../sandbox/sandbox.service.js";
+import type { BuiltinCallContext, BuiltinTool } from "../../registry.js";
+import { type SandboxToolDeps } from "./common.js";
+/** How long `TaskOutput` waits with `block` when `timeout` is not given (ms). */
+export declare const TASK_OUTPUT_DEFAULT_TIMEOUT_MS = 30000;
+/** The longest `TaskOutput` wait (ms). */
+export declare const TASK_OUTPUT_MAX_TIMEOUT_MS = 600000;
+/** How often a blocking `TaskOutput` checks the task (each check a short exec of its own). */
+export declare const TASK_CHECK_INTERVAL_MS = 2000;
+/** What `TaskOutput` and `TaskStop` work with. */
+export interface TaskEnv {
+    store: NonNullable<SandboxToolDeps["background"]>;
+    tasks: NonNullable<SandboxToolDeps["tasks"]>;
+    ifRunning: SandboxService["ifRunning"];
+    environments: SandboxToolDeps["environments"];
+}
+/** The task tools' dependencies; throws the tool's error when they are missing. */
+export declare function taskEnv(deps: SandboxToolDeps): TaskEnv;
+/**
+ * The task `id` when it belongs to the calling conversation; a task of another conversation (a
+ * sub-agent's, when called from its parent) is not found, the same as an unknown id.
+ */
+export declare function ownedTask(env: TaskEnv, ctx: BuiltinCallContext, id: string): Promise<BackgroundTaskRow>;
+/**
+ * The per-call access re-check of every sandbox tool (`inSandbox`): the conversation's environment
+ * may still be used by its owner. The task tools read a task's own instance without `inSandbox`,
+ * so they check here first; errors become the tools' errors.
+ */
+export declare function recheckEnvironment(env: TaskEnv, ctx: BuiltinCallContext): Promise<void>;
+/**
+ * `ifRunning` on the task's own environment instance (its execs act for the task's trigger in its
+ * conversation); sandbox errors become the tools' errors. A task from before environments has no
+ * instance (`not_running`).
+ */
+export declare function onTaskInstance<T>(env: TaskEnv, task: BackgroundTaskRow, fn: (p: HeldProvider, h: SandboxHandle, signal: AbortSignal) => Promise<T>, signal: AbortSignal): Promise<IfRunningResult<T>>;
+/**
+ * The task's status line: `Status: running (2m05s)`, `Status: failed, exit code 3, after 4m12s`,
+ * `Status: stopped after 1m00s`, `Status: lost (the sandbox was suspended) after 3s`.
+ */
+export declare function statusLine(task: BackgroundTaskRow, now?: Date): string;
+/** The absolute path of the task's output file, as the model sees it. */
+export declare const outputFile: (task: BackgroundTaskRow) => string;
+/** Why the output cannot be read: the task's sandbox instance is not running. */
+export declare function unavailableText(task: BackgroundTaskRow, r: IfRunningResult<unknown>): string;
+/**
+ * The exec that checks and reads task `t` (relative to `/workspace`): for a running task first
+ * its status line (the poller's, {@link pollScript}: liveness, then the exit file), then
+ * `size <bytes>` and `out <base64>`, at most `cap` bytes of the output from byte `offset` on.
+ * The file is never read whole: `tail -c +<offset+1> | head -c <cap>`. Without `read` only the
+ * status line.
+ */
+export declare function taskReadScript(t: {
+    id: string;
+    sid: string | null;
+    running: boolean;
+}, offset: number, cap: number, read?: boolean): string;
+/**
+ * The bytes of `buf` up to its last whole UTF-8 character: a character cut by the read's cap is
+ * left for the next read.
+ */
+export declare function wholeUtf8Length(buf: Uint8Array): number;
+/**
+ * Built-in `TaskOutput` (spec 2026-11-05-background-bash-design §2.2): a task's status and the
+ * output since this conversation's last read of it. Every check is a short exec through
+ * `SandboxService.ifRunning` on the task's own sandbox instance: it never creates or resumes a
+ * sandbox, so a suspended or rebuilt one means the task is lost (its output unavailable). With
+ * `block`, checks every {@link TASK_CHECK_INTERVAL_MS}, each under a lease of its own, until the
+ * task ends or the wait (at most `timeout` and the run's time left) is over; the checks only
+ * detect the end, and the one read that makes the result finishes the task (reported). The output
+ * read is capped at `tools.outputSpillChars` bytes; the pipeline spills the result beyond that.
+ */
+export declare function taskOutputTool(deps: SandboxToolDeps): BuiltinTool;