@armadra/agent 0.4.0 → 0.5.1

package/dist/agent/session-rewind.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 会话回滚编排（docs/rewind-plan.md §2、§3.1、§3.3–§3.6）。[RW-B]
+ *
+ * - 回合起点：`runPrompt` 开启新回合的那条用户消息（steer / followUp 并入当前回合、Stop Hook 续跑
+ *   的 `hook` 消息都不算）。本进程内落盘的按记录判断；恢复的会话以 `ama.checkpoint` 条目为准，
+ *   没有检查点时退回「origin 为空的用户消息」。
+ * - 检查点：回合起点落盘后调后端 `snapshot()`，首个模型请求前等它完成；ToolContext 的
+ *   `checkpoint` 钩子指向后端（子会话指向父会话的后端，记到父会话当前回合）。内存会话不建。
+ * - `rewind()`：代码（后端恢复）与对话（`navigate(parentId)`）；`readFiles` 按新路径上成功的
+ *   read / write 调用重算，再去掉被恢复、删除或与目标检查点不一致的文件。
+ * - 仅对话 / 仅代码时的一致性提示 `ama.rewind-note` 留到下一次提示前追加在末尾（§3.4、§7）。
+ * - 「从这里摘要」= navigate(parentId, summarize)；「摘要到这里」= 以该消息为切点的档二压缩。
+ * - 中断即撤回（§3.6）：本回合被 abort 且没有任何助手文本 / 工具调用 → 可撤回并回填原消息。
+ */
+import type { UserMessage } from "../ai/types.js";
+import type { CheckpointBackend } from "../checkpoints/index.js";
+import { type CheckpointHooks, type RewindPoint, type RewindRequest, type RewindResult } from "../checkpoints/types.js";
+import type { BranchSummaryEntry, SessionEntry } from "../session/types.js";
+import type { SessionCore } from "./session-core.js";
+import type { CompactionResult, RewindDraftText } from "./types.js";
+/** 提示里最多列出的文件数（§3.4）。 */
+export declare const REWIND_NOTE_MAX_FILES = 20;
+export type RewindDraft = RewindDraftText;
+/** 「从这里摘要」的结果。 */
+export interface SummarizeFromResult {
+    leafId: string | null;
+    draft: RewindDraft;
+    summary?: BranchSummaryEntry;
+}
+/** 会话交给回滚控制器的能力（避免与 session.ts 循环 import）。 */
+export interface RewindHost {
+    readonly core: SessionCore;
+    running(): boolean;
+    navigate(targetId: string | null, options?: {
+        summarize?: boolean;
+        instructions?: string;
+    }): Promise<BranchSummaryEntry | undefined>;
+    /** 以 entryId 为切点的档二压缩（运行中 → busy）。 */
+    compactAt(entryId: string, instructions: string | undefined): Promise<CompactionResult>;
+}
+/** 文件清单：最多 20 个，其余计数。 */
+export declare function listFiles(files: readonly string[]): string;
+export declare function conversationNote(files: readonly string[]): string;
+export declare function codeNote(files: readonly string[], index: number): string;
+export declare class RewindController {
+    readonly backend: CheckpointBackend | undefined;
+    private readonly host;
+    /** 本进程内落盘的回合起点。 */
+    private readonly turnStarts;
+    /** 本进程内落盘的全部用户消息（回合起点之外的不用回退规则判断）。 */
+    private readonly seenUsers;
+    private expected;
+    private turn;
+    private pendingSnapshot;
+    private pendingNote;
+    constructor(host: RewindHost);
+    /** ToolContext.checkpoint：自己的后端，或子会话继承的父会话钩子。 */
+    hooks(): CheckpointHooks | undefined;
+    /** runPrompt 构造了开启新回合的用户消息；同时把待发的一致性提示追加在它之前。 */
+    beginTurn(message: UserMessage): void;
+    /** 每条落盘的消息。 */
+    onPersisted(entry: SessionEntry | undefined): void;
+    /** 首个模型请求前（beforeRequest）：等检查点拍完，工具才可能写文件。 */
+    ready(): Promise<void>;
+    private checkpointIds;
+    private turnEntries;
+    points(): RewindPoint[];
+    private target;
+    private assertIdle;
+    rewind(request: RewindRequest): Promise<RewindResult>;
+    private absolute;
+    private announce;
+    /** 新路径上成功的 read / write 调用（与 markRead 的语义一致，不跨分支保留）。 */
+    recomputeReadFiles(): void;
+    summarizeFrom(entryId: string, instructions?: string): Promise<SummarizeFromResult>;
+    summarizeUpTo(entryId: string, instructions?: string): Promise<CompactionResult>;
+    /** 空闲、开关开、最近一个回合被中断且还没有任何助手文本 / 工具调用。 */
+    canUndoAbortedTurn(): boolean;
+    /** 撤回被中断的回合并返回原消息；不满足条件时 undefined。 */
+    undoAbortedTurn(): Promise<RewindDraft | undefined>;
+}

