pi-crew 0.1.5 → 0.1.6

package/src/runtime/crew-agent-records.ts

@@ -0,0 +1,99 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { atomicWriteJson, readJsonFile } from "../state/atomic-write.ts";
+import type { CrewAgentProgress, CrewAgentRecord, CrewRuntimeKind } from "./crew-agent-runtime.ts";
+import { taskStatusToAgentStatus } from "./crew-agent-runtime.ts";
+
+export function agentsPath(manifest: TeamRunManifest): string {
+	return path.join(manifest.stateRoot, "agents.json");
+}
+
+export function agentStateDir(manifest: TeamRunManifest, taskId: string): string {
+	return path.join(manifest.stateRoot, "agents", taskId);
+}
+
+export function agentStatusPath(manifest: TeamRunManifest, taskId: string): string {
+	return path.join(agentStateDir(manifest, taskId), "status.json");
+}
+
+export function agentEventsPath(manifest: TeamRunManifest, taskId: string): string {
+	return path.join(agentStateDir(manifest, taskId), "events.jsonl");
+}
+
+export function agentOutputPath(manifest: TeamRunManifest, taskId: string): string {
+	return path.join(agentStateDir(manifest, taskId), "output.log");
+}
+
+export function readCrewAgents(manifest: TeamRunManifest): CrewAgentRecord[] {
+	return readJsonFile<CrewAgentRecord[]>(agentsPath(manifest)) ?? [];
+}
+
+export function saveCrewAgents(manifest: TeamRunManifest, records: CrewAgentRecord[]): void {
+	fs.mkdirSync(manifest.stateRoot, { recursive: true });
+	atomicWriteJson(agentsPath(manifest), records);
+	for (const record of records) writeCrewAgentStatus(manifest, record);
+}
+
+export function upsertCrewAgent(manifest: TeamRunManifest, record: CrewAgentRecord): void {
+	const records = readCrewAgents(manifest).filter((item) => item.id !== record.id);
+	records.push(record);
+	saveCrewAgents(manifest, records);
+	writeCrewAgentStatus(manifest, record);
+}
+
+export function writeCrewAgentStatus(manifest: TeamRunManifest, record: CrewAgentRecord): void {
+	fs.mkdirSync(agentStateDir(manifest, record.taskId), { recursive: true });
+	atomicWriteJson(agentStatusPath(manifest, record.taskId), record);
+}
+
+export function readCrewAgentStatus(manifest: TeamRunManifest, taskOrAgentId: string): CrewAgentRecord | undefined {
+	const taskId = taskOrAgentId.includes(":") ? taskOrAgentId.split(":").pop()! : taskOrAgentId;
+	return readJsonFile<CrewAgentRecord>(agentStatusPath(manifest, taskId));
+}
+
+export function appendCrewAgentEvent(manifest: TeamRunManifest, taskId: string, event: unknown): void {
+	fs.mkdirSync(agentStateDir(manifest, taskId), { recursive: true });
+	fs.appendFileSync(agentEventsPath(manifest, taskId), `${JSON.stringify({ time: new Date().toISOString(), event })}\n`, "utf-8");
+}
+
+export function readCrewAgentEvents(manifest: TeamRunManifest, taskId: string): unknown[] {
+	const filePath = agentEventsPath(manifest, taskId);
+	if (!fs.existsSync(filePath)) return [];
+	return fs.readFileSync(filePath, "utf-8").split(/\r?\n/).filter(Boolean).map((line) => {
+		try { return JSON.parse(line) as unknown; } catch { return { raw: line }; }
+	});
+}
+
+export function appendCrewAgentOutput(manifest: TeamRunManifest, taskId: string, text: string): void {
+	if (!text.trim()) return;
+	fs.mkdirSync(agentStateDir(manifest, taskId), { recursive: true });
+	fs.appendFileSync(agentOutputPath(manifest, taskId), `${text}\n`, "utf-8");
+}
+
+export function emptyCrewAgentProgress(): CrewAgentProgress {
+	return { recentTools: [], recentOutput: [], toolCount: 0 };
+}
+
+export function recordFromTask(manifest: TeamRunManifest, task: TeamTaskState, runtime: CrewRuntimeKind): CrewAgentRecord {
+	return {
+		id: `${manifest.runId}:${task.id}`,
+		runId: manifest.runId,
+		taskId: task.id,
+		agent: task.agent,
+		role: task.role,
+		runtime,
+		status: taskStatusToAgentStatus(task.status),
+		startedAt: task.startedAt ?? new Date().toISOString(),
+		completedAt: task.finishedAt,
+		resultArtifactPath: task.resultArtifact?.path,
+		transcriptPath: task.transcriptArtifact?.path ?? task.logArtifact?.path,
+		statusPath: agentStatusPath(manifest, task.id),
+		eventsPath: agentEventsPath(manifest, task.id),
+		outputPath: agentOutputPath(manifest, task.id),
+		toolUses: task.agentProgress?.toolCount,
+		jsonEvents: task.jsonEvents,
+		progress: task.agentProgress,
+		error: task.error,
+	};
+}

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

