pi-subagents 0.31.0 → 0.31.1

package/src/runs/background/control-channel.ts

@@ -0,0 +1,177 @@
+/**
+ * Cross-OS control channel for async subagent runs.
+ *
+ * Background runs are detached OS processes. The original control path delivered
+ * an interrupt with `process.kill(pid, SIGUSR2|SIGBREAK)`, but Windows cannot
+ * deliver those signals cross-process via `process.kill` and throws `ENOSYS`,
+ * which left async runs uninterruptible (no stop, no live steer) on Windows.
+ *
+ * This module adds a portable, file-based control inbox inside the run directory.
+ * The parent drops an interrupt request file; the runner watches the inbox and
+ * routes the request into its existing graceful `interruptRunner()` (pause +
+ * resumable), identically on every platform. The OS signal is kept only as an
+ * opportunistic fast-path; its failure is non-fatal because the file inbox is
+ * authoritative.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import { POLL_INTERVAL_MS } from "../../shared/types.ts";
+
+/**
+ * Opportunistic fast-path interrupt signal. On Unix `SIGUSR2` is trapped by the
+ * runner; on Windows `process.kill(pid, "SIGBREAK")` is not deliverable
+ * cross-process and throws `ENOSYS`, so the file inbox below is the real channel.
+ */
+export const INTERRUPT_SIGNAL: NodeJS.Signals = process.platform === "win32" ? "SIGBREAK" : "SIGUSR2";
+
+export type ControlChannelFs = Pick<typeof fs, "mkdirSync" | "existsSync" | "rmSync" | "watch">;
+export type ControlChannelTimers = { setInterval: typeof setInterval; clearInterval: typeof clearInterval };
+type KillFn = (pid: number, signal?: NodeJS.Signals | 0) => unknown;
+
+export interface InterruptRequest {
+	type: "interrupt";
+	ts?: number;
+	source?: string;
+	reason?: string;
+}
+
+/** Control inbox directory inside an async run dir. */
+export function controlInboxDir(asyncDir: string): string {
+	return path.join(asyncDir, "control");
+}
+
+/** Path of the portable interrupt request file. */
+export function interruptRequestPath(asyncDir: string): string {
+	return path.join(controlInboxDir(asyncDir), "interrupt.json");
+}
+
+/**
+ * Parent side: drop a portable interrupt request the runner's inbox watcher will
+ * pick up regardless of OS. Written atomically (temp + rename), dir auto-created.
+ */
+export function requestAsyncInterrupt(
+	asyncDir: string,
+	payload: Omit<InterruptRequest, "type"> = {},
+	deps: { now?: () => number } = {},
+): string {
+	const requestPath = interruptRequestPath(asyncDir);
+	const request: InterruptRequest = { ...payload, ts: payload.ts ?? deps.now?.() ?? Date.now(), type: "interrupt" };
+	writeAtomicJson(requestPath, request);
+	return requestPath;
+}
+
+/**
+ * Runner side: consume a pending interrupt request. Idempotent — removes the file
+ * so each distinct request fires exactly once. Returns whether one was pending.
+ */
+export function consumeInterruptRequest(
+	asyncDir: string,
+	fsImpl: Pick<typeof fs, "existsSync" | "rmSync"> = fs,
+): boolean {
+	const requestPath = interruptRequestPath(asyncDir);
+	if (!fsImpl.existsSync(requestPath)) return false;
+	try {
+		fsImpl.rmSync(requestPath, { force: true, recursive: true });
+	} catch {
+		// Already removed by a concurrent check — still counts as consumed.
+	}
+	return true;
+}
+
+/**
+ * Parent side: portable interrupt = authoritative file request + best-effort OS
+ * signal. The signal is only a latency optimization on Unix; ENOSYS on Windows
+ * is swallowed because the file inbox is authoritative there. Other signal
+ * failures are surfaced because they usually mean the runner is not alive to
+ * consume the request.
+ */
+export function deliverInterruptRequest(input: {
+	asyncDir: string;
+	pid?: number;
+	kill?: KillFn;
+	signal?: NodeJS.Signals;
+	now?: () => number;
+	source?: string;
+}): void {
+	const requestPath = requestAsyncInterrupt(input.asyncDir, input.source ? { source: input.source } : {}, { now: input.now });
+	if (typeof input.pid === "number" && input.pid > 0) {
+		try {
+			(input.kill ?? process.kill)(input.pid, input.signal ?? INTERRUPT_SIGNAL);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException | undefined)?.code === "ENOSYS") {
+				// File inbox is authoritative when custom cross-process signals are unavailable.
+				return;
+			}
+			try {
+				fs.rmSync(requestPath, { force: true });
+			} catch {
+				// Best effort cleanup; the caller still gets the signal failure.
+			}
+			throw error;
+		}
+	}
+}
+
+/**
+ * Runner side: watch the control inbox and route interrupt requests into
+ * `onInterrupt`. Uses `fs.watch` when available plus an interval poll as a
+ * portable safety net (covers filesystems/platforms where `fs.watch` is
+ * unreliable). Fires once per distinct request. Returns a disposer.
+ */
+export function watchAsyncControlInbox(
+	asyncDir: string,
+	opts: {
+		onInterrupt: () => void;
+		pollIntervalMs?: number;
+		fs?: ControlChannelFs;
+		timers?: ControlChannelTimers;
+	},
+): () => void {
+	const fsImpl = opts.fs ?? fs;
+	const timers = opts.timers ?? { setInterval, clearInterval };
+	const dir = controlInboxDir(asyncDir);
+	try {
+		fsImpl.mkdirSync(dir, { recursive: true });
+	} catch {
+		// Best effort — the poll/watch below tolerates a missing dir.
+	}
+
+	let disposed = false;
+	const check = (): void => {
+		if (disposed) return;
+		try {
+			if (consumeInterruptRequest(asyncDir, fsImpl)) opts.onInterrupt();
+		} catch {
+			// Never let inbox errors crash the runner.
+		}
+	};
+
+	// Handle a request that may have arrived before the watcher started.
+	check();
+
+	let watcher: fs.FSWatcher | undefined;
+	try {
+		watcher = fsImpl.watch(dir, () => check());
+		watcher.on?.("error", () => {
+			// fs.watch can emit on transient FS errors; the interval poll keeps us live.
+		});
+	} catch {
+		watcher = undefined;
+	}
+
+	const interval = timers.setInterval(check, opts.pollIntervalMs ?? POLL_INTERVAL_MS);
+	interval.unref?.();
+
+	return () => {
+		if (disposed) return;
+		disposed = true;
+		try {
+			watcher?.close();
+		} catch {
+			// ignore
+		}
+		timers.clearInterval(interval);
+	};
+}

