@armadra/agent 0.4.0 → 0.5.1

package/dist/sandbox/detect.js

@@ -0,0 +1,149 @@
+/**
+ * 操作系统沙箱能力探测（docs/sandbox.md「探测与降级」）。
+ *
+ * - 「存在」不等于「可用」（嵌套在别的沙箱里、容器里没有用户命名空间）：用目标配置跑一次最小探针，退出码 0
+ *   才算可用；
+ * - macOS：`/usr/bin/sandbox-exec`；Linux：PATH 里的 `bwrap`，失败再试 `unshare -r -n`（只隔离网络）；
+ *   其它平台：none；
+ * - 开关：`sandbox.enabled: off` 或环境变量 `AMA_SANDBOX=off`；
+ * - 结果在进程内缓存（按开关分两份）；`configureOsSandbox` 记下组装根读到的配置，供拿不到配置的只读调用方
+ *   （状态栏）得到一致的结论。
+ */
+import { spawnSync } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { posix, win32 } from "node:path";
+import { buildBwrapArgs, buildSbplProfile, buildUnshareArgs, } from "./profile.js";
+export const NO_OS_SANDBOX = Object.freeze({
+    kind: "none",
+    isolatesNetwork: false,
+    restrictsWrites: false,
+    detail: "没有可用的操作系统沙箱",
+});
+export const SANDBOX_EXEC_PATH = "/usr/bin/sandbox-exec";
+export const PROBE_TIMEOUT_MS = 5000;
+/** 探针用的策略：拒绝网络、不可写——与 codemode 实际使用的最严配置相同。 */
+const PROBE_POLICY = { network: "deny", writable: [] };
+function isExecutable(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export const REAL_PROBE_DEPS = {
+    platform: process.platform,
+    env: process.env,
+    isExecutable,
+    run(command, args) {
+        const result = spawnSync(command, args, {
+            stdio: "ignore",
+            timeout: PROBE_TIMEOUT_MS,
+            env: { PATH: process.env["PATH"] ?? "/usr/bin:/bin" },
+        });
+        return result.error !== undefined ? null : result.status;
+    },
+};
+/** 在 PATH 里找可执行文件（按目标平台的路径规则）。 */
+export function findExecutable(name, env, check, platform = process.platform) {
+    const path = platform === "win32" ? win32 : posix;
+    for (const dir of (env["PATH"] ?? "").split(path.delimiter)) {
+        if (dir === "")
+            continue;
+        const candidate = path.join(dir, name);
+        if (check(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** 生效的开关：环境变量 `AMA_SANDBOX=off` 优先于配置。 */
+export function resolveSandboxEnabled(configured, env = process.env) {
+    const fromEnv = env["AMA_SANDBOX"]?.trim().toLowerCase();
+    if (fromEnv === "off" || fromEnv === "0" || fromEnv === "false")
+        return "off";
+    return configured ?? "auto";
+}
+/** 不缓存的探测（测试注入 deps）。 */
+export function probeOsSandbox(enabled, deps = REAL_PROBE_DEPS) {
+    if (enabled === "off")
+        return { ...NO_OS_SANDBOX, detail: "已关闭（sandbox.enabled: off 或 AMA_SANDBOX=off）" };
+    if (deps.platform === "darwin") {
+        if (!deps.isExecutable(SANDBOX_EXEC_PATH))
+            return { ...NO_OS_SANDBOX, detail: `没有 ${SANDBOX_EXEC_PATH}` };
+        const code = deps.run(SANDBOX_EXEC_PATH, [
+            "-p",
+            buildSbplProfile(PROBE_POLICY),
+            "/usr/bin/true",
+        ]);
+        if (code === 0)
+            return {
+                kind: "sandbox-exec",
+                path: SANDBOX_EXEC_PATH,
+                isolatesNetwork: true,
+                restrictsWrites: true,
+                detail: "macOS sandbox-exec",
+            };
+        return {
+            ...NO_OS_SANDBOX,
+            detail: `sandbox-exec 探针失败（${code === null ? "无法启动" : `退出码 ${code}`}；可能已在别的沙箱里）`,
+        };
+    }
+    if (deps.platform === "linux") {
+        const failures = [];
+        const bwrap = findExecutable("bwrap", deps.env, deps.isExecutable, deps.platform);
+        if (bwrap !== undefined) {
+            const code = deps.run(bwrap, [...buildBwrapArgs(PROBE_POLICY), "true"]);
+            if (code === 0)
+                return {
+                    kind: "bwrap",
+                    path: bwrap,
+                    isolatesNetwork: true,
+                    restrictsWrites: true,
+                    detail: "Linux bubblewrap",
+                };
+            failures.push(`bwrap 探针失败（${code === null ? "无法启动" : `退出码 ${code}`}）`);
+        }
+        else
+            failures.push("没有 bwrap");
+        const unshare = findExecutable("unshare", deps.env, deps.isExecutable, deps.platform);
+        if (unshare !== undefined) {
+            const code = deps.run(unshare, [...buildUnshareArgs(), "true"]);
+            if (code === 0)
+                return {
+                    kind: "unshare",
+                    path: unshare,
+                    isolatesNetwork: true,
+                    restrictsWrites: false,
+                    detail: `Linux unshare -r -n（只隔离网络；${failures.join("，")}）`,
+                };
+            failures.push(`unshare 探针失败（${code === null ? "无法启动" : `退出码 ${code}`}；可能不允许非特权用户命名空间）`);
+        }
+        else
+            failures.push("没有 unshare");
+        return { ...NO_OS_SANDBOX, detail: failures.join("，") };
+    }
+    return { ...NO_OS_SANDBOX, detail: `${deps.platform} 上没有操作系统沙箱实现` };
+}
+const cache = new Map();
+let configured;
+/** 组装根读到配置后记下（拿不到配置的只读调用方据此得到一致结论）；返回生效的状态。 */
+export function configureOsSandbox(enabled) {
+    configured = enabled;
+    return osSandboxStatus(enabled);
+}
+/** 进程内缓存的探测结果；不传开关时用 `configureOsSandbox` 记下的配置（缺省 auto）。 */
+export function osSandboxStatus(enabled = configured) {
+    const effective = resolveSandboxEnabled(enabled);
+    let status = cache.get(effective);
+    if (status === undefined) {
+        status = probeOsSandbox(effective);
+        cache.set(effective, status);
+    }
+    return status;
+}
+/** 测试用：清空缓存与记下的配置。 */
+export function resetOsSandboxForTests() {
+    cache.clear();
+    configured = undefined;
+}

package/dist/sandbox/index.d.ts

@@ -0,0 +1,5 @@
+/** 操作系统级沙箱（docs/sandbox.md）：探测、参数生成与命令包装。 */
+export { NO_OS_SANDBOX, configureOsSandbox, osSandboxStatus, probeOsSandbox, resetOsSandboxForTests, resolveSandboxEnabled, type OsSandboxStatus, type ProbeDeps, type SandboxEnabled, } from "./detect.js";
+export { buildBwrapArgs, buildSbplProfile, buildUnshareArgs, type OsSandboxKind, type OsSandboxPolicy, } from "./profile.js";
+export { resolveExtras, resolveWritable, wrapCommand, type WrappedCommand } from "./wrap.js";
+export { DEFAULT_BASH_SANDBOX_MODE, DEFAULT_SANDBOX_NETWORK, NO_BASH_SANDBOX, bashSandboxPolicy, looksLikeSandboxDenial, resolveBashSandbox, runsSandboxed, sandboxDenialHint, wantsUnsandboxed, wrapBashCommand, type BashCallPlace, type BashSandbox, type BashSandboxConfig, type BashSandboxMode, type SandboxNetwork, } from "./bash.js";

package/dist/sandbox/index.js

@@ -0,0 +1,5 @@
+/** 操作系统级沙箱（docs/sandbox.md）：探测、参数生成与命令包装。 */
+export { NO_OS_SANDBOX, configureOsSandbox, osSandboxStatus, probeOsSandbox, resetOsSandboxForTests, resolveSandboxEnabled, } from "./detect.js";
+export { buildBwrapArgs, buildSbplProfile, buildUnshareArgs, } from "./profile.js";
+export { resolveExtras, resolveWritable, wrapCommand } from "./wrap.js";
+export { DEFAULT_BASH_SANDBOX_MODE, DEFAULT_SANDBOX_NETWORK, NO_BASH_SANDBOX, bashSandboxPolicy, looksLikeSandboxDenial, resolveBashSandbox, runsSandboxed, sandboxDenialHint, wantsUnsandboxed, wrapBashCommand, } from "./bash.js";

package/dist/sandbox/profile.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 操作系统沙箱的参数生成（docs/sandbox.md「各平台实现」）：纯函数，不探测、不读文件系统。
+ *
+ * - `buildSbplProfile`：macOS `sandbox-exec -p` 的 SBPL 配置；
+ * - `buildBwrapArgs`：Linux bubblewrap 的参数（到 `--` 为止）；
+ * - `buildUnshareArgs`：Linux `unshare -r -n`（只隔离网络）。
+ *
+ * 路径由调用方先取 realpath（wrap.ts）；这里只做转义与校验。
+ */
+export type OsSandboxKind = "sandbox-exec" | "bwrap" | "unshare";
+export interface OsSandboxPolicy {
+    /** deny：拒绝一切网络（含 Unix 域套接字与 DNS）。 */
+    network: "deny" | "allow";
+    /** 允许写入的目录（绝对路径，已 realpath）；其余位置一律不可写。 */
+    writable: readonly string[];
+    /** 可写目录里仍然只读的路径（已 realpath；bash 用：项目 `.ama/`、`.git/hooks`、`.git/config`）。 */
+    readOnly?: readonly string[];
+    /** 不可读的目录（已 realpath；bash 用：`~/.ssh` 等凭据目录）。 */
+    hiddenDirs?: readonly string[];
+    /** 不可读的文件（已 realpath；bash 用：`~/.netrc`、ama 的 `auth.json` 等）。 */
+    hiddenFiles?: readonly string[];
+}
+/** 沙箱里始终可写的设备文件（stdio 是继承的描述符，不经路径检查）。 */
+export declare const SBPL_DEVICE_WRITES: readonly ["/dev/null", "/dev/zero", "/dev/tty", "/dev/dtracehelper"];
+/** 含控制字符的路径不进配置（SBPL 字符串 / 命令行里都难以安全表达）。 */
+export declare function assertSafePath(path: string): void;
+/** SBPL 字符串字面量：转义反斜杠与双引号。 */
+export declare function sbplString(value: string): string;
+export declare function buildSbplProfile(policy: OsSandboxPolicy): string;
+/** bwrap 参数（不含可执行文件与目标命令）：只读根 + 最小 /dev + 可写目录逐个绑回。 */
+export declare function buildBwrapArgs(policy: OsSandboxPolicy): string[];
+/** unshare 参数（不含可执行文件与目标命令）：只隔离网络，不限制写入。 */
+export declare function buildUnshareArgs(): string[];

package/dist/sandbox/profile.js

@@ -0,0 +1,76 @@
+/**
+ * 操作系统沙箱的参数生成（docs/sandbox.md「各平台实现」）：纯函数，不探测、不读文件系统。
+ *
+ * - `buildSbplProfile`：macOS `sandbox-exec -p` 的 SBPL 配置；
+ * - `buildBwrapArgs`：Linux bubblewrap 的参数（到 `--` 为止）；
+ * - `buildUnshareArgs`：Linux `unshare -r -n`（只隔离网络）。
+ *
+ * 路径由调用方先取 realpath（wrap.ts）；这里只做转义与校验。
+ */
+/** 沙箱里始终可写的设备文件（stdio 是继承的描述符，不经路径检查）。 */
+export const SBPL_DEVICE_WRITES = [
+    "/dev/null",
+    "/dev/zero",
+    "/dev/tty",
+    "/dev/dtracehelper",
+];
+/** 含控制字符的路径不进配置（SBPL 字符串 / 命令行里都难以安全表达）。 */
+export function assertSafePath(path) {
+    // eslint-disable-next-line no-control-regex
+    if (path === "" || /[\u0000-\u001f\u007f]/.test(path))
+        throw new Error(`sandbox: unsupported path ${JSON.stringify(path)}`);
+}
+/** SBPL 字符串字面量：转义反斜杠与双引号。 */
+export function sbplString(value) {
+    assertSafePath(value);
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+export function buildSbplProfile(policy) {
+    const lines = ["(version 1)", "(allow default)"];
+    if (policy.network === "deny") {
+        lines.push("(deny network*)");
+        // DNS 经 mDNSResponder：Unix 套接字已被 network* 拒绝，mach 服务也拒绝，堵住经 DNS 查询外带数据。
+        lines.push('(deny mach-lookup (global-name "com.apple.dnssd.service"))');
+    }
+    lines.push("(deny file-write*)");
+    for (const dir of policy.writable)
+        lines.push(`(allow file-write* (subpath ${sbplString(dir)}))`);
+    const devices = SBPL_DEVICE_WRITES.map((d) => `(literal ${sbplString(d)})`).join(" ");
+    lines.push(`(allow file-write* ${devices} (regex #"^/dev/fd/"))`);
+    // SBPL 后出现的规则优先：只读与不可读放在最后，覆盖前面的允许。
+    for (const path of policy.readOnly ?? [])
+        lines.push(`(deny file-write* (subpath ${sbplString(path)}))`);
+    for (const path of [...(policy.hiddenDirs ?? []), ...(policy.hiddenFiles ?? [])])
+        lines.push(`(deny file-read* file-write* (subpath ${sbplString(path)}))`);
+    return lines.join("\n");
+}
+/** bwrap 参数（不含可执行文件与目标命令）：只读根 + 最小 /dev + 可写目录逐个绑回。 */
+export function buildBwrapArgs(policy) {
+    const args = ["--die-with-parent", "--ro-bind", "/", "/", "--dev", "/dev"];
+    if (policy.network === "deny")
+        args.push("--unshare-net");
+    for (const dir of policy.writable) {
+        assertSafePath(dir);
+        args.push("--bind", dir, dir);
+    }
+    // 之后的挂载盖住前面的：只读路径重新只读绑定，不可读目录换成空 tmpfs、文件换成 /dev/null。
+    // bwrap 只能挂到已存在的路径上，调用方只传存在的。
+    for (const path of policy.readOnly ?? []) {
+        assertSafePath(path);
+        args.push("--ro-bind", path, path);
+    }
+    for (const dir of policy.hiddenDirs ?? []) {
+        assertSafePath(dir);
+        args.push("--tmpfs", dir);
+    }
+    for (const file of policy.hiddenFiles ?? []) {
+        assertSafePath(file);
+        args.push("--ro-bind", "/dev/null", file);
+    }
+    args.push("--");
+    return args;
+}
+/** unshare 参数（不含可执行文件与目标命令）：只隔离网络，不限制写入。 */
+export function buildUnshareArgs() {
+    return ["-r", "-n", "--"];
+}

package/dist/sandbox/wrap.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 包装命令行（docs/sandbox.md「分层」）：输入命令、参数与策略 → 输出经 OS 沙箱启动的命令行。使用方自己
+ * spawn（进程组、stdio、环境都不变）。
+ *
+ * - 可写目录取 realpath（SBPL 按真实路径匹配，macOS 的 /tmp、/var 是符号链接；bwrap 绑定也要求存在），
+ *   不存在的丢弃；
+ * - `unshare` 只能隔离网络：策略要求联网时等于不包装；
+ * - `none`：原样返回（调用方按 `sandboxed: false` 决定是否继续）；
+ * - 只读路径（`readOnly`）：存在的取 realpath；不存在的按「父目录 realpath + 名字」只给 SBPL（挡住新建），
+ *   bwrap 只能挂到已存在的路径，跳过；不可读路径（`hiddenDirs` / `hiddenFiles`）只保留存在的，并按实际
+ *   类型重新归类（bwrap 对目录挂 tmpfs、对文件挂 /dev/null）。
+ */
+import type { OsSandboxStatus } from "./detect.js";
+import { type OsSandboxPolicy } from "./profile.js";
+export interface WrappedCommand {
+    command: string;
+    args: string[];
+    /** 实际经 OS 沙箱启动。 */
+    sandboxed: boolean;
+    /** 本次包装拒绝了网络。 */
+    networkDenied: boolean;
+    /** 本次包装把写入限制在 `writable`。 */
+    writesRestricted: boolean;
+}
+/** 可写目录 → realpath，去掉不存在的与重复的。 */
+export declare function resolveWritable(dirs: readonly string[], realpath?: (path: string) => string): string[];
+/** 解析只读与不可读路径（见文件头）。`missingOk`：不存在的只读路径按父目录解析保留（SBPL）。 */
+export declare function resolveExtras(policy: OsSandboxPolicy, missingOk: boolean, realpath?: (path: string) => string, isDir?: (path: string) => boolean): Pick<OsSandboxPolicy, "readOnly" | "hiddenDirs" | "hiddenFiles">;
+export declare function wrapCommand(status: Pick<OsSandboxStatus, "kind" | "path">, command: string, args: readonly string[], policy: OsSandboxPolicy, realpath?: (path: string) => string, isDir?: (path: string) => boolean): WrappedCommand;

package/dist/sandbox/wrap.js

@@ -0,0 +1,117 @@
+/**
+ * 包装命令行（docs/sandbox.md「分层」）：输入命令、参数与策略 → 输出经 OS 沙箱启动的命令行。使用方自己
+ * spawn（进程组、stdio、环境都不变）。
+ *
+ * - 可写目录取 realpath（SBPL 按真实路径匹配，macOS 的 /tmp、/var 是符号链接；bwrap 绑定也要求存在），
+ *   不存在的丢弃；
+ * - `unshare` 只能隔离网络：策略要求联网时等于不包装；
+ * - `none`：原样返回（调用方按 `sandboxed: false` 决定是否继续）；
+ * - 只读路径（`readOnly`）：存在的取 realpath；不存在的按「父目录 realpath + 名字」只给 SBPL（挡住新建），
+ *   bwrap 只能挂到已存在的路径，跳过；不可读路径（`hiddenDirs` / `hiddenFiles`）只保留存在的，并按实际
+ *   类型重新归类（bwrap 对目录挂 tmpfs、对文件挂 /dev/null）。
+ */
+import { realpathSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { buildBwrapArgs, buildSbplProfile, buildUnshareArgs, } from "./profile.js";
+/** 可写目录 → realpath，去掉不存在的与重复的。 */
+export function resolveWritable(dirs, realpath = realpathSync) {
+    const out = [];
+    for (const dir of dirs) {
+        let real;
+        try {
+            real = realpath(dir);
+        }
+        catch {
+            continue;
+        }
+        if (!out.includes(real))
+            out.push(real);
+    }
+    return out;
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** 解析只读与不可读路径（见文件头）。`missingOk`：不存在的只读路径按父目录解析保留（SBPL）。 */
+export function resolveExtras(policy, missingOk, realpath = realpathSync, isDir = isDirectory) {
+    const readOnly = [];
+    for (const path of policy.readOnly ?? []) {
+        let real;
+        try {
+            real = realpath(path);
+        }
+        catch {
+            if (missingOk) {
+                try {
+                    real = join(realpath(dirname(path)), basename(path));
+                }
+                catch {
+                    real = undefined;
+                }
+            }
+        }
+        if (real !== undefined && !readOnly.includes(real))
+            readOnly.push(real);
+    }
+    const hidden = resolveWritable([...(policy.hiddenDirs ?? []), ...(policy.hiddenFiles ?? [])], realpath);
+    const out = {};
+    if (readOnly.length > 0)
+        out.readOnly = readOnly;
+    const dirs = hidden.filter((p) => isDir(p));
+    const files = hidden.filter((p) => !dirs.includes(p));
+    if (dirs.length > 0)
+        out.hiddenDirs = dirs;
+    if (files.length > 0)
+        out.hiddenFiles = files;
+    return out;
+}
+export function wrapCommand(status, command, args, policy, realpath, isDir) {
+    const plain = {
+        command,
+        args: [...args],
+        sandboxed: false,
+        networkDenied: false,
+        writesRestricted: false,
+    };
+    if (status.kind === "none" || status.path === undefined)
+        return plain;
+    const resolved = {
+        network: policy.network,
+        writable: resolveWritable(policy.writable, realpath),
+        ...resolveExtras(policy, status.kind === "sandbox-exec", realpath, isDir),
+    };
+    const networkDenied = policy.network === "deny";
+    switch (status.kind) {
+        case "sandbox-exec":
+            return {
+                command: status.path,
+                args: ["-p", buildSbplProfile(resolved), command, ...args],
+                sandboxed: true,
+                networkDenied,
+                writesRestricted: true,
+            };
+        case "bwrap":
+            return {
+                command: status.path,
+                args: [...buildBwrapArgs(resolved), command, ...args],
+                sandboxed: true,
+                networkDenied,
+                writesRestricted: true,
+            };
+        case "unshare":
+            if (!networkDenied)
+                return plain;
+            return {
+                command: status.path,
+                args: [...buildUnshareArgs(), command, ...args],
+                sandboxed: true,
+                networkDenied: true,
+                writesRestricted: false,
+            };
+    }
+}

package/dist/sdk.d.ts

@@ -6,13 +6,20 @@
  *   也可以直接给 `argv`（与 `ama` 命令行同语法）。
  * - `createAgentSession(options)`：不读文件系统配置的轻量装配——内存会话（或传入的
  *   SessionManager）、选定的工具、规则与回调审批，直接返回 `AgentSessionImpl`
- *   （含 `addTool / updateSystem / navigate` 等扩展方法）。
+ *   （含 `addTool / updateSystem / navigate` 等扩展方法；回滚 `rewindPoints / rewind /
+ *   summarizeFrom / summarizeUpTo / undoAbortedTurn`，内存会话只能仅对话）。
  *
  * 两者共用组装根（cli/compose*.ts），审批链、系统提示装配、工具预设与缓存行为与 CLI 一致。
+ * - [W5-F] 计划（docs/plan.md）：`CreateSessionOptions.plan`（plan.* 配置 + `onProposed` 审批回调）；
+ *   返回的会话带 `plan.current() / respond() / todos()`。没有 `onProposed` 时按 `plan.unattended`
+ *   （缺省 stop：计划落盘后停下，不替人批准）。
  */
 import type { ApiRegistry } from "./ai/apis/api.js";
 import type { ModelThinkingLevel, ProviderData } from "./ai/types.js";
 import type { AgentSessionImpl } from "./agent/session.js";
+import { type PlanDecision, type PlanResponse, type PlanResponseResult } from "./agent/session-plan.js";
+import type { PlanData, TodoItemView } from "./agent/types.js";
+import type { PlanConfig } from "./config/types-w5.js";
 import { type LogFn } from "./cli/compose-session.js";
 import { type ComposeOptions } from "./cli/compose.js";
 import type { Runtime } from "./cli/runtime.js";
@@ -24,6 +31,8 @@ import { SessionManager } from "./session/manager.js";
 import type { ToolDefinition } from "./tools/types.js";
 /** [W3-C2] 统计类型：`session.getStats()`、RPC `get_session_stats`、`-p --output-format json` 的 `cache`。 */
 export type { SessionCacheStats, SessionStats } from "./agent/types.js";
+/** [RW-B] 回滚：`session.rewindPoints()`、`session.rewind()`、`summarizeFrom / summarizeUpTo`。 */
+export type { CodeRestoreResult, RewindMode, RewindPoint, RewindRequest, RewindResult, } from "./checkpoints/types.js";
 export type { CacheMiss, CacheMissReason, CacheReporting, WarmerStatus, WarmingMode, } from "./ai/cache/types.js";
 export interface RuntimeOptions {
     cwd?: string;
@@ -46,6 +55,26 @@ export interface RuntimeOptions {
     compose?: ComposeOptions;
 }
 export declare function createRuntime(options?: RuntimeOptions): Promise<Runtime>;
+/** [W5-F] 计划：类型与 RPC 同形（`plan_proposed` / `plan_response`）。 */
+export type { PlanData, PlanDecision, PlanResponse, PlanResponseResult, TodoItemView };
+/** [W5-F] `CreateSessionOptions.plan`：plan.* 配置 + 审批回调。 */
+export interface SessionPlanOptions extends PlanConfig {
+    /**
+     * 计划待审批时调用（运行结束后；不阻塞运行）。返回回答即生效；返回 undefined 留待
+     * `session.plan.respond()`。不给时按 `unattended`（缺省 stop）。
+     */
+    onProposed?(plan: PlanData): Promise<PlanDecision | undefined>;
+}
+/** [W5-F] `session.plan`。 */
+export interface SessionPlanApi {
+    /** 分支上最近的计划；没有为 null。 */
+    current(): PlanData | null;
+    respond(response: PlanResponse): Promise<PlanResponseResult>;
+    todos(): TodoItemView[];
+}
+export type SdkAgentSession = AgentSessionImpl & {
+    readonly plan: SessionPlanApi;
+};
 export type SessionAuth = {
     kind: "file";
     path: string;
@@ -97,8 +126,10 @@ export interface CreateSessionOptions {
     /** 命令式 Hook（缺省不加载文件系统里的 hooks.json）。 */
     hooks?: HookConfig | false;
     config?: Partial<AmaConfig>;
+    /** [W5-F] 计划（plan.* 配置与审批回调），见 docs/plan.md。 */
+    plan?: SessionPlanOptions;
     unattended?: boolean;
     onWarning?: (message: string) => void;
     log?: LogFn;
 }
-export declare function createAgentSession(options?: CreateSessionOptions): Promise<AgentSessionImpl>;
+export declare function createAgentSession(options?: CreateSessionOptions): Promise<SdkAgentSession>;

package/dist/sdk.js

@@ -6,12 +6,17 @@
  *   也可以直接给 `argv`（与 `ama` 命令行同语法）。
  * - `createAgentSession(options)`：不读文件系统配置的轻量装配——内存会话（或传入的
  *   SessionManager）、选定的工具、规则与回调审批，直接返回 `AgentSessionImpl`
- *   （含 `addTool / updateSystem / navigate` 等扩展方法）。
+ *   （含 `addTool / updateSystem / navigate` 等扩展方法；回滚 `rewindPoints / rewind /
+ *   summarizeFrom / summarizeUpTo / undoAbortedTurn`，内存会话只能仅对话）。
  *
  * 两者共用组装根（cli/compose*.ts），审批链、系统提示装配、工具预设与缓存行为与 CLI 一致。
+ * - [W5-F] 计划（docs/plan.md）：`CreateSessionOptions.plan`（plan.* 配置 + `onProposed` 审批回调）；
+ *   返回的会话带 `plan.current() / respond() / todos()`。没有 `onProposed` 时按 `plan.unattended`
+ *   （缺省 stop：计划落盘后停下，不替人批准）。
  */
 import { resolve } from "node:path";
 import { ProviderRegistry } from "./ai/providers/registry.js";
+import { planController, } from "./agent/session-plan.js";
 import { parseArgs } from "./cli/args.js";
 import { bootstrap } from "./cli/bootstrap.js";
 import { withExtraProviders } from "./cli/compose-providers.js";
@@ -81,6 +86,9 @@ export async function createAgentSession(options = {}) {
     const cwd = resolve(options.cwd ?? process.cwd());
     const warn = options.onWarning ?? (() => undefined);
     let config = mergeConfig(DEFAULT_CONFIG, options.config);
+    const { onProposed, ...planConfig } = options.plan ?? {};
+    if (options.plan !== undefined)
+        config = { ...config, plan: { ...config.plan, ...planConfig } };
     if (options.toolsPreset !== undefined)
         config = mergeConfig(config, { tools: { preset: options.toolsPreset } });
     const providers = new ProviderRegistry({
@@ -199,5 +207,19 @@ export async function createAgentSession(options = {}) {
         warn,
     };
     session = composeSession(assembly, state, { log: options.log ?? (() => undefined) });
-    return session;
+    return withPlanApi(session, onProposed);
+}
+/** SDK 会话：审批交给 `onProposed`（没有则无人值守策略），并挂上 `session.plan`。 */
+function withPlanApi(session, onProposed) {
+    const controller = planController(session);
+    controller?.setAttendance(onProposed === undefined ? "unattended" : "callback", onProposed);
+    const missing = () => {
+        throw new AmaError("not_implemented", "该会话没有装配 plan 扩展");
+    };
+    const plan = {
+        current: () => controller?.current() ?? null,
+        respond: (response) => (controller ?? missing()).respond(response),
+        todos: () => controller?.todos() ?? [],
+    };
+    return Object.assign(session, { plan });
 }

package/dist/session/types.d.ts

@@ -14,6 +14,7 @@
  *   `append()` 同步：返回带 id 的条目并把叶子移到它（落盘可延迟到首条提示，§11.1 第 16 步）。
  * - （W3-C0）第三波 §1.7 / A7：新增 `usage` 条目（保温等不进上下文的请求用量，计入统计）与
  *   非条目的 `leaf` 行（`/tree` 位置落盘）；都是 v1 可选行，格式版本不升。
+ * - （W5-C0）`context_edit.reason` 加 `image_budget`（第五波 §4）；格式版本不升。
  */
 import type { ContentBlock, Message, ModelThinkingLevel, Usage } from "../ai/types.js";
 export declare const SESSION_FORMAT_VERSION: 1;
@@ -60,7 +61,8 @@ export interface BranchSummaryEntry extends EntryBase {
     usage?: Usage;
     details?: FileOpsDetails;
 }
-export type ContextEditReason = "prune" | "abort" | "retry" | "overflow" | "manual";
+/** [W5-C0] `image_budget`：单请求图片总量超预算时把旧图换成占位文本（wave5-plan §4）。 */
+export type ContextEditReason = "prune" | "abort" | "retry" | "overflow" | "manual" | "image_budget";
 /** 同一目标最新一条赢；replacement 为 null 表示从上下文剔除。 */
 export interface ContextEditEntry extends EntryBase {
     type: "context_edit";

package/dist/session/types.js

@@ -14,5 +14,6 @@
  *   `append()` 同步：返回带 id 的条目并把叶子移到它（落盘可延迟到首条提示，§11.1 第 16 步）。
  * - （W3-C0）第三波 §1.7 / A7：新增 `usage` 条目（保温等不进上下文的请求用量，计入统计）与
  *   非条目的 `leaf` 行（`/tree` 位置落盘）；都是 v1 可选行，格式版本不升。
+ * - （W5-C0）`context_edit.reason` 加 `image_budget`（第五波 §4）；格式版本不升。
  */
 export const SESSION_FORMAT_VERSION = 1;

package/dist/skills/builtin.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 内置 Skill（替代把 ama 自身文档塞进系统提示）。
+ *
+ * 系统提示里只常驻索引的一条（名字 + 一句描述，约 60 token），正文按需读取。单文件 bundle 没有
+ * docs 目录，所以正文是内联的配置速查（≤ 3 KB），会话发现时写到 `<dataDir>/builtin/<名>.md`（路径短，进前缀）
+ * （内容不变不重写），模型用 read 读、用户用 `/skill:ama-docs` 调用都走现成路径。
+ *
+ * - 排在全部用户 / 项目 Skill 之后：同名时用户的优先，内置的静默让位（不报重名 warning）。
+ * - 路径只取决于数据目录，会话开始时确定、会话内不变，不影响前缀稳定（设计 §9.1）。
+ * - 写盘失败只记 warning 并跳过该内置 Skill。
+ */
+import type { Skill } from "./discover.js";
+export declare const BUILTIN_SKILLS_DIR = "builtin";
+export interface BuiltinSkill {
+    name: string;
+    description: string;
+    body: string;
+}
+export declare const BUILTIN_SKILLS: readonly BuiltinSkill[];
+export declare function builtinSkillPath(dataDir: string, name: string): string;
+/** 是否内置 Skill（启动头的「已加载」只数用户 / 项目的）。 */
+export declare function isBuiltinSkill(skill: {
+    name: string;
+    location: string;
+}): boolean;
+export declare function builtinSkillText(skill: BuiltinSkill): string;
+/** 在已发现的 Skill 之后追加内置 Skill（同名让位给已有的）；返回新数组与 warning。 */
+export declare function withBuiltinSkills(skills: readonly Skill[], dataDir: string, builtins?: readonly BuiltinSkill[]): Promise<{
+    skills: Skill[];
+    warnings: string[];
+}>;