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

package/dist/runtime/waits.js

@@ -11,6 +11,7 @@ import { getQueueToken } from "@nestjs/bullmq";
 import { Inject, Injectable } from "@nestjs/common";
 import { DelayedError } from "bullmq";
 import { sql } from "kysely";
+import { BackgroundTaskStopper } from "../background/stop.js";
 import { EventLog } from "../conversations/event-log.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
@@ -70,6 +71,7 @@ let Waits = class Waits {
     abort;
     timeouts;
     log;
+    background;
     txHost;
     /** Drops the `run.orphaned` subscription (the events may outlive this instance). */
     unsubscribe;
@@ -88,7 +90,9 @@ let Waits = class Waits {
      */
     abort, 
     /** The maintenance queue: wait timeout jobs (`MaintenanceProcessor` consumes them). */
-    timeouts, events, log, txHost) {
+    timeouts, events, log, 
+    /** Stops a finished sub-agent run's background tasks ({@link childFinished}). */
+    background, txHost) {
         this.kdb = kdb;
         this.eventLog = eventLog;
         this.approvals = approvals;
@@ -100,6 +104,7 @@ let Waits = class Waits {
         this.abort = abort;
         this.timeouts = timeouts;
         this.log = log;
+        this.background = background;
         this.txHost = txHost;
         // an orphaned parent run (marked failed by `ensureRun`) stops its children at once; the
         // sweep's `sweepChildrenOfFinished` is the backstop
@@ -193,9 +198,17 @@ let Waits = class Waits {
             const row = waitingFor.kind === "approval"
                 ? await this.db
                     .selectFrom("approvals")
-                    .select(["tool_key", "expires_at"])
+                    .select(["tool_key", "expires_at", "requested_for", "approver_role"])
                     .where("id", "=", waitingFor.id)
                     .executeTakeFirst()
+                    .then((r) => r && {
+                    tool_key: r.tool_key,
+                    expires_at: r.expires_at,
+                    approver: {
+                        requestedFor: r.requested_for,
+                        approverRole: r.approver_role,
+                    },
+                })
                 : await this.db
                     .selectFrom("questions")
                     .select([sql `spec->>'toolKey'`.as("tool_key"), "expires_at"])
@@ -213,7 +226,10 @@ let Waits = class Waits {
                         childRunId: runId,
                         kind: waitingFor.kind,
                         ...(waitingFor.kind === "approval"
-                            ? { approvalId: waitingFor.id }
+                            ? {
+                                approvalId: waitingFor.id,
+                                ...row.approver,
+                            }
                             : { questionId: waitingFor.id }),
                         toolKey: row.tool_key,
                         expiresAt: new Date(row.expires_at).toISOString(),
@@ -925,7 +941,8 @@ let Waits = class Waits {
      * the conditional resume lets exactly one succeed, the last to see all its siblings terminal. A
      * run that is not a dispatched child, or not terminal yet, is left alone. A crash in between is
      * repaired by the wait sweep and by the parent's tools node, which writes a missing
-     * `subagent_finished` itself.
+     * `subagent_finished` itself. The running background tasks the terminal child run started are
+     * then stopped (not those of a later follow-up run of the same child).
      */
     async childFinished(childRunId) {
         const row = await dispatchOfChildRun(this.db, childRunId);
@@ -938,13 +955,21 @@ let Waits = class Waits {
             .executeTakeFirst();
         if (!run || !TERMINAL_STATUSES.has(run.status))
             return;
-        const r = await childResult(this.eventLog, row);
-        if (!r) {
-            this.log.warn("sub-agent run is terminal without a terminal event", { childRunId });
-            return;
+        try {
+            const r = await childResult(this.eventLog, row);
+            if (!r) {
+                this.log.warn("sub-agent run is terminal without a terminal event", { childRunId });
+                return;
+            }
+            await this.eventLog.append(row.parentConversationId, [finishedEvent(row, r.finished)]);
+            await this.resume(row.parentRunId, childRunId);
+        }
+        finally {
+            // whichever way the child run ended (its worker, a stop while waiting, an orphan repair):
+            // nobody can read or stop the background tasks it started through its model any more
+            // (background Bash spec §4.3). Never throws.
+            await this.background.stopSubagentTasks(row.childConversationId, childRunId);
         }
-        await this.eventLog.append(row.parentConversationId, [finishedEvent(row, r.finished)]);
-        await this.resume(row.parentRunId, childRunId);
     }
     /**
      * Stops the active children of a parent run (sub-agents spec §12), or only those dispatched in
@@ -1020,7 +1045,8 @@ Waits = __decorate([
     __param(9, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME))),
     __param(10, Inject(KernelEvents)),
     __param(11, Inject(KERNEL_LOGGER)),
-    __param(12, Inject(TransactionHost))
+    __param(12, Inject(BackgroundTaskStopper)),
+    __param(13, Inject(TransactionHost))
 ], Waits);
 export { Waits };
 /**

package/dist/sandbox/sandbox.module.js

@@ -5,6 +5,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { Module } from "@nestjs/common";
+import { BackgroundStoreModule } from "../background/store.module.js";
 import { ExtensionRegistryModule } from "../extensions/registry.js";
 import { QueueModule } from "../infra/queue/queue.module.js";
 import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
@@ -22,7 +23,11 @@ let SandboxModule = class SandboxModule {
 };
 SandboxModule = __decorate([
     Module({
-        imports: [ExtensionRegistryModule, QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME)],
+        imports: [
+            ExtensionRegistryModule,
+            BackgroundStoreModule,
+            QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
+        ],
         providers: [SandboxProviders, SandboxLeases, SandboxService, SandboxJobs],
         exports: [SandboxService, SandboxJobs],
     })

package/dist/sandbox/sandbox.service.d.ts

@@ -1,6 +1,7 @@
 import { type SandboxHandle, type SandboxProvider } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
 import { type Selectable } from "kysely";
+import { BackgroundTaskStore } from "../background/store.js";
 import { type KernelConfig } from "../config/schema.js";
 import type { SandboxesTable } from "../db/kernel-schema.js";
 import { ApiError } from "../errors.js";
@@ -28,6 +29,28 @@ interface Instance {
     handle: SandboxHandle;
     createdAt: number;
 }
+/**
+ * The provider {@link SandboxService.ifRunning} passes to its callback: every `exec` carries the
+ * holder's tag, like the one `withSandbox` passes.
+ */
+export type TaggedProvider = SandboxProvider;
+/** What {@link SandboxService.ifRunning} did. */
+export type IfRunningResult<T> = {
+    kind: "ran";
+    value: T;
+}
+/**
+ * No sandbox, or the instance is not running: `status` is the sandbox row's (`suspended`,
+ * `creating`, `destroyed`, or `running` recorded with another provider), `gone` without a row.
+ */
+ | {
+    kind: "not_running";
+    status: SandboxesTable["status"] | "gone";
+}
+/** The sandbox now records another instance (a rebuild). */
+ | {
+    kind: "other_instance";
+};
 /**
  * The row still records the instance `gone` (same handle and same `created_at`). Handles compare
  * canonically: a jsonb round trip reorders a multi-key handle's keys (final review m9).
@@ -100,11 +123,15 @@ export declare class SandboxService {
     private readonly providers;
     private readonly config;
     private readonly log;
+    /** Background tasks lost while their process may live on (killed after a resume). */
+    private readonly background;
     constructor(db: KernelDb, 
     /** The record of the instance each holder last used (`capk:sandbox-seen:…`). */
     redis: Pick<Redis, "set">, leases: SandboxLeases, 
     /** The `sandbox@1` provider (read at every call: providers are ready after the extension load). */
-    providers: Pick<SandboxProviders, "current" | "lookup">, config: Pick<KernelConfigService, "get">, log: Pick<KernelLogger, "info" | "warn">);
+    providers: Pick<SandboxProviders, "current" | "lookup">, config: Pick<KernelConfigService, "get">, log: Pick<KernelLogger, "info" | "warn">, 
+    /** Background tasks lost while their process may live on (killed after a resume). */
+    background: Pick<BackgroundTaskStore, "pendingKills" | "clearKill">);
     /** Poll interval while waiting for a lease (the leases' own). */
     private get pollMs();
     /** 是否有沙箱提供方。 */
@@ -119,6 +146,29 @@ export declare class SandboxService {
         status: "running" | "suspended";
         lastUsedAt: Date;
     } | null>;
+    /**
+     * The instance the conversation's sandbox records now (its `created_at`), while it has one that
+     * runs or is suspended; null otherwise. Read without a lease: a caller inside `withSandbox`
+     * reads the instance its own lease keeps.
+     */
+    currentInstance(conversationId: string): Promise<{
+        createdAt: Date;
+    } | null>;
+    /**
+     * Runs `fn` on the conversation's sandbox only while it runs the instance created at
+     * `instance.createdAt` (background tasks, spec 2026-11-05-background-bash-design §4.3). It never
+     * creates, resumes or rebuilds a sandbox: a sandbox that is missing, suspended, being created or
+     * destroyed (or recorded with another provider) is `not_running`, one that records another
+     * instance is `other_instance`. Otherwise `fn` runs under a shared lease, as a `withSandbox`
+     * holder does (its tag on every exec, crashed holders' commands killed), and `last_used_at`
+     * moves forward when it ends. Waits for the lease up to `sandbox.lockWaitSeconds`
+     * (`sandbox.busy`); `signal` (optional) ends the wait with its abort reason. The signal passed
+     * to `fn` aborts with `signal` or when the lease is lost. Errors of `fn` (`SandboxGoneError`
+     * too) are thrown as they are.
+     */
+    ifRunning<T>(conversationId: string, instance: {
+        createdAt: Date;
+    }, fn: (p: TaggedProvider, h: SandboxHandle, signal: AbortSignal) => Promise<T>, signal?: AbortSignal): Promise<IfRunningResult<T>>;
     /**
      * A short lease on one path of the conversation's sandbox around the kernel's own
      * read-modify-write of that file (spec §10.4); waits up to 30 s, then throws
@@ -164,8 +214,8 @@ export declare class SandboxService {
     /** Recorded running with the current provider, and not the instance found gone. */
     private usable;
     /**
-     * Under a just-taken shared lease: confirms the row is still usable (else releases and returns
-     * null), records the holder and kills crashed holders' commands.
+     * Under a just-taken shared lease: confirms the row is still `accept`ed (else releases and
+     * returns null), records the holder and kills crashed holders' commands.
      */
     private asShared;
     /**
@@ -206,6 +256,14 @@ export declare class SandboxService {
      * 结束）；其余失败只记 warn。提供方没有 `killAll` 时只记 info。
      */
     private killLeftovers;
+    /**
+     * Under the exclusive lease, right after a resume or a (re)build: kills the sessions of the
+     * background tasks marked lost while their process may live on (`kill_pending`), in one exec of
+     * `pkill -KILL -s <sid>`, then clears their flags. Tasks of another instance have no process
+     * here and are only cleared. A gone instance and an abort are thrown; another failure is warned
+     * and leaves the flags of this instance's tasks for the next resume.
+     */
+    private killPendingTasks;
     private require;
     /**
      * 防护写入：lease 仍在、且记录的 generation 仍是锁内读到的值时才写（并加一）；否则抛 {@link SandboxLockLostError}。

package/dist/sandbox/sandbox.service.js

@@ -11,6 +11,7 @@ import { randomUUID } from "node:crypto";
 import { isSandboxGoneError, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql, } from "kysely";
+import { BackgroundTaskStore } from "../background/store.js";
 import { DEFAULT_MAX_COMMAND_SECONDS, DEFAULT_MAX_RUN_SECONDS, } from "../config/schema.js";
 import { ApiError } from "../errors.js";
 import { readSandboxLimitOverride } from "../identity/settings.js";
@@ -36,6 +37,10 @@ const SWEEP_BATCH = 200;
 const SWEEP_CONCURRENCY = 4;
 /** destroyFor 等锁的上限：持有者在跑命令时最多等这么久。 */
 const DESTROY_FOR_WAIT_MS = 10 * 60_000;
+/** The time limit of the exec that kills lost background tasks after a resume (ms). */
+const PENDING_KILL_TIMEOUT_MS = 30_000;
+/** A background task's session id as `echo $!` printed it; anything else is never put in a command. */
+const SID_RE = /^[1-9][0-9]{0,9}$/;
 /** 维护里一次提供方操作的 signal：超时或锁丢失时中止。 */
 const opSignal = (lease) => AbortSignal.any([lease.signal, AbortSignal.timeout(SWEEP_OP_TIMEOUT_MS)]);
 /**
@@ -180,17 +185,21 @@ let SandboxService = class SandboxService {
     providers;
     config;
     log;
+    background;
     constructor(db, 
     /** The record of the instance each holder last used (`capk:sandbox-seen:…`). */
     redis, leases, 
     /** The `sandbox@1` provider (read at every call: providers are ready after the extension load). */
-    providers, config, log) {
+    providers, config, log, 
+    /** Background tasks lost while their process may live on (killed after a resume). */
+    background) {
         this.db = db;
         this.redis = redis;
         this.leases = leases;
         this.providers = providers;
         this.config = config;
         this.log = log;
+        this.background = background;
     }
     /** Poll interval while waiting for a lease (the leases' own). */
     get pollMs() {
@@ -219,6 +228,82 @@ let SandboxService = class SandboxService {
             return null;
         return { status: row.status, lastUsedAt: row.last_used_at };
     }
+    /**
+     * The instance the conversation's sandbox records now (its `created_at`), while it has one that
+     * runs or is suspended; null otherwise. Read without a lease: a caller inside `withSandbox`
+     * reads the instance its own lease keeps.
+     */
+    async currentInstance(conversationId) {
+        const row = await this.db
+            .selectFrom("sandboxes")
+            .select(["status", "handle", "created_at"])
+            .where("conversation_id", "=", conversationId)
+            .executeTakeFirst();
+        if (!row || row.handle === null)
+            return null;
+        if (row.status !== "running" && row.status !== "suspended")
+            return null;
+        return { createdAt: row.created_at };
+    }
+    /**
+     * Runs `fn` on the conversation's sandbox only while it runs the instance created at
+     * `instance.createdAt` (background tasks, spec 2026-11-05-background-bash-design §4.3). It never
+     * creates, resumes or rebuilds a sandbox: a sandbox that is missing, suspended, being created or
+     * destroyed (or recorded with another provider) is `not_running`, one that records another
+     * instance is `other_instance`. Otherwise `fn` runs under a shared lease, as a `withSandbox`
+     * holder does (its tag on every exec, crashed holders' commands killed), and `last_used_at`
+     * moves forward when it ends. Waits for the lease up to `sandbox.lockWaitSeconds`
+     * (`sandbox.busy`); `signal` (optional) ends the wait with its abort reason. The signal passed
+     * to `fn` aborts with `signal` or when the lease is lost. Errors of `fn` (`SandboxGoneError`
+     * too) are thrown as they are.
+     */
+    async ifRunning(conversationId, instance, fn, signal = new AbortController().signal) {
+        const p = this.require();
+        const conv = conversationId;
+        const cap = this.effectiveCap(p);
+        const deadline = Date.now() + this.config.get().sandbox.lockWaitSeconds * 1000;
+        const token = randomUUID();
+        for (;;) {
+            if (signal.aborted)
+                throw abortReason(signal);
+            const row = await this.db
+                .selectFrom("sandboxes")
+                .selectAll()
+                .where("conversation_id", "=", conv)
+                .executeTakeFirst();
+            if (!row)
+                return { kind: "not_running", status: "gone" };
+            if (row.created_at.getTime() !== instance.createdAt.getTime()) {
+                return { kind: "other_instance" };
+            }
+            if (!this.usable(row, p, null))
+                return { kind: "not_running", status: row.status };
+            // the instance this check saw: its handle plus `created_at` (never `generation`, which
+            // every lease bumps)
+            const want = { handle: row.handle, createdAt: row.created_at.getTime() };
+            if (!(await this.leases.legacyMarker(conv))) {
+                const lease = await this.leases.tryShared(conv, cap, token);
+                if (lease) {
+                    const e = await this.asShared({ orgId: row.org_id, conversationId: conv }, p, lease, (r) => this.usable(r, p, null) && isInstance(r, want), signal);
+                    if (e) {
+                        try {
+                            const impl = tagged(p.impl, lease.token, () => this.register(conv, lease.token));
+                            const sig = AbortSignal.any([signal, lease.signal]);
+                            return { kind: "ran", value: await fn(impl, e.handle, sig) };
+                        }
+                        finally {
+                            await this.leave(conv, e);
+                        }
+                    }
+                    // the row changed between the check and the lease: classify it again
+                    continue;
+                }
+            }
+            if (Date.now() + this.pollMs > deadline)
+                throw sandboxBusy();
+            await sleep(this.pollMs + Math.floor(Math.random() * this.pollMs), signal);
+        }
+    }
     /**
      * A short lease on one path of the conversation's sandbox around the kernel's own
      * read-modify-write of that file (spec §10.4); waits up to 30 s, then throws
@@ -318,7 +403,7 @@ let SandboxService = class SandboxService {
                         if (intent)
                             await this.clearIntent(conv, token);
                         intent = false;
-                        const e = await this.asShared(ctx, p, lease, gone, signal);
+                        const e = await this.asShared(ctx, p, lease, (r) => this.usable(r, p, gone), signal);
                         if (e)
                             return e;
                     }
@@ -365,14 +450,14 @@ let SandboxService = class SandboxService {
             !isInstance(row, gone));
     }
     /**
-     * Under a just-taken shared lease: confirms the row is still usable (else releases and returns
-     * null), records the holder and kills crashed holders' commands.
+     * Under a just-taken shared lease: confirms the row is still `accept`ed (else releases and
+     * returns null), records the holder and kills crashed holders' commands.
      */
-    async asShared(ctx, p, lease, gone, signal) {
+    async asShared(ctx, p, lease, accept, signal) {
         const conv = ctx.conversationId;
         try {
             const row = await this.readRow(ctx);
-            if (!this.usable(row, p, gone)) {
+            if (!accept(row)) {
                 await lease.release();
                 return null;
             }
@@ -429,6 +514,9 @@ let SandboxService = class SandboxService {
             if (!s.info.fresh && (s.resumed || dead.legacyMarker || dead.tags.length > 0)) {
                 await this.killLeftovers(conv, s.handle, p, sig, s.resumed && !dead.legacyMarker && dead.tags.length === 0 ? "resume" : "takeover");
             }
+            if (s.resumed || s.info.fresh) {
+                await this.killPendingTasks(conv, s.handle, s.createdAt, p, lease.token, sig);
+            }
             const shared = await lease.downgrade();
             await this.register(conv, shared.token);
             return { lease: shared, handle: s.handle, createdAt: s.createdAt, info: s.info };
@@ -618,6 +706,51 @@ let SandboxService = class SandboxService {
         }
         await this.kill(conversationId, why, () => killAll.call(p.impl, handle, signal), signal);
     }
+    /**
+     * Under the exclusive lease, right after a resume or a (re)build: kills the sessions of the
+     * background tasks marked lost while their process may live on (`kill_pending`), in one exec of
+     * `pkill -KILL -s <sid>`, then clears their flags. Tasks of another instance have no process
+     * here and are only cleared. A gone instance and an abort are thrown; another failure is warned
+     * and leaves the flags of this instance's tasks for the next resume.
+     */
+    async killPendingTasks(conversationId, handle, createdAt, p, tag, signal) {
+        const rows = await this.background.pendingKills(conversationId);
+        if (rows.length === 0)
+            return;
+        const mine = rows.filter((r) => r.sandboxCreatedAt?.getTime() === createdAt && r.sid !== null && SID_RE.test(r.sid));
+        let cleared = rows;
+        if (mine.length > 0) {
+            // pkill exits 1 when the session has no process left: only a higher status is a failure
+            const command = `rc=0; for sid in ${mine.map((r) => r.sid).join(" ")}; do pkill -KILL -s "$sid"; c=$?; [ "$c" -le 1 ] || rc=$c; done; exit $rc`;
+            try {
+                const r = await p.impl.exec(handle, {
+                    command,
+                    timeoutMs: PENDING_KILL_TIMEOUT_MS,
+                    maxOutputBytes: 4096,
+                    signal,
+                    tag,
+                });
+                if (r.exitCode !== 0) {
+                    throw new Error(`pkill exited with ${r.exitCode === null ? "no status" : r.exitCode}: ${r.stderr.slice(0, 500)}`);
+                }
+                this.log.info("lost background tasks killed after a sandbox resume", {
+                    conversationId,
+                    tasks: mine.map((t) => t.id),
+                });
+            }
+            catch (err) {
+                if (signal.aborted || isSandboxGoneError(err))
+                    throw err;
+                this.log.warn("cannot kill lost background tasks after a sandbox resume", {
+                    conversationId,
+                    err,
+                });
+                const kept = new Set(mine.map((r) => r.id));
+                cleared = rows.filter((r) => !kept.has(r.id));
+            }
+        }
+        await this.background.clearKill(cleared.map((r) => r.id));
+    }
     require() {
         const p = this.providers.current();
         if (!p)
@@ -934,6 +1067,7 @@ SandboxService = __decorate([
     __param(2, Inject(SandboxLeases)),
     __param(3, Inject(SandboxProviders)),
     __param(4, Inject(KernelConfigService)),
-    __param(5, Inject(KERNEL_LOGGER))
+    __param(5, Inject(KERNEL_LOGGER)),
+    __param(6, Inject(BackgroundTaskStore))
 ], SandboxService);
 export { SandboxService };

package/dist/tools/approvals.service.js

@@ -151,6 +151,8 @@ let ApprovalsService = class ApprovalsService {
                     toolKey: rec.toolKey,
                     expiresAt: rec.expiresAt,
                     ...(input.policy !== undefined && { policy: input.policy }),
+                    requestedFor: rec.requestedFor,
+                    approverRole: rec.approverRole,
                 },
             },
         ]);

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

@@ -21,11 +21,29 @@ export declare const BUILTIN: {
     readonly ReadToolOutput: "ReadToolOutput";
     readonly ToolSearch: "ToolSearch";
     readonly Agent: "Agent";
+    readonly TaskOutput: "TaskOutput";
+    readonly TaskStop: "TaskStop";
+    readonly WebSearch: "WebSearch";
+    readonly WebFetch: "WebFetch";
 };
 export type BuiltinName = (typeof BUILTIN)[keyof typeof BUILTIN];
-/** The builtin tools that run in the conversation's sandbox. */
+/**
+ * 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).
+ */
 export declare const SANDBOX_TOOL_NAMES: readonly BuiltinName[];
-/** Sandbox tools that need approval when the org setting `sandboxToolPolicy` is `ask` (not the read-only ones). */
+/** The builtin tools that reach the web through the org's web-search / web-fetch providers. */
+export declare const WEB_TOOL_NAMES: readonly BuiltinName[];
+/**
+ * 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 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
+ * already went through `Bash`'s policy (background Bash spec §4.5).
+ */
 export declare const SANDBOX_ASK_TOOL_NAMES: ReadonlySet<string>;
 /**
  * Every builtin name. Saving an agent checks builtin refs against this list, not against what is

package/dist/tools/builtin-names.js

@@ -19,8 +19,15 @@ export const BUILTIN = {
     ReadToolOutput: "ReadToolOutput",
     ToolSearch: "ToolSearch",
     Agent: "Agent",
+    TaskOutput: "TaskOutput",
+    TaskStop: "TaskStop",
+    WebSearch: "WebSearch",
+    WebFetch: "WebFetch",
 };
-/** The builtin tools that run in the conversation's sandbox. */
+/**
+ * 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).
+ */
 export const SANDBOX_TOOL_NAMES = [
     BUILTIN.Bash,
     BUILTIN.Read,
@@ -29,8 +36,21 @@ export const SANDBOX_TOOL_NAMES = [
     BUILTIN.Glob,
     BUILTIN.Grep,
     BUILTIN.Deliver,
+    BUILTIN.TaskOutput,
+    BUILTIN.TaskStop,
 ];
-/** Sandbox tools that need approval when the org setting `sandboxToolPolicy` is `ask` (not the read-only ones). */
+/** 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];
+/**
+ * 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];
+/**
+ * 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
+ * already went through `Bash`'s policy (background Bash spec §4.5).
+ */
 export const SANDBOX_ASK_TOOL_NAMES = new Set([
     BUILTIN.Bash,
     BUILTIN.Write,
@@ -51,6 +71,7 @@ export const BUILTIN_TOOL_NAMES = [
     BUILTIN.SkillWrite,
     ...SANDBOX_TOOL_NAMES,
     BUILTIN.Agent,
+    ...WEB_TOOL_NAMES,
 ];
 /** The builtin that loads a skill (added by the registry when the log has a skills catalog). */
 export const SKILL_LOAD = BUILTIN.Skill;
@@ -99,11 +120,15 @@ export const BUILTIN_TOOL_KINDS = {
     [BUILTIN.Glob]: "search",
     [BUILTIN.Grep]: "search",
     [BUILTIN.Deliver]: "tool",
+    [BUILTIN.TaskOutput]: "read",
+    [BUILTIN.TaskStop]: "command",
     [BUILTIN.ToolSearch]: "meta",
     [BUILTIN.Skill]: "meta",
     [BUILTIN.SkillWrite]: "meta",
     [BUILTIN.ReadToolOutput]: "meta",
     [BUILTIN.AskUserQuestion]: "meta",
+    [BUILTIN.WebSearch]: "search",
+    [BUILTIN.WebFetch]: "read",
 };
 /**
  * Input fields left out when matching a replayed call with a recorded one (full-run replay), per
@@ -112,5 +137,7 @@ export const BUILTIN_TOOL_KINDS = {
  * with one (or a different wording) still match.
  */
 export const MATCH_IGNORED_FIELDS = {
+    // `run_in_background` is matched on purpose: it changes what the call did (a launch that
+    // returns at once instead of the command's output; background Bash spec §4.4)
     [BUILTIN.Bash]: ["description"],
 };

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

@@ -1,12 +1,22 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import { BackgroundTaskFinisher } from "../../background/finish.js";
+import { BackgroundTaskStopper } from "../../background/stop.js";
+import { BackgroundTaskStore } from "../../background/store.js";
 import { AttachmentsService } from "../../conversations/attachments.service.js";
 import { EventLog } from "../../conversations/event-log.js";
+import { ExtensionPointDefaults } from "../../extensions/point-defaults.js";
 import { KernelConfigService } from "../../infra/config/kernel-config.service.js";
 import { KernelDb } from "../../infra/database/kernel-db.js";
+import { ModelPurposesService } from "../../models/purposes.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 { SkillChangesService } from "../../skills/changes.service.js";
 import { StorageService } from "../../storage/storage.service.js";
 import { ToolOutputs } from "../outputs.js";
 import type { BuiltinTool } from "../registry.js";
+import { WebPages } from "./web/index.js";
 /**
  * The kernel's builtin tools, built once from the injected services (their specs: names,
  * descriptions and schemas, are the factories' own and unchanged). `ToolSearch` and `Skill`
@@ -15,7 +25,11 @@ import type { BuiltinTool } from "../registry.js";
  */
 export declare class BuiltinTools {
     private readonly tools;
-    constructor(db: KernelDb, config: KernelConfigService, outputs: ToolOutputs, storage: StorageService, skillChanges: SkillChangesService, attachments: AttachmentsService, eventLog: EventLog, sandbox: SandboxService);
+    constructor(db: KernelDb, config: KernelConfigService, outputs: ToolOutputs, storage: StorageService, skillChanges: SkillChangesService, attachments: AttachmentsService, eventLog: EventLog, sandbox: SandboxService, points: ExtensionPointDefaults, webPages: WebPages, 
+    /** 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);
     /** The builtin tools, in a fixed order. */
     list(): readonly BuiltinTool[];
 }