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

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

@@ -0,0 +1,73 @@
+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";
+};
+export type BuiltinName = (typeof BUILTIN)[keyof typeof BUILTIN];
+/** The builtin tools that run in the conversation's sandbox. */
+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). */
+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[]>>;

package/dist/tools/builtin-names.js

@@ -0,0 +1,116 @@
+/**
+ * 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 const BUILTIN = {
+    Bash: "Bash",
+    Read: "Read",
+    Write: "Write",
+    Edit: "Edit",
+    Glob: "Glob",
+    Grep: "Grep",
+    Deliver: "Deliver",
+    Skill: "Skill",
+    SkillWrite: "SkillWrite",
+    AskUserQuestion: "AskUserQuestion",
+    ReadToolOutput: "ReadToolOutput",
+    ToolSearch: "ToolSearch",
+    Agent: "Agent",
+};
+/** The builtin tools that run in the conversation's sandbox. */
+export const SANDBOX_TOOL_NAMES = [
+    BUILTIN.Bash,
+    BUILTIN.Read,
+    BUILTIN.Write,
+    BUILTIN.Edit,
+    BUILTIN.Glob,
+    BUILTIN.Grep,
+    BUILTIN.Deliver,
+];
+/** Sandbox tools that need approval when the org setting `sandboxToolPolicy` is `ask` (not the read-only ones). */
+export const SANDBOX_ASK_TOOL_NAMES = new Set([
+    BUILTIN.Bash,
+    BUILTIN.Write,
+    BUILTIN.Edit,
+    BUILTIN.Deliver,
+]);
+/**
+ * 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 const BUILTIN_TOOL_NAMES = [
+    BUILTIN.AskUserQuestion,
+    BUILTIN.ReadToolOutput,
+    BUILTIN.ToolSearch,
+    BUILTIN.Skill,
+    BUILTIN.SkillWrite,
+    ...SANDBOX_TOOL_NAMES,
+    BUILTIN.Agent,
+];
+/** The builtin that loads a skill (added by the registry when the log has a skills catalog). */
+export const SKILL_LOAD = BUILTIN.Skill;
+/** The builtin that searches the tool catalog (added by the registry by org setting and threshold). */
+export const TOOL_SEARCH = BUILTIN.ToolSearch;
+/** The builtin that dispatches sub-agents. */
+export const AGENT_TOOL = BUILTIN.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 const R3_FIXED_ASK_TOOL_KEYS = new Set([BUILTIN.SkillWrite]);
+/**
+ * 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 const R3_SHARED_AGENT_ONLY_TOOL_KEYS = new Set([
+    BUILTIN.SkillWrite,
+]);
+/**
+ * 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 const CHILD_REMOVED_TOOLS = [
+    BUILTIN.Agent,
+    BUILTIN.AskUserQuestion,
+    BUILTIN.Deliver,
+    BUILTIN.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 const DEFAULT_AGENT_TOOLS = [
+    { kind: "builtin", name: BUILTIN.AskUserQuestion },
+    { kind: "builtin", name: BUILTIN.ReadToolOutput },
+];
+/** Kinds of the builtin tools (display only); a builtin missing here is a plain `tool`. */
+export const BUILTIN_TOOL_KINDS = {
+    [BUILTIN.Bash]: "command",
+    [BUILTIN.Read]: "read",
+    [BUILTIN.Write]: "edit",
+    [BUILTIN.Edit]: "edit",
+    [BUILTIN.Glob]: "search",
+    [BUILTIN.Grep]: "search",
+    [BUILTIN.Deliver]: "tool",
+    [BUILTIN.ToolSearch]: "meta",
+    [BUILTIN.Skill]: "meta",
+    [BUILTIN.SkillWrite]: "meta",
+    [BUILTIN.ReadToolOutput]: "meta",
+    [BUILTIN.AskUserQuestion]: "meta",
+};
+/**
+ * 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 const MATCH_IGNORED_FIELDS = {
+    [BUILTIN.Bash]: ["description"],
+};

package/dist/tools/builtins/agent.d.ts

@@ -3,15 +3,15 @@ import { z } from "zod";
 import type { EventPayload } from "../../conversations/events.js";
 import { type RosterEntry } from "../../runtime/subagents/roster.js";
 import type { BuiltinTool } from "../registry.js";
+export { AGENT_TOOL } from "../builtin-names.js";
 /**
- * The `agent` builtin tool (sub-agents spec §4): dispatches a sub-agent. Its description is built
+ * The `Agent` builtin tool (sub-agents spec §4): dispatches a sub-agent. Its description is built
  * per parent agent version from the roster ({@link agentToolSpec}); the tool pipeline handles the
  * call itself (dispatch, suspend, resume), so {@link agentTool}'s `run` is only a guard.
  */