@@ -0,0 +1,53 @@
+import type { TeamTaskStatus } from "../state/contracts.ts";
+
+export type CrewRuntimeKind = "scaffold" | "child-process" | "live-session";
+export type CrewAgentStatus = "queued" | "running" | "completed" | "failed" | "cancelled" | "stopped";
+
+export interface CrewAgentRecentTool {
+	tool: string;
+	args?: string;
+	endedAt: string;
+}
+
+export interface CrewAgentProgress {
+	currentTool?: string;
+	currentToolArgs?: string;
+	currentToolStartedAt?: string;
+	recentTools: CrewAgentRecentTool[];
+	recentOutput: string[];
+	toolCount: number;
+	tokens?: number;
+	turns?: number;
+	durationMs?: number;
+	lastActivityAt?: string;
+	activityState?: "active" | "needs_attention" | "stale";
+}
+
+export interface CrewAgentRecord {
+	id: string;
+	runId: string;
+	taskId: string;
+	agent: string;
+	role: string;
+	runtime: CrewRuntimeKind;
+	status: CrewAgentStatus;
+	startedAt: string;
+	completedAt?: string;
+	resultArtifactPath?: string;
+	transcriptPath?: string;
+	statusPath?: string;
+	eventsPath?: string;
+	outputPath?: string;
+	toolUses?: number;
+	jsonEvents?: number;
+	progress?: CrewAgentProgress;
+	error?: string;
+}
+
+export function taskStatusToAgentStatus(status: TeamTaskStatus): CrewAgentStatus {
+	if (status === "completed") return "completed";
+	if (status === "failed") return "failed";
+	if (status === "cancelled") return "cancelled";
+	if (status === "running") return "running";
+	return "queued";
+}

package/src/runtime/group-join.ts

