@armadra/agent 0.3.0 → 0.5.0

package/dist/config/merge.js

@@ -2,14 +2,17 @@
  * 配置层级合并（设计 §7.2、§10.2）。[B5]
  *
  * 顺序：内置缺省 ← 用户级 ← profile.config ← 项目级（受限字段，只能收紧）← 命令行。
- * - 对象深合并；数组整体替换，例外是「累加型」列表：`permission.allow / deny`、
+ * - 对象深合并；数组整体替换，例外是「累加型」列表：`permission.allow / deny / autoSafeCommands`、
  *   `tools.disabled`、`skills.dirs` 跨层拼接去重。
- * - 项目级 `.ama/config.json` 只接受：`permission.deny`（追加）、`permission.mode`（只能更严）、
- *   `compaction`、`tools.disabled`、`tools.preset`（只能更严）、`codemode.mode: "off"`、`ui`；
- *   其它字段与放宽项（含 `permission.builtinDeny`）被忽略并记 warning。
+ * - 项目级 `.ama/config.json` 只接受：`permission.deny`（追加）、`permission.mode`（只能更严，且不能是
+ *   auto / full-auto）、
+ *   `compaction`、`tools.disabled`、`tools.preset`（只能更严）、`codemode.mode: "off"`、`ui`、
+ *   `checkpoints.mode: "off"`、`checkpoints.maxFileBytes`（只能调小）、（W5-C0）`plan.bash`（只能更严）、
+ *   `reminders`；`compaction.prune / pruneExclude` 与第五波其余段只认用户级；
+ *   其它字段与放宽项（含 `permission.builtinDeny / autoModel / autoSafeCommands`）被忽略并记 warning。
  * - 同时产出带来源的权限规则清单（`ruleSpecs`），交给权限管线（B3 的 rules.ts 解析）。
  */
