@armadra/agent 0.3.0 → 0.5.0

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_PRESETS_STRICT_FIRST, } 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");
 }
@@ -116,6 +36,10 @@ const CONFIG_KEYS = [
     "ui",
     "skills",
     "cache",
+    "request",
+    "checkpoints",
+    "sandbox",
+    ...W5_CONFIG_KEYS,
     "$schema",
 ];
 const PROVIDER_KEYS = [
@@ -199,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)) {
@@ -218,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)
@@ -228,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);
@@ -249,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, ""))
@@ -275,13 +201,16 @@ 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);
         }
     }
-    checkSection(c, value, "permission", ["mode", "allow", "deny", "builtinDeny"], (s, p) => {
+    const permissionKeys = ["mode", "allow", "deny", "builtinDeny", "autoModel", "autoSafeCommands"];
+    checkSection(c, value, "permission", permissionKeys, (s, p) => {
         c.oneOf(s, "mode", p, PERMISSION_MODES_STRICT_FIRST);
         c.stringArray(s, "allow", p);
         c.stringArray(s, "deny", p);
+        c.string(s, "autoModel", p);
+        c.stringArray(s, "autoSafeCommands", p);
         const builtinDeny = s["builtinDeny"];
         if (builtinDeny !== undefined &&
             typeof builtinDeny !== "boolean" &&
@@ -289,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);
@@ -301,7 +232,7 @@ export function validateConfig(value) {
         c.number(s, "maxDelayMs", p);
     });
     checkSection(c, value, "tools", ["preset", "default", "maxToolResultChars", "bashTimeoutMs", "disabled"], (s, p) => {
-        c.oneOf(s, "preset", p, TOOLS_PRESETS_STRICT_FIRST);
+        c.oneOf(s, "preset", p, TOOLS_PRESET_INPUTS);
         c.stringArray(s, "default", p);
         c.number(s, "maxToolResultChars", p, 1);
         c.number(s, "bashTimeoutMs", p, 1);
@@ -315,14 +246,50 @@ export function validateConfig(value) {
     checkSection(c, value, "hooks", ["timeoutMs"], (s, p) => {
         c.number(s, "timeoutMs", p, 1, HOOK_TIMEOUT_MAX_MS);
     });
-    checkSection(c, value, "ui", ["theme", "markdown", "showThinking", "tuiMode", "quietStartup"], (s, p) => {
-        c.oneOf(s, "theme", p, ["dark", "light"]);
+    checkSection(c, value, "ui", [
+        "theme",
+        "markdown",
+        "showThinking",
+        "tuiMode",
+        "quietStartup",
+        "ascii",
+        "compact",
+        "animation",
+        "restoreOnCancel",
+        ...W5_UI_KEYS,
+    ], (s, p) => {
+        c.oneOf(s, "theme", p, ["dark", "light", "auto"]);
         c.boolean(s, "markdown", p);
         c.oneOf(s, "showThinking", p, ["full", "collapsed", "hidden"]);
         c.oneOf(s, "tuiMode", p, ["regular"]);
         c.oneOf(s, "quietStartup", p, ["normal", "header", "silent"]);
+        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);
@@ -330,6 +297,7 @@ export function validateConfig(value) {
         c.boolean(s, "missNotices", p);
         c.boolean(s, "warmSubagents", p);
     });
+    validateConfigW5(c, value);
     return c.diagnostics;
 }
 // ---------------------------------------------------------------------------
@@ -366,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。
@@ -65,11 +71,19 @@ export interface PermissionConfig {
      * 数组 = 要移除的规则原文。放宽项，只认用户级 / profile，项目级忽略并 warning。
      */
     builtinDeny?: boolean | string[];
+    /** auto 模式分类器的模型（`provider/model`）；缺省 = 当前会话模型。放宽项，项目级忽略。 */
+    autoModel?: string;
+    /** auto 模式安全名单追加（词前缀或含 `*` 的通配）。放宽项，项目级忽略；各层累加。 */
+    autoSafeCommands?: string[];
 }
 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;
@@ -77,13 +91,22 @@ export interface RetryConfig {
     baseDelayMs?: number;
     maxDelayMs?: number;
 }
-/** 工具预设（设计 §5.6）：模型直接看到的工具集合。 */
-export type ToolsPreset = "default" | "minimal" | "codemode" | "coordinator";
-/** 从严到宽：项目级只能把预设改成不比当前更宽的那个（coordinator 最严，codemode 最宽）。 */
+/** 工具预设（设计 §5.6）：模型直接看到的工具集合（规范名）。 */
+export type ToolsPreset = "default" | "minimal" | "codemode-only" | "coordinator";
+/** 预设别名 → 规范名：`codemode` 是 0.3.0 的旧名（行为同 `codemode-only`）。 */
+export declare const TOOLS_PRESET_ALIASES: Readonly<Record<string, ToolsPreset>>;
+/** 配置文件、命令行、RPC、SDK 接受的写法：规范名或别名。 */
+export type ToolsPresetInput = ToolsPreset | "codemode";
+/** 从严到宽：项目级只能把预设改成不比当前更宽的那个（coordinator 最严，codemode-only 最宽）。 */
 export declare const TOOLS_PRESETS_STRICT_FIRST: readonly ToolsPreset[];
+/** 全部可接受的写法（规范名在前，别名在后；schema 与命令行校验用）。 */
+export declare const TOOLS_PRESET_INPUTS: readonly ToolsPresetInput[];
+/** 规范名；未知名字原样返回（校验由 schema 负责）。 */
+export declare function canonicalPreset(name: ToolsPresetInput): ToolsPreset;
+export declare function canonicalPreset(name: string | undefined): ToolsPreset | undefined;
 export interface ToolsConfig {
-    /** 缺省 `default`；命令行 `--tools-preset`。 */
-    preset?: ToolsPreset;
+    /** 缺省 `default`；命令行 `--tools-preset`；`codemode` 是 `codemode-only` 的别名。 */
+    preset?: ToolsPresetInput;
     /**
      * 在预设上微调（设计 §5.6）：`+name` 加、`-name` 去；不带前缀的名字整组替换预设的内置工具。
      * 只认用户级 / profile（项目级忽略并 warning）。
@@ -108,12 +131,23 @@ export interface HooksSettings {
     timeoutMs?: number;
 }
 export interface UiConfig {
-    theme?: "dark" | "light";
+    /** auto 按 `COLORFGBG` / `TERM_PROGRAM` 猜（不发查询序列），猜不出用 dark。 */
+    theme?: "dark" | "light" | "auto";
     markdown?: boolean;
     showThinking?: "full" | "collapsed" | "hidden";
     /** 第一期只有 regular（§12.10）。 */
     tuiMode?: "regular";
     quietStartup?: "normal" | "header" | "silent";
+    /** ASCII 字形（`AMA_ASCII=1` 等价）；缺省按区域设置 / TERM 自动检测。 */
+    ascii?: boolean;
+    /** 消息区块间不空行、启动头无框，缺省 false。 */
+    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[];
@@ -136,8 +170,46 @@ export interface CacheConfig {
     warmSubagents?: boolean;
 }
 export declare const DEFAULT_CACHE_CONFIG: Readonly<Required<CacheConfig>>;
+/**
+ * 模型请求（W4-C）。只认用户级 / profile；环境变量 `AMA_IDLE_TIMEOUT_MS` 覆盖 `idleTimeoutMs`。
+ */
+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;
@@ -152,6 +224,9 @@ export interface AmaConfig {
     ui?: UiConfig;
     skills?: SkillsConfig;
     cache?: CacheConfig;
+    request?: RequestConfig;
+    checkpoints?: CheckpointsConfig;
+    sandbox?: SandboxConfig;
 }
 /** auth.json（0600）。 */
 export interface AuthFile {
@@ -169,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,17 +7,36 @@
  * 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}$/;
-/** 从严到宽：项目级只能把预设改成不比当前更宽的那个（coordinator 最严，codemode 最宽）。 */
+/** 预设别名 → 规范名：`codemode` 是 0.3.0 的旧名（行为同 `codemode-only`）。 */
+export const TOOLS_PRESET_ALIASES = Object.freeze({
+    codemode: "codemode-only",
+});
+/** 从严到宽：项目级只能把预设改成不比当前更宽的那个（coordinator 最严，codemode-only 最宽）。 */
 export const TOOLS_PRESETS_STRICT_FIRST = [
     "coordinator",
     "minimal",
     "default",
+    "codemode-only",
+];
+/** 全部可接受的写法（规范名在前，别名在后；schema 与命令行校验用）。 */
+export const TOOLS_PRESET_INPUTS = [
+    ...TOOLS_PRESETS_STRICT_FIRST,
     "codemode",
 ];
+export function canonicalPreset(name) {
+    if (name === undefined)
+        return undefined;
+    return Object.hasOwn(TOOLS_PRESET_ALIASES, name)
+        ? TOOLS_PRESET_ALIASES[name]
+        : name;
+}
 export const CODEMODE_MODES = ["off", "on", "only"];
 export const CACHE_RETENTIONS = ["none", "short", "long"];
 export const DEFAULT_CACHE_CONFIG = Object.freeze({
@@ -27,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"];