@capybara-hq/kernel 0.1.0-rc.22 → 0.1.0-rc.24

package/dist/tools/approvals.service.js

@@ -24,6 +24,7 @@ import { LockService } from "../infra/lock/lock.service.js";
 import { WithLock } from "../infra/lock/with-lock.decorator.js";
 import { DevicePolicyService } from "../local-devices/device-policy.service.js";
 import { ORG_ROLES, roleAtLeast } from "../orgs/roles.js";
+import { RunResume } from "../runtime/run-jobs.js";
 import { rootConversationOf } from "../runtime/subagents/child.js";
 import { SandboxService } from "../sandbox/sandbox.service.js";
 import { readScheduleSettings } from "../schedules/effective-settings.js";
@@ -102,10 +103,12 @@ function canHandle(a, initiator, accountId, role) {
  * 工具调用审批：新建（loop 调用）、列出 / 查看 / 处理（HTTP），以及「以后都允许」授权的查看与撤销。
  * 状态全部在 PG：处理决定在事务里 `SELECT … FOR UPDATE` 审批行，多副本并发处理同一审批时恰好一个生效。
  *
- * A decision is announced after the commit as the domain event `approval.decided` (exactly once:
- * only the decision that changed the row from pending), which the run's waits follow to resume it
- * (spec §3b; the wait sweep resumes a run whose resume was lost). Events are appended in the
- * context's transaction (`EventLog.appendIn`) and published after the commit.
+ * A decision resumes its waiting run in the decision's transaction (`RunResume.resumeIn`, after the
+ * decided row: lock order approval, then run; transactional outbox spec §6). It is announced after
+ * the commit as the domain event `approval.decided` (exactly once: only the decision that changed
+ * the row from pending; no kernel subscriber: the IM card update is owed by the `approval_decided`
+ * append, transactional outbox spec §8.1). Events are appended in the context's transaction
+ * (`EventLog.appendIn`) and published after the commit.
  */
 let ApprovalsService = class ApprovalsService {
     db;
@@ -118,6 +121,7 @@ let ApprovalsService = class ApprovalsService {
     policies;
     lockService;
     sandbox;
+    resumes;
     constructor(db, config, eventLog, events, txHost, schedules, 
     /** A trial approval is kept only for a tool the task may hold as a grant (its agent's tools). */
     registry, 
@@ -126,7 +130,9 @@ let ApprovalsService = class ApprovalsService {
     /** One decision of a network ask at a time, across replicas (the op is sent before the transaction). */
     lockService, 
     /** A trial run's 「这次允许」 becomes a task grant only within the org's egress. */
-    sandbox) {
+    sandbox, 
+    /** A decision resumes its waiting run in the decision's transaction. */
+    resumes) {
         this.db = db;
         this.config = config;
         this.eventLog = eventLog;
@@ -137,6 +143,7 @@ let ApprovalsService = class ApprovalsService {
         this.policies = policies;
         this.lockService = lockService;
         this.sandbox = sandbox;
+        this.resumes = resumes;
     }
     /**
      * 新建 pending 审批（`expires_at` = 现在 + `tools.approvalTimeoutHours`）并写 `approval_requested`，同一事务。
@@ -549,7 +556,7 @@ let ApprovalsService = class ApprovalsService {
     /** After the commit: the decision's events reach the page, the run's waits and IM delivery. */
     async announceDecided(record, toSeq) {
         await this.eventLog.notify(record.conversationId, toSeq);
-        // waits resume the run and its IM delivery is enqueued (handler failures are logged)
+        // its IM delivery is enqueued (handler failures are logged); the run resumed in the decision
         await this.events.emit("approval.decided", {
             id: record.id,
             orgId: record.orgId,
@@ -571,6 +578,9 @@ let ApprovalsService = class ApprovalsService {
     // decision committed, even when a caller has a transaction open
     async decideIn(orgId, id, accountId, body, actorTokenId, network) {
         const t = this.db.db;
+        // lock order: the conversation, the approval, then the run (as a stop of the waiting run)
+        if (!(await this.lockConversationOf(id, orgId)))
+            throw notFound();
         const locked = await t
             .selectFrom("approvals")
             .selectAll()
@@ -734,6 +744,7 @@ let ApprovalsService = class ApprovalsService {
                     ...(reason !== undefined && { reason }),
                 },
             });
+            await this.resumes.resumeIn(before.runId, id);
             return { record: toRecord(updated), toSeq: Math.max(...written.map((e) => e.seq)) };
         }
         await audit(t, {
@@ -754,6 +765,9 @@ let ApprovalsService = class ApprovalsService {
                 ...(reason !== undefined && { reason }),
             },
         });
+        // the run last (lock order: the decided row, then `runs`); a still-running run is resumed by
+        // its suspend's re-check
+        await this.resumes.resumeIn(before.runId, id);
         return { record: toRecord(updated), toSeq: Math.max(...written.map((e) => e.seq)) };
     }
     /**
@@ -908,6 +922,8 @@ let ApprovalsService = class ApprovalsService {
     }
     async expireIn(id) {
         const t = this.db.db;
+        if (!(await this.lockConversationOf(id)))
+            return { outcome: "settled" };
         const locked = await t
             .selectFrom("approvals")
             .selectAll()
@@ -965,10 +981,22 @@ let ApprovalsService = class ApprovalsService {
      */
     async cancelPendingFor(orgId, accountId) {
         const t = this.db.db;
+        // the conversations first, in id order (lock order: conversation, then approval rows)
+        const convs = await this.lockConversations(t
+            .selectFrom("approvals")
+            .select("conversation_id")
+            .where("org_id", "=", orgId)
+            .where("requested_for", "=", accountId)
+            .where("status", "=", "pending"));
+        // only the conversations locked above: an approval asked meanwhile in another one is left to
+        // the run's stop or the sweep, so no conversation is locked after a row
+        if (convs.length === 0)
+            return { records: [], seqs: new Map() };
         const rows = await t
             .selectFrom("approvals")
             .selectAll()
             .where("org_id", "=", orgId)
+            .where("conversation_id", "in", convs)
             .where("requested_for", "=", accountId)
             .where("status", "=", "pending")
             .orderBy("created_at")
@@ -996,17 +1024,29 @@ let ApprovalsService = class ApprovalsService {
      * active runs `authorAccountId` started, in the conversation and in its sub-agents'
      * conversations at any depth (their asks are shown in the root). Each becomes `skipped` with
      * `approval_decided{skipped}` by the author; access stays blocked. Returns the skipped records and
-     * the highest seq written per conversation; the caller notifies and emits
-     * `approval.decided{skipped}` after the commit, so the runs resume.
+     * the highest seq written per conversation; the caller resumes their waiting runs in this
+     * transaction once every skipped row is locked (`ConversationsService.skipWaitsIn`), and notifies
+     * and emits the domain event `approval.decided{skipped}` after the commit (its IM card update is
+     * owed by the append, transactional outbox spec §8.1).
      */
     async skipNetworkIn(conversationId, authorAccountId) {
         const t = this.db.db;
         const tree = await this.subtreeOf(conversationId);
+        // the sub-agents' conversations with a pending ask first, in id order (lock order:
+        // conversation, then approval rows; the caller holds `conversationId`'s already)
+        const convs = await this.lockConversations(t
+            .selectFrom("approvals")
+            .select("conversation_id")
+            .where("conversation_id", "in", tree)
+            .where("kind", "=", "network")
+            .where("status", "=", "pending"));
+        if (convs.length === 0)
+            return { records: [], seqs: new Map() };
         const rows = await t
             .selectFrom("approvals as a")
             .innerJoin("runs as r", "r.id", "a.run_id")
             .selectAll("a")
-            .where("a.conversation_id", "in", tree)
+            .where("a.conversation_id", "in", convs)
             .where("a.kind", "=", "network")
             .where("a.status", "=", "pending")
             .where(sql `a.expires_at > now()`)
@@ -1031,6 +1071,43 @@ let ApprovalsService = class ApprovalsService {
         }
         return { records, seqs };
     }
+    /**
+     * Locks the conversation row of approval `id` (`SELECT … FOR UPDATE`; re-entrant with the lock
+     * `EventLog.appendIn` takes later). Every write to an approval row takes its conversation's lock
+     * first, then the approval row, then the run row, as the stop of a waiting run
+     * (`Waits.abortWaitingIn`) and the questions do, so no two of them can deadlock. False: no such
+     * approval (in `orgId`).
+     */
+    async lockConversationOf(id, orgId) {
+        const t = this.db.db;
+        let q = t.selectFrom("approvals").select("conversation_id").where("id", "=", id);
+        if (orgId !== undefined)
+            q = q.where("org_id", "=", orgId);
+        const row = await q.executeTakeFirst();
+        if (!row)
+            return false;
+        await t
+            .selectFrom("conversations")
+            .select("id")
+            .where("id", "=", row.conversation_id)
+            .forUpdate()
+            .executeTakeFirst();
+        return true;
+    }
+    /** Locks, in id order, the conversations `ids` selects; returns their ids. */
+    async lockConversations(ids) {
+        const found = [...new Set((await ids.execute()).map((r) => r.conversation_id))];
+        if (found.length === 0)
+            return [];
+        const rows = await this.db.db
+            .selectFrom("conversations")
+            .select("id")
+            .where("id", "in", found)
+            .orderBy("id")
+            .forUpdate()
+            .execute();
+        return rows.map((r) => r.id);
+    }
     /** `conversationId` and its sub-agents' conversations at any depth (at most 16 levels). */
     async subtreeOf(conversationId) {
         const all = [conversationId];
@@ -1252,6 +1329,7 @@ ApprovalsService = __decorate([
     __param(6, Inject(ToolRegistry)),
     __param(7, Inject(DevicePolicyService)),
     __param(8, Inject(LockService)),
-    __param(9, Inject(SandboxService))
+    __param(9, Inject(SandboxService)),
+    __param(10, Inject(RunResume))
 ], ApprovalsService);
 export { ApprovalsService };

package/dist/tools/builtin-names.d.ts

@@ -23,6 +23,7 @@ export declare const BUILTIN: {
     readonly SubagentHandback: "SubagentHandback";
     readonly TaskOutput: "TaskOutput";
     readonly TaskStop: "TaskStop";
+    readonly TaskList: "TaskList";
     readonly WebSearch: "WebSearch";
     readonly WebFetch: "WebFetch";
     readonly Platform: "Platform";
@@ -35,7 +36,8 @@ export declare const BUILTIN: {
 export type BuiltinName = (typeof BUILTIN)[keyof typeof BUILTIN];
 /**
  * The builtin tools that run in the conversation's sandbox. `TaskOutput` and `TaskStop` read and
- * stop the background tasks `Bash` started (background Bash spec §2.2, §2.3).
+ * stop the background tasks `Bash` started (background Bash spec §2.2, §2.3); `TaskList` lists them
+ * (and the conversation's sub-agents).
  */
 export declare const SANDBOX_TOOL_NAMES: readonly BuiltinName[];
 /** The builtin tools that reach the web through the org's web-search / web-fetch providers. */
@@ -47,7 +49,7 @@ export declare const WEB_TOOL_NAMES: readonly BuiltinName[];
 export declare const BASH_COMPANION_TOOLS: readonly BuiltinName[];
 /**
  * Sandbox tools that need approval when the org setting `sandboxToolPolicy` is `ask` (not the
- * read-only ones). Not `TaskOutput` or `TaskStop`: they only read or stop a task whose launch
+ * read-only ones). Not `TaskOutput`, `TaskStop` or `TaskList`: they only read, list or stop tasks whose launch
  * already went through `Bash`'s policy (background Bash spec §4.5).
  */
 export declare const SANDBOX_ASK_TOOL_NAMES: ReadonlySet<string>;
@@ -110,7 +112,7 @@ export declare const CHILD_REMOVED_TOOLS: readonly ["AskUserQuestion", "Deliver"
 /**
  * The builtins every agent has unless it turns them off (tools default-on spec §4), in this
  * order: {@link BUILTIN_TOOL_NAMES} without the ones the registry manages by rule (`ToolSearch`,
- * `Skill`, `SendMessage`, `SubagentHandback`) and without `TaskOutput` / `TaskStop`, which come
+ * `Skill`, `SendMessage`, `SubagentHandback`) and without `TaskOutput` / `TaskStop` / `TaskList`, which come
  * with `Bash` ({@link BASH_COMPANION_TOOLS}). These are also the builtins an agent can turn off.
  */
 export declare const AGENT_BUILTIN_NAMES: readonly BuiltinName[];

package/dist/tools/builtin-names.js

@@ -23,6 +23,7 @@ export const BUILTIN = {
     SubagentHandback: "SubagentHandback",
     TaskOutput: "TaskOutput",
     TaskStop: "TaskStop",
+    TaskList: "TaskList",
     WebSearch: "WebSearch",
     WebFetch: "WebFetch",
     Platform: "Platform",
@@ -34,7 +35,8 @@ export const BUILTIN = {
 };
 /**
  * The builtin tools that run in the conversation's sandbox. `TaskOutput` and `TaskStop` read and
- * stop the background tasks `Bash` started (background Bash spec §2.2, §2.3).
+ * stop the background tasks `Bash` started (background Bash spec §2.2, §2.3); `TaskList` lists them
+ * (and the conversation's sub-agents).
  */
 export const SANDBOX_TOOL_NAMES = [
     BUILTIN.Bash,
@@ -46,6 +48,7 @@ export const SANDBOX_TOOL_NAMES = [
     BUILTIN.Deliver,
     BUILTIN.TaskOutput,
     BUILTIN.TaskStop,
+    BUILTIN.TaskList,
 ];
 /** The builtin tools that reach the web through the org's web-search / web-fetch providers. */
 export const WEB_TOOL_NAMES = [BUILTIN.WebSearch, BUILTIN.WebFetch];
@@ -53,10 +56,14 @@ export const WEB_TOOL_NAMES = [BUILTIN.WebSearch, BUILTIN.WebFetch];
  * The tools offered with `Bash` whenever it is offered (background Bash: a model that can start a
  * background task can read and stop it). `ToolRegistry` adds them; an explicit ref is harmless.
  */
-export const BASH_COMPANION_TOOLS = [BUILTIN.TaskOutput, BUILTIN.TaskStop];
+export const BASH_COMPANION_TOOLS = [
+    BUILTIN.TaskOutput,
+    BUILTIN.TaskStop,
+    BUILTIN.TaskList,
+];
 /**
  * Sandbox tools that need approval when the org setting `sandboxToolPolicy` is `ask` (not the
- * read-only ones). Not `TaskOutput` or `TaskStop`: they only read or stop a task whose launch
+ * read-only ones). Not `TaskOutput`, `TaskStop` or `TaskList`: they only read, list or stop tasks whose launch
  * already went through `Bash`'s policy (background Bash spec §4.5).
  */
 export const SANDBOX_ASK_TOOL_NAMES = new Set([
@@ -158,7 +165,7 @@ export const CHILD_REMOVED_TOOLS = [
 /**
  * The builtins every agent has unless it turns them off (tools default-on spec §4), in this
  * order: {@link BUILTIN_TOOL_NAMES} without the ones the registry manages by rule (`ToolSearch`,
- * `Skill`, `SendMessage`, `SubagentHandback`) and without `TaskOutput` / `TaskStop`, which come
+ * `Skill`, `SendMessage`, `SubagentHandback`) and without `TaskOutput` / `TaskStop` / `TaskList`, which come
  * with `Bash` ({@link BASH_COMPANION_TOOLS}). These are also the builtins an agent can turn off.
  */
 export const AGENT_BUILTIN_NAMES = BUILTIN_TOOL_NAMES.filter((n) => n !== BUILTIN.ToolSearch &&
@@ -177,6 +184,7 @@ export const BUILTIN_TOOL_KINDS = {
     [BUILTIN.Deliver]: "tool",
     [BUILTIN.TaskOutput]: "read",
     [BUILTIN.TaskStop]: "command",
+    [BUILTIN.TaskList]: "read",
     [BUILTIN.ToolSearch]: "meta",
     [BUILTIN.Skill]: "meta",
     [BUILTIN.ReadToolOutput]: "meta",

package/dist/tools/builtins/builtin-tools.d.ts

@@ -14,7 +14,6 @@ import { AgentDocs } from "../../platform/agent-docs.js";
 import { PlatformOperations } from "../../platform/registry.js";
 import type { HookRunner } from "../../runtime/hook-calls.js";
 import { StepLog } from "../../runtime/step-log.js";
-import { UsageReporter } from "../../runtime/usage-report.js";
 import { SandboxService } from "../../sandbox/sandbox.service.js";
 import { ScheduledTaskStore } from "../../schedules/store.js";
 import { StorageService } from "../../storage/storage.service.js";
@@ -34,7 +33,7 @@ export declare class BuiltinTools {
     /** The WebFetch extraction call: the `web_fetch` purpose, its hooks, usage and denials. */
     purposes: ModelPurposesService, host: {
         readonly hooks?: HookRunner;
-    } | undefined, usageReport: UsageReporter, stepLog: StepLog, log: Logger, background: BackgroundTaskStore, finisher: BackgroundTaskFinisher, stopper: BackgroundTaskStopper, platformOps: PlatformOperations, platformActor: PlatformActor, agentDocs: AgentDocs, 
+    } | undefined, stepLog: StepLog, log: Logger, background: BackgroundTaskStore, finisher: BackgroundTaskFinisher, stopper: BackgroundTaskStopper, platformOps: PlatformOperations, platformActor: PlatformActor, agentDocs: AgentDocs, 
     /** The schedule tools read tasks and grants; their writes go through the task service. */
     scheduleStore: ScheduledTaskStore, 
     /** `ScheduleUpdate`'s write: its field change and grant changes in one transaction. */

package/dist/tools/builtins/builtin-tools.js

@@ -11,8 +11,10 @@ import { Inject, Injectable, Optional } from "@nestjs/common";
 import { BackgroundTaskFinisher } from "../../background/finish.js";
 import { BackgroundTaskStopper } from "../../background/stop.js";
 import { BackgroundTaskStore } from "../../background/store.js";
+import { readChildAgents } from "../../conversations/agent-tree.js";
 import { AttachmentsService } from "../../conversations/attachments.service.js";
 import { EventLog } from "../../conversations/event-log.js";
+import { conversationAncestors } from "../../conversations/tree.js";
 import { ConversationDevices } from "../../devices/conversation-devices.js";
 import { ExtensionHost } from "../../extensions/host.js";
 import { ExtensionPointDefaults } from "../../extensions/point-defaults.js";
@@ -26,7 +28,6 @@ import { AgentDocs } from "../../platform/agent-docs.js";
 import { PlatformOperations } from "../../platform/registry.js";
 import { conversationTimeZone, RUN_CONTEXT_CLOCK } from "../../runtime/run-context.service.js";
 import { StepLog } from "../../runtime/step-log.js";
-import { UsageReporter } from "../../runtime/usage-report.js";
 import { SandboxService } from "../../sandbox/sandbox.service.js";
 import { ScheduledTaskStore } from "../../schedules/store.js";
 import { StorageService } from "../../storage/storage.service.js";
@@ -53,7 +54,7 @@ let BuiltinTools = class BuiltinTools {
     tools;
     constructor(db, config, outputs, storage, attachments, eventLog, sandbox, devices, points, webPages, 
     /** The WebFetch extraction call: the `web_fetch` purpose, its hooks, usage and denials. */
-    purposes, host, usageReport, stepLog, log, background, finisher, stopper, platformOps, platformActor, agentDocs, 
+    purposes, host, stepLog, log, background, finisher, stopper, platformOps, platformActor, agentDocs, 
     /** The schedule tools read tasks and grants; their writes go through the task service. */
     scheduleStore, 
     /** `ScheduleUpdate`'s write: its field change and grant changes in one transaction. */
@@ -67,6 +68,10 @@ let BuiltinTools = class BuiltinTools {
             devices,
             background,
             tasks: { finisher, stopper },
+            subagents: {
+                inTree: async (root, id) => id !== root && (await conversationAncestors(db.db, id)).includes(root),
+                childrenOf: (orgId, conversationId) => readChildAgents(db.db, orgId, conversationId),
+            },
             attachments,
             storage,
             eventLog,
@@ -103,7 +108,7 @@ let BuiltinTools = class BuiltinTools {
                 points,
                 config,
                 cache: webPages,
-                extract: (ctx, page, prompt) => extractAnswer({ purposes, eventLog, stepLog, config, log, hooks: host?.hooks, usageReport }, ctx, page, prompt),
+                extract: (ctx, page, prompt) => extractAnswer({ purposes, eventLog, stepLog, config, log, hooks: host?.hooks }, ctx, page, prompt),
             }),
             // the platform's own operations and docs, as the run's person (Platform tool spec)
             platformTool({
@@ -149,19 +154,18 @@ BuiltinTools = __decorate([
     __param(9, Inject(WebPages)),
     __param(10, Inject(ModelPurposesService)),
     __param(11, Inject(ExtensionHost)),
-    __param(12, Inject(UsageReporter)),
-    __param(13, Inject(StepLog)),
-    __param(14, Inject(KERNEL_LOGGER)),
-    __param(15, Inject(BackgroundTaskStore)),
-    __param(16, Inject(BackgroundTaskFinisher)),
-    __param(17, Inject(BackgroundTaskStopper)),
-    __param(18, Inject(PlatformOperations)),
-    __param(19, Inject(PlatformActor)),
-    __param(20, Inject(AgentDocs)),
-    __param(21, Inject(ScheduledTaskStore)),
-    __param(22, Inject(ScheduleUpdates)),
-    __param(23, Inject(ScheduleToolsPort)),
-    __param(24, Optional()),
-    __param(24, Inject(RUN_CONTEXT_CLOCK))
+    __param(12, Inject(StepLog)),
+    __param(13, Inject(KERNEL_LOGGER)),
+    __param(14, Inject(BackgroundTaskStore)),
+    __param(15, Inject(BackgroundTaskFinisher)),
+    __param(16, Inject(BackgroundTaskStopper)),
+    __param(17, Inject(PlatformOperations)),
+    __param(18, Inject(PlatformActor)),
+    __param(19, Inject(AgentDocs)),
+    __param(20, Inject(ScheduledTaskStore)),
+    __param(21, Inject(ScheduleUpdates)),
+    __param(22, Inject(ScheduleToolsPort)),
+    __param(23, Optional()),
+    __param(23, Inject(RUN_CONTEXT_CLOCK))
 ], BuiltinTools);
 export { BuiltinTools };

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

@@ -29,19 +29,25 @@ const SPEC = {
         "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.\n\n" +
+        "Processes a normal call leaves running (started with '&' or nohup) may be stopped when the " +
+        "call ends, depending on the device, so use run_in_background for a dev server, a watcher or " +
+        "anything that must keep running after the call.\n\n" +
         "You can use the run_in_background parameter to run the command in the background, which " +
         "allows you to continue working while the command runs, e.g. a dev server, a long build or a " +
         "test suite. The call returns at once with a task id and the command's output goes to a file " +
         "under .capybara/tasks in the workspace directory. Read the output with TaskOutput (or Read) and stop the " +
-        "task with TaskStop; you will be told when it finishes. You do not need to use '&' at the end " +
+        "task with TaskStop; you will be told when it finishes. TaskList lists this conversation's " +
+        "background tasks and their ids, running ones first. You do not need to use '&' at the end " +
         "of the command when using this parameter. In the background, timeout defaults to the " +
         "deployment's background maximum (7200000 by default). A background task ends when its " +
         "command exits, and processes it left running are stopped. A background task is lost if the " +
         "sandbox is suspended (it is suspended after it has been running for a while, " +
         "sandbox.limits.maxRunningMinutes), so keep its results in files under the workspace directory.\n\n" +
         "Network access goes through a proxy set in HTTP_PROXY / HTTPS_PROXY / ALL_PROXY; a tool " +
-        "that ignores them fails with 'Operation not permitted'. A blocked domain is reported after " +
-        "the output.",
+        "that ignores them fails with 'Operation not permitted' or cannot resolve names. Such tools, " +
+        "browsers for example, need the proxy passed explicitly: for Chromium (also headless, as " +
+        "Playwright or Puppeteer launch it) pass --proxy-server=$HTTPS_PROXY. A blocked domain is " +
+        "reported after the output.",
     inputSchema: {
         type: "object",
         properties: {

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

@@ -3,6 +3,7 @@ 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 { ChildAgent } from "../../../conversations/agent-tree.js";
 import type { AttachmentsService } from "../../../conversations/attachments.service.js";
 import type { EventLog } from "../../../conversations/event-log.js";
 import { type ConversationDevices } from "../../../devices/conversation-devices.js";
@@ -25,7 +26,16 @@ export interface SandboxToolDeps {
      */
     devices: Pick<ConversationDevices, "forTool"> & Partial<Pick<ConversationDevices, "usableNow" | "sandboxLevel">>;
     /** Background `Bash` tasks; absent in test stubs, where `run_in_background` is refused. */
-    background?: Pick<BackgroundTaskStore, "reserve" | "markStarted" | "failLaunch" | "finishStoppedLaunch" | "releaseStop" | "get" | "advanceOffset">;
+    background?: Pick<BackgroundTaskStore, "reserve" | "markStarted" | "failLaunch" | "finishStoppedLaunch" | "releaseStop" | "get" | "advanceOffset" | "runningOwnedBy" | "finishedOwnedBy">;
+    /**
+     * Whether `id` is a sub-agent conversation in the tree under `rootConversationId` (TaskOutput /
+     * TaskStop tell a sub-agent's agentId apart from an unknown task id), and the sub-agents a
+     * conversation dispatched itself (`TaskList`); absent in test stubs.
+     */
+    subagents?: {
+        inTree(rootConversationId: string, id: string): Promise<boolean>;
+        childrenOf(orgId: string, conversationId: string): Promise<ChildAgent[]>;
+    };
     /**
      * What `TaskOutput` and `TaskStop` finish and stop tasks with; absent in test stubs, where both
      * answer that background tasks are not available.
@@ -83,6 +93,13 @@ export declare function noSandboxError(): ToolError;
 export declare const SANDBOX_UNREACHABLE_TEXT = "The sandbox provider can't be reached (the connection failed), so this call did nothing in the sandbox; retrying won't help until a super admin checks the sandbox extension's configuration (Admin console \u2192 Extensions). Continue without the sandbox, or ask the person to have a super admin check it.";
 /** A provider connection that broke during the call: the provider may have acted before it broke. */
 export declare const SANDBOX_CONNECTION_DROPPED_TEXT = "The connection to the sandbox provider broke during this call, so it may or may not have taken effect; check the sandbox state before retrying. If it fails again, continue without the sandbox and ask the person to have a super admin check the sandbox extension's configuration (Admin console \u2192 Extensions).";
+/**
+ * A cloud provider refused the device's tier (`sandbox.tier_refused`, spec §5.3): the tier the
+ * device asks for, never the provider's own message (it may name its settings).
+ */
+export declare const sandboxTierRefusedText: (tier: string) => string;
+/** A cloud provider failed to create the device's sandbox otherwise (`sandbox.create_failed`). */
+export declare const SANDBOX_CREATE_FAILED_TEXT = "The cloud sandbox provider could not create this device's sandbox, so nothing ran in it. Retry once; if it fails again, continue without the sandbox and ask the person to have a super admin check the sandbox extension's settings (Admin console \u2192 Extensions).";
 /** The directory of attachments in the device (each conversation has a subdirectory). */
 export declare const attachmentsRoot: (roots: SandboxRoots) => string;
 /** {@link attachmentsRoot} of an instance with the default roots. */

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

@@ -1,4 +1,4 @@
-import { DEFAULT_SANDBOX_ROOTS, DeviceProtocolError, isFileSystemGoneError, isSandboxGoneError, ToolError, validateSandboxPath, validateSandboxPathShape, } from "@capybara-hq/plugin-sdk";
+import { DEFAULT_SANDBOX_ROOTS, DeviceProtocolError, isFileSystemGoneError, isSandboxGoneError, isSandboxTier, ToolError, validateSandboxPath, validateSandboxPathShape, } from "@capybara-hq/plugin-sdk";
 import { ANONYMOUS_NO_DEVICE, } from "../../../devices/conversation-devices.js";
 import { ApiError } from "../../../errors.js";
 import { UNSANDBOXED_NOT_ALLOWED_ERROR } from "../../../local-devices/local-device-provider.js";
@@ -48,6 +48,13 @@ const DEVICE_OFFLINE_TEXT = "The device's machine is offline. Ask the person to
 const DEVICE_OUTDATED_TEXT = "The device's machine runs an outdated capybara-device. Ask the person to update it on that machine and start it again.";
 const DEVICE_REVOKED_TEXT = "The device's machine was disconnected. Ask the person to run capybara-device logout, then capybara-device login on it, or to start a new conversation on another device.";
 const deviceProtocolText = (detail) => `The device's machine sent an answer the platform cannot read (${detail}). Ask the person to update capybara-device on that machine, then retry.`;
+/**
+ * A cloud provider refused the device's tier (`sandbox.tier_refused`, spec §5.3): the tier the
+ * device asks for, never the provider's own message (it may name its settings).
+ */
+export const sandboxTierRefusedText = (tier) => `The cloud sandbox can't run this device at the ${tier} tier: the sandbox provider refused to create it there, so nothing ran in the sandbox and retrying won't help. Ask the person to lower the device's sandbox tier on its device page, or to have an org admin lower the org's highest tier in the sandbox settings, or a super admin to allow that tier in the sandbox extension's settings (Admin console → Extensions). Continue without the sandbox meanwhile.`;
+/** A cloud provider failed to create the device's sandbox otherwise (`sandbox.create_failed`). */
+export const SANDBOX_CREATE_FAILED_TEXT = "The cloud sandbox provider could not create this device's sandbox, so nothing ran in it. Retry once; if it fails again, continue without the sandbox and ask the person to have a super admin check the sandbox extension's settings (Admin console → Extensions).";
 const LOCK_LOST_TEXT = "The sandbox operation was interrupted because the sandbox lock was lost; check the sandbox state and retry.";
 /** The directory of attachments in the device (each conversation has a subdirectory). */
 export const attachmentsRoot = (roots) => `${roots.workspace}/attachments`;
@@ -357,6 +364,12 @@ export function mapSandboxError(e, log) {
             return new ToolError(UNSANDBOXED_TEXT);
         if (e.code === "device.tier_not_granted")
             return new ToolError(UNATTENDED_OPEN_TIER_ERROR);
+        if (e.code === "sandbox.tier_refused") {
+            const tier = detail?.tier;
+            return new ToolError(sandboxTierRefusedText(isSandboxTier(tier) ? tier : "requested"));
+        }
+        if (e.code === "sandbox.create_failed")
+            return new ToolError(SANDBOX_CREATE_FAILED_TEXT);
     }
     // an operation outside withSandbox's own mapping (it records lost files itself)
     if (isFileSystemGoneError(e))

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

@@ -11,6 +11,7 @@ export { compileGlob, GlobPatternError, MAX_GLOB_STARS } from "./glob-match.js";
  * a provider for it. Allowed by default; with the org setting `sandboxToolPolicy` set to ask,
  * every one but Read / Glob / Grep needs approval (see policy.ts).
  * `TaskOutput` and `TaskStop` read and stop background `Bash` tasks through
- * `SandboxService.ifRunning` (never creating or resuming a sandbox); always allowed.
+ * `SandboxService.ifRunning` (never creating or resuming a sandbox); `TaskList` lists them and the
+ * conversation's sub-agents from PG; all three always allowed.
  */
 export declare function sandboxTools(deps: SandboxToolDeps): BuiltinTool[];

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

@@ -4,6 +4,7 @@ import { sandboxEditTool } from "./edit.js";
 import { sandboxGlobTool } from "./glob.js";
 import { sandboxGrepTool } from "./grep.js";
 import { sandboxReadTool } from "./read.js";
+import { taskListTool } from "./task-list.js";
 import { taskOutputTool } from "./task-output.js";
 import { taskStopTool } from "./task-stop.js";
 import { sandboxWriteTool } from "./write.js";
@@ -18,7 +19,8 @@ export { compileGlob, GlobPatternError, MAX_GLOB_STARS } from "./glob-match.js";
  * a provider for it. Allowed by default; with the org setting `sandboxToolPolicy` set to ask,
  * every one but Read / Glob / Grep needs approval (see policy.ts).
  * `TaskOutput` and `TaskStop` read and stop background `Bash` tasks through
- * `SandboxService.ifRunning` (never creating or resuming a sandbox); always allowed.
+ * `SandboxService.ifRunning` (never creating or resuming a sandbox); `TaskList` lists them and the
+ * conversation's sub-agents from PG; all three always allowed.
  */
 export function sandboxTools(deps) {
     return [
@@ -31,5 +33,6 @@ export function sandboxTools(deps) {
         sandboxDeliverTool(deps),
         taskOutputTool(deps),
         taskStopTool(deps),
+        taskListTool(deps),
     ];
 }

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

@@ -0,0 +1,12 @@
+import type { BuiltinTool } from "../../registry.js";
+import { type SandboxToolDeps } from "./common.js";
+/** How many finished background tasks (and finished sub-agents) `TaskList` lists at most. */
+export declare const TASK_LIST_FINISHED_LIMIT = 20;
+/**
+ * Built-in `TaskList`: the calling conversation's own background tasks (never its sub-agents' or
+ * another conversation's: owner `conversation_id`, as `TaskOutput` checks) and the sub-agents it
+ * dispatched itself. Running entries first (oldest first), then with `status: "all"` the
+ * {@link TASK_LIST_FINISHED_LIMIT} most recently finished. Reads PG only: it never checks a task in
+ * its sandbox, so a status is the poller's or a tool's last one.
+ */
+export declare function taskListTool(deps: SandboxToolDeps): BuiltinTool;