@ai-agent-forge/agent-forge 0.88.4 → 0.88.6

package/bundled-plugins/alignment/dist/index.js

@@ -0,0 +1,719 @@
+/**
+ * Alignment capability plugin (M1 of `docs/design/需求对齐插件设计.md`): a
+ * three-step requirement-alignment funnel (objective → detail → design) with
+ * block-level bidirectional feedback confirmed on a local HTML page.
+ *
+ * Persistence protocol, structurally identical to the goal/plan/todo/workflow
+ * plugins: append-only `alignment.state` full snapshots (the single rebuild
+ * source) plus one `alignment.transition` audit entry per conversion,
+ * announced as `alignment.changed` (version 1, correlationId
+ * "alignment.state", data = the complete AlignmentState snapshot).
+ *
+ * The round wait is non-blocking (设计 §5 总则 8): alignment_round returns the
+ * page URL immediately; page feedback arrives as a `alignment.feedback`
+ * custom message injected through SessionAPI.sendMessage (triggerTurn), and a
+ * round only closes after the injection succeeded (`round.delivered`,
+ * terminal audit D1).
+ */
+import { Type } from "typebox";
+import { activeStep, applyAlignmentAdvance, applyAlignmentSet, applyRoundPost, applyVersionRollback, finalBaselineLines, gate, markDelivered, } from "./engine.js";
+import { exportTargetPath, writeAlignmentExport } from "./export.js";
+import { startAlignmentServer } from "./http-server.js";
+import { alignmentToolResultRenderer } from "./render.js";
+import { AlignmentError, } from "./types.js";
+const STATE_ENTRY = "alignment.state";
+const TRANSITION_ENTRY = "alignment.transition";
+const GOAL_STATE_ENTRY = "goal.state";
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * 双调用约定（走查 2026-10-04，goal 插件同款问题的严谨版）：会话路径以
+ * (toolCallId, params, signal, onUpdate) 调用插件工具——first 是调用 id 字符串；
+ * runtime facade 以 (input, context?, signal?) 调用——first 是入参对象。
+ * 按 first 的类型区分，两条路径（含 runtime 携带 context）都取到真实入参。
+ */
+function toolInput(first, second) {
+    if (typeof first === "string") {
+        if (!isObject(second))
+            return {};
+        return second;
+    }
+    if (!isObject(first))
+        throw new Error("alignment tool input must be an object");
+    return first;
+}
+function loadState(api) {
+    const entries = api.session?.getBranchEntries() ?? [];
+    const entry = [...entries].reverse().find((item) => item.customType === STATE_ENTRY);
+    if (!entry?.data || !isObject(entry.data))
+        return { alignments: [] };
+    const data = entry.data;
+    return { alignments: Array.isArray(data.alignments) ? [...data.alignments] : [] };
+}
+function loadTransitions(api) {
+    const entries = api.session?.getBranchEntries() ?? [];
+    return entries
+        .filter((item) => item.customType === TRANSITION_ENTRY)
+        .map((item) => item.data)
+        .filter((item) => isObject(item));
+}
+/** Advisory goalId check (#10 soft-reference discipline, goal/plan precedent). */
+function goalKnownToSession(api, goalId) {
+    const entries = api.session?.getBranchEntries() ?? [];
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry.customType !== GOAL_STATE_ENTRY)
+            continue;
+        const data = entry.data;
+        if (!isObject(data))
+            return false;
+        const goals = data.goals;
+        if (!Array.isArray(goals))
+            return false;
+        return goals.some((goal) => isObject(goal) && goal.id === goalId);
+    }
+    return false;
+}
+/** Page projection (state.json): everything the fixed template renders. */
+function pageView(record, baselineFile, awaitingRevision) {
+    const snapshot = gate(record);
+    // gate already validated the active step exists (it throws otherwise).
+    const blocks = activeStep(record).blocks;
+    // 终审/终态头部展示跨步总口径（走查 2026-10-03）：completed 后仍按当前步
+    // 计数会显示「已确认 0/1」这类误导数字。
+    const countedBlocks = record.status === "aligning" ? blocks : record.steps.flatMap((s) => s.blocks);
+    return {
+        alignmentId: record.id,
+        title: record.title,
+        goalId: record.goalId,
+        status: record.status,
+        revision: record.revision,
+        round: record.roundCount,
+        activeStep: record.activeStep,
+        steps: record.steps.map((step) => ({
+            step: step.step,
+            status: step.status,
+            blocks: step.blocks.map((block) => ({
+                id: block.id,
+                kind: block.kind,
+                content: block.content,
+                rationale: block.rationale,
+                impact: block.impact,
+                status: block.status,
+                modifiedInRound: block.modifiedInRound,
+                draftAnswer: block.draftAnswer,
+                comments: block.comments,
+            })),
+        })),
+        gate: {
+            ...snapshot,
+            approvedCount: countedBlocks.filter((block) => block.status === "approved").length,
+            blockCount: countedBlocks.length,
+        },
+        pendingFeedback: record.pendingFeedback,
+        // Version snapshots for the read-only history switcher (走查 2026-10-03).
+        versions: record.versions ?? [],
+        awaitingRevision,
+        baselineFile,
+    };
+}
+function blockStateLine(block) {
+    const state = block.status === "approved" ? "已确认" : "待确认";
+    const first = block.content.split("\n")[0]?.slice(0, 80) ?? "";
+    const notes = [];
+    for (const comment of block.comments) {
+        if (comment.status !== "open")
+            continue;
+        notes.push(comment.author === "assistant"
+            ? `AI疑问待回应:${comment.note.slice(0, 40)}`
+            : `用户批注:${comment.note.slice(0, 40)}`);
+    }
+    return `- ${block.id}[${block.kind}|${state}] ${first}${notes.length ? `（${notes.join("；")}）` : ""}`;
+}
+function historyLines(transitions) {
+    if (transitions.length === 0)
+        return "（无）";
+    return transitions
+        .slice(-20)
+        .map((entry) => {
+        const where = entry.step ? `${entry.step} ` : "";
+        return `rev${entry.revision} ${where}${entry.event}${entry.reason.detail ? `(${entry.reason.detail.slice(0, 60)})` : ""}`;
+    })
+        .join("\n");
+}
+function feedbackMessage(record, result, transitions) {
+    const snapshot = gate(record);
+    const lines = [];
+    lines.push(`[alignment.feedback] ${result.alignmentId} 第 ${result.round} 轮（${result.step} 步，revision ${result.revision}，status ${record.status}）`);
+    lines.push("== 本轮反馈 ==");
+    if (result.approvals.length > 0)
+        lines.push(`确认块：${result.approvals.join(", ")}`);
+    for (const comment of result.comments) {
+        lines.push(`用户批注[${comment.blockId}]${comment.escalate ? "（上游问题）" : ""}：「${comment.quote}」→ ${comment.note}`);
+    }
+    for (const reply of result.commentReplies) {
+        lines.push(reply.dismiss
+            ? `AI 疑问 ${reply.commentId}：用户标记不重要`
+            : `AI 疑问 ${reply.commentId} 的回答：${reply.answer}`);
+    }
+    for (const answer of result.answers) {
+        lines.push(`补充答案[${answer.blockId}]：${answer.value}`);
+    }
+    for (const addition of result.additions) {
+        lines.push(`自由补充：${addition}`);
+    }
+    if (result.stepConfirmed) {
+        if (record.status === "completed") {
+            lines.push("用户已在终审总览确认基线——对齐完成。请输出最终基线总结（plan 输入）。");
+            if (result.finalBaseline) {
+                lines.push("最终基线紧凑清单：");
+                for (const line of result.finalBaseline) {
+                    lines.push(`  [${line.kind}] ${line.id}: ${line.line}`);
+                }
+            }
+        }
+        else {
+            lines.push("用户已确认本步——基线锁定。请 alignment_set 出下一步块集并 alignment_round 刷新。");
+        }
+    }
+    lines.push("== 当前块集（全量状态）==");
+    if (record.status === "finalizing") {
+        lines.push("三步基线已全部锁定，等待用户终审总览确认；此阶段无需你操作。");
+    }
+    else {
+        for (const step of record.steps) {
+            if (step.blocks.length === 0)
+                continue;
+            lines.push(`[${step.step}|${step.status}]`);
+            for (const block of step.blocks)
+                lines.push(blockStateLine(block));
+        }
+        lines.push(`待办：${snapshot.unapproved} 块待确认、${snapshot.openComments} 批注未清、${snapshot.pendingAdditions} 补充未落账。`);
+    }
+    lines.push("== 历史轮次（revision 锚点）==");
+    lines.push(historyLines(transitions));
+    return lines.join("\n");
+}
+/**
+ * Single-record summary returned by all three tools (设计 §6, v3.7): tool
+ * results no longer carry the full state (8-17KB per round pushed a 27-minute
+ * real session from 34KB to 295KB of model context) — the authoritative
+ * current state reaches the model through the alignment.feedback injection,
+ * and the TUI renderer (render.ts) consumes exactly this shape.
+ */
+function recordSummary(record, extra = {}) {
+    const snapshot = gate(record);
+    const step = activeStep(record);
+    return {
+        alignmentId: record.id,
+        status: record.status,
+        title: record.title,
+        activeStep: record.activeStep,
+        round: record.roundCount,
+        revision: record.revision,
+        gate: {
+            unapproved: snapshot.unapproved,
+            openComments: snapshot.openComments,
+            pendingAdditions: snapshot.pendingAdditions,
+            allGreen: snapshot.allGreen,
+        },
+        ...(extra.url !== undefined ? { url: extra.url } : {}),
+        ...(extra.warning !== undefined ? { warning: extra.warning } : {}),
+        step: {
+            name: record.activeStep,
+            status: step.status,
+            blocks: step.blocks.map((block) => ({
+                id: block.id,
+                kind: block.kind,
+                status: block.status,
+                preview: block.content.split("\n")[0]?.slice(0, 72) ?? "",
+                commentCount: block.comments.length,
+                ...(block.draftAnswer !== undefined ? { draftAnswer: block.draftAnswer } : {}),
+            })),
+        },
+        ...(extra.baseline !== undefined ? { baseline: extra.baseline } : {}),
+    };
+}
+const PROMPT_GUIDELINES = [
+    "进入分流（预检规则）：用户显式要求对齐时直接进入；否则先做零成本预检——列出缺失信息、被迫假设、矛盾歧义。三项全空则一行结论直接出方案（跳过证据必须可见，禁止静默跳过）；有任一项则列出要点并建议对齐，用户说直接做则跳过、但未决假设须在方案中显式标注。预检清单在对齐时直接作为第一轮块种子。",
+    "三步铁律：objective 只谈方向与非目标（≤10 块）；detail 只谈业务规则/公式/数据流/异常（禁止技术选型）；design 谈技术方案且不得与已锁定基线矛盾，发现矛盾必须停下向用户提出。",
+    "视觉对齐（涉及用户可见界面的任务）：design 步必须产出 visual 视觉方向块——按六节契约（风格宣言/配色角色表/布局与层级策略/文案密度预算/视觉验收清单/明确不做项）逐节落块，建议委派 design-proposer 出厂角色产出（subagent_run role=design-proposer，其指令内嵌保底资产）；纯后端/重构任务不产 visual 块；实现完成后渲染产物交 visual-reviewer 角色做视觉验收（防丑下限）。",
+    "块纪律：假设单独成 assumption 块；缺信息产 missing 块而不是脑补；可自查的先取证落 fact；assistant 批注只用于真实不确定点（公式口径、二义表述、潜在矛盾、与基线冲突）。",
+    "修订纪律：最小改动已确认的块（内容不变即继承确认）；修改已确认块的内容会被引擎拒绝（approved-blocks-conflict）——确需修改时重新提交并携带 reviseApproved: true，这些块会重置为待确认、须请用户重新确认；每次 alignment_set 之后必须跟 alignment_round 告知用户去看新版；用户批注的 quote 匹配失败时向用户说明而不是猜。",
+    "填空落账：收到补充答案（补充答案[blockId]）后，下一次 alignment_set 必须把答案重写进对应块内容并转为 fact/decision（missing 块不得带着未并入的答案被确认锁定）；注入消息的「当前块集（全量状态）」是权威现状，以它为准做最小修订。",
+    "终审阶段（status finalizing）：三步基线已全部锁定，页面进入只读总览，唯一动作是用户最终确认——此阶段不要调用 alignment_set；收到终审确认消息（alignment completed）即视为开发授权：先输出一行极简基线摘要，然后直接按基线实现——用 plan/todo 把基线拆成可执行任务，实现并自测，完成后向用户报告结果与验收方式。不要停在基线总结等用户再次指令（dogfood 2026-10-04：等指令会打断对齐→开发衔接）。",
+    "页面回退：用户可在页面上把任务回退到更早环节（step.retreated，后续环节作废重走）或把当前步回退到历史版本（version.rolled-back，当前未确认版本丢弃、批注保留）。收到这类消息后，以注入消息里的全量块集为准重新修订，不要复用回退前的块集。",
+];
+const setSchema = Type.Object({
+    id: Type.String({ description: "Stable alignment id; charset [A-Za-z0-9._-], no leading dot" }),
+    title: Type.Optional(Type.String({ description: "Human-readable alignment title" })),
+    goalId: Type.Optional(Type.String({ description: "Soft goal reference; unknown ids only warn" })),
+    revision: Type.Optional(Type.Integer({ description: "Monotonic revision; must exceed the stored one", minimum: 0 })),
+    reviseApproved: Type.Optional(Type.Boolean({
+        description: "Explicitly confirm this write modifies blocks the user already approved (they reset to pending and need re-approval)",
+    })),
+    blocks: Type.Array(Type.Object({
+        id: Type.String({ description: "Stable block id within the step" }),
+        kind: Type.Union([
+            Type.Literal("fact"),
+            Type.Literal("assumption"),
+            Type.Literal("decision"),
+            Type.Literal("missing"),
+            Type.Literal("visual"),
+        ], { description: "fact=取证 assumption=假设 decision=决策 missing=待补充" }),
+        content: Type.String({ description: "Block content (markdown text, ≤8192 chars)" }),
+        rationale: Type.Optional(Type.String({ description: "Why this decision/assumption (≤2048 chars)" })),
+        impact: Type.Optional(Type.Array(Type.String(), { description: "Affected modules/files/interfaces" })),
+        comments: Type.Optional(Type.Array(Type.Object({
+            id: Type.String(),
+            note: Type.String({ description: "Assistant question; only real uncertainty" }),
+            quote: Type.Optional(Type.String()),
+        }), { description: "New assistant comments (AI 主动标注的不确定点)" })),
+        commentResolutions: Type.Optional(Type.Array(Type.Object({
+            commentId: Type.String(),
+            kind: Type.Union([Type.Literal("answered"), Type.Literal("dismissed"), Type.Literal("incorporated")]),
+            text: Type.Optional(Type.String()),
+        }), {
+            description: "Resolutions for existing comments (user comments may only be resolved, never rewritten)",
+        })),
+    }), { description: "Full block set of the active step (全量提交；未变块按内容指纹继承确认)" }),
+});
+const roundSchema = Type.Object({
+    alignmentId: Type.String({ description: "Alignment id to open the confirmation page for" }),
+});
+const advanceSchema = Type.Object({
+    alignmentId: Type.String(),
+    action: Type.Union([
+        Type.Literal("inspect"),
+        Type.Literal("retreat"),
+        Type.Literal("cancel"),
+        Type.Literal("rollback"),
+    ]),
+    step: Type.Optional(Type.Union([Type.Literal("objective"), Type.Literal("detail"), Type.Literal("design")], {
+        description: "Retreat target; must be an earlier step",
+    })),
+    note: Type.Optional(Type.String({ description: "Retreat reason (required for retreat)" })),
+    versionId: Type.Optional(Type.Integer({
+        description: "Rollback target: the active step's snapshot revision; the latest snapshot is used when omitted",
+    })),
+});
+function pendingText(items) {
+    if (items.length === 0)
+        return "nothing pending";
+    const reasons = items.map((item) => `${item.blockId}(${item.reason})`);
+    return reasons.join(" ");
+}
+function listLines(state) {
+    if (state.alignments.length === 0)
+        return "no alignments in this session; create one with alignment_set";
+    const lines = [`alignments: ${state.alignments.length}`];
+    for (const record of state.alignments) {
+        const snapshot = gate(record);
+        lines.push(`- ${record.id} [${record.status} → ${record.goalId ?? "-"}] ${record.title} · ${record.activeStep} r${record.roundCount} · ${snapshot.unapproved} pending / ${snapshot.openComments} open`);
+    }
+    return lines.join("\n");
+}
+function whyLines(record) {
+    const snapshot = gate(record);
+    const lines = [`${record.id} · ${record.activeStep} · round ${record.roundCount}`];
+    if (record.status !== "aligning") {
+        lines.push(`status ${record.status} — nothing to wait for`);
+        return lines.join("\n");
+    }
+    if (snapshot.allGreen) {
+        lines.push("ALL GREEN — waiting for the user to click 确认完成 on the page");
+        return lines.join("\n");
+    }
+    lines.push(`pending: ${pendingText(snapshot.pending)}`);
+    if (snapshot.pendingAdditions > 0) {
+        lines.push(`undelivered additions: ${record.pendingFeedback?.additions.join(" | ")}`);
+    }
+    return lines.join("\n");
+}
+function logLines(transitions, count) {
+    if (transitions.length === 0)
+        return "no alignment transitions recorded";
+    const slice = transitions.slice(-count).reverse();
+    return slice
+        .map((entry, index) => {
+        const where = entry.step ? `${entry.step} ` : "";
+        return `${slice.length - index}. [r${entry.round ?? "-"} rev${entry.revision}] ${where}${entry.event} ${entry.reason.code}${entry.reason.detail ? ` — ${entry.reason.detail}` : ""}`;
+    })
+        .join("\n");
+}
+export function createCapability(api, options = {}) {
+    let state = loadState(api);
+    let server;
+    let cachedRound;
+    const deliveredRoundByAlignment = new Map();
+    /** Revision at last successful injection — awaitingRevision = delivered and not yet superseded by a set. */
+    const deliveredRevisionByAlignment = new Map();
+    const persist = (next, transitions) => {
+        state = next;
+        api.session?.appendEntry(STATE_ENTRY, state);
+        for (const entry of transitions)
+            api.session?.appendEntry(TRANSITION_ENTRY, entry);
+        void api.publish({ type: "alignment.changed", version: 1, correlationId: STATE_ENTRY, data: state });
+        return state;
+    };
+    const activeRecord = () => state.alignments.find((record) => record.status === "aligning") ??
+        [...state.alignments].reverse().find((record) => record.status !== "aligning");
+    const ensureServer = async () => {
+        // 页面生命周期（走查 2026-10-04 用户裁决）：服务随第一个 alignment_round
+        // 启动后常驻到插件 dispose（会话关闭）；终态对齐的页面保持可查看，直到
+        // 下一次对齐在同一 URL 上覆盖内容。不再做终态 idle 停服。
+        if (server)
+            return server;
+        server = await startAlignmentServer({
+            getState: () => {
+                const record = activeRecord();
+                if (!record)
+                    return undefined;
+                // awaitingRevision: feedback was delivered and the model has not
+                // bumped the revision yet — the page shows "AI revising…".
+                const awaiting = record.status === "aligning" && deliveredRevisionByAlignment.get(record.id) === record.revision;
+                return pageView(record, undefined, awaiting);
+            },
+            onRoundPost: (post) => handleRoundPost(post),
+        }, { port: options.serverPort });
+        return server;
+    };
+    const injectFeedback = async (cached) => {
+        const message = feedbackMessage(cached.record, cached.result, loadTransitions(api));
+        const send = api.session?.sendMessage;
+        if (!send) {
+            throw new AlignmentError("invalid-input", "host session does not expose sendMessage; feedback cannot be injected");
+        }
+        await send({ customType: "alignment.feedback", content: message, display: true }, { triggerTurn: true });
+    };
+    const handleRoundPost = async (post) => {
+        const record = activeRecord();
+        if (!record || (record.status !== "aligning" && record.status !== "finalizing")) {
+            return { status: 409, body: { error: "no alignment in progress" } };
+        }
+        const samePost = (candidate) => candidate.result.alignmentId === record.id && JSON.stringify(candidate.post) === JSON.stringify(post);
+        // Delivered idempotency: an identical replay of an already-delivered
+        // round returns the snapshot without re-injecting.
+        const pending = cachedRound;
+        if (pending && samePost(pending) && deliveredRoundByAlignment.get(record.id) === pending.result.round) {
+            return {
+                status: 200,
+                body: {
+                    ok: true,
+                    delivered: true,
+                    stepConfirmed: pending.result.stepConfirmed,
+                    revision: pending.record.revision,
+                },
+            };
+        }
+        // Submitted-but-undelivered replay retries only the injection.
+        if (pending && samePost(pending)) {
+            try {
+                await injectFeedback(pending);
+                // 同主路径：注入可能同步驱动模型回合，不回写回合前快照（走查 2026-10-04）。
+                for (const entry of markDelivered(pending.record, pending.result.round)) {
+                    api.session?.appendEntry(TRANSITION_ENTRY, entry);
+                }
+                void api.publish({
+                    type: "alignment.changed",
+                    version: 1,
+                    correlationId: STATE_ENTRY,
+                    data: loadState(api),
+                });
+                state = loadState(api);
+                deliveredRoundByAlignment.set(record.id, pending.result.round);
+                // 重放路径同主路径：纯确认轮不进入"AI 修订中"（走查 2026-10-04）。
+                const replayHasContent = pending.result.comments.length > 0 ||
+                    pending.result.commentReplies.length > 0 ||
+                    pending.result.answers.length > 0 ||
+                    pending.result.additions.length > 0;
+                if (replayHasContent)
+                    deliveredRevisionByAlignment.set(record.id, pending.record.revision);
+                return {
+                    status: 200,
+                    body: {
+                        ok: true,
+                        delivered: true,
+                        stepConfirmed: pending.result.stepConfirmed,
+                        revision: pending.record.revision,
+                    },
+                };
+            }
+            catch (error) {
+                return {
+                    status: 503,
+                    body: {
+                        error: `feedback delivery failed: ${error instanceof Error ? error.message : String(error)}`,
+                        retry: true,
+                    },
+                };
+            }
+        }
+        // Page-initiated rollbacks (走查 2026-10-03) share the POST /round
+        // entry so the submission→injection→delivered protocol is identical.
+        let outcome;
+        let runOutcome;
+        try {
+            if (post.action === "retreat" || post.action === "rollback") {
+                if (post.baseRevision !== record.revision) {
+                    return {
+                        status: 409,
+                        body: { code: "stale-state", error: "page snapshot is stale; reload and retry" },
+                    };
+                }
+            }
+            if (post.action === "retreat") {
+                runOutcome = applyAlignmentAdvance(state, {
+                    alignmentId: record.id,
+                    action: "retreat",
+                    step: post.targetStep,
+                    note: "回退自确认页：用户在页面上点击了更早的环节",
+                });
+            }
+            else if (post.action === "rollback") {
+                runOutcome = applyVersionRollback(state, {
+                    alignmentId: record.id,
+                    targetRevision: post.targetRevision ?? -1,
+                });
+            }
+            else {
+                outcome = applyRoundPost(record, post);
+            }
+        }
+        catch (error) {
+            if (error instanceof AlignmentError) {
+                return {
+                    status: error.code === "stale-state" ? 409 : 400,
+                    body: { code: error.code, error: error.message },
+                };
+            }
+            return { status: 500, body: { error: error instanceof Error ? error.message : String(error) } };
+        }
+        // Persist the submission first (append-only fact), then attempt delivery.
+        const record2 = outcome
+            ? outcome.record
+            : runOutcome.state.alignments.find((candidate) => candidate.id === record.id);
+        const transitions2 = outcome ? outcome.transitions : runOutcome.transitions;
+        persist({
+            alignments: state.alignments.map((candidate) => (candidate.id === record2.id ? record2 : candidate)),
+        }, transitions2);
+        const syntheticResult = outcome?.result ?? {
+            alignmentId: record2.id,
+            round: record2.roundCount,
+            step: record2.activeStep,
+            revision: record2.revision,
+            approvals: [],
+            comments: [],
+            commentReplies: [],
+            answers: [],
+            additions: [],
+            stepConfirmed: false,
+        };
+        let cached = { post, record: record2, transitions: [], result: syntheticResult };
+        if (outcome?.result.stepConfirmed && outcome.record.status === "completed") {
+            // 终审确认（走查 2026-10-03）：no workspace file is written; the
+            // compact listing rides the feedback message and `/alignment
+            // export` produces a file only on explicit request.
+            const lines = finalBaselineLines(outcome.record);
+            outcome.result.finalBaseline = lines;
+            cached = { ...cached, result: outcome.result };
+        }
+        cachedRound = cached;
+        try {
+            await injectFeedback(cached);
+            // injectFeedback 的 sendMessage(triggerTurn) 会同步驱动整个模型回合
+            //（agent-session sendCustomMessage → _runAgentPrompt）：回合内的
+            // alignment_set 已把修订落账 entries。此处若回写回合前快照，会把模型
+            // 刚提交的修订整体抹掉（走查 2026-10-04 dogfood：细节步 10 块被还原成
+            // 空步）。只追加 round.delivered 审计条目，并从 entries 重建内存态。
+            for (const entry of markDelivered(cached.record, cached.result.round)) {
+                api.session?.appendEntry(TRANSITION_ENTRY, entry);
+            }
+            void api.publish({ type: "alignment.changed", version: 1, correlationId: STATE_ENTRY, data: loadState(api) });
+            state = loadState(api);
+            deliveredRoundByAlignment.set(cached.record.id, cached.result.round);
+            // 只有携带内容反馈（批注/回复/答案/补充）的轮次才进入"AI 修订中"：
+            // 纯确认轮模型正确地不重发块，revision 不变——若也标记 awaiting，
+            // 页面会永远钉在机器人等待屏，用户反而无法确认剩余块（走查 2026-10-04）。
+            const hasContentFeedback = post.comments.length > 0 ||
+                post.commentReplies.length > 0 ||
+                post.answers.length > 0 ||
+                post.additions.length > 0;
+            if (hasContentFeedback)
+                deliveredRevisionByAlignment.set(cached.record.id, cached.record.revision);
+            return {
+                status: 200,
+                body: {
+                    ok: true,
+                    delivered: true,
+                    stepConfirmed: cached.result.stepConfirmed,
+                    revision: cached.record.revision,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                status: 503,
+                body: {
+                    error: `feedback delivery failed: ${error instanceof Error ? error.message : String(error)}`,
+                    retry: true,
+                },
+            };
+        }
+    };
+    const runSet = (input) => {
+        const run = applyAlignmentSet(state, input);
+        const record = run.state.alignments.find((candidate) => candidate.id === input.id);
+        persist(run.state, run.transitions);
+        const warning = record.goalId && !goalKnownToSession(api, record.goalId)
+            ? `goalId "${record.goalId}" does not match any goal in this session's goal state; the alignment keeps the soft reference`
+            : undefined;
+        return recordSummary(record, { warning });
+    };
+    const setTool = api.registerTool({
+        name: "alignment_set",
+        label: "Set alignment",
+        description: "Create or update a requirement alignment task: full block set of the active step (goal→detail→design funnel). Unchanged blocks inherit user approval by content fingerprint; rewriting an approved block requires reviseApproved: true",
+        parameters: setSchema,
+        promptGuidelines: PROMPT_GUIDELINES,
+        renderResult: alignmentToolResultRenderer,
+        // 双调用约定（goal 插件同款，走查 2026-10-04）：会话路径传
+        // (toolCallId, params, signal, onUpdate)，runtime facade 路径传
+        // (input, context?, signal?)——second 缺省时取 first。
+        execute: async (first, second) => {
+            const input = toolInput(first, second);
+            return runSet(input);
+        },
+    });
+    const roundTool = api.registerTool({
+        name: "alignment_round",
+        label: "Open alignment page",
+        description: "Open (or refresh) the local confirmation page for the active alignment and return its URL plus progress facts. Non-blocking: feedback arrives later as an alignment.feedback message",
+        parameters: roundSchema,
+        promptGuidelines: PROMPT_GUIDELINES,
+        renderResult: alignmentToolResultRenderer,
+        execute: async (first, second) => {
+            const input = toolInput(first, second);
+            const id = typeof input.alignmentId === "string" ? input.alignmentId : "";
+            const record = state.alignments.find((candidate) => candidate.id === id);
+            if (!record)
+                throw new Error(`unknown alignment: ${id}`);
+            if (record.status !== "aligning")
+                throw new Error(`alignment is ${record.status}: ${id}`);
+            if (!api.session?.sendMessage) {
+                throw new Error("host session does not expose sendMessage; the alignment confirmation page cannot deliver feedback on this host");
+            }
+            const running = await ensureServer();
+            return recordSummary(record, { url: running.url });
+        },
+    });
+    const advanceTool = api.registerTool({
+        name: "alignment_advance",
+        label: "Advance alignment",
+        description: "inspect (read-only status/gate/baseline), retreat (roll back to an earlier step, resets downstream confirmations), rollback (restore the active step's archived version — the latest snapshot, or a specific versionId), or cancel the alignment",
+        parameters: advanceSchema,
+        promptGuidelines: PROMPT_GUIDELINES,
+        renderResult: alignmentToolResultRenderer,
+        execute: async (first, second) => {
+            const input = toolInput(first, second);
+            if (input.action === "inspect") {
+                const record = state.alignments.find((candidate) => candidate.id === input.alignmentId);
+                if (!record)
+                    throw new Error(`unknown alignment: ${input.alignmentId}`);
+                return recordSummary(record, { baseline: finalBaselineLines(record) });
+            }
+            if (input.action === "rollback") {
+                const record = state.alignments.find((candidate) => candidate.id === input.alignmentId);
+                if (!record)
+                    throw new Error(`unknown alignment: ${input.alignmentId}`);
+                // 缺省 versionId = active 步最近一次快照；无快照 / 指向不存在的
+                // 快照由 applyVersionRollback 抛既有结构化错误（设计 §6）。
+                const stepVersions = (record.versions ?? []).filter((snapshot) => snapshot.step === record.activeStep);
+                const targetRevision = input.versionId ?? stepVersions.at(-1)?.revision;
+                if (targetRevision === undefined) {
+                    throw new AlignmentError("invalid-input", `no snapshot of step ${record.activeStep} to roll back to`);
+                }
+                const run = applyVersionRollback(state, { alignmentId: input.alignmentId, targetRevision });
+                persist(run.state, run.transitions);
+                return recordSummary(run.state.alignments.find((candidate) => candidate.id === input.alignmentId));
+            }
+            const run = applyAlignmentAdvance(state, input);
+            persist(run.state, run.transitions);
+            return recordSummary(run.state.alignments.find((candidate) => candidate.id === input.alignmentId));
+        },
+    });
+    const command = api.registerCommand({
+        name: "alignment",
+        description: "Show this session's alignments (progress, blockers, audit log); `export [id] [path]` writes a self-contained read-only HTML snapshot",
+        execute: async (args, context) => {
+            try {
+                const parts = args
+                    .trim()
+                    .split(/\s+/)
+                    .filter((part) => part !== "");
+                if (parts.length === 0)
+                    return { status: "success", message: listLines(state) };
+                if (parts[0] === "why") {
+                    const record = state.alignments.find((candidate) => candidate.status === "aligning") ?? state.alignments.at(-1);
+                    if (!record)
+                        return { status: "error", message: "no alignments in this session" };
+                    const extra = cachedRound && deliveredRoundByAlignment.get(record.id) !== cachedRound.result.round
+                        ? `\nundelivered round: r${cachedRound.result.round} (injection failed; the page can retry)`
+                        : "";
+                    return { status: "success", message: whyLines(record) + extra };
+                }
+                if (parts[0] === "log") {
+                    const count = Number.parseInt(parts[1] ?? "20", 10);
+                    return {
+                        status: "success",
+                        message: logLines(loadTransitions(api), Number.isFinite(count) && count > 0 ? count : 20),
+                    };
+                }
+                if (parts[0] === "export") {
+                    const id = parts[1];
+                    const record = id
+                        ? state.alignments.find((candidate) => candidate.id === id)
+                        : (state.alignments.find((candidate) => candidate.status === "aligning") ??
+                            state.alignments.find((candidate) => candidate.status === "finalizing") ??
+                            state.alignments.at(-1));
+                    if (!record)
+                        return { status: "error", message: `unknown alignment: ${id ?? "(none in session)"}` };
+                    // Explicit user request — the only path that writes a file.
+                    const target = exportTargetPath(context?.cwd ?? process.cwd(), record, parts[2]);
+                    const written = writeAlignmentExport(record, loadTransitions(api), target);
+                    return {
+                        status: "success",
+                        message: `exported: ${written}`,
+                        links: [{ label: written, url: `file:///${written.split("\\").join("/")}` }],
+                    };
+                }
+                return {
+                    status: "error",
+                    message: "Usage: /alignment | /alignment why | /alignment log [N] | /alignment export [id] [path]",
+                };
+            }
+            catch (error) {
+                return { status: "error", message: error instanceof Error ? error.message : String(error) };
+            }
+        },
+    });
+    const stopServer = () => {
+        const stopping = server;
+        server = undefined;
+        if (stopping)
+            void stopping.stop().catch(() => undefined);
+    };
+    // The command registration doubles as the teardown hook for the local
+    // confirmation server (plugin dispose must release the port).
+    const commandWithTeardown = {
+        id: command.id,
+        kind: command.kind,
+        dispose: () => {
+            void command.dispose();
+            stopServer();
+        },
+    };
+    return [setTool, roundTool, advanceTool, commandWithTeardown];
+}
+//# sourceMappingURL=index.js.map