@armadra/agent 0.4.0 → 0.5.1

package/dist/plan/prompts.js

@@ -0,0 +1,89 @@
+/**
+ * plan 模式注入给模型的文本（docs/wave5-plan.md §6.2、D18）。[W5-F]
+ *
+ * 全部以 `custom_message`（`display:false`）追加在尾部，投影成 user 消息，不碰 system 节与工具表
+ * （design §9.1）。文本是给模型看的，用英文；界面文案不在这里。
+ */
+export const PLAN_MODE_TYPE = "ama.plan_mode";
+export const PLAN_MODE_EXIT_TYPE = "ama.plan_mode_exit";
+export const PLAN_APPROVED_TYPE = "ama.plan_approved";
+/** 完整版（约 400 token）：进入 plan 后首个提示、每第 5 次提醒、压缩之后。 */
+export const PLAN_MODE_FULL = `Plan mode is active. You may read and search, run read-only shell commands (ls, cat, grep, rg, find, git status/log/show/diff, …) and start read-only subagents with task. Do not modify files, run builds or tests, or change any state; write/execute tools are refused in this mode.
+
+How to work:
+1. Explore first. Answer questions from the repository yourself instead of asking the user; ask only about decisions that the code cannot settle.
+2. When you are ready, write the plan as one block, with the tags on their own lines:
+
+<proposed_plan>
+# <title>
+
+## Background
+1–3 sentences: the goal and the key facts you found.
+
+## Steps
+- [ ] S1 <action> (files: path/a.ts)
+- [ ] S2 <action> [depends: S1] [agent: <name>]
+
+## Verification
+- <command or check>
+
+## Assumptions and risks
+- <defaults you chose for open questions>
+</proposed_plan>
+
+Rules for the plan:
+- Make it specific enough that someone else could carry it out without making further decisions. List the key files; describe a repeated change once.
+- Always include a Verification section.
+- At most one <proposed_plan> block per reply; to revise, rewrite the whole block.
+- Do not ask "is this OK?" in prose: the plan block itself is shown to the user for approval.
+- If the user asks you to make changes while plan mode is active, treat it as a request to plan how to make them.
+- Do not use the todo tool to record the plan; the task list is created from the steps when the plan is approved.`;
+/** 简版：两次完整版之间每 5 个提示一次。 */
+export const PLAN_MODE_BRIEF = "Plan mode is still active: read-only exploration only. Finish with a <proposed_plan> block (Background, Steps as - [ ] S1 …, Verification, Assumptions and risks).";
+/** 手动退出 plan（没有获批的计划）。 */
+export const PLAN_MODE_EXIT = "Plan mode has ended. The read-only restrictions no longer apply; the current permission mode decides what you may do.";
+/** 获批交接时开启新回合的用户消息（之后紧跟 `ama.plan_approved`）。 */
+export const PLAN_APPROVED_PROMPT = "The plan is approved. Go ahead.";
+/**
+ * 提醒节奏：plan 模式下第 n 个提示（从 1 起）。每 5 个提示提醒一次（第 1、6、11 … 个），
+ * 第 1、6、11 … 次提醒里每第 5 次用完整版（即第 1、26、51 … 个提示）。
+ */
+export function reminderKind(promptIndex) {
+    if (promptIndex < 1 || (promptIndex - 1) % 5 !== 0)
+        return undefined;
+    const reminder = (promptIndex - 1) / 5;
+    return reminder % 5 === 0 ? "full" : "brief";
+}
+const DONE_MARKER_HINT = "When you finish a step, write `[DONE:<step id>]` (for example `[DONE:S1]`) on its own line in your reply so progress can be tracked.";
+/** 交接消息：计划已批准 + plan 模式结束 + 计划全文 + 文件路径 + 进度记法。 */
+export function planApprovedText(plan, options = { todoTool: true }) {
+    const lines = [
+        "The user approved the plan below. Plan mode has ended: you may now edit files and run commands as the current permission mode allows.",
+    ];
+    if (plan.steps.length > 0) {
+        lines.push(options.todoTool
+            ? "The todo list has been created from the plan steps (the first step is in progress). Work through it in order and mark each step with todo update as soon as it is done."
+            : `Work through the plan steps in order. ${DONE_MARKER_HINT}`);
+    }
+    if (plan.filePath !== undefined)
+        lines.push(`Plan file: ${plan.filePath}`);
+    lines.push("", "<approved_plan>", plan.markdown, "</approved_plan>");
+    return lines.join("\n");
+}
+/** 「批准，在新上下文执行」：新会话的首条用户消息。 */
+export function freshContextPrompt(plan, options = { todoTool: true }) {
+    const lines = [
+        "Carry out the approved plan below. It was written in an earlier session that you cannot see; the plan is self-contained.",
+    ];
+    if (plan.steps.length > 0)
+        lines.push(options.todoTool
+            ? "Track progress with the todo tool: mark each step with todo update when done."
+            : DONE_MARKER_HINT);
+    if (plan.filePath !== undefined)
+        lines.push(`Plan file: ${plan.filePath}`);
+    lines.push("", "<approved_plan>", plan.markdown, "</approved_plan>");
+    return lines.join("\n");
+}
+export function planMessage(customType, content) {
+    return { role: "custom", customType, content, display: false, timestamp: Date.now() };
+}

