pi-crew 0.1.5 → 0.1.7

package/src/runtime/agent-control.ts

@@ -0,0 +1,64 @@
+import type { PiTeamsConfig } from "../config/config.ts";
+import type { TeamRunManifest } from "../state/types.ts";
+import { appendEvent } from "../state/event-log.ts";
+import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
+import { upsertCrewAgent } from "./crew-agent-records.ts";
+
+export interface CrewControlConfig {
+	enabled: boolean;
+	needsAttentionAfterMs: number;
+}
+
+const DEFAULT_NEEDS_ATTENTION_MS = 60_000;
+
+function positiveInt(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+export function resolveCrewControlConfig(config: PiTeamsConfig | undefined): CrewControlConfig {
+	const raw = config as PiTeamsConfig & { control?: { enabled?: unknown; needsAttentionAfterMs?: unknown } } | undefined;
+	return {
+		enabled: raw?.control?.enabled === false ? false : true,
+		needsAttentionAfterMs: positiveInt(raw?.control?.needsAttentionAfterMs) ?? DEFAULT_NEEDS_ATTENTION_MS,
+	};
+}
+
+export function activityAgeMs(agent: CrewAgentRecord, now = Date.now()): number | undefined {
+	const timestamp = agent.progress?.lastActivityAt ?? agent.startedAt;
+	if (!timestamp) return undefined;
+	const ms = now - new Date(timestamp).getTime();
+	return Number.isFinite(ms) ? Math.max(0, ms) : undefined;
+}
+
+export function formatActivityAge(agent: CrewAgentRecord, now = Date.now()): string | undefined {
+	const age = activityAgeMs(agent, now);
+	if (age === undefined) return undefined;
+	if (age < 1000) return "active now";
+	const seconds = Math.floor(age / 1000);
+	if (seconds < 60) return agent.progress?.activityState === "needs_attention" ? `no activity for ${seconds}s` : `active ${seconds}s ago`;
+	const minutes = Math.floor(seconds / 60);
+	return agent.progress?.activityState === "needs_attention" ? `no activity for ${minutes}m` : `active ${minutes}m ago`;
+}
+
+export function applyAttentionState(manifest: TeamRunManifest, agent: CrewAgentRecord, config: CrewControlConfig, now = Date.now()): CrewAgentRecord {
+	if (!config.enabled || agent.status !== "running") return agent;
+	const age = activityAgeMs(agent, now);
+	if (age === undefined || age <= config.needsAttentionAfterMs) return agent;
+	if (agent.progress?.activityState === "needs_attention") return agent;
+	const updated: CrewAgentRecord = {
+		...agent,
+		progress: {
+			...(agent.progress ?? { recentTools: [], recentOutput: [], toolCount: agent.toolUses ?? 0 }),
+			activityState: "needs_attention",
+		},
+	};
+	upsertCrewAgent(manifest, updated);
+	appendEvent(manifest.eventsPath, {
+		type: "agent.needs_attention",
+		runId: manifest.runId,
+		taskId: agent.taskId,
+		message: `${agent.agent} needs attention (no observed activity for ${Math.floor(age / 1000)}s).`,
+		data: { agentId: agent.id, ageMs: age, needsAttentionAfterMs: config.needsAttentionAfterMs },
+	});
+	return updated;
+}

package/src/runtime/agent-observability.ts

@@ -0,0 +1,88 @@
+import * as fs from "node:fs";
+import type { TeamRunManifest } from "../state/types.ts";
+import { agentOutputPath, readCrewAgents } from "./crew-agent-records.ts";
+import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
+
+export interface TextTailResult {
+	path: string;
+	text: string;
+	bytes: number;
+	truncated: boolean;
+}
+
+export function readTextTail(filePath: string, maxBytes = 64_000): TextTailResult {
+	if (!fs.existsSync(filePath)) return { path: filePath, text: "", bytes: 0, truncated: false };
+	const stat = fs.statSync(filePath);
+	const bytesToRead = Math.min(stat.size, Math.max(0, maxBytes));
+	const fd = fs.openSync(filePath, "r");
+	try {
+		const buffer = Buffer.alloc(bytesToRead);
+		fs.readSync(fd, buffer, 0, bytesToRead, stat.size - bytesToRead);
+		return { path: filePath, text: buffer.toString("utf-8"), bytes: stat.size, truncated: stat.size > bytesToRead };
+	} finally {
+		fs.closeSync(fd);
+	}
+}
+
+function activityText(agent: CrewAgentRecord): string {
+	const parts: string[] = [];
+	if (agent.progress?.activityState) parts.push(agent.progress.activityState);
+	if (agent.progress?.currentTool) parts.push(`tool=${agent.progress.currentTool}`);
+	if (agent.toolUses !== undefined) parts.push(`tools=${agent.toolUses}`);
+	if (agent.progress?.tokens !== undefined) parts.push(`tokens=${agent.progress.tokens}`);
+	if (agent.progress?.turns !== undefined) parts.push(`turns=${agent.progress.turns}`);
+	if (agent.progress?.durationMs !== undefined) parts.push(`durationMs=${agent.progress.durationMs}`);
+	if (agent.progress?.failedTool) parts.push(`failedTool=${agent.progress.failedTool}`);
+	if (agent.progress?.recentOutput?.length) parts.push(`last=${agent.progress.recentOutput.at(-1)}`);
+	return parts.join(" ") || "idle";
+}
+
+function statusGlyph(status: CrewAgentRecord["status"]): string {
+	if (status === "completed") return "✓";
+	if (status === "failed") return "✗";
+	if (status === "running") return "▶";
+	if (status === "cancelled" || status === "stopped") return "■";
+	return "·";
+}
+
+function outputWarning(agent: CrewAgentRecord): string {
+	if (agent.status !== "completed") return "";
+	if (!agent.outputPath || !fs.existsSync(agent.outputPath)) return " no-output";
+	try {
+		return fs.statSync(agent.outputPath).size === 0 ? " no-output" : "";
+	} catch {
+		return " no-output";
+	}
+}
+
+function agentLine(agent: CrewAgentRecord): string {
+	return `- ${statusGlyph(agent.status)} ${agent.taskId} [${agent.status}] ${agent.role}->${agent.agent} runtime=${agent.runtime} ${activityText(agent)}${outputWarning(agent)}${agent.error ? ` error=${agent.error}` : ""}`;
+}
+
+export function buildAgentDashboard(manifest: TeamRunManifest): { text: string; groups: Record<string, CrewAgentRecord[]> } {
+	const agents = readCrewAgents(manifest);
+	const groups: Record<string, CrewAgentRecord[]> = {
+		running: agents.filter((agent) => agent.status === "running"),
+		queued: agents.filter((agent) => agent.status === "queued"),
+		recent: agents.filter((agent) => agent.status !== "running" && agent.status !== "queued"),
+	};
+	const lines = [
+		`Crew agents for ${manifest.runId}`,
+		`Run status: ${manifest.status}`,
+		`Counts: running=${groups.running.length}, queued=${groups.queued.length}, recent=${groups.recent.length}`,
+		"",
+		"## Running",
+		...(groups.running.length ? groups.running.map(agentLine) : ["- (none)"]),
+		"",
+		"## Queued",
+		...(groups.queued.length ? groups.queued.map(agentLine) : ["- (none)"]),
+		"",
+		"## Recent",
+		...(groups.recent.length ? groups.recent.slice(-10).map(agentLine) : ["- (none)"]),
+	];
+	return { text: lines.join("\n"), groups };
+}
+
+export function readAgentOutput(manifest: TeamRunManifest, taskId: string, maxBytes?: number): TextTailResult {
+	return readTextTail(agentOutputPath(manifest, taskId), maxBytes);
+}

package/src/runtime/async-runner.ts

@@ -1,9 +1,36 @@
 import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { TeamRunManifest } from "../state/types.ts";
 
+const require = createRequire(import.meta.url);
+
+function resolveJitiCliPath(): string | undefined {
+	const candidates: Array<() => string> = [
+		() => path.join(path.dirname(require.resolve("jiti/package.json")), "lib/jiti-cli.mjs"),
+		() => path.join(path.dirname(require.resolve("@mariozechner/jiti/package.json")), "lib/jiti-cli.mjs"),
+	];
+	for (const candidate of candidates) {
+		try {
+			const filePath = candidate();
+			if (fs.existsSync(filePath)) return filePath;
+		} catch {
+			// Try the next possible runtime dependency location.
+		}
+	}
+	return undefined;
+}
+
+export function getBackgroundRunnerCommand(runnerPath: string, cwd: string, runId: string): { args: string[]; loader: "jiti" | "strip-types" } {
+	const jitiCliPath = resolveJitiCliPath();
+	const runnerArgs = [runnerPath, "--cwd", cwd, "--run-id", runId];
+	return jitiCliPath
+		? { args: [jitiCliPath, ...runnerArgs], loader: "jiti" }
+		: { args: ["--experimental-strip-types", ...runnerArgs], loader: "strip-types" };
+}
+
 export interface SpawnBackgroundTeamRunResult {
 	pid?: number;
 	logPath: string;
@@ -14,7 +41,9 @@ export function spawnBackgroundTeamRun(manifest: TeamRunManifest): SpawnBackgrou
 	const logPath = path.join(manifest.stateRoot, "background.log");
 	fs.mkdirSync(manifest.stateRoot, { recursive: true });
 	const logFd = fs.openSync(logPath, "a");
-	const child = spawn(process.execPath, ["--experimental-strip-types", runnerPath, "--cwd", manifest.cwd, "--run-id", manifest.runId], {
+	const command = getBackgroundRunnerCommand(runnerPath, manifest.cwd, manifest.runId);
+	fs.appendFileSync(logPath, `[pi-crew] background loader=${command.loader}\n`, "utf-8");
+	const child = spawn(process.execPath, command.args, {
 		cwd: manifest.cwd,
 		detached: true,
 		stdio: ["ignore", logFd, logFd],

package/src/runtime/background-runner.ts

@@ -5,6 +5,7 @@ import { loadRunManifestById, updateRunStatus } from "../state/state-store.ts";
 import { allWorkflows, discoverWorkflows } from "../workflows/discover-workflows.ts";
 import { loadConfig } from "../config/config.ts";
 import { executeTeamRun } from "./team-runner.ts";
+import { resolveCrewRuntime } from "./runtime-resolver.ts";
 
 function argValue(name: string): string | undefined {
 	const index = process.argv.indexOf(name);
@@ -29,8 +30,9 @@ async function main(): Promise<void> {
 		if (!workflow) throw new Error(`Workflow '${manifest.workflow ?? ""}' not found.`);
 		const agents = allAgents(discoverAgents(cwd));
 		const loadedConfig = loadConfig(cwd);
-		const executeWorkers = loadedConfig.config.executeWorkers === true || process.env.PI_TEAMS_EXECUTE_WORKERS === "1";
-		const result = await executeTeamRun({ manifest, tasks, team, workflow, agents, executeWorkers, limits: loadedConfig.config.limits });
+		const runtime = await resolveCrewRuntime(loadedConfig.config);
+		const executeWorkers = runtime.kind === "child-process";
+		const result = await executeTeamRun({ manifest, tasks, team, workflow, agents, executeWorkers, limits: loadedConfig.config.limits, runtime, runtimeConfig: loadedConfig.config.runtime });
 		manifest = result.manifest;
 		tasks = result.tasks;
 		appendEvent(manifest.eventsPath, { type: "async.completed", runId: manifest.runId, data: { status: manifest.status, tasks: tasks.length } });

package/src/runtime/child-pi.ts

@@ -1,14 +1,26 @@
 import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
 import type { AgentConfig } from "../agents/agent-config.ts";
-import { buildPiWorkerArgs, cleanupTempDir } from "./pi-args.ts";
+import { buildPiWorkerArgs, checkCrewDepth, cleanupTempDir } from "./pi-args.ts";
 import { getPiSpawnCommand } from "./pi-spawn.ts";
 
+const POST_EXIT_STDIO_GUARD_MS = 3000;
+const FINAL_DRAIN_MS = 5000;
+const HARD_KILL_MS = 3000;
+
 export interface ChildPiRunInput {
 	cwd: string;
 	task: string;
 	agent: AgentConfig;
 	model?: string;
 	signal?: AbortSignal;
+	transcriptPath?: string;
+	onStdoutLine?: (line: string) => void;
+	onJsonEvent?: (event: unknown) => void;
+	maxDepth?: number;
+	finalDrainMs?: number;
+	hardKillMs?: number;
 }
 
 export interface ChildPiRunResult {
@@ -18,15 +30,87 @@ export interface ChildPiRunResult {
 	error?: string;
 }
 
+function appendTranscript(input: ChildPiRunInput, line: string): void {
+	if (!input.transcriptPath) return;
+	fs.mkdirSync(path.dirname(input.transcriptPath), { recursive: true });
+	fs.appendFileSync(input.transcriptPath, `${line}\n`, "utf-8");
+}
+
+export class ChildPiLineObserver {
+	private buffer = "";
+	private readonly input: ChildPiRunInput;
+
+	constructor(input: ChildPiRunInput) {
+		this.input = input;
+	}
+
+	observe(text: string): void {
+		this.buffer += text;
+		const lines = this.buffer.split(/\r?\n/);
+		this.buffer = lines.pop() ?? "";
+		for (const line of lines) this.emitLine(line);
+	}
+
+	flush(): void {
+		if (!this.buffer) return;
+		const line = this.buffer;
+		this.buffer = "";
+		this.emitLine(line);
+	}
+
+	private emitLine(line: string): void {
+		if (!line.trim()) return;
+		appendTranscript(this.input, line);
+		this.input.onStdoutLine?.(line);
+		try {
+			this.input.onJsonEvent?.(JSON.parse(line));
+		} catch {
+			// Raw stdout is allowed.
+		}
+	}
+}
+
+function observeStdoutChunk(input: ChildPiRunInput, text: string): void {
+	const observer = new ChildPiLineObserver(input);
+	observer.observe(text);
+	observer.flush();
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function isFinalAssistantEvent(event: unknown): boolean {
+	const obj = asRecord(event);
+	if (!obj || obj.type !== "message_end") return false;
+	const message = asRecord(obj.message);
+	const role = message?.role;
+	if (role !== undefined && role !== "assistant") return false;
+	const stopReason = typeof message?.stopReason === "string" ? message.stopReason : typeof obj.stopReason === "string" ? obj.stopReason : undefined;
+	if (stopReason !== undefined && stopReason !== "stop") return false;
+	const content = Array.isArray(message?.content) ? message.content : [];
+	return !content.some((part) => asRecord(part)?.type === "toolCall");
+}
+
 export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResult> {
+	const depth = checkCrewDepth(input.maxDepth);
+	if (depth.blocked) return { exitCode: 1, stdout: "", stderr: `pi-crew depth guard blocked child worker: depth ${depth.depth} >= max ${depth.maxDepth}` };
 	const mock = process.env.PI_TEAMS_MOCK_CHILD_PI;
 	if (mock) {
-		if (mock === "success") return { exitCode: 0, stdout: `Mock child Pi success for ${input.agent.name}\n`, stderr: "" };
-		if (mock === "json-success") return { exitCode: 0, stdout: `${JSON.stringify({ type: "message", message: { role: "assistant", content: [{ type: "text", text: `Mock JSON success for ${input.agent.name}` }] } })}\n${JSON.stringify({ type: "message_end", usage: { input: 10, output: 5, cost: 0.001, turns: 1 } })}\n`, stderr: "" };
+		if (mock === "success") {
+			const stdout = `Mock child Pi success for ${input.agent.name}\n`;
+			observeStdoutChunk(input, stdout);
+			return { exitCode: 0, stdout, stderr: "" };
+		}
+		if (mock === "json-success") {
+			const stdout = `${JSON.stringify({ type: "message", message: { role: "assistant", content: [{ type: "text", text: `Mock JSON success for ${input.agent.name}` }] } })}\n${JSON.stringify({ type: "message_end", usage: { input: 10, output: 5, cost: 0.001, turns: 1 } })}\n`;
+			observeStdoutChunk(input, stdout);
+			return { exitCode: 0, stdout, stderr: "" };
+		}
 		if (mock === "retryable-failure") return { exitCode: 1, stdout: "", stderr: "rate limit: mock failure" };
 		return { exitCode: 1, stdout: "", stderr: `mock failure: ${mock}` };
 	}
-	const built = buildPiWorkerArgs({ task: input.task, agent: input.agent, model: input.model, sessionEnabled: false });
+	const built = buildPiWorkerArgs({ task: input.task, agent: input.agent, model: input.model, sessionEnabled: false, maxDepth: input.maxDepth });
 	const spawnSpec = getPiSpawnCommand(built.args);
 	try {
 		return await new Promise<ChildPiRunResult>((resolve) => {
@@ -38,10 +122,46 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			let stdout = "";
 			let stderr = "";
 			let settled = false;
+			let childExited = false;
+			let postExitGuard: NodeJS.Timeout | undefined;
+			let finalDrainTimer: NodeJS.Timeout | undefined;
+			let hardKillTimer: NodeJS.Timeout | undefined;
+			const finalDrainMs = input.finalDrainMs ?? FINAL_DRAIN_MS;
+			const hardKillMs = input.hardKillMs ?? HARD_KILL_MS;
+			let forcedFinalDrain = false;
+			const lineObserver = new ChildPiLineObserver({
+				...input,
+				onJsonEvent: (event) => {
+					input.onJsonEvent?.(event);
+					if (!isFinalAssistantEvent(event) || childExited || settled || finalDrainTimer) return;
+					finalDrainTimer = setTimeout(() => {
+						if (settled || childExited) return;
+						forcedFinalDrain = true;
+						try { child.kill(process.platform === "win32" ? undefined : "SIGTERM"); } catch {}
+						hardKillTimer = setTimeout(() => {
+							if (settled || childExited) return;
+							try { child.kill(process.platform === "win32" ? undefined : "SIGKILL"); } catch {}
+						}, hardKillMs);
+						hardKillTimer.unref?.();
+					}, finalDrainMs);
+					finalDrainTimer.unref?.();
+				},
+			});
+
+			const clearFinalDrainTimers = (): void => {
+				if (finalDrainTimer) clearTimeout(finalDrainTimer);
+				if (hardKillTimer) clearTimeout(hardKillTimer);
+				finalDrainTimer = undefined;
+				hardKillTimer = undefined;
+			};
 
 			const settle = (result: ChildPiRunResult): void => {
 				if (settled) return;
 				settled = true;
+				if (postExitGuard) clearTimeout(postExitGuard);
+				clearFinalDrainTimers();
+				lineObserver.flush();
+				input.signal?.removeEventListener("abort", abort);
 				cleanupTempDir(built.tempDir);
 				resolve(result);
 			};
@@ -56,7 +176,9 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 
 			input.signal?.addEventListener("abort", abort, { once: true });
 			child.stdout?.on("data", (chunk: Buffer) => {
-				stdout += chunk.toString("utf-8");
+				const text = chunk.toString("utf-8");
+				stdout += text;
+				lineObserver.observe(text);
 			});
 			child.stderr?.on("data", (chunk: Buffer) => {
 				stderr += chunk.toString("utf-8");
@@ -64,9 +186,17 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			child.on("error", (error) => {
 				settle({ exitCode: null, stdout, stderr, error: error.message });
 			});
+			child.on("exit", () => {
+				childExited = true;
+				clearFinalDrainTimers();
+				postExitGuard = setTimeout(() => {
+					child.stdout?.destroy();
+					child.stderr?.destroy();
+				}, POST_EXIT_STDIO_GUARD_MS);
+				postExitGuard.unref?.();
+			});
 			child.on("close", (exitCode) => {
-				input.signal?.removeEventListener("abort", abort);
-				settle({ exitCode, stdout, stderr });
+				settle({ exitCode, stdout, stderr, ...(forcedFinalDrain && !stderr.trim() ? { error: `Child Pi did not exit within ${finalDrainMs}ms after final assistant message; termination was requested.` } : {}) });
 			});
 		});
 	} finally {

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

@@ -0,0 +1,137 @@
+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));
+}
+
+function nextAgentEventSeq(filePath: string): number {
+	if (!fs.existsSync(filePath)) return 1;
+	let max = 0;
+	for (const line of fs.readFileSync(filePath, "utf-8").split(/\r?\n/)) {
+		if (!line.trim()) continue;
+		try {
+			const parsed = JSON.parse(line) as { seq?: unknown };
+			if (typeof parsed.seq === "number" && Number.isFinite(parsed.seq)) max = Math.max(max, parsed.seq);
+			else max += 1;
+		} catch {
+			max += 1;
+		}
+	}
+	return max + 1;
+}
+
+export function appendCrewAgentEvent(manifest: TeamRunManifest, taskId: string, event: unknown): void {
+	fs.mkdirSync(agentStateDir(manifest, taskId), { recursive: true });
+	const filePath = agentEventsPath(manifest, taskId);
+	fs.appendFileSync(filePath, `${JSON.stringify({ seq: nextAgentEventSeq(filePath), time: new Date().toISOString(), event })}\n`, "utf-8");
+}
+
+export interface CrewAgentEventCursorOptions {
+	sinceSeq?: number;
+	limit?: number;
+}
+
+export function readCrewAgentEvents(manifest: TeamRunManifest, taskId: string): unknown[] {
+	return readCrewAgentEventsCursor(manifest, taskId).events;
+}
+
+export function readCrewAgentEventsCursor(manifest: TeamRunManifest, taskId: string, options: CrewAgentEventCursorOptions = {}): { path: string; events: unknown[]; nextSeq: number; total: number } {
+	const filePath = agentEventsPath(manifest, taskId);
+	if (!fs.existsSync(filePath)) return { path: filePath, events: [], nextSeq: options.sinceSeq ?? 0, total: 0 };
+	const sinceSeq = typeof options.sinceSeq === "number" && Number.isInteger(options.sinceSeq) && options.sinceSeq >= 0 ? options.sinceSeq : 0;
+	const limit = typeof options.limit === "number" && Number.isInteger(options.limit) && options.limit >= 0 ? options.limit : undefined;
+	const parsed = fs.readFileSync(filePath, "utf-8").split(/\r?\n/).filter(Boolean).map((line, index) => {
+		try {
+			const event = JSON.parse(line) as Record<string, unknown>;
+			if (typeof event.seq !== "number") event.seq = index + 1;
+			return event;
+		} catch {
+			return { seq: index + 1, raw: line };
+		}
+	});
+	const filtered = parsed.filter((event) => typeof event.seq === "number" && event.seq > sinceSeq);
+	const events = limit !== undefined ? filtered.slice(0, limit) : filtered;
+	const returnedMaxSeq = events.reduce((max, event) => typeof event.seq === "number" ? Math.max(max, event.seq) : max, sinceSeq);
+	return { path: filePath, events, nextSeq: returnedMaxSeq, total: filtered.length };
+}
+
+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,54 @@
+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";
+	failedTool?: string;
+}
+
+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";
+}