pi-crew 0.1.45 → 0.1.46

package/src/runtime/heartbeat-watcher.ts

@@ -1,124 +1,124 @@
-import type { NotificationDescriptor } from "../extension/notification-router.ts";
-import type { MetricRegistry } from "../observability/metric-registry.ts";
-import { appendEvent } from "../state/event-log.ts";
-import { loadRunManifestById } from "../state/state-store.ts";
-import type { TeamRunManifest } from "../state/types.ts";
-import { logInternalError } from "../utils/internal-error.ts";
-import type { ManifestCache } from "./manifest-cache.ts";
-import { classifyHeartbeat, DEFAULT_GRADIENT_THRESHOLDS, heartbeatAgeMs, type GradientThresholds, type HeartbeatLevel } from "./heartbeat-gradient.ts";
-
-export interface HeartbeatWatcherRouter {
-	enqueue(notification: NotificationDescriptor): boolean;
-}
-
-export interface HeartbeatWatcherOptions {
-	cwd: string;
-	pollIntervalMs?: number;
-	thresholds?: GradientThresholds;
-	manifestCache: ManifestCache;
-	registry: MetricRegistry;
-	router: HeartbeatWatcherRouter;
-	deadletterTickThreshold?: number;
-	onDead?: (runId: string, taskId: string, elapsed: number) => void;
-	onDeadletterTrigger?: (manifest: TeamRunManifest, taskId: string) => void;
-}
-
-/**
- * Polls running runs for heartbeat staleness.
- *
- * Uses recursive setTimeout to avoid timer storms.
- * Cleanup is done in the same pass — no second scan over manifests.
- * Keys for runs that disappear from the cache are cleaned via staleness-age policy
- * rather than being leaked forever.
- */
-export class HeartbeatWatcher {
-	private timer?: ReturnType<typeof setTimeout>;
-	private lastLevel = new Map<string, HeartbeatLevel>();
-	private consecutiveDead = new Map<string, number>();
-	private lastSeen = new Map<string, number>(); // key → last time it was active
-	/** Max age (ms) to retain a stale key before garbage-collecting it. */
-	private readonly maxKeyAgeMs = 600_000; // 10 minutes
-	private readonly opts: HeartbeatWatcherOptions;
-
-	constructor(opts: HeartbeatWatcherOptions) {
-		this.opts = opts;
-	}
-
-	start(): void {
-		this.dispose();
-		this.scheduleTick();
-	}
-
-	private scheduleTick(): void {
-		this.timer = setTimeout(() => this.tick(), this.opts.pollIntervalMs ?? 5000);
-		this.timer.unref();
-	}
-
-	tick(now = Date.now()): void {
-		try {
-			this.tickUnsafe(now);
-		} catch (error) {
-			logInternalError("heartbeat-watcher.tick", error);
-		} finally {
-			this.scheduleTick();
-		}
-	}
-
-	private tickUnsafe(now: number): void {
-		const thresholds = this.opts.thresholds ?? DEFAULT_GRADIENT_THRESHOLDS;
-		const tickThreshold = this.opts.deadletterTickThreshold ?? 3;
-		const activeKeys = new Set<string>();
-
-		for (const run of this.opts.manifestCache.list(50)) {
-			if (run.status !== "running") continue;
-			const loaded = loadRunManifestById(this.opts.cwd, run.runId);
-			if (!loaded) continue;
-			for (const task of loaded.tasks) {
-				if (task.status !== "running") continue;
-				const key = `${run.runId}:${task.id}`;
-				activeKeys.add(key);
-				this.lastSeen.set(key, now);
-
-				const elapsed = heartbeatAgeMs(task.heartbeat, now);
-				const level = classifyHeartbeat(task.heartbeat, thresholds, now);
-				this.opts.registry.gauge("crew.heartbeat.staleness_ms", "Heartbeat elapsed since last seen, milliseconds").set({ runId: run.runId, taskId: task.id }, Number.isFinite(elapsed) ? elapsed : thresholds.deadMs);
-				this.opts.registry.counter("crew.heartbeat.level_total", "Heartbeat classifications by level").inc({ runId: run.runId, level });
-				const previous = this.lastLevel.get(key);
-				this.lastLevel.set(key, level);
-				if (level === "dead" && previous !== "dead") {
-					this.opts.registry.counter("crew.heartbeat.dead_total", "Dead heartbeat detections").inc({ runId: run.runId });
-					appendEvent(loaded.manifest.eventsPath, { type: "crew.task.heartbeat_dead", runId: run.runId, taskId: task.id, message: `Task ${task.id} heartbeat dead.`, data: { elapsedMs: Number.isFinite(elapsed) ? elapsed : undefined } });
-					this.opts.router.enqueue({ id: `dead_${run.runId}_${task.id}`, severity: "warning", source: "heartbeat-watcher", runId: run.runId, title: `Task ${task.id} heartbeat dead`, body: "Background watcher detected a stuck worker." });
-					this.opts.onDead?.(run.runId, task.id, Number.isFinite(elapsed) ? elapsed : thresholds.deadMs);
-				}
-				if (level === "dead") {
-					const count = (this.consecutiveDead.get(key) ?? 0) + 1;
-					this.consecutiveDead.set(key, count);
-					if (count === tickThreshold) this.opts.onDeadletterTrigger?.(loaded.manifest, task.id);
-				} else {
-					this.consecutiveDead.delete(key);
-				}
-			}
-		}
-
-		// Cleanup: drop keys that were NOT in this tick's active set AND
-		// haven't been seen for > maxKeyAgeMs.  This covers runs that
-		// completed or fell out of the manifest cache's top-50 window.
-		const cutoff = now - this.maxKeyAgeMs;
-		for (const [key, ts] of this.lastSeen) {
-			if (!activeKeys.has(key) && ts < cutoff) {
-				this.lastLevel.delete(key);
-				this.consecutiveDead.delete(key);
-				this.lastSeen.delete(key);
-			}
-		}
-	}
-
-	dispose(): void {
-		if (this.timer) clearTimeout(this.timer);
-		this.timer = undefined;
-		this.lastLevel.clear();
-		this.consecutiveDead.clear();
-		this.lastSeen.clear();
-	}
-}
+import type { NotificationDescriptor } from "../extension/notification-router.ts";
+import type { MetricRegistry } from "../observability/metric-registry.ts";
+import { appendEvent } from "../state/event-log.ts";
+import { loadRunManifestById } from "../state/state-store.ts";
+import type { TeamRunManifest } from "../state/types.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+import type { ManifestCache } from "./manifest-cache.ts";
+import { classifyHeartbeat, DEFAULT_GRADIENT_THRESHOLDS, heartbeatAgeMs, type GradientThresholds, type HeartbeatLevel } from "./heartbeat-gradient.ts";
+
+export interface HeartbeatWatcherRouter {
+	enqueue(notification: NotificationDescriptor): boolean;
+}
+
+export interface HeartbeatWatcherOptions {
+	cwd: string;
+	pollIntervalMs?: number;
+	thresholds?: GradientThresholds;
+	manifestCache: ManifestCache;
+	registry: MetricRegistry;
+	router: HeartbeatWatcherRouter;
+	deadletterTickThreshold?: number;
+	onDead?: (runId: string, taskId: string, elapsed: number) => void;
+	onDeadletterTrigger?: (manifest: TeamRunManifest, taskId: string) => void;
+}
+
+/**
+ * Polls running runs for heartbeat staleness.
+ *
+ * Uses recursive setTimeout to avoid timer storms.
+ * Cleanup is done in the same pass — no second scan over manifests.
+ * Keys for runs that disappear from the cache are cleaned via staleness-age policy
+ * rather than being leaked forever.
+ */
+export class HeartbeatWatcher {
+	private timer?: ReturnType<typeof setTimeout>;
+	private lastLevel = new Map<string, HeartbeatLevel>();
+	private consecutiveDead = new Map<string, number>();
+	private lastSeen = new Map<string, number>(); // key → last time it was active
+	/** Max age (ms) to retain a stale key before garbage-collecting it. */
+	private readonly maxKeyAgeMs = 600_000; // 10 minutes
+	private readonly opts: HeartbeatWatcherOptions;
+
+	constructor(opts: HeartbeatWatcherOptions) {
+		this.opts = opts;
+	}
+
+	start(): void {
+		this.dispose();
+		this.scheduleTick();
+	}
+
+	private scheduleTick(): void {
+		this.timer = setTimeout(() => this.tick(), this.opts.pollIntervalMs ?? 5000);
+		this.timer.unref();
+	}
+
+	tick(now = Date.now()): void {
+		try {
+			this.tickUnsafe(now);
+		} catch (error) {
+			logInternalError("heartbeat-watcher.tick", error);
+		} finally {
+			this.scheduleTick();
+		}
+	}
+
+	private tickUnsafe(now: number): void {
+		const thresholds = this.opts.thresholds ?? DEFAULT_GRADIENT_THRESHOLDS;
+		const tickThreshold = this.opts.deadletterTickThreshold ?? 3;
+		const activeKeys = new Set<string>();
+
+		for (const run of this.opts.manifestCache.list(50)) {
+			if (run.status !== "running") continue;
+			const loaded = loadRunManifestById(this.opts.cwd, run.runId);
+			if (!loaded) continue;
+			for (const task of loaded.tasks) {
+				if (task.status !== "running") continue;
+				const key = `${run.runId}:${task.id}`;
+				activeKeys.add(key);
+				this.lastSeen.set(key, now);
+
+				const elapsed = heartbeatAgeMs(task.heartbeat, now);
+				const level = classifyHeartbeat(task.heartbeat, thresholds, now);
+				this.opts.registry.gauge("crew.heartbeat.staleness_ms", "Heartbeat elapsed since last seen, milliseconds").set({ runId: run.runId, taskId: task.id }, Number.isFinite(elapsed) ? elapsed : thresholds.deadMs);
+				this.opts.registry.counter("crew.heartbeat.level_total", "Heartbeat classifications by level").inc({ runId: run.runId, level });
+				const previous = this.lastLevel.get(key);
+				this.lastLevel.set(key, level);
+				if (level === "dead" && previous !== "dead") {
+					this.opts.registry.counter("crew.heartbeat.dead_total", "Dead heartbeat detections").inc({ runId: run.runId });
+					appendEvent(loaded.manifest.eventsPath, { type: "crew.task.heartbeat_dead", runId: run.runId, taskId: task.id, message: `Task ${task.id} heartbeat dead.`, data: { elapsedMs: Number.isFinite(elapsed) ? elapsed : undefined } });
+					this.opts.router.enqueue({ id: `dead_${run.runId}_${task.id}`, severity: "warning", source: "heartbeat-watcher", runId: run.runId, title: `Task ${task.id} heartbeat dead`, body: "Background watcher detected a stuck worker." });
+					this.opts.onDead?.(run.runId, task.id, Number.isFinite(elapsed) ? elapsed : thresholds.deadMs);
+				}
+				if (level === "dead") {
+					const count = (this.consecutiveDead.get(key) ?? 0) + 1;
+					this.consecutiveDead.set(key, count);
+					if (count === tickThreshold) this.opts.onDeadletterTrigger?.(loaded.manifest, task.id);
+				} else {
+					this.consecutiveDead.delete(key);
+				}
+			}
+		}
+
+		// Cleanup: drop keys that were NOT in this tick's active set AND
+		// haven't been seen for > maxKeyAgeMs.  This covers runs that
+		// completed or fell out of the manifest cache's top-50 window.
+		const cutoff = now - this.maxKeyAgeMs;
+		for (const [key, ts] of this.lastSeen) {
+			if (!activeKeys.has(key) && ts < cutoff) {
+				this.lastLevel.delete(key);
+				this.consecutiveDead.delete(key);
+				this.lastSeen.delete(key);
+			}
+		}
+	}
+
+	dispose(): void {
+		if (this.timer) clearTimeout(this.timer);
+		this.timer = undefined;
+		this.lastLevel.clear();
+		this.consecutiveDead.clear();
+		this.lastSeen.clear();
+	}
+}

