pi-crew 0.9.68 → 0.10.2

package/src/observability/exporters/prometheus-exporter.ts

@@ -1,54 +0,0 @@
-import type { HistogramPoint, MetricLabels, MetricPoint, MetricSnapshot } from "../metrics-primitives.ts";
-
-function prometheusName(name: string): string {
-	return name.replace(/[^a-zA-Z0-9_:]/g, "_").replace(/^[0-9]/, "_$&");
-}
-
-function escapeLabel(value: string): string {
-	return value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, '\\"');
-}
-
-function labelsText(labels: MetricLabels): string {
-	const entries = Object.entries(labels);
-	if (!entries.length) return "";
-	return `{${entries.map(([key, value]) => `${key}="${escapeLabel(String(value))}"`).join(",")}}`;
-}
-
-function metricType(type: MetricSnapshot["type"]): string {
-	return type === "histogram" ? "histogram" : type === "gauge" ? "gauge" : "counter";
-}
-
-function isHistogramPoint(value: MetricPoint | HistogramPoint): value is HistogramPoint {
-	return "buckets" in value && "counts" in value;
-}
-
-function formatPrometheusValue(num: number): string {
-	if (Number.isNaN(num)) return "Nan";
-	if (num === Number.POSITIVE_INFINITY) return "+Inf";
-	if (num === Number.NEGATIVE_INFINITY) return "-Inf";
-	return String(num);
-}
-
-export function formatPrometheus(snapshots: MetricSnapshot[]): string {
-	const lines: string[] = [];
-	for (const snapshot of snapshots) {
-		const name = prometheusName(snapshot.name);
-		lines.push(`# HELP ${name} ${snapshot.description}`);
-		lines.push(`# TYPE ${name} ${metricType(snapshot.type)}`);
-		for (const value of snapshot.values) {
-			if (isHistogramPoint(value)) {
-				let cumulative = 0;
-				for (let index = 0; index < value.buckets.length; index += 1) {
-					cumulative += value.counts[index] ?? 0;
-					const le = Number.isFinite(value.buckets[index]) ? String(value.buckets[index]) : "+Inf";
-					lines.push(`${name}_bucket${labelsText({ ...value.labels, le })} ${cumulative}`);
-				}
-				lines.push(`${name}_sum${labelsText(value.labels)} ${value.sum}`);
-				lines.push(`${name}_count${labelsText(value.labels)} ${value.count}`);
-			} else {
-				lines.push(`${name}${labelsText(value.labels)} ${formatPrometheusValue(value.value)}`);
-			}
-		}
-	}
-	return `${lines.join("\n")}\n`;
-}

package/src/observability/metric-retention.ts

@@ -1,64 +0,0 @@
-import { labelKey, type MetricLabels } from "./metrics-primitives.ts";
-
-interface WindowEvent {
-	timestamp: number;
-	labels: MetricLabels;
-	delta: number;
-}
-
-export class TimeWindowedCounter {
-	private events: WindowEvent[] = [];
-	private readonly windowMs: number;
-	private readonly now: () => number;
-	private static readonly MAX_EVENTS = 100_000;
-
-	constructor(windowMs = 3_600_000, now: () => number = () => Date.now()) {
-		this.windowMs = windowMs;
-		this.now = now;
-	}
-
-	inc(labels: MetricLabels = {}, delta = 1): void {
-		if (!Number.isFinite(delta)) return;
-		// Cap the event array to prevent unbounded memory growth.
-		if (this.events.length >= TimeWindowedCounter.MAX_EVENTS) this.prune();
-		this.events.push({
-			timestamp: this.now(),
-			labels: { ...labels },
-			delta,
-		});
-		this.prune();
-	}
-
-	// PERF (OBS-5): This method is O(N) per call because it linearly scans
-	// all events and calls labelKey() (which uses JSON.stringify) on each.
-	// A more efficient aggregation (e.g., pre-aggregated label buckets or a
-	// sliding-window histogram) is planned to replace this hot path.
-	count(labels: MetricLabels = {}, durationMs = this.windowMs): number {
-		const now = this.now();
-		this.pruneAt(now);
-		const key = labelKey(labels);
-		const cutoff = now - durationMs;
-		return this.events
-			.filter((event) => event.timestamp >= cutoff && labelKey(event.labels) === key)
-			.reduce((sum, event) => sum + event.delta, 0);
-	}
-
-	rate(labels: MetricLabels = {}, durationMs = this.windowMs): number {
-		if (durationMs <= 0) return 0;
-		return this.count(labels, durationMs) / (durationMs / 1000);
-	}
-
-	size(): number {
-		this.prune();
-		return this.events.length;
-	}
-
-	private prune(): void {
-		this.pruneAt(this.now());
-	}
-
-	private pruneAt(now: number): void {
-		const cutoff = now - this.windowMs;
-		this.events = this.events.filter((event) => event.timestamp >= cutoff);
-	}
-}