package/dist/agent/session-rewind.js

@@ -0,0 +1,354 @@
+/**
+ * 会话回滚编排（docs/rewind-plan.md §2、§3.1、§3.3–§3.6）。[RW-B]
+ *
+ * - 回合起点：`runPrompt` 开启新回合的那条用户消息（steer / followUp 并入当前回合、Stop Hook 续跑
+ *   的 `hook` 消息都不算）。本进程内落盘的按记录判断；恢复的会话以 `ama.checkpoint` 条目为准，
+ *   没有检查点时退回「origin 为空的用户消息」。
+ * - 检查点：回合起点落盘后调后端 `snapshot()`，首个模型请求前等它完成；ToolContext 的
+ *   `checkpoint` 钩子指向后端（子会话指向父会话的后端，记到父会话当前回合）。内存会话不建。
+ * - `rewind()`：代码（后端恢复）与对话（`navigate(parentId)`）；`readFiles` 按新路径上成功的
+ *   read / write 调用重算，再去掉被恢复、删除或与目标检查点不一致的文件。
+ * - 仅对话 / 仅代码时的一致性提示 `ama.rewind-note` 留到下一次提示前追加在末尾（§3.4、§7）。
+ * - 「从这里摘要」= navigate(parentId, summarize)；「摘要到这里」= 以该消息为切点的档二压缩。
+ * - 中断即撤回（§3.6）：本回合被 abort 且没有任何助手文本 / 工具调用 → 可撤回并回填原消息。
+ */
+import { isAbsolute, resolve } from "node:path";
+import { CHECKPOINT_CUSTOM_TYPE, REWIND_NOTE_CUSTOM_TYPE, } from "../checkpoints/types.js";
+import { AmaError } from "../errors.js";
+import { resolvePath } from "../tools/paths.js";
+import { ABORTED_CUSTOM_TYPE } from "./session-run.js";
+/** 提示里最多列出的文件数（§3.4）。 */
+export const REWIND_NOTE_MAX_FILES = 20;
+function textOf(content) {
+    if (typeof content === "string")
+        return content;
+    return content.map((block) => (block.type === "text" ? block.text : "")).join("");
+}
+function draftOf(message) {
+    const draft = { text: textOf(message.content) };
+    if (typeof message.content !== "string") {
+        const images = message.content.filter((block) => block.type === "image");
+        if (images.length > 0)
+            draft.images = images;
+    }
+    return draft;
+}
+function userMessageOf(entry) {
+    return entry?.type === "message" && entry.message.role === "user" ? entry.message : undefined;
+}
+/** 文件清单：最多 20 个，其余计数。 */
+export function listFiles(files) {
+    const shown = files.slice(0, REWIND_NOTE_MAX_FILES).map((file) => `- ${file}`);
+    const rest = files.length - REWIND_NOTE_MAX_FILES;
+    if (rest > 0)
+        shown.push(`- … and ${rest} more`);
+    return shown.join("\n");
+}
+export function conversationNote(files) {
+    return ("The conversation was rewound to an earlier point, but these files keep the changes made " +
+        `after that point (their content may differ from what you saw earlier):\n${listFiles(files)}`);
+}
+export function codeNote(files, index) {
+    return (`These files were restored to their state before user message #${index} of this ` +
+        `conversation (read them again before editing):\n${listFiles(files)}`);
+}
+function changedFiles(result) {
+    return [...new Set([...result.restored, ...result.deleted, ...result.conflicts])];
+}
+/** 本回合有没有任何助手文本或工具调用。 */
+function hasOutput(entry) {
+    if (entry.type !== "message")
+        return false;
+    const message = entry.message;
+    if (message.role === "toolResult" || message.role === "user")
+        return true;
+    if (message.role !== "assistant")
+        return false;
+    return message.content.some((block) => block.type === "toolCall" || (block.type === "text" && block.text.trim().length > 0));
+}
+export class RewindController {
+    backend;
+    host;
+    /** 本进程内落盘的回合起点。 */
+    turnStarts = new Set();
+    /** 本进程内落盘的全部用户消息（回合起点之外的不用回退规则判断）。 */
+    seenUsers = new Set();
+    expected;
+    turn;
+    pendingSnapshot;
+    pendingNote;
+    constructor(host) {
+        this.host = host;
+        const core = host.core;
+        const factory = core.options.checkpoints;
+        const persisted = core.manager.directory() !== undefined;
+        this.backend =
+            factory !== undefined && core.depth === 0 && persisted
+                ? factory({
+                    cwd: core.cwd,
+                    entries: () => core.manager.entries(),
+                    appendCustom: (customType, data) => {
+                        core.appendEntry({ type: "custom", customType, data });
+                    },
+                    currentTurn: () => this.turn,
+                    log: (level, message) => core.log(level, message),
+                })
+                : undefined;
+    }
+    /** ToolContext.checkpoint：自己的后端，或子会话继承的父会话钩子。 */
+    hooks() {
+        return this.backend?.hooks ?? this.host.core.options.checkpointHooks;
+    }
+    // -------------------------------------------------------------------------
+    // 接线：runPrompt → 落盘 → snapshot → 首个请求前等待
+    // -------------------------------------------------------------------------
+    /** runPrompt 构造了开启新回合的用户消息；同时把待发的一致性提示追加在它之前。 */
+    beginTurn(message) {
+        this.expected = message;
+        if (this.pendingNote !== undefined) {
+            const content = this.pendingNote;
+            this.pendingNote = undefined;
+            this.host.core.appendEntry({
+                type: "custom_message",
+                customType: REWIND_NOTE_CUSTOM_TYPE,
+                content,
+                display: false,
+            });
+            this.host.core.reloadMessages();
+        }
+    }
+    /** 每条落盘的消息。 */
+    onPersisted(entry) {
+        const message = userMessageOf(entry);
+        if (entry === undefined || message === undefined)
+            return;
+        this.seenUsers.add(entry.id);
+        if (message !== this.expected)
+            return;
+        this.expected = undefined;
+        this.turnStarts.add(entry.id);
+        this.turn = entry.id;
+        const backend = this.backend;
+        if (backend === undefined)
+            return;
+        this.pendingSnapshot = backend.snapshot(entry.id).catch((error) => {
+            this.host.core.log("warn", `checkpoint snapshot failed: ${String(error)}`);
+        });
+    }
+    /** 首个模型请求前（beforeRequest）：等检查点拍完，工具才可能写文件。 */
+    async ready() {
+        const pending = this.pendingSnapshot;
+        this.pendingSnapshot = undefined;
+        if (pending !== undefined)
+            await pending;
+    }
+    // -------------------------------------------------------------------------
+    // 回滚点
+    // -------------------------------------------------------------------------
+    checkpointIds() {
+        const ids = new Set();
+        for (const entry of this.host.core.manager.entries()) {
+            if (entry.type !== "custom" || entry.customType !== CHECKPOINT_CUSTOM_TYPE)
+                continue;
+            const data = entry.data;
+            if (typeof data?.userEntryId === "string")
+                ids.add(data.userEntryId);
+        }
+        return ids;
+    }
+    turnEntries() {
+        const recorded = this.checkpointIds();
+        const out = [];
+        for (const entry of this.host.core.manager.branch()) {
+            const message = userMessageOf(entry);
+            if (message === undefined)
+                continue;
+            const start = this.seenUsers.has(entry.id)
+                ? this.turnStarts.has(entry.id)
+                : recorded.has(entry.id) || message.origin === undefined;
+            if (start)
+                out.push({ entry, message });
+        }
+        return out;
+    }
+    points() {
+        return this.turnEntries().map(({ entry, message }) => ({
+            entryId: entry.id,
+            text: textOf(message.content),
+            timestamp: message.timestamp,
+            hasCheckpoint: this.backend?.hasCheckpoint(entry.id) ?? false,
+        }));
+    }
+    target(entryId) {
+        const turns = this.turnEntries();
+        const index = turns.findIndex((turn) => turn.entry.id === entryId);
+        const found = turns[index];
+        if (found === undefined) {
+            throw new AmaError("invalid_arguments", `entry ${entryId} is not a rewind point on the active branch`);
+        }
+        return { ...found, index: index + 1 };
+    }
+    // -------------------------------------------------------------------------
+    // 回滚
+    // -------------------------------------------------------------------------
+    assertIdle() {
+        if (this.host.running())
+            throw new AmaError("busy", "cannot rewind while running");
+    }
+    async rewind(request) {
+        this.assertIdle();
+        const { entry, message, index } = this.target(request.entryId);
+        const mode = request.mode;
+        const withCode = mode !== "conversation";
+        const withConversation = mode !== "code";
+        const backend = this.backend;
+        const checkpointed = backend?.hasCheckpoint(entry.id) === true;
+        if (withCode && (backend === undefined || !checkpointed)) {
+            throw new AmaError("no_checkpoint", "this message has no checkpoint; rewind the conversation only");
+        }
+        const onConflict = request.onConflict ?? "skip";
+        const result = {};
+        if (checkpointed && backend !== undefined) {
+            const hint = await backend.gitHint(entry.id);
+            if (hint !== undefined)
+                result.gitHint = hint;
+        }
+        if (request.dryRun === true) {
+            if (checkpointed && backend !== undefined) {
+                result.code = (await backend.restore(entry.id, { dryRun: true, onConflict })).result;
+            }
+            return result;
+        }
+        let touched = [];
+        let divergent = [];
+        if (withCode && backend !== undefined) {
+            const restored = await backend.restore(entry.id, { dryRun: false, onConflict });
+            const code = restored.result;
+            if (code.failed.length > 0 && code.restored.length === 0 && code.deleted.length === 0) {
+                throw new AmaError("rewind_failed", `no files were restored: ${code.failed.map((f) => `${f.path}: ${f.message}`).join("; ")}`, { detail: code });
+            }
+            result.code = code;
+            touched = restored.touched;
+        }
+        else if (checkpointed && backend !== undefined) {
+            // 仅对话：与目标检查点不一致的文件要告诉模型，并从 readFiles 去掉
+            const preview = await backend.restore(entry.id, { dryRun: true, onConflict: "skip" });
+            divergent = changedFiles(preview.result);
+        }
+        if (withConversation) {
+            await this.host.navigate(entry.parentId);
+            result.conversation = { leafId: entry.parentId, draft: draftOf(message) };
+            this.recomputeReadFiles();
+        }
+        const core = this.host.core;
+        for (const path of [...touched, ...divergent.map((file) => this.absolute(file))]) {
+            core.readFiles.delete(path);
+        }
+        if (mode === "conversation") {
+            this.pendingNote = divergent.length > 0 ? conversationNote(divergent) : undefined;
+        }
+        else if (mode === "code") {
+            const files = result.code === undefined ? [] : [...result.code.restored, ...result.code.deleted];
+            this.pendingNote = files.length > 0 ? codeNote(files, index) : undefined;
+        }
+        else
+            this.pendingNote = undefined;
+        this.announce(entry.id, mode, result.code);
+        return result;
+    }
+    absolute(file) {
+        return isAbsolute(file) ? file : resolve(this.host.core.cwd, file);
+    }
+    announce(entryId, mode, code) {
+        const core = this.host.core;
+        const restored = code?.restored ?? [];
+        const deleted = code?.deleted ?? [];
+        core.emit({
+            type: "session_rewound",
+            entryId,
+            mode,
+            restored,
+            deleted,
+            conflicts: code?.conflicts ?? [],
+            skipped: code?.skipped ?? [],
+        });
+        void core.runHook("PostRewind", { entryId, mode, files: [...restored, ...deleted] });
+    }
+    /** 新路径上成功的 read / write 调用（与 markRead 的语义一致，不跨分支保留）。 */
+    recomputeReadFiles() {
+        const core = this.host.core;
+        const calls = new Map();
+        const next = new Set();
+        for (const entry of core.manager.branch()) {
+            if (entry.type !== "message")
+                continue;
+            const message = entry.message;
+            if (message.role === "assistant") {
+                for (const block of message.content) {
+                    if (block.type !== "toolCall" || (block.name !== "read" && block.name !== "write"))
+                        continue;
+                    const path = block.arguments["path"];
+                    if (typeof path === "string")
+                        calls.set(block.id, resolvePath(path, core.cwd));
+                }
+            }
+            else if (message.role === "toolResult" && message.isError !== true) {
+                const path = calls.get(message.toolCallId);
+                if (path !== undefined)
+                    next.add(path);
+            }
+        }
+        core.readFiles.clear();
+        for (const path of next)
+            core.readFiles.add(path);
+    }
+    // -------------------------------------------------------------------------
+    // 摘要两项（§3.5）
+    // -------------------------------------------------------------------------
+    async summarizeFrom(entryId, instructions) {
+        this.assertIdle();
+        const { entry, message } = this.target(entryId);
+        const options = { summarize: true };
+        if (instructions !== undefined)
+            options.instructions = instructions;
+        const summary = await this.host.navigate(entry.parentId, options);
+        this.recomputeReadFiles();
+        this.pendingNote = undefined;
+        this.announce(entry.id, "conversation", undefined);
+        const result = { leafId: entry.parentId, draft: draftOf(message) };
+        if (summary !== undefined)
+            result.summary = summary;
+        return result;
+    }
+    async summarizeUpTo(entryId, instructions) {
+        this.assertIdle();
+        const { entry } = this.target(entryId);
+        return this.host.compactAt(entry.id, instructions);
+    }
+    // -------------------------------------------------------------------------
+    // 中断即撤回（§3.6）
+    // -------------------------------------------------------------------------
+    /** 空闲、开关开、最近一个回合被中断且还没有任何助手文本 / 工具调用。 */
+    canUndoAbortedTurn() {
+        if (this.host.running() || this.host.core.options.restoreOnCancel === false)
+            return false;
+        const last = this.turnEntries().at(-1);
+        if (last === undefined)
+            return false;
+        const branch = this.host.core.manager.branch();
+        const after = branch.slice(branch.findIndex((entry) => entry.id === last.entry.id) + 1);
+        if (after.some(hasOutput))
+            return false;
+        return after.some((entry) => entry.type === "custom_message" && entry.customType === ABORTED_CUSTOM_TYPE);
+    }
+    /** 撤回被中断的回合并返回原消息；不满足条件时 undefined。 */
+    async undoAbortedTurn() {
+        if (!this.canUndoAbortedTurn())
+            return undefined;
+        const last = this.turnEntries().at(-1);
+        if (last === undefined)
+            return undefined;
+        const result = await this.rewind({ entryId: last.entry.id, mode: "conversation" });
+        return result.conversation?.draft;
+    }
+}

