@armadra/agent 0.3.0 → 0.5.0

package/dist/checkpoints/shadow-restore.js

@@ -0,0 +1,128 @@
+/**
+ * 按影子提交恢复代码（docs/rewind-plan.md §6）。[RW-D]
+ *
+ * 1. 把当前工作区写成树，与目标提交做 `diff-tree`：只处理有差异的文件，被忽略的文件不在两边的树里，不会被碰。
+ *    目标里有、当前树里没有但磁盘上还在的文件（现在被忽略了）跳过。
+ * 2. 每个差异文件交给 `restore.ts` 的 `restoreFile`，冲突与安全检查语义与 tools 模式相同：
+ *    - 「已知」= 当前内容等于最近一个影子提交里的内容，或等于 ama 最后写入的、最近检查点记录的；
+ *      其余视为回合外的改动（冲突），缺省跳过。
+ *    - 父目录应为 `realpath(cwd)/<相对目录>`（路径上有符号链接目录 → parent_moved）。
+ *    - 目标是符号链接 / 子模块 → not_regular；目标 blob 超过 maxFileBytes → too_large。
+ *    - 权限只在可执行位与目标不同时调整（git 只记 644 / 755），新建文件按目标的可执行位。
+ * 3. edit / write 跟踪的文件不在影子树里（cwd 外、被忽略）时，按 tools 的记录恢复。
+ */
+import { lstat, realpath } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { DEFAULT_MAX_FILE_BYTES, hashBytes, keyToPath } from "./blobs.js";
+import { latestCheckpoint } from "./replay.js";
+import { emptyCodeResult, restoreCheckpoint, restoreFile, settleFile, } from "./restore.js";
+import { MODE_ABSENT, MODE_EXECUTABLE, MODE_GITLINK, MODE_SYMLINK, } from "./shadow-git.js";
+const IS_WINDOWS = process.platform === "win32";
+/** 文件顺序上最后一个带影子提交的检查点。 */
+export function latestShadowCommit(state) {
+    for (let i = state.order.length - 1; i >= 0; i--) {
+        const commit = state.byUserEntry.get(state.order[i])?.shadowCommit;
+        if (commit !== undefined)
+            return commit;
+    }
+    return undefined;
+}
+/** 目标检查点没有影子提交、或提交已不在影子仓库里时抛错（调用方回退到 tools）。 */
+export async function restoreFromShadow(options) {
+    const { repo } = options;
+    const target = options.target.shadowCommit;
+    if (target === undefined)
+        throw new Error("检查点没有影子提交");
+    if (!(await repo.hasCommit(target)))
+        throw new Error(`影子提交 ${target.slice(0, 12)} 不存在`);
+    const maxBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+    const current = await repo.currentTree();
+    const changes = (await repo.diff(target, current)).filter((c) => c.oldMode !== MODE_GITLINK && c.newMode !== MODE_GITLINK);
+    const baseline = latestShadowCommit(options.state);
+    const changedSinceBaseline = baseline === undefined ? undefined : new Set((await repo.diff(baseline, current)).map(pathOf));
+    const blobs = await repo.readBlobs(changes.filter((c) => isRegularMode(c.oldMode)).map((c) => c.oldOid), maxBytes);
+    const realCwd = await realpath(options.cwd);
+    const latest = latestCheckpoint(options.state);
+    const result = emptyCodeResult();
+    const touched = [];
+    for (const change of changes) {
+        const key = change.path;
+        const abs = keyToPath(options.cwd, key);
+        const record = await targetRecord(change, abs, realCwd, blobs);
+        if (record === undefined)
+            continue;
+        const known = new Set();
+        const written = options.lastWritten?.get(abs);
+        if (written !== undefined)
+            known.add(written);
+        const latestRecord = latest?.files[key];
+        if (latestRecord !== undefined && latestRecord.skipped === undefined) {
+            known.add(latestRecord.blob);
+        }
+        const content = record.blob === null ? undefined : blobs.get(change.oldOid);
+        await settleFile(result, touched, key, abs, options, () => restoreFile(abs, record, {
+            dataDir: options.dataDir,
+            ...(options.dryRun !== undefined ? { dryRun: options.dryRun } : {}),
+            ...(options.onConflict !== undefined ? { onConflict: options.onConflict } : {}),
+            maxDiff: options.maxDiffBytes ?? maxBytes,
+            isKnown: (hash) => (changedSinceBaseline !== undefined && !changedSinceBaseline.has(key)) || known.has(hash),
+            load: async () => content,
+        }));
+    }
+    // edit / write 跟踪、但不在影子树里的文件（cwd 外、被忽略）：按 tools 的记录恢复
+    const covered = new Set([...(await repo.paths(target)), ...(await repo.paths(current))]);
+    const rest = [...options.state.earliest.keys()].filter((k) => isAbsolute(k) || !covered.has(k));
+    if (rest.length > 0) {
+        const extra = await restoreCheckpoint({ ...options, keys: rest });
+        merge(result, extra.result);
+        touched.push(...extra.touched);
+    }
+    return { result, touched };
+}
+function pathOf(change) {
+    return change.path;
+}
+function isRegularMode(mode) {
+    return mode.startsWith("100");
+}
+/** 目标提交里这个路径应有的状态；undefined = 不处理。 */
+async function targetRecord(change, abs, realCwd, blobs) {
+    const slash = change.path.lastIndexOf("/");
+    const realParentDir = slash < 0 ? realCwd : join(realCwd, ...change.path.slice(0, slash).split("/"));
+    const info = await lstat(abs).catch(() => undefined);
+    if (change.newMode === MODE_ABSENT && info !== undefined) {
+        // 当前树里没有、磁盘上却有：现在被忽略了（或读不了），不碰
+        return undefined;
+    }
+    if (change.oldMode === MODE_ABSENT)
+        return { blob: null, realParentDir };
+    if (change.oldMode === MODE_SYMLINK || !isRegularMode(change.oldMode)) {
+        return { blob: null, skipped: "not_regular" };
+    }
+    const bytes = blobs.get(change.oldOid);
+    if (bytes === undefined)
+        return { blob: null, skipped: "too_large" };
+    const record = { blob: hashBytes(bytes), size: bytes.length, realParentDir };
+    const executable = change.oldMode === MODE_EXECUTABLE;
+    if (!IS_WINDOWS) {
+        if (info === undefined || !info.isFile())
+            record.mode = executable ? 0o755 : 0o644;
+        else {
+            const mode = info.mode & 0o7777;
+            const isExec = (mode & 0o111) !== 0;
+            if (isExec !== executable) {
+                record.mode = executable ? mode | ((mode & 0o444) >> 2) : mode & ~0o111;
+            }
+        }
+    }
+    return record;
+}
+function merge(into, from) {
+    into.restored.push(...from.restored);
+    into.deleted.push(...from.deleted);
+    into.conflicts.push(...from.conflicts);
+    into.skipped.push(...from.skipped);
+    into.failed.push(...from.failed);
+    into.insertions += from.insertions;
+    into.deletions += from.deletions;
+}

