pi-crew 0.9.53 → 0.9.55

package/src/state/types.ts

@@ -0,0 +1,447 @@
+import type { CrashClass } from "../runtime/crash-classification.ts";
+import type { CrewAgentProgress } from "../runtime/crew-agent-runtime.ts";
+import type { WorkerHeartbeatState } from "../runtime/worker-heartbeat.ts";
+import type { TeamRunStatus, TeamTaskStatus } from "./contracts.ts";
+import type { CoherenceMark, RolloutEntry } from "./decision-ledger.ts";
+import type { TaskClaimState } from "./task-claims.ts";
+
+export type { TeamRunStatus, TeamTaskStatus } from "./contracts.ts";
+export type { CoherenceMark, CrewAgentProgress, RolloutEntry };
+
+export interface ArtifactDescriptor {
+	kind: "plan" | "prompt" | "result" | "summary" | "log" | "diff" | "patch" | "progress" | "notepad" | "metadata";
+	path: string;
+	createdAt: string;
+	producer: string;
+	sizeBytes?: number;
+	contentHash?: string;
+	retention: "run" | "project" | "temporary";
+	expiresAt?: string;
+}
+
+export type TaskScope = "workspace" | "module" | "single_file" | "custom";
+export type GreenLevel = "none" | "targeted" | "package" | "workspace" | "merge_ready";
+
+export interface VerificationCommandResult {
+	cmd: string;
+	status: "passed" | "failed" | "not_run";
+	exitCode?: number | null;
+	durationMs?: number;
+	outputArtifact?: ArtifactDescriptor;
+}
+
+export interface VerificationContract {
+	requiredGreenLevel: GreenLevel;
+	commands: string[];
+	allowManualEvidence: boolean;
+}
+
+export interface VerificationEvidence {
+	requiredGreenLevel: GreenLevel;
+	observedGreenLevel: GreenLevel;
+	satisfied: boolean;
+	commands: VerificationCommandResult[];
+	notes?: string;
+}
+
+export interface TaskOutputSchema {
+	/** Output format expected from the worker */
+	format: "json" | "markdown" | "text";
+	/** JTD or JSON Schema for validating JSON output (only when format="json") */
+	schema?: Record<string, unknown>;
+	/** Human-readable description of expected output */
+	description?: string;
+	/** Example of valid output (for prompt guidance) */
+	example?: string;
+}
+
+export interface TaskPacket {
+	objective: string;
+	scope: TaskScope;
+	scopePath?: string;
+	repo: string;
+	worktree?: string;
+	branchPolicy: string;
+	acceptanceTests: string[];
+	commitPolicy: string;
+	reportingContract: string;
+	escalationPolicy: string;
+	constraints: string[];
+	expectedArtifacts: string[];
+	verification: VerificationContract;
+	outputSchema?: TaskOutputSchema;
+}
+
+export type PolicyDecisionAction = "retry" | "reassign" | "escalate" | "block" | "notify" | "cleanup" | "closeout" | "fail";
+export type PolicyDecisionReason =
+	| "task_failed"
+	| "worker_stale"
+	| "green_unsatisfied"
+	| "limit_exceeded"
+	| "run_complete"
+	| "mailbox_timeout"
+	| "review_rejected"
+	| "branch_stale"
+	| "scope_mismatch"
+	| "ineffective_worker";
+
+export interface PolicyDecision {
+	action: PolicyDecisionAction;
+	reason: PolicyDecisionReason;
+	message: string;
+	taskId?: string;
+	createdAt: string;
+}
+
+export interface TaskGraphNode {
+	taskId: string;
+	parentId?: string;
+	children: string[];
+	dependencies: string[];
+	queue: "ready" | "blocked" | "running" | "done";
+	sessionForkFrom?: string;
+}
+
+export interface AsyncRunState {
+	pid?: number;
+	logPath: string;
+	spawnedAt: string;
+}
+
+export interface RuntimeResolutionState {
+	kind: "scaffold" | "child-process" | "live-session";
+	requestedMode: "auto" | "scaffold" | "child-process" | "live-session";
+	safety: "trusted" | "explicit_dry_run" | "blocked";
+	available: boolean;
+	fallback?: "scaffold" | "child-process" | "live-session";
+	reason?: string;
+	resolvedAt: string;
+}
+
+export interface WorkerExitStatus {
+	exitCode: number | null;
+	cancelled: boolean;
+	timedOut: boolean;
+	killed: boolean;
+	signal?: string;
+	cleanupErrors: string[];
+	finalDrainMs: number;
+	/** Categorical classification of the exit (P0 crash taxonomy). Optional
+	 *  because it is populated by child-pi.ts at settle time; older/synthetic
+	 *  exit statuses may omit it. */
+	crashClass?: CrashClass;
+	/** Phase-0 diagnostic (HB-003a): final-drain race state for the exit-null
+	 *  disableTools bug. Optional + read-only — absent when no drain timer was
+	 *  ever armed. Phase 1 will use `finalDrainArmed` to decide whether a
+	 *  signal-death (exitCode=null) should be treated as a forced final drain. */
+	finalDrainArmed?: boolean;
+	forcedFinalDrain?: boolean;
+	finalDrainFiredMonotonicMs?: number;
+}
+
+export interface OperationTerminalEvidence {
+	operation: "worker" | "tool" | "model";
+	status: "cancelled" | "failed" | "completed";
+	startedAt?: string;
+	finishedAt: string;
+	attemptId?: string;
+	reason?: {
+		code: string;
+		message: string;
+	};
+	exitStatus?: WorkerExitStatus;
+}
+
+export interface PlanApprovalState {
+	required: boolean;
+	status: "pending" | "approved" | "cancelled";
+	requestedAt: string;
+	updatedAt: string;
+	approvedAt?: string;
+	cancelledAt?: string;
+	planTaskId?: string;
+	planArtifactPath?: string;
+}
+
+export type CrewActivityState = "active" | "active_long_running" | "needs_attention" | "stale";
+export type CrewAttentionReason = "idle" | "tool_failures" | "completion_guard" | "heartbeat_stale" | "plan_approval_pending";
+
+export interface CrewAttentionEventData {
+	activityState: CrewActivityState;
+	reason: CrewAttentionReason;
+	elapsedMs?: number;
+	taskId?: string;
+	agentName?: string;
+	suggestedAction?: string;
+	observedTools?: string[];
+}
+
+/**
+ * S-01: schemaVersion sentinel for the run manifest. Increment on breaking
+ * state changes; add migration logic in state-store load paths. Loaded
+ * manifests whose schemaVersion differs emit a console.warn (no throw).
+ */
+export const CURRENT_SCHEMA_VERSION = 1 as const;
+
+export interface TeamRunManifest {
+	schemaVersion: typeof CURRENT_SCHEMA_VERSION;
+	runId: string;
+	/** pi session ID aligned with run ID for cross-referencing (e.g., "crew-team20260528") */
+	sessionId?: string;
+	team: string;
+	workflow?: string;
+	goal: string;
+	status: TeamRunStatus;
+	workspaceMode: "single" | "worktree";
+	createdAt: string;
+	updatedAt: string;
+	cwd: string;
+	stateRoot: string;
+	artifactsRoot: string;
+	tasksPath: string;
+	eventsPath: string;
+	artifacts: ArtifactDescriptor[];
+	async?: AsyncRunState;
+	planApproval?: PlanApprovalState;
+	/** Pi session that created the run, when available. Used to prevent cross-session destructive actions. */
+	ownerSessionId?: string;
+	/** pi-crew skill override selected when the run was created. false disables injected skill instructions. */
+	skillOverride?: string[] | false;
+	/** Resolved runtime/safety mode used for execution. Optional for backward compatibility with older manifests. */
+	runtimeResolution?: RuntimeResolutionState;
+	/** Effective run config snapshot used by async background workers. Optional for backward compatibility. */
+	runConfig?: unknown;
+	/** Background dispatch discriminator. Default "team-run" runs executeTeamRun; "goal-loop" / "dynamic-workflow" dispatch to their respective runners. Absent = "team-run" for backward compatibility. */
+	runKind?: "team-run" | "goal-loop" | "dynamic-workflow";
+	/** round-14 P1-5: typed workflow arguments accessible in .dwf.ts scripts via ctx.args<T>(). Any JSON value; default {} when unset. */
+	args?: unknown;
+	/** Per-run token budget snapshot. budgetTotal is the cap; budgetWarning/budgetAbort are fractions in [0,1] at which the team-runner emits run.budget_warning / run.budget_abort. budgetUnlimited=true opts out of enforcement. Optional for backward compat. */
+	budgetTotal?: number;
+	budgetWarning?: number;
+	budgetAbort?: number;
+	budgetUnlimited?: boolean;
+	summary?: string;
+	policyDecisions?: PolicyDecision[];
+	/** #2 (assessment): goal-achievement verdict — kills the silent false-green. */
+	goalAchieved?: boolean | "unknown";
+	goalAchievementNote?: string;
+}
+
+export interface UsageState {
+	input?: number;
+	output?: number;
+	cacheRead?: number;
+	cacheWrite?: number;
+	cost?: number;
+	turns?: number;
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Goal loop types (P0/P1 — autonomous goal loop, Claude-Code-style /goal).
+// Spec: research-findings/goal-workflow/00-SPEC.md §2.3; plan 07-PLAN.md v3 §0b G2 + §0c.
+// ───────────────────────────────────────────────────────────────────────────
+
+/**
+ * Outer-state lifecycle of a goal loop. Inner per-turn state lives on each turn's TeamRunManifest.
+ *
+ * P1b (RFC v0.5 §P1b): `"stuck"` is NON-TERMINAL and RE-HINTABLE. Legal transitions:
+ *   running → stuck     (only by the background loop, after the oscillation detector fires)
+ *   stuck   → running   (only by `goal resume`, atomically via GoalStore.compareAndSetStatus)
+ *   stuck   → cancelled (by the idle-timeout sweeper OR `goal stop`)
+ */
+export type GoalLoopStatus = "running" | "paused" | "stuck" | "achieved" | "max_turns" | "budget_exceeded" | "blocked" | "cancelled";
+
+/** One evaluation by the goal-judge model after a turn. */
+export interface GoalVerdict {
+	turn: number;
+	achieved: boolean;
+	/** "achieved: all tests pass" | "not-achieved: 2/8 tests failing" | "BLOCKED: <reason>" (BLOCKED: prefix → status='blocked'). */
+	reason: string;
+	evidenceRefs?: string[];
+	evaluatorModel: string;
+	evaluatedAt: string;
+}
+
+/** Persisted at <crewRoot>/state/goals/<goalId>.json by GoalStore. Survives session restart. */
+export interface GoalLoopState {
+	goalId: string;
+	ownerSessionId: string;
+	objective: string;
+	scope?: string;
+	/** Acceptance conditions as shell commands (exit 0 = pass). Reuses VerificationContract semantics. */
+	verification?: { commands: string[]; allowManualEvidence?: boolean };
+	state: GoalLoopStatus;
+	maxTurns: number;
+	turnsUsed: number;
+	budgetTotal?: number;
+	/** P1d (RFC v0.5 §P1d): when true, budget enforcement is skipped (explicit opt-out; audit-logged at start). */
+	budgetUnlimited?: boolean;
+	budgetWarning?: number;
+	budgetAbort?: number;
+	budgetUsed: number;
+	/**
+	 * P1a (RFC v0.5 §P1a): bookend integrity snapshot of project-manifest files
+	 * taken at goal start (only when verification.commands is declared). The
+	 * goal-loop-runner re-hashes before (T_snap) and after (T_verify_done) each
+	 * verification command to detect persistent manifest tampering. The literal
+	 * `"none-text-only"` marks goals started in text-only verification mode
+	 * (no objective oracle → no snapshot taken).
+	 */
+	verificationIntegrity?: { snapshot: Record<string, string>; takenAt: string } | "none-text-only";
+	evaluatorModel: string;
+	workerModel?: string;
+	/** subagent_type / agent name for worker turns (default "executor"). */
+	workerAgent?: string;
+	team?: string;
+	cwd: string;
+	/** Feedback from turn N's verdict, prepended into turn N+1's manifest.goal (G1). */
+	nextTurnFeedback?: string;
+	/** The team-run of the current in-flight turn (for cancel/steer). */
+	currentRunId?: string;
+	verdicts: GoalVerdict[];
+	history: {
+		runId: string;
+		outcome: string;
+		learnedAt: string;
+		turn: number;
+	}[];
+	createdAt: string;
+	updatedAt: string;
+	/** Mirror of manifest.async for PID-liveness checks (cf. AsyncRunState). */
+	async?: { pid: number; logPath: string; spawnedAt: string };
+}
+
+export interface ModelAttemptState {
+	model: string;
+	success: boolean;
+	exitCode?: number | null;
+	error?: string;
+}
+
+export interface ModelRoutingState {
+	requested?: string;
+	resolved: string;
+	fallbackChain: string[];
+	reason?: string;
+	usedAttempt: number;
+}
+
+export interface TaskWorktreeState {
+	path: string;
+	branch: string;
+	reused: boolean;
+}
+
+export interface TaskCheckpointState {
+	phase: "started" | "child-spawned" | "child-stdout-final" | "artifact-written";
+	updatedAt: string;
+	childPid?: number;
+}
+
+export interface TaskAttemptState {
+	attemptId?: string;
+	startedAt: string;
+	endedAt?: string;
+	error?: string;
+}
+
+export interface TeamTaskState {
+	id: string;
+	runId: string;
+	stepId?: string;
+	role: string;
+	agent: string;
+	title: string;
+	displayName?: string;
+	status: TeamTaskStatus;
+	dependsOn: string[];
+	cwd: string;
+	worktree?: TaskWorktreeState;
+	promptArtifact?: ArtifactDescriptor;
+	resultArtifact?: ArtifactDescriptor;
+	logArtifact?: ArtifactDescriptor;
+	transcriptArtifact?: ArtifactDescriptor;
+	startedAt?: string;
+	finishedAt?: string;
+	exitCode?: number | null;
+	model?: string;
+	modelAttempts?: ModelAttemptState[];
+	modelRouting?: ModelRoutingState;
+	usage?: UsageState;
+	jsonEvents?: number;
+	agentProgress?: CrewAgentProgress;
+	error?: string;
+	claim?: TaskClaimState;
+	heartbeat?: WorkerHeartbeatState;
+	checkpoint?: TaskCheckpointState;
+	attempts?: TaskAttemptState[];
+	workerExitStatus?: WorkerExitStatus;
+	terminalEvidence?: OperationTerminalEvidence[];
+	taskPacket?: TaskPacket;
+	verification?: VerificationEvidence;
+	graph?: TaskGraphNode;
+	adaptive?: {
+		phase: string;
+		task: string;
+	};
+	policy?: {
+		retryCount?: number;
+		lastDecision?: PolicyDecision;
+	};
+	controlReservation?: ControlReservation;
+
+	/** Structured diagnostics per task (ASI pattern from pi-autoresearch). */
+	diagnostics?: Record<string, unknown>;
+
+	/** Segment counter for task retry isolation. Default 0 (first attempt). Incremented on retry. */
+	segment?: number;
+
+	/** Parsed metric key-values from worker output (CREW_METRIC lines). */
+	metrics?: Record<string, number>;
+
+	/** Lifetime token usage accumulated via message_end events. Survives compaction
+	 *  (session.stats reset on compaction, but this is an independent accumulator). */
+	lifetimeUsage?: { input: number; output: number; cacheWrite: number };
+
+	/** Steering messages queued before the task's session was ready.
+	 *  Delivered when the session initializes (mirrors pi-subagents3 pendingSteers pattern). */
+	pendingSteers?: string[];
+}
+
+export interface ControlReservation {
+	reservedAt: string;
+	controllerId: string;
+	acceptsControlEvents: boolean;
+}
+
+/**
+ * A task scheduled to fire on a cron expression, interval, or one-shot.
+ * Persisted at `<cwd>/.crew/state/schedules/<sessionId>.json`.
+ * Session-scoped: survives /resume, resets on /new.
+ */
+export interface ScheduledTask {
+	id: string;
+	name: string;
+	description: string;
+	/** Raw schedule: cron expr | "+10m" | "5m" | ISO timestamp */
+	schedule: string;
+	scheduleType: "cron" | "interval" | "once";
+	intervalMs?: number;
+	/** Workflow/step to execute when the schedule fires */
+	workflowName: string;
+	stepId?: string;
+	/** Resolved at create time from workflow/step config */
+	agentName: string;
+	model?: string;
+	enabled: boolean;
+	createdAt: string;
+	lastRun?: string;
+	lastStatus?: "success" | "error" | "running";
+	nextRun?: string;
+	runCount: number;
+}
+
+export interface ScheduleStoreData {
+	version: 1;
+	jobs: ScheduledTask[];
+}

package/src/state/usage.ts

@@ -0,0 +1,138 @@
+import type { TeamTaskState, UsageState } from "./types.ts";
+
+/**
+ * Lifetime usage — accumulated via message_end events, survives compaction.
+ * cacheRead is excluded because each turn's cacheRead is the cumulative cached
+ * prefix re-read on that one call — summing across turns would count it N times.
+ * See: https://github.com/nichekate/pi-subagents3/issues/38
+ */
+export type LifetimeUsage = {
+	input: number;
+	output: number;
+	cacheWrite: number;
+};
+
+/** Sum of lifetime usage components, or 0 if undefined. */
+export function getLifetimeTotal(u?: LifetimeUsage): number {
+	return u ? u.input + u.output + u.cacheWrite : 0;
+}
+
+/** Add a usage delta into a target accumulator (mutates target). */
+export function addUsage(into: LifetimeUsage, delta: LifetimeUsage): void {
+	into.input += delta.input;
+	into.output += delta.output;
+	into.cacheWrite += delta.cacheWrite;
+}
+
+export function aggregateUsage(tasks: TeamTaskState[]): UsageState | undefined {
+	const total: UsageState = {};
+	let found = false;
+	for (const task of tasks) {
+		if (!task.usage) continue;
+		found = true;
+		total.input = (total.input ?? 0) + (task.usage.input ?? 0);
+		total.output = (total.output ?? 0) + (task.usage.output ?? 0);
+		total.cacheRead = (total.cacheRead ?? 0) + (task.usage.cacheRead ?? 0);
+		total.cacheWrite = (total.cacheWrite ?? 0) + (task.usage.cacheWrite ?? 0);
+		total.cost = (total.cost ?? 0) + (task.usage.cost ?? 0);
+		total.turns = (total.turns ?? 0) + (task.usage.turns ?? 0);
+	}
+	return found ? total : undefined;
+}
+
+export function formatUsage(usage: UsageState | undefined): string {
+	if (!usage) return "(none)";
+	const parts: string[] = [];
+	if (usage.input !== undefined) parts.push(`input=${usage.input}`);
+	if (usage.output !== undefined) parts.push(`output=${usage.output}`);
+	if (usage.cacheRead !== undefined) parts.push(`cacheRead=${usage.cacheRead}`);
+	if (usage.cacheWrite !== undefined) parts.push(`cacheWrite=${usage.cacheWrite}`);
+	if (usage.cost !== undefined && Number.isFinite(usage.cost)) parts.push(`cost=${usage.cost.toFixed(6)}`);
+	if (usage.turns !== undefined) parts.push(`turns=${usage.turns}`);
+	return parts.join(", ") || "(none)";
+}
+
+/** Human-readable compact token count (12345 -> "12.3k"). */
+export function formatTokens(n: number): string {
+	if (n < 1000) return `${n}`;
+	if (n < 1_000_000) return n < 10_000 ? `${(n / 1000).toFixed(1)}k` : `${Math.round(n / 1000)}k`;
+	return `${(n / 1_000_000).toFixed(2)}M`;
+}
+
+/** Human-readable cost ($0.001234 -> "$0.001234", $1.5 -> "$1.50"). */
+export function formatCost(cost: number | undefined): string {
+	if (cost === undefined || !Number.isFinite(cost)) return "$0.00";
+	if (cost === 0) return "$0.00";
+	if (cost < 0.01) return `$${cost.toFixed(6)}`;
+	return `$${cost.toFixed(cost < 1 ? 4 : 2)}`;
+}
+
+export interface RoleUsage {
+	role: string;
+	input: number;
+	output: number;
+	cacheWrite: number;
+	cost: number;
+	turns: number;
+	taskCount: number;
+}
+
+/** Aggregate usage per-role (and per-task) for cost attribution. */
+export function aggregateUsageByRole(tasks: TeamTaskState[]): RoleUsage[] {
+	const byRole = new Map<string, RoleUsage>();
+	for (const task of tasks) {
+		const role = task.role || "unknown";
+		let bucket = byRole.get(role);
+		if (!bucket) {
+			bucket = {
+				role,
+				input: 0,
+				output: 0,
+				cacheWrite: 0,
+				cost: 0,
+				turns: 0,
+				taskCount: 0,
+			};
+			byRole.set(role, bucket);
+		}
+		bucket.taskCount++;
+		if (!task.usage) continue;
+		bucket.input += task.usage.input ?? 0;
+		bucket.output += task.usage.output ?? 0;
+		bucket.cacheWrite += task.usage.cacheWrite ?? 0;
+		bucket.cost += task.usage.cost ?? 0;
+		bucket.turns += task.usage.turns ?? 0;
+	}
+	return [...byRole.values()].sort((a, b) => b.cost - a.cost);
+}
+
+/**
+ * Build a multi-line cost report with per-role attribution.
+ * Used by the `summary` action for cost visibility (roadmap T1.1).
+ */
+export function formatCostReport(tasks: TeamTaskState[]): string {
+	const usage = aggregateUsage(tasks);
+	if (!usage) return "Cost: (no usage data recorded)";
+	const byRole = aggregateUsageByRole(tasks);
+	const totalTokens = (usage.input ?? 0) + (usage.output ?? 0) + (usage.cacheWrite ?? 0);
+	const lines: string[] = [];
+	lines.push("═══ Cost Report ═══");
+	lines.push(
+		`Tokens: ${formatTokens(totalTokens)} (in ${formatTokens(usage.input ?? 0)}, out ${formatTokens(usage.output ?? 0)}, cache-write ${formatTokens(usage.cacheWrite ?? 0)})`,
+	);
+	lines.push(`Cost: ${formatCost(usage.cost)}${usage.turns ? ` across ${usage.turns} turn(s)` : ""}`);
+	if (byRole.length > 1) {
+		lines.push("");
+		lines.push("By role:");
+		for (const r of byRole) {
+			const pct = usage.cost && usage.cost > 0 ? Math.round((r.cost / usage.cost) * 100) : 0;
+			const tok = r.input + r.output + r.cacheWrite;
+			lines.push(
+				`  ${r.role} (${r.taskCount} task${r.taskCount === 1 ? "" : "s"}): ${formatCost(r.cost)}${pct ? ` — ${pct}%` : ""}, ${formatTokens(tok)} tok, ${r.turns} turns`,
+			);
+		}
+	}
+	lines.push("");
+	lines.push("Track budget via budgetTotal/budgetWarning/budgetAbort on team run.");
+	return lines.join("\n");
+}