@armadra/agent 0.3.0 → 0.5.0

package/dist/tui/glyphs.js

@@ -0,0 +1,118 @@
+/**
+ * 字形表与 ASCII 回退（终端界面视觉设计 v1 §2.2）。
+ *
+ * 所有组件通过 `theme.glyphs` 取字形，不另加参数；`UNICODE_GLYPHS` 里每个字形都是 1 列宽
+ * （`codePointWidth` 判定，与 wcwidth 一致；个别字体把 `⏺` 画成两格时用 `AMA_ASCII=1`）。
+ *
+ * ASCII 触发：`ui.ascii: true` / `AMA_ASCII=1`，或自动检测——区域设置（`LC_ALL` > `LC_CTYPE` > `LANG`）
+ * 已设置但不含 UTF-8、`TERM=linux`、Windows 上 `WT_SESSION` 与 `TERM_PROGRAM` 都为空（旧 conhost）。
+ * `AMA_ASCII=0` 强制 Unicode。区域变量都没设时按 Unicode 处理（容器与 CI 里常见）。
+ */
+export const UNICODE_GLYPHS = {
+    ascii: false,
+    prompt: "›",
+    tool: "⏺",
+    result: "⎿",
+    ok: "✓",
+    fail: "✗",
+    warn: "!",
+    thinking: "✻",
+    queued: "↳",
+    retry: "↻",
+    blocked: "⛔",
+    card: "▎",
+    expand: "▸",
+    collapse: "▾",
+    warm: "♨",
+    check: "✓",
+    bullets: ["•", "◦", "▪"],
+    meterFull: "▮",
+    meterEmpty: "▯",
+    box: {
+        topLeft: "╭",
+        topRight: "╮",
+        bottomLeft: "╰",
+        bottomRight: "╯",
+        vertical: "│",
+        horizontal: "─",
+    },
+    rule: "─",
+    spinner: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+    spinnerStatic: "·",
+    ellipsis: "…",
+    arrowUp: "↑",
+    arrowDown: "↓",
+    branch: "⎇",
+    dot: "•",
+};
+export const ASCII_GLYPHS = {
+    ascii: true,
+    prompt: ">",
+    tool: "*",
+    result: "L",
+    ok: "v",
+    fail: "x",
+    warn: "!",
+    thinking: "~",
+    queued: "->",
+    retry: "@",
+    blocked: "X",
+    card: "|",
+    expand: ">",
+    collapse: "v",
+    warm: "~",
+    check: "v",
+    bullets: ["-", "*", "+"],
+    meterFull: "#",
+    meterEmpty: ".",
+    box: {
+        topLeft: "+",
+        topRight: "+",
+        bottomLeft: "+",
+        bottomRight: "+",
+        vertical: "|",
+        horizontal: "-",
+    },
+    rule: "-",
+    spinner: ["-", "\\", "|", "/"],
+    spinnerStatic: ".",
+    ellipsis: "...",
+    arrowUp: "^",
+    arrowDown: "v",
+    branch: "git",
+    dot: "*",
+};
+function truthy(value) {
+    if (value === undefined || value === "")
+        return undefined;
+    const v = value.toLowerCase();
+    if (v === "1" || v === "true" || v === "yes" || v === "on")
+        return true;
+    if (v === "0" || v === "false" || v === "no" || v === "off")
+        return false;
+    return undefined;
+}
+/** 由环境判断是否用 ASCII 字形（`AMA_ASCII` 优先）。 */
+export function detectAscii(env = process.env, platform = process.platform) {
+    const forced = truthy(env["AMA_ASCII"]);
+    if (forced !== undefined)
+        return forced;
+    const locale = env["LC_ALL"] || env["LC_CTYPE"] || env["LANG"] || "";
+    if (locale !== "" && !/utf-?8/i.test(locale))
+        return true;
+    if ((env["TERM"] ?? "") === "linux")
+        return true;
+    if (platform === "win32" && !env["WT_SESSION"] && !env["TERM_PROGRAM"])
+        return true;
+    return false;
+}
+/** 配置与环境合并：`AMA_ASCII` 显式值 > `ui.ascii` > 自动检测。 */
+export function resolveAscii(configured, env = process.env, platform = process.platform) {
+    const forced = truthy(env["AMA_ASCII"]);
+    if (forced !== undefined)
+        return forced;
+    return configured ?? detectAscii(env, platform);
+}
+export function glyphsFor(ascii) {
+    return ascii ? ASCII_GLYPHS : UNICODE_GLYPHS;
+}