-export declare const AGENT_TOOL = "agent";
 /** How a sub-agent's run ended (`subagent_finished.status`). */
 export type SubagentStatus = EventPayload<"subagent_finished">["status"];
-/** The input of an `agent` call (§4.2). */
+/** The input of an `Agent` call (§4.2). */
 export declare const AgentToolInput: z.ZodObject<{
     description: z.ZodString;
     prompt: z.ZodString;
@@ -26,7 +26,7 @@ export declare const AgentToolInput: z.ZodObject<{
 }, z.core.$strict>;
 export type AgentToolInputT = z.infer<typeof AgentToolInput>;
 /**
- * The `agent` tool definition of a parent agent version (§4.3): the fixed text with
+ * The `Agent` tool definition of a parent agent version (§4.3): the fixed text with
  * `maxConcurrent`, then one line per roster entry in roster order. Built at tool resolution, so the
  * spec hash changes with the roster or the limit (logged per request in `tool_specs`).
  */
@@ -45,7 +45,7 @@ export declare const AGENT_REFUSALS: {
 };
 /**
  * The parent run was stopped while this sub-agent worked (§4.4, §12): the result of a stopped
- * parent's open `agent` call, and the text of a child stopped with its parent.
+ * parent's open `Agent` call, and the text of a child stopped with its parent.
  */
 export declare const AGENT_STOPPED_WITH_RUN_TEXT = "The run was stopped while this sub-agent was working; it was stopped too.";
 /**
@@ -65,7 +65,7 @@ export declare function agentResultText(r: {
     ownModel?: boolean;
     abortedBy?: "user" | "parent";
     /**
-     * Phase D: the report of a person's fork invocation, whose parent need not have the `agent`
+     * Phase D: the report of a person's fork invocation, whose parent need not have the `Agent`
      * tool: the status line leaves out the resume hint (batch 3 review m2).
      */
     noResumeHint?: boolean;
@@ -75,7 +75,7 @@ export declare function agentResultText(r: {
 };
 /**
  * The builtin. `defaultPolicy: "allow"` (§4.6): a sub-agent runs only tools its parent may run,
- * each under its own policy. The tool pipeline dispatches `agent` calls itself; `run` answers only
+ * each under its own policy. The tool pipeline dispatches `Agent` calls itself; `run` answers only
  * when a call reaches it anyway.
  */
 export declare const agentTool: BuiltinTool;

package/dist/tools/builtins/agent.js

@@ -1,12 +1,8 @@
 import { z } from "zod";
 import { ROSTER_DESCRIPTION_MAX } from "../../runtime/subagents/roster.js";
-/**
- * The `agent` builtin tool (sub-agents spec §4): dispatches a sub-agent. Its description is built
- * per parent agent version from the roster ({@link agentToolSpec}); the tool pipeline handles the
- * call itself (dispatch, suspend, resume), so {@link agentTool}'s `run` is only a guard.
- */
-export const AGENT_TOOL = "agent";
-/** The input of an `agent` call (§4.2). */
+import { AGENT_TOOL } from "../builtin-names.js";
+export { AGENT_TOOL } from "../builtin-names.js";
+/** The input of an `Agent` call (§4.2). */
 export const AgentToolInput = z
     .object({
     description: z.string().min(1).max(80),
@@ -86,7 +82,7 @@ function rosterLine(e) {
         : `${line} (the agent "${inert(e.agentName).replaceAll('"', "'")}", with its own tools and model)`;
 }
 /**
- * The `agent` tool definition of a parent agent version (§4.3): the fixed text with
+ * The `Agent` tool definition of a parent agent version (§4.3): the fixed text with
  * `maxConcurrent`, then one line per roster entry in roster order. Built at tool resolution, so the
  * spec hash changes with the roster or the limit (logged per request in `tool_specs`).
  */
@@ -105,7 +101,7 @@ export function agentToolSpec(roster, maxConcurrent) {
  * `agentToolSpec([general-purpose], 4)`.
  */
 const SPEC = {
-    name: "agent",
+    name: "Agent",
     description: "Dispatch a sub-agent: a fresh agent with its own context that works on one task and returns its " +
         "final reply as this tool's result. The sub-agent sees only your prompt, not this conversation, so " +
         "include everything it needs and say what its final reply must contain. It shares your sandbox " +
@@ -134,7 +130,7 @@ export const AGENT_REFUSALS = {
 };
 /**
  * The parent run was stopped while this sub-agent worked (§4.4, §12): the result of a stopped
- * parent's open `agent` call, and the text of a child stopped with its parent.
+ * parent's open `Agent` call, and the text of a child stopped with its parent.
  */
 export const AGENT_STOPPED_WITH_RUN_TEXT = "The run was stopped while this sub-agent was working; it was stopped too.";
 /** `12345` → `12,345` (no locale data involved, so the text is the same on every replica). */
@@ -210,7 +206,7 @@ export function agentResultText(r) {
 }
 /**
  * The builtin. `defaultPolicy: "allow"` (§4.6): a sub-agent runs only tools its parent may run,
- * each under its own policy. The tool pipeline dispatches `agent` calls itself; `run` answers only
+ * each under its own policy. The tool pipeline dispatches `Agent` calls itself; `run` answers only
  * when a call reaches it anyway.
  */
 export const agentTool = {

package/dist/tools/builtins/ask-user.d.ts

@@ -18,7 +18,7 @@ export declare function questionsForm(questions: Question[]): InputForm;
 /** 答案 → 给模型的结果文本：`User answered: "<question>" = "<answer>"; …`。 */
 export declare function answerText(questions: Question[], answer: FormAnswer): string;
 /**
- * 内置工具 `ask_user`：用通用的输入请求机制实现——首次调用返回 `input_required`，
+ * 内置工具 `AskUserQuestion`：用通用的输入请求机制实现——首次调用返回 `input_required`，
  * 内核暂停运行并展示表单；用户回答（或超时）后用同一 input 再次调用，按 `ctx.resume` 生成结果。
  * 默认 allow（提问本身就是让用户参与，不再审批）。
  */

package/dist/tools/builtins/ask-user.js

@@ -1,6 +1,6 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
 const SPEC = {
-    name: "ask_user",
+    name: "AskUserQuestion",
     description: "Ask the user one or more multiple-choice questions and wait for the answers. Use it when you " +
         "need the user's preference or decision to continue, or when a request is ambiguous; do not use " +
         "it for questions you can answer yourself. Each question has a short header, 2-4 options with a " +
@@ -103,7 +103,7 @@ const text = (t, zh, en) => ({
     display: { summary: { zh, en } },
 });
 /**
- * 内置工具 `ask_user`：用通用的输入请求机制实现——首次调用返回 `input_required`，
+ * 内置工具 `AskUserQuestion`：用通用的输入请求机制实现——首次调用返回 `input_required`，
  * 内核暂停运行并展示表单；用户回答（或超时）后用同一 input 再次调用，按 `ctx.resume` 生成结果。
  * 默认 allow（提问本身就是让用户参与，不再审批）。
  */

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

@@ -9,9 +9,9 @@ import { ToolOutputs } from "../outputs.js";
 import type { BuiltinTool } from "../registry.js";
 /**
  * The kernel's builtin tools, built once from the injected services (their specs: names,
- * descriptions and schemas, are the factories' own and unchanged). `tool_search` and `skill_load`
+ * descriptions and schemas, are the factories' own and unchanged). `ToolSearch` and `Skill`
  * are added to a run by the registry (`forAgent`: organization setting and threshold, a skills
- * catalog snapshot), not by agent definitions; `skill_write` only when a definition names it.
+ * catalog snapshot), not by agent definitions; `SkillWrite` only when a definition names it.
  */
 export declare class BuiltinTools {
     private readonly tools;

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

@@ -25,9 +25,9 @@ import { skillWriteTool } from "./skill-write.js";
 import { toolSearchTool } from "./tool-search.js";
 /**
  * The kernel's builtin tools, built once from the injected services (their specs: names,
- * descriptions and schemas, are the factories' own and unchanged). `tool_search` and `skill_load`
+ * descriptions and schemas, are the factories' own and unchanged). `ToolSearch` and `Skill`
  * are added to a run by the registry (`forAgent`: organization setting and threshold, a skills
- * catalog snapshot), not by agent definitions; `skill_write` only when a definition names it.
+ * catalog snapshot), not by agent definitions; `SkillWrite` only when a definition names it.
  */
 let BuiltinTools = class BuiltinTools {
     tools;

package/dist/tools/builtins/read-tool-output.d.ts

@@ -11,7 +11,7 @@ export declare function readPage(id: string, content: string, opts: {
     charOffset: number;
     budget: number;
 }): string;
-/** 内置工具 `read_tool_output`：读本会话未过期的输出存档（只读、默认 allow）。 */
+/** 内置工具 `ReadToolOutput`：读本会话未过期的输出存档（只读、默认 allow）。 */
 export declare function readToolOutputTool(deps: {
     outputs: Pick<ToolOutputs, "load">;
     config: Pick<KernelConfigService, "get">;

package/dist/tools/builtins/read-tool-output.js

@@ -8,7 +8,7 @@ const DEFAULT_LIMIT = 200;
  */
 const FOOTER_RESERVE = 200;
 const SPEC = {
-    name: "read_tool_output",
+    name: "ReadToolOutput",
     description: "Read a saved tool output by its id, page by page. Large tool results are truncated in the " +
         "conversation and saved in full; the truncation notice gives the output id. Lines are numbered " +
         "from 0. Each call returns up to `limit` lines starting at line `offset`, capped at a maximum " +
@@ -85,7 +85,7 @@ export function readPage(id, content, opts) {
     const footer = `[Lines ${offset}–${last} of ${total}]`;
     return [parts.join("\n"), ...(cut === null ? [] : [cut]), footer].join("\n");
 }
-/** 内置工具 `read_tool_output`：读本会话未过期的输出存档（只读、默认 allow）。 */
+/** 内置工具 `ReadToolOutput`：读本会话未过期的输出存档（只读、默认 allow）。 */
 export function readToolOutputTool(deps) {
     return {
         spec: SPEC,

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

@@ -1,16 +1,16 @@
-import { type ExecResult } from "@capybara-hq/plugin-sdk";
+import type { ExecResult } from "@capybara-hq/plugin-sdk";
 import type { BuiltinTool } from "../../registry.js";
 import { type SandboxToolDeps } from "./common.js";
-/** 不给 `timeoutSeconds` 时的命令超时（秒），不超过 `sandbox.limits.maxCommandSeconds`。 */
+/** The command timeout in seconds when `timeout` is not given, at most `sandbox.limits.maxCommandSeconds`. */
 export declare const BASH_DEFAULT_TIMEOUT_SECONDS = 120;
 /** The longest `description` (the shell row shows it instead of the command). */
 export declare const BASH_DESCRIPTION_MAX_CHARS = 120;
-/** bash 结果超过这么多字符即转存（走现有输出存档，模型用 read_tool_output 分页读）。 */
+/** bash 结果超过这么多字符即转存（走现有输出存档，模型用 ReadToolOutput 分页读）。 */
 export declare const BASH_SPILL_CHARS = 30000;
 /**
  * 命令结果 → 给模型的文本。`budgetClamped`：运行的时限把超时收紧到了 `seconds`（Ruling M20），超时说明改为
- * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeoutSeconds。
+ * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeout。
  */
 export declare function formatExec(r: ExecResult, seconds: number, budgetClamped?: boolean): string;
-/** 内置工具 `sandbox_bash`：在本对话的沙箱里执行命令。 */
+/** 内置工具 `Bash`：在本对话的沙箱里执行命令。 */
 export declare function sandboxBashTool(deps: SandboxToolDeps): BuiltinTool;

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

@@ -1,15 +1,14 @@
-import { ToolError } from "@capybara-hq/plugin-sdk";
 import { clip, display, inSandbox, runBudgetNote, runTimeLeftMs, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
-/** 不给 `timeoutSeconds` 时的命令超时（秒），不超过 `sandbox.limits.maxCommandSeconds`。 */
+/** The command timeout in seconds when `timeout` is not given, at most `sandbox.limits.maxCommandSeconds`. */
 export const BASH_DEFAULT_TIMEOUT_SECONDS = 120;
 /** The longest `description` (the shell row shows it instead of the command). */
 export const BASH_DESCRIPTION_MAX_CHARS = 120;
-/** bash 结果超过这么多字符即转存（走现有输出存档，模型用 read_tool_output 分页读）。 */
+/** bash 结果超过这么多字符即转存（走现有输出存档，模型用 ReadToolOutput 分页读）。 */
 export const BASH_SPILL_CHARS = 30_000;
 /** 一次命令最多收集的输出字节（stdout + stderr）；超出的丢弃并在结果里说明。 */
 const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
 const SPEC = {
-    name: "sandbox_bash",
+    name: "Bash",
     // Display only (the tool row; not in the fingerprint, never sent to the model).
     keyArgs: ["command"],
     description: "Run a shell command (bash) in this conversation's sandbox, an isolated Linux machine. " +
@@ -20,10 +19,10 @@ const SPEC = {
         "Files the user attached to the conversation are under /workspace/attachments, " +
         "and skill files under /skills (read-only). Each call runs in a fresh shell (no state such as " +
         "cd or environment variables carries over). The result has stdout, stderr and the exit code; " +
-        "long output is saved and can be paged with read_tool_output. A command that runs longer than " +
-        "timeoutSeconds is stopped. Prefer sandbox_read, sandbox_write, sandbox_edit, sandbox_glob and " +
-        "sandbox_grep for reading, writing and searching files. To give a file to the user, use " +
-        "sandbox_deliver. Other sub-agents of this conversation may run commands in this sandbox at " +
+        "long output is saved and can be paged with ReadToolOutput. A command that runs longer than " +
+        "timeout milliseconds is stopped. Prefer Read, Write, Edit, Glob and " +
+        "Grep for reading, writing and searching files. To give a file to the user, use " +
+        "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.",
     inputSchema: {
@@ -40,21 +39,21 @@ const SPEC = {
                 maxLength: BASH_DESCRIPTION_MAX_CHARS,
                 description: 'What this command does, in a few words (e.g. "Generate the final PDF"). Shown to the user.',
             },
-            timeoutSeconds: {
+            timeout: {
                 type: "integer",
                 minimum: 1,
-                description: `Seconds before the command is stopped. Default ${BASH_DEFAULT_TIMEOUT_SECONDS}; the deployment sets a maximum (7200 by default).`,
+                description: `Milliseconds before the command is stopped. Default ${BASH_DEFAULT_TIMEOUT_SECONDS * 1000}; the deployment sets a maximum (7200000 by default); a larger value is lowered to it.`,
             },
         },
         required: ["command", "description"],
         additionalProperties: false,
     },
 };
-/** 本次命令的超时（秒）：给定的值，或默认值（不超过上限）。 */
-const secondsFor = (input, max) => input.timeoutSeconds ?? Math.min(BASH_DEFAULT_TIMEOUT_SECONDS, max);
+/** This command's timeout in milliseconds: the given value or the default, at most the maximum. */
+const msFor = (input, maxSeconds) => Math.min(input.timeout ?? BASH_DEFAULT_TIMEOUT_SECONDS * 1000, maxSeconds * 1000);
 /**
  * 命令结果 → 给模型的文本。`budgetClamped`：运行的时限把超时收紧到了 `seconds`（Ruling M20），超时说明改为
- * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeoutSeconds。
+ * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeout。
  */
 export function formatExec(r, seconds, budgetClamped = false) {
     const parts = [];
@@ -68,7 +67,7 @@ export function formatExec(r, seconds, budgetClamped = false) {
         parts.push(`[timedOut: the command did not finish within ${seconds}s and was stopped. ${runBudgetNote(seconds)} The sandbox is still usable; split the work into shorter steps that save progress to files under /workspace, or run long jobs in the background and check on them in a later run.]`);
     }
     else if (r.timedOut) {
-        parts.push(`[timedOut: the command did not finish within ${seconds}s and was stopped. The sandbox is still usable; pass a larger timeoutSeconds (up to the deployment maximum), or split the work into shorter steps that save progress to files under /workspace.]`);
+        parts.push(`[timedOut: the command did not finish within ${seconds}s and was stopped. The sandbox is still usable; pass a larger timeout in milliseconds (up to the deployment maximum), or split the work into shorter steps that save progress to files under /workspace.]`);
     }
     else if (r.exitCode === null) {
         parts.push("[The command was stopped before it finished; its effects may be partial. Check the sandbox state before retrying.]");
@@ -80,7 +79,7 @@ export function formatExec(r, seconds, budgetClamped = false) {
     }
     return parts.join("\n");
 }
-/** 内置工具 `sandbox_bash`：在本对话的沙箱里执行命令。 */
+/** 内置工具 `Bash`：在本对话的沙箱里执行命令。 */
 export function sandboxBashTool(deps) {
     return {
         spec: SPEC,
@@ -91,33 +90,37 @@ export function sandboxBashTool(deps) {
         timeoutMs: (input) => {
             const cfg = deps.config.get();
             const max = cfg.sandbox.limits.maxCommandSeconds;
-            return Math.min(secondsFor(input, max), max) * 1000 + sandboxBaseTimeoutMs(cfg);
+            return msFor(input, max) + sandboxBaseTimeoutMs(cfg);
         },
         async run(input, ctx) {
             const { command, description } = input;
             const max = deps.config.get().sandbox.limits.maxCommandSeconds;
-            const req = input.timeoutSeconds;
-            if (req !== undefined && req > max) {
-                throw new ToolError(`timeoutSeconds ${req} is over the limit of ${max} seconds; pass a value of at most ${max}.`);
-            }
-            const asked = secondsFor(input, max);
-            // 运行截止前命令要自己超时（Ruling M20）：在拿到沙箱之后算，等锁与恢复用掉的时间一并扣掉
-            let seconds = asked;
+            const requested = input.timeout;
+            const maxMs = max * 1000;
+            const askedMs = msFor(input, max);
+            // The run's deadline makes the command time out itself first (Ruling M20): counted after the
+            // sandbox is obtained, so the time spent waiting for the lock and resuming is deducted
+            let ms = askedMs;
             const { value: r, notices } = await inSandbox(deps, ctx, ({ h, p, signal }) => {
-                const left = Math.floor(runTimeLeftMs(ctx.runDeadline) / 1000);
-                seconds = Math.max(1, Math.min(asked, left));
+                const left = Math.floor(runTimeLeftMs(ctx.runDeadline) / 1000) * 1000;
+                ms = Math.max(1000, Math.min(askedMs, left));
                 return p.exec(h, {
                     command,
                     cwd: "/workspace",
-                    timeoutMs: seconds * 1000,
+                    timeoutMs: ms,
                     maxOutputBytes: MAX_OUTPUT_BYTES,
                     signal,
                 });
             });
-            const clamped = seconds < asked;
+            const seconds = ms / 1000;
+            const clamped = ms < askedMs;
             const shown = clip(command, 120);
+            const lowered = requested !== undefined && requested > maxMs
+                ? `\n[timeout ${requested} ms is over the deployment maximum; it was lowered to ${maxMs} ms.]`
+                : "";
+            const text = formatExec(r, seconds, clamped) + lowered;
             return {
-                content: [{ type: "text", text: withNotices(notices, formatExec(r, seconds, clamped)) }],
+                content: [{ type: "text", text: withNotices(notices, text) }],
                 isError: r.timedOut || r.exitCode === null,
                 // display only: a non-zero exit shows as failed on the row, `isError` stays as it was
                 view: {

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

@@ -12,8 +12,8 @@ export interface SandboxToolDeps {
     sandbox: Pick<SandboxService, "available" | "withSandbox"> & Partial<Pick<SandboxService, "pathLease">>;
     attachments: Pick<AttachmentsService, "listForConversation" | "openForConversation">;
     storage: Pick<StorageService, "kernel" | "available">;
-    /** `publishChanged`: `sandbox_deliver` announces `changed: files` (UI refresh B). */
-    eventLog: Pick<EventLog, "append"> & Partial<Pick<EventLog, "publishChanged">>;
+    /** `publishChanged`: `Deliver` announces `changed: files` (UI refresh B). */
+    eventLog: Pick<EventLog, "append" | "latestFileState"> & Partial<Pick<EventLog, "publishChanged">>;
     config: Pick<KernelConfigService, "get">;
 }
 /** 回调拿到的沙箱：句柄、提供方与「调用 signal + 锁丢失」合并后的 signal（每个提供方调用都传它）。 */
@@ -80,7 +80,7 @@ export declare function clip(s: string, max: number): string;
 export declare function withNotices(notices: readonly string[], text: string): string;
 /** 校验沙箱内路径（`validateSandboxPath`）；不合法抛给模型可执行的错误。 */
 export declare function checkPath(path: string, field?: string): string;
-/** 写入类工具的路径：`/skills` 是技能文件的只读副本。 */
+/** A writing tool's `file_path`: `/skills` is the read-only copy of the skill files. */
 export declare function checkWritable(path: string): string;
 /** POSIX shell 单引号转义。 */
 export declare function shellQuote(s: string): string;

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

@@ -78,9 +78,9 @@ export function checkPath(path, field = "path") {
     }
     return path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
 }
-/** 写入类工具的路径：`/skills` 是技能文件的只读副本。 */
+/** A writing tool's `file_path`: `/skills` is the read-only copy of the skill files. */
 export function checkWritable(path) {
-    const p = checkPath(path);
+    const p = checkPath(path, "file_path");
     if (p === "/skills" || p.startsWith("/skills/")) {
         throw new ToolError(`Path ${clip(p, 200)} is read-only (/skills holds skill files); pass a path under /workspace or /tmp instead.`);
     }

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

@@ -1,5 +1,5 @@
 import type { BuiltinTool } from "../../registry.js";
 import { type SandboxToolDeps } from "./common.js";
 export declare function contentTypeFor(name: string): string;
-/** 内置工具 `sandbox_deliver`：把沙箱里的文件存进对象存储，写 `artifact_created`，用户可下载。 */
+/** 内置工具 `Deliver`：把沙箱里的文件存进对象存储，写 `artifact_created`，用户可下载。 */
 export declare function sandboxDeliverTool(deps: SandboxToolDeps): BuiltinTool;