pi-crew 0.9.7 → 0.9.9

package/src/runtime/crash-classification.ts

@@ -0,0 +1,208 @@
+/**
+ * Crash Classification Taxonomy — pure function for categorizing worker exits.
+ *
+ * Distilled from gajae-code's `debug/crash-diagnostics.ts` (P0 item #1).
+ * Unlike the original, this module is pure: it does NOT write crash reports or
+ * touch the filesystem. The file-I/O layer is intentionally omitted; callers
+ * that want durable crash logs can layer them on top of {@link classifyProcessCrash}.
+ *
+ * The classification precedence (most-significant first) mirrors the
+ * reference implementation:
+ *
+ *   1. timeout          — process was terminated by the response-timeout guard
+ *   2. cancelled        — cooperative cancellation (AbortSignal) triggered exit
+ *   3. spawn_error      — child_process emitted an `error` event before `exit`
+ *   4. native_panic     — stderr indicates a native crash (SIGSEGV / abort / panic)
+ *   5. signal_exit      — the process was terminated by an OS signal
+ *   6. clean_exit       — exit code 0
+ *   7. non_zero_exit    — exit code != 0 (and != null)
+ *   8. protocol_exit    — exit code is null with no signal (protocol/stream
+ *                         ended before a normal exit was observed)
+ *   9. unknown          — defensive fallback (should not occur in practice)
+ *
+ * NOTE on timeout-vs-cancel precedence: when BOTH `timedOut` and `cancelled`
+ * are true, `timeout` wins (the timeout terminated the process). This matches
+ * gajae-code and the existing child-pi.ts response-timeout guard, which fires
+ * the hard kill and is the proximate cause.
+ */
+
+/**
+ * Categorical classification of why a worker process ended.
+ *
+ * @see classifyProcessCrash
+ */
+export type CrashClass =
+	| "clean_exit"
+	| "non_zero_exit"
+	| "signal_exit"
+	| "timeout"
+	| "cancelled"
+	| "spawn_error"
+	| "protocol_exit"
+	| "native_panic"
+	| "unknown";
+
+/**
+ * Inputs to {@link classifyProcessCrash}. All fields are optional/safe-defaulting
+ * so callers can pass a partial view (e.g. just `{ exitCode: 0 }`).
+ *
+ * Field semantics:
+ * - `exitCode`    — the OS exit code, or `null` when no code was observed.
+ * - `signal`      — the terminating signal name (e.g. `"SIGTERM"`) or `null`.
+ * - `cancelled`   — true when cooperative cancellation (AbortSignal) was requested.
+ * - `timedOut`    — true when the response-timeout guard fired (and likely killed).
+ * - `killed`      — true when the parent explicitly killed the child (best-effort).
+ * - `spawnError`  — truthy when the child emitted a spawn/process `error` event.
+ * - `stderrSnippet` — tail of captured stderr, used to detect native panics.
+ */
+export interface CrashClassificationInput {
+	exitCode?: number | null;
+	signal?: string | null;
+	cancelled?: boolean;
+	timedOut?: boolean;
+	killed?: boolean;
+	spawnError?: unknown;
+	stderrSnippet?: string;
+}
+
+/**
+ * Result of classifying an exit. `crashClass` is machine-readable;
+ * `reason` is a human-friendly one-liner suitable for logs/diagnostics.
+ */
+export interface CrashClassification {
+	crashClass: CrashClass;
+	reason: string;
+}
+
+// ── native-panic detection ──────────────────────────────────────────────────
+//
+// We look for a small, well-known set of native-crash signatures in the stderr
+// tail. This is deliberately conservative: false positives would mislabel
+// ordinary non-zero exits as native panics. The patterns are anchored on
+// substrings that do not appear in normal application output.
+
+interface NativePanicSignature {
+	/** Substring to search for (case-insensitive). */
+	pattern: string;
+	/** Human-readable class-specific reason suffix. */
+	label: string;
+}
+
+const NATIVE_PANIC_SIGNATURES: readonly NativePanicSignature[] = [
+	{ pattern: "sigsegv", label: "segmentation fault" },
+	{ pattern: "segfault", label: "segmentation fault" },
+	{ pattern: "segmentation fault", label: "segmentation fault" },
+	{ pattern: "sigabrt", label: "abort signal" },
+	{ pattern: "abort(", label: "abort" },
+	{ pattern: "fatal error", label: "V8/node fatal error" },
+	{ pattern: "panic:", label: "rust/go panic" },
+	{ pattern: "thread '", label: "rust panic (thread context)" },
+	{ pattern: "illegal instruction", label: "illegal instruction" },
+	{ pattern: "double free", label: "heap corruption (double free)" },
+];
+
+/**
+ * If the stderr tail contains a recognizable native-crash signature, return the
+ * matching label; otherwise `null`. Case-insensitive.
+ */
+function detectNativePanic(stderrSnippet: string | undefined): string | null {
+	if (!stderrSnippet) return null;
+	const lower = stderrSnippet.toLowerCase();
+	for (const sig of NATIVE_PANIC_SIGNATURES) {
+		if (lower.includes(sig.pattern)) return sig.label;
+	}
+	return null;
+}
+
+/** Normalize an optional/signal-ish value to `string | null`. */
+function normalizeSignal(signal: string | null | undefined): string | null {
+	return signal ?? null;
+}
+
+/**
+ * Classify a worker exit into a {@link CrashClass}.
+ *
+ * Pure: no I/O, no globals, no side effects. Deterministic given the same input.
+ * Safe to call from any context (including signal handlers).
+ *
+ * @example
+ * classifyProcessCrash({ exitCode: 0 })                       // → clean_exit
+ * classifyProcessCrash({ exitCode: 1 })                       // → non_zero_exit
+ * classifyProcessCrash({ signal: "SIGTERM" })                 // → signal_exit
+ * classifyProcessCrash({ timedOut: true, exitCode: null })    // → timeout
+ * classifyProcessCrash({ cancelled: true, exitCode: null })   // → cancelled
+ * classifyProcessCrash({ spawnError: new Error("ENOENT") })   // → spawn_error
+ * classifyProcessCrash({ exitCode: null })                    // → protocol_exit
+ * classifyProcessCrash({ exitCode: 139, signal: "SIGSEGV" })  // → signal_exit
+ * classifyProcessCrash({ exitCode: 134, stderrSnippet: "abort()" }) // → native_panic
+ */
+export function classifyProcessCrash(input: CrashClassificationInput): CrashClassification {
+	const exitCode = input.exitCode ?? null;
+	const signal = normalizeSignal(input.signal);
+
+	// 1. Timeout takes precedence: the response-timeout guard is the proximate
+	//    cause of death even if cancellation was also requested.
+	if (input.timedOut) {
+		return { crashClass: "timeout", reason: "process timed out (response timeout guard fired)" };
+	}
+
+	// 2. Cooperative cancellation.
+	if (input.cancelled) {
+		return { crashClass: "cancelled", reason: "process was cancelled (abort requested)" };
+	}
+
+	// 3. Spawn error: the child never started or emitted a process error.
+	if (input.spawnError !== undefined && input.spawnError !== null) {
+		return {
+			crashClass: "spawn_error",
+			reason: `spawn error: ${stringifyError(input.spawnError)}`,
+		};
+	}
+
+	// 4. Native panic from stderr (only when we have a signal/abnormal exit —
+	//    never reclassify a clean exit as a panic based on stderr noise).
+	const abnormalExit = signal !== null || (exitCode !== null && exitCode !== 0);
+	if (abnormalExit) {
+		const panic = detectNativePanic(input.stderrSnippet);
+		if (panic !== null) {
+			return { crashClass: "native_panic", reason: `native panic detected: ${panic}` };
+		}
+	}
+
+	// 5. Signal exit.
+	if (signal !== null) {
+		return { crashClass: "signal_exit", reason: `process exited after signal ${signal}` };
+	}
+
+	// 6. Clean exit.
+	if (exitCode === 0) {
+		return { crashClass: "clean_exit", reason: "process exited cleanly" };
+	}
+
+	// 7. Non-zero exit.
+	if (exitCode !== null) {
+		return { crashClass: "non_zero_exit", reason: `process exited with code ${exitCode}` };
+	}
+
+	// 8. Protocol exit: exitCode is null with no signal — the process stream
+	//    ended before a normal exit was observed (e.g. stdio closed unexpectedly).
+	//    If `killed` is true but no signal was recorded, treat as protocol_exit
+	//    (the kill may not have delivered a signal we could capture).
+	if (input.killed) {
+		return { crashClass: "protocol_exit", reason: "process was killed but no signal/exit code was captured" };
+	}
+
+	// 8b. Truly null exitCode with no other context — protocol/stream ended early.
+	return { crashClass: "protocol_exit", reason: "process exited before protocol completion (exit code unknown)" };
+}
+
+/** Render an unknown error value to a short message string. */
+function stringifyError(error: unknown): string {
+	if (error instanceof Error) return error.message || error.name;
+	if (typeof error === "string") return error;
+	try {
+		return String(error);
+	} catch {
+		return "(unstringifiable error)";
+	}
+}