package/dist/plan/store.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 计划的持久化：会话条目的读取与计划文件导出（docs/wave5-plan.md §6.3）。[W5-F]
+ *
+ * - 权威数据在会话 JSONL：`custom{ama.plan}`（只追加：状态变化再记一条，同 id 取分支上最后一条）、
+ *   `custom{ama.plan_state}`（进入 / 退出 plan）。
+ * - 文件只作导出：缺省 `<dataDir>/plans/<sessionId>-v<N>.md`；`plan.directory` 可指到项目内
+ *   （相对路径按项目根解析，必须在项目根之内，否则 warning 回落缺省）。由 ama 进程写，不经工具调用。
+ */
+import type { PlanData, PlanStateData, TodoItemView } from "../agent/types.js";
+import type { PermissionMode } from "../permissions/types.js";
+import type { SessionEntry } from "../session/types.js";
+export declare const PLAN_CUSTOM_TYPE = "ama.plan";
+export declare const PLAN_STATE_CUSTOM_TYPE = "ama.plan_state";
+/**
+ * `ama.plan_state` 的落盘形状：契约 `PlanStateData` 加两项可选的本地字段，记下进入 plan 时切走的
+ * 执行模型（`plan.model` 配置时），resume 后批准仍能切回。读到旧条目时缺省。
+ */
+export interface PlanStateRecord extends PlanStateData {
+    executionModel?: string;
+    executionThinking?: string;
+}
+/** 分支上最后一条 `ama.plan`（任意状态）；`planId` 给定时取该计划的最后一条。 */
+export declare function latestPlan(branch: readonly SessionEntry[], planId?: string): PlanData | undefined;
+/** 分支上已用过的最大版本号（文件名 `-v<N>` 在会话内单调）。 */
+export declare function maxPlanVersion(branch: readonly SessionEntry[]): number;
+export declare function latestPlanState(branch: readonly SessionEntry[]): PlanStateRecord | undefined;
+/** 分支上的当前 todo 清单（RPC `get_todos`、`todo_updated` 事件）。 */
+export declare function currentTodos(branch: readonly SessionEntry[]): TodoItemView[];
+/** 批准时的执行模式：显式指定 > 进入 plan 前的模式；进入前就是 plan 时用 default。 */
+export declare function executionMode(requested: PermissionMode | undefined, prePlanMode: PermissionMode | undefined): PermissionMode;
+/** 计划文件目录：`plan.directory` 在项目根之内才用，否则 warning 回落 `<dataDir>/plans`。 */
+export declare function resolvePlanDirectory(configured: string | undefined, projectRoot: string, dataDir: string): {
+    dir: string;
+    warning?: string;
+};
+/** 写 `<dir>/<sessionId>-v<N>.md`，返回绝对路径。 */
+export declare function writePlanFile(dir: string, sessionId: string, version: number, markdown: string): string;

package/dist/plan/store.js