package/src/runtime/compaction/compaction-summary.ts

@@ -1,278 +0,0 @@
-/**
- * Deterministic compaction summary — builds a markdown summary of a pi-crew run
- * from manifest.json, tasks.json, and the tail of events.jsonl.
- *
- * Distilled from pi-autoresearch's compaction-summary pattern.
- */
-
-class GiantLineFallbackError extends Error {
-	constructor() {
-		super("GIANT_LINE_FALLBACK");
-		this.name = "GiantLineFallbackError";
-	}
-}
-
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { readJsonFile } from "../../state/atomic-write.ts";
-import type { TeamEvent } from "../../state/event-log/event-log.ts";
-import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
-
-/** Maximum number of events to read from the tail of events.jsonl. */
-const MAX_TAIL_EVENTS = 100;
-
-/** Maximum number of completed tasks to include in the "Recent Results" section. */
-const MAX_RECENT_RESULTS = 10;
-
-/** Paths relevant to building a compaction summary for a run. */
-export interface SummaryPaths {
-	manifestPath: string;
-	tasksPath: string;
-	eventsPath: string;
-	stateRoot: string;
-}
-
-/**
- * Derive the standard summary-relevant paths from a state root directory.
- * Mirrors pi-autoresearch's `autoresearchSummaryPathsFor()`.
- */
-export function summaryPathsFor(stateRoot: string): SummaryPaths {
-	return {
-		stateRoot,
-		manifestPath: path.join(stateRoot, "manifest.json"),
-		tasksPath: path.join(stateRoot, "tasks.json"),
-		eventsPath: path.join(stateRoot, "events.jsonl"),
-	};
-}
-
-/**
- * Read the last N lines from a text file.
- * Uses reverse buffer reading to avoid loading the entire file into memory.
- * For files larger than TAIL_MAX_READ bytes, only the last chunk is read.
- */
-const TAIL_MAX_READ = 256 * 1024; // 256KB — enough for ~1000 lines of JSONL
-const MAX_FALLBACK_READ = 2 * 1024 * 1024; // 2MB — safety limit for giant-line fallback
-function readTailLines(filePath: string, maxLines: number): string[] {
-	if (!fs.existsSync(filePath)) return [];
-	try {
-		const stat = fs.statSync(filePath);
-		const fileSize = stat.size;
-		if (fileSize === 0) return [];
-
-		// For small files, just read everything
-		if (fileSize <= TAIL_MAX_READ) {
-			const content = fs.readFileSync(filePath, "utf-8");
-			return content
-				.split("\n")
-				.filter((line) => line.trim().length > 0)
-				.slice(-maxLines);
-		}
-
-		// For large files, read only the last chunk.
-		// Search backwards from the read boundary for a newline to avoid
-		// splitting mid-line or mid-multibyte UTF-8 character.
-		const fd = fs.openSync(filePath, "r");
-		try {
-			const readSize = Math.min(fileSize, TAIL_MAX_READ);
-			const readOffset = fileSize - readSize;
-			const buf = Buffer.alloc(readSize);
-			fs.readSync(fd, buf, 0, readSize, readOffset);
-
-			// Find the first newline in the buffer to avoid partial lines.
-			// This also handles multibyte UTF-8 safety — we start after a
-			// newline boundary which is always a clean character boundary.
-			let start = 0;
-			if (readOffset > 0) {
-				const firstNewline = buf.indexOf("\n");
-				if (firstNewline >= 0) {
-					start = firstNewline + 1;
-				} else {
-					// No newline found in the entire tail chunk — single giant line.
-					// Fall back to reading the full file to avoid data loss.
-					// Note: fd will be closed by the outer finally block.
-					throw new GiantLineFallbackError();
-				}
-			}
-
-			const content = buf.toString("utf-8", start, readSize);
-			const lines = content.split("\n").filter((line) => line.trim().length > 0);
-			return lines.slice(-maxLines);
-		} finally {
-			fs.closeSync(fd);
-		}
-	} catch (err) {
-		// Giant-line fallback: fd already closed by finally above.
-		if (err instanceof GiantLineFallbackError) {
-			const stat = fs.statSync(filePath);
-			if (stat.size > MAX_FALLBACK_READ) return [];
-			const content = fs.readFileSync(filePath, "utf-8");
-			return content
-				.split("\n")
-				.filter((line) => line.trim().length > 0)
-				.slice(-maxLines);
-		}
-		return [];
-	}
-}
-
-/**
- * Parse JSONL lines into TeamEvent objects, skipping malformed lines.
- */
-function parseEvents(lines: string[]): TeamEvent[] {
-	const events: TeamEvent[] = [];
-	for (const line of lines) {
-		try {
-			const parsed = JSON.parse(line.trim());
-			if (typeof parsed === "object" && parsed !== null && typeof parsed.type === "string" && typeof parsed.runId === "string") {
-				events.push(parsed as TeamEvent);
-			}
-		} catch {
-			// Skip malformed lines
-		}
-	}
-	return events;
-}
-
-/**
- * Compute a human-readable duration between two ISO timestamp strings.
- */
-function formatDuration(startIso?: string, endIso?: string): string {
-	if (!startIso) return "—";
-	const start = new Date(startIso).getTime();
-	if (Number.isNaN(start)) return "—";
-	const end = endIso ? new Date(endIso).getTime() : Date.now();
-	if (Number.isNaN(end)) return "—";
-	const diffMs = end - start;
-	if (diffMs < 0) return "—";
-	const seconds = Math.floor(diffMs / 1000);
-	if (seconds < 60) return `${seconds}s`;
-	const minutes = Math.floor(seconds / 60);
-	const remainingSeconds = seconds % 60;
-	if (minutes < 60) return `${minutes}m ${remainingSeconds}s`;
-	const hours = Math.floor(minutes / 60);
-	const remainingMinutes = minutes % 60;
-	return `${hours}h ${remainingMinutes}m`;
-}
-
-/**
- * Build a deterministic compaction summary for a pi-crew run.
- *
- * Reads manifest.json, tasks.json, and the tail of events.jsonl to produce
- * a self-contained markdown summary suitable for context injection.
- *
- * @param stateRoot - Path to the run's state root directory
- * @returns Markdown-formatted compaction summary
- */
-export function buildCompactionSummary(stateRoot: string): string {
-	const paths = summaryPathsFor(stateRoot);
-
-	// Read manifest
-	const manifest = readJsonFile<TeamRunManifest>(paths.manifestPath);
-
-	// Read tasks
-	const tasks = readJsonFile<TeamTaskState[]>(paths.tasksPath) ?? [];
-
-	// Read tail events
-	const tailLines = readTailLines(paths.eventsPath, MAX_TAIL_EVENTS);
-	const tailEvents = parseEvents(tailLines);
-
-	const sections: string[] = [];
-
-	// Section: Run Metadata
-	sections.push("# Run Summary");
-	if (manifest) {
-		sections.push("");
-		sections.push("## Run Metadata");
-		sections.push(`- **Run ID**: ${manifest.runId}`);
-		sections.push(`- **Team**: ${manifest.team}`);
-		if (manifest.workflow) {
-			sections.push(`- **Workflow**: ${manifest.workflow}`);
-		}
-		if (manifest.goal) {
-			sections.push(`- **Goal**: ${manifest.goal.replace(/\n/g, " ").slice(0, 500)}`);
-		}
-		sections.push(`- **Status**: ${manifest.status}`);
-		sections.push(`- **Created**: ${manifest.createdAt}`);
-		sections.push(`- **Updated**: ${manifest.updatedAt}`);
-		if (manifest.workspaceMode) {
-			sections.push(`- **Workspace Mode**: ${manifest.workspaceMode}`);
-		}
-	} else {
-		sections.push("");
-		sections.push("## Run Metadata");
-		sections.push("- **Status**: manifest unavailable");
-	}
-
-	// Section: Task Progress Table
-	sections.push("");
-	sections.push("## Task Progress");
-	if (tasks.length > 0) {
-		sections.push("");
-		sections.push("| ID | Role | Status | Duration |");
-		sections.push("|---|---|---|---|");
-		for (const task of tasks) {
-			const taskId = task.id;
-			const role = task.role || "—";
-			const status = task.status || "—";
-			const duration = formatDuration(task.startedAt, task.finishedAt);
-			sections.push(`| ${taskId} | ${role} | ${status} | ${duration} |`);
-		}
-	} else {
-		sections.push("");
-		sections.push("No tasks recorded.");
-	}
-
-	// Section: Recent Task Results
-	const completedTasks = tasks.filter((t) => t.status === "completed" || t.status === "failed").slice(-MAX_RECENT_RESULTS);
-
-	if (completedTasks.length > 0) {
-		sections.push("");
-		sections.push("## Recent Task Results");
-		for (const task of completedTasks) {
-			sections.push("");
-			sections.push(`### ${task.id} (${task.status})`);
-			if (task.error) {
-				sections.push(`- **Error**: ${task.error}`);
-			}
-			if (task.diagnostics && Object.keys(task.diagnostics).length > 0) {
-				sections.push("- **Diagnostics**:");
-				for (const [key, value] of Object.entries(task.diagnostics)) {
-					sections.push(`  - ${key}: ${JSON.stringify(value)}`);
-				}
-			}
-			if (task.metrics && Object.keys(task.metrics).length > 0) {
-				sections.push("- **Metrics**:");
-				for (const [key, value] of Object.entries(task.metrics)) {
-					sections.push(`  - ${key}: ${value}`);
-				}
-			}
-		}
-	}
-
-	// Section: Next Steps (pending/queued tasks)
-	const pendingStatuses = new Set(["queued", "waiting", "running"]);
-	const pendingTasks = tasks.filter((t) => pendingStatuses.has(t.status));
-	if (pendingTasks.length > 0) {
-		sections.push("");
-		sections.push("## Next Steps");
-		sections.push("");
-		for (const task of pendingTasks) {
-			const title = task.title || task.role || "Untitled";
-			sections.push(`- [${task.status}] ${task.id}: ${title}`);
-		}
-	}
-
-	// Section: Tail Events Summary
-	if (tailEvents.length > 0) {
-		sections.push("");
-		sections.push(`## Recent Events (last ${tailEvents.length})`);
-		sections.push("");
-		for (const event of tailEvents.slice(-10)) {
-			const taskPart = event.taskId ? ` task=${event.taskId}` : "";
-			const msgPart = event.message ? ` — ${event.message}` : "";
-			sections.push(`- [${event.time}] ${event.type}${taskPart}${msgPart}`);
-		}
-	}
-
-	return sections.join("\n");
-}