package/src/runs/background/subagent-runner.ts

@@ -4,6 +4,7 @@ import * as path from "node:path";
 import { pathToFileURL } from "node:url";
 import type { Message } from "@earendil-works/pi-ai";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import { consumeInterruptRequest, watchAsyncControlInbox } from "./control-channel.ts";
 import { appendJsonl as appendRawJsonl, getArtifactPaths } from "../../shared/artifacts.ts";
 import { PI_CODING_AGENT_PACKAGE, getPiSpawnCommand, resolveInstalledPiPackageRoot } from "../shared/pi-spawn.ts";
 import { captureSingleOutputSnapshot, finalizeSingleOutput, formatSavedOutputReference, resolveSingleOutput, type SingleOutputSnapshot } from "../shared/single-output.ts";
@@ -1507,6 +1508,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 	}
 
 	const interruptRunner = () => {
+		consumeInterruptRequest(asyncDir);
 		if (interrupted || statusPayload.state !== "running") return;
 		interrupted = true;
 		const now = Date.now();
@@ -1532,6 +1534,10 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 		activeChildInterrupt?.();
 	};
 	process.on(ASYNC_INTERRUPT_SIGNAL, interruptRunner);
+	// Portable control inbox: the parent drops an interrupt request file here when
+	// it cannot deliver the OS signal (e.g. ENOSYS on Windows). Routes into the
+	// same graceful interruptRunner() so stop/steer work on every platform.
+	const disposeControlInbox = watchAsyncControlInbox(asyncDir, { onInterrupt: interruptRunner });
 	appendJsonl(
 		eventsPath,
 		JSON.stringify({
@@ -2317,6 +2323,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 		clearInterval(activityTimer);
 		activityTimer = undefined;
 	}
+	disposeControlInbox();
 	const effectiveSessionFile = sessionFile ?? latestSessionFile;
 	const runEndedAt = Date.now();
 	statusPayload.state = interrupted ? "paused" : results.every((r) => r.success) ? "complete" : "failed";

package/src/runs/foreground/subagent-executor.ts

@@ -51,6 +51,8 @@ import {
 	stripDetailsOutputsForIntercomReceipt,
 } from "../../intercom/result-intercom.ts";
 import { buildRevivedAsyncTask, interruptLiveAsyncResumeTarget, resolveAsyncResumeTarget } from "../background/async-resume.ts";
+import { deliverInterruptRequest } from "../background/control-channel.ts";
+import { reconcileAsyncRun } from "../background/stale-run-reconciler.ts";
 import { resolveAsyncRootResultPath } from "../background/chain-root-attachment.ts";
 import { createNestedRoute, readNestedControlResults, resolveInheritedNestedRouteFromEnv, resolveNestedAsyncDir, resolveNestedParentAddressFromEnv, updateForegroundNestedProjection, writeNestedControlRequest, writeNestedEvent, type NestedRunResolutionScope } from "../shared/nested-events.ts";
 import { resolveSubagentRunId, type ResolvedSubagentRunId } from "../background/run-id-resolver.ts";
@@ -97,7 +99,6 @@ import {
 	wrapForkTask,
 } from "../../shared/types.ts";
 
-const ASYNC_INTERRUPT_SIGNAL: NodeJS.Signals = process.platform === "win32" ? "SIGBREAK" : "SIGUSR2";
 const MUTATING_MANAGEMENT_ACTIONS = new Set(["create", "update", "delete"]);
 
 interface TaskParam {
@@ -372,7 +373,17 @@ function resolveResumeTarget(params: SubagentParamsLike, state: SubagentState, o
 	throw new Error("Run not found. Provide id or runId.");
 }
 
-function getAsyncInterruptTarget(state: SubagentState, runId: string | undefined): { asyncId: string; asyncDir: string } | undefined {
+function getAsyncInterruptTarget(
+	state: SubagentState,
+	runId: string | undefined,
+	location?: { asyncDir: string | null; resolvedId?: string },
+): { asyncId: string; asyncDir: string } | undefined {
+	if (location?.asyncDir) {
+		return {
+			asyncId: location.resolvedId ?? runId ?? path.basename(location.asyncDir),
+			asyncDir: location.asyncDir,
+		};
+	}
 	if (runId) {
 		const direct = state.asyncJobs.get(runId);
 		if (direct) return { asyncId: direct.asyncId, asyncDir: direct.asyncDir };
@@ -415,10 +426,15 @@ function emitControlNotification(input: {
 	}
 }
 
-function interruptAsyncRun(state: SubagentState, runId: string | undefined, kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean): AgentToolResult<Details> | null {
-	const target = getAsyncInterruptTarget(state, runId);
+function interruptAsyncRun(
+	state: SubagentState,
+	runId: string | undefined,
+	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean,
+	location?: { asyncDir: string | null; resolvedId?: string },
+): AgentToolResult<Details> | null {
+	const target = getAsyncInterruptTarget(state, runId, location);
 	if (!target) return null;
-	const status = readStatus(target.asyncDir);
+	const status = reconcileAsyncRun(target.asyncDir, { kill }).status;
 	if (!status || status.state !== "running" || typeof status.pid !== "number") {
 		return {
 			content: [{ type: "text", text: `No running async run with an interrupt-capable pid was found for '${runId ?? "current"}'.` }],
@@ -427,7 +443,7 @@ function interruptAsyncRun(state: SubagentState, runId: string | undefined, kill
 		};
 	}
 	try {
-		(kill ?? process.kill)(status.pid, ASYNC_INTERRUPT_SIGNAL);
+		deliverInterruptRequest({ asyncDir: target.asyncDir, pid: status.pid, kill, source: "interrupt-action" });
 		const tracked = state.asyncJobs.get(target.asyncId);
 		if (tracked) {
 			tracked.activityState = undefined;
@@ -719,11 +735,11 @@ function directNestedAsyncInterrupt(target: ResolvedSubagentRunId & { kind: "nes
 	const run = target.match.run;
 	const asyncDir = resolveNestedAsyncDir(target.match.rootRunId, run);
 	if (!asyncDir) return undefined;
-	const status = readStatus(asyncDir);
+	const status = reconcileAsyncRun(asyncDir, { resultsDir: path.join(RESULTS_DIR, "nested", target.match.rootRunId) }).status;
 	const pid = typeof status?.pid === "number" && status.pid > 0 ? status.pid : run.pid;
 	if (!status || status.state !== "running" || typeof pid !== "number" || pid <= 0) return undefined;
 	try {
-		process.kill(pid, ASYNC_INTERRUPT_SIGNAL);
+		deliverInterruptRequest({ asyncDir, pid, source: "nested-interrupt" });
 		return { content: [{ type: "text", text: `Interrupt requested for nested async run ${run.id}.` }], details: { mode: "management", results: [] } };
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
@@ -800,6 +816,7 @@ async function resumeAsyncRun(input: {
 			target,
 			state: input.deps.state,
 			kill: input.deps.kill,
+			resultsDir: RESULTS_DIR,
 		});
 		if (!interrupt.ok) {
 			return {
@@ -2784,7 +2801,12 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 						details: { mode: "management", results: [] },
 					};
 				}
-				const asyncInterruptResult = interruptAsyncRun(deps.state, resolved?.kind === "async" ? resolved.id : targetRunId, deps.kill);
+				const asyncInterruptResult = interruptAsyncRun(
+					deps.state,
+					resolved?.kind === "async" ? resolved.id : targetRunId,
+					deps.kill,
+					resolved?.kind === "async" ? resolved.location : undefined,
+				);
 				if (asyncInterruptResult) return asyncInterruptResult;
 				return {
 					content: [{ type: "text", text: "No interrupt-capable run found in this session." }],

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -35,6 +35,7 @@ export const CHILD_FANOUT_BOUNDARY_INSTRUCTIONS = [
 const PARENT_ONLY_CUSTOM_MESSAGE_TYPES = new Set([
 	"subagent-orchestration-instructions",
 	"subagent-slash-result",
+	"subagent-slash-text-result",
 	"subagent-notify",
 	"subagent_control_notice",
 	"subagent-control",

package/src/shared/types.ts

@@ -923,6 +923,7 @@ export const CHAIN_RUNS_DIR = path.join(TEMP_ROOT_DIR, "chain-runs");
 export const TEMP_ARTIFACTS_DIR = path.join(TEMP_ROOT_DIR, "artifacts");
 export const WIDGET_KEY = "subagent-async";
 export const SLASH_RESULT_TYPE = "subagent-slash-result";
+export const SLASH_TEXT_RESULT_TYPE = "subagent-slash-text-result";
 export const SLASH_SUBAGENT_REQUEST_EVENT = "subagent:slash:request";
 export const SLASH_SUBAGENT_STARTED_EVENT = "subagent:slash:started";
 export const SLASH_SUBAGENT_RESPONSE_EVENT = "subagent:slash:response";