package/src/runtime/live-agent-control.ts

@@ -1,87 +1,88 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { TeamRunManifest } from "../state/types.ts";
-import { agentStateFile, ensureAgentStateDir } from "./crew-agent-records.ts";
-
-export type LiveAgentControlOperation = "steer" | "stop" | "resume";
-
-export interface LiveAgentControlRequest {
-	id: string;
-	runId: string;
-	taskId: string;
-	agentId?: string;
-	operation: LiveAgentControlOperation;
-	message?: string;
-	createdAt: string;
-	processedAt?: string;
-	error?: string;
-}
-
-export interface LiveAgentControlCursor {
-	offset: number;
-}
-
-export function liveAgentControlPath(manifest: TeamRunManifest, taskId: string): string {
-	return path.join(ensureAgentStateDir(manifest, taskId), "live-control.jsonl");
-}
-
-function liveAgentControlFile(manifest: TeamRunManifest, taskId: string): string {
-	return agentStateFile(manifest, taskId, "live-control.jsonl");
-}
-
-function requestId(): string {
-	return `ctrl_${Date.now().toString(36)}_${Math.random().toString(16).slice(2, 10)}`;
-}
-
-export function appendLiveAgentControlRequest(manifest: TeamRunManifest, input: { taskId: string; agentId?: string; operation: LiveAgentControlOperation; message?: string }): LiveAgentControlRequest {
-	const request: LiveAgentControlRequest = {
-		id: requestId(),
-		runId: manifest.runId,
-		taskId: input.taskId,
-		agentId: input.agentId,
-		operation: input.operation,
-		message: input.message,
-		createdAt: new Date().toISOString(),
-	};
-	const filePath = liveAgentControlFile(manifest, input.taskId);
-	fs.appendFileSync(filePath, `${JSON.stringify(request)}\n`, "utf-8");
-	return request;
-}
-
-export function readLiveAgentControlRequests(manifest: TeamRunManifest, taskId: string, cursor: LiveAgentControlCursor = { offset: 0 }): { requests: LiveAgentControlRequest[]; cursor: LiveAgentControlCursor } {
-	let filePath: string;
-	try {
-		filePath = liveAgentControlFile(manifest, taskId);
-	} catch {
-		return { requests: [], cursor };
-	}
-	if (!fs.existsSync(filePath)) return { requests: [], cursor };
-	const text = fs.readFileSync(filePath, "utf-8");
-	const lines = text.split(/\r?\n/).filter(Boolean);
-	const requests = lines.slice(cursor.offset).flatMap((line) => {
-		try {
-			const parsed = JSON.parse(line) as LiveAgentControlRequest;
-			return parsed && parsed.runId === manifest.runId && parsed.taskId === taskId ? [parsed] : [];
-		} catch {
-			return [];
-		}
-	});
-	return { requests, cursor: { offset: lines.length } };
-}
-
-export async function applyLiveAgentControlRequest(input: { request: LiveAgentControlRequest; taskId: string; agentId: string; session: { steer?: (text: string) => Promise<void>; prompt?: (text: string, options?: Record<string, unknown>) => Promise<void>; abort?: () => Promise<void> | void }; seenRequestIds?: Set<string> }): Promise<boolean> {
-	const { request, taskId, agentId, session, seenRequestIds } = input;
-	if (seenRequestIds?.has(request.id)) return false;
-	if (request.agentId && request.agentId !== agentId && request.agentId !== taskId) return false;
-	seenRequestIds?.add(request.id);
-	if (request.operation === "steer") await session.steer?.(request.message ?? "Please report current status and wrap up if possible.");
-	else if (request.operation === "resume") await session.prompt?.(request.message ?? "Please resume and report final status.", { source: "api", expandPromptTemplates: false });
-	else if (request.operation === "stop") await session.abort?.();
-	return true;
-}
-
-export async function applyLiveAgentControlRequests(input: { manifest: TeamRunManifest; taskId: string; agentId: string; session: { steer?: (text: string) => Promise<void>; prompt?: (text: string, options?: Record<string, unknown>) => Promise<void>; abort?: () => Promise<void> | void }; cursor: LiveAgentControlCursor; seenRequestIds?: Set<string> }): Promise<LiveAgentControlCursor> {
-	const batch = readLiveAgentControlRequests(input.manifest, input.taskId, input.cursor);
-	for (const request of batch.requests) await applyLiveAgentControlRequest({ request, taskId: input.taskId, agentId: input.agentId, session: input.session, seenRequestIds: input.seenRequestIds });
-	return batch.cursor;
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TeamRunManifest } from "../state/types.ts";
+import { agentStateFile, ensureAgentStateDir } from "./crew-agent-records.ts";
+
+export type LiveAgentControlOperation = "steer" | "follow-up" | "stop" | "resume";
+
+export interface LiveAgentControlRequest {
+	id: string;
+	runId: string;
+	taskId: string;
+	agentId?: string;
+	operation: LiveAgentControlOperation;
+	message?: string;
+	createdAt: string;
+	processedAt?: string;
+	error?: string;
+}
+
+export interface LiveAgentControlCursor {
+	offset: number;
+}
+
+export function liveAgentControlPath(manifest: TeamRunManifest, taskId: string): string {
+	return path.join(ensureAgentStateDir(manifest, taskId), "live-control.jsonl");
+}
+
+function liveAgentControlFile(manifest: TeamRunManifest, taskId: string): string {
+	return agentStateFile(manifest, taskId, "live-control.jsonl");
+}
+
+function requestId(): string {
+	return `ctrl_${Date.now().toString(36)}_${Math.random().toString(16).slice(2, 10)}`;
+}
+
+export function appendLiveAgentControlRequest(manifest: TeamRunManifest, input: { taskId: string; agentId?: string; operation: LiveAgentControlOperation; message?: string }): LiveAgentControlRequest {
+	const request: LiveAgentControlRequest = {
+		id: requestId(),
+		runId: manifest.runId,
+		taskId: input.taskId,
+		agentId: input.agentId,
+		operation: input.operation,
+		message: input.message,
+		createdAt: new Date().toISOString(),
+	};
+	const filePath = liveAgentControlFile(manifest, input.taskId);
+	fs.appendFileSync(filePath, `${JSON.stringify(request)}\n`, "utf-8");
+	return request;
+}
+
+export function readLiveAgentControlRequests(manifest: TeamRunManifest, taskId: string, cursor: LiveAgentControlCursor = { offset: 0 }): { requests: LiveAgentControlRequest[]; cursor: LiveAgentControlCursor } {
+	let filePath: string;
+	try {
+		filePath = liveAgentControlFile(manifest, taskId);
+	} catch {
+		return { requests: [], cursor };
+	}
+	if (!fs.existsSync(filePath)) return { requests: [], cursor };
+	const text = fs.readFileSync(filePath, "utf-8");
+	const lines = text.split(/\r?\n/).filter(Boolean);
+	const requests = lines.slice(cursor.offset).flatMap((line) => {
+		try {
+			const parsed = JSON.parse(line) as LiveAgentControlRequest;
+			return parsed && parsed.runId === manifest.runId && parsed.taskId === taskId ? [parsed] : [];
+		} catch {
+			return [];
+		}
+	});
+	return { requests, cursor: { offset: lines.length } };
+}
+
+export async function applyLiveAgentControlRequest(input: { request: LiveAgentControlRequest; taskId: string; agentId: string; session: { steer?: (text: string) => Promise<void>; prompt?: (text: string, options?: Record<string, unknown>) => Promise<void>; abort?: () => Promise<void> | void }; seenRequestIds?: Set<string> }): Promise<boolean> {
+	const { request, taskId, agentId, session, seenRequestIds } = input;
+	if (seenRequestIds?.has(request.id)) return false;
+	if (request.agentId && request.agentId !== agentId && request.agentId !== taskId) return false;
+	seenRequestIds?.add(request.id);
+	if (request.operation === "steer") await session.steer?.(request.message ?? "Please report current status and wrap up if possible.");
+	else if (request.operation === "follow-up") await session.prompt?.(request.message ?? "Please continue with the follow-up request.", { source: "api", expandPromptTemplates: false });
+	else if (request.operation === "resume") await session.prompt?.(request.message ?? "Please resume and report final status.", { source: "api", expandPromptTemplates: false });
+	else if (request.operation === "stop") await session.abort?.();
+	return true;
+}
+
+export async function applyLiveAgentControlRequests(input: { manifest: TeamRunManifest; taskId: string; agentId: string; session: { steer?: (text: string) => Promise<void>; prompt?: (text: string, options?: Record<string, unknown>) => Promise<void>; abort?: () => Promise<void> | void }; cursor: LiveAgentControlCursor; seenRequestIds?: Set<string> }): Promise<LiveAgentControlCursor> {
+	const batch = readLiveAgentControlRequests(input.manifest, input.taskId, input.cursor);
+	for (const request of batch.requests) await applyLiveAgentControlRequest({ request, taskId: input.taskId, agentId: input.agentId, session: input.session, seenRequestIds: input.seenRequestIds });
+	return batch.cursor;
+}

