pi-crew 0.2.2 → 0.2.4

package/src/runtime/usage-tracker.ts

@@ -0,0 +1,71 @@
+import type { TeamRunManifest, TeamTaskState, UsageState } from "../state/types.ts";
+
+export interface LifetimeUsage {
+	input: number;
+	output: number;
+	cacheWrite: number;
+}
+
+export function emptyLifetimeUsage(): LifetimeUsage {
+	return { input: 0, output: 0, cacheWrite: 0 };
+}
+
+export function addUsage(into: LifetimeUsage, delta: { input?: number; output?: number; cacheWrite?: number }): void {
+	if (typeof delta.input === "number") into.input += delta.input;
+	if (typeof delta.output === "number") into.output += delta.output;
+	if (typeof delta.cacheWrite === "number") into.cacheWrite += delta.cacheWrite;
+}
+
+export function lifetimeUsageFromState(state: UsageState | undefined): LifetimeUsage {
+	if (!state) return emptyLifetimeUsage();
+	return {
+		input: state.input ?? 0,
+		output: state.output ?? 0,
+		cacheWrite: state.cacheWrite ?? 0,
+	};
+}
+
+export function usageStateFromLifetime(lifetime: LifetimeUsage): UsageState {
+	return {
+		input: lifetime.input,
+		output: lifetime.output,
+		cacheWrite: lifetime.cacheWrite,
+		cacheRead: 0,
+	};
+}
+
+const taskUsageMap = new Map<string, LifetimeUsage>();
+
+export function trackTaskUsage(taskId: string, delta: { input?: number; output?: number; cacheWrite?: number }): void {
+	const existing = taskUsageMap.get(taskId) ?? emptyLifetimeUsage();
+	addUsage(existing, delta);
+	taskUsageMap.set(taskId, existing);
+}
+
+export function getTrackedTaskUsage(taskId: string): LifetimeUsage {
+	return taskUsageMap.get(taskId) ?? emptyLifetimeUsage();
+}
+
+export function clearTrackedTaskUsage(taskId: string): void {
+	taskUsageMap.delete(taskId);
+}
+
+export function clearAllTrackedTaskUsage(): void {
+	taskUsageMap.clear();
+}
+
+// Aliases for public API
+export const getTaskUsage = getTrackedTaskUsage;
+export const getRunUsage = getTrackedTaskUsage;
+export const clearAllTaskUsage = clearAllTrackedTaskUsage;
+
+export function aggregateTrackedUsageForRun(manifest: TeamRunManifest, tasks: TeamTaskState[]): UsageState {
+	const total = emptyLifetimeUsage();
+	for (const task of tasks) {
+		const tracked = getTrackedTaskUsage(task.id);
+		addUsage(total, tracked);
+		// Also add any usage already stored on the task
+		if (task.usage) addUsage(total, task.usage);
+	}
+	return usageStateFromLifetime(total);
+}

package/src/runtime/worker-heartbeat.ts

@@ -1,21 +1,21 @@
-export interface WorkerHeartbeatState {
-	workerId: string;
-	pid?: number;
-	lastSeenAt: string;
-	lastStdoutAt?: string;
-	lastEventAt?: string;
-	turnCount?: number;
-	alive?: boolean;
-}
-
-export function createWorkerHeartbeat(workerId: string, pid?: number, now = new Date()): WorkerHeartbeatState {
-	return { workerId, pid, lastSeenAt: now.toISOString(), alive: true };
-}
-
-export function touchWorkerHeartbeat(heartbeat: WorkerHeartbeatState, updates: Partial<Omit<WorkerHeartbeatState, "workerId">> = {}, now = new Date()): WorkerHeartbeatState {
-	return { ...heartbeat, ...updates, lastSeenAt: now.toISOString() };
-}
-
-export function isWorkerHeartbeatStale(heartbeat: WorkerHeartbeatState, staleMs: number, now = new Date()): boolean {
-	return now.getTime() - Date.parse(heartbeat.lastSeenAt) > staleMs;
-}
+export interface WorkerHeartbeatState {
+	workerId: string;
+	pid?: number;
+	lastSeenAt: string;
+	lastStdoutAt?: string;
+	lastEventAt?: string;
+	turnCount?: number;
+	alive?: boolean;
+}
+
+export function createWorkerHeartbeat(workerId: string, pid?: number, now = new Date()): WorkerHeartbeatState {
+	return { workerId, pid, lastSeenAt: now.toISOString(), alive: true };
+}
+
+export function touchWorkerHeartbeat(heartbeat: WorkerHeartbeatState, updates: Partial<Omit<WorkerHeartbeatState, "workerId">> = {}, now = new Date()): WorkerHeartbeatState {
+	return { ...heartbeat, ...updates, lastSeenAt: now.toISOString() };
+}
+
+export function isWorkerHeartbeatStale(heartbeat: WorkerHeartbeatState, staleMs: number, now = new Date()): boolean {
+	return now.getTime() - Date.parse(heartbeat.lastSeenAt) > staleMs;
+}