@@ -0,0 +1,90 @@
+/**
+ * 计划的持久化：会话条目的读取与计划文件导出（docs/wave5-plan.md §6.3）。[W5-F]
+ *
+ * - 权威数据在会话 JSONL：`custom{ama.plan}`（只追加：状态变化再记一条，同 id 取分支上最后一条）、
+ *   `custom{ama.plan_state}`（进入 / 退出 plan）。
+ * - 文件只作导出：缺省 `<dataDir>/plans/<sessionId>-v<N>.md`；`plan.directory` 可指到项目内
+ *   （相对路径按项目根解析，必须在项目根之内，否则 warning 回落缺省）。由 ama 进程写，不经工具调用。
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { TODO_CUSTOM_TYPE, parseTodoState } from "../tools/todo.js";
+export const PLAN_CUSTOM_TYPE = "ama.plan";
+export const PLAN_STATE_CUSTOM_TYPE = "ama.plan_state";
+function customData(entry, customType) {
+    return entry.type === "custom" && entry.customType === customType ? entry.data : undefined;
+}
+function isPlanData(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.id === "string" &&
+        typeof v.version === "number" &&
+        typeof v.markdown === "string" &&
+        Array.isArray(v.steps));
+}
+/** 分支上最后一条 `ama.plan`（任意状态）；`planId` 给定时取该计划的最后一条。 */
+export function latestPlan(branch, planId) {
+    for (let i = branch.length - 1; i >= 0; i--) {
+        const data = customData(branch[i], PLAN_CUSTOM_TYPE);
+        if (isPlanData(data) && (planId === undefined || data.id === planId))
+            return data;
+    }
+    return undefined;
+}
+/** 分支上已用过的最大版本号（文件名 `-v<N>` 在会话内单调）。 */
+export function maxPlanVersion(branch) {
+    let max = 0;
+    for (const entry of branch) {
+        const data = customData(entry, PLAN_CUSTOM_TYPE);
+        if (isPlanData(data))
+            max = Math.max(max, data.version);
+    }
+    return max;
+}
+export function latestPlanState(branch) {
+    for (let i = branch.length - 1; i >= 0; i--) {
+        const data = customData(branch[i], PLAN_STATE_CUSTOM_TYPE);
+        if (typeof data === "object" &&
+            data !== null &&
+            typeof data.active === "boolean")
+            return data;
+    }
+    return undefined;
+}
+/** 分支上的当前 todo 清单（RPC `get_todos`、`todo_updated` 事件）。 */
+export function currentTodos(branch) {
+    for (let i = branch.length - 1; i >= 0; i--) {
+        const entry = branch[i];
+        if (entry.type === "custom" && entry.customType === TODO_CUSTOM_TYPE)
+            return parseTodoState(entry.data).items;
+    }
+    return [];
+}
+/** 批准时的执行模式：显式指定 > 进入 plan 前的模式；进入前就是 plan 时用 default。 */
+export function executionMode(requested, prePlanMode) {
+    const mode = requested ?? prePlanMode ?? "default";
+    return mode === "plan" ? "default" : mode;
+}
+/** 计划文件目录：`plan.directory` 在项目根之内才用，否则 warning 回落 `<dataDir>/plans`。 */
+export function resolvePlanDirectory(configured, projectRoot, dataDir) {
+    const fallback = join(dataDir, "plans");
+    if (configured === undefined || configured.trim() === "")
+        return { dir: fallback };
+    const dir = resolve(projectRoot, configured);
+    const rel = relative(resolve(projectRoot), dir);
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+        return {
+            dir: fallback,
+            warning: `plan.directory ${configured} 不在项目根 ${projectRoot} 之内，计划文件改写到 ${fallback}`,
+        };
+    }
+    return { dir };
+}
+/** 写 `<dir>/<sessionId>-v<N>.md`，返回绝对路径。 */
+export function writePlanFile(dir, sessionId, version, markdown) {
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, `${sessionId}-v${version}.md`);
+    writeFileSync(file, markdown.endsWith("\n") ? markdown : `${markdown}\n`, "utf8");
+    return file;
+}

package/dist/rpc.d.ts

@@ -6,16 +6,27 @@
  * - 设计只列了命令名；参数形状按 v1 §8.4 补全，新增命令（get_available_thinking_levels、
  *   set_auto_retry、abort_retry、get_fork_messages、set_permission_mode、get_commands、
  *   get_skills）按名字含义补全。
