pi-crew 0.9.68 → 0.10.1

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;
-}

package/src/runtime/live-session/intercom-bridge.ts

@@ -1,187 +0,0 @@
-/**
- * Intercom bridge — workers can escalate questions to the orchestrator.
- *
- * Pattern origin: pi-subagents/src/intercom-bridge.ts — contact_supervisor tool
- * for child agents to escalate decisions, report progress, or ask questions.
- *
- * This module provides the message queue and correlation logic.
- * The actual tool registration happens in task-runner.ts.
- */
-
-// ── Types ────────────────────────────────────────────────────────────────
-
-export type IntercomUrgency = "low" | "medium" | "high" | "critical";
-export type IntercomType = "question" | "escalation" | "progress" | "block";
-
-export interface IntercomMessage {
-	type: IntercomType;
-	taskStepId: string;
-	content: string;
-	urgency: IntercomUrgency;
-	timestamp: number;
-	timeout?: number; // ms to wait for response
-}
-
-export interface IntercomResponse {
-	answer: string;
-	source: "orchestrator" | "human" | "timeout";
-	timestamp: number;
-	messageId: string;
-}
-
-// ── Message Queue ────────────────────────────────────────────────────────
-
-interface PendingMessage {
-	message: IntercomMessage;
-	id: string;
-	resolve: (response: IntercomResponse) => void;
-	timer?: ReturnType<typeof setTimeout>;
-}
-
-const MAX_QUEUE_SIZE = 100;
-
-/**
- * In-process intercom queue for worker→orchestrator communication.
- *
- * Each message gets a unique ID. Callers await a response via a Promise.
- * If no response arrives within the timeout, resolves with source="timeout".
- */
-export class IntercomQueue {
-	private pending = new Map<string, PendingMessage>();
-	private queue: IntercomMessage[] = [];
-	/** Monotonic sequence counter — guarantees unique IDs even when many
-	 * messages enqueue within the same millisecond (avoids Date.now()
-	 * collision + weak Math.random birthday-paradox flakes under load). */
-	private seq = 0;
-
-	/**
-	 * Enqueue a message and return a promise that resolves when the
-	 * orchestrator responds (or times out).
-	 */
-	enqueue(message: IntercomMessage): Promise<IntercomResponse> {
-		if (this.pending.size >= MAX_QUEUE_SIZE) {
-			// Evict oldest
-			const firstKey = this.pending.keys().next().value;
-			if (firstKey) this.evict(firstKey, "queue_full");
-		}
-
-		const id = `icm-${Date.now().toString(36)}-${(this.seq++).toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
-
-		return new Promise<IntercomResponse>((resolve) => {
-			const entry: PendingMessage = { message, id, resolve };
-
-			// Set timeout if specified
-			if (message.timeout && message.timeout > 0) {
-				entry.timer = setTimeout(() => {
-					resolve({
-						answer: "No response received within timeout",
-						source: "timeout",
-						timestamp: Date.now(),
-						messageId: id,
-					});
-					this.pending.delete(id);
-				}, message.timeout);
-				// Defense in depth: never let a pending-message timer block
-				// process exit. The timer is cleared via respond()/evict() in
-				// the normal case; .unref() ensures shutdown isn't blocked if
-				// the queue is abandoned.
-				if (entry.timer && typeof entry.timer.unref === "function") {
-					entry.timer.unref();
-				}
-			}
-
-			this.pending.set(id, entry);
-			this.queue.push({ ...message });
-		});
-	}
-
-	/**
-	 * Respond to a pending message by ID.
-	 */
-	respond(messageId: string, answer: string, source: "orchestrator" | "human" = "orchestrator"): boolean {
-		const entry = this.pending.get(messageId);
-		if (!entry) return false;
-
-		if (entry.timer) clearTimeout(entry.timer);
-
-		entry.resolve({
-			answer,
-			source,
-			timestamp: Date.now(),
-			messageId,
-		});
-
-		this.pending.delete(messageId);
-		return true;
-	}
-
-	/**
-	 * Get all pending messages (for orchestrator to process).
-	 */
-	getPending(): Array<IntercomMessage & { id: string }> {
-		return [...this.pending.entries()].map(([id, entry]) => ({
-			...entry.message,
-			id,
-		}));
-	}
-
-	/**
-	 * Number of pending messages awaiting response.
-	 */
-	get pendingCount(): number {
-		return this.pending.size;
-	}
-
-	/**
-	 * Clean up all pending messages (e.g., on run completion).
-	 */
-	clear(): void {
-		for (const [id, entry] of this.pending) {
-			this.evict(id, "run_complete");
-		}
-		this.queue = [];
-	}
-
-	private evict(id: string, reason: string): void {
-		const entry = this.pending.get(id);
-		if (!entry) return;
-
-		if (entry.timer) clearTimeout(entry.timer);
-
-		entry.resolve({
-			answer: `Message evicted: ${reason}`,
-			source: "timeout",
-			timestamp: Date.now(),
-			messageId: id,
-		});
-
-		this.pending.delete(id);
-	}
-}
-
-// ── Singleton per run ────────────────────────────────────────────────────
-
-const queues = new Map<string, IntercomQueue>();
-
-/**
- * Get or create an intercom queue for a run.
- */
-export function getIntercomQueue(runId: string): IntercomQueue {
-	let queue = queues.get(runId);
-	if (!queue) {
-		queue = new IntercomQueue();
-		queues.set(runId, queue);
-	}
-	return queue;
-}
-
-/**
- * Clean up intercom queue for a completed run.
- */
-export function cleanupIntercomQueue(runId: string): void {
-	const queue = queues.get(runId);
-	if (queue) {
-		queue.clear();
-		queues.delete(runId);
-	}
-}

package/src/runtime/loop-gates.ts

@@ -1,128 +0,0 @@
-/**
- * Dual-gate loop control — determines whether a task should auto-resume
- * based on meaningful progress and turn limits.
- *
- * Gate 1: At least one signal of meaningful progress must be true.
- * Gate 2: The auto-resume turn count must be below the maximum.
- *
- * Distilled from pi-autoresearch's dual-gate loop pattern.
- */
-import * as fs from "node:fs";
-import type { TeamTaskState } from "../state/types.ts";
-
-/**
- * Signal indicating what kind of progress a task has made.
- */
-export interface TaskProgressSignal {
-	/** Whether the task has edited files or produced non-empty results. */
-	editedFiles: boolean;
-	/** Whether the task has produced artifacts in the artifacts directory. */
-	producedArtifacts: boolean;
-	/** Whether the task has run tests (detected via result text). */
-	ranTests: boolean;
-}
-
-/**
- * Runtime state for auto-resume turn tracking.
- */
-export interface AutoResumeRuntime {
-	/** Current number of auto-resume turns taken. */
-	autoResumeTurns: number;
-	/** Maximum allowed auto-resume turns. */
-	maxTurns: number;
-}
-
-/** Keywords in result text that indicate tests were run. */
-const TEST_KEYWORDS = [
-	"test passed",
-	"test failed",
-	"tests passed",
-	"tests failed",
-	"test results",
-	"jest",
-	"vitest",
-	"mocha",
-	"pytest",
-	"npx test",
-	"npm test",
-	"cargo test",
-	"all tests",
-	"test suite",
-	"✓",
-	"✗",
-	"PASS ",
-	" FAIL ",
-] as const;
-
-/**
- * Determine whether a task should auto-resume based on dual-gate logic.
- *
- * Gate 1 (meaningful progress): at least one of editedFiles, producedArtifacts,
- *   or ranTests must be true.
- * Gate 2 (turn limit): autoResumeTurns must be strictly less than maxTurns.
- *
- * Both gates must pass for auto-resume to be allowed.
- */
-export function shouldAutoResume(runtime: AutoResumeRuntime, taskProgress: TaskProgressSignal): boolean {
-	// Gate 2: Turn limit check (check first — cheaper)
-	if (runtime.autoResumeTurns >= runtime.maxTurns) {
-		return false;
-	}
-
-	// Gate 1: Meaningful progress check
-	const hasProgress = taskProgress.editedFiles || taskProgress.producedArtifacts || taskProgress.ranTests;
-	if (!hasProgress) {
-		return false;
-	}
-
-	return true;
-}
-
-/**
- * Compute the task progress signal from a task's state and artifacts directory.
- *
- * - editedFiles: true if task has artifact files or a non-empty result
- * - producedArtifacts: true if artifacts directory contains task-specific files
- * - ranTests: true if result text contains test-related keywords
- *
- * @param task - The task state to analyze
- * @param artifactsDir - Path to the artifacts directory
- * @returns TaskProgressSignal indicating what progress was made
- */
-export function computeTaskProgressSignal(task: TeamTaskState, artifactsDir: string): TaskProgressSignal {
-	// editedFiles: check if task has artifact descriptors or a non-empty result
-	const hasResultArtifact = task.resultArtifact !== undefined;
-	const hasNonEmptyResult = task.resultArtifact?.path !== undefined;
-	const editedFiles = hasResultArtifact || hasNonEmptyResult;
-
-	// producedArtifacts: check artifacts directory for task-specific files
-	let producedArtifacts = false;
-	if (artifactsDir && fs.existsSync(artifactsDir)) {
-		try {
-			const entries = fs.readdirSync(artifactsDir);
-			// Look for files/directories that START with the task ID prefix.
-			// Using startsWith instead of includes to avoid false positives
-			// from short task IDs like "01" matching unrelated entries.
-			const taskPrefix = task.id.replace(/[^a-zA-Z0-9_-]/g, "");
-			producedArtifacts = entries.some((entry) => {
-				const baseName = entry.split(".")[0] ?? entry;
-				return baseName.startsWith(taskPrefix);
-			});
-		} catch {
-			producedArtifacts = false;
-		}
-	}
-
-	// ranTests: check if result-related fields contain test keywords
-	let ranTests = false;
-	const textToSearch = [
-		task.error ?? "",
-		task.terminalEvidence ? JSON.stringify(task.terminalEvidence) : "",
-		task.diagnostics ? JSON.stringify(task.diagnostics) : "",
-	].join(" ");
-
-	const lowerText = textToSearch.toLowerCase();
-	ranTests = TEST_KEYWORDS.some((keyword) => lowerText.includes(keyword.toLowerCase()));
-
-	return { editedFiles, producedArtifacts, ranTests };
-}

package/src/runtime/metric-parser.ts

@@ -1,36 +0,0 @@
-/**
- * Metric names that are denied to prevent prototype pollution.
- */
-export const DENIED_METRIC_NAMES: ReadonlySet<string> = new Set(["__proto__", "constructor", "prototype"]);
-
-const METRIC_LINE_RE = /^CREW_METRIC\s+(\w+)=(\S+)$/;
-
-/**
- * Parse CREW_METRIC lines from worker stdout.
- *
- * Lines must match the pattern: `CREW_METRIC name=value`
- * - `name` must be a word character sequence (alphanumeric + underscore)
- * - `value` must parse as a valid finite number
- * - Denied names (__proto__, constructor, prototype) are silently skipped
- *
- * @param output - Raw worker stdout text
- * @returns Map of metric name → numeric value
- */
-export function parseMetricLines(output: string): Record<string, number> {
-	const metrics: Record<string, number> = {};
-
-	for (const line of output.split("\n")) {
-		const match = METRIC_LINE_RE.exec(line);
-		if (!match) continue;
-
-		const [, name, rawValue] = match;
-		if (DENIED_METRIC_NAMES.has(name)) continue;
-
-		const value = Number(rawValue);
-		if (!Number.isFinite(value)) continue;
-
-		metrics[name] = value;
-	}
-
-	return metrics;
-}

package/src/runtime/output/stream-preview.ts

@@ -1,184 +0,0 @@
-// ─── Streaming Preview ───────────────────────────────────────────────────────
-// Captures incremental worker output during task execution for live preview.
-// Used by the UI layer to show partial results before task completion.
-
-import { TAIL_CAPTURE_STREAM_STAGE } from "../compaction/compact-stages/index.ts";
-import type { ParsedPiUsage } from "./pi-json-output.ts";
-
-export interface ToolCallPreview {
-	toolName: string;
-	inputPreview: string;
-	startedAt: number;
-}
-
-export interface StreamPreview {
-	taskId: string;
-	runId: string;
-	/** Cumulative text output captured so far */
-	textBuffer: string;
-	/** Current tool call in progress (if any) */
-	activeToolCall: ToolCallPreview | null;
-	/** Completed tool calls count */
-	toolCallCount: number;
-	/** Current turn number (incremented per assistant message) */
-	turnCount: number;
-	/** Token usage snapshot */
-	usage: Partial<ParsedPiUsage> | null;
-	/** Wall-clock start time */
-	startedAt: number;
-	/** Last update timestamp */
-	lastUpdatedAt: number;
-	/** Whether the task has completed */
-	finished: boolean;
-}
-
-export function createStreamPreview(taskId: string, runId: string): StreamPreview {
-	const now = Date.now();
-	return {
-		taskId,
-		runId,
-		textBuffer: "",
-		activeToolCall: null,
-		toolCallCount: 0,
-		turnCount: 0,
-		usage: null,
-		startedAt: now,
-		lastUpdatedAt: now,
-		finished: false,
-	};
-}
-
-/** Max text buffer size — drop oldest content when exceeded */
-const MAX_TEXT_BUFFER = 16_384;
-/** Max tool input preview length */
-const MAX_INPUT_PREVIEW = 512;
-
-const asRecord = (value: unknown): Record<string, unknown> | undefined =>
-	value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
-
-function truncateWithEllipsis(text: string, maxLength: number): string {
-	if (text.length <= maxLength) return text;
-	return text.slice(0, maxLength - 3) + "...";
-}
-
-function extractTextFromContent(content: unknown): string {
-	if (typeof content === "string") return content;
-	if (!Array.isArray(content)) return "";
-	const parts: string[] = [];
-	for (const part of content) {
-		const obj = asRecord(part);
-		if (!obj) continue;
-		if (obj.type === "text" && typeof obj.text === "string") parts.push(obj.text);
-		else if (typeof obj.content === "string") parts.push(obj.content);
-	}
-	return parts.join("");
-}
-
-/**
- * Feed a JSON event from Pi's stdout into the preview, updating it in place.
- * Returns true if the preview was modified.
- */
-export function feedJsonEvent(preview: StreamPreview, event: unknown): boolean {
-	const obj = asRecord(event);
-	if (!obj) return false;
-
-	let modified = false;
-	preview.lastUpdatedAt = Date.now();
-
-	// Detect tool calls
-	if (obj.type === "tool_call" || obj.type === "tool_use" || obj.type === "toolCall") {
-		const toolName = typeof obj.name === "string" ? obj.name : typeof obj.tool === "string" ? obj.tool : "unknown";
-		const rawInput = obj.input ?? obj.arguments ?? obj.params ?? "";
-		const inputStr = typeof rawInput === "string" ? rawInput : JSON.stringify(rawInput);
-		preview.activeToolCall = {
-			toolName,
-			inputPreview: truncateWithEllipsis(inputStr, MAX_INPUT_PREVIEW),
-			startedAt: Date.now(),
-		};
-		preview.toolCallCount++;
-		modified = true;
-	}
-
-	// Detect tool results (clear active tool call)
-	if (obj.type === "tool_result" || obj.type === "toolResult" || obj.type === "result") {
-		preview.activeToolCall = null;
-		modified = true;
-	}
-
-	// Detect assistant text output
-	const message = asRecord(obj.message);
-	if (message?.role === "assistant" || obj.role === "assistant") {
-		preview.turnCount++;
-		const text = extractTextFromContent(message?.content ?? obj.content);
-		if (text) {
-			const appended = preview.textBuffer.length > 0 ? preview.textBuffer + "\n" + text : text;
-			// Sprint 5: refactored onto the stage-chain. TAIL_CAPTURE_STREAM_STAGE
-			// is a 16_384-char tail-capture stage with no marker (the UI shows
-			// raw text without a prefix). It is bit-equivalent to the inline
-			// `appended.slice(appended.length - MAX_TEXT_BUFFER)` for inputs at
-			// or below the cap (returns verbatim) and equivalent for over-cap
-			// inputs (returns last MAX_TEXT_BUFFER chars).
-			preview.textBuffer = TAIL_CAPTURE_STREAM_STAGE.apply(appended);
-		}
-		modified = true;
-	}
-
-	// Detect direct text/final output
-	if (typeof obj.text === "string" && obj.text.trim()) {
-		const appended = preview.textBuffer.length > 0 ? preview.textBuffer + "\n" + obj.text : obj.text;
-		preview.textBuffer = TAIL_CAPTURE_STREAM_STAGE.apply(appended);
-		modified = true;
-	}
-
-	// Detect usage
-	const rawUsage = obj.usage ?? obj.tokenUsage ?? obj.tokens ?? obj.stats;
-	if (rawUsage && typeof rawUsage === "object") {
-		const u = asRecord(rawUsage);
-		if (u) {
-			preview.usage = {
-				input: typeof u.input === "number" ? u.input : preview.usage?.input,
-				output: typeof u.output === "number" ? u.output : preview.usage?.output,
-				cacheRead: typeof u.cacheRead === "number" ? u.cacheRead : preview.usage?.cacheRead,
-				cacheWrite: typeof u.cacheWrite === "number" ? u.cacheWrite : preview.usage?.cacheWrite,
-				cost: typeof u.cost === "number" ? u.cost : preview.usage?.cost,
-				turns: typeof u.turns === "number" ? u.turns : preview.usage?.turns,
-			};
-			modified = true;
-		}
-	}
-
-	return modified;
-}
-
-/** Mark preview as finished */
-export function finishStreamPreview(preview: StreamPreview): void {
-	preview.finished = true;
-	preview.activeToolCall = null;
-	preview.lastUpdatedAt = Date.now();
-}
-
-/** Render a compact one-line status for the preview */
-export function renderPreviewStatus(preview: StreamPreview): string {
-	const elapsed = Math.round((Date.now() - preview.startedAt) / 1000);
-	const parts: string[] = [];
-
-	if (preview.finished) {
-		parts.push("✓ done");
-	} else if (preview.activeToolCall) {
-		parts.push(`⚙ ${preview.activeToolCall.toolName}`);
-	} else {
-		parts.push("⟳ thinking");
-	}
-
-	parts.push(`T${preview.turnCount}`);
-	parts.push(`${preview.toolCallCount} tools`);
-
-	if (preview.usage?.input) {
-		const inK = Math.round(preview.usage.input / 1024);
-		parts.push(`${inK}k in`);
-	}
-
-	parts.push(`${elapsed}s`);
-
-	return parts.join(" | ");
-}