@armadra/agent 0.4.0 → 0.5.1

package/dist/config/schema.d.ts

@@ -6,23 +6,19 @@
  * （未知字段等）。`path` 是 JSON 指针风格的字段路径（`permission.mode`、`hooks.PreToolUse[0]`）。
  */
 import type { AmaConfig, AuthFile, ProfileFile, TrustFile } from "./types.js";
+import { type Diagnostic } from "./checker.js";
 import type { HookConfig } from "../hooks/types.js";
-export type { AmaConfig, AuthFile, ProfileFile, TrustFile, TrustEntry, ProviderConfig, PermissionConfig, CompactionConfig, RetryConfig, ToolsConfig, ToolsPreset, ToolsPresetInput, CodemodeConfig, CodemodeMode, HooksSettings, UiConfig, SkillsConfig, CacheConfig, ModelConfig, ModelOverride, ChannelConfig, } from "./types.js";
+export type { AmaConfig, AuthFile, ProfileFile, TrustFile, TrustEntry, ProviderConfig, PermissionConfig, CompactionConfig, RetryConfig, ToolsConfig, ToolsPreset, ToolsPresetInput, CodemodeConfig, CodemodeMode, HooksSettings, UiConfig, SkillsConfig, CacheConfig, CheckpointsConfig, ModelConfig, ModelOverride, ChannelConfig, } from "./types.js";
 export { CONFIG_FILE_VERSION } from "./types.js";
 export type { HookConfig } from "../hooks/types.js";
-export interface Diagnostic {
-    severity: "error" | "warning";
-    /** 字段路径；文件级问题为 ""。 */
-    path: string;
-    message: string;
-}
-export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh"];
+export type { Diagnostic } from "./checker.js";
+export { THINKING_LEVELS } from "./checker.js";
 export declare const HOOK_TIMEOUT_MAX_MS = 600000;
 export declare function hasErrors(diagnostics: readonly Diagnostic[]): boolean;
 export declare function validateConfig(value: unknown): Diagnostic[];
 export declare function validateAuthFile(value: unknown): Diagnostic[];
 export declare const PROFILE_PATH_FIELDS: readonly ["host", "hooksFile", "authFile", "sessionDir", "config"];
-export declare const PROFILE_PATH_LIST_FIELDS: readonly ["instructions", "skillDirs", "promptDirs"];
+export declare const PROFILE_PATH_LIST_FIELDS: readonly ["instructions", "skillDirs", "promptDirs", "agentDirs"];
 export declare function validateProfile(value: unknown): Diagnostic[];
 export declare function validateTrustFile(value: unknown): Diagnostic[];
 export declare function validateHookConfig(value: unknown): Diagnostic[];

package/dist/config/schema.js

@@ -5,97 +5,17 @@
  * 校验结果是诊断列表：`severity: "error"` 拒绝该文件（启动退出码 3），`"warning"` 只提示
  * （未知字段等）。`path` 是 JSON 指针风格的字段路径（`permission.mode`、`hooks.PreToolUse[0]`）。
  */
+import { isAbsolute } from "node:path";
+import { Checker, THINKING_LEVELS, checkSection, join, } from "./checker.js";
+import { W5_COMPACTION_KEYS, W5_CONFIG_KEYS, W5_UI_KEYS, checkCompactionW5, checkUiW5, validateConfigW5, } from "./schema-w5.js";
 import { HOOK_EVENTS } from "../hooks/types.js";
 import { PERMISSION_MODES_STRICT_FIRST } from "../permissions/types.js";
 import { WARMING_MODES } from "../ai/cache/types.js";
-import { CACHE_RETENTIONS, CHANNEL_NAME_PATTERN, CODEMODE_MODES, TOOLS_PRESET_INPUTS, } from "./types.js";
+import { BUILTIN_PROVIDERS } from "../ai/providers/builtin.js";
+import { CACHE_RETENTIONS, CHANNEL_NAME_PATTERN, CHECKPOINT_MODES, SANDBOX_ENABLED_MODES, SANDBOX_NETWORK_MODES, CODEMODE_MODES, TOOLS_PRESET_INPUTS, } from "./types.js";
 export { CONFIG_FILE_VERSION } from "./types.js";
-export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
+export { THINKING_LEVELS } from "./checker.js";
 export const HOOK_TIMEOUT_MAX_MS = 600_000;