+ * - [RW-B] 回滚：get_rewind_points → `{ points }`、rewind → `RewindResult`（形状见
+ *   checkpoints/types.ts）、summarize_from → `{ leafId, draft, summary? }`、summarize_up_to →
+ *   `CompactionResult`；成功回滚发 `session_rewound` 事件。
  * - 线上事件 = 进程内 `SessionEvent`，但 `message_update` 换成纯增量（去掉 partial / 累计消息，
  *   附最新 usage）；stream-json 输出同一形状。
  * - 类型定义直接放在本文件（B6 实现 import 它），避免子路径入口依赖实现文件。
+ * - [W5-C0] 第五波（docs/wave5-plan.md §6.5、§7.5）：命令 `plan_response / get_plan / get_todos /
+ *   get_tasks / get_agents`（返回形状见 `RpcW5Results`），客户端能力 `plans`（声明后计划审批交客户端）；
+ *   新事件由 `SessionEvent` 派生自动包含。命令实现归 W5-F（C0 时返回 `not_implemented`），
+ *   `RPC_PROTOCOL_VERSION` 不变。
  */
 import type { AssistantEvent, ImageBlock, ModelThinkingLevel, Usage } from "./ai/types.js";
-import type { QueueMode, SessionEvent } from "./agent/types.js";
+import type { PlanData, PlanDecisionKind, QueueMode, SessionEvent, TodoItemView } from "./agent/types.js";
+import type { AgentInfo } from "./agents/types.js";
+import type { TaskInfo } from "./tools/types.js";
+import type { RewindRequest } from "./checkpoints/types.js";
 import type { ApprovalDecision, PermissionMode } from "./permissions/types.js";
 export type { SessionEvent } from "./agent/types.js";
 export declare const RPC_PROTOCOL_VERSION: 1;
-export type RpcCapability = "approvals" | "images" | "hooks";
+/** `plans`（W5-C0）：客户端声明后计划审批交给客户端（`plan_proposed` → `plan_response`）。 */
+export type RpcCapability = "approvals" | "images" | "hooks" | "plans";
 export interface RpcHello {
     type: "hello";
     protocolVersion: typeof RPC_PROTOCOL_VERSION;
@@ -89,6 +100,16 @@ export interface RpcCommandMap {
         name: string;
     };
     get_fork_messages: NoParams;
+    get_rewind_points: NoParams;
+    rewind: RewindRequest;
+    summarize_from: {
+        entryId: string;
+        instructions?: string;
+    };
+    summarize_up_to: {
+        entryId: string;
+        instructions?: string;
+    };
     set_client_capabilities: {
         capabilities: RpcCapability[];
     };
@@ -105,6 +126,41 @@ export interface RpcCommandMap {
     };
     get_commands: NoParams;
     get_skills: NoParams;
+    plan_response: RpcPlanResponse;
+    get_plan: {
+        planId?: string;
+    };
+    get_todos: NoParams;
+    get_tasks: NoParams;
+    get_agents: NoParams;
+}
+/** [W5-C0] 计划审批的回答（与 `permission_response` 同构）。 */
+export interface RpcPlanResponse {
+    planId: string;
+    decision: PlanDecisionKind;
+    /** `approve` 时指定执行模式（缺省回到进入 plan 前的模式）。 */
+    mode?: PermissionMode;
+    /** `revise`：修改意见（作为普通 user 消息，留在 plan）。 */
+    feedback?: string;
+    /** 客户端改过的计划全文（version + 1）。 */
+    editedMarkdown?: string;
+}
+/** [W5-C0] 第五波命令成功时的 `data` 形状。 */
+export interface RpcW5Results {
+    plan_response: {
+        planId: string;
+        decision: PlanDecisionKind;
+    };
+    get_plan: PlanData | null;
+    get_todos: {
+        items: TodoItemView[];
+    };
+    get_tasks: {
+        tasks: TaskInfo[];
+    };
+    get_agents: {
+        agents: AgentInfo[];
+    };
 }
 export type RpcCommandType = keyof RpcCommandMap;
 /** `{ id?, type, ...参数 }`。 */

package/dist/rpc.js