package/dist/agent/session-run.d.ts

@@ -10,6 +10,11 @@
  * - 将要停下时发 agent_before_settle 并跑 Stop（子 Agent 为 SubagentStop）Hook：block + reason →
  *   以 reason 作为新 user 消息再跑一轮（上限 3 次，stopHookActive 传给 Hook）。
  * - 最终失败后若 followUp 队列非空，照常投递。
+ * - [W5-H2] 模型回退：可重试错误在 overloaded 时、或重试用尽后，若配置了 `fallbackModel` 就切过去
+ *   重试一次本请求（`model_fallback` 事件），回退模型回复后切回主模型；每个周期最多一次。
+ * - [W5-H2] 扩展经 `noteSettleWarning` 登记的 warning（预算到限 `limit_reached`）写进本周期的 agent_settled；
+ *   `limit_reached:` 开头的错误回复（预算拦下请求）不重试。
+ * - [W5-H2] run 带 `warning`（重复调用检测 `repeated_tool_call`）：不跑 Stop Hook，agent_settled 带该 warning。
  */
 import type { AssistantMessage, ImageBlock, UserMessage } from "../ai/types.js";
 import type { AgentMessage } from "../session/types.js";
@@ -19,6 +24,9 @@ import type { CompactionController } from "./session-compaction.js";
 import type { PromptDisposition, RetrySettings } from "./types.js";
 export declare const MAX_STOP_HOOK_CONTINUATIONS = 3;
 export declare const ABORTED_CUSTOM_TYPE = "ama.aborted";