package/src/runtime/live-agent-manager.ts

@@ -1,85 +1,103 @@
-import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
-
-type LiveSessionHandle = {
-	steer?: (text: string) => Promise<void>;
-	prompt?: (text: string, options?: Record<string, unknown>) => Promise<void>;
-	abort?: () => Promise<void> | void;
-};
-
-export interface LiveAgentHandle {
-	agentId: string;
-	taskId: string;
-	runId: string;
-	session: LiveSessionHandle;
-	createdAt: string;
-	updatedAt: string;
-	status: CrewAgentRecord["status"];
-	pendingSteers: string[];
-}
-
-const liveAgents = new Map<string, LiveAgentHandle>();
-
-export function registerLiveAgent(input: Omit<LiveAgentHandle, "createdAt" | "updatedAt" | "pendingSteers">): LiveAgentHandle {
-	const now = new Date().toISOString();
-	const existing = liveAgents.get(input.agentId);
-	const handle: LiveAgentHandle = { ...input, createdAt: existing?.createdAt ?? now, updatedAt: now, pendingSteers: existing?.pendingSteers ?? [] };
-	liveAgents.set(input.agentId, handle);
-	if (handle.pendingSteers.length && typeof handle.session.steer === "function") {
-		const pending = [...handle.pendingSteers];
-		handle.pendingSteers.length = 0;
-		for (const message of pending) void handle.session.steer(message).catch(() => {});
-	}
-	return handle;
-}
-
-export function updateLiveAgentStatus(agentId: string, status: CrewAgentRecord["status"]): void {
-	const handle = liveAgents.get(agentId);
-	if (!handle) return;
-	handle.status = status;
-	handle.updatedAt = new Date().toISOString();
-}
-
-export function getLiveAgent(agentIdOrTaskId: string): LiveAgentHandle | undefined {
-	return liveAgents.get(agentIdOrTaskId) ?? [...liveAgents.values()].find((entry) => entry.taskId === agentIdOrTaskId);
-}
-
-export function listLiveAgents(): LiveAgentHandle[] {
-	return [...liveAgents.values()].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
-}
-
-export async function steerLiveAgent(agentIdOrTaskId: string, message: string): Promise<LiveAgentHandle> {
-	const handle = getLiveAgent(agentIdOrTaskId);
-	if (!handle) throw new Error(`Live agent '${agentIdOrTaskId}' is not registered in this process.`);
-	if (typeof handle.session.steer !== "function") {
-		handle.pendingSteers.push(message);
-		return handle;
-	}
-	await handle.session.steer(message);
-	handle.updatedAt = new Date().toISOString();
-	return handle;
-}
-
-export async function stopLiveAgent(agentIdOrTaskId: string): Promise<LiveAgentHandle> {
-	const handle = getLiveAgent(agentIdOrTaskId);
-	if (!handle) throw new Error(`Live agent '${agentIdOrTaskId}' is not registered in this process.`);
-	if (typeof handle.session.abort !== "function") throw new Error(`Live agent '${agentIdOrTaskId}' does not expose abort().`);
-	await handle.session.abort();
-	handle.status = "stopped";
-	handle.updatedAt = new Date().toISOString();
-	return handle;
-}
-
-export async function resumeLiveAgent(agentIdOrTaskId: string, prompt: string): Promise<LiveAgentHandle> {
-	const handle = getLiveAgent(agentIdOrTaskId);
-	if (!handle) throw new Error(`Live agent '${agentIdOrTaskId}' is not registered in this process.`);
-	if (typeof handle.session.prompt !== "function") throw new Error(`Live agent '${agentIdOrTaskId}' does not expose prompt().`);
-	handle.status = "running";
-	await handle.session.prompt(prompt, { source: "api", expandPromptTemplates: false });
-	handle.status = "completed";
-	handle.updatedAt = new Date().toISOString();
-	return handle;
-}
-
-export function clearLiveAgentsForTest(): void {
-	liveAgents.clear();
-}
+import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
+
+type LiveSessionHandle = {
+	steer?: (text: string) => Promise<void>;
+	prompt?: (text: string, options?: Record<string, unknown>) => Promise<void>;
+	abort?: () => Promise<void> | void;
+};
+
+export interface LiveAgentHandle {
+	agentId: string;
+	taskId: string;
+	runId: string;
+	session: LiveSessionHandle;
+	createdAt: string;
+	updatedAt: string;
+	status: CrewAgentRecord["status"];
+	pendingSteers: string[];
+	pendingFollowUps: string[];
+}
+
+const liveAgents = new Map<string, LiveAgentHandle>();
+
+export function registerLiveAgent(input: Omit<LiveAgentHandle, "createdAt" | "updatedAt" | "pendingSteers" | "pendingFollowUps">): LiveAgentHandle {
+	const now = new Date().toISOString();
+	const existing = liveAgents.get(input.agentId);
+	const handle: LiveAgentHandle = { ...input, createdAt: existing?.createdAt ?? now, updatedAt: now, pendingSteers: existing?.pendingSteers ?? [], pendingFollowUps: existing?.pendingFollowUps ?? [] };
+	liveAgents.set(input.agentId, handle);
+	if (handle.pendingSteers.length && typeof handle.session.steer === "function") {
+		const pending = [...handle.pendingSteers];
+		handle.pendingSteers.length = 0;
+		for (const message of pending) void handle.session.steer(message).catch(() => {});
+	}
+	if (handle.pendingFollowUps.length && typeof handle.session.prompt === "function") {
+		const pending = [...handle.pendingFollowUps];
+		handle.pendingFollowUps.length = 0;
+		for (const message of pending) void handle.session.prompt(message, { source: "api", expandPromptTemplates: false }).catch(() => {});
+	}
+	return handle;
+}
+
+export function updateLiveAgentStatus(agentId: string, status: CrewAgentRecord["status"]): void {
+	const handle = liveAgents.get(agentId);
+	if (!handle) return;
+	handle.status = status;
+	handle.updatedAt = new Date().toISOString();
+}
+
+export function getLiveAgent(agentIdOrTaskId: string): LiveAgentHandle | undefined {
+	return liveAgents.get(agentIdOrTaskId) ?? [...liveAgents.values()].find((entry) => entry.taskId === agentIdOrTaskId);
+}
+
+export function listLiveAgents(): LiveAgentHandle[] {
+	return [...liveAgents.values()].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+export async function steerLiveAgent(agentIdOrTaskId: string, message: string): Promise<LiveAgentHandle> {
+	const handle = getLiveAgent(agentIdOrTaskId);
+	if (!handle) throw new Error(`Live agent '${agentIdOrTaskId}' is not registered in this process.`);
+	if (typeof handle.session.steer !== "function") {
+		handle.pendingSteers.push(message);
+		return handle;
+	}
+	await handle.session.steer(message);
+	handle.updatedAt = new Date().toISOString();
+	return handle;
+}
+
+export async function followUpLiveAgent(agentIdOrTaskId: string, prompt: string): Promise<LiveAgentHandle> {
+	const handle = getLiveAgent(agentIdOrTaskId);
+	if (!handle) throw new Error(`Live agent '${agentIdOrTaskId}' is not registered in this process.`);
+	if (typeof handle.session.prompt !== "function") {
+		handle.pendingFollowUps.push(prompt);
+		return handle;
+	}
+	await handle.session.prompt(prompt, { source: "api", expandPromptTemplates: false });
+	handle.updatedAt = new Date().toISOString();
+	return handle;
+}
+
+export async function stopLiveAgent(agentIdOrTaskId: string): Promise<LiveAgentHandle> {
+	const handle = getLiveAgent(agentIdOrTaskId);
+	if (!handle) throw new Error(`Live agent '${agentIdOrTaskId}' is not registered in this process.`);
+	if (typeof handle.session.abort !== "function") throw new Error(`Live agent '${agentIdOrTaskId}' does not expose abort().`);
+	await handle.session.abort();
+	handle.status = "stopped";
+	handle.updatedAt = new Date().toISOString();
+	return handle;
+}
+
+export async function resumeLiveAgent(agentIdOrTaskId: string, prompt: string): Promise<LiveAgentHandle> {
+	const handle = getLiveAgent(agentIdOrTaskId);
+	if (!handle) throw new Error(`Live agent '${agentIdOrTaskId}' is not registered in this process.`);
+	if (typeof handle.session.prompt !== "function") throw new Error(`Live agent '${agentIdOrTaskId}' does not expose prompt().`);
+	handle.status = "running";
+	await handle.session.prompt(prompt, { source: "api", expandPromptTemplates: false });
+	handle.status = "completed";
+	handle.updatedAt = new Date().toISOString();
+	return handle;
+}
+
+export function clearLiveAgentsForTest(): void {
+	liveAgents.clear();
+}