@@ -6,8 +6,15 @@
  * - 设计只列了命令名；参数形状按 v1 §8.4 补全，新增命令（get_available_thinking_levels、
  *   set_auto_retry、abort_retry、get_fork_messages、set_permission_mode、get_commands、
  *   get_skills）按名字含义补全。
+ * - [RW-B] 回滚：get_rewind_points → `{ points }`、rewind → `RewindResult`（形状见
+ *   checkpoints/types.ts）、summarize_from → `{ leafId, draft, summary? }`、summarize_up_to →
+ *   `CompactionResult`；成功回滚发 `session_rewound` 事件。
  * - 线上事件 = 进程内 `SessionEvent`，但 `message_update` 换成纯增量（去掉 partial / 累计消息，
  *   附最新 usage）；stream-json 输出同一形状。
  * - 类型定义直接放在本文件（B6 实现 import 它），避免子路径入口依赖实现文件。
+ * - [W5-C0] 第五波（docs/wave5-plan.md §6.5、§7.5）：命令 `plan_response / get_plan / get_todos /
+ *   get_tasks / get_agents`（返回形状见 `RpcW5Results`），客户端能力 `plans`（声明后计划审批交客户端）；
+ *   新事件由 `SessionEvent` 派生自动包含。命令实现归 W5-F（C0 时返回 `not_implemented`），
+ *   `RPC_PROTOCOL_VERSION` 不变。
  */
 export const RPC_PROTOCOL_VERSION = 1;

package/dist/sandbox/bash.d.ts

@@ -0,0 +1,74 @@
+/**
+ * bash 的 OS 沙箱（docs/sandbox.md「第二阶段」）：配置 → 会话内固定的沙箱设定，以及每次调用的策略。
+ *
+ * - 生效条件：`sandbox.bash: auto` 且探测到能限制写入的沙箱（sandbox-exec / bwrap；`unshare` 只隔离网络，
+ *   不算）。不生效时 bash 原样运行、权限照旧；
+ * - 每次调用的策略：可写 = 会话工作区 + 系统临时目录（POSIX 另加 `/tmp`）+ ama 的输出目录 +
+ *   `sandbox.writable`；工作区里 `.ama/`、`.git/hooks`、`.git/config` 仍只读（防止借 Hook / 配置 / git
+ *   钩子在沙箱外执行）；凭据目录与 ama 的 `auth.json` 不可读；网络按 `sandbox.network`；
+ * - 设定在组装时算一次（探测结果进程内缓存），同一会话内不变：工具描述与 schema 逐字节稳定（设计 §9.1）。
+ *
+ * 只依赖 `node:` 内置模块与本目录。
+ */
+import type { OsSandboxStatus } from "./detect.js";
+import type { OsSandboxPolicy } from "./profile.js";
+import { type WrappedCommand } from "./wrap.js";
+export type BashSandboxMode = "auto" | "off";
+export type SandboxNetwork = "deny" | "allow";
+export declare const DEFAULT_BASH_SANDBOX_MODE: BashSandboxMode;
+export declare const DEFAULT_SANDBOX_NETWORK: SandboxNetwork;
+/** 配置 `sandbox` 段里与 bash 有关的键（结构与 config/types.ts 的 SandboxConfig 相容）。 */
+export interface BashSandboxConfig {
+    bash?: BashSandboxMode;
+    network?: SandboxNetwork;
+    writable?: readonly string[];
+}
+export interface BashSandbox {
+    /** 命令将经 OS 沙箱运行（不传 `sandbox: false` 时）。 */
+    active: boolean;
+    status: OsSandboxStatus;
+    network: SandboxNetwork;
+    /** `sandbox.writable` 展开 `~` 后的绝对路径。 */
+    writable: string[];
+    /** 不可读的路径（凭据目录 / 文件）。 */
+    hidden: string[];
+    /** 人读说明（doctor / config show）。 */
+    detail: string;
+}
+export declare const NO_BASH_SANDBOX: BashSandbox;
+/** 用户主目录下的凭据路径（与 permissions/protected.ts 的机密路径同一批）。 */
+export declare const HIDDEN_HOME_PATHS: readonly [".ssh", ".gnupg", ".aws", ".kube", ".docker/config.json", ".config/gcloud", ".netrc", ".pgpass", ".git-credentials"];
+/** 工作区里沙箱内仍只读的路径。 */
+export declare const WORKSPACE_READ_ONLY: readonly [".ama", ".git/hooks", ".git/config"];
+/** `~` / `~/x` 展开；其余相对路径不认（返回 undefined）。 */
+export declare function expandHome(path: string, home: string): string | undefined;
+export interface ResolveBashSandboxDeps {
+    status: OsSandboxStatus;
+    home?: string;
+    /** 额外不可读的文件（ama 的 auth.json）。 */
+    hidden?: readonly string[];
+}
+export declare function resolveBashSandbox(config: BashSandboxConfig | undefined, deps: ResolveBashSandboxDeps): BashSandbox;
+export interface BashCallPlace {
+    /** 会话工作区（会话 cwd）。 */
+    workspace: string;
+    /** ama 的输出目录（截断全文、后台输出）。 */
+    outputDir?: string;
+    /** 测试注入：系统临时目录。 */
+    tmpdir?: string;
+    platform?: NodeJS.Platform;
+}
+/** 一次 bash 调用的沙箱策略（路径未 realpath，wrapCommand 再解析）。 */
+export declare function bashSandboxPolicy(sandbox: BashSandbox, place: BashCallPlace): OsSandboxPolicy;
+/** 调用参数里显式要求不经沙箱（`sandbox: false`）。 */
+export declare function wantsUnsandboxed(input: unknown): boolean;
+/** 这次调用会不会经沙箱运行（权限管线与 bash 工具共用，保证两边结论一致）。 */
+export declare function runsSandboxed(sandbox: BashSandbox | undefined, input: unknown): boolean;
+/**
+ * 包装 shell 命令行；设定生效但没能包上（不应发生）时抛错——权限管线已按「在沙箱内」放行，不能悄悄裸跑。
+ */
+export declare function wrapBashCommand(sandbox: BashSandbox, shell: string, args: readonly string[], place: BashCallPlace): WrappedCommand;
+/** 失败输出看起来像被沙箱拒绝（写入被拒；网络拒绝时另看联网失败）。 */
+export declare function looksLikeSandboxDenial(output: string, networkDenied: boolean): boolean;
+/** 沙箱拒绝时追加给模型的一行说明。 */
+export declare function sandboxDenialHint(networkDenied: boolean): string;

