@capybara-hq/kernel 0.1.0-rc.4 → 0.1.0-rc.6

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

@@ -1,14 +1,15 @@
 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);
@@ -16,12 +17,26 @@ export const SANDBOX_UNAVAILABLE_REASON = NO_SANDBOX_TEXT.slice(0, -1);
 export function noSandboxError() {
     return new ToolError(NO_SANDBOX_TEXT);
 }
-const PATH_BUSY_TEXT = "Another sub-agent is writing this file; wait a moment and retry.";
+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;
@@ -133,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;
@@ -171,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;
@@ -208,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)
@@ -228,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) {
@@ -243,8 +259,20 @@ 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);
@@ -253,25 +281,31 @@ export function mapSandboxError(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(", ")}.`);
             }
@@ -283,18 +317,19 @@ export async function inSandbox(deps, ctx, fn) {
         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]));
     }

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,7 +2,7 @@ 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，都在本对话的沙箱上执行

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

@@ -9,7 +9,7 @@ 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，都在本对话的沙箱上执行

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

@@ -1,6 +1,6 @@
 import { type SandboxHandle } from "@capybara-hq/plugin-sdk";
 import type { BackgroundTaskRow } from "../../../background/store.js";
-import type { IfRunningResult, SandboxService, TaggedProvider } from "../../../sandbox/sandbox.service.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). */
@@ -14,6 +14,7 @@ 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;
@@ -22,8 +23,18 @@ export declare function taskEnv(deps: SandboxToolDeps): TaskEnv;
  * 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>;
-/** `ifRunning` on the task's own sandbox instance; sandbox errors become the tools' errors. */
-export declare function onTaskInstance<T>(env: TaskEnv, task: BackgroundTaskRow, fn: (p: TaggedProvider, h: SandboxHandle, signal: AbortSignal) => Promise<T>, signal: AbortSignal): Promise<IfRunningResult<T>>;
+/**
+ * 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`.

package/dist/tools/builtins/sandbox/task-output.js

@@ -2,10 +2,10 @@ import { setTimeout as sleep } from "node:timers/promises";
 import { isSandboxGoneError, ToolError, } from "@capybara-hq/plugin-sdk";
 import { TASK_ID_RE, TASKS_DIR } from "../../../background/launch.js";
 import { formatElapsed, lostReasonText } from "../../../background/render.js";
-import { SID_RE } from "../../../background/session.js";
+import { actingAs, SID_RE, taskActor } from "../../../background/session.js";
 import { parsePollOutput, polledAs, pollScript, } from "../../../background/status.js";
 import { notRunningAs, RECREATED } from "../../../background/stop.js";
-import { clip, display, mapSandboxError, noSandboxError, runTimeLeftMs, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, } from "./common.js";
+import { clip, display, mapSandboxError, noSandboxError, runTimeLeftMs, sandboxBaseTimeoutMs, sandboxConversationOf, unavailableWhenNoSandbox, } from "./common.js";
 /** How long `TaskOutput` waits with `block` when `timeout` is not given (ms). */
 export const TASK_OUTPUT_DEFAULT_TIMEOUT_MS = 30_000;
 /** The longest `TaskOutput` wait (ms). */
