pi-harness-runtime 1.1.407 → 1.1.410

package/packages/two-phase-review/dist/state.js

@@ -0,0 +1,238 @@
+/**
+ * The persisted state of the two-phase workflow.
+ *
+ * The state survives a restart and a compaction, so the phase, the task start
+ * revision, the review scope, the finished chunks and the open findings are
+ * never lost.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** The directory the state files live in. */
+export const TWO_PHASE_STATE_DIR = join(homedir(), ".pi-harness-runtime", "two-phase-review");
+const PHASE_ORDER = {
+    implementation: 0,
+    review_pending: 1,
+    review: 2,
+    review_fixes: 3,
+    complete: 4,
+};
+/** Makes the name of a temporary state file unique. */
+let writeCounter = 0;
+/** A fresh state for a task. */
+export function createState(taskId, startRevision = null) {
+    return {
+        phase: "implementation",
+        taskId,
+        startRevision,
+        scopeFiles: [],
+        chunks: [],
+        signals: [],
+        findings: [],
+        updatedAt: new Date().toISOString(),
+    };
+}
+/** Make a file name safe for the file system. */
+export function safeFileName(taskId) {
+    return (taskId || "default").replace(/[^A-Za-z0-9._-]+/g, "_");
+}
+/** The entries of a directory, for a readable error message. */
+function listDir(dir) {
+    try {
+        return readdirSync(dir).join(",");
+    }
+    catch {
+        return "<unreadable>";
+    }
+}
+function isPhase(value) {
+    return (typeof value === "string" &&
+        ["implementation", "review_pending", "review", "review_fixes", "complete"].includes(value));
+}
+/** Repair a state that was read from disk. */
+export function normalizeState(value, taskId) {
+    const raw = (value ?? {});
+    return {
+        phase: isPhase(raw.phase) ? raw.phase : "implementation",
+        taskId: typeof raw.taskId === "string" && raw.taskId ? raw.taskId : taskId,
+        startRevision: typeof raw.startRevision === "string" ? raw.startRevision : null,
+        scopeFiles: Array.isArray(raw.scopeFiles) ? raw.scopeFiles.filter((f) => typeof f === "string") : [],
+        chunks: Array.isArray(raw.chunks) ? raw.chunks.filter(isChunk) : [],
+        signals: Array.isArray(raw.signals) ? raw.signals.filter(isSignal) : [],
+        findings: Array.isArray(raw.findings) ? raw.findings.filter(isFinding) : [],
+        reviewTodoSubject: typeof raw.reviewTodoSubject === "string" ? raw.reviewTodoSubject : undefined,
+        reviewTodoDescription: typeof raw.reviewTodoDescription === "string" ? raw.reviewTodoDescription : undefined,
+        updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : new Date().toISOString(),
+    };
+}
+/** Is the chunk of a persisted state usable? */
+function isChunk(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const chunk = value;
+    return (typeof chunk.id === "string" &&
+        typeof chunk.label === "string" &&
+        Array.isArray(chunk.files) &&
+        chunk.files.every((file) => typeof file === "string") &&
+        (chunk.status === "pending" || chunk.status === "done"));
+}
+/** Is the signal of a persisted state usable? */
+function isSignal(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const signal = value;
+    return (typeof signal.source === "string" &&
+        typeof signal.reason === "string" &&
+        Array.isArray(signal.files) &&
+        signal.files.every((file) => typeof file === "string"));
+}
+/** Is the finding of a persisted state usable? */
+function isFinding(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const finding = value;
+    return typeof finding.id === "string" && typeof finding.summary === "string";
+}
+/** The state of one task on disk. */
+export class TwoPhaseStateStore {
+    dir;
+    constructor(dir = TWO_PHASE_STATE_DIR) {
+        this.dir = dir;
+    }
+    /** The file the state of the task lives in. */
+    path(taskId) {
+        return join(this.dir, `${safeFileName(taskId)}.json`);
+    }
+    /**
+     * Read the state of the task.
+     *
+     * `null` means that there is no state. A state that exists but cannot be
+     * read is an error: it must not be mistaken for a fresh task, because that
+     * would lose the revision the task started at and the progress of the
+     * review.
+     */
+    read(taskId) {
+        const path = this.path(taskId);
+        if (!existsSync(path))
+            return null;
+        let content;
+        try {
+            content = readFileSync(path, "utf8");
+        }
+        catch (error) {
+            throw new Error(`the state file could not be read: ${error.message}; path=${path}`, { cause: error });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (error) {
+            throw new Error(`the state file is not valid JSON: ${error.message}; path=${path}`, { cause: error });
+        }
+        if (!parsed || typeof parsed !== "object") {
+            throw new Error(`the state file does not contain a state: path=${path}`);
+        }
+        return normalizeState(parsed, taskId);
+    }
+    /**
+     * Write the state of the task.
+     *
+     * A failing write is reported to the caller: the runtime decides whether
+     * the session may continue without the state, the test sees the reason.
+     */
+    write(state) {
+        const next = { ...state, updatedAt: new Date().toISOString() };
+        mkdirSync(this.dir, { recursive: true });
+        const path = this.path(next.taskId);
+        // Every writer uses its own temporary file, so two writers cannot
+        // rename the content of each other.
+        const temporary = `${path}.${process.pid}.${writeCounter++}.tmp`;
+        try {
+            writeFileSync(temporary, JSON.stringify(next, null, 2), "utf8");
+            renameSync(temporary, path);
+        }
+        catch (error) {
+            throw new Error(`the state file could not be written: ${error.message}; dir=${this.dir}; entries=${listDir(this.dir)}`, { cause: error });
+        }
+        return next;
+    }
+    /** Remove the state of the task. */
+    clear(taskId) {
+        try {
+            rmSync(this.path(taskId), { force: true });
+        }
+        catch {
+            // Nothing to remove.
+        }
+    }
+}
+/** Move to a phase, never backwards. */
+export function moveToPhase(state, phase) {
+    if (PHASE_ORDER[phase] <= PHASE_ORDER[state.phase])
+        return state;
+    return { ...state, phase };
+}
+/** Record a review signal. The phase does not change. */
+export function recordSignal(state, signal) {
+    const key = `${signal.source}::${[...signal.files].sort().join(",")}::${signal.reason
+        .trim()
+        .toLowerCase()}`;
+    if (state.signals.some((entry) => `${entry.source}::${[...entry.files]
+        .sort()
+        .join(",")}::${entry.reason.trim().toLowerCase()}` === key)) {
+        return state;
+    }
+    return { ...state, signals: [...state.signals, signal] };
+}
+/** The implementation is done: the review waits for its scope. */
+export function transitionToReviewPending(state, scopeFiles) {
+    return { ...moveToPhase(state, "review_pending"), scopeFiles };
+}
+/** The review starts with the given chunks. */
+export function startReview(state, chunks) {
+    return { ...moveToPhase(state, "review"), chunks };
+}
+/** Mark a review chunk as finished. */
+export function markChunkDone(state, chunkId) {
+    const chunks = state.chunks.map((chunk) => chunk.id === chunkId ? { ...chunk, status: "done" } : chunk);
+    return { ...state, chunks };
+}
+/** Record a confirmed finding. */
+export function recordFinding(state, finding) {
+    return { ...state, findings: [...state.findings, finding] };
+}
+/**
+ * The review found something: the fixes are now the work.
+ *
+ * The fixes start when the review is finished: a fix phase before the review
+ * ran would hide the work that is still open.
+ */
+export function transitionToReviewFixes(state) {
+    if (state.phase !== "review")
+        return state;
+    if (!allChunksDone(state))
+        return state;
+    return moveToPhase(state, "review_fixes");
+}
+/** Every chunk is finished. */
+export function allChunksDone(state) {
+    return state.chunks.length > 0 && state.chunks.every((chunk) => chunk.status === "done");
+}
+/**
+ * The work is finished.
+ *
+ * The task is only complete when the review ran over every chunk. The
+ * implementation phase never completes the task on its own.
+ */
+export function markComplete(state) {
+    if (state.phase === "implementation" || state.phase === "review_pending")
+        return state;
+    if (!allChunksDone(state))
+        return state;
+    return moveToPhase(state, "complete");
+}
+/** Is a review queued? */
+export function hasQueuedReview(state) {
+    return state.signals.length > 0;
+}
+//# sourceMappingURL=state.js.map

package/packages/two-phase-review/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}