package/src/runtime/worker-startup.ts

@@ -1,57 +1,57 @@
-export type WorkerLifecycleState = "spawning" | "trust_required" | "ready_for_prompt" | "running" | "finished" | "failed";
-export type StartupFailureClassification = "trust_required" | "prompt_misdelivery" | "prompt_acceptance_timeout" | "transport_dead" | "worker_crashed" | "unknown";
-
-export interface WorkerStartupEvidence {
-	lastLifecycleState: WorkerLifecycleState;
-	command: string;
-	promptSentAt?: string;
-	promptAccepted: boolean;
-	trustPromptDetected: boolean;
-	transportHealthy: boolean;
-	childProcessAlive: boolean;
-	elapsedMs: number;
-	classification: StartupFailureClassification;
-	stderrPreview?: string;
-}
-
-export function detectTrustPrompt(text: string): boolean {
-	const lowered = text.toLowerCase();
-	return lowered.includes("do you trust") || lowered.includes("trust this") || lowered.includes("untrusted") || lowered.includes("workspace trust") || lowered.includes("allow this folder");
-}
-
-export function classifyStartupFailure(evidence: Omit<WorkerStartupEvidence, "classification">): StartupFailureClassification {
-	if (!evidence.transportHealthy) return "transport_dead";
-	if (evidence.trustPromptDetected || evidence.lastLifecycleState === "trust_required") return "trust_required";
-	if (evidence.promptSentAt && !evidence.promptAccepted && evidence.childProcessAlive) return "prompt_acceptance_timeout";
-	if (evidence.promptSentAt && !evidence.promptAccepted && !evidence.childProcessAlive) return "worker_crashed";
-	if (evidence.stderrPreview?.toLowerCase().includes("command not found") || evidence.stderrPreview?.toLowerCase().includes("not recognized")) return "prompt_misdelivery";
-	if (!evidence.childProcessAlive && evidence.lastLifecycleState !== "finished") return "worker_crashed";
-	return "unknown";
-}
-
-export function createStartupEvidence(input: {
-	command: string;
-	startedAt: Date;
-	finishedAt?: Date;
-	promptSentAt?: Date;
-	promptAccepted?: boolean;
-	stderr?: string;
-	error?: string;
-	exitCode?: number | null;
-}): WorkerStartupEvidence {
-	const stderrPreview = (input.error || input.stderr || "").slice(0, 500) || undefined;
-	const trustPromptDetected = detectTrustPrompt(stderrPreview ?? "");
-	const childProcessAlive = input.exitCode === undefined || input.exitCode === null ? !input.finishedAt : false;
-	const base: Omit<WorkerStartupEvidence, "classification"> = {
-		lastLifecycleState: input.error || (input.exitCode !== undefined && input.exitCode !== null && input.exitCode !== 0) ? "failed" : input.finishedAt ? "finished" : "running",
-		command: input.command,
-		promptSentAt: input.promptSentAt?.toISOString(),
-		promptAccepted: input.promptAccepted ?? !input.error,
-		trustPromptDetected,
-		transportHealthy: !input.error || !/enoent|spawn|transport/i.test(input.error),
-		childProcessAlive,
-		elapsedMs: Math.max(0, (input.finishedAt ?? new Date()).getTime() - input.startedAt.getTime()),
-		stderrPreview,
-	};
-	return { ...base, classification: classifyStartupFailure(base) };
-}
+export type WorkerLifecycleState = "spawning" | "trust_required" | "ready_for_prompt" | "running" | "finished" | "failed";
+export type StartupFailureClassification = "trust_required" | "prompt_misdelivery" | "prompt_acceptance_timeout" | "transport_dead" | "worker_crashed" | "unknown";
+
+export interface WorkerStartupEvidence {
+	lastLifecycleState: WorkerLifecycleState;
+	command: string;
+	promptSentAt?: string;
+	promptAccepted: boolean;
+	trustPromptDetected: boolean;
+	transportHealthy: boolean;
+	childProcessAlive: boolean;
+	elapsedMs: number;
+	classification: StartupFailureClassification;
+	stderrPreview?: string;
+}
+
+export function detectTrustPrompt(text: string): boolean {
+	const lowered = text.toLowerCase();
+	return lowered.includes("do you trust") || lowered.includes("trust this") || lowered.includes("untrusted") || lowered.includes("workspace trust") || lowered.includes("allow this folder");
+}
+
+export function classifyStartupFailure(evidence: Omit<WorkerStartupEvidence, "classification">): StartupFailureClassification {
+	if (!evidence.transportHealthy) return "transport_dead";
+	if (evidence.trustPromptDetected || evidence.lastLifecycleState === "trust_required") return "trust_required";
+	if (evidence.promptSentAt && !evidence.promptAccepted && evidence.childProcessAlive) return "prompt_acceptance_timeout";
+	if (evidence.promptSentAt && !evidence.promptAccepted && !evidence.childProcessAlive) return "worker_crashed";
+	if (evidence.stderrPreview?.toLowerCase().includes("command not found") || evidence.stderrPreview?.toLowerCase().includes("not recognized")) return "prompt_misdelivery";
+	if (!evidence.childProcessAlive && evidence.lastLifecycleState !== "finished") return "worker_crashed";
+	return "unknown";
+}
+
+export function createStartupEvidence(input: {
+	command: string;
+	startedAt: Date;
+	finishedAt?: Date;
+	promptSentAt?: Date;
+	promptAccepted?: boolean;
+	stderr?: string;
+	error?: string;
+	exitCode?: number | null;
+}): WorkerStartupEvidence {
+	const stderrPreview = (input.error || input.stderr || "").slice(0, 500) || undefined;
+	const trustPromptDetected = detectTrustPrompt(stderrPreview ?? "");
+	const childProcessAlive = input.exitCode === undefined || input.exitCode === null ? !input.finishedAt : false;
+	const base: Omit<WorkerStartupEvidence, "classification"> = {
+		lastLifecycleState: input.error || (input.exitCode !== undefined && input.exitCode !== null && input.exitCode !== 0) ? "failed" : input.finishedAt ? "finished" : "running",
+		command: input.command,
+		promptSentAt: input.promptSentAt?.toISOString(),
+		promptAccepted: input.promptAccepted ?? !input.error,
+		trustPromptDetected,
+		transportHealthy: !input.error || !/enoent|spawn|transport/i.test(input.error),
+		childProcessAlive,
+		elapsedMs: Math.max(0, (input.finishedAt ?? new Date()).getTime() - input.startedAt.getTime()),
+		stderrPreview,
+	};
+	return { ...base, classification: classifyStartupFailure(base) };
+}