package/dist/checkpoints/tracker.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 检查点运行时状态（docs/rewind-plan.md §1.3、§2）。[RW-A]
+ *
+ * - `beforeWrite`：文件在任何检查点里都没出现过 → 备份当前内容、追加 `ama.checkpoint-track`、
+ *   加入已跟踪；出现过则什么都不做。失败只 warn，不抛（检查点是辅助，不能让编辑失败）。
+ * - `afterWrite`：记 `lastWritten`（ama 最后写入内容的 sha256，冲突检测用；只在内存）。
+ * - `snapshot(userEntryId)`：新回合用户消息落盘后，对每个已跟踪文件按 §2 第一行的规则重拍，追加
+ *   `ama.checkpoint`。沿用判断：size / mode 与上一条一致且 mtime 早于记录时间减去
+ *   `MTIME_GRANULARITY_MS`（文件系统时间戳粒度的余量）；否则算哈希，相同仍沿用。
+ * - 只经注入的 `append(customType, data)` 写条目，不依赖会话实现。
+ */
+import { type LoadedCheckpoints } from "./replay.js";
+import { type CheckpointData, type CheckpointHooks } from "./types.js";
+/** mtime 粒度余量（FAT 2 s；其它文件系统更细）。 */
+export declare const MTIME_GRANULARITY_MS = 2000;
+export interface CheckpointTrackerOptions {
+    cwd: string;
+    dataDir: string;
+    /** 缺省 5 MiB。 */
+    maxFileBytes?: number;
+    /** 追加 custom 条目（`ama.checkpoint` / `ama.checkpoint-track`）。 */
+    append(customType: string, data: unknown): void;
+    /** 当前回合的用户消息 id；不给时用最近一次 `snapshot` 的 id。 */
+    currentTurn?(): string | undefined;
+    warn?(message: string): void;
+    /** 从会话条目重放的状态（`loadCheckpoints`）；缺省为空。 */
+    initial?: LoadedCheckpoints;
+    /** 测试用。 */
+    now?(): number;
+    /** 测试用：读 HEAD（缺省 `readGitHead`）。 */
+    readHead?(cwd: string): Promise<{
+        head: string;
+        branch?: string;
+    } | undefined>;
+}
+export declare class CheckpointTracker implements CheckpointHooks {
+    readonly state: LoadedCheckpoints;
+    /** ama 最后一次写入后的内容哈希（绝对路径 → sha256）。 */
+    readonly lastWritten: Map<string, string>;
+    private readonly cwd;
+    private readonly dataDir;
+    private readonly maxFileBytes;
+    private readonly options;
+    private readonly inflight;
+    /** 记录的真实时间（键 → 毫秒）；覆盖条目时间（条目时间晚于读取，不能用于沿用判断以外）。 */
+    private readonly recordedAt;
+    private lastSnapshotId;
+    constructor(options: CheckpointTrackerOptions);
+    /** 已跟踪文件的绝对路径。 */
+    get trackedFiles(): ReadonlySet<string>;
+    isTracked(absolutePath: string): boolean;
+    private now;
+    private warn;
+    private currentTurn;
+    beforeWrite(absolutePath: string): Promise<void>;
+    private track;
+    afterWrite(absolutePath: string, content: Uint8Array | string): void;
+    /** 新回合：重拍全部已跟踪文件，追加 `ama.checkpoint`，返回它。`extra.shadowCommit` 来自影子 git。 */
+    snapshot(userEntryId: string, extra?: {
+        shadowCommit?: string;
+    }): Promise<CheckpointData>;
+    private snapshotFile;
+}
+export declare function createCheckpointTracker(options: CheckpointTrackerOptions): CheckpointTracker;

