pi-subagents 0.38.0 → 0.40.0

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

@@ -53,6 +53,13 @@ export interface StopRequest {
 	reason?: string;
 }
 
+export interface CheckpointDecisionRequest {
+	type: "approve-checkpoint" | "reject-checkpoint";
+	ts?: number;
+	source?: string;
+	reason?: string;
+}
+
 export interface SteerRequest {
 	type: "steer";
 	id: string;
@@ -110,6 +117,14 @@ export function stopRequestPath(asyncDir: string): string {
 	return path.join(controlInboxDir(asyncDir), "stop.json");
 }
 
+export function approveCheckpointRequestPath(asyncDir: string): string {
+	return path.join(controlInboxDir(asyncDir), "approve-checkpoint.json");
+}
+
+export function rejectCheckpointRequestPath(asyncDir: string): string {
+	return path.join(controlInboxDir(asyncDir), "reject-checkpoint.json");
+}
+
 /** Directory of parent-to-runner steering requests. */
 export function steerRequestsDir(asyncDir: string): string {
 	return path.join(controlInboxDir(asyncDir), STEER_REQUESTS_DIR);
@@ -254,6 +269,18 @@ export function requestAsyncStop(
 	return requestPath;
 }
 
+export function requestAsyncCheckpointDecision(
+	asyncDir: string,
+	type: CheckpointDecisionRequest["type"],
+	payload: Omit<CheckpointDecisionRequest, "type"> = {},
+	deps: { now?: () => number } = {},
+): string {
+	const requestPath = type === "approve-checkpoint" ? approveCheckpointRequestPath(asyncDir) : rejectCheckpointRequestPath(asyncDir);
+	const request: CheckpointDecisionRequest = { ...payload, ts: payload.ts ?? deps.now?.() ?? Date.now(), type };
+	writeAtomicJson(requestPath, request);
+	return requestPath;
+}
+
 export function requestAsyncSteer(
 	asyncDir: string,
 	payload: { message: string; targetIndex?: number; targetIndexes?: number[]; source?: string; id?: string; ts?: number },
@@ -457,6 +484,21 @@ export function consumeStopRequest(
 	return true;
 }
 
+export function consumeCheckpointDecisionRequest(
+	asyncDir: string,
+	fsImpl: Pick<typeof fs, "existsSync" | "rmSync"> = fs,
+): "approved" | "rejected" | undefined {
+	if (fsImpl.existsSync(rejectCheckpointRequestPath(asyncDir))) {
+		try { fsImpl.rmSync(rejectCheckpointRequestPath(asyncDir), { force: true, recursive: true }); } catch {}
+		return "rejected";
+	}
+	if (fsImpl.existsSync(approveCheckpointRequestPath(asyncDir))) {
+		try { fsImpl.rmSync(approveCheckpointRequestPath(asyncDir), { force: true, recursive: true }); } catch {}
+		return "approved";
+	}
+	return undefined;
+}
+
 /**
  * Parent side: portable interrupt = authoritative file request + best-effort OS
  * signal. The signal is only a latency optimization on Unix; ENOSYS on Windows
@@ -513,6 +555,21 @@ export function deliverStopRequest(input: {
 	requestAsyncStop(input.asyncDir, input.source ? { source: input.source } : {}, { now: input.now });
 }
 
+export function deliverCheckpointDecisionRequest(input: {
+	asyncDir: string;
+	decision: "approved" | "rejected";
+	now?: () => number;
+	source?: string;
+	reason?: string;
+}): void {
+	requestAsyncCheckpointDecision(
+		input.asyncDir,
+		input.decision === "approved" ? "approve-checkpoint" : "reject-checkpoint",
+		{ ...(input.source ? { source: input.source } : {}), ...(input.reason ? { reason: input.reason } : {}) },
+		{ now: input.now },
+	);
+}
+
 /**
  * Runner side: watch the control inbox and route interrupt requests into
  * `onInterrupt`. Uses `fs.watch` when available plus an interval poll as a
@@ -526,6 +583,7 @@ export function watchAsyncControlInbox(
 		onTimeout?: () => void;
 		onStop?: () => void;
 		onSteer?: (request: SteerRequest) => void;
+		onCheckpointDecision?: (decision: "approved" | "rejected") => void;
 		onSteerCapability?: (capability: SteerCapability) => void;
 		onSteerAck?: (ack: SteerAck) => void;
 		pollIntervalMs?: number;
@@ -549,6 +607,8 @@ export function watchAsyncControlInbox(
 			if (consumeStopRequest(asyncDir, fsImpl)) opts.onStop?.();
 			if (consumeTimeoutRequest(asyncDir, fsImpl)) opts.onTimeout?.();
 			if (consumeInterruptRequest(asyncDir, fsImpl)) opts.onInterrupt();
+			const checkpointDecision = consumeCheckpointDecisionRequest(asyncDir, fsImpl);
+			if (checkpointDecision) opts.onCheckpointDecision?.(checkpointDecision);
 			for (const request of consumeSteerRequests(asyncDir, fsImpl)) opts.onSteer?.(request);
 			for (const capability of consumeSteerCapabilities(asyncDir, fsImpl)) opts.onSteerCapability?.(capability);
 			for (const ack of consumeSteerAcks(asyncDir, fsImpl)) opts.onSteerAck?.(ack);

package/src/runs/background/notify.ts

@@ -15,10 +15,11 @@ import {
 	resolveCompletionBatchConfig,
 } from "./completion-batcher.ts";
 import { SUBAGENT_ASYNC_COMPLETE_EVENT, SUBAGENT_FOREGROUND_COMPLETE_EVENT, type ParallelHandoffReference, type SubagentState } from "../../shared/types.ts";
+import { isUnexplainedProcessSignal } from "../shared/process-signal.ts";
 
 export interface SubagentNotifyDetails {
 	agent: string;
-	status: "completed" | "failed" | "paused";
+	status: "completed" | "failed" | "paused" | "stopped";
 	source?: "async" | "foreground";
 	taskInfo?: string;
 	resultPreview: string;
@@ -37,6 +38,21 @@ export interface CompletionNotification {
 	summary?: string;
 	exitCode?: number;
 	state?: string;
+	processSignal?: string | null;
+	interrupted?: boolean;
+	timedOut?: boolean;
+	stopped?: boolean;
+	turnBudgetExceeded?: boolean;
+	results?: Array<{
+		status?: string;
+		success?: boolean;
+		exitCode?: number | null;
+		processSignal?: string | null;
+		interrupted?: boolean;
+		timedOut?: boolean;
+		stopped?: boolean;
+		turnBudgetExceeded?: boolean;
+	}>;
 	timestamp?: number;
 	durationMs?: number;
 	cwd?: string;
@@ -92,7 +108,7 @@ export function formatSingleCompletion(details: SubagentNotifyDetails): string {
 
 export function parseSubagentNotifyContent(content: string): SubagentNotifyDetails | undefined {
 	const lines = content.split("\n");
-	const match = (lines[0] ?? "").match(/^(Background task|Detached foreground task) (completed|failed|paused): \*\*(.+?)\*\*(?:\s+(\([^)]*\)))?$/);
+	const match = (lines[0] ?? "").match(/^(Background task|Detached foreground task) (completed|failed|paused|stopped): \*\*(.+?)\*\*(?:\s+(\([^)]*\)))?$/);
 	if (!match) return undefined;
 	const body = lines.slice(2);
 	let sessionIndex = -1;
@@ -179,12 +195,18 @@ function completionBatchKey(result: CompletionNotification): string {
 export function buildCompletionDetails(result: CompletionNotification): SubagentNotifyDetails {
 	const agent = result.agent ?? "unknown";
 	const summary = typeof result.summary === "string" ? result.summary : "";
-	const paused = !result.success && (
+	const stopped = result.stopped === true
+		|| result.state === "stopped"
+		|| (result.success !== true && result.exitCode !== 0 && isUnexplainedProcessSignal(result))
+		|| result.results?.some((child) => child.stopped === true
+			|| child.status === "stopped"
+			|| (child.success !== true && child.exitCode !== 0 && isUnexplainedProcessSignal(child))) === true;
+	const paused = !stopped && !result.success && (
 		result.exitCode === 0
 		|| result.state === "paused"
 		|| summary.startsWith("Paused after interrupt.")
 	);
-	const status = paused ? "paused" : result.success ? "completed" : "failed";
+	const status = stopped ? "stopped" : paused ? "paused" : result.success ? "completed" : "failed";
 	const taskInfo =
 		result.taskIndex !== undefined && result.totalTasks !== undefined
 			? ` (${result.taskIndex + 1}/${result.totalTasks})`

package/src/runs/background/result-watcher.ts

@@ -8,6 +8,7 @@ import {
 	type NestedRunSummary,
 	type ParallelHandoffReference,
 	type SubagentResultIntercomChild,
+	type SubagentOutputState,
 	type SubagentState,
 } from "../../shared/types.ts";
 import {
@@ -45,10 +46,15 @@ type ResultWatcherDeps = {
 type ResultFileChild = {
 	agent?: string;
 	output?: string;
+	outputState?: SubagentOutputState;
 	error?: string;
 	success?: boolean;
 	state?: string;
+	interrupted?: boolean;
+	timedOut?: boolean;
 	stopped?: boolean;
+	turnBudgetExceeded?: boolean;
+	processSignal?: string | null;
 	sessionFile?: string;
 	artifactPaths?: { outputPath?: string };
 	intercomTarget?: string;
@@ -174,9 +180,9 @@ export function createResultWatcher(
 			const hasResultChildren = Array.isArray(data.results) && data.results.length > 0;
 			const resultChildren: ResultFileChild[] = hasResultChildren
 				? data.results!
-				: [{ agent: data.agent ?? undefined, output: data.summary, success: data.success }];
+				: [{ agent: data.agent ?? undefined, output: data.summary, outputState: "unknown", success: data.success }];
 			const normalizedChildren = attachNestedChildrenToResultChildren(runId, resultChildren.map((result = {}, index): SubagentResultIntercomChild => {
-				const baseOutput = result.output ?? data.summary;
+				const baseOutput = hasResultChildren ? result.output : result.output ?? data.summary;
 				const hasRealOutput = typeof baseOutput === "string" && baseOutput.trim().length > 0;
 				const output = hasRealOutput ? baseOutput : "(no output)";
 				const summary = result.success === false && result.error
@@ -193,7 +199,18 @@ export function createResultWatcher(
 							: undefined;
 				return {
 					agent: result.agent ?? data.agent ?? `step-${index + 1}`,
-					status: resolveSubagentResultStatus({ success: result.success, state: childState }),
+					status: resolveSubagentResultStatus({
+						success: result.success,
+						state: childState,
+						interrupted: result.interrupted,
+						timedOut: result.timedOut,
+						stopped: result.stopped,
+						turnBudgetExceeded: result.turnBudgetExceeded,
+						processSignal: result.processSignal,
+					}),
+					outputState: result.outputState === "present" || result.outputState === "absent" || result.outputState === "unknown"
+						? result.outputState
+						: "unknown",
 					summary,
 					index,
 					artifactPath: result.artifactPaths?.outputPath,

package/src/runs/background/run-status.ts

@@ -8,6 +8,7 @@ import { formatModelThinking } from "../../shared/formatters.ts";
 import { formatActivityLabel } from "../../shared/status-format.ts";
 import { ASYNC_DIR, RESULTS_DIR, type AsyncStatus, type Details, type ForegroundResumeRun, type NestedRunSummary, type SteeringStatus, type SubagentState } from "../../shared/types.ts";
 import { resolveSubagentIntercomTarget } from "../../intercom/intercom-bridge.ts";
+import { resolveSubagentResultStatus } from "../../intercom/result-intercom.ts";
 import { readProcessTerminal, sanitizeProcessTerminal } from "./process-terminal.ts";
 import { resolveAsyncRunLocation } from "./async-resume.ts";
 import { resolveSubagentRunId } from "./run-id-resolver.ts";
@@ -39,6 +40,11 @@ function hasExistingSessionFile(value: unknown): value is string {
 	return typeof value === "string" && fs.existsSync(value);
 }
 
+function formatCheckpointGuidance(runId: string | undefined, checkpoint: AsyncStatus["checkpoint"] | undefined): string | undefined {
+	if (!runId || !checkpoint || checkpoint.status !== "pending") return undefined;
+	return `Checkpoint: ${checkpoint.name}${checkpoint.message ? ` — ${checkpoint.message}` : ""}\nApprove: subagent({ action: "approve-checkpoint", id: "${runId}" })\nReject: subagent({ action: "reject-checkpoint", id: "${runId}" })`;
+}
+
 function formatResumeGuidance(runId: string | undefined, children: Array<{ agent?: unknown; sessionFile?: unknown }>, fallbackSessionFile?: unknown, options: { stopped?: boolean } = {}): string {
 	if (options.stopped) return "Resume: unavailable; stopped runs are not resumable. Start a new run instead.";
 	const knownChildren = children
@@ -126,6 +132,12 @@ function formatRememberedForegroundStatus(run: ForegroundResumeRun): string {
 	else lines.push(`Transcript: subagent({ action: "status", id: "${run.runId}", index: 0, view: "transcript" })`);
 	const detached = run.children.some((child) => child.status === "detached");
 	const resumable = run.children.find((child) => hasExistingSessionFile(child.sessionFile));
+	if (run.checkpoint?.status === "pending") {
+		lines.push(`Checkpoint: ${run.checkpoint.name}${run.checkpoint.message ? ` — ${run.checkpoint.message}` : ""}`);
+		lines.push(`Approve: subagent({ action: "approve-checkpoint", id: "${run.runId}" })`);
+		lines.push(`Reject: subagent({ action: "reject-checkpoint", id: "${run.runId}" })`);
+		return lines.join("\n");
+	}
 	if (detached) {
 		lines.push(`Recovery: reply to the supervisor request first, then wait with subagent_wait({ id: "${run.runId}" }); do not resume or launch a replacement while any child remains detached.`);
 	} else if (resumable) {
@@ -403,7 +415,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 			if (status.sessionFile) lines.push(`Session: ${status.sessionFile}`);
 			if (status.state === "running") lines.push(`Steer running child: subagent({ action: "steer", id: "${status.runId}", message: "..." })`);
 			if (status.state !== "running") {
-				lines.push(formatResumeGuidance(status.runId, status.steps ?? [], status.sessionFile, { stopped: status.state === "stopped" || status.stopped === true }));
+				lines.push(formatCheckpointGuidance(status.runId, status.checkpoint) ?? formatResumeGuidance(status.runId, status.steps ?? [], status.sessionFile, { stopped: status.state === "stopped" || status.stopped === true }));
 			}
 			if (fs.existsSync(logPath)) lines.push(`Log: ${logPath}`);
 			if (fs.existsSync(eventsPath)) lines.push(`Events: ${eventsPath}`);
@@ -415,7 +427,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 	if (resultPath) {
 		try {
 			const raw = fs.readFileSync(resultPath, "utf-8");
-			const data = JSON.parse(raw) as { id?: string; runId?: string; agent?: string; success?: boolean; summary?: string; output?: string; exitCode?: number; state?: string; sessionFile?: string; parallelHandoff?: { path?: string }; results?: Array<{ agent?: string; output?: string; summary?: string; sessionFile?: string; state?: string; success?: boolean; exitCode?: number | null }> };
+			const data = JSON.parse(raw) as { id?: string; runId?: string; agent?: string; success?: boolean; summary?: string; output?: string; exitCode?: number; state?: string; stopped?: boolean; timedOut?: boolean; turnBudgetExceeded?: boolean; processSignal?: string | null; sessionFile?: string; parallelHandoff?: { path?: string }; results?: Array<{ agent?: string; output?: string; summary?: string; sessionFile?: string; state?: string; success?: boolean; exitCode?: number | null; stopped?: boolean; timedOut?: boolean; turnBudgetExceeded?: boolean; interrupted?: boolean; processSignal?: string | null }> };
 			if (params.view === "transcript") {
 				try {
 					return { content: [{ type: "text", text: formatAsyncResultTranscript(data, resultPath, { index: params.index, lines: params.lines }) }], details: { mode: "single", results: [] } };
@@ -424,7 +436,21 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 					return { content: [{ type: "text", text: message }], isError: true, details: { mode: "single", results: [] } };
 				}
 			}
-			const status = data.state === "stopped" ? "stopped" : data.success ? "complete" : data.state === "paused" || data.exitCode === 0 ? "paused" : "failed";
+			const childStatuses = Array.isArray(data.results)
+				? data.results.map((child) => resolveSubagentResultStatus({
+					success: child.success,
+					state: child.state,
+					interrupted: child.interrupted,
+					timedOut: child.timedOut,
+					stopped: child.stopped,
+					turnBudgetExceeded: child.turnBudgetExceeded,
+					processSignal: child.processSignal,
+					exitCode: typeof child.exitCode === "number" ? child.exitCode : undefined,
+				}))
+				: [];
+			const status = data.state === "stopped" || data.stopped === true || childStatuses.includes("stopped")
+				? "stopped"
+				: data.success ? "complete" : data.state === "paused" || data.exitCode === 0 ? "paused" : "failed";
 			const runId = data.runId ?? data.id ?? resolvedId;
 			const lines = [`Run: ${runId}`, `State: ${status}`, `Result: ${resultPath}`];
 			if (data.parallelHandoff?.path) lines.push(`Parallel handoff: ${data.parallelHandoff.path}`);