-class Checker {
-    diagnostics = [];
-    error(path, message) {
-        this.diagnostics.push({ severity: "error", path, message });
-    }
-    warn(path, message) {
-        this.diagnostics.push({ severity: "warning", path, message });
-    }
-    object(value, path) {
-        if (typeof value === "object" && value !== null && !Array.isArray(value))
-            return true;
-        this.error(path, "应为对象");
-        return false;
-    }
-    /** 未知字段只警告（前向兼容）。 */
-    keys(value, path, allowed) {
-        for (const key of Object.keys(value)) {
-            if (!allowed.includes(key))
-                this.warn(join(path, key), "未知字段，已忽略");
-        }
-    }
-    version(value, path) {
-        if (value["version"] !== 1)
-            this.error(join(path, "version"), "version 必须为 1");
-    }
-    string(value, key, path, required = false) {
-        const v = value[key];
-        if (v === undefined) {
-            if (required)
-                this.error(join(path, key), "缺少必填字符串");
-            return;
-        }
-        if (typeof v !== "string")
-            this.error(join(path, key), "应为字符串");
-    }
-    boolean(value, key, path) {
-        const v = value[key];
-        if (v !== undefined && typeof v !== "boolean")
-            this.error(join(path, key), "应为布尔值");
-    }
-    number(value, key, path, min = 0, max = Number.MAX_SAFE_INTEGER) {
-        const v = value[key];
-        if (v === undefined)
-            return;
-        if (typeof v !== "number" || !Number.isFinite(v)) {
-            this.error(join(path, key), "应为数字");
-        }
-        else if (v < min || v > max) {
-            this.error(join(path, key), `应在 ${min}–${max} 之间`);
-        }
-    }
-    oneOf(value, key, path, choices) {
-        const v = value[key];
-        if (v === undefined)
-            return;
-        if (typeof v !== "string" || !choices.includes(v)) {
-            this.error(join(path, key), `取值应为 ${choices.join(" | ")}`);
-        }
-    }
-    stringArray(value, key, path) {
-        const v = value[key];
-        if (v === undefined)
-            return;
-        if (!Array.isArray(v) || v.some((item) => typeof item !== "string")) {
-            this.error(join(path, key), "应为字符串数组");
-        }
-    }
-    stringRecord(value, key, path) {
-        const v = value[key];
-        if (v === undefined)
-            return;
-        if (!this.object(v, join(path, key)))
-            return;
-        for (const [k, item] of Object.entries(v)) {
-            if (typeof item !== "string")
-                this.error(join(join(path, key), k), "应为字符串");
-        }
-    }
-}
-function join(path, key) {
-    if (typeof key === "number")
-        return `${path}[${key}]`;
-    return path === "" ? key : `${path}.${key}`;
-}
 export function hasErrors(diagnostics) {
     return diagnostics.some((d) => d.severity === "error");
 }