package/src/runtime/custom-tools/irc-tool.ts

@@ -14,7 +14,7 @@
 
 import { defineTool, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "@sinclair/typebox";
-import { listLiveAgents, sendIrcMessage, broadcastIrcMessage } from "../live-agent-manager.ts";
+import { listLiveAgents, sendIrcMessage, broadcastIrcMessage, respondAsBackground } from "../live-agent-manager.ts";
 import type { IrcMessage } from "../live-irc.ts";
 
 const IrcParams = Type.Object({
@@ -37,7 +37,7 @@ const IrcParams = Type.Object({
 	),
 	awaitReply: Type.Optional(
 		Type.Boolean({
-			description: "Wait for a reply (default: true for DM, false for broadcast). Not yet supported — messages are fire-and-forget.",
+			description: "Wait for a prose reply (default: true for DM, false for broadcast). For DMs the recipient receives the message as a non-blocking background turn and its reply is returned to the caller. Broadcast always ignores this flag.",
 		}),
 	),
 });
@@ -64,6 +64,8 @@ interface IrcDetails {
 	delivered?: string[];
 	notFound?: string[];
 	peers?: Array<{ id: string; status: string }>;
+	/** Replies received from recipients (awaitReply DM path). */
+	replies?: Array<{ from: string; text: string }>;
 	error?: string;
 }
 
@@ -130,10 +132,10 @@ function executeList(selfId: string): { content: Array<{ type: "text"; text: str
 	};
 }
 
-function executeSend(
+async function executeSend(
 	selfId: string,
 	params: IrcParams,
-): { content: Array<{ type: "text"; text: string }>; details: IrcDetails } {
+): Promise<{ content: Array<{ type: "text"; text: string }>; details: IrcDetails }> {
 	const to = params.to?.trim();
 	const message = params.message?.trim();
 
@@ -156,23 +158,52 @@ function executeSend(
 		};
 	}
 
+	// awaitReply defaults to true for DMs, false for broadcast. Broadcast
+	// always ignores the flag (fire-and-forget) — there is no single sender
+	// to receive a correlated reply from.
+	const isBroadcast = to === "all";
+	const wantsReply = !isBroadcast && (params.awaitReply ?? true);
+
 	const ircMessage: IrcMessage = {
 		from: selfId,
 		to,
 		content: message,
 		timestamp: new Date().toISOString(),
-		awaitReply: params.awaitReply,
+		awaitReply: wantsReply,
 	};
 
 	const notFound: string[] = [];
 	const delivered: string[] = [];
+	const replies: Array<{ from: string; text: string }> = [];
 
 	try {
-		if (to === "all") {
+		if (isBroadcast) {
+			// Broadcast: always fire-and-forget regardless of awaitReply.
 			const recipients = broadcastIrcMessage(selfId, ircMessage);
 			delivered.push(...recipients);
+		} else if (wantsReply) {
+			// DM with reply: use the non-blocking side-channel.
+			const agents = listLiveAgents();
+			const target = agents.find((a) => a.agentId === to);
+			if (!target || (target.status !== "running" && target.status !== "queued")) {
+				notFound.push(to);
+			} else {
+				const result = await respondAsBackground(to, selfId, message, { awaitReply: true });
+				if (result.ok) {
+					delivered.push(to);
+					if (result.replyContent) replies.push({ from: to, text: result.replyContent });
+				} else if (result.timedOut) {
+					// Message was delivered (non-blocking), but no reply in time.
+					delivered.push(to);
+					replies.push({ from: to, text: `(no reply — timed out)` });
+				} else {
+					// Delivery channel unavailable or cancelled.
+					if (result.error === "cancelled") delivered.push(to);
+					else notFound.push(to);
+				}
+			}
 		} else {
-			// DM to specific agent
+			// DM fire-and-forget (awaitReply explicitly false).
 			const agents = listLiveAgents();
 			const target = agents.find((a) => a.agentId === to);
 			if (!target || (target.status !== "running" && target.status !== "queued")) {
@@ -197,6 +228,14 @@ function executeSend(
 	} else {
 		lines.push("No recipients received the message.");
 	}
+	if (replies.length > 0) {
+		lines.push("");
+		lines.push("## Replies");
+		for (const reply of replies) {
+			lines.push(`### ${reply.from}`);
+			lines.push(reply.text);
+		}
+	}
 	if (notFound.length > 0) {
 		lines.push(`Unknown / unavailable peers: ${notFound.join(", ")}`);
 	}
@@ -209,6 +248,7 @@ function executeSend(
 			to,
 			delivered: delivered.length > 0 ? delivered : undefined,
 			notFound: notFound.length > 0 ? notFound : undefined,
+			replies: replies.length > 0 ? replies : undefined,
 		},
 	};
 }

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

@@ -416,3 +416,188 @@ function drainIrcMessages(agentIdOrTaskId: string): IrcMessage[] {
 	handle.pendingMessages.length = 0;
 	return messages;
 }
+
+/* ── IRC reply support (side-channel Q&A) ─────────────────────────── */
+
+/** Default timeout for awaiting a side-channel reply (60s). */
+const DEFAULT_REPLY_TIMEOUT_MS = 60_000;
+
+/** Result of a background reply attempt. */
+export interface BackgroundReplyResult {
+	ok: boolean;
+	/** Correlation id for the pending reply (present once registered). */
+	corrId?: string;
+	/** Reply prose content (present on success when awaitReply was set). */
+	replyContent?: string;
+	/** Human-readable error description. */
+	error?: string;
+	/** True when the reply did not arrive before the timeout. */
+	timedOut?: boolean;
+}
+
+interface PendingReply {
+	corrId: string;
+	targetAgentId: string;
+	fromId: string;
+	deadline: number;
+	resolve: (result: BackgroundReplyResult) => void;
+	timer?: ReturnType<typeof setTimeout>;
+}
+
+/** In-process pending replies keyed by correlation id. */
+const pendingReplies = new Map<string, PendingReply>();
+/** Reverse index: targetAgentId → set of corrIds awaiting a reply from it. */
+const pendingRepliesByTarget = new Map<string, Set<string>>();
+
+function makeCorrelationId(): string {
+	return `irc_reply_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/**
+ * Deliver a message to a live agent's session as a *background* turn —
+ * without blocking the recipient's main agent loop — and (optionally)
+ * await a prose reply via a side-channel.
+ *
+ * Non-blocking invariant (mirrors gajae-code's `respondAsBackground`):
+ * the message is injected via `sendCustomMessage` (triggerTurn:false) or a
+ * fire-and-forget `session.prompt`; we NEVER await the recipient's full
+ * main-loop turn. When `awaitReply` is set we instead await an event-driven
+ * reply resolution (see {@link resolveIrcReply}) bounded by a timeout.
+ *
+ * Note on mailbox.ts reply fields: those file-based fields
+ * (`replyTo`/`replyContent`/`replyDeadline`/`updateMailboxMessageReply`)
+ * serve cross-process workers that communicate via on-disk mailbox files.
+ * Live-session agents share a single process, so an in-memory event-driven
+ * registry is used here — it is lower-latency and trivially non-blocking.
+ * Both mechanisms coexist; file-based workers keep using mailbox.ts.
+ */
+export async function respondAsBackground(
+	targetAgentId: string,
+	fromId: string,
+	message: string,
+	opts?: { awaitReply?: boolean; timeoutMs?: number; signal?: AbortSignal },
+): Promise<BackgroundReplyResult> {
+	const handle = getLiveAgent(targetAgentId);
+	if (!handle) return { ok: false, error: `Live agent '${targetAgentId}' not found.` };
+
+	const awaitReply = opts?.awaitReply ?? false;
+	const timeoutMs = opts?.timeoutMs ?? DEFAULT_REPLY_TIMEOUT_MS;
+	const corrId = makeCorrelationId();
+
+	// --- Non-blocking delivery -------------------------------------------
+	const session = handle.session as Record<string, unknown>;
+	const deliveredTag = `[DM from ${fromId}] ${message}`;
+	let delivered = false;
+	if (typeof session.sendCustomMessage === "function") {
+		try {
+			(session.sendCustomMessage as (msg: unknown, o?: unknown) => void)(
+				{ customType: "irc", content: deliveredTag, display: "collapsed", corrId },
+				{ deliverAs: "followUp", triggerTurn: false },
+			);
+			delivered = true;
+		} catch {
+			// fall through to prompt-based delivery
+		}
+	}
+	if (!delivered && typeof handle.session.prompt === "function") {
+		const promptText = `${deliveredTag}${awaitReply ? ` (reply correlation: ${corrId})` : ""}`;
+		void handle.session.prompt(promptText, { source: "api", expandPromptTemplates: false }).catch((error) => logInternalError("live-agent-manager.respondAsBackground", error, `agentId=${handle.agentId}`));
+		delivered = true;
+	}
+	if (!delivered) return { ok: false, error: `Target '${targetAgentId}' has no message channel.` };
+	handle.updatedAt = new Date().toISOString();
+
+	if (!awaitReply) return { ok: true, corrId };
+
+	// --- Await reply (event-driven, bounded by timeout) ------------------
+	return awaitPendingReply(corrId, targetAgentId, fromId, timeoutMs, opts?.signal);
+}
+
+/**
+ * Register a pending reply and resolve it when the reply arrives, the
+ * timeout elapses, or the caller's abort signal fires.
+ *
+ * @internal exported for testing
+ */
+export function awaitPendingReply(
+	corrId: string,
+	targetAgentId: string,
+	fromId: string,
+	timeoutMs: number,
+	signal?: AbortSignal,
+): Promise<BackgroundReplyResult> {
+	return new Promise((resolve) => {
+		const deadline = Date.now() + timeoutMs;
+		let settled = false;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		let signalListener: (() => void) | undefined;
+
+		const finish = (result: BackgroundReplyResult) => {
+			if (settled) return;
+			settled = true;
+			if (timer) clearTimeout(timer);
+			if (signalListener && signal) signal.removeEventListener("abort", signalListener);
+			pendingReplies.delete(corrId);
+			const set = pendingRepliesByTarget.get(targetAgentId);
+			set?.delete(corrId);
+			if (set && set.size === 0) pendingRepliesByTarget.delete(targetAgentId);
+			resolve(result);
+		};
+
+		timer = setTimeout(() => finish({ ok: false, corrId, timedOut: true }), timeoutMs);
+
+		if (signal) {
+			if (signal.aborted) {
+				finish({ ok: false, corrId, error: "cancelled" });
+				return;
+			}
+			signalListener = () => finish({ ok: false, corrId, error: "cancelled" });
+			signal.addEventListener("abort", signalListener, { once: true });
+		}
+
+		pendingReplies.set(corrId, { corrId, targetAgentId, fromId, deadline, resolve: finish, timer });
+		const set = pendingRepliesByTarget.get(targetAgentId) ?? new Set<string>();
+		set.add(corrId);
+		pendingRepliesByTarget.set(targetAgentId, set);
+	});
+}
+
+/**
+ * Resolve a pending side-channel reply. Called by the reply-routing layer
+ * (e.g. irc-tool when the recipient sends a message back referencing the
+ * correlation id, or by tests simulating a recipient response).
+ *
+ * Returns true if a pending reply was resolved, false if none matched
+ * (already timed out / cancelled / unknown correlation id).
+ */
+export function resolveIrcReply(corrId: string, replyContent: string): boolean {
+	const pending = pendingReplies.get(corrId);
+	if (!pending) return false;
+	pending.resolve({ ok: true, corrId, replyContent });
+	return true;
+}
+
+/**
+ * Cancel a pending side-channel reply (e.g. sender gave up).
+ * Returns true if a pending reply was cancelled, false if none matched.
+ */
+export function cancelIrcReply(corrId: string, reason = "cancelled"): boolean {
+	const pending = pendingReplies.get(corrId);
+	if (!pending) return false;
+	pending.resolve({ ok: false, corrId, error: reason });
+	return true;
+}
+
+/** Correlation ids currently awaiting a reply from the given target agent. */
+export function pendingReplyCorrIdsForTarget(targetAgentId: string): string[] {
+	return [...(pendingRepliesByTarget.get(targetAgentId) ?? [])];
+}
+
+/** Clear all pending replies (test helper). */
+export function clearPendingRepliesForTest(): void {
+	for (const pending of pendingReplies.values()) {
+		if (pending.timer) clearTimeout(pending.timer);
+	}
+	pendingReplies.clear();
+	pendingRepliesByTarget.clear();
+}