pi-firecode 1.0.0 → 1.0.2

package/review/checkpoint.ts

@@ -1,378 +0,0 @@
-/**
- * /fire-review 的持久化：custom entry（不进 LLM 上下文）存 reducer 状态快照。
- *
- * 零外部依赖：schema 用纯函数一次性整体校验（结构不符直接丢弃，不做字段级兼容），
- * 不引入 typebox——firecode 单目录自封闭，运行时无 node_modules，不能在扩展里声明生产依赖。
- *
- * 写入分两档：
- * - beginCheckpoint：新审查首次写入，无条件替换旧终态；
- * - writeCheckpoint：后续写入带 Run ID CAS——期望值由调用方（controller）记住的
- *   上一次写入值提供，出现不是自己写的 Run ID 才算冲突（CheckpointConflictError）。
- */
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type {
-	ActiveCheck,
-	ActiveReviewer,
-	AdvisorResult,
-	PendingRound,
-	RepairState,
-	ReviewRound,
-	ReviewState,
-	ReviewerResult,
-	SummaryState,
-} from "./state.js";
-
-export const CHECKPOINT_TYPE = "firecode-review-checkpoint";
-const VERSION = 5;
-
-/** 写入凭证：同一场审查内 Run ID 不变，靠单调递增的 seq 识别陈旧写者。 */
-export interface CheckpointStamp {
-	runId: string;
-	seq: number;
-}
-
-export class CheckpointConflictError extends Error {
-	constructor() {
-		super("fire-review checkpoint Run ID 已失效");
-		this.name = "CheckpointConflictError";
-	}
-}
-
-/** 只读会话访问（checkpoint 读/写前的 CAS 读取）。 */
-export interface CheckpointReadContext {
-	sessionManager: { getBranch(): unknown[] };
-}
-
-const PHASES = new Set([
-	"idle",
-	"queued",
-	"reviewing",
-	"needs_fix",
-	"awaiting_fix",
-	"summarizing",
-	"settled",
-]);
-const ROUND_RESULTS = new Set([
-	"passed",
-	"failed",
-	"error",
-	"stopped",
-	"cancelled",
-	"timed_out",
-]);
-const REVIEWER_STATUSES = new Set(["running", "passed", "failed", "error"]);
-const ADVISOR_VERDICTS = new Set(["continue", "stop", "narrow"]);
-const STOP_REASONS = new Set([
-	"advisor",
-	"max_rounds",
-	"user",
-	"shutdown",
-	"timeout",
-]);
-const REPAIR_STATUSES = new Set(["pending", "awaiting_start", "running", "completed"]);
-const SUMMARY_KINDS = new Set(["passed", "max_rounds", "advisor_stop"]);
-const SUMMARY_STATUSES = new Set(["pending", "awaiting_start", "running"]);
-
-/**
- * 键白名单由领域类型派生：satisfies 要求逐字段列全，
- * state.ts 增删字段而此处未同步时编译失败——手写校验漂移的唯一防线。
- */
-function keysOf<T extends Record<string, true>>(map: T): string[] {
-	return Object.keys(map);
-}
-
-const REVIEWER_RESULT_KEYS = keysOf({
-	index: true,
-	model: true,
-	thinking: true,
-	status: true,
-	summary: true,
-	details: true,
-} satisfies Record<keyof ReviewerResult, true>);
-
-const ACTIVE_REVIEWER_KEYS = keysOf({
-	index: true,
-	model: true,
-	thinking: true,
-	status: true,
-	result: true,
-} satisfies Record<keyof ActiveReviewer, true>);
-
-const ACTIVE_CHECK_KEYS = keysOf({
-	round: true,
-	reviewers: true,
-	settledCount: true,
-} satisfies Record<keyof ActiveCheck, true>);
-
-const ADVISOR_KEYS = keysOf({
-	verdict: true,
-	advice: true,
-} satisfies Record<keyof AdvisorResult, true>);
-
-const ROUND_KEYS = keysOf({
-	round: true,
-	result: true,
-	details: true,
-	reviewers: true,
-	advisor: true,
-	reason: true,
-	elapsedMs: true,
-} satisfies Record<keyof ReviewRound, true>);
-
-const PENDING_ROUND_KEYS = keysOf({
-	round: true,
-	reviewers: true,
-	details: true,
-} satisfies Record<keyof PendingRound, true>);
-
-const REPAIR_KEYS = keysOf({
-	details: true,
-	advisor: true,
-	status: true,
-} satisfies Record<keyof RepairState, true>);
-
-const SUMMARY_KEYS = keysOf({
-	kind: true,
-	status: true,
-} satisfies Record<keyof SummaryState, true>);
-
-const CHECKPOINT_KEYS = keysOf({
-	version: true,
-	seq: true,
-	runId: true,
-	phase: true,
-	round: true,
-	focus: true,
-	history: true,
-	active: true,
-	pending: true,
-	repair: true,
-	summary: true,
-	consecutiveFailures: true,
-	startedAt: true,
-	roundStartedAt: true,
-	updatedAt: true,
-} satisfies Record<keyof ReviewState | "version" | "seq", true>);
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function isString(value: unknown): value is string {
-	return typeof value === "string";
-}
-
-function isNonNegativeInt(value: unknown): value is number {
-	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
-}
-
-function oneOf(value: unknown, allowed: ReadonlySet<string>): value is string {
-	return isString(value) && allowed.has(value);
-}
-
-function hasOnlyKeys(record: Record<string, unknown>, keys: readonly string[]): boolean {
-	return Object.keys(record).every((key) => keys.includes(key));
-}
-
-function isValidReviewerResult(value: unknown): boolean {
-	if (!isRecord(value)) return false;
-	if (!isNonNegativeInt(value.index) || !hasOnlyKeys(value, REVIEWER_RESULT_KEYS))
-		return false;
-	return (
-		isString(value.model) &&
-		isString(value.thinking) &&
-		oneOf(value.status, REVIEWER_STATUSES) &&
-		value.status !== "running" &&
-		isString(value.summary) &&
-		isString(value.details)
-	);
-}
-
-function isValidActiveReviewer(value: unknown): boolean {
-	if (!isRecord(value) || !isNonNegativeInt(value.index)) return false;
-	if (!hasOnlyKeys(value, ACTIVE_REVIEWER_KEYS)) return false;
-	return (
-		isString(value.model) &&
-		isString(value.thinking) &&
-		oneOf(value.status, REVIEWER_STATUSES) &&
-		(value.result === null || isValidReviewerResult(value.result))
-	);
-}
-
-function isValidActiveCheck(value: unknown): boolean {
-	if (!isRecord(value)) return false;
-	if (!hasOnlyKeys(value, ACTIVE_CHECK_KEYS)) return false;
-	const round = value.round;
-	const settledCount = value.settledCount;
-	if (!isNonNegativeInt(round) || !isNonNegativeInt(settledCount)) return false;
-	return (
-		round >= 1 &&
-		Array.isArray(value.reviewers) &&
-		value.reviewers.every(isValidActiveReviewer) &&
-		value.reviewers.length > 0 &&
-		settledCount <= value.reviewers.length
-	);
-}
-
-function isValidAdvisor(value: unknown): boolean {
-	if (!isRecord(value) || !hasOnlyKeys(value, ADVISOR_KEYS)) return false;
-	return oneOf(value.verdict, ADVISOR_VERDICTS) && isString(value.advice);
-}
-
-function isValidRound(value: unknown): boolean {
-	if (!isRecord(value)) return false;
-	if (!hasOnlyKeys(value, ROUND_KEYS)) return false;
-	return (
-		isNonNegativeInt(value.round) &&
-		oneOf(value.result, ROUND_RESULTS) &&
-		isString(value.details) &&
-		Array.isArray(value.reviewers) &&
-		value.reviewers.every(isValidReviewerResult) &&
-		(value.advisor === undefined || isValidAdvisor(value.advisor)) &&
-		(value.reason === undefined || oneOf(value.reason, STOP_REASONS)) &&
-		isNonNegativeInt(value.elapsedMs)
-	);
-}
-
-function isValidPendingRound(value: unknown): boolean {
-	if (!isRecord(value)) return false;
-	if (!hasOnlyKeys(value, PENDING_ROUND_KEYS)) return false;
-	const round = value.round;
-	return (
-		isNonNegativeInt(round) &&
-		round >= 1 &&
-		Array.isArray(value.reviewers) &&
-		value.reviewers.every(isValidReviewerResult) &&
-		isString(value.details)
-	);
-}
-
-function isValidRepair(value: unknown): boolean {
-	return (
-		isRecord(value) &&
-		hasOnlyKeys(value, REPAIR_KEYS) &&
-		isString(value.details) &&
-		(value.advisor === null || isValidAdvisor(value.advisor)) &&
-		oneOf(value.status, REPAIR_STATUSES)
-	);
-}
-
-function isValidSummary(value: unknown): boolean {
-	return (
-		isRecord(value) &&
-		hasOnlyKeys(value, SUMMARY_KEYS) &&
-		oneOf(value.kind, SUMMARY_KINDS) &&
-		oneOf(value.status, SUMMARY_STATUSES)
-	);
-}
-
-/** 一次性整体校验 checkpoint；结构或版本不符返回 false（调用方直接丢弃）。 */
-export function isValidCheckpoint(value: unknown): boolean {
-	if (!isRecord(value)) return false;
-	if (!hasOnlyKeys(value, CHECKPOINT_KEYS)) return false;
-	if (!isNonNegativeInt(value.seq) || value.seq < 1) return false;
-	return (
-		value.version === VERSION &&
-		isString(value.runId) &&
-		oneOf(value.phase, PHASES) &&
-		isNonNegativeInt(value.round) &&
-		isString(value.focus) &&
-		Array.isArray(value.history) &&
-		value.history.every(isValidRound) &&
-		(value.active === null || isValidActiveCheck(value.active)) &&
-		(value.pending === null || isValidPendingRound(value.pending)) &&
-		(value.repair === null || isValidRepair(value.repair)) &&
-		(value.summary === null || isValidSummary(value.summary)) &&
-		isNonNegativeInt(value.consecutiveFailures) &&
-		isNonNegativeInt(value.startedAt) &&
-		isNonNegativeInt(value.roundStartedAt) &&
-		isNonNegativeInt(value.updatedAt)
-	);
-}
-
-function toCheckpoint(state: ReviewState) {
-	return {
-		version: VERSION,
-		runId: state.runId,
-		phase: state.phase,
-		round: state.round,
-		focus: state.focus,
-		history: state.history,
-		active: state.active,
-		pending: state.pending,
-		repair: state.repair,
-		summary: state.summary,
-		consecutiveFailures: state.consecutiveFailures,
-		startedAt: state.startedAt,
-		roundStartedAt: state.roundStartedAt,
-		updatedAt: state.updatedAt,
-	};
-}
-
-/** 读当前分支上最近一个 checkpoint；无、损坏或版本不匹配都返回 undefined。 */
-export function readCheckpoint(ctx: CheckpointReadContext): ReviewState | undefined {
-	const entry = latestEntry(ctx);
-	return entry ? (entry as unknown as ReviewState) : undefined;
-}
-
-function latestEntry(ctx: CheckpointReadContext): Record<string, unknown> | undefined {
-	const entries = ctx.sessionManager.getBranch();
-	for (let index = entries.length - 1; index >= 0; index -= 1) {
-		const entry = entries[index];
-		if (!isRecord(entry) || entry.type !== "custom") continue;
-		if (entry.customType !== CHECKPOINT_TYPE) continue;
-		if (!isValidCheckpoint(entry.data)) return undefined;
-		return entry.data as Record<string, unknown>;
-	}
-	return undefined;
-}
-
-/** 读最近一条 checkpoint 的写入凭证；无则 null。 */
-export function readStamp(ctx: CheckpointReadContext): CheckpointStamp | null {
-	const entry = latestEntry(ctx);
-	if (!entry) return null;
-	const data = entry as { runId: string; seq: number };
-	return { runId: data.runId, seq: data.seq };
-}
-
-function appendCheckpoint(
-	pi: ExtensionAPI,
-	state: ReviewState,
-	seq: number,
-): CheckpointStamp {
-	const data = { ...toCheckpoint(state), seq };
-	if (!isValidCheckpoint(data)) throw new Error("fire-review checkpoint 状态非法");
-	pi.appendEntry(CHECKPOINT_TYPE, data);
-	return { runId: state.runId, seq };
-}
-
-/** 新审查首次写入：无条件替换旧终态（不校验旧 Run ID）。 */
-/** 新审查首写：无条件替换旧终态，返回本次写入凭证。 */
-export function beginCheckpoint(
-	pi: ExtensionAPI,
-	_ctx: CheckpointReadContext,
-	state: ReviewState,
-): CheckpointStamp {
-	return appendCheckpoint(pi, state, 1);
-}
-
-/**
- * 后续写入时当前持久化凭证必须与 controller 记住的上一次完全一致。
- * 只比 Run ID 不够——同一场审查被两个运行时同时恢复时 Run ID 相同，
- * 靠 seq 才能识别出陈旧写者并拒绝静默覆盖。
- */
-export function writeCheckpoint(
-	pi: ExtensionAPI,
-	ctx: CheckpointReadContext,
-	state: ReviewState,
-	expected: CheckpointStamp,
-): CheckpointStamp {
-	const current = readStamp(ctx);
-	if (
-		!current ||
-		current.runId !== expected.runId ||
-		current.seq !== expected.seq
-	)
-		throw new CheckpointConflictError();
-	return appendCheckpoint(pi, state, expected.seq + 1);
-}

