pi-crew 0.1.6 → 0.1.8

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

@@ -52,17 +52,55 @@ export function readCrewAgentStatus(manifest: TeamRunManifest, taskOrAgentId: st
 	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 });
-	fs.appendFileSync(agentEventsPath(manifest, taskId), `${JSON.stringify({ time: new Date().toISOString(), event })}\n`, "utf-8");
+	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 [];
-	return fs.readFileSync(filePath, "utf-8").split(/\r?\n/).filter(Boolean).map((line) => {
-		try { return JSON.parse(line) as unknown; } catch { return { raw: line }; }
+	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 {

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

@@ -21,6 +21,7 @@ export interface CrewAgentProgress {
 	durationMs?: number;
 	lastActivityAt?: string;
 	activityState?: "active" | "needs_attention" | "stale";
+	failedTool?: string;
 }
 
 export interface CrewAgentRecord {

package/src/runtime/foreground-control.ts

@@ -0,0 +1,82 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { appendEvent } from "../state/event-log.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { checkProcessLiveness, isActiveRunStatus } from "./process-status.ts";
+import { readCrewAgents } from "./crew-agent-records.ts";
+
+export type ForegroundControlRequestType = "interrupt" | "status";
+
+export interface ForegroundControlStatus {
+	runId: string;
+	status: TeamRunManifest["status"];
+	active: boolean;
+	asyncPid?: number;
+	asyncAlive?: boolean;
+	runningTasks: string[];
+	runningAgents: string[];
+	controlPath: string;
+	lastRequest?: ForegroundControlRequest;
+}
+
+export interface ForegroundControlRequest {
+	id: string;
+	type: ForegroundControlRequestType;
+	createdAt: string;
+	reason: string;
+	acknowledged: boolean;
+}
+
+export function foregroundControlPath(manifest: TeamRunManifest): string {
+	return path.join(manifest.stateRoot, "foreground-control.json");
+}
+
+function readLastRequest(controlPath: string): ForegroundControlRequest | undefined {
+	if (!fs.existsSync(controlPath)) return undefined;
+	try {
+		const parsed = JSON.parse(fs.readFileSync(controlPath, "utf-8")) as { requests?: ForegroundControlRequest[] };
+		return parsed.requests?.at(-1);
+	} catch {
+		return undefined;
+	}
+}
+
+export function readForegroundControlStatus(manifest: TeamRunManifest, tasks: TeamTaskState[]): ForegroundControlStatus {
+	const controlPath = foregroundControlPath(manifest);
+	const asyncAlive = manifest.async?.pid !== undefined ? checkProcessLiveness(manifest.async.pid).alive : undefined;
+	return {
+		runId: manifest.runId,
+		status: manifest.status,
+		active: isActiveRunStatus(manifest.status),
+		asyncPid: manifest.async?.pid,
+		asyncAlive,
+		runningTasks: tasks.filter((task) => task.status === "running").map((task) => task.id),
+		runningAgents: readCrewAgents(manifest).filter((agent) => agent.status === "running").map((agent) => agent.id),
+		controlPath,
+		lastRequest: readLastRequest(controlPath),
+	};
+}
+
+export function writeForegroundInterruptRequest(manifest: TeamRunManifest, reason = "User requested foreground interrupt."): ForegroundControlRequest {
+	const controlPath = foregroundControlPath(manifest);
+	let requests: ForegroundControlRequest[] = [];
+	if (fs.existsSync(controlPath)) {
+		try {
+			const parsed = JSON.parse(fs.readFileSync(controlPath, "utf-8")) as { requests?: ForegroundControlRequest[] };
+			requests = Array.isArray(parsed.requests) ? parsed.requests : [];
+		} catch {
+			requests = [];
+		}
+	}
+	const request: ForegroundControlRequest = {
+		id: `fg_${Date.now().toString(36)}_${Math.random().toString(16).slice(2, 10)}`,
+		type: "interrupt",
+		createdAt: new Date().toISOString(),
+		reason,
+		acknowledged: false,
+	};
+	fs.mkdirSync(path.dirname(controlPath), { recursive: true });
+	fs.writeFileSync(controlPath, `${JSON.stringify({ requests: [...requests, request] }, null, 2)}\n`, "utf-8");
+	appendEvent(manifest.eventsPath, { type: "foreground.interrupt_requested", runId: manifest.runId, message: reason, data: { requestId: request.id, controlPath } });
+	return request;
+}

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

@@ -0,0 +1,78 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TeamRunManifest } from "../state/types.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(manifest.stateRoot, "agents", 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 = liveAgentControlPath(manifest, input.taskId);
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	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 } {
+	const filePath = liveAgentControlPath(manifest, taskId);
+	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;
+}

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

@@ -0,0 +1,85 @@
+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();
+}

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

@@ -0,0 +1,36 @@
+import type { LiveAgentControlRequest } from "./live-agent-control.ts";
+
+export interface LiveControlRealtimeMessage {
+	type: "live-control";
+	version: 1;
+	request: LiveAgentControlRequest;
+}
+
+type Listener = (request: LiveAgentControlRequest) => void | Promise<void>;
+
+const listeners = new Set<Listener>();
+
+export function publishLiveControlRealtime(request: LiveAgentControlRequest): void {
+	for (const listener of [...listeners]) void listener(request);
+}
+
+export function subscribeLiveControlRealtime(listener: Listener): () => void {
+	listeners.add(listener);
+	return () => listeners.delete(listener);
+}
+
+export function liveControlRealtimeMessage(request: LiveAgentControlRequest): LiveControlRealtimeMessage {
+	return { type: "live-control", version: 1, request };
+}
+
+export function parseLiveControlRealtimeMessage(raw: unknown): LiveAgentControlRequest | undefined {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+	const message = raw as { type?: unknown; version?: unknown; request?: unknown };
+	if (message.type !== "live-control" || message.version !== 1 || !message.request || typeof message.request !== "object" || Array.isArray(message.request)) return undefined;
+	const request = message.request as Partial<LiveAgentControlRequest>;
+	return typeof request.id === "string" && typeof request.runId === "string" && typeof request.taskId === "string" && (request.operation === "steer" || request.operation === "stop" || request.operation === "resume") && typeof request.createdAt === "string" ? request as LiveAgentControlRequest : undefined;
+}
+
+export function clearLiveControlRealtimeForTest(): void {
+	listeners.clear();
+}

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

@@ -1,5 +1,13 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import type { AgentConfig } from "../agents/agent-config.ts";
-import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import type { CrewRuntimeConfig } from "../config/config.ts";
+import type { TeamRunManifest, TeamTaskState, UsageState } from "../state/types.ts";
+import { buildMemoryBlock } from "./agent-memory.ts";
+import { registerLiveAgent, updateLiveAgentStatus } from "./live-agent-manager.ts";
+import { applyLiveAgentControlRequest, applyLiveAgentControlRequests, type LiveAgentControlCursor } from "./live-agent-control.ts";
+import { subscribeLiveControlRealtime } from "./live-control-realtime.ts";
+import { eventToSidechainType, sidechainOutputPath, writeSidechainEntry } from "./sidechain-output.ts";
 import type { WorkflowStep } from "../workflows/workflow-config.ts";
 import { isLiveSessionRuntimeAvailable } from "./runtime-resolver.ts";
 
@@ -9,6 +17,24 @@ export interface LiveSessionSpawnInput {
 	step: WorkflowStep;
 	agent: AgentConfig;
 	prompt: string;
+	signal?: AbortSignal;
+	transcriptPath?: string;
+	onEvent?: (event: unknown) => void;
+	onOutput?: (text: string) => void;
+	runtimeConfig?: CrewRuntimeConfig;
+	parentContext?: string;
+	parentModel?: unknown;
+	modelRegistry?: unknown;
+}
+
+export interface LiveSessionRunResult {
+	available: true;
+	exitCode: number | null;
+	stdout: string;
+	stderr: string;
+	jsonEvents: number;
+	usage?: UsageState;
+	error?: string;
 }
 
 export interface LiveSessionUnavailableResult {
@@ -21,13 +47,253 @@ export interface LiveSessionPlannedResult {
 	reason: string;
 }
 
+type LiveSessionModule = Record<string, unknown> & {
+	createAgentSession?: (options?: Record<string, unknown>) => Promise<{ session: LiveSessionLike; modelFallbackMessage?: string }>;
+	DefaultResourceLoader?: new (options: Record<string, unknown>) => { reload?: () => Promise<void> };
+	SessionManager?: { inMemory?: (cwd?: string) => unknown; create?: (cwd?: string, sessionDir?: string) => unknown };
+	SettingsManager?: { create?: (cwd?: string, agentDir?: string) => unknown };
+	getAgentDir?: () => string;
+};
+
+type LiveSessionLike = {
+	subscribe?: (listener: (event: unknown) => void) => (() => void);
+	prompt?: (text: string, options?: Record<string, unknown>) => Promise<void>;
+	steer?: (text: string) => Promise<void>;
+	abort?: () => Promise<void> | void;
+	getStats?: () => unknown;
+	stats?: unknown;
+	bindExtensions?: (bindings?: Record<string, unknown>) => Promise<void>;
+	getActiveToolNames?: () => string[];
+	setActiveToolsByName?: (names: string[]) => void;
+};
+
+function appendTranscript(filePath: string | undefined, event: unknown): void {
+	if (!filePath) return;
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	fs.appendFileSync(filePath, `${JSON.stringify(event)}\n`, "utf-8");
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function textFromContent(content: unknown): string[] {
+	if (typeof content === "string") return [content];
+	if (!Array.isArray(content)) return [];
+	return content.flatMap((part) => {
+		const obj = asRecord(part);
+		if (!obj) return [];
+		if (obj.type === "text" && typeof obj.text === "string") return [obj.text];
+		if (typeof obj.content === "string") return [obj.content];
+		return [];
+	});
+}
+
+function eventText(event: unknown): string[] {
+	const obj = asRecord(event);
+	if (!obj) return [];
+	const text: string[] = [];
+	if (typeof obj.text === "string") text.push(obj.text);
+	text.push(...textFromContent(obj.content));
+	const message = asRecord(obj.message);
+	if (message) text.push(...textFromContent(message.content));
+	return text.filter((entry) => entry.trim());
+}
+
+function finalAssistantText(event: unknown): string[] {
+	const obj = asRecord(event);
+	if (!obj || obj.type !== "message_end") return [];
+	const message = asRecord(obj.message);
+	if (message?.role !== "assistant") return [];
+	return textFromContent(message.content);
+}
+
+function numberField(obj: Record<string, unknown> | undefined, keys: string[]): number | undefined {
+	if (!obj) return undefined;
+	for (const key of keys) {
+		const value = obj[key];
+		if (typeof value === "number" && Number.isFinite(value)) return value;
+	}
+	return undefined;
+}
+
+function modelFromRegistry(modelRegistry: unknown, modelId: string | undefined): unknown {
+	if (!modelId || !modelId.includes("/")) return undefined;
+	const registry = asRecord(modelRegistry);
+	const find = registry?.find;
+	if (typeof find !== "function") return undefined;
+	const [provider, ...modelParts] = modelId.split("/");
+	const id = modelParts.join("/");
+	try {
+		return find.call(modelRegistry, provider, id);
+	} catch {
+		return undefined;
+	}
+}
+
+function liveSystemPrompt(input: LiveSessionSpawnInput): string {
+	const memory = input.agent.memory ? buildMemoryBlock(input.agent.name, input.agent.memory, input.task.cwd, Boolean(input.agent.tools?.some((tool) => tool === "write" || tool === "edit"))) : "";
+	return [
+		"# pi-crew Live Subagent",
+		`Run ID: ${input.manifest.runId}`,
+		`Task ID: ${input.task.id}`,
+		`Role: ${input.task.role}`,
+		`Agent: ${input.agent.name}`,
+		`Working directory: ${input.task.cwd}`,
+		"",
+		input.agent.systemPrompt || "Follow the user task exactly and report verification evidence.",
+		memory ? `\n${memory}` : "",
+	].filter(Boolean).join("\n");
+}
+
+function filterActiveTools(session: LiveSessionLike, agent: AgentConfig): void {
+	if (typeof session.getActiveToolNames !== "function" || typeof session.setActiveToolsByName !== "function") return;
+	const recursiveTools = new Set(["team", "Team", "Agent", "get_subagent_result", "steer_subagent"]);
+	const allowed = agent.tools?.length ? new Set(agent.tools) : undefined;
+	const active = session.getActiveToolNames().filter((name) => !recursiveTools.has(name) && (!allowed || allowed.has(name)));
+	session.setActiveToolsByName(active);
+}
+
+function usageFromStats(stats: unknown): UsageState | undefined {
+	const obj = asRecord(stats);
+	if (!obj) return undefined;
+	const input = numberField(obj, ["input", "inputTokens", "input_tokens"]);
+	const output = numberField(obj, ["output", "outputTokens", "output_tokens"]);
+	const cacheRead = numberField(obj, ["cacheRead", "cache_read"]);
+	const cacheWrite = numberField(obj, ["cacheWrite", "cache_write"]);
+	const cost = numberField(obj, ["cost"]);
+	const turns = numberField(obj, ["turns", "turnCount", "turn_count"]);
+	return [input, output, cacheRead, cacheWrite, cost, turns].some((value) => value !== undefined) ? { input, output, cacheRead, cacheWrite, cost, turns } : undefined;
+}
+
 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." };
+	return { available: true, reason: "Live-session SDK exports are available and pi-crew can run experimental in-process live agents when runtime.mode=live-session." };
 }
 
-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);
+export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<LiveSessionRunResult> {
+	if (process.env.PI_CREW_MOCK_LIVE_SESSION === "success") {
+		const agentId = `${input.manifest.runId}:${input.task.id}`;
+		const inherited = input.runtimeConfig?.inheritContext === true && input.parentContext ? ` with inherited context: ${input.parentContext}` : "";
+		const event = { type: "message_end", message: { role: "assistant", content: [{ type: "text", text: `Mock live-session success for ${input.agent.name}${inherited}` }] } };
+		const mockSession = { steer: async () => {}, prompt: async () => {}, abort: async () => {} };
+		registerLiveAgent({ agentId, runId: input.manifest.runId, taskId: input.task.id, session: mockSession, status: "running" });
+		appendTranscript(input.transcriptPath, event);
+		const sidechainPath = sidechainOutputPath(input.manifest.stateRoot, input.task.id);
+		writeSidechainEntry(sidechainPath, { agentId, type: "user", message: { role: "user", content: input.prompt }, cwd: input.task.cwd });
+		writeSidechainEntry(sidechainPath, { agentId, type: "message", message: event, cwd: input.task.cwd });
+		input.onEvent?.(event);
+		const stdout = `Mock live-session success for ${input.agent.name}${inherited}`;
+		input.onOutput?.(stdout);
+		updateLiveAgentStatus(agentId, "completed");
+		return { available: true, exitCode: 0, stdout, stderr: "", jsonEvents: 1 };
+	}
+	const availability = await isLiveSessionRuntimeAvailable();
+	if (!availability.available) return { available: true, exitCode: 1, stdout: "", stderr: availability.reason ?? "Live-session runtime unavailable.", jsonEvents: 0, error: availability.reason };
+	const mod = await import("@mariozechner/pi-coding-agent") as LiveSessionModule;
+	if (typeof mod.createAgentSession !== "function") return { available: true, exitCode: 1, stdout: "", stderr: "createAgentSession export is unavailable.", jsonEvents: 0, error: "createAgentSession export is unavailable." };
+	let session: LiveSessionLike | undefined;
+	let unsubscribe: (() => void) | undefined;
+	let unsubscribeControlRealtime: (() => void) | undefined;
+	let controlTimer: ReturnType<typeof setInterval> | undefined;
+	let stdout = "";
+	let jsonEvents = 0;
+	try {
+		const agentDir = typeof mod.getAgentDir === "function" ? mod.getAgentDir() : undefined;
+		let resourceLoader: unknown;
+		if (mod.DefaultResourceLoader && agentDir) {
+			resourceLoader = new mod.DefaultResourceLoader({
+				cwd: input.task.cwd,
+				agentDir,
+				noPromptTemplates: true,
+				noThemes: true,
+				noContextFiles: input.runtimeConfig?.inheritContext !== true,
+				systemPromptOverride: () => liveSystemPrompt(input),
+				appendSystemPromptOverride: () => [],
+			});
+			await (resourceLoader as { reload?: () => Promise<void> }).reload?.();
+		}
+		const resolvedModel = modelFromRegistry(input.modelRegistry, input.agent.model) ?? input.parentModel;
+		const created = await mod.createAgentSession({
+			cwd: input.task.cwd,
+			...(agentDir ? { agentDir } : {}),
+			...(resourceLoader ? { resourceLoader } : {}),
+			...(mod.SessionManager?.inMemory ? { sessionManager: mod.SessionManager.inMemory(input.task.cwd) } : {}),
+			...(mod.SettingsManager?.create && agentDir ? { settingsManager: mod.SettingsManager.create(input.task.cwd, agentDir) } : {}),
+			...(input.modelRegistry ? { modelRegistry: input.modelRegistry } : {}),
+			...(resolvedModel ? { model: resolvedModel } : {}),
+			...(input.agent.thinking ? { thinkingLevel: input.agent.thinking } : {}),
+		});
+		session = created.session;
+		filterActiveTools(session, input.agent);
+		await session.bindExtensions?.({});
+		const agentId = `${input.manifest.runId}:${input.task.id}`;
+		registerLiveAgent({ agentId, runId: input.manifest.runId, taskId: input.task.id, session, status: "running" });
+		let controlCursor: LiveAgentControlCursor = { offset: 0 };
+		const seenControlRequestIds = new Set<string>();
+		let controlBusy = false;
+		const pollControl = async () => {
+			if (controlBusy || !session) return;
+			controlBusy = true;
+			try {
+				controlCursor = await applyLiveAgentControlRequests({ manifest: input.manifest, taskId: input.task.id, agentId, session, cursor: controlCursor, seenRequestIds: seenControlRequestIds });
+			} finally {
+				controlBusy = false;
+			}
+		};
+		unsubscribeControlRealtime = subscribeLiveControlRealtime((request) => {
+			if (request.runId !== input.manifest.runId || request.taskId !== input.task.id || !session) return;
+			void applyLiveAgentControlRequest({ request, taskId: input.task.id, agentId, session, seenRequestIds: seenControlRequestIds });
+		});
+		await pollControl();
+		controlTimer = setInterval(() => { void pollControl(); }, 500);
+		let turnCount = 0;
+		let softLimitReached = false;
+		const maxTurns = input.runtimeConfig?.maxTurns;
+		const graceTurns = input.runtimeConfig?.graceTurns ?? 5;
+		const sidechainPath = sidechainOutputPath(input.manifest.stateRoot, input.task.id);
+		writeSidechainEntry(sidechainPath, { agentId, type: "user", message: { role: "user", content: input.prompt }, cwd: input.task.cwd });
+		if (typeof session.subscribe === "function") {
+			unsubscribe = session.subscribe((event) => {
+				jsonEvents += 1;
+				appendTranscript(input.transcriptPath, event);
+				const sidechainType = eventToSidechainType(event);
+				if (sidechainType) writeSidechainEntry(sidechainPath, { agentId, type: sidechainType, message: event, cwd: input.task.cwd });
+				const obj = asRecord(event);
+				if (obj?.type === "turn_end") {
+					turnCount += 1;
+					if (maxTurns !== undefined && !softLimitReached && turnCount >= maxTurns) {
+						softLimitReached = true;
+						void session?.steer?.("You have reached your turn limit. Wrap up immediately — provide your final answer now.");
+					} else if (maxTurns !== undefined && softLimitReached && turnCount >= maxTurns + graceTurns) {
+						void session?.abort?.();
+					}
+				}
+				input.onEvent?.(event);
+				const text = [...eventText(event), ...finalAssistantText(event)].join("\n");
+				if (text.trim()) {
+					stdout += `${text}\n`;
+					input.onOutput?.(text);
+				}
+			});
+		}
+		if (input.signal) {
+			if (input.signal.aborted) await session.abort?.();
+			else input.signal.addEventListener("abort", () => { void session?.abort?.(); }, { once: true });
+		}
+		const effectivePrompt = input.runtimeConfig?.inheritContext === true && input.parentContext ? `${input.parentContext}\n\n---\n# Live Subagent Task\n${input.prompt}` : input.prompt;
+		await session.prompt?.(effectivePrompt, { source: "api", expandPromptTemplates: false });
+		const usage = usageFromStats(typeof session.getStats === "function" ? session.getStats() : session.stats);
+		updateLiveAgentStatus(agentId, "completed");
+		return { available: true, exitCode: 0, stdout: stdout.trim(), stderr: created.modelFallbackMessage ?? "", jsonEvents, usage };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		updateLiveAgentStatus(`${input.manifest.runId}:${input.task.id}`, "failed");
+		return { available: true, exitCode: 1, stdout: stdout.trim(), stderr: message, jsonEvents, error: message };
+	} finally {
+		if (controlTimer) clearInterval(controlTimer);
+		unsubscribeControlRealtime?.();
+		unsubscribe?.();
+	}
 }