package/packages/two-phase-review/dist/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Types of the two-phase implementation and review workflow.
+ *
+ * The workflow keeps two phases apart: the implementation of the requested
+ * work (Phase 1) and the comprehensive review of that work (Phase 2). A
+ * review signal that arrives during Phase 1 is recorded, never executed.
+ */
+/** The phase the task currently is in. */
+export type TwoPhasePhase = "implementation" | "review_pending" | "review" | "review_fixes" | "complete";
+/** What a todo item represents. */
+export type TodoKind = "implement" | "review" | "review_fix" | "other";
+/** A "review now" signal that arrived while the implementation was running. */
+export interface ReviewSignal {
+    /** Who raised the signal (tool name, agent name, command). */
+    source: string;
+    /** The files the signal points at (best effort). */
+    files: string[];
+    /** Why the signal was raised, in one short line. */
+    reason: string;
+    /** ISO timestamp of the signal. */
+    at: string;
+}
+/** One review unit: a logical scope of the task diff. */
+export interface ReviewChunk {
+    id: string;
+    label: string;
+    files: string[];
+    status: "pending" | "done";
+}
+/** A confirmed finding of the review. */
+export interface ReviewFinding {
+    id: string;
+    severity: "low" | "medium" | "high";
+    summary: string;
+    chunkId?: string;
+    /** A finding the user accepted as a known issue. */
+    accepted?: boolean;
+    at: string;
+}
+/** The persisted state of the workflow for one task. */
+export interface TwoPhaseState {
+    phase: TwoPhasePhase;
+    /** The task the state belongs to (the session id). */
+    taskId: string;
+    /** The revision the task started at: the review scope is the diff since then. */
+    startRevision: string | null;
+    /** The files the review covers. */
+    scopeFiles: string[];
+    /** The review chunks the scope was split into. */
+    chunks: ReviewChunk[];
+    /** Every review signal that was recorded (deduplicated). */
+    signals: ReviewSignal[];
+    /** The findings the review produced. */
+    findings: ReviewFinding[];
+    /** The subject of the queued review todo (one item, not many). */
+    reviewTodoSubject?: string;
+    /** The description of the queued review todo. */
+    reviewTodoDescription?: string;
+    /** ISO timestamp of the last write. */
+    updatedAt: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/packages/two-phase-review/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,0CAA0C;AAC1C,MAAM,MAAM,aAAa,GACtB,gBAAgB,GAChB,gBAAgB,GAChB,QAAQ,GACR,cAAc,GACd,UAAU,CAAC;AAEd,mCAAmC;AACnC,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC;AAEvE,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC5B,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;CACX;AAED,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;CAC3B;AAED,yCAAyC;AACzC,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;CACX;AAED,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,aAAa,CAAC;IACrB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mCAAmC;IACnC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,kDAAkD;IAClD,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,4DAA4D;IAC5D,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,wCAAwC;IACxC,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,kEAAkE;IAClE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;CAClB"}

package/packages/two-phase-review/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * Types of the two-phase implementation and review workflow.
+ *
+ * The workflow keeps two phases apart: the implementation of the requested
+ * work (Phase 1) and the comprehensive review of that work (Phase 2). A
+ * review signal that arrives during Phase 1 is recorded, never executed.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/packages/two-phase-review/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/packages/two-phase-review/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@pi-harness/two-phase-review",
+  "version": "1.1.410",
+  "description": "pi-harness-runtime — two-phase implementation and review workflow (queue review signals, gate the phase, scope the diff)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test"
+  }
+}

