@armadra/agent 0.4.0 → 0.5.0

package/dist/agent/session-images.js

@@ -0,0 +1,97 @@
+/**
+ * 图片预算扩展（docs/wave5-plan.md §4、D11、D30）。[W5-I]
+ *
+ * 每次请求前检查图片总量：超预算（或有超单图上限的旧图、> 20 张时的大图）就按
+ * `planImageBudget` 把旧图换成占位文本，写成 `context_edit{reason:"image_budget"}` 持久化、
+ * 重建上下文，并通知缓存控制器「下一条是重置点」（前缀只在这里变一次，之后稳定）。
+ *
+ * 两个检查点：
+ * - `beforePrompts`：新回合投递前；本回合提示里的附件计入总量但不降级；
+ * - `wrapStream`：回合内（工具结果里新读的图）每次 `turn` 请求前；已发出的消息都已落盘时才降级，
+ *   并把本次请求的转录换成降级后的（就地改 context，缓存控制器看到的也是降级后的请求）。
+ *
+ * 模型不收图片时不处理：`normalizeContext` 已把图片换成占位（ai/context.ts）。
+ */
+import { MANY_IMAGES_COUNT, imageLimits } from "../ai/image-limits.js";
+import { planImageBudget } from "../compaction/image-budget.js";
+import { buildProjection } from "../session/projection.js";
+import { convertToLlm } from "./transform.js";
+function imagesIn(message) {
+    if (!("content" in message) || !Array.isArray(message.content))
+        return [];
+    return message.content.filter((block) => block.type === "image");
+}
+/** 粗查：总量、单张、张数都没越线就不必建投影。 */
+function withinLimits(messages, reserve, limits) {
+    let total = 0;
+    let count = 0;
+    for (const message of [...messages.map(imagesIn), reserve]) {
+        for (const image of message) {
+            if (image.data.length > limits.perImageBase64)
+                return false;
+            total += image.data.length;
+            count++;
+        }
+    }
+    return total <= limits.perRequestBase64 && count <= MANY_IMAGES_COUNT;
+}
+export function createImageBudgetExtension(core, deps = {}) {
+    const limitsOf = deps.limits ?? ((model) => imageLimits(model));
+    /** 返回写下的降级条目；`synced`：要求 Agent 的消息与落盘的投影一致（回合内）。 */
+    const enforce = (model, reserve, synced) => {
+        if (!model.input.includes("image"))
+            return [];
+        const limits = limitsOf(model);
+        if (withinLimits(core.agent.messages, reserve, limits))
+            return [];
+        const projection = buildProjection(core.manager.branch());
+        if (synced && projection.messages.length !== core.agent.messages.length)
+            return [];
+        const plan = planImageBudget(projection.items, limits.perRequestBase64, {
+            perImageBytes: limits.perImageBase64,
+            reserve,
+        });
+        if (plan.length === 0)
+            return [];
+        for (const edit of plan) {
+            core.appendEntry({
+                type: "context_edit",
+                targetId: edit.targetId,
+                replacement: edit.replacement,
+                reason: "image_budget",
+            });
+        }
+        core.reloadMessages();
+        core.cache?.onContextChanged();
+        const images = plan.reduce((sum, edit) => sum + edit.images, 0);
+        core.log("info", `image budget: omitted ${images} earlier image(s) in ${plan.length} message(s) to fit the request size`);
+        return plan;
+    };
+    return {
+        id: "images",
+        beforePrompts(_ctx, prompts) {
+            const reserve = prompts.flatMap(imagesIn);
+            enforce(core.model(), reserve, false);
+            return [];
+        },
+        wrapStream(stream) {
+            return (model, context, options) => {
+                if ((options.purpose ?? "turn") === "turn") {
+                    try {
+                        if (enforce(model, [], true).length > 0) {
+                            const messages = convertToLlm(core.agent.messages, {
+                                provider: model.provider,
+                                model: model.id,
+                            });
+                            context.messages = messages;
+                        }
+                    }
+                    catch (error) {
+                        core.log("warn", `image budget check failed: ${String(error)}`);
+                    }
+                }
+                return stream(model, context, options);
+            };
+        },
+    };
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Plan 扩展：模式说明注入、`plan_state` 持久化、计划提取与审批编排、交接（docs/wave5-plan.md §6、
+ * D18–D21）。[W5-F] 只装在根会话（task 子会话的计划块作为 task 结果返回给父会话）。
+ *
+ * - 进入 plan（任何来源的 `permission_mode_changed`，或会话以 plan 启动 / resume 回到 plan）：记
+ *   prePlanMode，落 `custom{ama.plan_state{active:true}}`；之后的提示前按节奏追加
+ *   `custom_message{ama.plan_mode}`（第 1 个提示完整版，之后每 5 个提示一次简版，每第 5 次完整版；
+ *   压缩后的首个提示补完整版）。手动退出：下一个提示前追加 `ama.plan_mode_exit`。全部只追加在尾部，
+ *   不改 system 与工具表（§9.1）。
+ * - 提取：plan 下一回合以纯文本结束（无工具调用）时，从这条回复里取 `<proposed_plan>`，落
+ *   `custom{ama.plan{status:"proposed"}}` 与计划文件，发 `plan_proposed`。
+ * - 审批（谁来答，见 {@link PlanAttendance}）：客户端 / SDK 回调 / 交互模式文本回复；无人值守按
+ *   `plan.unattended`（缺省 stop：落盘后停下，**不替人批准**；approve 才自动批准）。
+ * - 批准：落 approved、步骤转 `ama.todo`（首项 in_progress）、切回执行模式（缺省进入前的模式）、
+ *   `plan.model` 配置时切回执行模型，然后以 `custom_message{ama.plan_approved}`（计划全文 + 文件路径
+ *   + 按 todo 推进）开启新回合。「新上下文执行」由调用方新建会话，用 `adopt()` + `freshPrompt`。
+ */
+import { type PlanExtensionOptions } from "../plan/controller.js";
+import type { SessionExtensionFactory } from "./session-extensions.js";
+export declare function createPlanExtensionFactory(options: PlanExtensionOptions): SessionExtensionFactory;
+export { planController, type PlanAttendance, type PlanController, type PlanDecision, type PlanDecisionHandler, type PlanExtensionOptions, type PlanResponse, type PlanResponseResult, } from "../plan/controller.js";

package/dist/agent/session-plan.js

@@ -0,0 +1,524 @@
+/**
+ * Plan 扩展：模式说明注入、`plan_state` 持久化、计划提取与审批编排、交接（docs/wave5-plan.md §6、
+ * D18–D21）。[W5-F] 只装在根会话（task 子会话的计划块作为 task 结果返回给父会话）。
+ *
+ * - 进入 plan（任何来源的 `permission_mode_changed`，或会话以 plan 启动 / resume 回到 plan）：记
+ *   prePlanMode，落 `custom{ama.plan_state{active:true}}`；之后的提示前按节奏追加
+ *   `custom_message{ama.plan_mode}`（第 1 个提示完整版，之后每 5 个提示一次简版，每第 5 次完整版；
+ *   压缩后的首个提示补完整版）。手动退出：下一个提示前追加 `ama.plan_mode_exit`。全部只追加在尾部，
+ *   不改 system 与工具表（§9.1）。
+ * - 提取：plan 下一回合以纯文本结束（无工具调用）时，从这条回复里取 `<proposed_plan>`，落
+ *   `custom{ama.plan{status:"proposed"}}` 与计划文件，发 `plan_proposed`。
+ * - 审批（谁来答，见 {@link PlanAttendance}）：客户端 / SDK 回调 / 交互模式文本回复；无人值守按
+ *   `plan.unattended`（缺省 stop：落盘后停下，**不替人批准**；approve 才自动批准）。
+ * - 批准：落 approved、步骤转 `ama.todo`（首项 in_progress）、切回执行模式（缺省进入前的模式）、
+ *   `plan.model` 配置时切回执行模型，然后以 `custom_message{ama.plan_approved}`（计划全文 + 文件路径
+ *   + 按 todo 推进）开启新回合。「新上下文执行」由调用方新建会话，用 `adopt()` + `freshPrompt`。
+ */
+import { randomUUID } from "node:crypto";
+import { formatModelRef } from "../ai/providers/channels.js";
+import { AmaError } from "../errors.js";
+import { permissionModeLabel } from "../permissions/modes.js";
+import { todosFromDoneMarkers } from "../plan/done-markers.js";
+import { extractProposedPlan, planFromMarkdown } from "../plan/extract.js";
+import { PLAN_APPROVED_PROMPT, PLAN_APPROVED_TYPE, PLAN_MODE_BRIEF, PLAN_MODE_EXIT, PLAN_MODE_EXIT_TYPE, PLAN_MODE_FULL, PLAN_MODE_TYPE, freshContextPrompt, planApprovedText, planMessage, reminderKind, } from "../plan/prompts.js";
+import { PLAN_CUSTOM_TYPE, PLAN_STATE_CUSTOM_TYPE, currentTodos, executionMode, latestPlan, latestPlanState, maxPlanVersion, resolvePlanDirectory, writePlanFile, } from "../plan/store.js";
+import { APPROVE_REPLY, PLAN_NOTICE_TYPE, registerPlanController, } from "../plan/controller.js";
+import { TODO_CUSTOM_TYPE } from "../tools/todo.js";
+export function createPlanExtensionFactory(options) {
+    return ({ core }) => (core.depth > 0 ? undefined : new PlanExtension(core, options));
+}
+class PlanExtension {
+    core;
+    options;
+    id = "plan";
+    permission;
+    attendance;
+    handler;
+    lastMode;
+    inPlan = false;
+    pre = "default";
+    planId;
+    promptIndex = 0;
+    forceFull = false;
+    pendingExit = false;
+    pendingHandoff;
+    stateDirty = false;
+    approving = false;
+    lastSource;
+    justProposed;
+    executionModel;
+    executionThinking;
+    constructor(core, options) {
+        this.core = core;
+        this.options = options;
+        this.permission = core.options.permission;
+        this.attendance = options.attendance ?? "unattended";
+        const bash = options.config?.bash;
+        const pipeline = this.permission;
+        if (bash !== undefined)
+            pipeline?.setPlanBash?.(bash);
+        this.lastMode = this.permission?.mode ?? "default";
+        this.restore();
+        registerPlanController(core, this);
+    }
+    // -------------------------------------------------------------------------
+    // 恢复与模式跟踪
+    // -------------------------------------------------------------------------
+    restore() {
+        const branch = this.core.manager.branch();
+        const state = latestPlanState(branch);
+        const pending = latestPlan(branch);
+        if (pending !== undefined)
+            this.lastSource = pending.sourceEntryId;
+        if (state?.active === true) {
+            this.inPlan = true;
+            this.pre = state.prePlanMode;
+            this.planId = state.planId;
+            if (state.executionModel !== undefined)
+                this.executionModel = state.executionModel;
+            if (state.executionThinking !== undefined)
+                this.executionThinking = state.executionThinking;
+            if (this.permission !== undefined && this.permission.mode !== "plan")
+                this.permission.setMode("plan");
+            this.lastMode = "plan";
+            // 已投递过的提示按 plan_state 之后的 user 消息计数，提醒节奏接着走
+            const at = branch.findLastIndex((e) => e.type === "custom" && e.customType === PLAN_STATE_CUSTOM_TYPE);
+            this.promptIndex = branch
+                .slice(at + 1)
+                .filter((e) => e.type === "message" && e.message.role === "user").length;
+        }
+        else if (this.lastMode === "plan") {
+            this.inPlan = true;
+            this.planId = randomUUID();
+            this.stateDirty = true;
+        }
+    }
+    handle() {
+        const candidate = this.core;
+        return typeof candidate.prompt === "function" &&
+            typeof candidate.setPermissionMode === "function"
+            ? candidate
+            : undefined;
+    }
+    writeState(active) {
+        const data = { active, prePlanMode: this.pre };
+        if (this.planId !== undefined)
+            data.planId = this.planId;
+        if (active && this.executionModel !== undefined)
+            data.executionModel = this.executionModel;
+        if (active && this.executionThinking !== undefined)
+            data.executionThinking = this.executionThinking;
+        this.core.appendEntry({ type: "custom", customType: PLAN_STATE_CUSTOM_TYPE, data });
+    }
+    onModeChanged(mode) {
+        const previous = this.lastMode;
+        this.lastMode = mode;
+        if (mode === "plan" && !this.inPlan) {
+            this.inPlan = true;
+            this.pre = previous === "plan" ? "default" : previous;
+            this.planId = randomUUID();
+            this.promptIndex = 0;
+            this.pendingExit = false;
+            this.stateDirty = false;
+            this.writeState(true);
+        }
+        else if (mode !== "plan" && this.inPlan) {
+            this.inPlan = false;
+            if (!this.approving)
+                this.pendingExit = true;
+            this.stateDirty = false;
+            this.writeState(false);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // 扩展钩子
+    // -------------------------------------------------------------------------
+    onEvent(event) {
+        switch (event.type) {
+            case "permission_mode_changed":
+                this.onModeChanged(event.mode);
+                break;
+            case "compaction_end":
+                if (event.result !== undefined)
+                    this.forceFull = true;
+                break;
+            case "entry_appended":
+                if (event.entry.type === "custom" && event.entry.customType === TODO_CUSTOM_TYPE)
+                    this.core.emit({ type: "todo_updated", items: currentTodos(this.core.manager.branch()) });
+                break;
+            case "turn_end":
+                if (this.inPlan && event.toolResults.length === 0 && event.message.stopReason === "stop")
+                    this.proposeFromLastAssistant(true);
+                else if (!this.inPlan)
+                    this.writeTodoItems(todosFromDoneMarkers(event.message, this.todos()));
+                break;
+            default:
+                break;
+        }
+    }
+    beforePrompts(_ctx, prompts) {
+        const out = [];
+        if (this.stateDirty) {
+            this.stateDirty = false;
+            this.writeState(true);
+        }
+        const reply = this.textApproval(prompts);
+        if (reply !== undefined) {
+            out.push(planMessage(PLAN_APPROVED_TYPE, reply));
+            return out;
+        }
+        if (this.pendingHandoff !== undefined) {
+            out.push(planMessage(PLAN_APPROVED_TYPE, this.pendingHandoff));
+            this.pendingHandoff = undefined;
+            this.pendingExit = false;
+            return out;
+        }
+        if (this.inPlan) {
+            this.usePlanningModel();
+            this.promptIndex++;
+            const kind = this.forceFull ? "full" : reminderKind(this.promptIndex);
+            this.forceFull = false;
+            if (kind !== undefined)
+                out.push(planMessage(PLAN_MODE_TYPE, kind === "full" ? PLAN_MODE_FULL : PLAN_MODE_BRIEF));
+            return out;
+        }
+        this.restoreExecutionModel();
+        if (this.pendingExit) {
+            this.pendingExit = false;
+            out.push(planMessage(PLAN_MODE_EXIT_TYPE, PLAN_MODE_EXIT));
+        }
+        return out;
+    }
+    onAgentSettled() {
+        if (this.inPlan && this.lastSourceChanged())
+            this.proposeFromLastAssistant(false);
+        const plan = this.justProposed;
+        this.justProposed = undefined;
+        if (plan === undefined)
+            return;
+        if (this.attendance === "text")
+            this.showNotice(this.noticeText(plan));
+        else if (this.attendance === "callback" && this.handler !== undefined) {
+            const handler = this.handler;
+            void (async () => {
+                await this.handle()?.waitForIdle();
+                const answer = await handler(plan);
+                if (answer !== undefined)
+                    await this.respond({ ...answer, planId: plan.id });
+            })().catch((error) => this.log("warn", `plan approval failed: ${String(error)}`));
+        }
+        else if (this.attendance === "unattended" && this.unattendedPolicy() === "stop") {
+            this.log("info", `plan v${plan.version} awaits approval: ${plan.filePath ?? plan.id}`);
+        }
+    }
+    dispose() {
+        registerPlanController(this.core, undefined);
+    }
+    // -------------------------------------------------------------------------
+    // 提取与提交审批
+    // -------------------------------------------------------------------------
+    lastAssistantEntry() {
+        const branch = this.core.manager.branch();
+        for (let i = branch.length - 1; i >= 0; i--) {
+            const entry = branch[i];
+            if (entry.type !== "message" || entry.message.role !== "assistant")
+                continue;
+            const message = entry.message;
+            if (message.stopReason === "error" || message.stopReason === "aborted")
+                return undefined;
+            const text = message.content.map((b) => (b.type === "text" ? b.text : "")).join("");
+            return { id: entry.id, text };
+        }
+        return undefined;
+    }
+    lastSourceChanged() {
+        const last = this.lastAssistantEntry();
+        return last !== undefined && last.id !== this.lastSource;
+    }
+    proposeFromLastAssistant(inRun) {
+        const last = this.lastAssistantEntry();
+        if (last === undefined || last.id === this.lastSource)
+            return;
+        this.lastSource = last.id;
+        const extracted = extractProposedPlan(last.text);
+        if (extracted === undefined)
+            return;
+        const plan = this.propose(extracted, last.id);
+        if (this.attendance === "unattended" && this.unattendedPolicy() === "approve") {
+            const handoff = this.approve(plan, executionMode(undefined, this.pre), "approve");
+            if (inRun)
+                this.core.agent.followUp(planMessage(PLAN_APPROVED_TYPE, handoff));
+            else {
+                this.pendingHandoff = handoff;
+                void this.deliver(PLAN_APPROVED_PROMPT, "plan");
+            }
+            return;
+        }
+        this.justProposed = plan;
+    }
+    proposeFromLastReply() {
+        const pending = this.pending();
+        if (pending !== undefined)
+            return pending;
+        const last = this.lastAssistantEntry();
+        if (last === undefined || last.text.trim() === "")
+            return undefined;
+        this.lastSource = last.id;
+        return this.propose(extractProposedPlan(last.text) ?? planFromMarkdown(last.text), last.id);
+    }
+    propose(extracted, sourceEntryId) {
+        const branch = this.core.manager.branch();
+        const previous = latestPlan(branch);
+        if (previous?.status === "proposed")
+            this.appendPlan({ ...previous, status: "superseded" });
+        if (extracted.truncated === true)
+            this.log("warn", "plan has more than 30 steps; only the first 30 become todo items");
+        this.planId ??= randomUUID();
+        const plan = {
+            id: this.planId,
+            version: maxPlanVersion(branch) + 1,
+            status: "proposed",
+            markdown: extracted.markdown,
+            steps: extracted.steps,
+            sourceEntryId,
+        };
+        const filePath = this.writeFile(plan);
+        if (filePath !== undefined)
+            plan.filePath = filePath;
+        this.appendPlan(plan);
+        const event = {
+            type: "plan_proposed",
+            planId: plan.id,
+            version: plan.version,
+            markdown: plan.markdown,
+            steps: plan.steps,
+        };
+        if (filePath !== undefined)
+            event.filePath = filePath;
+        this.core.emit(event);
+        return plan;
+    }
+    writeFile(plan) {
+        const root = this.permission?.projectRoot ?? this.core.cwd;
+        const { dataDir } = this.options;
+        const configured = this.options.config?.directory;
+        if (dataDir === undefined && configured === undefined)
+            return undefined;
+        const target = resolvePlanDirectory(configured, root, dataDir ?? root);
+        if (target.warning !== undefined)
+            this.log("warn", target.warning);
+        try {
+            return writePlanFile(target.dir, this.core.manager.id, plan.version, plan.markdown);
+        }
+        catch (error) {
+            this.log("warn", `cannot write plan file: ${String(error)}`);
+            return undefined;
+        }
+    }
+    appendPlan(plan) {
+        this.core.appendEntry({ type: "custom", customType: PLAN_CUSTOM_TYPE, data: plan });
+    }
+    unattendedPolicy() {
+        return this.options.config?.unattended ?? "stop";
+    }
+    showNotice(text) {
+        if (this.options.notice !== true)
+            return;
+        const message = { ...planMessage(PLAN_NOTICE_TYPE, text), display: true };
+        this.core.emit({ type: "message_start", message });
+    }
+    noticeText(plan) {
+        const target = permissionModeLabel(executionMode(undefined, this.pre));
+        const where = plan.filePath === undefined ? "" : `（${plan.filePath}）`;
+        return `计划 v${plan.version} 待审批${where}：回复 1 批准并执行（${target}）· 2 以 Accept edits 执行 · 3 以 Auto 执行；回复其它内容作为修改意见，留在 Plan 模式。`;
+    }
+    // -------------------------------------------------------------------------
+    // 审批与交接
+    // -------------------------------------------------------------------------
+    current() {
+        return latestPlan(this.core.manager.branch()) ?? null;
+    }
+    get(planId) {
+        return latestPlan(this.core.manager.branch(), planId) ?? null;
+    }
+    pending() {
+        const plan = latestPlan(this.core.manager.branch());
+        return plan?.status === "proposed" ? plan : undefined;
+    }
+    todos() {
+        return currentTodos(this.core.manager.branch());
+    }
+    prePlanMode() {
+        return this.inPlan ? this.pre : undefined;
+    }
+    setAttendance(kind, handler) {
+        this.attendance = kind;
+        this.handler = handler;
+    }
+    /** 交互模式：计划待审批时用户回复 1 / 2 / 3（等）即批准；返回交接文本。 */
+    textApproval(prompts) {
+        if (this.attendance !== "text" || !this.inPlan)
+            return undefined;
+        const plan = this.pending();
+        const first = prompts[0];
+        if (plan === undefined || first?.role !== "user")
+            return undefined;
+        const text = typeof first.content === "string"
+            ? first.content
+            : first.content.map((b) => (b.type === "text" ? b.text : "")).join("");
+        const choice = APPROVE_REPLY[text.trim().toLowerCase()];
+        if (choice === undefined)
+            return undefined;
+        const mode = choice === "pre" ? executionMode(undefined, this.pre) : choice;
+        return this.approve(plan, mode, "approve");
+    }
+    async respond(response) {
+        let plan = this.pending();
+        if (plan === undefined || plan.id !== response.planId)
+            throw new AmaError("plan_not_found", `no plan ${response.planId} is waiting for approval`);
+        const { decision } = response;
+        if (decision === "reject") {
+            this.appendPlan({ ...plan, status: "rejected" });
+            this.core.emit({ type: "plan_resolved", planId: plan.id, decision });
+            return { planId: plan.id, decision, plan: { ...plan, status: "rejected" } };
+        }
+        if (decision === "revise") {
+            this.core.emit({ type: "plan_resolved", planId: plan.id, decision });
+            if (response.feedback !== undefined && response.feedback.trim() !== "")
+                await this.deliver(response.feedback, undefined);
+            return { planId: plan.id, decision, plan };
+        }
+        if (response.editedMarkdown !== undefined && response.editedMarkdown !== plan.markdown) {
+            const edited = extractProposedPlan(response.editedMarkdown) ?? planFromMarkdown(response.editedMarkdown);
+            plan = this.propose(edited, plan.sourceEntryId);
+            this.justProposed = undefined;
+        }
+        const mode = executionMode(response.mode, this.inPlan ? this.pre : this.lastMode);
+        if (decision === "approve_fresh") {
+            this.approve(plan, mode, decision, false);
+            return {
+                planId: plan.id,
+                decision,
+                mode,
+                plan: { ...plan, status: "approved" },
+                freshPrompt: freshContextPrompt(plan, { todoTool: this.todoTool() }),
+            };
+        }
+        this.pendingHandoff = this.approve(plan, mode, decision);
+        await this.deliver(PLAN_APPROVED_PROMPT, "plan");
+        return { planId: plan.id, decision, mode, plan: { ...plan, status: "approved" } };
+    }
+    /** 落 approved、生成 todo、发 plan_resolved、切模式与执行模型；返回交接文本。 */
+    approve(plan, mode, decision, todos = true) {
+        const approved = { ...plan, status: "approved" };
+        this.appendPlan(approved);
+        if (todos)
+            this.writeTodos(plan);
+        this.core.emit({ type: "plan_resolved", planId: plan.id, decision, mode });
+        this.approving = true;
+        try {
+            if (this.inPlan) {
+                const session = this.handle();
+                if (session !== undefined)
+                    session.setPermissionMode(mode);
+                else {
+                    this.permission?.setMode(mode);
+                    this.core.emit({ type: "permission_mode_changed", mode });
+                }
+            }
+        }
+        finally {
+            this.approving = false;
+        }
+        this.pendingExit = false;
+        this.restoreExecutionModel();
+        return planApprovedText(plan, { todoTool: this.todoTool() });
+    }
+    /** [W5-Z] 活动工具集里没有 todo 时交接改用 `[DONE:n]` 文本标记（plan/done-markers.ts）。 */
+    todoTool() {
+        return this.core.activeToolNames().includes("todo");
+    }
+    writeTodos(plan) {
+        if (plan.steps.length === 0)
+            return;
+        const items = plan.steps.map((step, i) => ({
+            id: step.id,
+            text: step.text,
+            status: i === 0 ? "in_progress" : "pending",
+            planStep: step.id,
+        }));
+        this.writeTodoItems(items);
+    }
+    writeTodoItems(items) {
+        if (items !== undefined)
+            this.core.appendEntry({ type: "custom", customType: TODO_CUSTOM_TYPE, data: { items } });
+    }
+    adopt(plan) {
+        this.appendPlan({ ...plan, status: "approved" });
+        this.lastSource = plan.sourceEntryId;
+        this.writeTodos(plan);
+    }
+    /** 空闲时开一个新回合（运行中则等它结束）；新回合开始即返回。 */
+    async deliver(text, origin) {
+        const session = this.handle();
+        if (session === undefined)
+            return;
+        for (let attempt = 0; attempt < 20; attempt++) {
+            await session.waitForIdle();
+            let failure;
+            session.prompt(text, origin === undefined ? {} : { origin }).catch((error) => {
+                failure = error;
+            });
+            for (let i = 0; i < 3; i++)
+                await Promise.resolve();
+            if (failure instanceof AmaError && failure.code === "busy")
+                continue;
+            if (failure !== undefined)
+                this.log("warn", `plan turn failed: ${String(failure)}`);
+            return;
+        }
+        this.log("warn", "plan turn not started: session stayed busy");
+    }
+    // -------------------------------------------------------------------------
+    // 规划 / 执行分模型（§6.4，缺省关）
+    // -------------------------------------------------------------------------
+    usePlanningModel() {
+        const ref = this.options.config?.model;
+        const level = this.options.config?.thinkingLevel;
+        if ((ref === undefined && level === undefined) || this.executionModel !== undefined)
+            return;
+        const session = this.handle();
+        if (session === undefined)
+            return;
+        this.executionModel = formatModelRef(this.core.model());
+        this.executionThinking = this.core.thinkingLevel();
+        const failed = (error) => this.log("warn", `cannot switch to plan.model ${ref ?? ""}: ${String(error)}`);
+        if (ref !== undefined && ref !== this.executionModel)
+            session.setModel(ref).catch(failed);
+        if (level !== undefined && level !== this.executionThinking)
+            session.setThinkingLevel(level);
+        this.writeState(true);
+    }
+    restoreExecutionModel() {
+        const ref = this.executionModel;
+        const level = this.executionThinking;
+        if (ref === undefined)
+            return;
+        this.executionModel = undefined;
+        this.executionThinking = undefined;
+        const session = this.handle();
+        if (session === undefined)
+            return;
+        if (ref !== formatModelRef(this.core.model()))
+            session
+                .setModel(ref)
+                .catch((error) => this.log("warn", `cannot switch back to ${ref}: ${String(error)}`));
+        if (level !== undefined && level !== this.core.thinkingLevel())
+            session.setThinkingLevel(level);
+    }
+    log(level, message) {
+        (this.options.log ?? this.core.log.bind(this.core))(level, message);
+    }
+}
+export { planController, } from "../plan/controller.js";