-import { CONFIG_FILE_VERSION, TOOLS_PRESETS_STRICT_FIRST } from "./types.js";
+import { CONFIG_FILE_VERSION, DEFAULT_CHECKPOINTS_CONFIG, PLAN_BASH_MODES_STRICT_FIRST, TOOLS_PRESETS_STRICT_FIRST, canonicalPreset, } from "./types.js";
 import { isAtLeastAsStrict } from "../permissions/rules.js";
 export const DEFAULT_CONFIG = Object.freeze({
     version: CONFIG_FILE_VERSION,
@@ -30,7 +33,8 @@ export const DEFAULT_CONFIG = Object.freeze({
 });
 /** 嵌入宿主（有 profile）时的缺省覆盖（§12.10）。 */
 export const PROFILE_DEFAULTS = Object.freeze({
-    ui: { quietStartup: "header" },
+    // [W5-A] 嵌入宿主以「最后一行 = 状态栏」锚定，底部信息行缺省单行
+    ui: { quietStartup: "header", statusLine: "compact" },
 });
 /** 层名 → 规则来源（RuleSource）。 */
 const RULE_SOURCE = {
@@ -43,8 +47,10 @@ const RULE_SOURCE = {
 const ACCUMULATING = new Set([
     "permission.allow",
     "permission.deny",
+    "permission.autoSafeCommands",
     "tools.disabled",
     "skills.dirs",
+    "agents.dirs",
 ]);
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -78,17 +84,21 @@ export function mergeConfig(base, over) {
         return structuredCloneSafe(base);
     const merged = mergeValue(base, over, "");
     merged.version = CONFIG_FILE_VERSION;
+    // 别名（`codemode`）在合并后折成规范名：下游只见规范名。
+    if (merged.tools?.preset !== undefined)
+        merged.tools.preset = canonicalPreset(merged.tools.preset);
     return merged;
 }
-/** 预设 a 是否比 b 更严或相同（coordinator 最严，codemode 最宽）。 */
+/** 预设 a 是否比 b 更严或相同（coordinator 最严，codemode-only 最宽；别名按规范名比）。 */
 export function isPresetStricterOrEqual(a, b) {
-    return TOOLS_PRESETS_STRICT_FIRST.indexOf(a) <= TOOLS_PRESETS_STRICT_FIRST.indexOf(b);
+    return (TOOLS_PRESETS_STRICT_FIRST.indexOf(canonicalPreset(a)) <=
+        TOOLS_PRESETS_STRICT_FIRST.indexOf(canonicalPreset(b)));
 }
 /**
  * 把项目级配置裁剪为受限字段（§7.2）；`currentMode` / `currentPreset` 是合并到此为止的
  * 权限模式与工具预设。
  */
-export function restrictProjectConfig(project, currentMode, label = ".ama/config.json", currentPreset = "default") {
+export function restrictProjectConfig(project, currentMode, label = ".ama/config.json", currentPreset = "default", currentMaxFileBytes = DEFAULT_CHECKPOINTS_CONFIG.maxFileBytes, currentPlanBash = "readonly") {
     const warnings = [];
     const accepted = {};
     for (const [key, value] of Object.entries(project)) {
@@ -96,9 +106,24 @@ export function restrictProjectConfig(project, currentMode, label = ".ama/config
             continue;
         switch (key) {
             case "compaction":
-                if (project.compaction !== undefined)
-                    accepted.compaction = structuredClone(project.compaction);
+                if (project.compaction !== undefined) {
+                    const { prune, pruneExclude, ...rest } = structuredClone(project.compaction);
+                    if (prune !== undefined || pruneExclude !== undefined)
+                        warnings.push(`${label}: 项目级不能设 compaction.prune / pruneExclude，已忽略`);
+                    if (Object.keys(rest).length > 0)
+                        accepted.compaction = rest;
+                }
+                break;
+            case "reminders":
+                if (project.reminders !== undefined)
+                    accepted.reminders = structuredClone(project.reminders);
+                break;
+            case "plan": {
+                const plan = restrictPlan(project.plan ?? {}, currentPlanBash, label, warnings);
+                if (plan !== undefined)
+                    accepted.plan = plan;
                 break;
+            }
             case "ui":
                 if (project.ui !== undefined)
                     accepted.ui = structuredClone(project.ui);
@@ -133,18 +158,73 @@ export function restrictProjectConfig(project, currentMode, label = ".ama/config
                     accepted.codemode = { mode: "off" };
                 break;
             }
+            case "checkpoints": {
+                const checkpoints = restrictCheckpoints(project.checkpoints ?? {}, currentMaxFileBytes, label, warnings);
+                if (checkpoints !== undefined)
+                    accepted.checkpoints = checkpoints;
+                break;
+            }
             case "permission": {
                 const permission = restrictPermission(project.permission ?? {}, currentMode, label, warnings);
                 if (permission !== undefined)
                     accepted.permission = permission;
                 break;
             }
+            case "sandbox": {
+                // [S2] 只能收紧：network "deny"。enabled / bash 两个方向都不是单纯更严（打开 bash 沙箱会让 default
+                // 模式免审批，关闭会让命令裸跑），writable 是放宽，一律忽略。
+                const sandbox = project.sandbox ?? {};
+                for (const [sub, v] of Object.entries(sandbox)) {
+                    if (sub === "network" && v === "deny")
+                        continue;
+                    warnings.push(`${label}: 项目级只接受 sandbox.network "deny"，忽略 sandbox.${sub}${sub === "network" ? ` ${String(v)}` : ""}`);
+                }
+                if (sandbox.network === "deny")
+                    accepted.sandbox = { network: "deny" };
+                break;
+            }
             default:
                 warnings.push(`${label}: 项目级不能设 ${key}，已忽略`);
         }
     }
     return { accepted, warnings };
 }
+/** [W5-C0] 项目级 plan：只接受 `bash`，且只能更严（deny < readonly < ask）。 */
+function restrictPlan(plan, current, label, warnings) {
+    for (const sub of Object.keys(plan)) {
+        if (sub !== "bash")
+            warnings.push(`${label}: 项目级只能设 plan.bash，忽略 plan.${sub}`);
+    }
+    if (plan.bash === undefined)
+        return undefined;
+    const order = PLAN_BASH_MODES_STRICT_FIRST;
+    if (order.indexOf(plan.bash) <= order.indexOf(current))
+        return { bash: plan.bash };
+    warnings.push(`${label}: 项目级只能收紧 plan.bash，忽略 ${plan.bash}（当前 ${current}）`);
+    return undefined;
+}
+/** 项目级检查点：只能关闭、只能调小单文件上限（多备份即多占用户磁盘）；`keep` 只认用户级。 */
+function restrictCheckpoints(checkpoints, currentMaxFileBytes, label, warnings) {
+    const result = {};
+    for (const [sub, v] of Object.entries(checkpoints)) {
+        if (sub === "mode") {
+            if (v === "off")
+                result.mode = "off";
+            else
+                warnings.push(`${label}: 项目级只接受 checkpoints.mode "off"，忽略 ${String(v)}`);
+        }
+        else if (sub === "maxFileBytes" && typeof v === "number") {
+            if (v <= currentMaxFileBytes)
+                result.maxFileBytes = v;
+            else
+                warnings.push(`${label}: 项目级只能调小 checkpoints.maxFileBytes，忽略 ${v}（当前 ${currentMaxFileBytes}）`);
+        }
+        else {
+            warnings.push(`${label}: 项目级不能设 checkpoints.${sub}，已忽略`);
+        }
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
 function restrictPermission(permission, currentMode, label, warnings) {
     const result = {};
     if (permission.allow !== undefined && permission.allow.length > 0) {
@@ -155,7 +235,16 @@ function restrictPermission(permission, currentMode, label, warnings) {
     if (permission.builtinDeny !== undefined) {
         warnings.push(`${label}: 项目级不能改内置 deny 表，忽略 permission.builtinDeny`);
     }
-    if (permission.mode !== undefined) {
+    if (permission.autoModel !== undefined) {
+        warnings.push(`${label}: 项目级不能设 permission.autoModel，已忽略`);
+    }
+    if (permission.autoSafeCommands !== undefined && permission.autoSafeCommands.length > 0) {
+        warnings.push(`${label}: 项目级不能追加 permission.autoSafeCommands（放宽），已忽略`);
+    }
+    if (permission.mode === "auto" || permission.mode === "full-auto") {
+        warnings.push(`${label}: 项目级不能把权限模式设为 ${permission.mode}（放宽，只能在用户级配置、profile 或命令行设），已忽略`);
+    }
+    else if (permission.mode !== undefined) {
         if (isAtLeastAsStrict(permission.mode, currentMode)) {
             result.mode = permission.mode;
         }
@@ -227,7 +316,7 @@ export function mergeProjectAndCli(base, project, cli, projectLabel) {
     const present = [...base.layers];
     if (project !== undefined) {
         const baseline = config.permission?.mode ?? "default";
-        const restricted = restrictProjectConfig(project, baseline, projectLabel, config.tools?.preset ?? "default");
+        const restricted = restrictProjectConfig(project, baseline, projectLabel, config.tools?.preset ?? "default", config.checkpoints?.maxFileBytes ?? DEFAULT_CHECKPOINTS_CONFIG.maxFileBytes, config.plan?.bash ?? "readonly");
         warnings.push(...restricted.warnings);
         config = mergeConfig(config, restricted.accepted);
         present.push("project");

package/dist/config/profile.d.ts

@@ -12,6 +12,8 @@ export interface ProfileOptions {
     instructions: string[];
     skillDirs: string[];
     promptDirs: string[];
+    /** [W5-C0] 子 Agent 定义目录（W5-G 接入发现）。 */
+    agentDirs?: string[];
     hooksFile?: string;
     authFile?: string;
     /** false：key 只来自 authFile。 */

package/dist/config/profile.js

@@ -51,6 +51,8 @@ function profileToOptions(path, profile, warnings) {
         trustProject: profile.trustProject === true,
         warnings: [...warnings],
     };
+    if (profile.agentDirs !== undefined)
+        options.agentDirs = [...profile.agentDirs];
     if (profile.host !== undefined)
         options.host = profile.host;
     if (profile.hooksFile !== undefined)

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

@@ -0,0 +1,18 @@
+/**
+ * 第五波配置键的校验（docs/wave5-plan.md §9；schema.ts 已近 600 行，新键放这里）。[W5-C0]
+ *
+ * 规则与 json-schema.ts 一一对应（json-schema.test.ts 的正反例守住）：类型 / 取值错误是 error，
+ * 未知字段是 warning。只校验形状；行为由各批次实现。
+ */
+import { Checker, type Obj } from "./checker.js";
+/** 第五波新增的顶层键（schema.ts 的 CONFIG_KEYS 并入）。 */
+export declare const W5_CONFIG_KEYS: readonly ["images", "plan", "agents", "subagents", "models", "fallbackModel", "limits", "reminders", "todo"];
+/** 已有段新增的键。 */
+export declare const W5_UI_KEYS: readonly ["statusLine"];
+export declare const W5_COMPACTION_KEYS: readonly ["prune", "pruneExclude"];
+/** `agents.<id>` 的 id：子 Agent 名（`^[a-z0-9-]`）或外部 Agent（可带 `acp:` 前缀）。 */
+export declare const AGENT_ID_PATTERN: RegExp;
+export declare function checkUiW5(c: Checker, ui: Obj, path: string): void;
+export declare function checkCompactionW5(c: Checker, compaction: Obj, path: string): void;
+/** 第五波顶层段的校验（validateConfig 末尾调用）。 */
+export declare function validateConfigW5(c: Checker, config: Obj): void;

package/dist/config/schema-w5.js

@@ -0,0 +1,109 @@
+/**
+ * 第五波配置键的校验（docs/wave5-plan.md §9；schema.ts 已近 600 行，新键放这里）。[W5-C0]
+ *
+ * 规则与 json-schema.ts 一一对应（json-schema.test.ts 的正反例守住）：类型 / 取值错误是 error，
+ * 未知字段是 warning。只校验形状；行为由各批次实现。
+ */
+import { PERMISSION_MODES_STRICT_FIRST } from "../permissions/types.js";
+import { Checker, THINKING_LEVELS, checkSection, join } from "./checker.js";
+import { AGENTS_RESERVED_KEYS, IMAGE_RESIZE_MODES, PLAN_BASH_MODES_STRICT_FIRST, PLAN_UNATTENDED_MODES, STATUS_LINE_MODES, } from "./types-w5.js";
+/** 第五波新增的顶层键（schema.ts 的 CONFIG_KEYS 并入）。 */
+export const W5_CONFIG_KEYS = [
+    "images",
+    "plan",
+    "agents",
+    "subagents",
+    "models",
+    "fallbackModel",
+    "limits",
+    "reminders",
+    "todo",
+];
+/** 已有段新增的键。 */
+export const W5_UI_KEYS = ["statusLine"];
+export const W5_COMPACTION_KEYS = ["prune", "pruneExclude"];
+/** `agents.<id>` 的 id：子 Agent 名（`^[a-z0-9-]`）或外部 Agent（可带 `acp:` 前缀）。 */
+export const AGENT_ID_PATTERN = /^(acp:)?[a-z0-9][a-z0-9._-]{0,63}$/;
+const AGENT_ENTRY_KEYS = ["maxConcurrent", "maxMode", "model", "env"];
+export function checkUiW5(c, ui, path) {
+    c.oneOf(ui, "statusLine", path, STATUS_LINE_MODES);
+}
+export function checkCompactionW5(c, compaction, path) {
+    c.stringArray(compaction, "pruneExclude", path);
+    const prune = compaction["prune"];
+    const p = join(path, "prune");
+    if (prune === undefined || !c.object(prune, p))
+        return;
+    c.keys(prune, p, ["keepResults", "clearAtLeast"]);
+    c.number(prune, "keepResults", p, 0);
+    const clear = prune["clearAtLeast"];
+    if (clear !== undefined && clear !== "auto" && (typeof clear !== "number" || clear < 0))
+        c.error(join(p, "clearAtLeast"), '应为 "auto" 或非负数字');
+}
+function checkAgentEntry(c, entry, path) {
+    if (!c.object(entry, path))
+        return;
+    c.keys(entry, path, AGENT_ENTRY_KEYS);
+    c.number(entry, "maxConcurrent", path, 1, 64);
+    c.oneOf(entry, "maxMode", path, PERMISSION_MODES_STRICT_FIRST);
+    c.string(entry, "model", path);
+    const env = entry["env"];
+    const envPath = join(path, "env");
+    if (env !== undefined && c.object(env, envPath)) {
+        c.keys(env, envPath, ["passthrough"]);
+        c.stringArray(env, "passthrough", envPath);
+    }
+}
+function checkAgents(c, config) {
+    const agents = config["agents"];
+    if (agents === undefined || !c.object(agents, "agents"))
+        return;
+    c.number(agents, "maxConcurrent", "agents", 1, 64);
+    c.number(agents, "sessionBudgetUsd", "agents", 0);
+    c.stringArray(agents, "dirs", "agents");
+    for (const [id, entry] of Object.entries(agents)) {
+        if (AGENTS_RESERVED_KEYS.includes(id))
+            continue;
+        const p = join("agents", id);
+        if (!AGENT_ID_PATTERN.test(id))
+            c.error(p, "Agent id 只能是小写字母、数字、- . _（可带 acp: 前缀）");
+        else
+            checkAgentEntry(c, entry, p);
+    }
+}
+/** 第五波顶层段的校验（validateConfig 末尾调用）。 */
+export function validateConfigW5(c, config) {
+    checkSection(c, config, "images", ["resize"], (s, p) => c.oneOf(s, "resize", p, IMAGE_RESIZE_MODES));
+    checkSection(c, config, "plan", ["bash", "directory", "unattended", "model", "thinkingLevel"], (s, p) => {
+        c.oneOf(s, "bash", p, PLAN_BASH_MODES_STRICT_FIRST);
+        c.string(s, "directory", p);
+        c.oneOf(s, "unattended", p, PLAN_UNATTENDED_MODES);
+        c.string(s, "model", p);
+        c.oneOf(s, "thinkingLevel", p, THINKING_LEVELS);
+    });
+    checkAgents(c, config);
+    checkSection(c, config, "subagents", ["maxConcurrent", "maxPending", "defaultModel"], (s, p) => {
+        c.number(s, "maxConcurrent", p, 1, 64);
+        c.number(s, "maxPending", p, 0, 1024);
+        c.string(s, "defaultModel", p);
+    });
+    checkSection(c, config, "models", ["aliases"], (s, p) => {
+        const aliases = s["aliases"];
+        const ap = join(p, "aliases");
+        if (aliases === undefined || !c.object(aliases, ap))
+            return;
+        c.keys(aliases, ap, ["fast", "strong"]);
+        c.string(aliases, "fast", ap);
+        c.string(aliases, "strong", ap);
+    });
+    c.string(config, "fallbackModel", "");
+    checkSection(c, config, "limits", ["maxTurns", "maxCostUsd"], (s, p) => {
+        c.number(s, "maxTurns", p, 1);
+        c.number(s, "maxCostUsd", p, 0);
+    });
+    checkSection(c, config, "reminders", ["todo", "fileChanges", "contextPressure", "budget"], (s, p) => {
+        for (const key of ["todo", "fileChanges", "contextPressure", "budget"])
+            c.boolean(s, key, p);
+    });
+    checkSection(c, config, "todo", ["reminder"], (s, p) => c.number(s, "reminder", p, 0));
+}

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, 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[];