package/packages/two-phase-review/src/classify.ts

@@ -0,0 +1,129 @@
+/**
+ * Todo classification for the two-phase workflow.
+ *
+ * Implementation work and queued review work must never be confused. The
+ * workflow therefore classifies every todo item before it decides whether
+ * the implementation phase is over.
+ */
+
+import type { TodoKind } from "./types.js";
+
+/** Prefix of a todo item that is implementation work. */
+export const IMPLEMENT_PREFIX = "[IMPLEMENT]";
+/** Prefix of a todo item that is the queued review. */
+export const REVIEW_PREFIX = "[REVIEW]";
+/** Prefix of a todo item that fixes a confirmed review finding. */
+export const REVIEW_FIX_PREFIX = "[REVIEW-FIX]";
+
+/** The part of a todo item the workflow needs. */
+export interface TodoLike {
+	id?: number;
+	subject?: string;
+	status?: string;
+	metadata?: Record<string, unknown>;
+}
+
+const KIND_BY_NAME: Record<string, TodoKind> = {
+	implement: "implement",
+	implementation: "implement",
+	impl: "implement",
+	review: "review",
+	review_pending: "review",
+	"review-pending": "review",
+	review_fix: "review_fix",
+	"review-fix": "review_fix",
+	reviewfix: "review_fix",
+	other: "other",
+};
+
+/**
+ * Classify a todo item.
+ *
+ * The metadata wins over the title: an explicit kind is more reliable than a
+ * prefix. A `[REVIEW-FIX]` title is a fix item, not a review item, so the fix
+ * prefix is checked first.
+ */
+export function classifyTodo(todo: TodoLike | null | undefined): TodoKind {
+	if (!todo) return "other";
+
+	const metadata = todo.metadata ?? {};
+	const declared = metadata.kind ?? metadata.todoKind;
+	if (typeof declared === "string") {
+		const key = declared.toLowerCase().trim().replace(/[\s-]+/g, "_");
+		const mapped = KIND_BY_NAME[key];
+		if (mapped) return mapped;
+	}
+
+	const subject = (todo.subject ?? "").trim().toUpperCase();
+	if (subject.startsWith(REVIEW_FIX_PREFIX)) return "review_fix";
+	if (subject.startsWith(IMPLEMENT_PREFIX)) return "implement";
+	if (subject.startsWith(REVIEW_PREFIX)) return "review";
+	return "other";
+}
+
+/** Is the todo item still open? */
+export function isOpenTodo(todo: TodoLike): boolean {
+	return todo.status === "pending" || todo.status === "in_progress";
+}
+
+/** Every open todo item. */
+export function openTodos(todos: TodoLike[]): TodoLike[] {
+	return todos.filter((todo) => isOpenTodo(todo));
+}
+
+/**
+ * The open todo items that are still implementation work.
+ *
+ * A queued review item is not implementation work: it must never block the
+ * implementation. An unclassified item counts as implementation work, because
+ * a task that is tracked without a prefix is still work that has to finish.
+ */
+export function implementationTodos(todos: TodoLike[]): TodoLike[] {
+	return openTodos(todos).filter((todo) => {
+		const kind = classifyTodo(todo);
+		return kind === "implement" || kind === "other";
+	});
+}
+
+/** The open todo items that represent the queued review. */
+export function reviewTodos(todos: TodoLike[]): TodoLike[] {
+	return openTodos(todos).filter((todo) => classifyTodo(todo) === "review");
+}
+
+/** The open todo items that fix a confirmed review finding. */
+export function reviewFixTodos(todos: TodoLike[]): TodoLike[] {
+	return openTodos(todos).filter((todo) => classifyTodo(todo) === "review_fix");
+}
+
+/** Does the task still have implementation work? */
+export function hasOpenImplementationWork(todos: TodoLike[]): boolean {
+	return implementationTodos(todos).length > 0;
+}
+
+/** How many todo items of each kind are open. */
+export function summarizeTodos(todos: TodoLike[]): {
+	implementation: number;
+	review: number;
+	reviewFix: number;
+} {
+	return {
+		implementation: implementationTodos(todos).length,
+		review: reviewTodos(todos).length,
+		reviewFix: reviewFixTodos(todos).length,
+	};
+}
+
+const PREFIX_BY_KIND: Record<TodoKind, string> = {
+	implement: IMPLEMENT_PREFIX,
+	review: REVIEW_PREFIX,
+	review_fix: REVIEW_FIX_PREFIX,
+	other: "",
+};
+
+/** Prefix a title with the kind of its todo item. */
+export function buildTodoSubject(kind: TodoKind, text: string): string {
+	const prefix = PREFIX_BY_KIND[kind];
+	const clean = text.trim();
+	if (!prefix) return clean;
+	return clean.toUpperCase().startsWith(prefix) ? clean : `${prefix} ${clean}`;
+}