package/src/runtime/workflow-state.ts

@@ -1,187 +1,187 @@
-/**
- * Workflow Phase State Machine
- *
- * Tracks phase-level progression through a workflow, validating that each
- * phase's declared inputs (required artifacts) are satisfied before it can
- * start. All transition functions are immutable — they return new machine
- * state rather than mutating in place.
- */
-
-// ── Public types ──────────────────────────────────────────────────────────────
-
-export type PhaseStatus = "pending" | "running" | "completed" | "failed" | "skipped";
-
-export interface PhaseGuardContext {
-	/** Artifact paths that currently exist on disk. */
-	completedArtifacts: string[];
-	/** Status of the phase immediately preceding the target phase. */
-	previousPhaseStatus: PhaseStatus;
-	/** Results from tasks that have already completed. */
-	taskResults: Array<{ taskId: string; status: string; outputPath?: string }>;
-}
-
-export interface GuardResult {
-	allowed: boolean;
-	reason?: string;
-}
-
-export interface PhaseTransition {
-	from: PhaseStatus;
-	to: PhaseStatus;
-	guard?: (context: PhaseGuardContext) => GuardResult;
-}
-
-export interface PhaseState {
-	name: string;
-	status: PhaseStatus;
-	/** Artifact names required before this phase can start. */
-	inputs: string[];
-	/** Artifact names this phase produces. */
-	outputs: string[];
-	startedAt?: string;
-	finishedAt?: string;
-}
-
-export interface WorkflowStateMachine {
-	phases: PhaseState[];
-	currentPhaseIndex: number;
-}
-
-// ── Factory ───────────────────────────────────────────────────────────────────
-
-/**
- * Create a new workflow state machine from an initial set of phases.
- * All phases start as "pending" and the current index is set to 0.
- */
-export function createWorkflowStateMachine(phases: PhaseState[]): WorkflowStateMachine {
-	return {
-		phases: phases.map((phase) => ({
-			...phase,
-			status: phase.status ?? "pending",
-		})),
-		currentPhaseIndex: 0,
-	};
-}
-
-// ── Queries ───────────────────────────────────────────────────────────────────
-
-/**
- * Return the declared inputs for a given phase index.
- * Returns an empty array for out-of-bounds indices.
- */
-export function getPhaseInputs(machine: WorkflowStateMachine, phaseIndex: number): string[] {
-	const phase = machine.phases[phaseIndex];
-	if (!phase) return [];
-	return phase.inputs;
-}
-
-/**
- * Check whether a transition to a specific phase is allowed.
- *
- * Rules (evaluated in order):
- * 1. `phaseIndex` must be in bounds.
- * 2. If this is not the first phase, the previous phase must be "completed" or "skipped".
- * 3. All declared `inputs` for the target phase must appear in `completedArtifacts`.
- * 4. If a custom `guard` is supplied on a transition, it must also approve.
- */
-export function canTransitionToPhase(
-	machine: WorkflowStateMachine,
-	phaseIndex: number,
-	context: PhaseGuardContext,
-): GuardResult {
-	if (phaseIndex < 0 || phaseIndex >= machine.phases.length) {
-		return { allowed: false, reason: `Phase index ${phaseIndex} is out of bounds (0..${machine.phases.length - 1}).` };
-	}
-
-	// Previous phase must have completed (or been skipped).
-	if (phaseIndex > 0) {
-		const prevStatus = context.previousPhaseStatus;
-		if (prevStatus !== "completed" && prevStatus !== "skipped") {
-			return { allowed: false, reason: `Previous phase status is '${prevStatus}'; expected 'completed' or 'skipped'.` };
-		}
-	}
-
-	// All declared inputs must be satisfied.
-	const phase = machine.phases[phaseIndex]!;
-	if (phase.inputs.length > 0) {
-		const artifactSet = new Set(context.completedArtifacts);
-		const missing = phase.inputs.filter((input) => !artifactSet.has(input));
-		if (missing.length > 0) {
-			return { allowed: false, reason: `Missing required artifacts: ${missing.join(", ")}.` };
-		}
-	}
-
-	return { allowed: true };
-}
-
-/**
- * Validate that all preconditions for the *current* phase are met.
- * Returns the subset of declared inputs that are not yet present in `completedArtifacts`.
- */
-export function validatePhasePreconditions(
-	machine: WorkflowStateMachine,
-	context: PhaseGuardContext,
-): { ready: boolean; blocking: string[] } {
-	const phase = machine.phases[machine.currentPhaseIndex];
-	if (!phase) {
-		return { ready: false, blocking: [`No phase at index ${machine.currentPhaseIndex}.`] };
-	}
-
-	const artifactSet = new Set(context.completedArtifacts);
-	const missing = phase.inputs.filter((input) => !artifactSet.has(input));
-	return { ready: missing.length === 0, blocking: missing };
-}
-
-// ── Transitions ───────────────────────────────────────────────────────────────
-
-/** Result of a phase transition: the (potentially unchanged) machine and an optional guard result. */
-export interface TransitionResult {
-	machine: WorkflowStateMachine;
-	guardResult?: GuardResult;
-}
-
-/**
- * Transition a phase to a new status. Returns a `TransitionResult` containing
- * the new `WorkflowStateMachine` and an optional `guardResult` when the guard
- * was checked.
- *
- * If `context` is provided and the guard fails, the machine is returned
- * **UNCHANGED** (the phase is NOT auto-failed) along with the `guardResult`
- * so the caller can decide what to do.
- *
- * For the "pending → running" transition the `startedAt` timestamp is set.
- * For terminal transitions ("completed", "failed", "skipped") the `finishedAt` timestamp is set.
- * On success the `currentPhaseIndex` advances to `phaseIndex` (or stays if already there).
- */
-export function transitionPhase(
-	machine: WorkflowStateMachine,
-	phaseIndex: number,
-	status: PhaseStatus,
-	context?: PhaseGuardContext,
-): TransitionResult {
-	if (context) {
-		const check = canTransitionToPhase(machine, phaseIndex, context);
-		if (!check.allowed) {
-			// Return machine UNCHANGED with guard result — caller decides what to do
-			return { machine, guardResult: check };
-		}
-	}
-
-	const now = new Date().toISOString();
-	const phases = machine.phases.map((phase, index) => {
-		if (index !== phaseIndex) return phase;
-		return {
-			...phase,
-			status,
-			...(status === "running" && !phase.startedAt ? { startedAt: now } : {}),
-			...((status === "completed" || status === "failed" || status === "skipped") && !phase.finishedAt ? { finishedAt: now } : {}),
-		};
-	});
-
-	return {
-		machine: {
-			phases,
-			currentPhaseIndex: Math.max(machine.currentPhaseIndex, phaseIndex),
-		},
-	};
-}
+/**
+ * Workflow Phase State Machine
+ *
+ * Tracks phase-level progression through a workflow, validating that each
+ * phase's declared inputs (required artifacts) are satisfied before it can
+ * start. All transition functions are immutable — they return new machine
+ * state rather than mutating in place.
+ */
+
+// ── Public types ──────────────────────────────────────────────────────────────
+
+export type PhaseStatus = "pending" | "running" | "completed" | "failed" | "skipped";
+
+export interface PhaseGuardContext {
+	/** Artifact paths that currently exist on disk. */
+	completedArtifacts: string[];
+	/** Status of the phase immediately preceding the target phase. */
+	previousPhaseStatus: PhaseStatus;
+	/** Results from tasks that have already completed. */
+	taskResults: Array<{ taskId: string; status: string; outputPath?: string }>;
+}
+
+export interface GuardResult {
+	allowed: boolean;
+	reason?: string;
+}
+
+export interface PhaseTransition {
+	from: PhaseStatus;
+	to: PhaseStatus;
+	guard?: (context: PhaseGuardContext) => GuardResult;
+}
+
+export interface PhaseState {
+	name: string;
+	status: PhaseStatus;
+	/** Artifact names required before this phase can start. */
+	inputs: string[];
+	/** Artifact names this phase produces. */
+	outputs: string[];
+	startedAt?: string;
+	finishedAt?: string;
+}
+
+export interface WorkflowStateMachine {
+	phases: PhaseState[];
+	currentPhaseIndex: number;
+}
+
+// ── Factory ───────────────────────────────────────────────────────────────────
+
+/**
+ * Create a new workflow state machine from an initial set of phases.
+ * All phases start as "pending" and the current index is set to 0.
+ */
+export function createWorkflowStateMachine(phases: PhaseState[]): WorkflowStateMachine {
+	return {
+		phases: phases.map((phase) => ({
+			...phase,
+			status: phase.status ?? "pending",
+		})),
+		currentPhaseIndex: 0,
+	};
+}
+
+// ── Queries ───────────────────────────────────────────────────────────────────
+
+/**
+ * Return the declared inputs for a given phase index.
+ * Returns an empty array for out-of-bounds indices.
+ */
+export function getPhaseInputs(machine: WorkflowStateMachine, phaseIndex: number): string[] {
+	const phase = machine.phases[phaseIndex];
+	if (!phase) return [];
+	return phase.inputs;
+}
+
+/**
+ * Check whether a transition to a specific phase is allowed.
+ *
+ * Rules (evaluated in order):
+ * 1. `phaseIndex` must be in bounds.
+ * 2. If this is not the first phase, the previous phase must be "completed" or "skipped".
+ * 3. All declared `inputs` for the target phase must appear in `completedArtifacts`.
+ * 4. If a custom `guard` is supplied on a transition, it must also approve.
+ */
+export function canTransitionToPhase(
+	machine: WorkflowStateMachine,
+	phaseIndex: number,
+	context: PhaseGuardContext,
+): GuardResult {
+	if (phaseIndex < 0 || phaseIndex >= machine.phases.length) {
+		return { allowed: false, reason: `Phase index ${phaseIndex} is out of bounds (0..${machine.phases.length - 1}).` };
+	}
+
+	// Previous phase must have completed (or been skipped).
+	if (phaseIndex > 0) {
+		const prevStatus = context.previousPhaseStatus;
+		if (prevStatus !== "completed" && prevStatus !== "skipped") {
+			return { allowed: false, reason: `Previous phase status is '${prevStatus}'; expected 'completed' or 'skipped'.` };
+		}
+	}
+
+	// All declared inputs must be satisfied.
+	const phase = machine.phases[phaseIndex]!;
+	if (phase.inputs.length > 0) {
+		const artifactSet = new Set(context.completedArtifacts);
+		const missing = phase.inputs.filter((input) => !artifactSet.has(input));
+		if (missing.length > 0) {
+			return { allowed: false, reason: `Missing required artifacts: ${missing.join(", ")}.` };
+		}
+	}
+
+	return { allowed: true };
+}
+
+/**
+ * Validate that all preconditions for the *current* phase are met.
+ * Returns the subset of declared inputs that are not yet present in `completedArtifacts`.
+ */
+export function validatePhasePreconditions(
+	machine: WorkflowStateMachine,
+	context: PhaseGuardContext,
+): { ready: boolean; blocking: string[] } {
+	const phase = machine.phases[machine.currentPhaseIndex];
+	if (!phase) {
+		return { ready: false, blocking: [`No phase at index ${machine.currentPhaseIndex}.`] };
+	}
+
+	const artifactSet = new Set(context.completedArtifacts);
+	const missing = phase.inputs.filter((input) => !artifactSet.has(input));
+	return { ready: missing.length === 0, blocking: missing };
+}
+
+// ── Transitions ───────────────────────────────────────────────────────────────
+
+/** Result of a phase transition: the (potentially unchanged) machine and an optional guard result. */
+export interface TransitionResult {
+	machine: WorkflowStateMachine;
+	guardResult?: GuardResult;
+}
+
+/**
+ * Transition a phase to a new status. Returns a `TransitionResult` containing
+ * the new `WorkflowStateMachine` and an optional `guardResult` when the guard
+ * was checked.
+ *
+ * If `context` is provided and the guard fails, the machine is returned
+ * **UNCHANGED** (the phase is NOT auto-failed) along with the `guardResult`
+ * so the caller can decide what to do.
+ *
+ * For the "pending → running" transition the `startedAt` timestamp is set.
+ * For terminal transitions ("completed", "failed", "skipped") the `finishedAt` timestamp is set.
+ * On success the `currentPhaseIndex` advances to `phaseIndex` (or stays if already there).
+ */
+export function transitionPhase(
+	machine: WorkflowStateMachine,
+	phaseIndex: number,
+	status: PhaseStatus,
+	context?: PhaseGuardContext,
+): TransitionResult {
+	if (context) {
+		const check = canTransitionToPhase(machine, phaseIndex, context);
+		if (!check.allowed) {
+			// Return machine UNCHANGED with guard result — caller decides what to do
+			return { machine, guardResult: check };
+		}
+	}
+
+	const now = new Date().toISOString();
+	const phases = machine.phases.map((phase, index) => {
+		if (index !== phaseIndex) return phase;
+		return {
+			...phase,
+			status,
+			...(status === "running" && !phase.startedAt ? { startedAt: now } : {}),
+			...((status === "completed" || status === "failed" || status === "skipped") && !phase.finishedAt ? { finishedAt: now } : {}),
+		};
+	});
+
+	return {
+		machine: {
+			phases,
+			currentPhaseIndex: Math.max(machine.currentPhaseIndex, phaseIndex),
+		},
+	};
+}