pi-web-ui 0.18.0 → 0.19.0

package/dist/server/agent-service.js

@@ -14,7 +14,8 @@ import { spawn } from "node:child_process";
 import { existsSync, readFileSync, statSync, writeFileSync, mkdirSync, watch, } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, getAgentDir, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, defineTool, getAgentDir, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
 import { serializeMessage, serializeStreamingMessage, } from "./serialize.js";
 import { loadCommands, saveCommandsFile, TerminalManager, } from "./terminals.js";
 const SNAPSHOT_INTERVAL_MS = 60;
@@ -211,6 +212,23 @@ function looksLikeText(buf) {
  * payloads by data length (identical lengths within the same ms are far too
  * unlikely to matter).
  */
+/** System prompt for the goal-wizard session. The wizard asks the user a few
+ *  questions (via its goal_ask tool) to scope a raw requirement into a precise,
+ *  reviewable goal, then emits ONLY the final goal text as its last message. */
+function wizardPrompt(draft) {
+    return [
+        `You are a goal-clarification wizard. The user has stated a raw requirement. Your job is to turn it into ONE precise, actionable goal that a coding agent can fully satisfy and that can be strictly reviewed.`, // eslint-disable-line max-len
+        ``,
+        `# User's raw requirement`, // eslint-disable-line no-regex-spaces
+        draft,
+        ``,
+        `Use your goal_ask tool to ask the user focused questions to pin down the essential, ambiguous details. Keep it concise — usually 2 to 4 questions: what exactly to build/do, scope boundaries (what NOT to do), acceptance criteria / done-definition, and any constraints (style, performance, environment).`, // eslint-disable-line max-len
+        `Prefer multiple-choice (goal_ask with options) when you can offer clear choices; use open questions only for things that genuinely need free text.`, // eslint-disable-line max-len
+        `Once you have enough to write an unambiguous, reviewable goal, STOP asking and reply with EXACTLY this format and nothing else (no preamble, no bullets):`, // eslint-disable-line max-len
+        `GOAL: <one concrete, verifiable sentence describing the deliverable and its acceptance criteria>`, // eslint-disable-line max-len
+        `If the user cancels or stops answering (the tool reports a cancellation), still produce a sensible best-effort goal from what you already know.`, // eslint-disable-line max-len
+    ].join("\n");
+}
 function contentFingerprint(m) {
     const content = m.content;
     if (!Array.isArray(content) || content.length === 0)
@@ -405,6 +423,15 @@ export class WebUIContext {
             this.emit({ type: "dialog_closed", id });
         }
     }
+    /** Close every pending dialog as cancelled (used when a goal wizard aborts —
+     *  its unanswered browser dialogs must vanish, not linger). */
+    cancelPendingDialogs() {
+        for (const [id, resolve] of this.pendingDialogs) {
+            this.pendingDialogs.delete(id);
+            resolve(null);
+            this.emit({ type: "dialog_closed", id });
+        }
+    }
     // -- inert TUI-only affordances ------------------------------------------
     onTerminalInput = () => () => { };
     setWorkingMessage = () => { };
@@ -639,6 +666,28 @@ class ClientStateStore {
         ].slice(0, 30);
         this.save();
     }
+    /** Last-used goal/review prefs for a client, or undefined if never set. */
+    getGoalPrefs(clientId) {
+        const s = this.load()[clientId];
+        if (!s?.goalPrefs)
+            return undefined;
+        return {
+            reviewModel: s.goalPrefs.reviewModel ?? null,
+            maxRounds: s.goalPrefs.maxRounds ?? 0,
+            locked: s.goalPrefs.locked ?? true,
+        };
+    }
+    /** Persist the client's goal/review preferences (model choice, rounds, lock). */
+    saveGoalPrefs(clientId, prefs) {
+        const all = this.load();
+        const state = (all[clientId] ??= { projects: [] });
+        state.goalPrefs = {
+            reviewModel: prefs?.reviewModel ?? null,
+            maxRounds: prefs?.maxRounds ?? 0,
+            locked: prefs?.locked ?? true,
+        };
+        this.save();
+    }
 }
 /** Cap on simultaneously open conversations of ONE project (each keeps a full
  *  runtime alive; conversations of other projects keep their own lists). */
