pi-harness-runtime 0.10.11 → 0.10.12

package/packages/experience-replay/src/replay.ts

@@ -0,0 +1,348 @@
+/**
+ * Experience Replay (RFC-0059)
+ *
+ * Reconstructs prior runtime execution from persisted events and checkpoints.
+ */
+
+import type {
+	ReplayRequest,
+	ReplayResult,
+	ReplayEvent,
+	ReplayDivergence,
+	JobStateSnapshot,
+	ReplaySources,
+	DivergenceReason,
+	ReplayRuntimeEvent,
+	RuntimeEvent,
+	RuntimeCheckpoint,
+	TaskGraph,
+} from "./types.js";
+
+// --- Event Timeline Reconstruction -------------------------------------------
+
+function reconstructTimeline(
+	events: RuntimeEvent[],
+	startSequence = 0,
+): ReplayEvent[] {
+	return events.map((event, index) => ({
+		sequence: startSequence + index,
+		timestamp: event.ts,
+		type: event.type,
+		data: event.data || {},
+	}));
+}
+
+// --- State Reconstruction -----------------------------------------------------
+
+function reconstructState(
+	jobId: string,
+	checkpoint: RuntimeCheckpoint | undefined,
+	events: RuntimeEvent[],
+	taskGraph: TaskGraph | undefined,
+): JobStateSnapshot {
+	// Apply events to checkpoint to get final state
+	let currentTaskId = checkpoint?.currentTaskId;
+	let status = checkpoint?.status || "unknown";
+
+	// Process events to find latest state
+	for (const event of events) {
+		if (event.type === "task.started" && event.data?.taskId) {
+			currentTaskId = event.data.taskId as string;
+		}
+		if (event.type === "job.status") {
+			status = (event.data?.status as string) || status;
+		}
+	}
+
+	return {
+		jobId,
+		status,
+		currentTaskId,
+		checkpoint: checkpoint || {
+			version: 0,
+			jobId,
+			status: "unknown",
+			requirement: "",
+			createdAt: new Date().toISOString(),
+			updatedAt: new Date().toISOString(),
+		},
+		taskGraph: taskGraph || { nodes: [], edges: [] },
+		events,
+		timestamp: new Date().toISOString(),
+	};
+}
+
+// --- Divergence Detection ----------------------------------------------------
+
+// --- Source Validation --------------------------------------------------------
+
+function validateSources(sources: ReplaySources): {
+	valid: boolean;
+	missing: string[];
+} {
+	const missing: string[] = [];
+
+	if (!sources.checkpoint && !sources.events) {
+		missing.push("checkpoint or events");
+	}
+
+	return { valid: missing.length === 0, missing };
+}
+
+// --- Mode Handlers ------------------------------------------------------------
+
+async function handleInspect(
+	sources: ReplaySources,
+	jobId: string,
+	fromSequence?: number,
+	toSequence?: number,
+): Promise<{ state: JobStateSnapshot; timeline: ReplayEvent[] }> {
+	const events = sources.events || [];
+	const filteredEvents =
+		fromSequence !== undefined || toSequence !== undefined
+			? events.slice(fromSequence, toSequence)
+			: events;
+
+	const timeline = reconstructTimeline(filteredEvents, fromSequence ?? 0);
+	const state = reconstructState(
+		jobId,
+		sources.checkpoint,
+		filteredEvents,
+		sources.taskGraph,
+	);
+
+	return { state, timeline };
+}
+
+async function handleSimulate(
+	sources: ReplaySources,
+	jobId: string,
+	fromSequence?: number,
+	toSequence?: number,
+): Promise<{
+	state: JobStateSnapshot;
+	timeline: ReplayEvent[];
+	divergences: ReplayDivergence[];
+}> {
+	const events = sources.events || [];
+	const filteredEvents =
+		fromSequence !== undefined || toSequence !== undefined
+			? events.slice(fromSequence, toSequence)
+			: events;
+
+	const timeline = reconstructTimeline(filteredEvents, fromSequence ?? 0);
+	const state = reconstructState(
+		jobId,
+		sources.checkpoint,
+		filteredEvents,
+		sources.taskGraph,
+	);
+
+	// Check for divergent events
+	const divergences: ReplayDivergence[] = [];
+	for (let i = 0; i < timeline.length; i++) {
+		const event = timeline[i];
+		if (event.type.includes("error") || event.type.includes("failure")) {
+			divergences.push({
+				sequence: event.sequence,
+				reason: "Provider output differs" as DivergenceReason,
+				severity: "warning",
+			});
+		}
+	}
+
+	return { state, timeline, divergences };
+}
+
+async function handleReexecute(
+	sources: ReplaySources,
+	jobId: string,
+	allowExternalCalls: boolean,
+): Promise<{
+	state: JobStateSnapshot;
+	timeline: ReplayEvent[];
+	divergences: ReplayDivergence[];
+}> {
+	// Reexecute requires explicit approval and valid sources
+	const validation = validateSources(sources);
+	if (!validation.valid) {
+		throw new Error(
+			`Missing required sources: ${validation.missing.join(", ")}`,
+		);
+	}
+
+	if (!allowExternalCalls) {
+		throw new Error(
+			"Reexecution with external calls requires explicit approval",
+		);
+	}
+
+	// For reexecution, we simulate first then mark for actual reexecution
+	const result = await handleSimulate(sources, jobId);
+
+	// Add informational divergence for reexecution mode
+	result.divergences.push({
+		sequence: 0,
+		reason: "Runtime version differs" as DivergenceReason,
+		severity: "info",
+	});
+
+	return result;
+}
+
+// --- Main Engine ---------------------------------------------------------------
+
+export class ExperienceReplay {
+	private eventListeners: Array<(event: ReplayRuntimeEvent) => void> = [];
+
+	/**
+	 * Replay a prior job execution
+	 */
+	async replay(
+		request: ReplayRequest,
+		sources: ReplaySources,
+	): Promise<ReplayResult> {
+		const { jobId, mode } = request;
+
+		// Emit start event
+		this.emit({ type: "replay.started", jobId, mode });
+
+		// Validate sources
+		const validation = validateSources(sources);
+		if (!validation.valid) {
+			return {
+				jobId,
+				reconstructedState: {
+					jobId,
+					status: "error",
+					checkpoint: sources.checkpoint || ({} as RuntimeCheckpoint),
+					taskGraph: sources.taskGraph || { nodes: [], edges: [] },
+					events: [],
+					timestamp: new Date().toISOString(),
+				},
+				timeline: [],
+				divergences: [
+					{
+						sequence: 0,
+						reason: `Missing sources: ${validation.missing.join(", ")}`,
+						severity: "error",
+					},
+				],
+				artifacts: [],
+				replayedAt: new Date().toISOString(),
+			};
+		}
+
+		try {
+			let result: {
+				state: JobStateSnapshot;
+				timeline: ReplayEvent[];
+				divergences?: ReplayDivergence[];
+			};
+
+			switch (mode) {
+				case "inspect":
+					result = await handleInspect(
+						sources,
+						jobId,
+						request.fromSequence,
+						request.toSequence,
+					);
+					break;
+				case "simulate":
+					result = await handleSimulate(
+						sources,
+						jobId,
+						request.fromSequence,
+						request.toSequence,
+					);
+					break;
+				case "reexecute":
+					result = await handleReexecute(
+						sources,
+						jobId,
+						request.allowExternalCalls,
+					);
+					break;
+			}
+
+			// Emit divergence events
+			if (result.divergences) {
+				for (const div of result.divergences) {
+					this.emit({
+						type: "replay.divergence.detected",
+						jobId,
+						reason: div.reason,
+					});
+				}
+			}
+
+			// Collect artifacts
+			const artifacts: string[] = [];
+			if (sources.prompts) artifacts.push(...Object.keys(sources.prompts));
+			if (sources.outputs) artifacts.push(...Object.keys(sources.outputs));
+
+			// Emit completion event
+			this.emit({ type: "replay.completed", jobId });
+
+			return {
+				jobId,
+				reconstructedState: result.state,
+				timeline: result.timeline,
+				divergences: result.divergences || [],
+				artifacts,
+				replayedAt: new Date().toISOString(),
+			};
+		} catch (error) {
+			const errorMessage =
+				error instanceof Error ? error.message : String(error);
+			return {
+				jobId,
+				reconstructedState: {
+					jobId,
+					status: "error",
+					checkpoint: sources.checkpoint || ({} as RuntimeCheckpoint),
+					taskGraph: sources.taskGraph || { nodes: [], edges: [] },
+					events: [],
+					timestamp: new Date().toISOString(),
+				},
+				timeline: [],
+				divergences: [
+					{
+						sequence: 0,
+						reason: errorMessage,
+						severity: "error",
+					},
+				],
+				artifacts: [],
+				replayedAt: new Date().toISOString(),
+			};
+		}
+	}
+
+	/**
+	 * Subscribe to replay events
+	 */
+	onEvent(listener: (event: ReplayRuntimeEvent) => void): () => void {
+		this.eventListeners.push(listener);
+		return () => {
+			this.eventListeners = this.eventListeners.filter((l) => l !== listener);
+		};
+	}
+
+	private emit(event: ReplayRuntimeEvent): void {
+		for (const listener of this.eventListeners) {
+			try {
+				listener(event);
+			} catch {
+				// Best effort
+			}
+		}
+	}
+}
+
+// --- Factory -----------------------------------------------------------------
+
+export function createExperienceReplay(): ExperienceReplay {
+	return new ExperienceReplay();
+}