package/review/evidence.ts

@@ -1,230 +0,0 @@
-/**
- * 会话证据组装：取会话分支 entries 转纯文本，按 token 预算裁剪。
- *
- * 根因规避：首条用户消息是原始需求锚点，固定保留，不参与预算竞争；
- * 预算只裁剪中间的旧消息，从最新往前保留最近工作，审查者既知道要什么也知道做了什么。
- * assistant 的工具调用轨迹（工具名 + path/command）随消息渲染：它是范围归因的一手证据，
- * 审查者靠它判断本会话实际编辑了什么，共享 checkout 上无法归因的 diff 不得立案。
- * isError 的调用标注失败：尝试过不等于编辑成功，失败调用不得成为归因依据；
- * 无结果的调用不标——把压缩/中止场景的真实编辑误标未完成，会反向把归因弱化成假 PASS。
- * toolResult 正文仍跳过（输出体积大且非一手证据——审查者应自行重跑验证命令）。
- */
-import type { Language } from "../config.js";
-import { textOf } from "../format.js";
-
-export const DEFAULT_EVIDENCE_TOKENS = 24_000;
-/** 单条消息渲染上限，防单条超长消息撑爆预算。 */
-const MESSAGE_MAX_CHARS = 3_000;
-
-export interface Evidence {
-	text: string;
-	/** 被预算裁剪掉的中间消息条数。 */
-	omitted: number;
-}
-
-interface Render {
-	language: Language;
-	/** 会话文件：截断标记据此告诉审查者完整原文在哪里。内存会话没有。 */
-	sessionFile?: string;
-	failedCalls: ReadonlySet<string>;
-}
-
-export function buildEvidence(
-	entries: readonly unknown[],
-	language: Language,
-	{ budgetTokens = DEFAULT_EVIDENCE_TOKENS, sessionFile }: { budgetTokens?: number; sessionFile?: string } = {},
-): Evidence {
-	const render: Render = { language, ...(sessionFile ? { sessionFile } : {}), failedCalls: collectFailedCalls(entries) };
-	const blocks = entries.flatMap((entry) => renderEntry(entry, render));
-	if (blocks.length === 0) return { text: "", omitted: 0 };
-	// 锚点必须是首条用户消息（原始需求）：它之前可能排着其他扩展的可显示消息，
-	// 盲取第一块会把真正的需求锚点让进预算竞争、在长会话里被裁掉。
-	const anchorIndex = Math.max(
-		0,
-		blocks.findIndex((block) => block.role === "user"),
-	);
-	const anchor = blocks[anchorIndex];
-	const rest = blocks.filter((_, index) => index !== anchorIndex);
-	const recent: string[] = [];
-	let used = estimateTokens(anchor.text);
-	let omitted = 0;
-	for (let index = rest.length - 1; index >= 0; index -= 1) {
-		const block = rest[index];
-		const cost = estimateTokens(block.text);
-		if (used + cost > budgetTokens) {
-			omitted += 1;
-			continue;
-		}
-		recent.push(block.text);
-		used += cost;
-	}
-	recent.reverse();
-	const text =
-		recent.length === 0
-			? anchor.text
-			: `${anchor.text}\n\n${omitted > 0 ? gapLabel(omitted, language) : ""}${recent.join("\n\n")}`;
-	return { text, omitted };
-}
-
-function gapLabel(omitted: number, language: Language) {
-	return language === "en"
-		? `[${omitted} intermediate message(s) omitted under the evidence budget]\n\n`
-		: `[证据预算省略了 ${omitted} 条中间消息]\n\n`;
-}
-
-type EvidenceBlock = { text: string; role?: "user" };
-
-/** isError 的 toolResult 集合：失败调用不得在轨迹里冒充实际编辑。 */
-function collectFailedCalls(entries: readonly unknown[]): ReadonlySet<string> {
-	const failed = new Set<string>();
-	for (const entry of entries) {
-		if (!isRecord(entry) || entry.type !== "message") continue;
-		const message = asRecord(entry.message);
-		if (message?.role !== "toolResult" || message.isError !== true) continue;
-		if (typeof message.toolCallId === "string") failed.add(message.toolCallId);
-	}
-	return failed;
-}
-
-function renderEntry(entry: unknown, render: Render): EvidenceBlock[] {
-	const { language } = render;
-	if (!isRecord(entry)) return [];
-	switch (entry.type) {
-		case "message": {
-			const message = asRecord(entry.message);
-			if (!message) return [];
-			if (message.role === "user")
-				return [
-					{
-						text: `## ${userLabel(language)}\n${clip(textOf(message.content), render)}`,
-						role: "user" as const,
-					},
-				];
-			if (message.role === "assistant")
-				return [{ text: `## ${assistantLabel(language)}\n${assistantBody(message.content, render)}` }];
-			return [];
-		}
-		case "custom_message": {
-			if (entry.display !== true) return [];
-			return [{ text: `## ${customLabel(language, String(entry.customType ?? ""))}\n${clip(textOf(entry.content), render)}` }];
-		}
-		case "compaction":
-			return typeof entry.summary === "string" && entry.summary
-				? [{ text: `## ${summaryLabel(language)}\n${clip(entry.summary, render)}` }]
-				: [];
-		case "branch_summary":
-			return typeof entry.summary === "string" && entry.summary
-				? [{ text: `## ${branchSummaryLabel(language)}\n${clip(entry.summary, render)}` }]
-				: [];
-		default:
-			return [];
-	}
-}
-
-function userLabel(language: Language) {
-	return language === "en" ? "User" : "用户";
-}
-
-function assistantLabel(language: Language) {
-	return language === "en" ? "Assistant" : "助手";
-}
-
-function customLabel(language: Language, customType: string) {
-	return language === "en" ? `Message (${customType})` : `消息（${customType}）`;
-}
-
-function summaryLabel(language: Language) {
-	return language === "en" ? "History summary (compacted)" : "历史摘要（已压缩）";
-}
-
-function branchSummaryLabel(language: Language) {
-	return language === "en" ? "Branch summary" : "分支摘要";
-}
-
-/** assistant 正文 = 文本段 + 工具调用轨迹；纯工具回合也因此留下编辑记录。 */
-function assistantBody(content: unknown, render: Render): string {
-	if (typeof content === "string") return clip(content, render);
-	if (!Array.isArray(content)) return "";
-	const trail = content
-		.map((part) => toolCallLine(asRecord(part), render))
-		.filter(Boolean)
-		.join("\n");
-	const body = clip(textOf(content), render);
-	return [body, trail].filter(Boolean).join("\n");
-}
-
-function toolCallLine(part: Record<string, unknown> | undefined, render: Render): string {
-	const { language, failedCalls } = render;
-	if (part?.type !== "toolCall" || typeof part.name !== "string" || !part.name) return "";
-	const args = asRecord(part.arguments);
-	const target =
-		typeof args?.path === "string"
-			? args.path
-			: typeof args?.command === "string"
-				? args.command
-				: "";
-	const failed =
-		typeof part.id === "string" && failedCalls.has(part.id)
-			? language === "en"
-				? " (failed)"
-				: "（失败）"
-			: "";
-	return `${`[${part.name}] ${clipLine(target, render)}`.trimEnd()}${failed}`;
-}
-
-/** 单行轨迹上限：防超长 bash 命令撑大证据块；路径不受影响。 */
-const TOOL_LINE_MAX_CHARS = 200;
-
-function clipLine(text: string, { language, sessionFile }: Render) {
-	const single = text.replace(/\s+/gu, " ").trim();
-	if (single.length <= TOOL_LINE_MAX_CHARS) return single;
-	const where = sessionFile ?? (language === "en" ? "the session file" : "会话文件");
-	const note = language === "en"
-		? `…[truncated, ${single.length} chars; full original in ${where}]`
-		: `…[截断，原文 ${single.length} 字，完整原文在 ${where}]`;
-	return `${single.slice(0, TOOL_LINE_MAX_CHARS)}${note}`;
-}
-
-/**
- * 截断处必须写明是证据组装的截断：裸省略号会被审查者当成回复本身没写完（长交付物曾因此连判 FAIL）。
- * 完整原文在会话文件里，审查者能用 read 自行核对。
- */
-function clip(text: string, { language, sessionFile }: Render) {
-	if (text.length <= MESSAGE_MAX_CHARS) return text.trim();
-	const where = sessionFile ?? (language === "en" ? "the session file" : "会话文件");
-	const note = language === "en"
-		? `[evidence truncated: this message has ${text.length} characters, only the first ${MESSAGE_MAX_CHARS} are shown; the full original is in ${where} — read it if you need to verify]`
-		: `[证据截断：本条消息原文 ${text.length} 字，此处只给出前 ${MESSAGE_MAX_CHARS} 字；完整原文在 ${where}，需要核对时用 read 查看]`;
-	return `${text.slice(0, MESSAGE_MAX_CHARS).trim()}\n${note}`;
-}
-
-/**
- * 粗略 token 估计：CJK 每字 1 token，其余按 4 字符/token。
- * 用于预算裁剪的相对量级，不追求精确。
- */
-export function estimateTokens(text: string): number {
-	let cjk = 0;
-	let other = 0;
-	for (const char of text) {
-		if (isCjk(char)) cjk += 1;
-		else other += 1;
-	}
-	return Math.ceil(cjk + other / 4);
-}
-
-function isCjk(char: string) {
-	const code = char.codePointAt(0) ?? 0;
-	return (
-		(code >= 0x4e00 && code <= 0x9fff) ||
-		(code >= 0x3400 && code <= 0x4dbf) ||
-		(code >= 0xf900 && code <= 0xfaff)
-	);
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-	return isRecord(value) ? value : undefined;
-}