@@ -694,6 +743,51 @@ export class ClientSession {
      *  top bar applies to every chat, not just the one that set it. Seeded by
      *  the first conversation and reused by later ones. */
     sharedModelRuntime;
+    // -----------------------------------------------------------------------
+    // Goal / review state. When a goal is active, every finished agent run
+    // (agent_end) is checked by an ISOLATED reviewer agent; a failing review
+    // injects its feedback back into the main session to revise. All goal
+    // mutation goes through setGoal/clearGoal so UI state stays consistent.
+    // -----------------------------------------------------------------------
+    goal = {
+        goal: null,
+        reviewModel: null,
+        maxRounds: 0, // 0 = unlimited (keep revising until the goal passes)
+        locked: true,
+        reviewing: false,
+        round: 0,
+        status: "",
+        verdict: "pending",
+        wizard: {
+            active: false,
+            draft: "",
+            model: null,
+            step: 0,
+            maxSteps: 6,
+            status: "",
+        },
+    };
+    /** Guard: only one review may run at a time (agent_end fires per turn and
+     *  review is async). */
+    goalReviewing = false;
+    /** Guard: the goal wizard and the review loop are mutually exclusive — a
+     *  wizard in flight stops review triggers (and vice versa). */
+    goalWizardRunning = false;
+    /** Aborts the currently-running goal wizard (user clicked ✗ / timed out). Drives
+     *  the in-flight goal_ask dialog to resolve as cancelled and (via the run
+     *  signal) stops the wizard session's agent run. Recreated per wizard. */
+    wizardAbort = null;
+    /** The wizard's AgentSession while it runs — lets clearGoal truly terminate it
+     *  (abort the run), not just flip a flag. */
+    wizardSession = null;
+    /** True when the wizard was cancelled externally (✗ / clear_goal / timeout) —
+     *  startGoalWizard reads this after the run to avoid setting a goal. */
+    wizardCancelled = false;
+    /** Idle-timeout for the wizard: if no answer arrives within this window (a
+     *  dialog is up but the user doesn't respond), the wizard is auto-cancelled. */
+    static WIZARD_IDLE_TIMEOUT_MS = 5 * 60_000;
+    /** Absolute deadline for the whole wizard session (model latency guard). */
+    static WIZARD_MAX_TOTAL_MS = 20 * 60_000;
     /** The active conversation (all session operations target it). */
     get conv() {
         const conv = this.convs.get(this.activeId);
@@ -745,6 +839,13 @@ export class ClientSession {
     static async create(clientId, cwd, stateStore) {
         const agentDir = process.env.PI_CODING_AGENT_DIR ?? getAgentDir();
         const cs = new ClientSession(clientId, cwd, agentDir, stateStore);
+        // Restore last-used goal/review preferences so model & rounds survive reload.
+        const gPrefs = stateStore.getGoalPrefs(clientId);
+        if (gPrefs) {
+            cs.goal.reviewModel = gPrefs.reviewModel;
+            cs.goal.maxRounds = gPrefs.maxRounds;
+            cs.goal.locked = gPrefs.locked;
+        }
         const runtime = await createAgentSessionRuntime(cs.makeRuntimeFactory(), {
             cwd,
             agentDir,
@@ -835,6 +936,9 @@ export class ClientSession {
         // Reconnect: same for the slash-command catalog (the picker needs it even
         // before the client asks).
         void this.pushSlashCommands();
+        // Reconnect: push the remembered goal prefs (model choice, rounds cap,
+        // locked) so the goal bar restores them on reload — "全局记忆".
+        this.emitGoalStatus();
     }
     detachSink(send) {
         this.sinks.delete(send);
@@ -956,7 +1060,46 @@ export class ClientSession {
                 break;
             // A run finished or a new entry was persisted — keep the session list fresh
             // (new chat + first message, completed turns, compaction, etc.).
-            case "agent_end":
+            case "agent_end": {
+                this.scheduleSessionsRefresh();
+                const g = this.goal;
+                // Manual interrupt (Stop button / abort): the last assistant message
+                // carries stopReason "aborted". A half-finished run should NOT be
+                // reviewed (it would fail and inject a revision, only to be stopped
+                // again → an endless review loop). Clear the goal so the review loop
+                // stops too, then let the user give a fresh instruction.
+                const aborted = event.messages.some((m) => {
+                    const a = m;
+                    return a.role === "assistant" && a.stopReason === "aborted";
+                });
+                if (aborted) {
+                    if (g.goal) {
+                        this.goal.goal = null;
+                        this.goal.reviewing = false;
+                        this.goal.verdict = "pending";
+                        this.goal.feedback = undefined;
+                        this.goal.status = "已手动停止，目标审查已中止";
+                        this.emitGoalStatus();
+                        this.emit({
+                            type: "notice",
+                            level: "warning",
+                            text: "⏹ 已手动停止，目标审查已中止（想继续可重新设定目标）",
+                        });
+                    }
+                    break;
+                }
+                // Goal review hook: after the run finished normally, if a goal is
+                // active (and it belonged to the ACTIVE conversation) and we're not
+                // already mid-review, spawn the isolated reviewer.
+                if (g.goal &&
+                    !g.reviewing &&
+                    !this.goalWizardRunning &&
+                    conv.id === this.activeId &&
+                    !this.disposed) {
+                    void this.runGoalReview(conv);
+                }
+                break;
+            }
             case "entry_appended":
                 this.scheduleSessionsRefresh();
                 break;
@@ -1122,11 +1265,12 @@ export class ClientSession {
      * Never throws / never crashes the server: spawn errors (ENOENT etc.)
      * resolve with code -1 so callers can report them as notices.
      */
-    runAsync(cmd, args, timeoutMs) {
+    runAsync(cmd, args, timeoutMs, cwd) {
         return new Promise((resolve) => {
             let p;
             try {
                 p = spawn(cmd, args, {
+                    ...(cwd ? { cwd } : {}),
                     stdio: ["ignore", "pipe", "pipe"],
                     // Windows: npm and friends are .cmd shims — Node can only exec
                     // them through the shell (otherwise spawn npm → ENOENT).
@@ -3055,6 +3199,665 @@ export class ClientSession {
             });
         }
     }
+    // ---------------------------------------------------------------------------
+    // Goal / review
+    // ---------------------------------------------------------------------------
+    /** Push the current goal status to the client (the goal bar UI). */
+    emitGoalStatus() {
+        this.emit({ type: "goal_status", status: { ...this.goal } });
+    }
+    /**
+     * Set (or clear) the active goal. `goal === ""` clears it. The goal is
+     * applied to the CURRENT active conversation of this project; reviews check
+     * whatever run finishes next (agent_end).
+     */
+    async setGoal(goalText, opts) {
+        const text = (goalText ?? "").trim();
+        if (!text) {
+            await this.clearGoal();
+            return;
+        }
+        this.goal.goal = text;
+        // Model & rounds preference semantics ("全局记忆"):
+        //  - reviewModel undefined → keep the remembered choice; empty → main model.
+        //  - maxRounds 0 = unlimited (default); >0 = finite cap (clamped to 50).
+        if (opts?.reviewModel !== undefined)
+            this.goal.reviewModel = opts.reviewModel || null;
+        if (typeof opts?.maxRounds === "number") {
+            const mr = Math.round(opts.maxRounds);
+            this.goal.maxRounds = mr >= 1 ? Math.min(mr, 50) : 0;
+        }
+        if (opts?.locked !== undefined)
+            this.goal.locked = opts.locked;
+        // Persist the chosen preferences so they survive reload.
+        this.stateStore.saveGoalPrefs(this.clientId, {
+            reviewModel: this.goal.reviewModel,
+            maxRounds: this.goal.maxRounds,
+            locked: this.goal.locked,
+        });
+        // Reset the loop for a freshly-set goal (single-shot goals start at 0).
+        this.goal.round = 0;
+        this.goal.reviewing = false;
+        this.goal.verdict = "pending";
+        this.goal.feedback = undefined;
+        this.goal.wizard.active = false;
+        this.goal.wizard.status = "";
+        this.goal.status = "目标已设，等待生成…";
+        this.emitGoalStatus();
+        this.emit({
+            type: "notice",
+            level: "info",
+            text: `🎯 已设目标：${text.slice(0, 80)}${text.length > 80 ? "…" : ""}`,
+        });
+        // Auto-start generation right after setting the goal (unless this setGoal is
+        // the wizard's internal one, which kicks off itself). This makes the direct
+        // goal-bar path behave like the AI-提炼 path: set a target → agent begins.
+        if (opts?.autoStart !== false) {
+            try {
+                const s = this.conv.session;
+                await s.sendUserMessage(`【目标已设定】\n\n${text}\n\n请现在开始实现这个目标。`, { deliverAs: s.isStreaming ? "steer" : "followUp" });
+            }
+            catch {
+                // Best-effort; the user can still prompt manually.
+            }
+            this.flushSnapshot();
+        }
+    }
+    /**
+     * Collaborative target wizard. Turns a raw user requirement into a refined
+     * goal by spinning up an ISOLATED wizard session (own fresh ModelRuntime +
+     * in-memory session, so its model choice is its own) that questions the user
+     * via `goal_ask` (multiple-choice + free-text, bridged to the browser through
+     * the existing select/input dialog), converging on a goal, then auto-sets it.
+     * Mutually exclusive with the review loop.
+     */
+    async startGoalWizard(text, opts) {
+        const draft = (text ?? "").trim();
+        if (!draft)
+            return;
+        if (this.goalWizardRunning) {
+            this.emit({
+                type: "notice",
+                level: "warning",
+                text: "已有目标调研进行中，请等它完成…",
+            });
+            return;
+        }
+        if (this.goalReviewing) {
+            this.emit({
+                type: "notice",
+                level: "warning",
+                text: "正在审查中，无法开始目标调研，请稍等…",
+            });
+            return;
+        }
+        // Questions are NOT capped (调研不限制) — the wizard converges on its own;
+        // the idle- and total-timeouts are the only guards. maxSteps is purely a
+        // soft UI indicator, not a hard stop.
+        const maxSteps = 20;
+        this.goalWizardRunning = true;
+        this.wizardCancelled = false;
+        this.wizardAbort = new AbortController();
+        this.wizardSession = null;
+        this.goal.wizard.active = true;
+        this.goal.wizard.draft = draft;
+        this.goal.wizard.model = opts?.wizardModel ?? null;
+        // Remember the model choice (and persist rounds/lock) — global memory.
+        if (opts?.wizardModel !== undefined && opts.wizardModel !== null)
+            this.goal.reviewModel = opts.wizardModel || null;
+        this.stateStore.saveGoalPrefs(this.clientId, {
+            reviewModel: this.goal.reviewModel,
+            maxRounds: this.goal.maxRounds,
+            locked: this.goal.locked,
+        });
+        this.goal.wizard.step = 0;
+        this.goal.wizard.maxSteps = maxSteps;
+        this.goal.wizard.status = "调研中…";
+        this.goal.status = "目标调研中…";
+        this.emitGoalStatus();
+        // Idle-timeout: cancel the wizard if no question is answered within the
+        // window (a stale dialog with no user response must not run forever). A
+        // fresh timer is armed for each question; cleared once the run ends.
+        const ac = this.wizardAbort;
+        let idleTimer = null;
+        const armIdle = () => {
+            if (idleTimer)
+                clearTimeout(idleTimer);
+            idleTimer = setTimeout(() => {
+                if (!ac.signal.aborted) {
+                    this.wizardCancelled = true;
+                    ac.abort(new Error("目标调研超时（等待回答过久）"));
+                }
+            }, ClientSession.WIZARD_IDLE_TIMEOUT_MS);
+            idleTimer.unref?.();
+        };
+        const clearIdle = () => {
+            if (idleTimer) {
+                clearTimeout(idleTimer);
+                idleTimer = null;
+            }
+        };
+        armIdle();
+        // Total-duration guard: hard cap on the whole wizard session (model
+        // latency / unexpected loops must not run forever).
+        const totalTimer = setTimeout(() => {
+            if (!ac.signal.aborted) {
+                this.wizardCancelled = true;
+                ac.abort(new Error("目标调研超过总时长上限"));
+            }
+        }, ClientSession.WIZARD_MAX_TOTAL_MS);
+        totalTimer.unref?.();
+        this.emit({
+            type: "notice",
+            level: "info",
+            text: `🔍 正在围绕需求展开调研：${draft.slice(0, 60)}${draft.length > 60 ? "…" : ""}`,
+        });
+        // The main conversation to show wizard progress cards in.
+        let mainSession = this.session;
+        try {
+            const conv = this.conv;
+            mainSession = conv.session;
+        }
+        catch {
+            // no active conversation yet
+        }
+        let refinedGoal = "";
+        try {
+            const wmSpec = opts?.wizardModel
+                ? this.resolveReviewModel(opts.wizardModel)
+                : null; // reuse the honest "provider/id" parser
+            const services = await createAgentSessionServices({
+                cwd: this.cwd,
+                agentDir: this.agentDir,
+                modelRuntime: await ModelRuntime.create({
+                    authPath: join(this.agentDir, "auth.json"),
+                    modelsPath: join(this.agentDir, "models.json"),
+                }),
+            });
+            let model;
+            if (wmSpec)
+                model = services.modelRuntime.getModel(wmSpec.provider, wmSpec.id);
+            if (!model) {
+                const mainModel = mainSession.model;
+                if (mainModel?.provider && mainModel.id)
+                    model = services.modelRuntime.getModel(mainModel.provider, mainModel.id);
+            }
+            // The wizard asks the user questions via this tool; each call bridges one
+            // select/input dialog to the browser and returns the user's answer.
+            let qStep = 0;
+            const goalAsk = defineTool({
+                name: "goal_ask",
+                label: "Ask the user",
+                description: "Ask the user ONE question at a time to scope down the goal. Provide a clear question and 2-4 concise options; or ask an open question. Returns the user's chosen answer.",
+                parameters: Type.Object({
+                    question: Type.String({ description: "The question to ask" }),
+                    options: Type.Optional(Type.Array(Type.String())),
+                }),
+                // ONE question at a time. Sequential execution prevents the agent from
+                // firing parallel goal_ask calls whose dialogs would overwrite each other
+                // in the single browser modal (leaving earlier ones deadlocked — the
+                // reported "调研卡住").
+                executionMode: "sequential",
+                execute: async (_id, params, _sig, _onUpdate, ctx) => {
+                    qStep += 1;
+                    if (qStep > maxSteps) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: "(达到最大提问数，请直接给出收敛后的目标文本作为最终答案)",
+                                },
+                            ],
+                            details: {},
+                        };
+                    }
+                    // Show the question in the main flow BEFORE blocking on the dialog, so
+                    // the user sees the wizard working even before answering.
+                    this.goal.wizard.step = qStep;
+                    this.goal.wizard.status = `调研中：请回答第 ${qStep} 题`;
+                    this.emitGoalStatus();
+                    try {
+                        armIdle();
+                        const isChoice = !!(params.options && params.options.length > 0);
+                        await this.pushWizardCard(mainSession, `🔍 第 ${qStep} 题：${params.question}${isChoice ? `【${params.options.join(" / ")}】` : ""}`, { question: params.question });
+                        // Resolve the pending dialog as cancelled if the wizard is aborted.
+                        let aborted = false;
+                        const onAbort = () => {
+                            aborted = true;
+                        };
+                        ac.signal.addEventListener("abort", onAbort, { once: true });
+                        const choose = isChoice
+                            ? ctx.ui.select(`🔍 第 ${qStep} 题：${params.question}`, params.options)
+                            : ctx.ui.input(`🔍 第 ${qStep} 题：${params.question}`);
+                        const ans = (await choose);
+                        ac.signal.removeEventListener("abort", onAbort);
+                        if (aborted || ac.signal.aborted) {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: "(调研已取消，请不要继续提问，直接结束对话)",
+                                    },
+                                ],
+                                details: {},
+                            };
+                        }
+                        if (ans === undefined || ans === null || ans === false || ans === "") {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: "(用户已取消调研，请直接给出你当前收敛的目标文本作为最终答案)",
+                                    },
+                                ],
+                                details: {},
+                            };
+                        }
+                        // Record the answer in the flow too (instant append, main session idle).
+                        await this.pushWizardCard(mainSession, `↳ 您的回答：${ans}`, { question: params.question, answer: String(ans) });
+                        return {
+                            content: [{ type: "text", text: `用户回答：${ans}` }],
+                            details: {},
+                        };
+                    }
+                    catch (err) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: ac.signal.aborted
+                                        ? "(调研已取消，请不要继续提问，直接结束对话)"
+                                        : `提问失败：${err.message}`,
+                                },
+                            ],
+                            details: {},
+                        };
+                    }
+                },
+            });
+            const srv = await createAgentSessionFromServices({
+                services,
+                sessionManager: SessionManager.inMemory(this.cwd),
+                customTools: [goalAsk],
+                ...(model ? { model } : {}),
+            });
+            const wizard = srv.session;
+            this.wizardSession = wizard;
+            await wizard.bindExtensions({ mode: "rpc", uiContext: this.webUi });
+            // Cancel watcher: when the user ✗s / idle-timeout fires, truly stop the
+            // wizard's agent run (not just mark it).
+            if (!ac.signal.aborted) {
+                ac.signal.addEventListener("abort", () => {
+                    void wizard.abort().catch(() => { });
+                    // Close the unanswered browser dialog(s) the wizard may have up.
+                    this.webUi.cancelPendingDialogs();
+                }, { once: true });
+            }
+            await wizard.prompt(wizardPrompt(draft));
+            refinedGoal = wizard.getLastAssistantText()?.trim() ?? "";
+            // The wizard is prompted to emit "GOAL: <text>". Parse past the marker;
+            // if it didn't follow, strip a leading preamble line and keep the rest.
+            const goalMatch = refinedGoal.match(/GOAL\s*[:：]\s*([\s\S]*)/i);
+            if (goalMatch) {
+                refinedGoal = goalMatch[1].trim();
+            }
+            else {
+                const lines = refinedGoal.split("\n").filter((l) => l.trim());
+                if (lines.length > 1 && !/[。.!?？]\s*$/.test(lines[0])) {
+                    // First line looks like preamble (no sentence-ending punctuation).
+                    refinedGoal = lines.slice(1).join(" ").trim();
+                }
+            }
+            await srv.session.dispose();
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `目标调研失败：${err.message}`,
+            });
+        }
+        finally {
+            clearIdle();
+            clearTimeout(totalTimer);
+            this.goalWizardRunning = false;
+            this.goal.wizard.active = false;
+            this.goal.wizard.step = 0;
+            this.goal.wizard.status = "";
+            this.wizardSession = null;
+            this.emitGoalStatus();
+        }
+        // Aborted externally (✗ / clear_goal / idle-timeout): do NOT set a goal.
+        if (ac.signal.aborted || this.wizardCancelled) {
+            this.emit({
+                type: "notice",
+                level: "info",
+                text: `目标调研已取消${ac.signal.reason ? `：${String(ac.signal.reason?.message ?? ac.signal.reason)}` : ""}`,
+            });
+            this.wizardAbort = null;
+            return;
+        }
+        if (!refinedGoal.trim()) {
+            this.emit({
+                type: "notice",
+                level: "warning",
+                text: "调研未产出有效目标，请重试",
+            });
+            return;
+        }
+        // Auto-set the refined goal. The wizard workflow implies "set a goal and
+        // work until it passes", so default LOCKED=true unless the user explicitly
+        // turned the lock off (a lock lets the review loop keep revising to pass;
+        // without it the review is single-shot).
+        const wantLocked = opts?.locked === undefined ? true : opts.locked;
+        await this.setGoal(refinedGoal, {
+            reviewModel: this.goal.reviewModel ?? undefined,
+            maxRounds: opts?.maxRounds,
+            locked: wantLocked,
+            // The wizard kicks off generation itself below — avoid a double kick.
+            autoStart: false,
+        });
+        const g2 = this.goal;
+        this.wizardCancelled = false;
+        this.wizardAbort = null;
+        this.emit({
+            type: "notice",
+            level: "info",
+            text: `🎯 调研完成，目标已设为：${refinedGoal.slice(0, 80)}${refinedGoal.length > 80 ? "…" : ""}`,
+        });
+        // Kick the main agent into generating right away (no manual "开始吧").
+        // The kick-off is a user message so it appears in the flow and triggers a
+        // normal turn; the finishing agent_end then runs the review loop.
+        try {
+            await mainSession.sendUserMessage(`【目标已设定】\n\n${g2.goal}\n\n请现在开始实现这个目标。`, { deliverAs: mainSession.isStreaming ? "steer" : "followUp" });
+        }
+        catch {
+            // Generation kick-off is best-effort; the user can still prompt manually.
+        }
+    }
+    /** Persist goal/review preference defaults (model, rounds cap, locked) without
+     *  touching the active goal — so changes in the goal bar are remembered across
+     *  reloads. maxRounds 0 = unlimited. Emits goal_status so the UI stays synced. */
+    async setGoalPrefs(opts) {
+        if (opts?.reviewModel !== undefined)
+            this.goal.reviewModel = opts.reviewModel || null;
+        if (typeof opts?.maxRounds === "number") {
+            const mr = Math.round(opts.maxRounds);
+            this.goal.maxRounds = mr >= 1 ? Math.min(mr, 50) : 0;
+        }
+        if (opts?.locked !== undefined)
+            this.goal.locked = opts.locked;
+        this.stateStore.saveGoalPrefs(this.clientId, {
+            reviewModel: this.goal.reviewModel,
+            maxRounds: this.goal.maxRounds,
+            locked: this.goal.locked,
+        });
+        this.emitGoalStatus();
+    }
+    /** Clear the active goal (cancels the review loop AND aborts a running
+     *  goal wizard — truly terminating its in-flight dialog + agent run). */
+    async clearGoal() {
+        this.goal.goal = null;
+        this.goal.reviewing = false;
+        this.goal.verdict = "pending";
+        this.goal.feedback = undefined;
+        this.goal.wizard.active = false;
+        this.goal.wizard.status = "";
+        this.goal.status = "";
+        this.emitGoalStatus();
+        // Abort a running wizard for real (✗ in the goal bar while scoping).
+        if (this.goalWizardRunning || this.wizardAbort || this.wizardSession) {
+            this.wizardCancelled = true;
+            this.webUi.cancelPendingDialogs();
+            this.wizardAbort?.abort();
+            const ws2 = this.wizardSession;
+            this.wizardSession = null;
+            if (ws2) {
+                await ws2.abort().catch(() => { });
+                ws2.dispose();
+            }
+            this.wizardAbort = null;
+        }
+    }
+    /** Build a "provider/id" or null for the reviewer model, validating it exists. */
+    resolveReviewModel(spec) {
+        if (!spec)
+            return null;
+        const slash = spec.indexOf("/");
+        if (slash <= 0 || slash === spec.length - 1)
+            return null;
+        return { provider: spec.slice(0, slash), id: spec.slice(slash + 1), spec };
+    }
+    /**
+     * The whitelisted reviewer plan — tell the reviewer what to decide and how
+     * to report, regardless of which model it runs on.
+     */
+    reviewerPrompt(goal, round, maxRounds, output, gitDiff) {
+        return [
+            `You are a strict, independent goal-reviewer. Your ONLY job is to judge whether the agent's work fully satisfies the stated goal, by checking the agent's final output and, when present, its git diff.`, // eslint-disable-line max-len
+            ``,
+            `# Goal`, // eslint-disable-line no-regex-spaces
+            goal,
+            ``,
+            `# Agent's final output`, // eslint-disable-line no-regex-spaces
+            output.length > 0 ? output : "(the agent produced no text — inspect the diff)", // eslint-disable-line max-len
+            ``,
+            `# Git diff (if any)`, // eslint-disable-line no-regex-spaces
+            gitDiff.length > 0 ? gitDiff : "(no staged/committed changes detected)", // eslint-disable-line max-len
+            ``,
+            `This is review round ${round}${maxRounds > 0 ? ` of up to ${maxRounds}` : " (no round cap — keep revising until it passes)"}.`, // eslint-disable-line max-len
+            ``,
+            `Decide: does the work satisfy the goal? If yes, respond with ONLY a JSON object with this exact shape (no markdown fences, no extra text):`, // eslint-disable-line max-len
+            `{"verdict":"pass","feedback":"<one short sentence: what was satisfied>"}`, // eslint-disable-line max-len
+            `If NO, respond with ONLY: {"verdict":"fail","feedback":"<concise, actionable list of what the agent must fix to satisfy the goal>"}`, // eslint-disable-line max-len
+            `The feedback for a fail must be specific enough that the agent can act on it directly.`, // eslint-disable-line max-len
+        ].join("\n");
+    }
+    /** Insert a wizard progress card into the MAIN conversation flow and render it
+     *  IMMEDIATELY (the main session is idle while the wizard runs in its own
+     *  session, so — unlike nextTurn, which queues until the next user prompt —
+     *  sending without a delivery option appends + persists + emits at once). */
+    async pushWizardCard(sess, text, details) {
+        try {
+            await sess.sendCustomMessage({
+                customType: "goal-wizard",
+                content: [{ type: "text", text }],
+                display: true,
+                details: { type: "goal-wizard", ...details },
+            });
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    /** Run a git diff (unstaged + staged) in the workspace, or "" when not a repo. */
+    async gitDiff() {
+        try {
+            const { code, out } = await this.runAsync("git", ["diff", "HEAD"], 10_000, this.cwd);
+            if (code !== 0)
+                return "";
+            return out.slice(0, 60_000);
+        }
+        catch {
+            return "";
+        }
+    }
+    /**
+     * The review loop: build an ISOLATED reviewer session (own fresh
+     * AgentSession + own ModelRuntime so the reviewer truly runs on a different
+     * model without touching the main session), ask it to judge the goal, then:
+     *   - pass  → set status "已通过", insert a verdict card, end the loop;
+     *   - fail  → inject the feedback as a user message into the main session
+     *             to steer a revision; the next agent_end re-reviews with the
+     *             same round budget.
+     * Guarded so it never runs two reviews concurrently.
+     */
+    async runGoalReview(conv) {
+        // The review is bound to the conversation that just ran — but the user may
+        // have switched to another conversation meanwhile. Reviews only make sense
+        // for the conversation that generated output, so track it locally.
+        const mainConv = this.convs.get(conv.id) ?? conv;
+        const mainSession = mainConv.session;
+        const g = this.goal;
+        if (!g.goal ||
+            this.goalReviewing ||
+            this.goalWizardRunning ||
+            this.disposed)
+            return;
+        // Narrowed copy — TS control-flow can't narrow `g.goal` (a mutable shared
+        // object field) through the entire async body, so capture it here.
+        const goalText = g.goal;
+        // Cap rounds: single-shot (locked=false) always exactly one review.
+        // For locked goals, maxRounds 0 = unlimited (keep revising until pass).
+        const budget = g.locked ? (g.maxRounds > 0 ? g.maxRounds : Infinity) : 1;
+        if (g.locked && g.maxRounds > 0 && g.round >= budget) {
+            this.goal.status = `已达最大轮数（${budget}），停止审查`;
+            this.goal.reviewing = false;
+            this.emitGoalStatus();
+            return;
+        }
+        this.goalReviewing = true;
+        g.reviewing = true;
+        g.round += 1;
+        g.verdict = "pending";
+        g.feedback = undefined;
+        g.status = `审查中（第 ${g.round} 轮）…`;
+        this.emitGoalStatus();
+        // Collect the review inputs.
+        let finalText = "";
+        try {
+            finalText = mainSession.getLastAssistantText() ?? "";
+        }
+        catch {
+            finalText = "";
+        }
+        const diff = await this.gitDiff();
+        let reviewerVerdict = "fail";
+        let reviewerFeedback = "（审查无法完成）";
+        try {
+            const rmSpec = this.resolveReviewModel(g.reviewModel);
+            const services = await createAgentSessionServices({
+                cwd: this.cwd,
+                agentDir: this.agentDir,
+                // A FRESH ModelRuntime for the reviewer — isolated from the shared
+                // one used by the main conversations, so its model choice is its own.
+                modelRuntime: await ModelRuntime.create({
+                    authPath: join(this.agentDir, "auth.json"),
+                    modelsPath: join(this.agentDir, "models.json"),
+                }),
+            });
+            // Model resolution: explicit reviewer model, else the main session's
+            // current model (so a goal works even when no reviewer model is given).
+            let model;
+            if (rmSpec) {
+                model = services.modelRuntime.getModel(rmSpec.provider, rmSpec.id);
+            }
+            if (!model) {
+                const mainModel = mainSession.model;
+                if (mainModel?.provider && mainModel.id) {
+                    model = services.modelRuntime.getModel(mainModel.provider, mainModel.id);
+                }
+            }
+            const srv = await createAgentSessionFromServices({
+                services,
+                sessionManager: SessionManager.inMemory(this.cwd),
+                ...(model ? { model } : {}),
+            });
+            const reviewCap = g.locked && g.maxRounds > 0 ? g.maxRounds : 0; // 0 = no cap
+            const reviewer = srv.session;
+            await reviewer.prompt(this.reviewerPrompt(goalText, g.round, reviewCap, finalText, diff));
+            // Parse the reviewer's final output (expected to be a JSON object).
+            const raw = reviewer.getLastAssistantText() ?? "";
+            const m = raw.match(/\{\s*"verdict"\s*:\s*"(pass|fail)"[^}]*\}/);
+            if (m) {
+                reviewerVerdict = m[1];
+                const fm = raw.match(/"feedback"\s*:\s*"([^"]*)"/);
+                reviewerFeedback = fm?.[1] ?? "";
+            }
+            else {
+                // No JSON — assume fail with the raw output as feedback.
+                reviewerVerdict = "fail";
+                reviewerFeedback = raw.slice(0, 2000);
+            }
+            await srv.session.dispose();
+        }
+        catch (err) {
+            reviewerVerdict = "fail";
+            reviewerFeedback = `审查过程中出错：${err.message}`;
+        }
+        this.goalReviewing = false;
+        g.reviewing = false;
+        g.verdict = reviewerVerdict;
+        g.feedback = reviewerFeedback;
+        const round = g.round;
+        // Display cap: 0 means "unlimited" (keep revising until pass).
+        const budgetForCard = g.locked ? (Number.isFinite(budget) ? budget : 0) : 1;
+        const verdict = reviewerVerdict;
+        const feedback = reviewerFeedback;
+        /** Format "round/cap" for user-facing strings; cap 0 → 不限. */
+        const capFmt = (cap) => cap > 0 ? `第 ${round}/${cap} 轮` : `第 ${round} 轮（不限）`;
+        if (verdict === "pass") {
+            g.status = "✅ 已通过目标审查";
+            this.emit({ type: "notice", level: "info", text: "✅ 目标已通过审查" });
+            g.goal = null; // a passed goal is done and cleared
+            this.emitGoalStatus();
+            // Pass = the review result goes straight into the conversation as an
+            // ordinary user message (NO separate goal-review card). It both tells the
+            // USER the outcome and hands the main agent back out of "goal mode", so a
+            // follow-up instruction like "发布" is a normal request — not a confirm echo.
+            try {
+                await mainSession.sendUserMessage(`✅ 目标已达成并通过审查（第 ${round} 轮）。\n\n目标：${goalText}\n\n${feedback}\n\n（目标模式已解除，接下来按你的普通指令响应。）`, { deliverAs: mainSession.isStreaming ? "steer" : "followUp" });
+            }
+            catch {
+                // Best-effort.
+            }
+            this.flushSnapshot();
+            return;
+        }
+        // Failure: if rounds remain, steer a revision; else report the loop done.
+        // For unlimited (budget=0) isLastRound is always false → keeps revising.
+        const isLastRound = !g.locked ? true : g.maxRounds > 0 && g.round >= g.maxRounds;
+        if (!isLastRound) {
+            g.status = `本轮不通过，正在把意见交给 agent 修改（${capFmt(budgetForCard)}）…`;
+            this.emit({
+                type: "notice",
+                level: "warning",
+                text: `目标审查第 ${g.round}/${budgetForCard > 0 ? budgetForCard : "不限"} 轮未通过，把意见交给 agent 修改…`,
+            });
+            // Inject the reviewer's feedback into the main session to revise (this IS
+            // the fail review result, as an ordinary user message — no separate card).
+            try {
+                const steerText = `【目标审查：第 ${g.round}/${budgetForCard > 0 ? budgetForCard : "不限"} 轮未通过】\n\n目标：${goalText}\n\n` +
+                    `审查意见：${feedback}\n\n请根据以上意见修改你的成果，使其完全满足目标。`;
+                await mainSession.sendUserMessage(steerText, {
+                    deliverAs: mainSession.isStreaming ? "steer" : "followUp",
+                });
+            }
+            catch (err) {
+                g.status = `意见注入失败：${err.message}`;
+            }
+            this.emitGoalStatus();
+            this.flushSnapshot();
+            return;
+        }
+        // Rounds exhausted (finite cap reached / single-shot failed). Deliver the
+        // fail result as an ordinary user message (no separate card), like the pass
+        // and revise paths — the review result always lands in the conversation.
+        g.status =
+            g.locked && g.maxRounds > 0
+                ? `已达最大轮数（${g.maxRounds}），目标仍未通过`
+                : `目标未通过（${capFmt(budgetForCard)}）`;
+        try {
+            await mainSession.sendUserMessage(`❌ 目标未通过审查（第 ${round}/${budgetForCard > 0 ? budgetForCard : "不限"} 轮）。\n\n目标：${goalText}\n\n审查意见：${feedback}`, { deliverAs: mainSession.isStreaming ? "steer" : "followUp" });
+        }
+        catch {
+            // Best-effort.
+        }
+        this.emit({ type: "notice", level: "warning", text: "目标未通过审查（已达最大轮数）" });
+        g.goal = null; // loop exhausted — clear the active goal
+        this.emitGoalStatus();
+        this.flushSnapshot();
+    }
     /** Switch to a specific model by "provider/id" (e.g. "anthropic/claude-sonnet-5"). */
     async setModel(modelId) {
         try {