@@ -117,6 +37,9 @@ const CONFIG_KEYS = [
     "skills",
     "cache",
     "request",
+    "checkpoints",
+    "sandbox",
+    ...W5_CONFIG_KEYS,
     "$schema",
 ];
 const PROVIDER_KEYS = [
@@ -200,15 +123,22 @@ function checkCompat(c, compat, path) {
         c.boolean(compat, key, path);
     c.oneOf(compat, "cacheReporting", path, ["auto", "silent", "reported"]);
 }
-/** 返回合法的渠道名集合；没有 `channels` 时 undefined。 */
-function checkChannels(c, value, path) {
+/**
+ * 返回合法的渠道名集合；没有 `channels`（也没有内置渠道）时 undefined。`builtin` 是内置供应商的内置渠道名
+ * （[W5-M2]）：同名渠道可只写要改的字段，`defaultChannel` 与模型 `channels` 也可引用它们。
+ */
+function checkChannels(c, value, path, builtin) {
     const channels = value["channels"];
-    if (channels === undefined)
-        return undefined;
+    if (channels === undefined) {
+        if (builtin.length === 0)
+            return undefined;
+        checkDefaultChannel(c, value, path, new Set(builtin));
+        return new Set(builtin);
+    }
     const cp = join(path, "channels");
     if (!c.object(channels, cp))
         return new Set();
-    const names = new Set();
+    const names = new Set(builtin);
     for (const [name, channel] of Object.entries(channels)) {
         const p = join(cp, name);
         if (!CHANNEL_NAME_PATTERN.test(name)) {
@@ -219,8 +149,8 @@ function checkChannels(c, value, path) {
         if (!c.object(channel, p))
             continue;
         c.keys(channel, p, CHANNEL_KEYS);
-        c.string(channel, "api", p, true);
-        c.string(channel, "baseUrl", p, true);
+        c.string(channel, "api", p, !builtin.includes(name));
+        c.string(channel, "baseUrl", p, !builtin.includes(name));
         c.string(channel, "apiKey", p);
         c.stringRecord(channel, "headers", p);
         if (channel["authHeader"] !== undefined)
@@ -229,16 +159,19 @@ function checkChannels(c, value, path) {
     }
     if (names.size === 0 && Object.keys(channels).length === 0)
         c.error(cp, "至少要有一个渠道");
-    const preferred = value["defaultChannel"];
-    if (preferred !== undefined) {
-        if (typeof preferred !== "string")
-            c.error(join(path, "defaultChannel"), "应为字符串");
-        else if (!names.has(preferred))
-            c.error(join(path, "defaultChannel"), `渠道 "${preferred}" 不存在`);
-    }
+    checkDefaultChannel(c, value, path, names);
     return names;
 }
-function checkProvider(c, value, path) {
+function checkDefaultChannel(c, value, path, names) {
+    const preferred = value["defaultChannel"];
+    if (preferred === undefined)
+        return;
+    if (typeof preferred !== "string")
+        c.error(join(path, "defaultChannel"), "应为字符串");
+    else if (!names.has(preferred))
+        c.error(join(path, "defaultChannel"), `渠道 "${preferred}" 不存在`);
+}
+function checkProvider(c, value, path, id) {
     if (!c.object(value, path))
         return;
     c.keys(value, path, PROVIDER_KEYS);
@@ -250,21 +183,13 @@ function checkProvider(c, value, path) {
     checkCompat(c, value["compat"], join(path, "compat"));
     if (value["authHeader"] !== undefined)
         c.object(value["authHeader"], join(path, "authHeader"));
-    const channels = checkChannels(c, value, path);
+    const builtin = BUILTIN_PROVIDERS.find((p) => p.id === id)?.channels?.map((ch) => ch.name);
+    const channels = checkChannels(c, value, path, builtin ?? []);
     if (channels === undefined && value["defaultChannel"] !== undefined)
         c.error(join(path, "defaultChannel"), "没有 channels 时不能设 defaultChannel");
     checkModels(c, value["models"], join(path, "models"), channels);
     checkModels(c, value["modelOverrides"], join(path, "modelOverrides"), channels);
 }
-function checkSection(c, config, key, allowed, body) {
-    const section = config[key];
-    if (section === undefined)
-        return;
-    if (!c.object(section, key))
-        return;
-    c.keys(section, key, allowed);
-    body(section, key);
-}
 export function validateConfig(value) {
     const c = new Checker();
     if (!c.object(value, ""))
@@ -276,7 +201,7 @@ export function validateConfig(value) {
     const providers = value["providers"];
     if (providers !== undefined && c.object(providers, "providers")) {
         for (const [id, provider] of Object.entries(providers)) {
-            checkProvider(c, provider, join("providers", id));
+            checkProvider(c, provider, join("providers", id), id);
         }
     }
     const permissionKeys = ["mode", "allow", "deny", "builtinDeny", "autoModel", "autoSafeCommands"];
@@ -293,10 +218,12 @@ export function validateConfig(value) {
             c.error(join(p, "builtinDeny"), "应为布尔值或字符串数组");
         }
     });
-    checkSection(c, value, "compaction", ["enabled", "reserveTokens", "keepRecentTokens"], (s, p) => {
+    const compactionKeys = ["enabled", "reserveTokens", "keepRecentTokens", ...W5_COMPACTION_KEYS];
+    checkSection(c, value, "compaction", compactionKeys, (s, p) => {
         c.boolean(s, "enabled", p);
         c.number(s, "reserveTokens", p);
         c.number(s, "keepRecentTokens", p);
+        checkCompactionW5(c, s, p);
     });
     checkSection(c, value, "retry", ["enabled", "maxRetries", "baseDelayMs", "maxDelayMs"], (s, p) => {
         c.boolean(s, "enabled", p);
@@ -328,6 +255,8 @@ export function validateConfig(value) {
         "ascii",
         "compact",
         "animation",
+        "restoreOnCancel",
+        ...W5_UI_KEYS,
     ], (s, p) => {
         c.oneOf(s, "theme", p, ["dark", "light", "auto"]);
         c.boolean(s, "markdown", p);
@@ -337,11 +266,30 @@ export function validateConfig(value) {
         c.boolean(s, "ascii", p);
         c.boolean(s, "compact", p);
         c.boolean(s, "animation", p);
+        c.boolean(s, "restoreOnCancel", p);
+        checkUiW5(c, s, p);
     });
     checkSection(c, value, "skills", ["dirs"], (s, p) => c.stringArray(s, "dirs", p));
     checkSection(c, value, "request", ["idleTimeoutMs"], (s, p) => {
         c.number(s, "idleTimeoutMs", p, 0);
     });
+    checkSection(c, value, "checkpoints", ["mode", "maxFileBytes", "keep"], (s, p) => {
+        c.oneOf(s, "mode", p, CHECKPOINT_MODES);
+        c.number(s, "maxFileBytes", p, 0);
+        c.number(s, "keep", p, 1);
+    });
+    checkSection(c, value, "sandbox", ["enabled", "bash", "network", "writable"], (s, p) => {
+        c.oneOf(s, "enabled", p, SANDBOX_ENABLED_MODES);
+        c.oneOf(s, "bash", p, SANDBOX_ENABLED_MODES);
+        c.oneOf(s, "network", p, SANDBOX_NETWORK_MODES);
+        c.stringArray(s, "writable", p);
+        const writable = s["writable"];
+        if (Array.isArray(writable))
+            writable.forEach((item, i) => {
+                if (typeof item === "string" && !isAbsolute(item) && item !== "~" && !item.startsWith("~/"))
+                    c.warn(`${p}.writable[${i}]`, "应为绝对路径或 ~/…，已忽略");
+            });
+    });
     checkSection(c, value, "cache", ["warming", "retention", "minSavingsUsd", "missNotices", "warmSubagents"], (s, p) => {
         c.oneOf(s, "warming", p, WARMING_MODES);
         c.oneOf(s, "retention", p, CACHE_RETENTIONS);
@@ -349,6 +297,7 @@ export function validateConfig(value) {
         c.boolean(s, "missNotices", p);
         c.boolean(s, "warmSubagents", p);
     });
+    validateConfigW5(c, value);
     return c.diagnostics;
 }
 // ---------------------------------------------------------------------------
@@ -385,7 +334,12 @@ export const PROFILE_PATH_FIELDS = [
     "sessionDir",
     "config",
 ];
-export const PROFILE_PATH_LIST_FIELDS = ["instructions", "skillDirs", "promptDirs"];
+export const PROFILE_PATH_LIST_FIELDS = [
+    "instructions",
+    "skillDirs",
+    "promptDirs",
+    "agentDirs",
+];
 export function validateProfile(value) {
     const c = new Checker();
     if (!c.object(value, ""))

package/dist/config/types-w5.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 第五波配置键的形状（docs/wave5-plan.md §9）。[W5-C0] 契约文件：C0 只定形状、校验（schema-w5.ts）、
+ * 说明与缺省（key-docs.ts）、JSON Schema；行为由各批次实现，未实现前这些键被接受但不起作用。
+ *
+ * 层级：项目级只接受 `plan.bash`（只能更严）、`reminders`、`ui.statusLine`（随 `ui` 段）；其余只认
+ * 用户级 / profile（项目级忽略并 warning，merge.ts）。
+ */
+import type { ModelThinkingLevel } from "../ai/types.js";
+import type { PermissionMode } from "../permissions/types.js";
+/** [W5-A] 底部信息行：full 两行（速率行 + 状态行），compact 一行。 */
+export type StatusLineMode = "full" | "compact";
+export declare const STATUS_LINE_MODES: readonly StatusLineMode[];
+/** [W5-I] 图像。 */
+export interface ImagesConfig {
+    /** auto：超限时用系统工具（sips / magick）缩放，没有工具按原规则拒绝；off：从不缩放。 */
+    resize?: "auto" | "off";
+}
+export declare const IMAGE_RESIZE_MODES: readonly ["auto", "off"];
+/** plan 模式下 bash 的处理，从严到宽。 */
+export type PlanBashMode = "deny" | "readonly" | "ask";
+export declare const PLAN_BASH_MODES_STRICT_FIRST: readonly PlanBashMode[];
+/** [W5-F] Plan。 */
+export interface PlanConfig {
+    /** 缺省 readonly：只读命令放行、其余拒绝；ask：其余询问；deny：bash 全拒。项目级只能更严。 */
+    bash?: PlanBashMode;
+    /** 计划文件目录（必须在项目根之内）；缺省 `<dataDir>/plans`。 */
+    directory?: string;
+    /** 无人值守（`-p`、RPC 未声明 plans 能力）时：stop 落盘后停下（缺省），approve 自动批准执行。 */
+    unattended?: "stop" | "approve";
+    /** 规划用模型 `provider/model[@channel]`：进入 plan 时切换、批准时切回。 */
+    model?: string;
+    thinkingLevel?: ModelThinkingLevel;
+}
+export declare const PLAN_UNATTENDED_MODES: readonly ["stop", "approve"];
+/** [W5-E / W5-G] 单个 Agent（外部 CLI 或子 Agent 类型）的设置：`agents.<id>`。 */
+export interface AgentEntryConfig {
+    /** 该 Agent 的并发上限（claude 缺省 2）。 */
+    maxConcurrent?: number;
+    /** 允许比 ama 当前模式更宽的上限（只认用户级）。 */
+    maxMode?: PermissionMode;
+    /** 该类型 / 外部 Agent 使用的模型。 */
+    model?: string;
+    env?: {
+        /** 子进程环境缺省剥离供应商 key、`*_BASE_URL` 与 `AMA_*`；这里列出要放回的变量名。 */
+        passthrough?: string[];
+    };
+}
+/** `agents` 段里的保留键（其余键都是 Agent id）。 */
+export declare const AGENTS_RESERVED_KEYS: readonly ["maxConcurrent", "sessionBudgetUsd", "dirs"];
+/** [W5-E / W5-G] `agents`：外部 Agent 与子 Agent 定义。 */
+export interface AgentsConfig {
+    /** 外部 Agent 总并发，缺省 3。 */
+    maxConcurrent?: number;
+    /** 本会话外部 Agent 的美元预算；缺省不限。 */
+    sessionBudgetUsd?: number;
+    /** 追加的子 Agent 定义目录；各层累加。 */
+    dirs?: string[];
+    [agentId: string]: AgentEntryConfig | number | string[] | undefined;
+}
+/** 取 `agents.<id>`（保留键返回 undefined）。 */
+export declare function agentEntry(agents: AgentsConfig | undefined, agentId: string): AgentEntryConfig | undefined;
+/** [W5-G] ama 自己的子会话。 */
+export interface SubagentsConfig {
+    /** 同时运行的子会话，缺省 4。 */
+    maxConcurrent?: number;
+    /** 排队上限，缺省 16（超出报错）。 */
+    maxPending?: number;
+    /** 子会话缺省模型；不设继承父会话。 */
+    defaultModel?: string;
+}
+/** [W5-G] 模型别名（子 Agent 定义的 `model: fast | strong`）。 */
+export interface ModelsConfig {
+    aliases?: {
+        fast?: string;
+        strong?: string;
+    };
+}
+/** [W5-H1] 档一裁剪参数（其余随窗口缩放的常量不暴露）。 */
+export interface PruneConfig {
+    /** 保留最近 N 个工具结果，缺省 5。 */
+    keepResults?: number;
+    /** 一次至少能省多少 token 才裁：auto = max(20k, 0.1×预算)。 */
+    clearAtLeast?: "auto" | number;
+}
+/** [W5-H2] 会话预算（`--max-turns` / `--max-cost` 覆盖）。 */
+export interface LimitsConfig {
+    maxTurns?: number;
+    maxCostUsd?: number;
+}
+/** [W5-H2] 提醒通道 `ama.reminder` 的各项开关（缺省全开）。 */
+export interface RemindersConfig {
+    /** 连续多回合未更新 todo 且有未完成项时复述。 */
+    todo?: boolean;
+    /** 读过的文件被外部改动时列出。 */
+    fileChanges?: boolean;
+    /** 上下文用量 70% / 85% 各提醒一次。 */
+    contextPressure?: boolean;
+    /** 预算剩余 < 20% 时提醒。 */
+    budget?: boolean;
+}
+/** [W5-F / W5-H2] todo。 */
+export interface TodoConfig {
+    /** 连续 N 回合未更新且有未完成项时提醒复述，缺省 10；0 关闭。 */
+    reminder?: number;
+}
+/** 第五波并入 `AmaConfig` 的顶层段。 */
+export interface AmaConfigW5 {
+    images?: ImagesConfig;
+    plan?: PlanConfig;
+    agents?: AgentsConfig;
+    subagents?: SubagentsConfig;
+    models?: ModelsConfig;
+    /** [W5-H2] 回退模型 `provider/model[@channel]`：可重试错误用尽或 overloaded 时切换重试一次。 */
+    fallbackModel?: string;
+    limits?: LimitsConfig;
+    reminders?: RemindersConfig;
+    todo?: TodoConfig;
+}

package/dist/config/types-w5.js

@@ -0,0 +1,20 @@
+/**
+ * 第五波配置键的形状（docs/wave5-plan.md §9）。[W5-C0] 契约文件：C0 只定形状、校验（schema-w5.ts）、
+ * 说明与缺省（key-docs.ts）、JSON Schema；行为由各批次实现，未实现前这些键被接受但不起作用。
+ *
+ * 层级：项目级只接受 `plan.bash`（只能更严）、`reminders`、`ui.statusLine`（随 `ui` 段）；其余只认
+ * 用户级 / profile（项目级忽略并 warning，merge.ts）。
+ */
+export const STATUS_LINE_MODES = ["full", "compact"];
+export const IMAGE_RESIZE_MODES = ["auto", "off"];
+export const PLAN_BASH_MODES_STRICT_FIRST = ["deny", "readonly", "ask"];
+export const PLAN_UNATTENDED_MODES = ["stop", "approve"];
+/** `agents` 段里的保留键（其余键都是 Agent id）。 */
+export const AGENTS_RESERVED_KEYS = ["maxConcurrent", "sessionBudgetUsd", "dirs"];
+/** 取 `agents.<id>`（保留键返回 undefined）。 */
+export function agentEntry(agents, agentId) {
+    if (agents === undefined || AGENTS_RESERVED_KEYS.includes(agentId))
+        return undefined;
+    const entry = agents[agentId];
+    return typeof entry === "object" && !Array.isArray(entry) ? entry : undefined;
+}

package/dist/config/types.d.ts

@@ -7,10 +7,16 @@
  * hooks.json 的形状是 `HookConfig`（hooks/types.ts）。
  * （W3-C0）第三波：`cache` 段（§1.12，只认用户级 / profile）；`ModelConfig` / `ModelOverride`
  * 允许模型级 `api`（§2.3，同一中转的模型走不同协议），由 W3-B12 在注册表里生效。
+ * （W5-C0）第五波配置键（docs/wave5-plan.md §9）：新段的形状在 types-w5.ts（`AmaConfigW5` 并入
+ * `AmaConfig`），已有段加 `ui.statusLine`、`compaction.prune / pruneExclude`、profile `agentDirs`。
  */
 import type { WarmingMode } from "../ai/cache/types.js";
 import type { Api, AuthHeader, CacheRetention, Model, ModelThinkingLevel, ProviderCompat } from "../ai/types.js";
 import type { PermissionMode } from "../permissions/types.js";
+import type { CheckpointMode } from "../checkpoints/types.js";
+import type { AmaConfigW5, PruneConfig, StatusLineMode } from "./types-w5.js";
+export type * from "./types-w5.js";
+export { AGENTS_RESERVED_KEYS, IMAGE_RESIZE_MODES, PLAN_BASH_MODES_STRICT_FIRST, PLAN_UNATTENDED_MODES, STATUS_LINE_MODES, agentEntry, } from "./types-w5.js";
 export declare const CONFIG_FILE_VERSION: 1;
 /**
  * 自定义模型条目；缺省 maxTokens 8192、reasoning false、input ["text"]，不猜 contextWindow。
@@ -74,6 +80,10 @@ export interface CompactionConfig {
     enabled?: boolean;
     reserveTokens?: number;
     keepRecentTokens?: number;
+    /** [W5-C0] 档一裁剪参数（W5-H1）；只认用户级。 */
+    prune?: PruneConfig;
+    /** [W5-C0] 不被档一裁剪的工具名（W5-H1）；只认用户级。 */
+    pruneExclude?: string[];
 }
 export interface RetryConfig {
     enabled?: boolean;
@@ -134,6 +144,10 @@ export interface UiConfig {
     compact?: boolean;
     /** false：运行中 spinner 固定为 `·`，缺省 true。 */
     animation?: boolean;
+    /** 运行中 Esc 中断、本回合还没有任何输出时撤回该回合并回填原消息，缺省 true。 */
+    restoreOnCancel?: boolean;
+    /** [W5-C0] 底部信息行（W5-A）：缺省独立终端 full、嵌入宿主（有 profile）compact。 */
+    statusLine?: StatusLineMode;
 }
 export interface SkillsConfig {
     dirs?: string[];
@@ -163,8 +177,39 @@ export interface RequestConfig {
     /** 等响应头与流中两块数据之间的最长间隔（毫秒），收到任何字节即重新计时；缺省 300 000，0 关闭。 */
     idleTimeoutMs?: number;
 }
+export declare const CHECKPOINT_MODES: readonly CheckpointMode[];
+/**
+ * 检查点（docs/rewind-plan.md §5）。环境变量 `AMA_CHECKPOINTS` 覆盖 `mode`；项目级只接受
+ * `mode: "off"` 与调小 `maxFileBytes`（只能收紧）。
+ */
+export interface CheckpointsConfig {
+    /** tools（缺省）：跟踪 edit / write 改过的文件；shadow-git：影子 git（RW-D）；off：关闭。 */
+    mode?: CheckpointMode;
+    /** 单个文件的备份上限（字节），超出不备份，回滚时报告无法恢复；缺省 5 242 880。 */
+    maxFileBytes?: number;
+    /** 可回滚的最近检查点数，缺省 100。 */
+    keep?: number;
+}
+export declare const DEFAULT_CHECKPOINTS_CONFIG: Readonly<Required<CheckpointsConfig>>;
+export declare const SANDBOX_ENABLED_MODES: readonly ("auto" | "off")[];
+/** [S2] `sandbox.network` 的取值。 */
+export declare const SANDBOX_NETWORK_MODES: readonly ("deny" | "allow")[];
+/**
+ * 操作系统级沙箱（docs/sandbox.md）。只认用户级 / profile；项目级只接受收紧的 `network: "deny"`，其余忽略
+ * 并 warning。环境变量 `AMA_SANDBOX=off` 覆盖 `enabled`。
+ */
+export interface SandboxConfig {
+    /** auto（缺省）：探测到可用的 sandbox-exec / bwrap / unshare 就用；off：不用。 */
+    enabled?: "auto" | "off";
+    /** [S2] bash 经 OS 沙箱运行：auto 有 sandbox-exec / bwrap 就用；off（缺省）不用。 */
+    bash?: "auto" | "off";
+    /** [S2] bash 沙箱里的网络：deny（缺省，满足 default 模式免审批的条件）/ allow。 */
+    network?: "deny" | "allow";
+    /** [S2] bash 沙箱追加的可写目录（绝对路径或 `~/…`）。 */
+    writable?: string[];
+}
 /** config.json（用户级 / 项目级 / profile.config 同形状；项目级只接受受限字段，§10.2）。 */
-export interface AmaConfig {
+export interface AmaConfig extends AmaConfigW5 {
     version: typeof CONFIG_FILE_VERSION;
     /** `provider/model-id`。 */
     defaultModel?: string;
@@ -180,6 +225,8 @@ export interface AmaConfig {
     skills?: SkillsConfig;
     cache?: CacheConfig;
     request?: RequestConfig;
+    checkpoints?: CheckpointsConfig;
+    sandbox?: SandboxConfig;
 }
 /** auth.json（0600）。 */
 export interface AuthFile {
@@ -197,6 +244,8 @@ export interface ProfileFile {
     instructions?: string[];
     skillDirs?: string[];
     promptDirs?: string[];
+    /** [W5-C0] 子 Agent 定义目录（发现顺序在 `--agent-dir` 之后、用户级之前，W5-G）。 */
+    agentDirs?: string[];
     hooksFile?: string;
     authFile?: string;
     /** false：key 只来自 authFile，不读环境变量（§11.2）。 */

package/dist/config/types.js

@@ -7,7 +7,10 @@
  * hooks.json 的形状是 `HookConfig`（hooks/types.ts）。
  * （W3-C0）第三波：`cache` 段（§1.12，只认用户级 / profile）；`ModelConfig` / `ModelOverride`
  * 允许模型级 `api`（§2.3，同一中转的模型走不同协议），由 W3-B12 在注册表里生效。
+ * （W5-C0）第五波配置键（docs/wave5-plan.md §9）：新段的形状在 types-w5.ts（`AmaConfigW5` 并入
+ * `AmaConfig`），已有段加 `ui.statusLine`、`compaction.prune / pruneExclude`、profile `agentDirs`。
  */
+export { AGENTS_RESERVED_KEYS, IMAGE_RESIZE_MODES, PLAN_BASH_MODES_STRICT_FIRST, PLAN_UNATTENDED_MODES, STATUS_LINE_MODES, agentEntry, } from "./types-w5.js";
 export const CONFIG_FILE_VERSION = 1;
 /** 渠道名：不含 `/` 与 `@`（`provider/model@channel`）。 */
 export const CHANNEL_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/;
@@ -43,3 +46,12 @@ export const DEFAULT_CACHE_CONFIG = Object.freeze({
     missNotices: true,
     warmSubagents: false,
 });
+export const CHECKPOINT_MODES = ["tools", "shadow-git", "off"];
+export const DEFAULT_CHECKPOINTS_CONFIG = Object.freeze({
+    mode: "tools",
+    maxFileBytes: 5_242_880,
+    keep: 100,
+});
+export const SANDBOX_ENABLED_MODES = ["auto", "off"];
+/** [S2] `sandbox.network` 的取值。 */
+export const SANDBOX_NETWORK_MODES = ["deny", "allow"];

package/dist/drivers/acp/client.d.ts

@@ -0,0 +1,57 @@
+/**
+ * ACP 客户端（docs/wave5-plan.md §5.1，D14）。[W5-E]
+ *
+ * JSON-RPC over NDJSON（{@link JsonRpcPeer}），手写零依赖；`@armadra/agent/acp` 导出供 Armadra 复用。
+ *
+ * - 不声明 `fs` / `terminal` 能力：Agent 发来的 `fs/*`、`terminal/*` 请求一律 method not found。
+ * - `session/request_permission` 交给 `onPermission`（驱动再交给 ama 的审批通道，只交给人）；
+ *   没有处理器时按无人值守回首个 `reject_once`（没有则 cancelled）。
+ * - `cancel(sessionId)` 发 `session/cancel` 通知，并让该会话所有挂起的权限请求回 `cancelled`
+ *   （规范要求：客户端取消回合后必须以 cancelled 回答挂起的请求）。
+ */
+import { type AcpAgentCapabilities, type AcpContentBlock, type AcpImplementationInfo, type AcpInitializeResult, type AcpListSessionsResult, type AcpLoadSessionResult, type AcpNewSessionResult, type AcpPromptResult, type AcpRequestPermissionParams, type AcpRequestPermissionResult, type AcpSessionNotification } from "./types.js";
+export interface AcpClientHandlers {
+    onUpdate?(notification: AcpSessionNotification): void;
+    /** `signal`：该会话被 cancel、连接关闭时 abort（此时应尽快回 cancelled）。 */
+    onPermission?(params: AcpRequestPermissionParams, signal: AbortSignal): Promise<AcpRequestPermissionResult>;
+    onProtocolError?(line: string, reason: string): void;
+    onClose?(): void;
+}
+export interface AcpClientOptions extends AcpClientHandlers {
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+    clientInfo?: AcpImplementationInfo;
+}
+/** 无人值守的回答：首个 reject_once，没有就 cancelled。 */
+export declare function unattendedOutcome(params: AcpRequestPermissionParams): AcpRequestPermissionResult;
+export declare class AcpClient {
+    private readonly options;
+    private readonly peer;
+    /** sessionId → 挂起权限请求的取消器。 */
+    private readonly pendingPermissions;
+    private initResult;
+    constructor(options: AcpClientOptions);
+    get closed(): Promise<void>;
+    get isOpen(): boolean;
+    get agentCapabilities(): AcpAgentCapabilities;
+    get agentInfo(): AcpImplementationInfo | undefined;
+    initialize(signal?: AbortSignal): Promise<AcpInitializeResult>;
+    supportsResume(): boolean;
+    supportsLoad(): boolean;
+    supportsList(): boolean;
+    supportsClose(): boolean;
+    supportsImages(): boolean;
+    newSession(cwd: string, signal?: AbortSignal): Promise<AcpNewSessionResult>;
+    /** 不回放历史（优先，R13：v2 计划取消 load）。 */
+    resumeSession(sessionId: string, cwd: string, signal?: AbortSignal): Promise<AcpLoadSessionResult>;
+    /** 回放历史（以 session/update 通知）。 */
+    loadSession(sessionId: string, cwd: string, signal?: AbortSignal): Promise<AcpLoadSessionResult>;
+    listSessions(cwd?: string, cursor?: string): Promise<AcpListSessionsResult>;
+    closeSession(sessionId: string): Promise<unknown>;
+    prompt(sessionId: string, prompt: AcpContentBlock[], signal?: AbortSignal): Promise<AcpPromptResult>;
+    setMode(sessionId: string, modeId: string): Promise<unknown>;
+    /** 协议级取消：发通知，并让挂起的权限请求回 cancelled。 */
+    cancel(sessionId: string): Promise<void>;
+    close(): void;
+    private onRequest;
+}