package/packages/two-phase-review/src/index.ts

@@ -0,0 +1,110 @@
+/**
+ * Two-phase implementation and review workflow.
+ *
+ * Phase 1 finishes the implementation todos of a request. Phase 2 reviews the
+ * diff of that request. A review signal that arrives during Phase 1 is
+ * recorded and deferred, never executed between two implementation todos.
+ */
+
+export type {
+	TwoPhasePhase,
+	TodoKind,
+	ReviewSignal,
+	ReviewChunk,
+	ReviewFinding,
+	TwoPhaseState,
+} from "./types.js";
+
+export {
+	IMPLEMENT_PREFIX,
+	REVIEW_PREFIX,
+	REVIEW_FIX_PREFIX,
+	classifyTodo,
+	isOpenTodo,
+	openTodos,
+	implementationTodos,
+	reviewTodos,
+	reviewFixTodos,
+	hasOpenImplementationWork,
+	summarizeTodos,
+	buildTodoSubject,
+} from "./classify.js";
+export type { TodoLike } from "./classify.js";
+
+export {
+	DEFAULT_REVIEW_TOOL_PATTERNS,
+	DEFAULT_REVIEW_COMMAND_PATTERNS,
+	parseExtraPatterns,
+	isComprehensiveReviewTool,
+	isReviewCommand,
+	dispatchAgentName,
+	detectReviewInvocation,
+	explicitReviewRequest,
+	extractFiles,
+	signalKey,
+	mergeSignals,
+	summarizeSignals,
+} from "./signals.js";
+export type { ReviewInvocation, SignalSummary } from "./signals.js";
+
+export {
+	EXCLUDED_SCOPE_PREFIXES,
+	DEFAULT_CHUNK_SIZE,
+	isReviewablePath,
+	isGitRepository,
+	currentRevision,
+	revisionExists,
+	moduleKey,
+	countModules,
+	parseNumstat,
+	collectScope,
+	chunkScope,
+	shouldChunkScope,
+} from "./scope.js";
+export type { ScopeMetrics, ScopeResult } from "./scope.js";
+
+export {
+	TWO_PHASE_STATE_DIR,
+	createState,
+	safeFileName,
+	normalizeState,
+	TwoPhaseStateStore,
+	moveToPhase,
+	recordSignal,
+	transitionToReviewPending,
+	startReview,
+	markChunkDone,
+	recordFinding,
+	transitionToReviewFixes,
+	allChunksDone,
+	markComplete,
+	hasQueuedReview,
+} from "./state.js";
+
+export {
+	TWO_PHASE_CONTRACT,
+	buildPhaseView,
+	buildPhaseInstruction,
+	buildReviewTodoSubject,
+	buildReviewTodoDescription,
+	buildChunkTodoSubject,
+	buildChunkTodoDescription,
+	isChunkTodo,
+	syncChunkStatus,
+	formatPhaseStatus,
+	buildDeferralReason,
+} from "./rules.js";
+export type { PhaseView } from "./rules.js";
+
+export {
+	HARNESS_MESSAGE_MARKER,
+	initTwoPhaseReview,
+} from "./runtime.js";
+export type {
+	TwoPhaseExtensionApi,
+	TwoPhaseExtensionContext,
+	TwoPhaseRuntime,
+	TwoPhaseRuntimeOptions,
+	TodoReadResult,
+	TodoReader,
+} from "./runtime.js";