package/dist/tui/keybindings.d.ts

@@ -31,6 +31,7 @@ export declare const DEFAULT_KEYBINDINGS: {
     readonly "tui.select.confirm": readonly ["enter", "tab"];
     readonly "tui.select.cancel": readonly ["escape", "ctrl+c"];
     readonly "app.interrupt": readonly ["escape"];
+    readonly "app.rewind": readonly ["escape"];
     readonly "app.clear": readonly ["ctrl+c"];
     readonly "app.exit": readonly ["ctrl+d"];
     readonly "app.message.followUp": readonly ["alt+enter"];
@@ -39,6 +40,10 @@ export declare const DEFAULT_KEYBINDINGS: {
     readonly "app.tools.expand": readonly ["ctrl+o"];
     readonly "app.model.select": readonly ["ctrl+l"];
     readonly "app.thinking.select": readonly ["ctrl+t"];
+    /** [W5-A] 底部信息行 full ↔ compact（只影响本会话）。 */
+    readonly "app.statusLine.toggle": readonly ["ctrl+g"];
+    /** [W5-U] 粘贴剪贴板图片（写进数据目录，输入框插入 `@路径`）。 */
+    readonly "app.paste.image": readonly ["ctrl+v"];
 };
 export type ActionId = keyof typeof DEFAULT_KEYBINDINGS;
 export type KeybindingOverrides = Partial<Record<ActionId, readonly string[]>>;

package/dist/tui/keybindings.js

@@ -33,6 +33,7 @@ export const DEFAULT_KEYBINDINGS = {
     "tui.select.confirm": ["enter", "tab"],
     "tui.select.cancel": ["escape", "ctrl+c"],
     "app.interrupt": ["escape"],
+    "app.rewind": ["escape"],
     "app.clear": ["ctrl+c"],
     "app.exit": ["ctrl+d"],
     "app.message.followUp": ["alt+enter"],
@@ -41,6 +42,10 @@ export const DEFAULT_KEYBINDINGS = {
     "app.tools.expand": ["ctrl+o"],
     "app.model.select": ["ctrl+l"],
     "app.thinking.select": ["ctrl+t"],
+    /** [W5-A] 底部信息行 full ↔ compact（只影响本会话）。 */
+    "app.statusLine.toggle": ["ctrl+g"],
+    /** [W5-U] 粘贴剪贴板图片（写进数据目录，输入框插入 `@路径`）。 */
+    "app.paste.image": ["ctrl+v"],
 };
 export function isActionId(id) {
     return Object.prototype.hasOwnProperty.call(DEFAULT_KEYBINDINGS, id);

package/dist/tui/theme.d.ts

@@ -1,8 +1,11 @@
 /**
  * 主题与颜色能力（设计 §12.7）。[B4]
  *
- * - `dark` / `light` 两套语义色（§12.7 的 11 个名字），以 24 位 RGB 定义。
- * - 能力降级：truecolor → 256 色（6×6×6 立方 + 灰阶取近）→ 16 色（xterm 缺省调色板取近）→ 无色。
+ * - `dark` / `light` 两套语义色（14 个名字，终端界面视觉设计 v1 §2.1），以 24 位 RGB 定义；取值都落在
+ *   xterm 256 色立方 / 灰阶上，所以 256 色回退无损。
+ * - 能力降级：truecolor → 256 色（6×6×6 立方 + 灰阶取近）→ 16 色（内置色板按 `THEME_ANSI16` 查表，
+ *   覆盖色按 xterm 缺省调色板取近）→ 无色。
+ * - `bg("selection")` 在 < 256 色时退化为 `accent` 粗体前景（16 色下底色太跳，且常留「尾巴」）。
  * - `NO_COLOR`（非空）或 `TERM=dumb` → 无色；不探测终端背景（不发查询序列）。
  * - 样式用各自的关闭码（39 / 49 / 22 / 23 / 24）而不是全重置，可以嵌套。
  */
@@ -10,6 +13,21 @@ import type { ColorDepth, SemanticColor, Theme, ThemeCapabilities } from "./comp
 export type ThemeName = "dark" | "light";
 type Rgb = readonly [number, number, number];
 export declare const THEME_PALETTES: Record<ThemeName, Record<SemanticColor, string>>;
+/**
+ * 16 色下的索引（xterm 0–15）。距离取近对饱和色不可靠（`#ff5f5f` 会落到灰 8），所以内置色板查表；
+ * `selection` 在 16 色下不作 bg，表里给前景兜底值。
+ */
+export declare const THEME_ANSI16: Record<ThemeName, Record<SemanticColor, number>>;
+/** 阈值档位：≥ dangerAt error，≥ warnAt warning，否则 success（状态栏 ctx、Meter、/session 共用）。 */
+export declare function levelColor(ratio: number, thresholds?: {
+    warnAt?: number;
+    dangerAt?: number;
+}): SemanticColor;
+/**
+ * `auto` → dark / light：不发查询序列，只看环境。`COLORFGBG` 的最后一段是背景色号（0–6、8 暗，
+ * 7、9–15 亮）；没有时 Apple Terminal 按 dark；其余缺省 dark。只是猜，文档建议显式配置。
+ */
+export declare function resolveThemeName(name: ThemeName | "auto" | undefined, env?: NodeJS.ProcessEnv): ThemeName;
 /** 由环境推断颜色深度。 */
 export declare function detectColorDepth(env?: NodeJS.ProcessEnv, isTTY?: boolean): ColorDepth;
 export declare function detectCapabilities(env?: NodeJS.ProcessEnv, isTTY?: boolean): ThemeCapabilities;
@@ -18,14 +36,20 @@ export declare function parseHex(hex: string): Rgb;
 export declare function rgbTo256(rgb: Rgb): number;
 /** RGB → 16 色索引（0–15）。 */
 export declare function rgbTo16(rgb: Rgb): number;
-/** 生成前景 / 背景开启序列；depth 0 返回空串。 */
-export declare function colorCode(hex: string, depth: ColorDepth, background: boolean): string;
+/**
+ * 生成前景 / 背景开启序列；depth 0 返回空串。`ansi16` 给定时 16 色下直接用它（内置色板查表）。
+ */
+export declare function colorCode(hex: string, depth: ColorDepth, background: boolean, ansi16?: number): string;
 export interface CreateThemeOptions {
     caps?: ThemeCapabilities;
     /** 覆盖部分语义色（`#rrggbb`）。 */
     overrides?: Partial<Record<SemanticColor, string>>;
+    /** ASCII 字形；缺省按环境检测（`detectAscii`）。 */
+    ascii?: boolean;
 }
 export declare function createTheme(name?: ThemeName, options?: CreateThemeOptions): Theme;
-/** 无色主题（测试、line 模式、NO_COLOR）：所有方法原样返回文本。 */
-export declare function plainTheme(): Theme;
+/** 无色主题（测试、line 模式、NO_COLOR）：所有方法原样返回文本；字形缺省 Unicode。 */
+export declare function plainTheme(options?: {
+    ascii?: boolean;
+}): Theme;
 export {};

package/dist/tui/theme.js

@@ -1,15 +1,20 @@
 /**
  * 主题与颜色能力（设计 §12.7）。[B4]
  *
- * - `dark` / `light` 两套语义色（§12.7 的 11 个名字），以 24 位 RGB 定义。
- * - 能力降级：truecolor → 256 色（6×6×6 立方 + 灰阶取近）→ 16 色（xterm 缺省调色板取近）→ 无色。
+ * - `dark` / `light` 两套语义色（14 个名字，终端界面视觉设计 v1 §2.1），以 24 位 RGB 定义；取值都落在
+ *   xterm 256 色立方 / 灰阶上，所以 256 色回退无损。
+ * - 能力降级：truecolor → 256 色（6×6×6 立方 + 灰阶取近）→ 16 色（内置色板按 `THEME_ANSI16` 查表，
+ *   覆盖色按 xterm 缺省调色板取近）→ 无色。
+ * - `bg("selection")` 在 < 256 色时退化为 `accent` 粗体前景（16 色下底色太跳，且常留「尾巴」）。
  * - `NO_COLOR`（非空）或 `TERM=dumb` → 无色；不探测终端背景（不发查询序列）。
  * - 样式用各自的关闭码（39 / 49 / 22 / 23 / 24）而不是全重置，可以嵌套。
  */
+import { detectAscii, glyphsFor } from "./glyphs.js";
 export const THEME_PALETTES = {
     dark: {
         text: "#e4e4e4",
-        dim: "#808080",
+        muted: "#a8a8a8",
+        dim: "#6c6c6c",
         accent: "#5fafff",
         success: "#5fd787",
         warning: "#ffd75f",
@@ -17,12 +22,15 @@ export const THEME_PALETTES = {
         user: "#87afff",
         assistant: "#e4e4e4",
         tool: "#af87ff",
-        border: "#5f5f5f",
+        border: "#585858",
         code: "#ffaf5f",
+        link: "#87d7ff",
+        selection: "#303030",
     },
     light: {
         text: "#1c1c1c",
-        dim: "#6c6c6c",
+        muted: "#585858",
+        dim: "#8a8a8a",
         accent: "#005fd7",
         success: "#008700",
         warning: "#af5f00",
@@ -30,10 +38,73 @@ export const THEME_PALETTES = {
         user: "#005faf",
         assistant: "#1c1c1c",
         tool: "#8700af",
-        border: "#a8a8a8",
+        border: "#bcbcbc",
         code: "#875f00",
+        link: "#0087af",
+        selection: "#e4e4e4",
+    },
+};
+/**
+ * 16 色下的索引（xterm 0–15）。距离取近对饱和色不可靠（`#ff5f5f` 会落到灰 8），所以内置色板查表；
+ * `selection` 在 16 色下不作 bg，表里给前景兜底值。
+ */
+export const THEME_ANSI16 = {
+    dark: {
+        text: 7,
+        muted: 7,
+        dim: 8,
+        accent: 12,
+        success: 10,
+        warning: 11,
+        error: 9,
+        user: 12,
+        assistant: 7,
+        tool: 13,
+        border: 8,
+        code: 11,
+        link: 14,
+        selection: 8,
+    },
+    light: {
+        text: 0,
+        muted: 8,
+        dim: 8,
+        accent: 4,
+        success: 2,
+        warning: 3,
+        error: 1,
+        user: 4,
+        assistant: 0,
+        tool: 5,
+        border: 7,
+        code: 3,
+        link: 6,
+        selection: 7,
     },
 };
+/** 阈值档位：≥ dangerAt error，≥ warnAt warning，否则 success（状态栏 ctx、Meter、/session 共用）。 */
+export function levelColor(ratio, thresholds = {}) {
+    if (ratio >= (thresholds.dangerAt ?? 0.9))
+        return "error";
+    if (ratio >= (thresholds.warnAt ?? 0.7))
+        return "warning";
+    return "success";
+}
+/**
+ * `auto` → dark / light：不发查询序列，只看环境。`COLORFGBG` 的最后一段是背景色号（0–6、8 暗，
+ * 7、9–15 亮）；没有时 Apple Terminal 按 dark；其余缺省 dark。只是猜，文档建议显式配置。
+ */
+export function resolveThemeName(name, env = process.env) {
+    if (name === "dark" || name === "light")
+        return name;
+    const colorfgbg = env["COLORFGBG"];
+    if (colorfgbg !== undefined && colorfgbg !== "") {
+        const bg = Number(colorfgbg.split(";").at(-1));
+        if (Number.isInteger(bg) && bg >= 0 && bg <= 15)
+            return bg === 7 || bg >= 9 ? "light" : "dark";
+    }
+    return "dark";
+}
 /** 由环境推断颜色深度。 */
 export function detectColorDepth(env = process.env, isTTY = process.stdout.isTTY === true) {
     if (env["NO_COLOR"] !== undefined && env["NO_COLOR"] !== "")
@@ -116,8 +187,10 @@ export function rgbTo16(rgb) {
     }
     return best;
 }
-/** 生成前景 / 背景开启序列；depth 0 返回空串。 */
-export function colorCode(hex, depth, background) {
+/**
+ * 生成前景 / 背景开启序列；depth 0 返回空串。`ansi16` 给定时 16 色下直接用它（内置色板查表）。
+ */
+export function colorCode(hex, depth, background, ansi16) {
     if (depth === 0)
         return "";
     const rgb = parseHex(hex);
@@ -125,23 +198,25 @@ export function colorCode(hex, depth, background) {
         return `\x1b[${background ? 48 : 38};2;${rgb[0]};${rgb[1]};${rgb[2]}m`;
     if (depth === 256)
         return `\x1b[${background ? 48 : 38};5;${rgbTo256(rgb)}m`;
-    const idx = rgbTo16(rgb);
+    const idx = ansi16 ?? rgbTo16(rgb);
     const base = idx < 8 ? (background ? 40 : 30) + idx : (background ? 100 : 90) + idx - 8;
     return `\x1b[${base}m`;
 }
 class PaletteTheme {
     name;
     caps;
+    glyphs;
     fgCodes;
     bgCodes;
-    constructor(name, palette, caps) {
+    constructor(name, palette, caps, glyphs, ansi16 = {}) {
         this.name = name;
         this.caps = caps;
+        this.glyphs = glyphs;
         const fg = {};
         const bg = {};
         for (const key of Object.keys(palette)) {
-            fg[key] = colorCode(palette[key], caps.colors, false);
-            bg[key] = colorCode(palette[key], caps.colors, true);
+            fg[key] = colorCode(palette[key], caps.colors, false, ansi16[key]);
+            bg[key] = colorCode(palette[key], caps.colors, true, ansi16[key]);
         }
         this.fgCodes = fg;
         this.bgCodes = bg;
@@ -151,6 +226,8 @@ class PaletteTheme {
         return code === "" ? text : `${code}${text}\x1b[39m`;
     }
     bg(color, text) {
+        if (color === "selection" && this.caps.colors < 256)
+            return this.bold(this.fg("accent", text));
         const code = this.bgCodes[color];
         return code === "" ? text : `${code}${text}\x1b[49m`;
     }
@@ -168,16 +245,25 @@ class PaletteTheme {
     }
 }
 export function createTheme(name = "dark", options = {}) {
-    const palette = { ...THEME_PALETTES[name], ...options.overrides };
-    return new PaletteTheme(name, palette, options.caps ?? detectCapabilities());
+    const overrides = options.overrides ?? {};
+    const palette = { ...THEME_PALETTES[name], ...overrides };
+    const ansi16 = { ...THEME_ANSI16[name] };
+    for (const key of Object.keys(overrides))
+        delete ansi16[key];
+    const glyphs = glyphsFor(options.ascii ?? detectAscii());
+    return new PaletteTheme(name, palette, options.caps ?? detectCapabilities(), glyphs, ansi16);
 }
-/** 无色主题（测试、line 模式、NO_COLOR）：所有方法原样返回文本。 */
-export function plainTheme() {
-    return new PlainTheme();
+/** 无色主题（测试、line 模式、NO_COLOR）：所有方法原样返回文本；字形缺省 Unicode。 */
+export function plainTheme(options = {}) {
+    return new PlainTheme(glyphsFor(options.ascii === true));
 }
 class PlainTheme {
+    glyphs;
     name = "plain";
     caps = { colors: 0 };
+    constructor(glyphs) {
+        this.glyphs = glyphs;
+    }
     fg(_color, text) {
         return text;
     }

package/dist/tui.d.ts

@@ -13,7 +13,8 @@ export { VirtualScreen, type ScreenModes } from "./tui/vt-screen.js";
 export { StdinBuffer, defaultEscTimeout, type StdinBufferOptions } from "./tui/stdin-buffer.js";
 export { parseKey, matchesKey, normalizeKeyId, isPasteData, unwrapPaste, isPrintableText, PASTE_START, PASTE_END, type KeyEvent, } from "./tui/keys.js";
 export { visibleWidth, truncateToWidth, sliceByColumn, wrapTextWithAnsi, padToWidth, stripAnsi, codePointWidth, graphemeWidth, SGR_RESET, } from "./tui/ansi.js";
-export { createTheme, plainTheme, detectCapabilities, detectColorDepth, colorCode, rgbTo256, rgbTo16, THEME_PALETTES, type ThemeName, type CreateThemeOptions, } from "./tui/theme.js";
+export { createTheme, plainTheme, detectCapabilities, detectColorDepth, colorCode, rgbTo256, rgbTo16, THEME_PALETTES, THEME_ANSI16, resolveThemeName, levelColor, type ThemeName, type CreateThemeOptions, } from "./tui/theme.js";
+export { UNICODE_GLYPHS, ASCII_GLYPHS, detectAscii, resolveAscii, glyphsFor, } from "./tui/glyphs.js";
 export { Keybindings, defaultKeybindings, DEFAULT_KEYBINDINGS, parseKeybindings, loadKeybindingsFile, isActionId, type ActionId, type KeybindingOverrides, type ParsedKeybindings, } from "./tui/keybindings.js";
 export { Container } from "./tui/components/container.js";
 export { Text, TruncatedText, type TextOptions } from "./tui/components/text.js";
@@ -23,8 +24,9 @@ export { Editor, loadHistoryFile, type EditorOptions, type AutocompleteProvider,
 export { PasteStore, shouldCollapse, formatMarker, PASTE_LINE_THRESHOLD, PASTE_CHAR_THRESHOLD, } from "./tui/components/editor-paste.js";
 export { SelectList, filterItems, type SelectItem, type SelectListOptions, } from "./tui/components/select-list.js";
 export { Box, type BoxOptions } from "./tui/components/box.js";
+export { Card, type CardOptions } from "./tui/components/card.js";
 export { Spacer } from "./tui/components/spacer.js";
-export { Loader, LOADER_FRAMES, formatElapsed, type LoaderOptions, } from "./tui/components/loader.js";
+export { Loader, LOADER_FRAMES, formatElapsed, type LoaderOptions, type LoaderVerbOptions, } from "./tui/components/loader.js";
 export { compositeOverlays, type OverlayAnchor, type OverlayOptions, type OverlayLayer, } from "./tui/components/overlay.js";
 export { KeyValue, type KeyValueRow, type KeyValueOptions } from "./tui/components/key-value.js";
 export { Meter, METER_FULL, METER_EMPTY, type MeterOptions } from "./tui/components/meter.js";

package/dist/tui.js

@@ -13,7 +13,8 @@ export { VirtualScreen } from "./tui/vt-screen.js";
 export { StdinBuffer, defaultEscTimeout } from "./tui/stdin-buffer.js";
 export { parseKey, matchesKey, normalizeKeyId, isPasteData, unwrapPaste, isPrintableText, PASTE_START, PASTE_END, } from "./tui/keys.js";
 export { visibleWidth, truncateToWidth, sliceByColumn, wrapTextWithAnsi, padToWidth, stripAnsi, codePointWidth, graphemeWidth, SGR_RESET, } from "./tui/ansi.js";
-export { createTheme, plainTheme, detectCapabilities, detectColorDepth, colorCode, rgbTo256, rgbTo16, THEME_PALETTES, } from "./tui/theme.js";
+export { createTheme, plainTheme, detectCapabilities, detectColorDepth, colorCode, rgbTo256, rgbTo16, THEME_PALETTES, THEME_ANSI16, resolveThemeName, levelColor, } from "./tui/theme.js";
+export { UNICODE_GLYPHS, ASCII_GLYPHS, detectAscii, resolveAscii, glyphsFor, } from "./tui/glyphs.js";
 export { Keybindings, defaultKeybindings, DEFAULT_KEYBINDINGS, parseKeybindings, loadKeybindingsFile, isActionId, } from "./tui/keybindings.js";
 export { Container } from "./tui/components/container.js";
 export { Text, TruncatedText } from "./tui/components/text.js";
@@ -23,6 +24,7 @@ export { Editor, loadHistoryFile, } from "./tui/components/editor.js";
 export { PasteStore, shouldCollapse, formatMarker, PASTE_LINE_THRESHOLD, PASTE_CHAR_THRESHOLD, } from "./tui/components/editor-paste.js";
 export { SelectList, filterItems, } from "./tui/components/select-list.js";
 export { Box } from "./tui/components/box.js";
+export { Card } from "./tui/components/card.js";
 export { Spacer } from "./tui/components/spacer.js";
 export { Loader, LOADER_FRAMES, formatElapsed, } from "./tui/components/loader.js";
 export { compositeOverlays, } from "./tui/components/overlay.js";

package/docs/acp.md

@@ -0,0 +1,78 @@
+# ACP（Agent Client Protocol）
+
+ama 在 ACP 两侧都能用：
+
+- **服务端**：`ama --mode acp` 把 ama 暴露为 ACP Agent，供 Zed、JetBrains、Armadra 的 ACP 节点驱动；
+- **客户端**：ama 经 ACP 驱动外部 Agent（Gemini CLI、OpenCode、Kimi、Copilot 等原生 ACP，或装了适配器的 Claude Code / Codex），见 [agents.md](agents.md)。
+
+协议栈零依赖、手写，只维护一份：`@armadra/agent/acp` 导出类型、分帧、客户端与假 Agent，Armadra 直接复用。设计依据见 [wave5-plan.md](wave5-plan.md) §5（D14）。
+
+## 线路
+
+JSON-RPC 2.0 over NDJSON（stdio）：只按 `\n` 切行，64 KiB 分片写并等待背压，与 [rpc.md](rpc.md) 的「线路」一致。stdout 只有协议行，诊断写 stderr。由客户端以 `initialize` 起头，没有 `hello`。
+
+## `ama --mode acp`
+
+```sh
+ama --mode acp                      # 与 -p 互斥；其余参数（--model、--profile、--trust 等）照常
+```
+
+| 方法                     | ama 的行为                                                                                                                                                        |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `initialize`             | `protocolVersion: 1`；`loadSession: true`，`sessionCapabilities: { list, resume, close }`，`promptCapabilities: { image: true, embeddedContext: true }`；不要认证 |
+| `session/new`            | 新开会话（启动时那个空会话第一次直接认领）；`cwd` 必须是 ama 的启动目录（按 realpath 比较），否则 invalid params                                                  |
+| `session/load`           | 切到该会话并以 `session/update` 回放历史（用户消息、回复、思考、工具调用）                                                                                        |
+| `session/resume`         | 切到该会话，不回放                                                                                                                                                |
+| `session/list`           | 启动目录下的会话（标题取会话名或首条提示）                                                                                                                        |
+| `session/close`          | 中断运行并释放活动会话                                                                                                                                            |
+| `session/prompt`         | 文本与图片照收；`resource_link` 以 `@uri` 文本给出，嵌入资源取文本。回合结束：中断 → `cancelled`，输出截断 → `max_tokens`，出错 → JSON-RPC 错误                   |
+| `session/cancel`（通知） | 中断当前回合                                                                                                                                                      |
+| `session/set_mode`       | 模式 id 就是 ama 的权限模式（`plan`、`allowlist`、`default`、`auto-edit`、`auto`、`full-auto`）                                                                   |
+
+一次只有一个活动会话；对非活动会话发 `session/prompt` 时（空闲）先切过去，运行中切换报 invalid request。
+
+### 事件映射
+
+| ama                 | `session/update`                                                                   |
+| ------------------- | ---------------------------------------------------------------------------------- |
+| 文本增量 / 思考增量 | `agent_message_chunk` / `agent_thought_chunk`                                      |
+| 模型发出工具调用    | `tool_call`（`pending`，带 `rawInput`、`kind`、`locations`）                       |
+| 工具开始 / 结束     | `tool_call_update`（`in_progress` → `completed` / `failed`，结果只带前 4 KB 文本） |
+| `todo` 更新         | `plan`                                                                             |
+| 每轮结束            | `usage_update`（上下文已用、窗口、会话累计美元）                                   |
+| 权限模式变化        | `current_mode_update`                                                              |
+
+codemode 内层调用不单列。`session/prompt` 的结果带本回合 token 用量（`inputTokens`、`outputTokens`、`cachedReadTokens`、`cachedWriteTokens`、`totalTokens`）。
+
+### 审批
+
+ama 需要询问的调用经 `session/request_permission` 交给客户端，三个选项：`allow_once`（允许）、`allow_always`（本会话允许）、`reject_once`（拒绝）。`toolCall.toolCallId` 关联到先前 `tool_call` 的 id。客户端回 `cancelled`、连接断开或回合被中断时，按无人作答处理（拒绝）。auto 模式下 ama 自己的分类器照常工作——这只影响 ama 自己的工具；ama 驱动的外部 Agent 发来的请求只交给人（见 [agents.md](agents.md)）。
+
+不声明、也不使用客户端的 `fs` / `terminal` 能力：ama 自己读写、自己跑命令，按自己的权限管线。
+
+### 退出
+
+stdin 关闭后等已开始的运行结束再退出（0）；SIGINT / SIGTERM 中断后退出 130 / 143。宿主看到的模式是 `rpc`（`HostApi.mode`）。SDK 直接 `bootstrap(--mode acp)` 时得到 `mode: "rpc"` 的 Runtime，再交给 `runAcpMode`。
+
+## 作为客户端
+
+模型经 `task(agent="acp:<程序>")` 使用 ACP Agent（ama 自己是 `task(agent="acp:ama")`，见 [agents.md](agents.md)「在 task 里使用」）。
+
+`AcpClient`（`@armadra/agent/acp`）：`initialize`、`newSession`、`resumeSession`（优先，不回放）、`loadSession`、`listSessions`、`closeSession`、`prompt`、`setMode`、`cancel`。
+
+- 声明的客户端能力为空：Agent 发来的 `fs/*`、`terminal/*` 请求回 method not found。
+- `session/request_permission` 交给 `onPermission`；没有处理器时回首个 `reject_once`（无人值守）。
+- `cancel(sessionId)` 发 `session/cancel`，并让该会话挂起的权限请求回 `cancelled`（规范要求）。
+- 只接受 Agent 自己给出的 `optionId`。
+
+`AcpDriver` 在客户端之上实现驱动契约（`AgentDriver`）：续接优先 `session/resume`，其次 `session/load`（回放的历史丢弃），都不支持就新开并提示；按 ama 模式 `session/set_mode`，只读模式找不到对应模式 id 时拒绝启动。
+
+## 测试替身
+
+`runFakeAcpAgent(input, output)` 是进程内的假 ACP Agent，`fakeAcpAgentPath()` 是它的可执行入口（`node <path> [--minimal]`）。行为由提示里的标记决定：`[permission]`（请求权限，四个选项）、`[slow]`（等到 cancel）、`[plan]`、`[think]`、`[refuse]`，其余回 `echo: <文本>`。`--minimal` 不声明 resume / load / list / close，也不给模式，用来测降级路径。
+
+黄金记录在 `test/fixtures/acp/`：`driver-{allow,reject,cancel}.jsonl`（ama 驱动假 Agent 的三条路径）与 `mode-prompt.jsonl`（`ama --mode acp` 一轮往返）。`UPDATE_GOLDEN=1` 重写。
+
+## 兼容性
+
+按 ACP v1（含 2026 年稳定的 `session/list`、`session/resume`、`session/close`、`usage_update`）。v2 计划取消 `session/load`，ama 作客户端时已优先 `resume`。