+/** [W5-H2] 预算拦下请求时错误回复的前缀（limits.ts）：判为最终失败，不重试、不回退。 */
+export declare const LIMIT_ERROR_PREFIX = "limit_reached:";
+export declare function noteSettleWarning(core: SessionCore, warning: string): void;
 export type RunDecision = {
     kind: "done";
 } | {
@@ -31,6 +39,11 @@ export type RunDecision = {
 } | {
     kind: "failed";
     errorMessage: string;
+}
+/** [W5-H2] 切到 `fallbackModel` 重试一次本请求（overloaded，或可重试错误的重试已用尽）。 */
+ | {
+    kind: "fallback";
+    errorMessage: string;
 };
 export interface RunCycleDeps {
     core: SessionCore;
@@ -40,12 +53,26 @@ export interface RunCycleDeps {
     stopRequested(): boolean;
     setRetrying(value: boolean): void;
     lastAssistantText(): string | null;
+    /** [RW-B] 开启新回合的用户消息已构造、尚未落盘（建检查点、追加回滚提示）。 */
+    beginTurn?(message: UserMessage): void;
+    /** [W5-C0] 扩展点 beforePrompts：返回追加在 prompts 之后的消息（session-extensions.ts）。 */
+    beforePrompts?(prompts: readonly AgentMessage[]): Promise<AgentMessage[]>;
+    /** [W5-C0] 扩展点 onAgentSettled：agent_settled 之后、周期结束之前。 */
+    afterSettled?(): Promise<void>;
 }
-export declare function decideAfterRun(deps: RunCycleDeps, outcome: RunOutcome, retryAttempt: number, overflowRecovered: boolean): RunDecision;
+export declare function decideAfterRun(deps: RunCycleDeps, outcome: RunOutcome, retryAttempt: number, overflowRecovered: boolean, fallbackUsed?: boolean): RunDecision;
 /** 用 context_edit 把失败尝试（助手消息与其后补的结果）从上下文剔除。 */
 export declare function excludeFailedAttempt(core: SessionCore, failed: AssistantMessage | undefined, reason: "retry" | "overflow"): void;
 export declare function recordAbort(core: SessionCore): void;
+/**
+ * 会话周期：跑完一轮（到 agent_settled 与 onAgentSettled）后，若期间（Stop Hook、agent_settled 监听器、
+ * onAgentSettled 扩展）又有 steer / followUp 入队——宿主 `sendUser`、子 Agent 后台通知等在周期收尾
+ * 阶段调用时会话仍算忙，只能入队——就在同一周期里再开一轮投递它们（[W5-H2]，W5-G 发现的竞态）。
+ * abort 或已请求停止（Hook continue:false、预算到限）时不续投，消息留在队列。
+ */
 export declare function runCycle(deps: RunCycleDeps, prompts: AgentMessage[], signal: AbortSignal): Promise<void>;
+/** `"user"` = 普通用户输入，不写 origin。 */
+export declare function normalizeOrigin(origin: string | undefined): string | undefined;
 export declare function makeUserMessage(text: string, images?: readonly ImageBlock[], origin?: string): UserMessage;
 /**
  * 一次提示：展开（expandPrompt）→ UserPromptSubmit Hook（block 拒绝；updatedPrompt 替换；