@@ -0,0 +1,88 @@
+import type { CrewRuntimeConfig } from "../config/config.ts";
+import { writeArtifact } from "../state/artifact-store.ts";
+import { appendEvent } from "../state/event-log.ts";
+import { appendMailboxMessage } from "../state/mailbox.ts";
+import type { ArtifactDescriptor, TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { aggregateTaskOutputs } from "./task-output-context.ts";
+
+export type CrewGroupJoinMode = "off" | "group" | "smart";
+
+export interface CrewGroupJoinDelivery {
+	batchId: string;
+	mode: CrewGroupJoinMode;
+	partial: boolean;
+	taskIds: string[];
+	completed: string[];
+	failed: string[];
+	skipped: string[];
+	remaining: string[];
+	artifact?: ArtifactDescriptor;
+	messageId?: string;
+}
+
+export function resolveGroupJoinMode(runtime?: CrewRuntimeConfig): CrewGroupJoinMode {
+	return runtime?.groupJoin ?? "smart";
+}
+
+export function shouldGroupJoin(mode: CrewGroupJoinMode, batch: TeamTaskState[]): boolean {
+	if (mode === "off") return false;
+	if (mode === "group") return batch.length > 0;
+	return batch.length > 1;
+}
+
+function batchIdFor(runId: string, taskIds: string[]): string {
+	return `${runId}_${taskIds.join("+").replace(/[^a-zA-Z0-9_+-]/g, "_")}`;
+}
+
+function statusList(tasks: TeamTaskState[], status: TeamTaskState["status"]): string[] {
+	return tasks.filter((task) => task.status === status).map((task) => task.id);
+}
+
+export function deliverGroupJoin(input: {
+	manifest: TeamRunManifest;
+	mode: CrewGroupJoinMode;
+	batch: TeamTaskState[];
+	allTasks: TeamTaskState[];
+	partial?: boolean;
+}): CrewGroupJoinDelivery | undefined {
+	if (!shouldGroupJoin(input.mode, input.batch)) return undefined;
+	const taskIds = input.batch.map((task) => task.id);
+	const latest = taskIds.map((id) => input.allTasks.find((task) => task.id === id)).filter((task): task is TeamTaskState => Boolean(task));
+	const completed = statusList(latest, "completed");
+	const failed = statusList(latest, "failed");
+	const skipped = statusList(latest, "skipped");
+	const remaining = latest.filter((task) => task.status === "queued" || task.status === "running").map((task) => task.id);
+	const partial = input.partial ?? remaining.length > 0;
+	const batchId = batchIdFor(input.manifest.runId, taskIds);
+	const summary = aggregateTaskOutputs(latest);
+	const delivery: CrewGroupJoinDelivery = { batchId, mode: input.mode, partial, taskIds, completed, failed, skipped, remaining };
+	const content = `${JSON.stringify({ ...delivery, createdAt: new Date().toISOString() }, null, 2)}\n`;
+	const artifact = writeArtifact(input.manifest.artifactsRoot, {
+		kind: "metadata",
+		relativePath: `metadata/group-joins/${batchId}.json`,
+		producer: "group-join",
+		content,
+	});
+	const mailbox = appendMailboxMessage(input.manifest, {
+		direction: "outbox",
+		from: "group-join",
+		to: "leader",
+		body: [
+			`Group join ${partial ? "partial" : "completed"}: ${taskIds.join(", ")}`,
+			`Completed: ${completed.join(", ") || "none"}`,
+			`Failed: ${failed.join(", ") || "none"}`,
+			`Skipped: ${skipped.join(", ") || "none"}`,
+			`Remaining: ${remaining.join(", ") || "none"}`,
+			"",
+			summary,
+		].join("\n"),
+		status: "delivered",
+	});
+	appendEvent(input.manifest.eventsPath, {
+		type: partial ? "agent.group_join.partial" : "agent.group_join.completed",
+		runId: input.manifest.runId,
+		message: `Group join ${partial ? "partial" : "completed"} for ${taskIds.length} task(s).`,
+		data: { ...delivery, artifactPath: artifact.path, messageId: mailbox.id },
+	});
+	return { ...delivery, artifact, messageId: mailbox.id };
+}

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

@@ -0,0 +1,33 @@
+import type { AgentConfig } from "../agents/agent-config.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import type { WorkflowStep } from "../workflows/workflow-config.ts";
+import { isLiveSessionRuntimeAvailable } from "./runtime-resolver.ts";
+
+export interface LiveSessionSpawnInput {
+	manifest: TeamRunManifest;
+	task: TeamTaskState;
+	step: WorkflowStep;
+	agent: AgentConfig;
+	prompt: string;
+}
+
+export interface LiveSessionUnavailableResult {
+	available: false;
+	reason: string;
+}
+
+export interface LiveSessionPlannedResult {
+	available: true;
+	reason: string;
+}
+
+export async function probeLiveSessionRuntime(): Promise<LiveSessionUnavailableResult | LiveSessionPlannedResult> {
+	const availability = await isLiveSessionRuntimeAvailable();
+	if (!availability.available) return { available: false, reason: availability.reason ?? "Live-session runtime is unavailable." };
+	return { available: true, reason: "Live-session SDK exports are available. Full session execution is intentionally gated behind the runtime adapter implementation." };
+}
+
+export async function runLiveSessionTask(_input: LiveSessionSpawnInput): Promise<never> {
+	const probe = await probeLiveSessionRuntime();
+	throw new Error(probe.available ? "Live-session runtime adapter is not enabled yet; use child-process runtime or scaffold." : probe.reason);
+}

package/src/runtime/policy-engine.ts

@@ -20,14 +20,37 @@ function decision(action: PolicyDecisionAction, reason: PolicyDecisionReason, me
 	};
 }
 