package/dist/checkpoints/tracker.js

@@ -0,0 +1,192 @@
+/**
+ * 检查点运行时状态（docs/rewind-plan.md §1.3、§2）。[RW-A]
+ *
+ * - `beforeWrite`：文件在任何检查点里都没出现过 → 备份当前内容、追加 `ama.checkpoint-track`、
+ *   加入已跟踪；出现过则什么都不做。失败只 warn，不抛（检查点是辅助，不能让编辑失败）。
+ * - `afterWrite`：记 `lastWritten`（ama 最后写入内容的 sha256，冲突检测用；只在内存）。
+ * - `snapshot(userEntryId)`：新回合用户消息落盘后，对每个已跟踪文件按 §2 第一行的规则重拍，追加
+ *   `ama.checkpoint`。沿用判断：size / mode 与上一条一致且 mtime 早于记录时间减去
+ *   `MTIME_GRANULARITY_MS`（文件系统时间戳粒度的余量）；否则算哈希，相同仍沿用。
+ * - 只经注入的 `append(customType, data)` 写条目，不依赖会话实现。
+ */
+import { lstat, readFile } from "node:fs/promises";
+import { readGitHead } from "./git-head.js";
+import { DEFAULT_MAX_FILE_BYTES, hashBytes, isNotFound, keyToPath, pathKey, putBlob, realParentOf, recordFile, } from "./blobs.js";
+import { applyCheckpoint, applyTrack, emptyCheckpoints } from "./replay.js";
+import { CHECKPOINT_CUSTOM_TYPE, CHECKPOINT_TRACK_CUSTOM_TYPE, } from "./types.js";
+/** mtime 粒度余量（FAT 2 s；其它文件系统更细）。 */
+export const MTIME_GRANULARITY_MS = 2_000;
+export class CheckpointTracker {
+    state;
+    /** ama 最后一次写入后的内容哈希（绝对路径 → sha256）。 */
+    lastWritten = new Map();
+    cwd;
+    dataDir;
+    maxFileBytes;
+    options;
+    inflight = new Map();
+    /** 记录的真实时间（键 → 毫秒）；覆盖条目时间（条目时间晚于读取，不能用于沿用判断以外）。 */
+    recordedAt = new Map();
+    lastSnapshotId;
+    constructor(options) {
+        this.options = options;
+        this.cwd = options.cwd;
+        this.dataDir = options.dataDir;
+        this.maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+        this.state = options.initial ?? emptyCheckpoints();
+        this.lastSnapshotId = this.state.order[this.state.order.length - 1];
+    }
+    /** 已跟踪文件的绝对路径。 */
+    get trackedFiles() {
+        return new Set([...this.state.earliest.keys()].map((key) => keyToPath(this.cwd, key)));
+    }
+    isTracked(absolutePath) {
+        return this.state.earliest.has(pathKey(this.cwd, absolutePath));
+    }
+    now() {
+        return this.options.now?.() ?? Date.now();
+    }
+    warn(message) {
+        this.options.warn?.(message);
+    }
+    currentTurn() {
+        return this.options.currentTurn !== undefined
+            ? this.options.currentTurn()
+            : this.lastSnapshotId;
+    }
+    async beforeWrite(absolutePath) {
+        const key = pathKey(this.cwd, absolutePath);
+        if (this.state.earliest.has(key))
+            return;
+        const pending = this.inflight.get(key);
+        if (pending !== undefined)
+            return pending;
+        const work = this.track(key, absolutePath).finally(() => this.inflight.delete(key));
+        this.inflight.set(key, work);
+        return work;
+    }
+    async track(key, absolutePath) {
+        try {
+            const { record, at } = await recordFile(absolutePath, {
+                dataDir: this.dataDir,
+                maxFileBytes: this.maxFileBytes,
+            });
+            if (this.state.earliest.has(key))
+                return;
+            const turn = this.currentTurn();
+            if (turn !== undefined) {
+                const data = { v: 1, userEntryId: turn, path: key, record };
+                this.options.append(CHECKPOINT_TRACK_CUSTOM_TYPE, data);
+                applyTrack(this.state, data, at);
+            }
+            else {
+                // 没有回合（宿主未接 snapshot）：只在内存里跟踪，下一次 snapshot 会把它收进检查点。
+                this.state.earliest.set(key, record);
+                this.state.latest.set(key, { record, at });
+            }
+            this.recordedAt.set(key, at);
+        }
+        catch (error) {
+            this.warn(`检查点：备份 ${key} 失败（${describe(error)}），本次写入不可回滚`);
+        }
+    }
+    afterWrite(absolutePath, content) {
+        try {
+            this.lastWritten.set(absolutePath, hashBytes(content));
+        }
+        catch (error) {
+            this.warn(`检查点：记录 ${absolutePath} 的写入失败（${describe(error)}）`);
+        }
+    }
+    /** 新回合：重拍全部已跟踪文件，追加 `ama.checkpoint`，返回它。`extra.shadowCommit` 来自影子 git。 */
+    async snapshot(userEntryId, extra = {}) {
+        this.lastSnapshotId = userEntryId;
+        const files = {};
+        const times = new Map();
+        for (const key of [...this.state.earliest.keys()]) {
+            const previous = this.state.latest.get(key);
+            const prev = previous === undefined
+                ? undefined
+                : { record: previous.record, at: this.recordedAt.get(key) ?? previous.at };
+            try {
+                const next = await this.snapshotFile(keyToPath(this.cwd, key), prev);
+                files[key] = next.record;
+                times.set(key, next.at);
+            }
+            catch (error) {
+                this.warn(`检查点：快照 ${key} 失败（${describe(error)}），该文件回滚到此处时用更早的记录`);
+            }
+        }
+        const data = { v: 1, userEntryId, files };
+        if (extra.shadowCommit !== undefined)
+            data.shadowCommit = extra.shadowCommit;
+        try {
+            const git = await (this.options.readHead ?? readGitHead)(this.cwd);
+            if (git !== undefined)
+                data.git = git;
+        }
+        catch {
+            // 读不到 HEAD 不影响检查点
+        }
+        this.options.append(CHECKPOINT_CUSTOM_TYPE, data);
+        applyCheckpoint(this.state, data, this.now());
+        for (const [key, at] of times)
+            this.recordedAt.set(key, at);
+        return data;
+    }
+    async snapshotFile(absolutePath, prev) {
+        const at = this.now();
+        let info;
+        try {
+            info = await lstat(absolutePath);
+        }
+        catch (error) {
+            if (!isNotFound(error))
+                throw error;
+            if (prev !== undefined && prev.record.blob === null && prev.record.skipped === undefined)
+                return prev;
+            const realParentDir = await realParentOf(absolutePath);
+            return {
+                record: { blob: null, ...(realParentDir !== undefined ? { realParentDir } : {}) },
+                at,
+            };
+        }
+        if (!info.isFile()) {
+            if (prev?.record.skipped === "not_regular")
+                return prev;
+            return { record: { blob: null, skipped: "not_regular" }, at };
+        }
+        const mode = info.mode & 0o7777;
+        const p = prev?.record;
+        const sameMeta = p !== undefined && p.blob !== null && p.size === info.size && p.mode === mode;
+        if (sameMeta && prev !== undefined && info.mtimeMs <= prev.at - MTIME_GRANULARITY_MS)
+            return prev;
+        const realParentDir = await realParentOf(absolutePath);
+        const base = {
+            mode,
+            size: info.size,
+            ...(realParentDir !== undefined ? { realParentDir } : {}),
+        };
+        if (info.size > this.maxFileBytes) {
+            if (p?.skipped === "too_large" && p.size === info.size && p.mode === mode)
+                return prev;
+            return { record: { blob: null, ...base, skipped: "too_large" }, at };
+        }
+        const bytes = await readFile(absolutePath);
+        const hash = hashBytes(bytes);
+        if (p !== undefined &&
+            p.blob === hash &&
+            p.mode === mode &&
+            p.realParentDir === realParentDir) {
+            return { record: p, at };
+        }
+        await putBlob(this.dataDir, bytes, hash);
+        return { record: { blob: hash, ...base, size: bytes.length }, at };
+    }
+}
+export function createCheckpointTracker(options) {
+    return new CheckpointTracker(options);
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/checkpoints/types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 检查点与回滚契约（docs/rewind-plan.md §1、§3）。契约文件，实现归 RW-A（`src/checkpoints/**`）
+ * 与 RW-B（`src/agent/session-rewind.ts`）。
+ *
+ * - 会话条目两类，均为 `custom`（不进上下文）：`ama.checkpoint`（新回合的用户消息之后）与
+ *   `ama.checkpoint-track`（回合中途第一次碰某文件，补进本回合检查点）。
+ * - 备份按内容 sha256 存 `<dataDir>/file-history/blobs/<前 2 位>/<全长>`，会话只记哈希。
+ * - 路径键：cwd 内为相对路径（`/` 分隔），cwd 外为绝对路径。
+ */
+import type { ImageBlock } from "../ai/types.js";
+export declare const CHECKPOINT_CUSTOM_TYPE = "ama.checkpoint";
+export declare const CHECKPOINT_TRACK_CUSTOM_TYPE = "ama.checkpoint-track";
+export declare const REWIND_NOTE_CUSTOM_TYPE = "ama.rewind-note";
+export type CheckpointMode = "tools" | "shadow-git" | "off";
+export interface FileRecord {
+    /** 内容 sha256；null = 当时文件不存在（回滚时删除）。 */
+    blob: string | null;
+    /** 普通文件的权限位。 */
+    mode?: number;
+    size?: number;
+    /** 记录时父目录的 realpath；恢复时校验没被移动。 */
+    realParentDir?: string;
+    /** 记录时取不到内容的原因；回滚时报告「无法恢复」。 */
+    skipped?: "too_large" | "not_regular";
+}
+export interface CheckpointData {
+    v: 1;
+    /** 这个检查点属于哪条用户消息：记的是「这条消息发出前」的状态。 */
+    userEntryId: string;
+    files: Record<string, FileRecord>;
+    /** 直接读 .git/HEAD 得到；cwd 不在 git 仓库里时省略。 */
+    git?: {
+        head: string;
+        branch?: string;
+    };
+    /** `checkpoints.mode: "shadow-git"` 时的影子仓库提交 id（RW-D）。 */
+    shadowCommit?: string;
+}
+export interface CheckpointTrackData {
+    v: 1;
+    userEntryId: string;
+    path: string;
+    record: FileRecord;
+}
+/** 交给工具的接口：edit / write 写文件前后各调一次。可选——宿主或内存会话没有时为 undefined。 */
+export interface CheckpointHooks {
+    /** 写之前：文件第一次被跟踪时备份当前内容。失败只记 warn，不抛。 */
+    beforeWrite(absolutePath: string): Promise<void>;
+    /** 写之后：记下 ama 最后写入的内容（冲突检测用）。 */
+    afterWrite(absolutePath: string, content: Uint8Array | string): void;
+}
+export type RewindMode = "both" | "conversation" | "code";
+export interface RewindPoint {
+    entryId: string;
+    text: string;
+    timestamp: number;
+    /** 没有检查点（内存会话、检查点关闭、超出保留数）时只能仅对话。 */
+    hasCheckpoint: boolean;
+}
+export interface RewindRequest {
+    entryId: string;
+    mode: RewindMode;
+    /** 只返回预览，不改任何东西。 */
+    dryRun?: boolean;
+    /** 冲突文件的处理；缺省 skip。 */
+    onConflict?: "skip" | "overwrite";
+}
+export type RewindSkipReason = "symlink" | "hardlink" | "not_regular" | "parent_moved" | "too_large" | "backup_missing";
+export interface CodeRestoreResult {
+    restored: string[];
+    deleted: string[];
+    /** 冲突文件：skip 时未动，overwrite 时已覆盖。 */
+    conflicts: string[];
+    skipped: {
+        path: string;
+        reason: RewindSkipReason;
+    }[];
+    failed: {
+        path: string;
+        message: string;
+    }[];
+    insertions: number;
+    deletions: number;
+}
+export interface RewindResult {
+    conversation?: {
+        leafId: string | null;
+        draft: {
+            text: string;
+            images?: ImageBlock[];
+        };
+    };
+    code?: CodeRestoreResult;
+    /** 记录的 HEAD 与当前不同时给出；只提示，不操作 git。 */
+    gitHint?: {
+        recordedHead: string;
+        currentHead: string;
+    };
+}

package/dist/checkpoints/types.js

@@ -0,0 +1,12 @@
+/**
+ * 检查点与回滚契约（docs/rewind-plan.md §1、§3）。契约文件，实现归 RW-A（`src/checkpoints/**`）
+ * 与 RW-B（`src/agent/session-rewind.ts`）。
+ *
+ * - 会话条目两类，均为 `custom`（不进上下文）：`ama.checkpoint`（新回合的用户消息之后）与
+ *   `ama.checkpoint-track`（回合中途第一次碰某文件，补进本回合检查点）。
+ * - 备份按内容 sha256 存 `<dataDir>/file-history/blobs/<前 2 位>/<全长>`，会话只记哈希。
+ * - 路径键：cwd 内为相对路径（`/` 分隔），cwd 外为绝对路径。
+ */
+export const CHECKPOINT_CUSTOM_TYPE = "ama.checkpoint";
+export const CHECKPOINT_TRACK_CUSTOM_TYPE = "ama.checkpoint-track";
+export const REWIND_NOTE_CUSTOM_TYPE = "ama.rewind-note";

package/dist/cli/args.d.ts

@@ -2,9 +2,10 @@
  * 手写参数解析（设计 §11.1 第 2 步、§12.10、§13）。[B5]
  *
  * - 支持 `--opt value` 与 `--opt=value`；`--` 之后全部作为提示文本；可重复的参数累加。
+ * - 位置参数 `-`：`-p` 一直等 stdin 到 EOF（有提示参数时也不设首字节超时）。
  * - 子命令只在第一个参数是 `auth / sessions / models / providers / doctor / config / init` 时识别，
  *   其余参数原样交给子命令。
- * - 互斥：`-p` 与 `--mode rpc`；`--continue` / `--resume` / `--session-id` / `--fork` 两两互斥；
+ * - 互斥：`-p` 与 `--mode rpc / acp`；`--continue` / `--resume` / `--session-id` / `--fork` 两两互斥；
  *   `--trust` 与 `--no-trust`；`--api-key` 需要 `--model`；`--output-format` 需要 `-p`。
  * - `--resume [id]`：下一个参数形如会话 id（无空白、不以 `-` 开头）才被当作 id；
  *   否则仍作为提示文本。显式写法 `--resume=<id>`。
@@ -12,9 +13,9 @@
  */
 import { AmaError } from "../errors.js";
 import type { ModelThinkingLevel } from "../ai/types.js";
-import type { PermissionMode } from "../permissions/types.js";
-import type { CodemodeMode, ToolsPreset } from "../config/types.js";
-export declare const SUBCOMMANDS: readonly ["auth", "sessions", "models", "providers", "doctor", "config", "init"];
+import { type PermissionMode } from "../permissions/types.js";
+import { type CodemodeMode, type ToolsPreset } from "../config/types.js";
+export declare const SUBCOMMANDS: readonly ["auth", "sessions", "models", "providers", "doctor", "config", "init", "stats"];
 export type SubcommandName = (typeof SUBCOMMANDS)[number];
 export type OutputFormat = "text" | "json" | "stream-json";
 export type QuietStartup = "normal" | "header" | "silent";
@@ -42,8 +43,8 @@ export interface ParsedArgs {
     sessionDir?: string;
     print: boolean;
     outputFormat?: OutputFormat;
-    /** `--mode rpc`。 */
-    mode?: "rpc";
+    /** `--mode rpc`；[W5-C0] `--mode acp`（ACP 服务端，W5-E 实现前报「尚未实现」）。 */
+    mode?: "rpc" | "acp";
     noTui: boolean;
     tuiMode?: "regular";
     quietStartup?: QuietStartup;
@@ -55,8 +56,26 @@ export interface ParsedArgs {
     toolsPreset?: ToolsPreset;
     /** `--codemode`：覆盖 config `codemode.mode`。 */
     codemode?: CodemodeMode;
+    /** `--no-session`：会话只在内存里，不写会话文件。 */
+    noSession: boolean;
+    /** `--system-prompt <文本|@文件>`：缺省追加进系统提示的 rules 节。 */
+    systemPrompt?: string;
+    /** `--system-prompt-mode`：append（缺省）| replace（替换开头的 preamble）。 */
+    systemPromptMode?: "append" | "replace";
+    /** `--max-turns N`（只用于 -p）：一次运行最多 N 轮（模型请求 + 工具执行算一轮）。 */
+    maxTurns?: number;
+    /** [W5-C0] `--max-cost USD`：一次运行的美元上限（W5-H2 实现前只透传并提示未生效）。 */
+    maxCostUsd?: number;
+    /** [W5-C0] `--agent-dir <目录>`（可重复）：子 Agent 定义目录（W5-G 实现前只透传）。 */
+    agentDirs?: string[];
+    /** 位置参数 `-`（只用于 -p）：一直等 stdin 到 EOF，不设首字节超时。 */
+    stdin: boolean;
+    /** `--no-stdin`（只用于 -p）：不读 stdin。 */
+    noStdin: boolean;
     /** `--image <文件>`（可重复，只用于 -p）：随首条提示发送的图片。 */
     images: string[];
+    /** `--from <会话 id>[#编号]`：用旧会话的一条用户消息作为提示（cli/from-prompt.ts）。 */
+    from?: string;
     /** 位置参数拼成的提示（空格连接）。 */
     prompt?: string;
     /** 原始位置参数。 */
@@ -73,7 +92,7 @@ export type ParseResult = {
 export declare class UsageError extends AmaError {
     constructor(message: string);
 }
-export declare const HELP_TEXT = "\u7528\u6CD5\uFF1Aama [\u9009\u9879] [\u63D0\u793A]\n      ama <\u5B50\u547D\u4EE4> \u2026\n\n\u6A21\u5F0F\n  \uFF08\u7F3A\u7701\uFF09                     \u7EC8\u7AEF\u754C\u9762\uFF1Bstdin / stdout \u975E TTY \u6216 TERM=dumb \u65F6\u81EA\u52A8\u964D\u7EA7\u4E3A\u884C\u5F0F\n  --no-tui                     \u884C\u5F0F\u754C\u9762\uFF08readline + \u62EC\u53F7\u7C98\u8D34\uFF09\n  -p, --print                  \u975E\u4EA4\u4E92\uFF1A\u6267\u884C\u63D0\u793A\u540E\u9000\u51FA\uFF08\u63D0\u793A\u53EF\u6765\u81EA\u53C2\u6570\u4E0E stdin \u7BA1\u9053\uFF09\n  --output-format <\u683C\u5F0F>       -p \u7684\u8F93\u51FA\uFF1Atext\uFF08\u7F3A\u7701\uFF09| json | stream-json\n  --image <\u6587\u4EF6>               -p \u968F\u63D0\u793A\u53D1\u9001\u56FE\u7247\uFF08\u53EF\u91CD\u590D\uFF1Bpng / jpg / gif / webp\uFF0C\u5355\u5F20 \u2264 5 MB\uFF09\uFF1B\n                               \u4EA4\u4E92\u754C\u9762\u91CC\u5199 @\u56FE\u7247\u8DEF\u5F84 \u6216\u7C98\u8D34\u56FE\u7247\u8DEF\u5F84\n  --mode rpc                   stdio JSONL \u534F\u8BAE\uFF08\u4F9B\u5D4C\u5165\uFF09\n  --tui-mode <\u6A21\u5F0F>            \u663E\u793A\u6A21\u5F0F\uFF0C\u7B2C\u4E00\u671F\u53EA\u6709 regular\uFF08\u4E3B\u5C4F\uFF09\n  --quiet-startup <\u6863>         \u542F\u52A8\u753B\u9762\uFF1Anormal | header | silent\n\n\u6A21\u578B\n  --model <provider/id>        \u6A21\u578B\uFF08\u53EF\u914D\u5408 --provider \u53EA\u5199 id\uFF1B@\u6E20\u9053 \u6307\u5B9A\u6E20\u9053\uFF0C\u5982 packy/kimi-k2.5@messages\uFF09\n  --provider <id>              \u4F9B\u5E94\u5546\uFF08\u5FC5\u987B\u540C\u65F6\u7ED9 --model\uFF09\n  --api-key <key>              \u53EA\u7528\u4E8E\u672C\u6B21\u542F\u52A8\u7684 key\uFF08\u9700\u8981 --model\uFF1B\u4F18\u5148\u7528 ama auth set\uFF09\n  --thinking <\u7EA7\u522B>            off | minimal | low | medium | high | xhigh\n\n\u4F1A\u8BDD\n  -c, --continue               \u7EE7\u7EED\u672C\u76EE\u5F55\u6700\u8FD1\u7684\u4F1A\u8BDD\n  -r, --resume [id]            \u6062\u590D\u4F1A\u8BDD\uFF08\u4EA4\u4E92\u6A21\u5F0F\u65E0 id \u65F6\u5F39\u9009\u62E9\u5668\uFF09\n  --session-id <id>            \u4F7F\u7528\u6307\u5B9A id \u7684\u4F1A\u8BDD\uFF08\u4E0D\u5B58\u5728\u5219\u65B0\u5EFA\uFF09\n  --fork <id>                  \u4ECE\u6307\u5B9A\u4F1A\u8BDD\u5206\u53C9\u51FA\u65B0\u4F1A\u8BDD\n  --session-dir <\u76EE\u5F55>         \u4F1A\u8BDD\u76EE\u5F55\uFF08\u7F3A\u7701 ~/.local/share/ama/sessions\uFF09\n\n\u6743\u9650\u4E0E\u4FE1\u4EFB\n  --permission-mode <\u6A21\u5F0F>     plan | default | auto-edit | full-auto\n  --allow <\u89C4\u5219>               \u8FFD\u52A0\u5141\u8BB8\u89C4\u5219\uFF0C\u53EF\u91CD\u590D\uFF08\u5982 \"bash(git status*)\"\uFF09\n  --deny <\u89C4\u5219>                \u8FFD\u52A0\u62D2\u7EDD\u89C4\u5219\uFF0C\u53EF\u91CD\u590D\uFF08\u5982 \"write(**/.env*)\"\uFF09\n  --trust / --no-trust         \u4FE1\u4EFB / \u4E0D\u4FE1\u4EFB\u5F53\u524D\u9879\u76EE\uFF08\u9879\u76EE\u7EA7 Hook\u3001Skill\u3001\u63D0\u793A\u6A21\u677F\uFF09\n\n\u8D44\u6E90\n  --profile <\u6587\u4EF6>             \u5BBF\u4E3B profile.json\uFF08\u5B57\u6BB5\u7B49\u4EF7\u4E8E\u5BF9\u5E94\u53C2\u6570\uFF0C\u547D\u4EE4\u884C\u4F18\u5148\uFF09\n  --host <\u6A21\u5757>                \u5BBF\u4E3B\u9002\u914D\u5668\u6A21\u5757\uFF08CJS / ESM\uFF09\n  --instructions <\u6587\u4EF6>        \u8FFD\u52A0\u6307\u4EE4\u6587\u4EF6\uFF0C\u53EF\u91CD\u590D\n  --skill-dir <\u76EE\u5F55>           \u8FFD\u52A0 Skill \u76EE\u5F55\uFF0C\u53EF\u91CD\u590D\n  --auth-file <\u6587\u4EF6>           auth.json \u4F4D\u7F6E\uFF08\u7F3A\u7701 ~/.config/ama/auth.json\uFF09\n  --tools <a,b,\u2026>              \u53EA\u542F\u7528\u8FD9\u4E9B\u5DE5\u5177\n  --exclude-tools <a,b,\u2026>      \u7981\u7528\u8FD9\u4E9B\u5DE5\u5177\n  --tools-preset <\u540D>          \u5DE5\u5177\u9884\u8BBE\uFF1Adefault\uFF08\u7F3A\u7701\uFF09| minimal | codemode | coordinator\n  --codemode <\u6A21\u5F0F>            codemode \u8C03\u7528\u65B9\u5F0F\uFF1Aoff | on | only\n\n\u5B50\u547D\u4EE4\n  ama auth set <provider>      \u4ECE stdin \u8BFB\u53D6 key \u5199\u5165 auth.json\uFF080600\uFF09\n  ama auth list                \u5217\u51FA\u5DF2\u4FDD\u5B58 key \u7684\u4F9B\u5E94\u5546\uFF08\u4E0D\u663E\u793A key\uFF09\n  ama auth remove <provider>   \u5220\u9664\u5DF2\u4FDD\u5B58\u7684 key\n  ama sessions list|show|prune \u4F1A\u8BDD\u7BA1\u7406\n  ama models list [--provider <id>]  \u5217\u51FA\u6A21\u578B\uFF08\u542B\u6765\u6E90\u4E0E key \u72B6\u6001\uFF09\n  ama models check <provider/id>     \u53D1\u4E00\u6B21\u6700\u5C0F\u8BF7\u6C42\u68C0\u67E5\u53EF\u7528\u6027\n  ama models discover <provider> [--probe] [--write] [--limit N]\n                               \u4ECE\u4E2D\u8F6C /v1/models \u5217\u51FA\u6A21\u578B\uFF0C\u63A2\u6D4B\u534F\u8BAE\u5E76\u5199\u5165\u914D\u7F6E\n  ama models refresh-catalog   \u5F3A\u5236\u5237\u65B0 models.dev \u6A21\u578B\u5143\u6570\u636E\u7F13\u5B58\n  ama providers add <id> --base-url <url> [--key-env VAR] [--probe] [--channel n=api@url] [--yes]\n                               \u4E00\u952E\u63A5\u5165\uFF1A\u5217\u6A21\u578B\u3001\u8865 models.dev \u5143\u6570\u636E\u3001\u63A2\u6D4B\u6E20\u9053\u3001\u5199\u5165\u914D\u7F6E\n  ama providers list|channels <id>|remove <id>|refresh <id>\n                               \u4F9B\u5E94\u5546 \u2192 \u6E20\u9053 \u2192 \u6A21\u578B\uFF1B\u5220\u9664\uFF1B\u91CD\u62C9\u6A21\u578B\u5217\u8868\n  ama models cache-probe <provider/id> [--tokens N] [--gap-ms MS] [--yes] [--json]\n                               \u5224\u65AD\u7AEF\u70B9\u662F\u5426\u62A5\u544A\u7F13\u5B58\u547D\u4E2D\n  ama doctor                   \u914D\u7F6E\u5C42\u7EA7\u3001\u4FE1\u4EFB\u3001key \u6765\u6E90\u3001Hook\u3001\u7EC8\u7AEF\u80FD\u529B\n  ama config show [--json]     \u751F\u6548\u914D\u7F6E\u4E0E\u6BCF\u9879\u6765\u6E90\u3001\u5C06\u4F7F\u7528\u7684\u6A21\u578B\n  ama config path              \u914D\u7F6E\u76EE\u5F55\u3001\u6570\u636E\u76EE\u5F55\u4E0E\u5404\u6587\u4EF6\u8DEF\u5F84\n  ama config edit              \u7528 $VISUAL / $EDITOR \u6253\u5F00 config.json\n  ama init [--force]           \u5EFA\u914D\u7F6E\u76EE\u5F55\uFF080700\uFF09\u4E0E config.json\u3001config.schema.json\uFF1B\u5DF2\u6709\u7684\u4E0D\u8986\u76D6\n\n\u5176\u5B83\n  -h, --help                   \u8F93\u51FA\u672C\u5E2E\u52A9\n  -v, --version                \u8F93\u51FA\u7248\u672C\n\n\u9000\u51FA\u7801\uFF1A0 \u6B63\u5E38 \u00B7 1 \u8FD0\u884C\u671F\u9519\u8BEF \u00B7 2 \u7528\u6CD5\u9519\u8BEF \u00B7 3 \u914D\u7F6E\u9519\u8BEF \u00B7 4 \u65E0\u53EF\u7528\u6A21\u578B\u6216 key \u00B7\n        5 \u4F1A\u8BDD\u9519\u8BEF \u00B7 6 \u5BBF\u4E3B / Hook \u542F\u52A8\u5931\u8D25 \u00B7 78 \u5BBF\u4E3B API \u7248\u672C\u4E0D\u5339\u914D \u00B7 130 SIGINT \u00B7 143 SIGTERM\n";
+export { HELP_TEXT } from "./help-text.js";
 export declare function emptyArgs(): ParsedArgs;
 /** 解析 argv（不含 node 与脚本路径）；用法错误抛 UsageError（退出码 2）。 */
 export declare function parseArgs(argv: readonly string[]): ParseResult;