pi-agent-squad 0.8.4 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-squad",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "description": "Interactive multi-agent orchestration, messaging, and live sessions for the Pi Coding Agent",
   "type": "module",
   "keywords": [
@@ -20,11 +20,28 @@
   "dependencies": {
     "pi-compact-ui": "^0.1.0"
   },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.3",
+    "@earendil-works/pi-tui": "0.84.3",
+    "@types/node": "^24.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "jiti": "^2.7.0",
+    "tsx": "^4.20.0",
+    "typebox": "^1.0.0",
+    "typescript": "^5.9.0"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "test": "node --import tsx --test test/**/*.test.ts"
+  },
   "pi": {
     "extensions": [
       "./index.ts"

package/session.ts

@@ -1,5 +1,7 @@
 export interface SubagentSessionHandle {
 	readonly agent: string;
+	/** Child Pi session file when the child is configured to persist one. */
+	readonly sessionFile?: string;
 	getMessages(): Promise<any[]>;
 	isStreaming(): Promise<boolean>;
 	send(message: string): Promise<void>;

package/spawn.ts

@@ -51,9 +51,13 @@ export interface SpawnOptions {
 	childIndex: number;
 	signal?: AbortSignal;
 	timeoutMs?: number;
+	/** Persist the child Pi session so full background results remain recoverable. */
+	persistSession?: boolean;
 }
 
 export interface InteractiveSpawnOptions extends SpawnOptions {
+	/** Called after the RPC child has started, before the initial task prompt. */
+	onStarted?: (childSessionFile?: string) => void;
 	onSession?: (session: SubagentSessionHandle) => void;
 	onEvent?: (event: any) => void;
 }
@@ -63,6 +67,38 @@ const FORCE_KILL_DELAY_MS = 5000;
 const TEARDOWN_ABORT_CAP_MS = 3000;
 const CRASH_STDERR_MAX_CHARS = 2000;
 
+/**
+ * Keep the owning task lifecycle alive while a routed message is waiting for
+ * the same child session to settle. RpcClient can emit agent_settled before
+ * the waiting caller has read the routed reply; tearing down at that instant
+ * would kill the child and turn a successful reply into exit 143.
+ */
+export class SessionSettleGate {
+	private activeWaits = 0;
+	private settleDeferred = false;
+
+	constructor(private readonly settle: () => void) {}
+
+	beginWait(): () => void {
+		this.activeWaits++;
+		let finished = false;
+		return () => {
+			if (finished) return;
+			finished = true;
+			this.activeWaits = Math.max(0, this.activeWaits - 1);
+			if (this.activeWaits === 0 && this.settleDeferred) {
+				this.settleDeferred = false;
+				this.settle();
+			}
+		};
+	}
+
+	onAgentSettled(): void {
+		if (this.activeWaits > 0) this.settleDeferred = true;
+		else this.settle();
+	}
+}
+
 /** Bound a best-effort teardown step so a stuck child can never stall cleanup. */
 async function raceWithCap(promise: Promise<void>, capMs: number): Promise<void> {
 	let capTimer: ReturnType<typeof setTimeout> | undefined;
@@ -204,6 +240,7 @@ export async function spawnInteractiveSubagent(opts: InteractiveSpawnOptions): P
 	let childExitListener: ((code: number | null, exitSignal: string | null) => void) | undefined;
 	let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
 	const sessionListeners = new Set<(event: any) => void>();
+	const sessionSettleGate = new SessionSettleGate(() => settleLifecycle({ kind: "settled" }));
 
 	const emitSessionEvent = (event: any) => {
 		for (const listener of sessionListeners) {
@@ -222,7 +259,7 @@ export async function spawnInteractiveSubagent(opts: InteractiveSpawnOptions): P
 	};
 
 	try {
-		const args: string[] = ["--no-session"];
+		const args: string[] = opts.persistSession ? [] : ["--no-session"];
 		if (agent.thinking) args.push("--thinking", agent.thinking);
 		const tools = agent.tools ? [...agent.tools] : [];
 		for (const tool of ["send_message", "read_inbox", "reply_message"]) {
@@ -286,7 +323,9 @@ export async function spawnInteractiveSubagent(opts: InteractiveSpawnOptions): P
 			// be cancelled during teardown). The subscription above is live
 			// before the prompt is sent, so a very fast run cannot settle in the
 			// gap between prompt acceptance and waiter setup.
-			if (event?.type === "agent_settled") settleLifecycle({ kind: "settled" });
+			if (event?.type === "agent_settled") {
+				sessionSettleGate.onAgentSettled();
+			}
 		});
 
 		// Timeout and abort feed the same terminal-cause promise as settle/crash.
@@ -315,8 +354,11 @@ export async function spawnInteractiveSubagent(opts: InteractiveSpawnOptions): P
 				childExitListener(childProcess.exitCode, childProcess.signalCode);
 			}
 		}
+		const initialState = await activeClient.getState();
+		opts.onStarted?.(initialState.sessionFile);
 		const session: SubagentSessionHandle = {
 			agent: address,
+			sessionFile: initialState.sessionFile,
 			getMessages: () => activeClient.getMessages(),
 			isStreaming: async () => (await activeClient.getState()).isStreaming,
 			send: async (message: string) => {
@@ -326,47 +368,52 @@ export async function spawnInteractiveSubagent(opts: InteractiveSpawnOptions): P
 				else await activeClient.prompt(message);
 			},
 			sendAndWait: async (message: string, messageTimeoutMs: number, messageSignal?: AbortSignal) => {
-				await initialPromptAcceptedPromise;
-				if (messageSignal?.aborted) throw new Error("Message delivery cancelled.");
-				const before = await activeClient.getMessages();
-				// Own settle detection so the timer and listener are always
-				// cancelled below (RpcClient.waitForIdle would leak both).
-				let resolveSettled!: () => void;
-				let rejectSettled!: (error: unknown) => void;
-				const settled = new Promise<void>((resolve, reject) => {
-					resolveSettled = resolve;
-					rejectSettled = reject;
-				});
-				let unsubscribeSettle: (() => void) | undefined;
-				let settleTimer: ReturnType<typeof setTimeout> | undefined;
-				let abortHandler: (() => void) | undefined;
-				const aborted = new Promise<never>((_resolve, reject) => {
-					abortHandler = () => reject(new Error("Message delivery cancelled."));
-					if (messageSignal?.aborted) abortHandler();
-					else messageSignal?.addEventListener("abort", abortHandler, { once: true });
-				});
+				const finishSessionWait = sessionSettleGate.beginWait();
 				try {
-					unsubscribeSettle = activeClient.onEvent((event: any) => {
-						if (event?.type === "agent_settled") resolveSettled();
+					await initialPromptAcceptedPromise;
+					if (messageSignal?.aborted) throw new Error("Message delivery cancelled.");
+					const before = await activeClient.getMessages();
+					// Own settle detection so the timer and listener are always
+					// cancelled below (RpcClient.waitForIdle would leak both).
+					let resolveSettled!: () => void;
+					let rejectSettled!: (error: unknown) => void;
+					const settled = new Promise<void>((resolve, reject) => {
+						resolveSettled = resolve;
+						rejectSettled = reject;
+					});
+					let unsubscribeSettle: (() => void) | undefined;
+					let settleTimer: ReturnType<typeof setTimeout> | undefined;
+					let abortHandler: (() => void) | undefined;
+					const aborted = new Promise<never>((_resolve, reject) => {
+						abortHandler = () => reject(new Error("Message delivery cancelled."));
+						if (messageSignal?.aborted) abortHandler();
+						else messageSignal?.addEventListener("abort", abortHandler, { once: true });
 					});
-					settleTimer = setTimeout(() => {
-						rejectSettled(
-							new Error(`Timeout waiting for agent to become idle. Stderr: ${activeClient.getStderr()}`),
-						);
-					}, messageTimeoutMs);
-					settleTimer.unref?.();
-					const state = await activeClient.getState();
-					if (state.isStreaming) await activeClient.steer(message);
-					else await activeClient.prompt(message);
-					// `crashed` fails fast if the child dies mid-message.
-					await Promise.race([settled, aborted, crashed]);
+					try {
+						unsubscribeSettle = activeClient.onEvent((event: any) => {
+							if (event?.type === "agent_settled") resolveSettled();
+						});
+						settleTimer = setTimeout(() => {
+							rejectSettled(
+								new Error(`Timeout waiting for agent to become idle. Stderr: ${activeClient.getStderr()}`),
+							);
+						}, messageTimeoutMs);
+						settleTimer.unref?.();
+						const state = await activeClient.getState();
+						if (state.isStreaming) await activeClient.steer(message);
+						else await activeClient.prompt(message);
+						// `crashed` fails fast if the child dies mid-message.
+						await Promise.race([settled, aborted, crashed]);
+					} finally {
+						if (settleTimer) clearTimeout(settleTimer);
+						unsubscribeSettle?.();
+						if (messageSignal && abortHandler) messageSignal.removeEventListener("abort", abortHandler);
+					}
+					const after = await activeClient.getMessages();
+					return getFinalOutput(after.slice(before.length) as unknown as SingleResult["messages"]);
 				} finally {
-					if (settleTimer) clearTimeout(settleTimer);
-					unsubscribeSettle?.();
-					if (messageSignal && abortHandler) messageSignal.removeEventListener("abort", abortHandler);
+					finishSessionWait();
 				}
-				const after = await activeClient.getMessages();
-				return getFinalOutput(after.slice(before.length) as unknown as SingleResult["messages"]);
 			},
 			abort: () => activeClient.abort(),
 			subscribe: (listener) => {

package/task-delivery.ts

@@ -0,0 +1,201 @@
+import {
+	TASK_RESULT_DELIVERY_PREFIX,
+	type PersistedTaskState,
+} from "./task-state.ts";
+
+export const BACKGROUND_EVENT_TYPE = "pi_subagent_background_event";
+export const DELIVERY_ID_PREFIX = TASK_RESULT_DELIVERY_PREFIX;
+
+export interface BackgroundEventDetails {
+	agent?: string;
+	address?: string;
+	status?: "done" | "error";
+	body?: string;
+	elapsedMs?: number;
+	runId?: string;
+	deliveryId?: string;
+}
+
+export interface BackgroundResultPayload {
+	body: string;
+	content?: string;
+}
+
+export function resultDeliveryId(runId: string): string {
+	return `${DELIVERY_ID_PREFIX}${runId}`;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	try {
+		const prototype = Object.getPrototypeOf(value);
+		return prototype === Object.prototype || prototype === null;
+	} catch {
+		return false;
+	}
+}
+
+/** Match the real Pi CustomMessageEntry shape persisted by sendMessage(). */
+export function entryHasResultDelivery(entry: unknown, deliveryId: string): boolean {
+	if (!isPlainObject(entry)) return false;
+	if (entry.type !== "custom_message" || entry.customType !== BACKGROUND_EVENT_TYPE) return false;
+	if (!isPlainObject(entry.details)) return false;
+	return (
+		entry.details.deliveryId === deliveryId &&
+		typeof entry.details.runId === "string" &&
+		entry.details.deliveryId === resultDeliveryId(entry.details.runId) &&
+		typeof entry.details.agent === "string" &&
+		typeof entry.details.address === "string" &&
+		entry.details.status === "done"
+	);
+}
+
+export function branchHasResultDelivery(entries: readonly unknown[], deliveryId: string): boolean {
+	return entries.some((entry) => entryHasResultDelivery(entry, deliveryId));
+}
+
+export function createBackgroundResultMessage(
+	state: PersistedTaskState,
+	payload?: BackgroundResultPayload,
+): {
+	customType: typeof BACKGROUND_EVENT_TYPE;
+	content: string;
+	display: true;
+	details: BackgroundEventDetails;
+} {
+	const body = payload?.body || state.resultSummary || "(result summary unavailable)";
+	const contentBody = payload?.content || body;
+	return {
+		customType: BACKGROUND_EVENT_TYPE,
+		content: `[background subagent done] Subagent ${state.agent} done (run ${state.runId.slice(0, 8)})\n\n--- result ---\n${contentBody}`,
+		display: true,
+		details: {
+			agent: state.agent,
+			address: state.address,
+			status: "done",
+			body,
+			elapsedMs: Math.max(0, (state.endedAt ?? state.updatedAt) - state.startedAt),
+			runId: state.runId,
+			deliveryId: state.deliveryId,
+		},
+	};
+}
+
+interface OutboxJob {
+	state: PersistedTaskState;
+	payload?: BackgroundResultPayload;
+	sessionToken: string;
+	timer?: ReturnType<typeof setTimeout>;
+	sent: boolean;
+}
+
+export interface RecoveryOutboxOptions {
+	getSessionToken(): string | undefined;
+	getBranch(): readonly unknown[];
+	getTaskState(runId: string): PersistedTaskState | undefined;
+	send(
+		message: ReturnType<typeof createBackgroundResultMessage>,
+		options: { triggerTurn: true; deliverAs: "steer" },
+	): void;
+	markInjected(state: PersistedTaskState): void;
+	onError?(error: unknown, state: PersistedTaskState): void;
+	pollMs?: number;
+}
+
+/**
+ * In-memory scheduler for completed-but-undelivered results. Durable state
+ * remains in the Pi session; losing this object cannot lose recovery data.
+ */
+export class RecoveryOutbox {
+	private readonly jobs = new Map<string, OutboxJob>();
+	private readonly pollMs: number;
+
+	constructor(private readonly options: RecoveryOutboxOptions) {
+		this.pollMs = Math.max(10, options.pollMs ?? 250);
+	}
+
+	get size(): number {
+		return this.jobs.size;
+	}
+
+	enqueue(state: PersistedTaskState, payload?: BackgroundResultPayload): boolean {
+		const deliveryId = state.deliveryId;
+		const sessionToken = this.options.getSessionToken();
+		if (
+			state.status !== "completed" ||
+			state.resultInjected !== false ||
+			!deliveryId ||
+			!sessionToken ||
+			this.jobs.has(deliveryId)
+		) {
+			return false;
+		}
+		const job: OutboxJob = { state, payload, sessionToken, sent: false };
+		this.jobs.set(deliveryId, job);
+		job.timer = setTimeout(() => this.run(deliveryId, job), 0);
+		return true;
+	}
+
+	cancelAll(): void {
+		for (const job of this.jobs.values()) {
+			if (job.timer) clearTimeout(job.timer);
+		}
+		this.jobs.clear();
+	}
+
+	private finish(deliveryId: string, job: OutboxJob): void {
+		if (job.timer) clearTimeout(job.timer);
+		if (this.jobs.get(deliveryId) === job) this.jobs.delete(deliveryId);
+	}
+
+	private schedulePoll(deliveryId: string, job: OutboxJob): void {
+		job.timer = setTimeout(() => this.run(deliveryId, job), this.pollMs);
+		job.timer.unref?.();
+	}
+
+	private run(deliveryId: string, job: OutboxJob): void {
+		if (this.jobs.get(deliveryId) !== job) return;
+		if (this.options.getSessionToken() !== job.sessionToken) {
+			this.finish(deliveryId, job);
+			return;
+		}
+		const current = this.options.getTaskState(job.state.runId);
+		if (
+			!current ||
+			current.status !== "completed" ||
+			current.resultInjected !== false ||
+			current.deliveryId !== deliveryId
+		) {
+			this.finish(deliveryId, job);
+			return;
+		}
+
+		// Check immediately before every possible send. This is the durable
+		// dedupe barrier for both crash window B and concurrent recovery events.
+		if (branchHasResultDelivery(this.options.getBranch(), deliveryId)) {
+			try {
+				this.options.markInjected(current);
+				this.finish(deliveryId, job);
+			} catch (error) {
+				this.options.onError?.(error, current);
+				this.schedulePoll(deliveryId, job);
+			}
+			return;
+		}
+
+		if (!job.sent) {
+			try {
+				this.options.send(createBackgroundResultMessage(current, job.payload), {
+					triggerTurn: true,
+					deliverAs: "steer",
+				});
+				job.sent = true;
+			} catch (error) {
+				this.options.onError?.(error, current);
+				this.finish(deliveryId, job);
+				return;
+			}
+		}
+		this.schedulePoll(deliveryId, job);
+	}
+}

package/task-recovery.ts

@@ -0,0 +1,41 @@
+import type { PersistedTaskState } from "./task-state.ts";
+
+export interface TaskRecoveryPlan {
+	interrupt: PersistedTaskState[];
+	markInjected: PersistedTaskState[];
+	deliver: PersistedTaskState[];
+}
+
+export type DeliveryPresence = (deliveryId: string) => boolean;
+
+/**
+ * Build a recovery plan without performing any process launch. The caller
+ * applies append-only snapshots and schedules result delivery after the
+ * session_start handlers have finished.
+ */
+export function planTaskRecovery(
+	states: ReadonlyMap<string, PersistedTaskState>,
+	ownerRuntimeId: string,
+	liveRunIds: ReadonlySet<string>,
+	hasDelivery: DeliveryPresence,
+): TaskRecoveryPlan {
+	const plan: TaskRecoveryPlan = { interrupt: [], markInjected: [], deliver: [] };
+	for (const state of states.values()) {
+		if (state.status === "starting" || state.status === "running") {
+			const genuinelyLive =
+				state.ownerRuntimeId === ownerRuntimeId && liveRunIds.has(state.runId);
+			if (!genuinelyLive) plan.interrupt.push(state);
+			continue;
+		}
+		if (
+			state.status === "completed" &&
+			state.resultInjected === false &&
+			state.deliveryId
+		) {
+			if (hasDelivery(state.deliveryId)) plan.markInjected.push(state);
+			else plan.deliver.push(state);
+		}
+	}
+	return plan;
+}
+