+function taskDepth(task: TeamTaskState, tasksById: Map<string, TeamTaskState>): number {
+	let depth = 0;
+	let current = task.graph?.parentId;
+	const seen = new Set<string>();
+	while (current && !seen.has(current)) {
+		seen.add(current);
+		depth += 1;
+		current = tasksById.get(current)?.graph?.parentId;
+	}
+	return depth;
+}
+
 export function evaluateCrewPolicy(input: PolicyEngineInput): PolicyDecision[] {
 	const decisions: PolicyDecision[] = [];
 	const maxTasksPerRun = input.limits?.maxTasksPerRun;
 	if (maxTasksPerRun !== undefined && input.tasks.length > maxTasksPerRun) {
 		decisions.push(decision("block", "limit_exceeded", `Run has ${input.tasks.length} tasks, exceeding maxTasksPerRun=${maxTasksPerRun}.`));
 	}
+	const runningCount = input.tasks.filter((task) => task.status === "running").length;
+	if (input.limits?.maxConcurrentWorkers !== undefined && runningCount > input.limits.maxConcurrentWorkers) {
+		decisions.push(decision("block", "limit_exceeded", `Run has ${runningCount} running workers, exceeding maxConcurrentWorkers=${input.limits.maxConcurrentWorkers}.`));
+	}
+	const tasksById = new Map(input.tasks.map((task) => [task.id, task]));
 
 	for (const task of input.tasks) {
+		if (input.limits?.maxChildrenPerTask !== undefined && (task.graph?.children.length ?? 0) > input.limits.maxChildrenPerTask) {
+			decisions.push(decision("block", "limit_exceeded", `Task has ${task.graph?.children.length ?? 0} children, exceeding maxChildrenPerTask=${input.limits.maxChildrenPerTask}.`, task.id));
+		}
+		if (input.limits?.maxTaskDepth !== undefined && taskDepth(task, tasksById) > input.limits.maxTaskDepth) {
+			decisions.push(decision("block", "limit_exceeded", `Task graph depth exceeds maxTaskDepth=${input.limits.maxTaskDepth}.`, task.id));
+		}
 		if (task.status === "failed") {
 			const retryCount = task.policy?.retryCount ?? 0;
 			const maxRetries = input.limits?.maxRetriesPerTask ?? 0;

package/src/runtime/recovery-recipes.ts

@@ -0,0 +1,74 @@
+import type { PolicyDecision, PolicyDecisionReason } from "../state/types.ts";
+
+export type FailureScenario = "trust_prompt_unresolved" | "prompt_misdelivery" | "stale_branch" | "compile_red_cross_crate" | "mcp_handshake_failure" | "partial_plugin_startup" | "provider_failure" | "task_failed" | "worker_stale" | "green_unsatisfied";
+export type RecoveryStep = "accept_trust_prompt" | "redirect_prompt_to_agent" | "rebase_branch" | "clean_build" | "retry_mcp_handshake" | "restart_plugin" | "restart_worker" | "rerun_task" | "collect_verification_evidence" | "escalate_to_human";
+export type RecoveryResultState = "planned" | "skipped" | "escalation_required";
+
+export interface RecoveryRecipe {
+	scenario: FailureScenario;
+	steps: RecoveryStep[];
+	maxAttempts: number;
+	escalationPolicy: "alert_human" | "log_and_continue" | "abort";
+}
+
+export interface RecoveryLedgerEntry {
+	scenario: FailureScenario;
+	taskId?: string;
+	decisionReason: PolicyDecisionReason;
+	attempt: number;
+	state: RecoveryResultState;
+	steps: RecoveryStep[];
+	message: string;
+	createdAt: string;
+}
+
+export interface RecoveryLedger {
+	entries: RecoveryLedgerEntry[];
+}
+
+export function scenarioForPolicyReason(reason: PolicyDecisionReason): FailureScenario {
+	switch (reason) {
+		case "branch_stale": return "stale_branch";
+		case "worker_stale": return "worker_stale";
+		case "green_unsatisfied": return "green_unsatisfied";
+		case "task_failed": return "task_failed";
+		default: return "provider_failure";
+	}
+}
+
+export function recipeFor(scenario: FailureScenario): RecoveryRecipe {
+	switch (scenario) {
+		case "trust_prompt_unresolved": return { scenario, steps: ["accept_trust_prompt"], maxAttempts: 1, escalationPolicy: "alert_human" };
+		case "prompt_misdelivery": return { scenario, steps: ["redirect_prompt_to_agent"], maxAttempts: 1, escalationPolicy: "alert_human" };
+		case "stale_branch": return { scenario, steps: ["rebase_branch", "clean_build"], maxAttempts: 1, escalationPolicy: "alert_human" };
+		case "compile_red_cross_crate": return { scenario, steps: ["clean_build"], maxAttempts: 1, escalationPolicy: "alert_human" };
+		case "mcp_handshake_failure": return { scenario, steps: ["retry_mcp_handshake"], maxAttempts: 1, escalationPolicy: "abort" };
+		case "partial_plugin_startup": return { scenario, steps: ["restart_plugin", "retry_mcp_handshake"], maxAttempts: 1, escalationPolicy: "log_and_continue" };
+		case "worker_stale": return { scenario, steps: ["restart_worker"], maxAttempts: 1, escalationPolicy: "alert_human" };
+		case "green_unsatisfied": return { scenario, steps: ["collect_verification_evidence"], maxAttempts: 1, escalationPolicy: "alert_human" };
+		case "task_failed": return { scenario, steps: ["rerun_task"], maxAttempts: 1, escalationPolicy: "alert_human" };
+		case "provider_failure": return { scenario, steps: ["restart_worker"], maxAttempts: 1, escalationPolicy: "alert_human" };
+	}
+}
+
+export function buildRecoveryLedger(decisions: PolicyDecision[], previous: RecoveryLedger = { entries: [] }): RecoveryLedger {
+	const entries = [...previous.entries];
+	for (const item of decisions) {
+		if (!["retry", "escalate", "block"].includes(item.action)) continue;
+		const scenario = scenarioForPolicyReason(item.reason);
+		const recipe = recipeFor(scenario);
+		const priorAttempts = entries.filter((entry) => entry.scenario === scenario && entry.taskId === item.taskId).length;
+		const attempt = priorAttempts + 1;
+		entries.push({
+			scenario,
+			taskId: item.taskId,
+			decisionReason: item.reason,
+			attempt,
+			state: attempt <= recipe.maxAttempts && item.action !== "block" ? "planned" : "escalation_required",
+			steps: attempt <= recipe.maxAttempts ? recipe.steps : ["escalate_to_human"],
+			message: item.message,
+			createdAt: new Date().toISOString(),
+		});
+	}
+	return { entries };
+}

package/src/runtime/role-permission.ts

@@ -0,0 +1,28 @@
+export type RolePermissionMode = "read_only" | "workspace_write" | "danger_full_access" | "explicit_confirm";
+
+const READ_ONLY_ROLES = new Set(["explorer", "reviewer", "security-reviewer", "verifier", "analyst", "critic", "planner", "writer"]);
+const WRITE_ROLES = new Set(["executor", "test-engineer"]);
+const READ_ONLY_COMMANDS = new Set(["cat", "head", "tail", "less", "more", "wc", "ls", "find", "grep", "rg", "awk", "sed", "echo", "printf", "which", "where", "whoami", "pwd", "env", "printenv", "date", "df", "du", "uname", "file", "stat", "diff", "sort", "uniq", "tr", "cut", "paste", "test", "true", "false", "type", "readlink", "realpath", "basename", "dirname", "sha256sum", "md5sum", "xxd", "hexdump", "od", "strings", "tree", "jq", "git", "gh"]);
+
+export interface PermissionCheckResult {
+	allowed: boolean;
+	mode: RolePermissionMode;
+	reason?: string;
+}
+
+export function permissionForRole(role: string): RolePermissionMode {
+	if (READ_ONLY_ROLES.has(role)) return "read_only";
+	if (WRITE_ROLES.has(role)) return "workspace_write";
+	return "workspace_write";
+}
+
+export function isReadOnlyCommand(command: string): boolean {
+	const first = command.trim().split(/\s+/)[0]?.split(/[\\/]/).pop() ?? "";
+	return READ_ONLY_COMMANDS.has(first) && !/\s(-i|--in-place)\b|\s>{1,2}\s|\brm\b|\bmv\b|\bcp\b|\bnpm\s+install\b|\bgit\s+(commit|push|merge|rebase|reset|checkout)\b/.test(command);
+}
+
+export function checkRolePermission(role: string, command: string): PermissionCheckResult {
+	const mode = permissionForRole(role);
+	if (mode === "read_only" && !isReadOnlyCommand(command)) return { allowed: false, mode, reason: `Role '${role}' is read-only and command may modify state.` };
+	return { allowed: true, mode };
+}

package/src/runtime/runtime-resolver.ts

@@ -0,0 +1,75 @@
+import type { PiTeamsConfig } from "../config/config.ts";
+import type { CrewRuntimeKind } from "./crew-agent-runtime.ts";
+
+export type CrewRuntimeMode = "auto" | "scaffold" | "child-process" | "live-session";
+
+export interface CrewRuntimeCapabilities {
+	kind: CrewRuntimeKind;
+	requestedMode: CrewRuntimeMode;
+	available: boolean;
+	fallback?: CrewRuntimeKind;
+	steer: boolean;
+	resume: boolean;
+	liveToolActivity: boolean;
+	transcript: boolean;
+	reason?: string;
+}
+
+export async function isLiveSessionRuntimeAvailable(timeoutMs = 1500, env: NodeJS.ProcessEnv = process.env): Promise<{ available: boolean; reason?: string }> {
+	if (env.PI_CREW_ENABLE_EXPERIMENTAL_LIVE_SESSION !== "1") {
+		return { available: false, reason: "Live-session runtime adapter is experimental and disabled. Set PI_CREW_ENABLE_EXPERIMENTAL_LIVE_SESSION=1 to probe SDK support." };
+	}
+	const probe = async (): Promise<{ available: boolean; reason?: string }> => {
+		try {
+			const mod = await import("@mariozechner/pi-coding-agent");
+			const api = mod as Record<string, unknown>;
+			const required = ["createAgentSession", "DefaultResourceLoader", "SessionManager", "SettingsManager"];
+			const missing = required.filter((name) => typeof api[name] === "undefined");
+			if (missing.length) return { available: false, reason: `Pi SDK live-session exports missing: ${missing.join(", ")}.` };
+			return { available: true };
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return { available: false, reason: `Could not load optional Pi SDK live-session runtime: ${message}` };
+		}
+	};
+	let timer: NodeJS.Timeout | undefined;
+	try {
+		return await Promise.race([
+			probe(),
+			new Promise<{ available: boolean; reason: string }>((resolve) => {
+				timer = setTimeout(() => resolve({ available: false, reason: `Timed out probing optional Pi SDK live-session runtime after ${timeoutMs}ms.` }), timeoutMs);
+				timer.unref?.();
+			}),
+		]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+
+export async function resolveCrewRuntime(config: PiTeamsConfig, env: NodeJS.ProcessEnv = process.env): Promise<CrewRuntimeCapabilities> {
+	const requestedMode = config.runtime?.mode ?? "auto";
+	const executeWorkers = config.executeWorkers === true || env.PI_TEAMS_EXECUTE_WORKERS === "1";
+	if (requestedMode === "scaffold") return scaffoldCaps(requestedMode);
+	if (requestedMode === "child-process") return childCaps(requestedMode, executeWorkers ? undefined : "child-process requested but executeWorkers is not enabled; caller should refuse or fall back explicitly.");
+	if (requestedMode === "live-session" || (requestedMode === "auto" && config.runtime?.preferLiveSession === true)) {
+		const live = await isLiveSessionRuntimeAvailable(1500, env);
+		if (live.available) return liveCaps(requestedMode);
+		if (requestedMode === "live-session" && config.runtime?.allowChildProcessFallback === false) return { ...scaffoldCaps(requestedMode), available: false, reason: live.reason };
+		if (executeWorkers) return { ...childCaps(requestedMode), fallback: "child-process", reason: live.reason };
+		return { ...scaffoldCaps(requestedMode), fallback: "scaffold", reason: live.reason };
+	}
+	if (executeWorkers) return childCaps(requestedMode);
+	return scaffoldCaps(requestedMode);
+}
+
+function scaffoldCaps(requestedMode: CrewRuntimeMode): CrewRuntimeCapabilities {
+	return { kind: "scaffold", requestedMode, available: true, steer: false, resume: false, liveToolActivity: false, transcript: false };
+}
+
+function childCaps(requestedMode: CrewRuntimeMode, reason?: string): CrewRuntimeCapabilities {
+	return { kind: "child-process", requestedMode, available: true, steer: false, resume: false, liveToolActivity: false, transcript: true, ...(reason ? { reason } : {}) };
+}
+
+function liveCaps(requestedMode: CrewRuntimeMode): CrewRuntimeCapabilities {
+	return { kind: "live-session", requestedMode, available: true, steer: true, resume: true, liveToolActivity: true, transcript: true };
+}

package/src/runtime/session-usage.ts

@@ -0,0 +1,79 @@
+import * as fs from "node:fs";
+import type { UsageState } from "../state/types.ts";
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function numberField(obj: Record<string, unknown>, keys: string[]): number | undefined {
+	for (const key of keys) {
+		const value = obj[key];
+		if (typeof value === "number" && Number.isFinite(value)) return value;
+	}
+	return undefined;
+}
+
+function usageFromValue(value: unknown): UsageState | undefined {
+	const obj = asRecord(value);
+	if (!obj) return undefined;
+	const direct: UsageState = {
+		input: numberField(obj, ["input", "inputTokens", "input_tokens"]),
+		output: numberField(obj, ["output", "outputTokens", "output_tokens"]),
+		cacheRead: numberField(obj, ["cacheRead", "cache_read", "cacheReadTokens", "cache_read_tokens"]),
+		cacheWrite: numberField(obj, ["cacheWrite", "cache_write", "cacheWriteTokens", "cache_write_tokens"]),
+		cost: numberField(obj, ["cost", "costUsd", "cost_usd"]),
+		turns: numberField(obj, ["turns", "turnCount", "turn_count"]),
+	};
+	if (Object.values(direct).some((entry) => entry !== undefined)) return direct;
+	for (const key of ["usage", "tokenUsage", "tokens", "stats"]) {
+		const nested = usageFromValue(obj[key]);
+		if (nested) return nested;
+	}
+	const message = asRecord(obj.message);
+	return message ? usageFromValue(message.usage) : undefined;
+}
+
+function addUsage(total: UsageState, usage: UsageState): UsageState {
+	return {
+		input: (total.input ?? 0) + (usage.input ?? 0),
+		output: (total.output ?? 0) + (usage.output ?? 0),
+		cacheRead: (total.cacheRead ?? 0) + (usage.cacheRead ?? 0),
+		cacheWrite: (total.cacheWrite ?? 0) + (usage.cacheWrite ?? 0),
+		cost: (total.cost ?? 0) + (usage.cost ?? 0),
+		turns: (total.turns ?? 0) + (usage.turns ?? 0),
+	};
+}
+
+function compactUsage(total: UsageState, foundKeys: Set<keyof UsageState>): UsageState | undefined {
+	if (foundKeys.size === 0) return undefined;
+	const compact: UsageState = {};
+	for (const key of foundKeys) compact[key] = total[key];
+	return compact;
+}
+
+export function parseSessionUsageFromJsonlText(text: string): UsageState | undefined {
+	let total: UsageState = {};
+	const foundKeys = new Set<keyof UsageState>();
+	for (const line of text.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		try {
+			const usage = usageFromValue(JSON.parse(trimmed) as unknown);
+			if (!usage) continue;
+			for (const key of Object.keys(usage) as Array<keyof UsageState>) foundKeys.add(key);
+			total = addUsage(total, usage);
+		} catch {
+			// Session JSONL can contain partial/corrupt lines after interrupted workers.
+		}
+	}
+	return compactUsage(total, foundKeys);
+}
+
+export function parseSessionUsage(filePath: string): UsageState | undefined {
+	try {
+		if (!fs.existsSync(filePath)) return undefined;
+		return parseSessionUsageFromJsonlText(fs.readFileSync(filePath, "utf-8"));
+	} catch {
+		return undefined;
+	}
+}