@@ -57,7 +57,12 @@ export function taskEnv(deps) {
     if (!background || !tasks || !deps.sandbox.ifRunning) {
         throw new ToolError("Background tasks are not available here; use Bash without run_in_background instead.");
     }
-    return { store: background, tasks, ifRunning: deps.sandbox.ifRunning.bind(deps.sandbox) };
+    return {
+        store: background,
+        tasks,
+        ifRunning: deps.sandbox.ifRunning.bind(deps.sandbox),
+        environments: deps.environments,
+    };
 }
 const notFound = (id) => new ToolError(`No background task ${clip(id, 40)} in this conversation. Pass a task id that Bash with run_in_background returned in this conversation.`);
 /**
@@ -72,10 +77,29 @@ export async function ownedTask(env, ctx, id) {
         throw notFound(id);
     return task;
 }
-/** `ifRunning` on the task's own sandbox instance; sandbox errors become the tools' errors. */
+/**
+ * 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 async function recheckEnvironment(env, ctx) {
+    try {
+        await env.environments.forTool(ctx.orgId, sandboxConversationOf(ctx));
+    }
+    catch (e) {
+        throw mapSandboxError(e);
+    }
+}
+/**
+ * `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 async function onTaskInstance(env, task, fn, signal) {
+    if (task.environmentId === null)
+        return { kind: "not_running", status: "gone" };
     try {
-        return await env.ifRunning(task.sandboxConversationId, { createdAt: task.sandboxCreatedAt }, fn, signal);
+        return await env.ifRunning(task.environmentId, { createdAt: task.sandboxCreatedAt }, (p, h, sig) => fn(actingAs(p, taskActor(task)), h, sig), signal);
     }
     catch (e) {
         throw mapSandboxError(e);
@@ -240,6 +264,7 @@ export function taskOutputTool(deps) {
             const { task_id, block = true, timeout } = input;
             const env = taskEnv(deps);
             let task = await ownedTask(env, ctx, task_id);
+            await recheckEnvironment(env, ctx);
             if (block && task.status === "running") {
                 const wait = Math.max(0, Math.min(timeout ?? TASK_OUTPUT_DEFAULT_TIMEOUT_MS, TASK_OUTPUT_MAX_TIMEOUT_MS, runTimeLeftMs(ctx.runDeadline)));
                 const until = Date.now() + wait;

package/dist/tools/builtins/sandbox/task-stop.js

@@ -1,7 +1,7 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
 import { decodeTail, tailCommand } from "../../../background/session.js";
 import { clip, display, mapSandboxError, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, } from "./common.js";
-import { onTaskInstance, ownedTask, statusLine, taskEnv } from "./task-output.js";
+import { onTaskInstance, ownedTask, recheckEnvironment, statusLine, taskEnv, } from "./task-output.js";
 /** The time limit of reading a stopped task's last lines. */
 const TAIL_EXEC_TIMEOUT_MS = 10_000;
 const SPEC = {
@@ -84,6 +84,7 @@ export function taskStopTool(deps) {
             const { task_id } = input;
             const env = taskEnv(deps);
             const task = await ownedTask(env, ctx, task_id);
+            await recheckEnvironment(env, ctx);
             if (task.status !== "running") {
                 return ended(env, task, "had already finished", ctx.signal);
             }

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

@@ -45,9 +45,9 @@ export function sandboxWriteTool(deps) {
         async run(input, ctx) {
             const path = checkWritable(input.file_path);
             const data = new TextEncoder().encode(input.content);
-            const { value, notices } = await inSandbox(deps, ctx, ({ h, p, signal }) => 
+            const { value, notices } = await inSandbox(deps, ctx, ({ environmentId, h, p, signal }) => 
             // stat, read the previous content, 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?.isDir)
                     throw new ToolError(isDirectory(path));

package/dist/tools/builtins/send-message.d.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import type { BuiltinTool } from "../registry.js";
+export { SEND_MESSAGE } from "../builtin-names.js";
+/**
+ * The `SendMessage` builtin tool (agent map spec §4.2, §5.1, §5.2): moves text between the agents
+ * of one tree. An agent sends to one of its own sub-agents by agentId (a running one reads it at its
+ * next step, an idle one starts again with its earlier context), and a sub-agent to `"parent"`.
+ * The result says the message was delivered, never the target's reply. The tool pipeline handles
+ * the call itself (`SubagentMessages`), so {@link sendMessageTool}'s `run` is only a guard.
+ */
+/** The input of a `SendMessage` call. */
+export declare const SendMessageInput: z.ZodObject<{
+    to: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strict>;
+export type SendMessageInputT = z.infer<typeof SendMessageInput>;
+/** The target a sub-agent uses for the agent that dispatched it. */
+export declare const PARENT_TARGET = "parent";
+/** One valid target of a caller: a sub-agent of its own, by agentId and task label. */
+export interface SendTarget {
+    id: string;
+    description: string;
+}
+/** Refusals: `isError` results written without delivering anything (model-visible). */
+export declare const SEND_MESSAGE_REFUSALS: {
+    /**
+     * `to` is none of the caller's own sub-agents (nor `"parent"` in a sub-agent): lists the valid
+     * targets, at most the newest {@link SEND_TARGETS_LISTED} sub-agents.
+     */
+    readonly unknownTarget: (to: string, targets: readonly SendTarget[], opts: {
+        hasParent: boolean;
+        more: number;
+    }) => string;
+    /** The sub-agent's type or org agent is no longer available to the caller (its gates). */
+    readonly notAvailable: (id: string, type: string) => string;
+    /** The limits of a send that would start an idle sub-agent again (agent map spec §6). */
+    readonly tooManyConcurrent: (n: number) => string;
+    readonly tooManyDispatches: (n: number) => string;
+    readonly budget: (n: number) => string;
+    readonly depthLimit: (maxDepth: number) => string;
+    readonly notAvailableHere: "Messages between agents are not available in this conversation.";
+};
+/** How many of the caller's sub-agents an unknown-target refusal lists (the newest). */
+export declare const SEND_TARGETS_LISTED = 20;
+/** The result of a message to a sub-agent whose run was active (agent map spec §5.1). */
+export declare const sentToRunningText: (t: SendTarget) => string;
+/** The result of a message that started an idle sub-agent again (agent map spec §5.1, §6). */
+export declare const sentToIdleText: (t: SendTarget) => string;
+/** The result of a sub-agent's note to its parent (agent map spec §5.2). */
+export declare const SENT_TO_PARENT_TEXT = "Message delivered to the agent that dispatched you. Keep working; its reply, if any, arrives as a message in this conversation.";
+/**
+ * The builtin. `defaultPolicy: "allow"` (agent map spec §4.2): it only moves text inside one tree
+ * the person already started. The tool pipeline handles `SendMessage` calls itself; `run` answers
+ * only when a call reaches it anyway.
+ */
+export declare const sendMessageTool: BuiltinTool;

package/dist/tools/builtins/send-message.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+export { SEND_MESSAGE } from "../builtin-names.js";
+/**
+ * The `SendMessage` builtin tool (agent map spec §4.2, §5.1, §5.2): moves text between the agents
+ * of one tree. An agent sends to one of its own sub-agents by agentId (a running one reads it at its
+ * next step, an idle one starts again with its earlier context), and a sub-agent to `"parent"`.
+ * The result says the message was delivered, never the target's reply. The tool pipeline handles
+ * the call itself (`SubagentMessages`), so {@link sendMessageTool}'s `run` is only a guard.
+ */
+/** The input of a `SendMessage` call. */
+export const SendMessageInput = z
+    .object({
+    to: z.string().min(1).max(64),
+    message: z.string().min(1).max(100_000),
+})
+    .strict();
+/** The target a sub-agent uses for the agent that dispatched it. */
+export const PARENT_TARGET = "parent";
+const SPEC = {
+    name: "SendMessage",
+    description: "Send a message to another agent of this conversation. To reach one of your sub-agents, pass " +
+        "its agentId (from the Agent result) as to: a sub-agent that is working reads the message at " +
+        "its next step, and one that already finished starts working again with its earlier context. " +
+        'A sub-agent can pass "parent" as to, to send a note to the agent that dispatched it. This ' +
+        "tool only delivers the message and returns at once; it never waits for a reply. Replies, " +
+        "reports and finishes arrive later in this conversation as notifications. A sub-agent hands " +
+        "back its final report with SubagentHandback, not with this tool.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            to: {
+                type: "string",
+                minLength: 1,
+                maxLength: 64,
+                description: 'The agentId of one of your sub-agents, or "parent" in a sub-agent.',
+            },
+            message: {
+                type: "string",
+                minLength: 1,
+                maxLength: 100000,
+                description: "The message. The receiving agent sees only this text, so include everything it needs.",
+            },
+        },
+        required: ["to", "message"],
+        additionalProperties: false,
+    },
+    // display only (UI refresh B): who the message goes to; never sent to the model
+    keyArgs: ["to"],
+};
+/** `12345` → `12,345` (no locale data involved, so the text is the same on every replica). */
+const count = (n) => String(Math.round(n)).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+/** How a target is listed in a refusal. */
+const targetLine = (t) => `${t.id} (${JSON.stringify(t.description)})`;
+/** Refusals: `isError` results written without delivering anything (model-visible). */
+export const SEND_MESSAGE_REFUSALS = {
+    /**
+     * `to` is none of the caller's own sub-agents (nor `"parent"` in a sub-agent): lists the valid
+     * targets, at most the newest {@link SEND_TARGETS_LISTED} sub-agents.
+     */
+    unknownTarget: (to, targets, opts) => {
+        const lines = [
+            ...targets.map(targetLine),
+            ...(opts.hasParent ? [`"${PARENT_TARGET}" (the agent that dispatched you)`] : []),
+        ];
+        if (lines.length === 0) {
+            return `There is no agent "${to}" to send to: you have no sub-agents yet. Use Agent to dispatch one.`;
+        }
+        const more = opts.more > 0 ? `, and ${opts.more} older sub-agents` : "";
+        return `There is no agent "${to}" you can send to. Pass one of these as to: ${lines.join(", ")}${more}.`;
+    },
+    /** The sub-agent's type or org agent is no longer available to the caller (its gates). */
+    notAvailable: (id, type) => `Sub-agent ${id} can no longer receive messages: its agent type "${type}" is not available to you any more. Use Agent to dispatch another sub-agent instead.`,
+    /** The limits of a send that would start an idle sub-agent again (agent map spec §6). */
+    tooManyConcurrent: (n) => `At most ${n} of your sub-agents can run at once in this conversation, and this one has finished; send the message again after one of the running sub-agents finishes.`,
+    tooManyDispatches: (n) => `${n} sub-agents have been dispatched or restarted since the user's latest message, counted across all levels of sub-agents; that is the limit, so this finished sub-agent cannot start again. Do the remaining work yourself.`,
+    budget: (n) => `Sub-agents have used their token budget since the user's latest message (${count(n)} tokens, counted across all levels of sub-agents), so this finished sub-agent cannot start again. Do the remaining work yourself.`,
+    depthLimit: (maxDepth) => `Sub-agents can be nested at most ${maxDepth} levels deep and you are at the deepest level, so this finished sub-agent cannot start again. Do the remaining work yourself.`,
+    notAvailableHere: "Messages between agents are not available in this conversation.",
+};
+/** How many of the caller's sub-agents an unknown-target refusal lists (the newest). */
+export const SEND_TARGETS_LISTED = 20;
+/** The result of a message to a sub-agent whose run was active (agent map spec §5.1). */
+export const sentToRunningText = (t) => `Message delivered to sub-agent ${targetLine(t)}, which is working; it reads the message at its next step. Its reply or report arrives later as a notification; keep working or end your turn.`;
+/** The result of a message that started an idle sub-agent again (agent map spec §5.1, §6). */
+export const sentToIdleText = (t) => `Message delivered to sub-agent ${targetLine(t)}, which had finished; it is working again with its earlier context. Its reply or report arrives later as a notification; keep working or end your turn.`;
+/** The result of a sub-agent's note to its parent (agent map spec §5.2). */
+export const SENT_TO_PARENT_TEXT = "Message delivered to the agent that dispatched you. Keep working; its reply, if any, arrives as a message in this conversation.";
+/**
+ * The builtin. `defaultPolicy: "allow"` (agent map spec §4.2): it only moves text inside one tree
+ * the person already started. The tool pipeline handles `SendMessage` calls itself; `run` answers
+ * only when a call reaches it anyway.
+ */
+export const sendMessageTool = {
+    spec: SPEC,
+    defaultPolicy: "allow",
+    run: async () => ({
+        content: [{ type: "text", text: SEND_MESSAGE_REFUSALS.notAvailableHere }],
+        isError: true,
+    }),
+};