package/dist/sandbox/bash.js

@@ -0,0 +1,126 @@
+/**
+ * bash 的 OS 沙箱（docs/sandbox.md「第二阶段」）：配置 → 会话内固定的沙箱设定，以及每次调用的策略。
+ *
+ * - 生效条件：`sandbox.bash: auto` 且探测到能限制写入的沙箱（sandbox-exec / bwrap；`unshare` 只隔离网络，
+ *   不算）。不生效时 bash 原样运行、权限照旧；
+ * - 每次调用的策略：可写 = 会话工作区 + 系统临时目录（POSIX 另加 `/tmp`）+ ama 的输出目录 +
+ *   `sandbox.writable`；工作区里 `.ama/`、`.git/hooks`、`.git/config` 仍只读（防止借 Hook / 配置 / git
+ *   钩子在沙箱外执行）；凭据目录与 ama 的 `auth.json` 不可读；网络按 `sandbox.network`；
+ * - 设定在组装时算一次（探测结果进程内缓存），同一会话内不变：工具描述与 schema 逐字节稳定（设计 §9.1）。
+ *
+ * 只依赖 `node:` 内置模块与本目录。
+ */
+import { homedir, tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { wrapCommand } from "./wrap.js";
+export const DEFAULT_BASH_SANDBOX_MODE = "off";
+export const DEFAULT_SANDBOX_NETWORK = "deny";
+export const NO_BASH_SANDBOX = Object.freeze({
+    active: false,
+    status: Object.freeze({
+        kind: "none",
+        isolatesNetwork: false,
+        restrictsWrites: false,
+        detail: "未配置",
+    }),
+    network: DEFAULT_SANDBOX_NETWORK,
+    writable: [],
+    hidden: [],
+    detail: "未配置",
+});
+/** 用户主目录下的凭据路径（与 permissions/protected.ts 的机密路径同一批）。 */
+export const HIDDEN_HOME_PATHS = [
+    ".ssh",
+    ".gnupg",
+    ".aws",
+    ".kube",
+    ".docker/config.json",
+    ".config/gcloud",
+    ".netrc",
+    ".pgpass",
+    ".git-credentials",
+];
+/** 工作区里沙箱内仍只读的路径。 */
+export const WORKSPACE_READ_ONLY = [".ama", ".git/hooks", ".git/config"];
+/** `~` / `~/x` 展开；其余相对路径不认（返回 undefined）。 */
+export function expandHome(path, home) {
+    if (path === "~")
+        return home;
+    if (path.startsWith("~/"))
+        return join(home, path.slice(2));
+    return isAbsolute(path) ? resolve(path) : undefined;
+}
+export function resolveBashSandbox(config, deps) {
+    const home = deps.home ?? homedir();
+    const mode = config?.bash ?? DEFAULT_BASH_SANDBOX_MODE;
+    const network = config?.network ?? DEFAULT_SANDBOX_NETWORK;
+    const writable = [];
+    for (const raw of config?.writable ?? []) {
+        const path = expandHome(raw, home);
+        if (path !== undefined && !writable.includes(path))
+            writable.push(path);
+    }
+    const hidden = [...HIDDEN_HOME_PATHS.map((p) => join(home, p)), ...(deps.hidden ?? [])];
+    const status = deps.status;
+    const usable = status.kind === "sandbox-exec" || status.kind === "bwrap";
+    const active = mode === "auto" && usable && status.restrictsWrites;
+    let detail;
+    if (mode === "off")
+        detail = "关闭（sandbox.bash: off）";
+    else if (!active)
+        detail =
+            status.kind === "unshare"
+                ? "不可用：unshare 只隔离网络、不能限制写入"
+                : `不可用：${status.detail}`;
+    else
+        detail =
+            `${status.kind}，网络 ${network}，可写：工作区、临时目录、输出目录` +
+                (writable.length > 0 ? `、${writable.join("、")}` : "");
+    return { active, status, network, writable, hidden, detail };
+}
+/** 一次 bash 调用的沙箱策略（路径未 realpath，wrapCommand 再解析）。 */
+export function bashSandboxPolicy(sandbox, place) {
+    const writable = [place.workspace, place.tmpdir ?? tmpdir()];
+    if ((place.platform ?? process.platform) !== "win32")
+        writable.push("/tmp");
+    if (place.outputDir !== undefined)
+        writable.push(place.outputDir);
+    writable.push(...sandbox.writable);
+    return {
+        network: sandbox.network,
+        writable,
+        readOnly: WORKSPACE_READ_ONLY.map((p) => join(place.workspace, p)),
+        hiddenDirs: [...sandbox.hidden],
+    };
+}
+/** 调用参数里显式要求不经沙箱（`sandbox: false`）。 */
+export function wantsUnsandboxed(input) {
+    return (typeof input === "object" &&
+        input !== null &&
+        input["sandbox"] === false);
+}
+/** 这次调用会不会经沙箱运行（权限管线与 bash 工具共用，保证两边结论一致）。 */
+export function runsSandboxed(sandbox, input) {
+    return sandbox?.active === true && !wantsUnsandboxed(input);
+}
+/**
+ * 包装 shell 命令行；设定生效但没能包上（不应发生）时抛错——权限管线已按「在沙箱内」放行，不能悄悄裸跑。
+ */
+export function wrapBashCommand(sandbox, shell, args, place) {
+    const wrapped = wrapCommand(sandbox.status, shell, args, bashSandboxPolicy(sandbox, place));
+    if (!wrapped.sandboxed || !wrapped.writesRestricted)
+        throw new Error(`sandbox: could not wrap the command with ${sandbox.status.kind}`);
+    return wrapped;
+}
+const WRITE_DENIAL = /Operation not permitted|Read-only file system|\bEPERM\b|\bEROFS\b|Permission denied|\bEACCES\b/i;
+const NETWORK_DENIAL = /Could not resolve host|\bENOTFOUND\b|\bEAI_AGAIN\b|getaddrinfo|nodename nor servname|Temporary failure in name resolution|Name or service not known|Network is unreachable|\bENETUNREACH\b|Couldn't connect to server|Failed to connect|\bECONNREFUSED\b|Could not resolve hostname/i;
+/** 失败输出看起来像被沙箱拒绝（写入被拒；网络拒绝时另看联网失败）。 */
+export function looksLikeSandboxDenial(output, networkDenied) {
+    return WRITE_DENIAL.test(output) || (networkDenied && NETWORK_DENIAL.test(output));
+}
+/** 沙箱拒绝时追加给模型的一行说明。 */
+export function sandboxDenialHint(networkDenied) {
+    return ("[sandbox: this command ran in ama's OS sandbox (writes only in the workspace and temp dirs" +
+        (networkDenied ? ", no network" : "") +
+        "). If it failed because of that, rerun it with sandbox:false, which needs the user's approval.]");
+}

package/dist/sandbox/detect.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 操作系统沙箱能力探测（docs/sandbox.md「探测与降级」）。
+ *
+ * - 「存在」不等于「可用」（嵌套在别的沙箱里、容器里没有用户命名空间）：用目标配置跑一次最小探针，退出码 0
+ *   才算可用；
+ * - macOS：`/usr/bin/sandbox-exec`；Linux：PATH 里的 `bwrap`，失败再试 `unshare -r -n`（只隔离网络）；
+ *   其它平台：none；
+ * - 开关：`sandbox.enabled: off` 或环境变量 `AMA_SANDBOX=off`；
+ * - 结果在进程内缓存（按开关分两份）；`configureOsSandbox` 记下组装根读到的配置，供拿不到配置的只读调用方
+ *   （状态栏）得到一致的结论。
+ */
+import { type OsSandboxKind } from "./profile.js";
+export type SandboxEnabled = "auto" | "off";
+export interface OsSandboxStatus {
+    kind: OsSandboxKind | "none";
+    /** 沙箱程序的绝对路径（kind 不是 none 时）。 */
+    path?: string;
+    /** 能拒绝网络。 */
+    isolatesNetwork: boolean;
+    /** 能把写入限制在指定目录（unshare 不能）。 */
+    restrictsWrites: boolean;
+    /** 人读说明（中文，给 doctor / config show）。 */
+    detail: string;
+}
+export declare const NO_OS_SANDBOX: OsSandboxStatus;
+export declare const SANDBOX_EXEC_PATH = "/usr/bin/sandbox-exec";
+export declare const PROBE_TIMEOUT_MS = 5000;
+export interface ProbeDeps {
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    /** 可执行文件存在且可执行。 */
+    isExecutable(path: string): boolean;
+    /** 同步运行，返回退出码（启动失败 / 超时 / 被信号杀 → null）。 */
+    run(command: string, args: readonly string[]): number | null;
+}
+export declare const REAL_PROBE_DEPS: ProbeDeps;
+/** 在 PATH 里找可执行文件（按目标平台的路径规则）。 */
+export declare function findExecutable(name: string, env: NodeJS.ProcessEnv, check: (path: string) => boolean, platform?: NodeJS.Platform): string | undefined;
+/** 生效的开关：环境变量 `AMA_SANDBOX=off` 优先于配置。 */
+export declare function resolveSandboxEnabled(configured: SandboxEnabled | undefined, env?: NodeJS.ProcessEnv): SandboxEnabled;
+/** 不缓存的探测（测试注入 deps）。 */
+export declare function probeOsSandbox(enabled: SandboxEnabled, deps?: ProbeDeps): OsSandboxStatus;
+/** 组装根读到配置后记下（拿不到配置的只读调用方据此得到一致结论）；返回生效的状态。 */
+export declare function configureOsSandbox(enabled: SandboxEnabled | undefined): OsSandboxStatus;
+/** 进程内缓存的探测结果；不传开关时用 `configureOsSandbox` 记下的配置（缺省 auto）。 */
+export declare function osSandboxStatus(enabled?: SandboxEnabled | undefined): OsSandboxStatus;
+/** 测试用：清空缓存与记下的配置。 */
+export declare function resetOsSandboxForTests(): void;