@tea-agent/loop-agent 0.39.0-beta.0 → 0.39.0-beta.10

package/dist/task/source-prepare/ledger-review.js

@@ -0,0 +1,214 @@
+import { mergeInventoryItems } from "./ledger-reconciliation.js";
+// ---------------------------------------------------------------------------
+// 独立 reviewer（AC-007 / AC-FIDELITY-REPAIR-007）
+// context-only / duplicate / conflicts 由独立可注入 reviewer 审核，与 reconciler
+// 是不同调用阶段（fixture 断言调用顺序，杜绝共享一次输出冒充独立审核）。
+// 最多一次有界修订；review/revision 失败或第二次不通过 fail closed。低风险
+// context-only 仅 reviewer pass 放行，高风险 context-only 始终阻断；duplicate
+// 保留全部来源但审核失败（含修订后仍拒绝）以稳定码 fail closed。
+// ---------------------------------------------------------------------------
+/** review 片段原文按 budget 有界截断（AC-004 / AC-HARD-004），禁止整文档入
+ * prompt；沿用 MAX_SOURCE_EXCERPT_CHARS 边界语义。 */
+export const LEDGER_REVIEW_DEFAULT_BUDGET_CHARS = 2000;
+export const LEDGER_REVIEW_MAX_REVISIONS = 1;
+/** review 失败（reviewer 异常/第二次不通过）统一稳定错误码。 */
+export class LedgerReviewError extends Error {
+    code = "SOURCE_FIDELITY_RECONCILIATION_FAILED";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "LedgerReviewError";
+    }
+}
+/**
+ * 独立 reviewer 编排：仅 context-only（低风险）、duplicate 与 conflict 进入审核。
+ * - context-only high risk：始终阻断（不调 reviewer，fail closed）。
+ * - context-only low：仅 reviewer pass 放行；否则（一次修订后仍失败）阻断。
+ * - duplicate：进入审核并记录；duplicate 保留全部来源，失败不升级为阻断。
+ * - conflict：需 reviewer pass 或存在有效 human resolution，否则阻断。
+ * reviewer 异常即 fail closed，不回退。
+ */
+export async function reviewLedgerFragments(input) {
+    const { canonicalRequirements, reviewer, maxRevisions = LEDGER_REVIEW_MAX_REVISIONS, conflictIds = new Set(), resolvedConflictIds = new Set(), } = input;
+    const calls = input.calls ?? [];
+    const reasons = [];
+    const reviewed = [];
+    for (const fragment of input.fragments) {
+        let kind = null;
+        if (fragment.disposition === "context-only")
+            kind = "context-only";
+        else if (fragment.disposition === "duplicate")
+            kind = "duplicate";
+        else if (conflictIds.has(fragment.id))
+            kind = "conflict";
+        if (!kind)
+            continue;
+        // 高风险 context-only：始终阻断，不进入 reviewer。
+        if (kind === "context-only" && fragment.risk === "high") {
+            reviewed.push({
+                fragmentId: fragment.id,
+                kind,
+                approved: false,
+                revisionUsed: false,
+            });
+            reasons.push(`high-risk context-only fragment ${fragment.id} always blocks; reviewer cannot waive it`);
+            return {
+                approved: false,
+                code: "SOURCE_FIDELITY_HIGH_RISK_UNCOVERED",
+                reasons,
+                reviewed,
+                calls,
+            };
+        }
+        const resolutionAvailable = kind === "conflict" && resolvedConflictIds.has(fragment.id);
+        // AC-002：已被绑定当前 inputDigest 的有效 human resolution 覆盖的 conflict
+        // （resolutionAvailable=true）直接 approved（revisionUsed=false），注入的
+        // reviewer（含模型 reviewer）零调用：calls 不出现该 fragment 条目，reviewed
+        // audit 保留该条目。其余 fragment（unresolved / context-only / duplicate /
+        // 未解决的 conflict）的 reviewer 调用、修订与审核行为完全不变。
+        if (resolutionAvailable) {
+            reviewed.push({
+                fragmentId: fragment.id,
+                kind,
+                approved: true,
+                revisionUsed: false,
+            });
+            continue;
+        }
+        let current = fragment;
+        let approved = false;
+        let revisionUsed = false;
+        let revisionsRemaining = maxRevisions;
+        for (;;) {
+            const request = {
+                kind,
+                fragment: current,
+                canonicalRequirements,
+                resolutionAvailable,
+            };
+            let response;
+            try {
+                response = await reviewer(request);
+            }
+            catch (error) {
+                throw new LedgerReviewError(`independent reviewer failed for ${kind} fragment ${fragment.id}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            calls.push(fragment.id);
+            if (response?.approved === true) {
+                approved = true;
+                break;
+            }
+            // 最多一次有界修订：仅当 reviewer 给出 revision 建议且还有配额时采纳。
+            if (revisionsRemaining > 0 && response?.revision) {
+                current = {
+                    ...current,
+                    ...(response.revision.disposition
+                        ? { disposition: response.revision.disposition }
+                        : {}),
+                    ...(response.revision.reason
+                        ? { reason: response.revision.reason }
+                        : {}),
+                };
+                revisionsRemaining -= 1;
+                revisionUsed = true;
+                continue;
+            }
+            approved = false;
+            break;
+        }
+        reviewed.push({
+            fragmentId: fragment.id,
+            kind,
+            approved,
+            revisionUsed,
+        });
+        if (approved)
+            continue;
+        if (kind === "duplicate") {
+            // duplicate 保留全部来源，但审核失败（含 LEDGER_REVIEW_MAX_REVISIONS=1
+            // 单次有界修订后仍拒绝）即 fail closed（稳定码阻断，绝不静默放行未确认
+            // 的重复排除；ledger 保留全部 duplicate 来源记录不丢失）。
+            reasons.push(`duplicate fragment ${fragment.id} not approved by independent reviewer${revisionUsed ? " after one bounded revision" : ""}`);
+            return {
+                approved: false,
+                code: "SOURCE_FIDELITY_RECONCILIATION_FAILED",
+                reasons,
+                reviewed,
+                calls,
+            };
+        }
+        reasons.push(`${kind} fragment ${fragment.id} not approved by independent reviewer${revisionUsed ? " after one bounded revision" : ""}`);
+        return {
+            approved: false,
+            code: kind === "context-only"
+                ? "SOURCE_FIDELITY_CONTEXT_ONLY_UNREVIEWED"
+                : "SOURCE_FIDELITY_CONFLICT",
+            reasons,
+            reviewed,
+            calls,
+        };
+    }
+    return { approved: true, code: null, reasons, reviewed, calls };
+}
+/**
+ * 仓库内确定性默认 reviewer（无模型依赖）：context-only 需完整排除理由且低风险；
+ * duplicate 需完整理由；conflict 需有效 human resolution。prepare 在未注入外部
+ * reviewer 时使用该实现，保证 frontend task 的 ledger 评审语义 fail closed。
+ */
+export const defaultLedgerReviewer = async (request) => {
+    if (request.kind === "context-only") {
+        const complete = Boolean(request.fragment.reason?.trim());
+        return {
+            approved: complete && request.fragment.risk === "low",
+            reason: complete
+                ? "context-only 排除理由完整且低风险"
+                : "context-only fragment 缺少完整排除理由",
+        };
+    }
+    if (request.kind === "duplicate") {
+        const complete = Boolean(request.fragment.reason?.trim());
+        return {
+            approved: complete,
+            reason: complete
+                ? "duplicate 排除理由完整（保留全部来源）"
+                : "duplicate fragment 缺少完整排除理由",
+        };
+    }
+    return {
+        approved: request.resolutionAvailable,
+        reason: request.resolutionAvailable
+            ? "conflict 已被绑定当前 inputDigest 的有效 human resolution 覆盖"
+            : "conflict 无有效 human resolution 覆盖，保持阻断",
+    };
+};
+/** 供 prepare.ts 接入：从 ledger fragments 中挑选需审核的条目，复用
+ * mergeInventoryItems 的 id→原文映射，按 budgetChars 有界截断后传入 reviewer
+ * （AC-004 / AC-HARD-004）：请求携带非空有界原文与精确 fragment id，完整文档
+ * 绝不进入下游 prompt；原文不可得时退化为 reason / id 保证非空。 */
+export function ledgerReviewItemsFromRecords(records, input) {
+    const budgetChars = input?.budgetChars ?? LEDGER_REVIEW_DEFAULT_BUDGET_CHARS;
+    const merged = input?.fragments
+        ? mergeInventoryItems({ records, fragments: input.fragments })
+        : records.map((record) => ({
+            id: record.id,
+            path: "",
+            headingPath: record.headingPath,
+            lineRange: record.lineRange,
+            text: "",
+            disposition: record.disposition,
+            ...(record.reason ? { reason: record.reason } : {}),
+            risk: record.risk,
+            canonicalRequirementIds: record.canonicalRequirementIds,
+        }));
+    return merged.map((item) => {
+        const bounded = item.text.slice(0, budgetChars);
+        const text = bounded.trim() || item.reason?.trim() || item.id;
+        return {
+            id: item.id,
+            text,
+            disposition: item.disposition,
+            ...(item.reason ? { reason: item.reason } : {}),
+            risk: item.risk,
+            canonicalRequirementIds: item.canonicalRequirementIds,
+        };
+    });
+}