package/src/runtime/errors/crew-errors.ts

@@ -1,162 +0,0 @@
-/**
- * crew-errors.ts — Typed error sentinels for pi-crew operations.
- *
- * Based on oh-my-pi pattern from compaction/errors.ts.
- * Uses `instanceof` discrimination instead of string matching.
- *
- * NOTE: Constructor parameters are explicit properties (not TypeScript
- * parameter properties) for strip-types compatibility.
- *
- * The `name` property is not set on instances because JavaScript's `name`
- * on functions is special and can't be overridden. Use `instanceof` checks
- * or the `code` property for discrimination.
- */
-
-/** Base class for all pi-crew errors. */
-export abstract class CrewError extends Error {
-	abstract readonly code: string;
-
-	/** Returns the class name. Use `instanceof` for discrimination. */
-	toString(): string {
-		return `[${this.constructor.name}] ${this.message}`;
-	}
-}
-
-/** Raised when a crew run is explicitly cancelled by user or API. */
-export class CrewCancelledError extends CrewError {
-	readonly code = "CREW_CANCELLED";
-	constructor(message = "Crew run cancelled") {
-		super(message);
-	}
-}
-
-/** Raised when a crew run exceeds its configured maximum duration. */
-export class CrewTimeoutError extends CrewError {
-	readonly code = "CREW_TIMEOUT";
-	readonly maxDurationMs: number;
-	constructor(maxDurationMs: number, message?: string) {
-		super(message ?? `Crew run exceeded timeout of ${maxDurationMs}ms`);
-		this.maxDurationMs = maxDurationMs;
-	}
-}
-
-/**
- * Raised when an individual agent in a crew goes deadletter — i.e. it
- * encountered an unrecoverable error that blocks its task from completing.
- * Common causes: crash, OOM, unhandled exception in tool execution.
- */
-export class CrewDeadletterError extends CrewError {
-	readonly code = "CREW_DEADLETTER";
-	readonly agentId: string;
-	readonly reason: string;
-	constructor(agentId: string, reason: string, message?: string) {
-		super(message ?? `Agent ${agentId} deadlettered: ${reason}`);
-		this.agentId = agentId;
-		this.reason = reason;
-	}
-}
-
-/** Raised when a crew run is aborted — operator Esc, SIGINT, or similar. */
-export class CrewAbortError extends CrewError {
-	readonly code = "CREW_ABORT";
-	constructor(message = "Crew run aborted") {
-		super(message);
-	}
-}
-
-/** Raised when a manifest or task file is malformed or missing required fields. */
-export class CrewManifestError extends CrewError {
-	readonly code = "CREW_MANIFEST_ERROR";
-	readonly runId?: string;
-	readonly taskId?: string;
-	constructor(message: string, runId?: string, taskId?: string) {
-		super(message);
-		this.runId = runId;
-		this.taskId = taskId;
-	}
-}
-
-/** Raised when a lock cannot be acquired or is held by a stale process. */
-export class CrewLockError extends CrewError {
-	readonly code = "CREW_LOCK_ERROR";
-	readonly lockPath?: string;
-	constructor(message: string, lockPath?: string) {
-		super(message);
-		this.lockPath = lockPath;
-	}
-}
-
-/** Raised when an agent exceeds its turn limit. */
-export class CrewTurnLimitError extends CrewError {
-	readonly code = "CREW_TURN_LIMIT";
-	readonly agentId: string;
-	readonly maxTurns: number;
-	constructor(agentId: string, maxTurns: number) {
-		super(`Agent ${agentId} exceeded turn limit of ${maxTurns}`);
-		this.agentId = agentId;
-		this.maxTurns = maxTurns;
-	}
-}
-
-/** Raised when a workflow step gate condition is not met. */
-export class CrewGateError extends CrewError {
-	readonly code = "CREW_GATE_ERROR";
-	readonly gateName: string;
-	constructor(gateName: string, message: string) {
-		super(message);
-		this.gateName = gateName;
-	}
-}
-
-/** Raised when an agent session fails to initialize (e.g. model not found). */
-export class CrewSessionError extends CrewError {
-	readonly code = "CREW_SESSION_ERROR";
-	readonly agentId?: string;
-	constructor(message: string, agentId?: string) {
-		super(message);
-		this.agentId = agentId;
-	}
-}
-
-/**
- * Outcome of a crew run attempt.
- * Used by RunTracker and health monitoring for outcome classification.
- */
-export type CrewRunOutcome =
-	| "ok" // Completed successfully
-	| "cancelled" // Explicitly cancelled by user or API
-	| "deadletter" // Agent encountered unrecoverable error
-	| "failed" // Workflow step failed (gate error, etc.)
-	| "timeout" // Exceeded max duration
-	| "aborted"; // Operator interrupt (Esc, SIGINT)
-
-/**
- * Classify a thrown error into a CrewRunOutcome.
- * Useful in catch blocks that need to determine run outcome.
- */
-export function classifyError(error: unknown): CrewRunOutcome {
-	if (error instanceof CrewCancelledError) return "cancelled";
-	if (error instanceof CrewTimeoutError) return "timeout";
-	if (error instanceof CrewDeadletterError) return "deadletter";
-	if (error instanceof CrewAbortError) return "aborted";
-	if (error instanceof CrewGateError) return "failed";
-	if (error instanceof CrewError) return "failed";
-	// Unknown errors → failed
-	return "failed";
-}
-
-/**
- * Check if an error indicates the run was intentionally interrupted
- * (cancelled, aborted, or timed out) vs a genuine failure.
- */
-export function isInterruptError(error: unknown): boolean {
-	return error instanceof CrewCancelledError || error instanceof CrewAbortError || error instanceof CrewTimeoutError;
-}
-
-/**
- * Check if an error indicates the run failed due to agent malfunction
- * rather than workflow logic or user action.
- */
-export function isAgentError(error: unknown): boolean {
-	return error instanceof CrewDeadletterError || error instanceof CrewTurnLimitError || error instanceof CrewSessionError;
-}