package/packages/experience-replay/src/types.ts

@@ -0,0 +1,128 @@
+/**
+ * Experience Replay Types (RFC-0059)
+ *
+ * Interfaces for replaying prior runtime execution.
+ */
+
+// --- Local Type Definitions -----------------------------------------------
+
+export interface RuntimeEvent {
+	ts: string;
+	jobId: string;
+	type: string;
+	message: string;
+	data?: Record<string, unknown>;
+}
+
+export interface RuntimeCheckpoint {
+	version: number;
+	jobId: string;
+	status: string;
+	requirement: string;
+	currentTaskId?: string;
+	provider?: string;
+	resumeAt?: string;
+	lastError?: string;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface TaskGraphNode {
+	id: string;
+	title: string;
+	description: string;
+	status: string;
+	dependencies: string[];
+}
+
+export interface TaskGraph {
+	nodes: TaskGraphNode[];
+	edges: Array<{ from: string; to: string }>;
+}
+
+// --- Replay Types -------------------------------------------------------------
+
+export type ReplayMode = "inspect" | "simulate" | "reexecute";
+
+export interface ReplayRequest {
+	jobId: string;
+	mode: ReplayMode;
+	fromSequence?: number;
+	toSequence?: number;
+	allowExternalCalls: boolean;
+}
+
+export interface JobStateSnapshot {
+	jobId: string;
+	status: string;
+	currentTaskId?: string;
+	checkpoint: RuntimeCheckpoint;
+	taskGraph: TaskGraph;
+	events: RuntimeEvent[];
+	timestamp: string;
+}
+
+export interface ReplayEvent {
+	sequence: number;
+	timestamp: string;
+	type: string;
+	data: Record<string, unknown>;
+}
+
+export interface ReplayDivergence {
+	sequence: number;
+	reason: string;
+	expected?: unknown;
+	actual?: unknown;
+	severity: "info" | "warning" | "error";
+}
+
+export interface ReplayResult {
+	jobId: string;
+	reconstructedState: JobStateSnapshot;
+	timeline: ReplayEvent[];
+	divergences: ReplayDivergence[];
+	artifacts: string[];
+	replayedAt: string;
+}
+
+// --- Replay Sources -----------------------------------------------------------
+
+export interface ReplaySources {
+	checkpoint?: RuntimeCheckpoint;
+	events?: RuntimeEvent[];
+	taskGraph?: TaskGraph;
+	prompts?: Record<string, string>;
+	outputs?: Record<string, string>;
+	testResults?: Record<string, unknown>;
+	evaluation?: Record<string, unknown>;
+	repairs?: Record<string, unknown>;
+	knowledgeRefs?: string[];
+	/** Filter events by sequence range */
+	fromSequence?: number;
+	toSequence?: number;
+}
+
+// --- Divergence Detection -----------------------------------------------------
+
+export type DivergenceReason =
+	| "source_file_changed"
+	| "project_rules_changed"
+	| "provider_output_differs"
+	| "test_environment_changed"
+	| "required_artifact_missing"
+	| "runtime_version_differs";
+
+export interface DivergenceCheck {
+	type: DivergenceReason;
+	check: () => Promise<boolean>;
+	severity: "info" | "warning" | "error";
+}
+
+// --- Runtime Events -----------------------------------------------------------
+
+export type ReplayRuntimeEvent =
+	| { type: "replay.started"; jobId: string; mode: ReplayMode }
+	| { type: "replay.state.reconstructed"; jobId: string; sequence: number }
+	| { type: "replay.divergence.detected"; jobId: string; reason: string }
+	| { type: "replay.completed"; jobId: string };

package/packages/feedback-collector/src/collector.ts

@@ -0,0 +1,160 @@
+/**
+ * Feedback Collector — Core (RFC-0021)
+ */
+
+import type {
+	FeedbackBatch,
+	FeedbackCollectionConfig,
+	FeedbackFilter,
+	FeedbackItem,
+	FeedbackSentiment,
+	FeedbackSource,
+	FeedbackSummary,
+} from "./types.js";
+
+let _idCounter = 0;
+function nextId(): string {
+	return `fb-${Date.now()}-${++_idCounter}`;
+}
+
+function inferSentiment(message: string): FeedbackSentiment {
+	const lower = message.toLowerCase();
+	const positive = ["great", "excellent", "love", "perfect", "good", "helpful", "works", "amazing"];
+	const negative = ["bad", "wrong", "hate", "broken", "fail", "slow", "terrible", "bug", "error"];
+	if (positive.some((w) => lower.includes(w))) return "positive";
+	if (negative.some((w) => lower.includes(w))) return "negative";
+	return "neutral";
+}
+
+export class FeedbackCollector {
+	private items: FeedbackItem[] = [];
+	private batches: FeedbackBatch[] = [];
+	private config: Required<FeedbackCollectionConfig>;
+
+	constructor(config: FeedbackCollectionConfig = {}) {
+		this.config = {
+			retentionDays: config.retentionDays ?? 90,
+			autoCloseThreshold: config.autoCloseThreshold ?? 10,
+			anonymizeUserId: config.anonymizeUserId ?? false,
+		};
+	}
+
+		collect(source: FeedbackSource, message: string, metadata?: Record<string, unknown>): FeedbackItem {
+		const item: FeedbackItem = {
+			id: nextId(),
+			source,
+			sentiment: inferSentiment(message),
+			message,
+			status: "pending",
+			createdAt: new Date().toISOString(),
+			tags: (metadata?.tags as string[] | undefined) ?? [],
+			metadata,
+		};
+		this.items.push(item);
+		return item;
+	}
+
+	collectBatch(batch: FeedbackBatch): void {
+		for (const item of batch.items) {
+			if (!item.id) item.id = nextId();
+			if (!item.createdAt) item.createdAt = new Date().toISOString();
+			if (!item.sentiment) item.sentiment = inferSentiment(item.message);
+			if (!item.status) item.status = "pending";
+			this.items.push(item);
+		}
+		this.batches.push(batch);
+	}
+
+	query(filter?: FeedbackFilter): FeedbackItem[] {
+		let results = [...this.items];
+		if (!filter) return results;
+
+		if (filter.source) results = results.filter((i) => i.source === filter.source);
+		if (filter.sentiment) results = results.filter((i) => i.sentiment === filter.sentiment);
+		if (filter.status) results = results.filter((i) => i.status === filter.status);
+		if (filter.tags?.length) {
+			results = results.filter((i) => filter.tags!.some((t) => i.tags?.includes(t)));
+		}
+		if (filter.since) {
+			results = results.filter((i) => (i.createdAt ?? "") >= filter.since!);
+		}
+		if (filter.until) {
+			results = results.filter((i) => (i.createdAt ?? "") <= filter.until!);
+		}
+
+		return results;
+	}
+
+	summary(filter?: FeedbackFilter): FeedbackSummary {
+		const items = this.query(filter);
+		const total = items.length;
+		const bySource: Record<FeedbackSource, number> = {
+			human: 0,
+			automated: 0,
+			system: 0,
+			user: 0,
+		};
+		const bySentiment: Record<FeedbackSentiment, number> = {
+			positive: 0,
+			neutral: 0,
+			negative: 0,
+		};
+		let scoreSum = 0;
+		let scoreCount = 0;
+
+		for (const item of items) {
+			bySource[item.source] = (bySource[item.source] ?? 0) + 1;
+			if (item.sentiment) {
+				bySentiment[item.sentiment] = (bySentiment[item.sentiment] ?? 0) + 1;
+			}
+			if (item.score !== undefined) {
+				scoreSum += item.score;
+				scoreCount++;
+			}
+		}
+
+		return {
+			total,
+			bySource,
+			bySentiment,
+			avgScore: scoreCount > 0 ? scoreSum / scoreCount : 0,
+			pending: items.filter((i) => i.status === "pending").length,
+		};
+	}
+
+	updateStatus(id: string, status: FeedbackItem["status"]): boolean {
+		const item = this.items.find((i) => i.id === id);
+		if (!item) return false;
+		item.status = status;
+		if (status === "actioned" || status === "dismissed") {
+			item.resolvedAt = new Date().toISOString();
+		}
+		return true;
+	}
+
+	resolve(id: string, status: "actioned" | "dismissed"): boolean {
+		return this.updateStatus(id, status);
+	}
+
+	autoCloseOld(): number {
+		const cutoff = Date.now() - this.config.retentionDays * 86_400_000;
+		let count = 0;
+		for (const item of this.items) {
+			const created = new Date(item.createdAt ?? Date.now()).getTime();
+			if (created < cutoff && item.status === "pending") {
+				item.status = "dismissed";
+				item.resolvedAt = new Date().toISOString();
+				count++;
+			}
+		}
+		return count;
+	}
+
+	count(): number {
+		return this.items.length;
+	}
+
+	listBatches(): FeedbackBatch[] {
+		return [...this.batches];
+	}
+}

package/packages/feedback-collector/src/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Feedback Collector — Main Entry (RFC-0021)
+ */
+
+export { FeedbackCollector } from "./collector.js";
+export type * from "./types.js";

package/packages/feedback-collector/src/types.ts

@@ -0,0 +1,51 @@
+/**
+ * Feedback Collector — Types (RFC-0021)
+ */
+
+export type FeedbackSource = "human" | "automated" | "system" | "user";
+export type FeedbackSentiment = "positive" | "neutral" | "negative";
+export type FeedbackStatus = "pending" | "reviewed" | "actioned" | "dismissed";
+
+export interface FeedbackItem {
+	id: string;
+	source: FeedbackSource;
+	sentiment?: FeedbackSentiment;
+	score?: number;
+	message: string;
+	targetId?: string;
+	tags?: string[];
+	status: FeedbackStatus;
+	createdAt?: string;
+	resolvedAt?: string;
+	metadata?: Record<string, unknown>;
+}
+
+export interface FeedbackBatch {
+	id: string;
+	items: FeedbackItem[];
+	source: FeedbackSource;
+	receivedAt: string;
+}
+
+export interface FeedbackSummary {
+	total: number;
+	bySource: Record<FeedbackSource, number>;
+	bySentiment: Record<FeedbackSentiment, number>;
+	avgScore: number;
+	pending: number;
+}
+
+export interface FeedbackFilter {
+	source?: FeedbackSource;
+	sentiment?: FeedbackSentiment;
+	status?: FeedbackStatus;
+	tags?: string[];
+	since?: string;
+	until?: string;
+}
+
+export interface FeedbackCollectionConfig {
+	retentionDays?: number;
+	autoCloseThreshold?: number;
+	anonymizeUserId?: boolean;
+}