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

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/skills/catalog.d.ts

@@ -11,7 +11,7 @@ import { type CatalogSkill, type PinnedSkill, type SkillsSnapshot } from "../run
 import { type PrefixedStorage, StorageService } from "../storage/storage.service.js";
 /**
  * 技能目录快照（M5 T14，Ruling M17）：运行开始时解析「此刻对这个对话生效的技能」，与日志里最新一份快照不同才写
- * `skills_catalog`。模型看到的目录与 `skill_load` 的名字解析只来自日志，不读实时的库。
+ * `skills_catalog`。模型看到的目录与 `Skill` 的名字解析只来自日志，不读实时的库。
  */
 /**
  * Pinned skill limits (spec §9.1): at most `count` pinned skills per agent, whose current SKILL.md
@@ -103,9 +103,9 @@ export declare function loadPinnedBodies(storage: PrefixedStorage, orgId: string
 export declare function fitPinned(pinned: readonly PinnedSkill[], log: Pick<Logger, "warn"> | undefined, input: Partial<Pick<EffectiveSkillsInput, "orgId" | "agentId" | "conversationId">>): PinnedSkill[];
 /** `skills_catalog` 的幂等键：每次运行最多写一份。 */
 /**
- * 是否给模型 `skill_load`：日志里有过技能目录快照（Ruling M17），**即使最新一份是空的**。构建请求与执行工具调用
+ * 是否给模型 `Skill`：日志里有过技能目录快照（Ruling M17），**即使最新一份是空的**。构建请求与执行工具调用
  * 用同一判定。不因空快照收回这个工具：工具集合一变缓存前缀就失效；而且 agent 没有别的工具时会发出「没有工具
- * 但历史里有 tool_use」的请求，Anthropic 会拒绝。空目录下调用 skill_load 由 `NO_SKILLS_TEXT` 给出可执行的说明。
+ * 但历史里有 tool_use」的请求，Anthropic 会拒绝。空目录下调用 Skill 由 `NO_SKILLS_TEXT` 给出可执行的说明。
  */
 export declare function skillLoadOffered(latest: Extract<ConversationEvent, {
     type: "skills_catalog";
@@ -124,7 +124,7 @@ export declare const skillsCatalogIdemKey: (runId: string) => string;
 /**
  * 在调用方事务里锁会话行（与 `EventLog.append` 同一把锁）并读最新一份技能目录快照（没有为 undefined）。
  * `db` is the caller's transaction handle (`KernelDb.db` inside `@Transactional`).
- * 「读最新 → 推出下一份 → 追加」都在这把锁内，别的写快照的事务（运行开始、skill_write、拒绝时的回退）插不进来。
+ * 「读最新 → 推出下一份 → 追加」都在这把锁内，别的写快照的事务（运行开始、SkillWrite、拒绝时的回退）插不进来。
  */
 export declare function lockLatestCatalog(db: KernelSchemaDb, conversationId: string): Promise<SkillsSnapshot | undefined>;
 /**

package/dist/skills/catalog.js

@@ -23,7 +23,7 @@ import { sameSnapshot, } from "../runtime/context/skills.js";
 import { StorageService } from "../storage/storage.service.js";
 /**
  * 技能目录快照（M5 T14，Ruling M17）：运行开始时解析「此刻对这个对话生效的技能」，与日志里最新一份快照不同才写
- * `skills_catalog`。模型看到的目录与 `skill_load` 的名字解析只来自日志，不读实时的库。
+ * `skills_catalog`。模型看到的目录与 `Skill` 的名字解析只来自日志，不读实时的库。
  */
 /**
  * Pinned skill limits (spec §9.1): at most `count` pinned skills per agent, whose current SKILL.md
@@ -303,9 +303,9 @@ export function fitPinned(pinned, log, input) {
 }
 /** `skills_catalog` 的幂等键：每次运行最多写一份。 */
 /**
- * 是否给模型 `skill_load`：日志里有过技能目录快照（Ruling M17），**即使最新一份是空的**。构建请求与执行工具调用
+ * 是否给模型 `Skill`：日志里有过技能目录快照（Ruling M17），**即使最新一份是空的**。构建请求与执行工具调用
  * 用同一判定。不因空快照收回这个工具：工具集合一变缓存前缀就失效；而且 agent 没有别的工具时会发出「没有工具
- * 但历史里有 tool_use」的请求，Anthropic 会拒绝。空目录下调用 skill_load 由 `NO_SKILLS_TEXT` 给出可执行的说明。
+ * 但历史里有 tool_use」的请求，Anthropic 会拒绝。空目录下调用 Skill 由 `NO_SKILLS_TEXT` 给出可执行的说明。
  */
 export function skillLoadOffered(latest, 
 /**
@@ -336,7 +336,7 @@ export const skillsCatalogIdemKey = (runId) => `skills_catalog:${runId}`;
 /**
  * 在调用方事务里锁会话行（与 `EventLog.append` 同一把锁）并读最新一份技能目录快照（没有为 undefined）。
  * `db` is the caller's transaction handle (`KernelDb.db` inside `@Transactional`).
- * 「读最新 → 推出下一份 → 追加」都在这把锁内，别的写快照的事务（运行开始、skill_write、拒绝时的回退）插不进来。
+ * 「读最新 → 推出下一份 → 追加」都在这把锁内，别的写快照的事务（运行开始、SkillWrite、拒绝时的回退）插不进来。
  */
 export async function lockLatestCatalog(db, conversationId) {
     await db

package/dist/skills/changes.service.d.ts

@@ -97,9 +97,9 @@ export interface CancelledDrafts {
 }
 /**
  * agent 自写技能与共享 agent 的技能变更审批（M5 T15，R4）：
- * - `write`（工具 `skill_write` 调用）：私有 agent 直接生成新版本；共享 agent 生成一条待负责人批准的申请，
+ * - `write`（工具 `SkillWrite` 调用）：私有 agent 直接生成新版本；共享 agent 生成一条待负责人批准的申请，
  *   期间只有发起对话试用（`resolveEffectiveSkills` 按对话合并）；两种情况都在同一事务里往发起对话追加一份
- *   技能目录快照（Ruling M17：日志是唯一事实源），同一运行的下一步即可 `skill_load`；
+ *   技能目录快照（Ruling M17：日志是唯一事实源），同一运行的下一步即可 `Skill`；
  * - `decide`（HTTP，只有该 agent 当前的负责人）：批准 → 版本对所有对话生效（各对话下一次运行开始时写新快照）；
  *   拒绝 → 删除草稿对象，发起对话下一次运行开始时目录回到当前版本；
  * - 同一 agent 的同名技能最多一条待处理申请：同一对话再写取代旧的（旧的 cancelled、草稿删除、技能 id 不变），

package/dist/skills/changes.service.js

@@ -22,6 +22,7 @@ import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { sameSnapshot, } from "../runtime/context/skills.js";
 import { StorageService } from "../storage/storage.service.js";
+import { BUILTIN } from "../tools/builtin-names.js";
 import { fitPinned, invocationOf, lockLatestCatalog } from "./catalog.js";
 /**
  * 每个 agent 自己的技能（`scope = agent`）上限，含待批准的新技能。远低于目录快照的上限（`SKILLS_CATALOG_MAX`），
@@ -42,7 +43,7 @@ const AGENT_GONE_TEXT = "This agent no longer exists, so the skill cannot be sav
 const iso = (v) => new Date(v).toISOString();
 const byName = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
 const notFound = () => new ApiError("skill_change.not_found", "Skill change not found");
-/** The body of the SKILL.md a skill_write just stored (as run start would read it); null if unparsable. */
+/** The body of the SKILL.md a SkillWrite just stored (as run start would read it); null if unparsable. */
 function writtenBody(pkg) {
     const md = pkg.files.find((f) => f.path === SKILL_ENTRY_FILE);
     if (!md)
@@ -57,9 +58,9 @@ function writtenBody(pkg) {
 }
 /**
  * agent 自写技能与共享 agent 的技能变更审批（M5 T15，R4）：
- * - `write`（工具 `skill_write` 调用）：私有 agent 直接生成新版本；共享 agent 生成一条待负责人批准的申请，
+ * - `write`（工具 `SkillWrite` 调用）：私有 agent 直接生成新版本；共享 agent 生成一条待负责人批准的申请，
  *   期间只有发起对话试用（`resolveEffectiveSkills` 按对话合并）；两种情况都在同一事务里往发起对话追加一份
- *   技能目录快照（Ruling M17：日志是唯一事实源），同一运行的下一步即可 `skill_load`；
+ *   技能目录快照（Ruling M17：日志是唯一事实源），同一运行的下一步即可 `Skill`；
  * - `decide`（HTTP，只有该 agent 当前的负责人）：批准 → 版本对所有对话生效（各对话下一次运行开始时写新快照）；
  *   拒绝 → 删除草稿对象，发起对话下一次运行开始时目录回到当前版本；
  * - 同一 agent 的同名技能最多一条待处理申请：同一对话再写取代旧的（旧的 cancelled、草稿删除、技能 id 不变），
@@ -245,7 +246,7 @@ let SkillChangesService = class SkillChangesService {
                     files: pkg.manifest.files.length,
                     agentId: ctx.agentId,
                     conversationId: ctx.conversationId,
-                    via: "skill_write",
+                    via: BUILTIN.SkillWrite,
                 },
             });
             outcome = { kind: "version", skillId, version, created: !existing };

package/dist/skills/invocation-keys.d.ts

@@ -2,7 +2,7 @@
  * The SKILL.md invocation keys (package ecosystem phase D) and their lenient reading: readers of
  * stored files (catalog install and upgrade) and the Claude Code translation drop a key the strict
  * `parseSkillMd` checks would refuse, with the reason, instead of refusing the skill or storing an
- * invocation nobody can use. Uploads, native imports and `skill_write` stay strict.
+ * invocation nobody can use. Uploads, native imports and `SkillWrite` stay strict.
  */
 /** The frontmatter keys that make up a skill's invocation metadata. */
 export declare const INVOCATION_KEYS: readonly ["disable-model-invocation", "user-invocable", "context", "agent", "argument-hint", "arguments"];

package/dist/skills/invocation-keys.js

@@ -3,7 +3,7 @@ import { parseSkillMd } from "@capybara-hq/plugin-sdk";
  * The SKILL.md invocation keys (package ecosystem phase D) and their lenient reading: readers of
  * stored files (catalog install and upgrade) and the Claude Code translation drop a key the strict
  * `parseSkillMd` checks would refuse, with the reason, instead of refusing the skill or storing an
- * invocation nobody can use. Uploads, native imports and `skill_write` stay strict.
+ * invocation nobody can use. Uploads, native imports and `SkillWrite` stay strict.
  */
 /** The frontmatter keys that make up a skill's invocation metadata. */
 export const INVOCATION_KEYS = [

package/dist/skills/invoke.d.ts

@@ -121,7 +121,7 @@ export declare class SkillInvoker {
      * `storage.unavailable` (`skill_unreadable`) when the version is gone or its SKILL.md cannot be
      * read, plain `storage.unavailable` when storage is down. `task` renders the text for the
      * sub-agent's effective definition: the shell-injection line only when the sub-agent has
-     * `sandbox_bash` (batch 3 review m1).
+     * `Bash` (batch 3 review m1).
      */
     renderTask(a: {
         orgId: string;

package/dist/skills/invoke.js

@@ -15,6 +15,7 @@ import { KernelDb } from "../infra/database/kernel-db.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { isGeneralAlias, resolveSkillForkType } from "../runtime/subagents/roster.js";
 import { StorageService } from "../storage/storage.service.js";
+import { BUILTIN } from "../tools/builtin-names.js";
 import { findSkillVersion, readSkillFile, SkillIntegrityError, } from "../tools/builtins/skill-load.js";
 import { invocationOf, resolveSkills } from "./catalog.js";
 /** A leading `/<name>` or `/<plugin>:<name>`, then whitespace or the end (spec §3.2). */
@@ -142,10 +143,10 @@ let SkillInvoker = class SkillInvoker {
         const body = await this.readBody(a.orgId, found);
         const others = found.manifest.files.some((f) => f.path !== SKILL_ENTRY_FILE);
         const lines = {
-            // the invocation itself makes the conversation's next run offer skill_load (skillLoadOffered)
+            // the invocation itself makes the conversation's next run offer Skill (skillLoadOffered)
             ...(others && { files: "load" }),
             ...(hasShellInjection(body) &&
-                hasBuiltin(a.agent, "sandbox_bash") && { shellHint: true }),
+                hasBuiltin(a.agent, BUILTIN.Bash) && { shellHint: true }),
         };
         const input = {
             name: a.name,
@@ -192,7 +193,7 @@ let SkillInvoker = class SkillInvoker {
      * `storage.unavailable` (`skill_unreadable`) when the version is gone or its SKILL.md cannot be
      * read, plain `storage.unavailable` when storage is down. `task` renders the text for the
      * sub-agent's effective definition: the shell-injection line only when the sub-agent has
-     * `sandbox_bash` (batch 3 review m1).
+     * `Bash` (batch 3 review m1).
      */
     async renderTask(a) {
         const { skill } = a;
@@ -225,7 +226,7 @@ let SkillInvoker = class SkillInvoker {
             lines: {
                 ...(others && { files: "load" }),
                 ...(hasShellInjection(body) &&
-                    hasBuiltin(child, "sandbox_bash") && { shellHint: true }),
+                    hasBuiltin(child, BUILTIN.Bash) && { shellHint: true }),
             },
             lead: false,
         });

package/dist/tools/approvals.service.d.ts

@@ -1,3 +1,4 @@
+import { type LocalizedName } from "@capybara-hq/plugin-sdk";
 import { EventLog } from "../conversations/event-log.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
@@ -43,6 +44,11 @@ export interface ApprovalView extends ApprovalRecord {
         name: string;
         slug: string;
     } | null;
+    /** An extension tool's plugin (`plugin__<plugin>__<tool>`) and its display name (display only). */
+    extension: {
+        name: string;
+        displayName: LocalizedName;
+    } | null;
     agent: {
         id: string;
         name: string;

package/dist/tools/approvals.service.js

@@ -8,6 +8,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { randomUUID } from "node:crypto";
+import { connectorToolKey, parseToolKey } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { EventLog } from "../conversations/event-log.js";
@@ -19,6 +20,7 @@ import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
 import { ORG_ROLES, roleAtLeast } from "../orgs/roles.js";
+import { pluginDisplayNames } from "./display-names.js";
 export { APPROVAL_DENY_REASON_MAX_CHARS } from "../conversations/events.js";
 /** `list` 一次最多返回的审批数（收件箱据此判断这个来源是否取满）。 */
 export const APPROVALS_LIST_MAX = 100;
@@ -149,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,
                 },
             },
         ]);
@@ -579,12 +583,22 @@ let ApprovalsService = class ApprovalsService {
                 .where("id", "in", connectorIds)
                 .execute();
         const connectorById = new Map(apps.map((a) => [a.id, a]));
+        const pluginOf = (r) => {
+            if (r.connectorId !== null)
+                return null;
+            const p = parseToolKey(r.toolKey);
+            return p?.kind === "extension" ? p.plugin : null;
+        };
+        const displayNames = await pluginDisplayNames(db.db, recs.flatMap((r) => {
+            const p = pluginOf(r);
+            return p === null ? [] : [p];
+        }));
         return recs.flatMap((r) => {
             const c = ctx.get(r.runId);
             if (!c)
                 return [];
             const app = r.connectorId === null ? undefined : connectorById.get(r.connectorId);
-            const prefix = app ? `${app.slug}__` : undefined;
+            const prefix = app ? connectorToolKey(app.slug, "") : undefined;
             return [
                 {
                     ...r,
@@ -592,6 +606,12 @@ let ApprovalsService = class ApprovalsService {
                         ? r.toolKey.slice(prefix.length)
                         : r.toolKey,
                     connector: app ? { id: app.id, name: app.name, slug: app.slug } : null,
+                    extension: (() => {
+                        const p = pluginOf(r);
+                        return p === null
+                            ? null
+                            : { name: p, displayName: displayNames.get(p) ?? { zh: p, en: p } };
+                    })(),
                     agent: { id: c.agent_id, name: names.get(c.agent_id) ?? "" },
                     ...(c.parent_conversation_id !== null
                         ? {

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

@@ -0,0 +1,91 @@
+import type { AgentToolRef } from "../agents/definition.js";
+import type { ToolKind } from "./info.js";
+/**
+ * The names (model-visible keys) of the kernel's builtin tools, following Claude Code (tool naming
+ * spec §4.1). Plain constants: `BuiltinTools`, the tool factories, the registry, policy and the
+ * runtime import them from here. The web keeps its own copy (`apps/web/src/lib/agents.ts`,
+ * `lib/timeline.ts`), checked equal by `test/tools/builtin-names.test.ts`. The release-candidate
+ * names are in `legacy-keys.ts`, never here.
+ */
+export declare const BUILTIN: {
+    readonly Bash: "Bash";
+    readonly Read: "Read";
+    readonly Write: "Write";
+    readonly Edit: "Edit";
+    readonly Glob: "Glob";
+    readonly Grep: "Grep";
+    readonly Deliver: "Deliver";
+    readonly Skill: "Skill";
+    readonly SkillWrite: "SkillWrite";
+    readonly AskUserQuestion: "AskUserQuestion";
+    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. `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[];
+/** 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
+ * registered now, so the order the implementations land in never affects a saved definition.
+ * `SkillWrite` is available only when a definition names it; `ToolSearch` and `Skill` are added
+ * by the registry; `Agent` dispatches sub-agents and its description is built per agent.
+ */
+export declare const BUILTIN_TOOL_NAMES: readonly BuiltinName[];
+/** The builtin that loads a skill (added by the registry when the log has a skills catalog). */
+export declare const SKILL_LOAD: "Skill";
+/** The builtin that searches the tool catalog (added by the registry by org setting and threshold). */
+export declare const TOOL_SEARCH: "ToolSearch";
+/** The builtin that dispatches sub-agents. */
+export declare const AGENT_TOOL: "Agent";
+/**
+ * Tool keys on the spec 3.6 R3 fixed list ("allowed is not confirmed"): their policy is at least
+ * `ask` and remembered grants never let them through. `SkillWrite` changes shared skills.
+ * Connector and extension tools express the same rule with `annotations.requiresUserInteraction`.
+ */
+export declare const R3_FIXED_ASK_TOOL_KEYS: ReadonlySet<string>;
+/**
+ * R3 keys that apply only to shared agents: a private agent's skills are not shared, so its
+ * `SkillWrite` takes effect without asking (R4).
+ */
+export declare const R3_SHARED_AGENT_ONLY_TOOL_KEYS: ReadonlySet<string>;
+/**
+ * Tools a sub-agent never gets (sub-agents spec §5.3, §5.5): `Agent` (depth 1), `AskUserQuestion`
+ * (the person does not see the child), `Deliver` (delivering files is the parent's job) and
+ * `SkillWrite`.
+ */
+export declare const CHILD_REMOVED_TOOLS: readonly ["Agent", "AskUserQuestion", "Deliver", "SkillWrite"];
+/**
+ * The tools of a new agent created without `tools` (`ToolSearch` is added by the registry, never
+ * by a definition). Only for create requests; updates and stored versions get no defaults.
+ */
+export declare const DEFAULT_AGENT_TOOLS: AgentToolRef[];
+/** Kinds of the builtin tools (display only); a builtin missing here is a plain `tool`. */
+export declare const BUILTIN_TOOL_KINDS: Readonly<Record<string, ToolKind>>;
+/**
+ * Input fields left out when matching a replayed call with a recorded one (full-run replay), per
+ * tool: display-only arguments the model writes that do not change what the tool does. `Bash`'s
+ * `description` became required in UI refresh B, so a recording without it and a replayed call
+ * with one (or a different wording) still match.
+ */
+export declare const MATCH_IGNORED_FIELDS: Readonly<Record<string, readonly string[]>>;