pi-subagents 0.17.3 → 0.17.5

package/subagent-runner.ts

@@ -8,15 +8,18 @@ import { appendJsonl, getArtifactPaths } from "./artifacts.ts";
 import { getPiSpawnCommand } from "./pi-spawn.ts";
 import { captureSingleOutputSnapshot, resolveSingleOutput } from "./single-output.ts";
 import {
+	type ActivityState,
 	type ArtifactConfig,
 	type ArtifactPaths,
 	type ModelAttempt,
+	type ResolvedControlConfig,
 	type Usage,
 	DEFAULT_MAX_OUTPUT,
 	type MaxOutputConfig,
 	truncateOutput,
 	getSubagentDepthEnv,
 } from "./types.ts";
+import { DEFAULT_CONTROL_CONFIG } from "./subagent-control.ts";
 import {
 	type RunnerSubagentStep as SubagentStep,
 	type RunnerStep,
@@ -60,6 +63,7 @@ interface SubagentRunConfig {
 	piArgv1?: string;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
+	controlConfig?: ResolvedControlConfig;
 }
 
 interface StepResult {
@@ -75,6 +79,7 @@ interface StepResult {
 }
 
 const require = createRequire(import.meta.url);
+const ASYNC_INTERRUPT_SIGNAL: NodeJS.Signals = process.platform === "win32" ? "SIGBREAK" : "SIGUSR2";
 
 function findLatestSessionFile(sessionDir: string): string | null {
 	try {
@@ -95,6 +100,18 @@ function emptyUsage(): Usage {
 	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
 }
 
+function tokenUsageFromAttempts(attempts: ModelAttempt[] | undefined): TokenUsage | null {
+	if (!attempts || attempts.length === 0) return null;
+	let input = 0;
+	let output = 0;
+	for (const attempt of attempts) {
+		input += attempt.usage?.input ?? 0;
+		output += attempt.usage?.output ?? 0;
+	}
+	const total = input + output;
+	return total > 0 ? { input, output, total } : null;
+}
+
 interface ChildEventContext {
 	eventsPath: string;
 	runId: string;
@@ -133,6 +150,7 @@ interface RunPiStreamingResult {
 	model?: string;
 	error?: string;
 	finalOutput: string;
+	interrupted?: boolean;
 }
 
 function runPiStreaming(
@@ -144,6 +162,7 @@ function runPiStreaming(
 	piArgv1?: string,
 	maxSubagentDepth?: number,
 	childEventContext?: ChildEventContext,
+	registerInterrupt?: (interrupt: (() => void) | undefined) => void,
 ): Promise<RunPiStreamingResult> {
 	return new Promise((resolve) => {
 		const outputStream = fs.createWriteStream(outputFile, { flags: "w" });
@@ -160,6 +179,7 @@ function runPiStreaming(
 		const usage = emptyUsage();
 		let model: string | undefined;
 		let error: string | undefined;
+		let interrupted = false;
 		const rawStdoutLines: string[] = [];
 
 		const writeOutputLine = (line: string) => {
@@ -267,6 +287,15 @@ function runPiStreaming(
 		child.stderr.on("data", (chunk: Buffer) => {
 			processStderrText(chunk.toString());
 		});
+		registerInterrupt?.(() => {
+			if (settled) return;
+			interrupted = true;
+			if (!error) error = "Interrupted. Waiting for explicit next action.";
+			trySignalChild(child, "SIGINT");
+			setTimeout(() => {
+				if (!settled) trySignalChild(child, "SIGTERM");
+			}, 1000).unref?.();
+		});
 		const clearDrainTimers = () => {
 			if (finalDrainTimer) {
 				clearTimeout(finalDrainTimer);
@@ -301,6 +330,7 @@ function runPiStreaming(
 		});
 		child.on("close", (exitCode, signal) => {
 			settled = true;
+			registerInterrupt?.(undefined);
 			clearDrainTimers();
 			clearStdioGuard();
 			if (stdoutBuf.trim()) processStdoutLine(stdoutBuf);
@@ -309,17 +339,19 @@ function runPiStreaming(
 			const finalOutput = getFinalOutput(messages) || rawStdoutLines.join("\n").trim();
 			resolve({
 				stderr,
-				exitCode: forcedTerminationSignal || signal ? (exitCode ?? 1) : exitCode,
+				exitCode: interrupted ? 0 : forcedTerminationSignal || signal ? (exitCode ?? 1) : exitCode,
 				messages,
 				usage,
 				model,
-				error,
+				error: interrupted ? undefined : error,
 				finalOutput,
+				interrupted,
 			});
 		});
 
 		child.on("error", (spawnError) => {
 			settled = true;
+			registerInterrupt?.(undefined);
 			clearDrainTimers();
 			clearStdioGuard();
 			outputStream.end();
@@ -481,6 +513,7 @@ interface SingleStepContext {
 	outputFile: string;
 	piPackageRoot?: string;
 	piArgv1?: string;
+	registerInterrupt?: (interrupt: (() => void) | undefined) => void;
 }
 
 /** Run a single pi agent step, returning output and metadata */
@@ -496,6 +529,7 @@ async function runSingleStep(
 	attemptedModels?: string[];
 	modelAttempts?: ModelAttempt[];
 	artifactPaths?: ArtifactPaths;
+	interrupted?: boolean;
 }> {
 	const placeholderRegex = new RegExp(ctx.placeholder.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g");
 	const task = step.task.replace(placeholderRegex, () => ctx.previousOutput);
@@ -551,6 +585,7 @@ async function runSingleStep(
 			ctx.piArgv1,
 			step.maxSubagentDepth,
 			{ eventsPath, runId: ctx.id, stepIndex: ctx.flatIndex, agent: step.agent },
+			ctx.registerInterrupt,
 		);
 		cleanupTempDir(tempDir);
 
@@ -627,13 +662,15 @@ async function runSingleStep(
 		attemptedModels: attemptedModels.length > 0 ? attemptedModels : undefined,
 		modelAttempts,
 		artifactPaths,
+		interrupted: finalResult?.interrupted,
 	};
 }
 
 type RunnerStatusPayload = {
 	runId: string;
 	mode: "single" | "chain";
-	state: "queued" | "running" | "complete" | "failed";
+	state: "queued" | "running" | "complete" | "failed" | "paused";
+	activityState?: ActivityState;
 	startedAt: number;
 	endedAt?: number;
 	lastUpdate: number;
@@ -643,6 +680,7 @@ type RunnerStatusPayload = {
 	steps: Array<{
 		agent: string;
 		status: "pending" | "running" | "complete" | "failed";
+		activityState?: ActivityState;
 		startedAt?: number;
 		endedAt?: number;
 		durationMs?: number;
@@ -714,9 +752,11 @@ function markParallelGroupRunning(input: {
 	for (let taskIndex = 0; taskIndex < input.group.parallel.length; taskIndex++) {
 		const flatTaskIndex = input.groupStartFlatIndex + taskIndex;
 		input.statusPayload.steps[flatTaskIndex].status = "running";
+		input.statusPayload.steps[flatTaskIndex].activityState = "active";
 		input.statusPayload.steps[flatTaskIndex].startedAt = input.groupStartTime;
 	}
 	input.statusPayload.currentStep = input.groupStartFlatIndex;
+	input.statusPayload.activityState = "active";
 	input.statusPayload.lastUpdate = input.groupStartTime;
 	input.statusPayload.outputFile = path.join(input.asyncDir, `output-${input.groupStartFlatIndex}.log`);
 	writeJson(input.statusPath, input.statusPayload);
@@ -769,6 +809,9 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 	const statusPath = path.join(asyncDir, "status.json");
 	const eventsPath = path.join(asyncDir, "events.jsonl");
 	const logPath = path.join(asyncDir, `subagent-log-${id}.md`);
+	const controlConfig = config.controlConfig ?? DEFAULT_CONTROL_CONFIG;
+	let activeChildInterrupt: (() => void) | undefined;
+	let interrupted = false;
 	let previousCumulativeTokens: TokenUsage = { input: 0, output: 0, total: 0 };
 	let latestSessionFile: string | undefined;
 
@@ -780,6 +823,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 		runId: id,
 		mode: flatSteps.length > 1 ? "chain" : "single",
 		state: "running",
+		activityState: controlConfig.enabled ? "starting" : undefined,
 		startedAt: overallStartTime,
 		lastUpdate: overallStartTime,
 		pid: process.pid,
@@ -788,6 +832,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 		steps: flatSteps.map((step) => ({
 			agent: step.agent,
 			status: "pending",
+			activityState: controlConfig.enabled ? "starting" : undefined,
 			skills: step.skills,
 			model: step.model,
 			attemptedModels: step.modelCandidates && step.modelCandidates.length > 0 ? step.modelCandidates : step.model ? [step.model] : undefined,
@@ -799,6 +844,28 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 
 	fs.mkdirSync(asyncDir, { recursive: true });
 	writeJson(statusPath, statusPayload);
+	const interruptRunner = () => {
+		if (interrupted || statusPayload.state !== "running") return;
+		interrupted = true;
+		const now = Date.now();
+		statusPayload.state = "paused";
+		statusPayload.activityState = "paused";
+		statusPayload.lastUpdate = now;
+		const current = statusPayload.steps[statusPayload.currentStep];
+		if (current?.status === "running") {
+			current.activityState = "paused";
+			current.endedAt = now;
+			current.durationMs = current.startedAt ? now - current.startedAt : undefined;
+		}
+		writeJson(statusPath, statusPayload);
+		appendJsonl(eventsPath, JSON.stringify({
+			type: "subagent.run.paused",
+			ts: now,
+			runId: id,
+		}));
+		activeChildInterrupt?.();
+	};
+	process.on(ASYNC_INTERRUPT_SIGNAL, interruptRunner);
 	appendJsonl(
 		eventsPath,
 		JSON.stringify({
@@ -814,6 +881,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 	let flatIndex = 0;
 
 	for (let stepIndex = 0; stepIndex < steps.length; stepIndex++) {
+		if (interrupted) break;
 		const step = steps[stepIndex];
 
 		if (isParallelGroup(step)) {
@@ -912,6 +980,9 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 							outputFile: path.join(asyncDir, `output-${fi}.log`),
 							piPackageRoot: config.piPackageRoot,
 							piArgv1: config.piArgv1,
+							registerInterrupt: (interrupt) => {
+								activeChildInterrupt = interrupt;
+							},
 						});
 						if (task.sessionFile) {
 							latestSessionFile = task.sessionFile;
@@ -944,24 +1015,23 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 
 				flatIndex += group.parallel.length;
 
-				if (config.sessionDir) {
-					for (let t = 0; t < group.parallel.length; t++) {
-						const taskSessionDir = path.join(config.sessionDir, `parallel-${t}`);
-						const taskTokens = parseSessionTokens(taskSessionDir);
-						if (taskTokens) {
-							const fi = groupStartFlatIndex + t;
-							statusPayload.steps[fi].tokens = taskTokens;
-							previousCumulativeTokens = {
-								input: previousCumulativeTokens.input + taskTokens.input,
-								output: previousCumulativeTokens.output + taskTokens.output,
-								total: previousCumulativeTokens.total + taskTokens.total,
-							};
-						}
-					}
-					statusPayload.totalTokens = { ...previousCumulativeTokens };
-					statusPayload.lastUpdate = Date.now();
-					writeJson(statusPath, statusPayload);
+				for (let t = 0; t < group.parallel.length; t++) {
+					const fi = groupStartFlatIndex + t;
+					const sessionTokens = config.sessionDir
+						? parseSessionTokens(path.join(config.sessionDir, `parallel-${t}`))
+						: null;
+					const taskTokens = sessionTokens ?? tokenUsageFromAttempts(parallelResults[t]?.modelAttempts);
+					if (!taskTokens) continue;
+					statusPayload.steps[fi].tokens = taskTokens;
+					previousCumulativeTokens = {
+						input: previousCumulativeTokens.input + taskTokens.input,
+						output: previousCumulativeTokens.output + taskTokens.output,
+						total: previousCumulativeTokens.total + taskTokens.total,
+					};
 				}
+				statusPayload.totalTokens = { ...previousCumulativeTokens };
+				statusPayload.lastUpdate = Date.now();
+				writeJson(statusPath, statusPayload);
 
 				for (const pr of parallelResults) {
 					results.push({
@@ -1007,6 +1077,8 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 			const stepStartTime = Date.now();
 			statusPayload.currentStep = flatIndex;
 			statusPayload.steps[flatIndex].status = "running";
+			statusPayload.steps[flatIndex].activityState = "active";
+			statusPayload.activityState = "active";
 			statusPayload.steps[flatIndex].skills = seqStep.skills;
 			statusPayload.steps[flatIndex].startedAt = stepStartTime;
 			statusPayload.lastUpdate = stepStartTime;
@@ -1029,6 +1101,9 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 				outputFile: path.join(asyncDir, `output-${flatIndex}.log`),
 				piPackageRoot: config.piPackageRoot,
 				piArgv1: config.piArgv1,
+				registerInterrupt: (interrupt) => {
+					activeChildInterrupt = interrupt;
+				},
 			});
 			if (seqStep.sessionFile) {
 				latestSessionFile = seqStep.sessionFile;
@@ -1046,7 +1121,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 			});
 
 			const cumulativeTokens = config.sessionDir ? parseSessionTokens(config.sessionDir) : null;
-			const stepTokens: TokenUsage | null = cumulativeTokens
+			let stepTokens: TokenUsage | null = cumulativeTokens
 				? {
 						input: cumulativeTokens.input - previousCumulativeTokens.input,
 						output: cumulativeTokens.output - previousCumulativeTokens.output,
@@ -1055,6 +1130,15 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 				: null;
 			if (cumulativeTokens) {
 				previousCumulativeTokens = cumulativeTokens;
+			} else {
+				stepTokens = tokenUsageFromAttempts(singleResult.modelAttempts);
+				if (stepTokens) {
+					previousCumulativeTokens = {
+						input: previousCumulativeTokens.input + stepTokens.input,
+						output: previousCumulativeTokens.output + stepTokens.output,
+						total: previousCumulativeTokens.total + stepTokens.total,
+					};
+				}
 			}
 
 			const stepEndTime = Date.now();
@@ -1139,7 +1223,8 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 
 	const effectiveSessionFile = sessionFile ?? latestSessionFile;
 	const runEndedAt = Date.now();
-	statusPayload.state = results.every((r) => r.success) ? "complete" : "failed";
+	statusPayload.state = interrupted ? "paused" : results.every((r) => r.success) ? "complete" : "failed";
+	statusPayload.activityState = interrupted ? "paused" : undefined;
 	statusPayload.endedAt = runEndedAt;
 	statusPayload.lastUpdate = runEndedAt;
 	statusPayload.sessionFile = effectiveSessionFile;
@@ -1186,8 +1271,8 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 		writeJson(resultPath, {
 			id,
 			agent: agentName,
-			success: results.every((r) => r.success),
-			summary,
+			success: !interrupted && results.every((r) => r.success),
+			summary: interrupted ? "Paused after interrupt. Waiting for explicit next action." : summary,
 			results: results.map((r) => ({
 				agent: r.agent,
 				output: r.output,
@@ -1199,7 +1284,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 				artifactPaths: r.artifactPaths,
 				truncated: r.truncated,
 			})),
-			exitCode: results.every((r) => r.success) ? 0 : 1,
+			exitCode: interrupted || results.every((r) => r.success) ? 0 : 1,
 			timestamp: runEndedAt,
 			durationMs: runEndedAt - overallStartTime,
 			truncated,

package/subagents-status.ts

@@ -25,6 +25,7 @@ function statusColor(theme: Theme, status: AsyncRunSummary["state"]): string {
 		case "queued": return theme.fg("accent", status);
 		case "complete": return theme.fg("success", status);
 		case "failed": return theme.fg("error", status);
+		case "paused": return theme.fg("warning", status);
 	}
 }
 
@@ -33,6 +34,7 @@ function stepStatusColor(theme: Theme, status: string): string {
 	if (status === "pending") return theme.fg("dim", status);
 	if (status === "complete" || status === "completed") return theme.fg("success", status);
 	if (status === "failed") return theme.fg("error", status);
+	if (status === "paused") return theme.fg("warning", status);
 	return status;
 }
 
@@ -170,7 +172,8 @@ export class SubagentsStatusComponent implements Component {
 				: "";
 			const duration = step.durationMs !== undefined ? ` | ${formatDuration(step.durationMs)}` : "";
 			const tokens = step.tokens ? ` | ${formatTokens(step.tokens.total)} tok` : "";
-			const line = `  ${step.index + 1}. ${step.agent} | ${stepStatusColor(this.theme, step.status)}${model}${attempts}${duration}${tokens}`;
+			const activity = step.activityState ? `/${step.activityState}` : "";
+			const line = `  ${step.index + 1}. ${step.agent} | ${stepStatusColor(this.theme, step.status)}${activity}${model}${attempts}${duration}${tokens}`;
 			lines.push(row(truncateToWidth(line, innerW), width, this.theme));
 			if (step.error) {
 				lines.push(row(truncateToWidth(`     ${step.error}`, innerW), width, this.theme));

package/types.ts

@@ -40,6 +40,35 @@ export interface TokenUsage {
 	total: number;
 }
 
+export type ActivityState = "starting" | "active" | "quiet" | "stalled" | "paused";
+export type ControlParentMode = "transitions" | "verbose";
+export type ControlEventType = "stalled" | "recovered" | "paused" | "resumed" | "activity";
+
+export interface ControlConfig {
+	enabled?: boolean;
+	quietAfterMs?: number;
+	stalledAfterMs?: number;
+	parentMode?: ControlParentMode;
+}
+
+export interface ResolvedControlConfig {
+	enabled: boolean;
+	quietAfterMs: number;
+	stalledAfterMs: number;
+	parentMode: ControlParentMode;
+}
+
+export interface ControlEvent {
+	type: ControlEventType;
+	from?: ActivityState;
+	to: ActivityState;
+	ts: number;
+	agent: string;
+	index?: number;
+	runId: string;
+	message: string;
+}
+
 // ============================================================================
 // Progress Tracking
 // ============================================================================
@@ -48,6 +77,7 @@ export interface AgentProgress {
 	index: number;
 	agent: string;
 	status: "pending" | "running" | "completed" | "failed" | "detached";
+	activityState?: ActivityState;
 	task: string;
 	skills?: string[];
 	lastActivityAt?: number;
@@ -92,11 +122,13 @@ export interface SingleResult {
 	exitCode: number;
 	detached?: boolean;
 	detachedReason?: string;
+	interrupted?: boolean;
 	messages?: Message[];
 	usage: Usage;
 	model?: string;
 	attemptedModels?: string[];
 	modelAttempts?: ModelAttempt[];
+	controlEvents?: ControlEvent[];
 	error?: string;
 	sessionFile?: string;
 	skills?: string[];
@@ -115,6 +147,7 @@ export interface Details {
 	mode: "single" | "parallel" | "chain" | "management";
 	context?: "fresh" | "fork";
 	results: SingleResult[];
+	controlEvents?: ControlEvent[];
 	asyncId?: string;
 	asyncDir?: string;
 	progress?: AgentProgress[];
@@ -162,15 +195,18 @@ export interface ArtifactConfig {
 export interface AsyncStatus {
 	runId: string;
 	mode: "single" | "chain";
-	state: "queued" | "running" | "complete" | "failed";
+	state: "queued" | "running" | "complete" | "failed" | "paused";
+	activityState?: ActivityState;
 	startedAt: number;
 	endedAt?: number;
 	lastUpdate?: number;
+	pid?: number;
 	cwd?: string;
 	currentStep?: number;
 	steps?: Array<{
 		agent: string;
 		status: string;
+		activityState?: ActivityState;
 		durationMs?: number;
 		tokens?: TokenUsage;
 		skills?: string[];
@@ -188,7 +224,8 @@ export interface AsyncStatus {
 export interface AsyncJobState {
 	asyncId: string;
 	asyncDir: string;
-	status: "queued" | "running" | "complete" | "failed";
+	status: "queued" | "running" | "complete" | "failed" | "paused";
+	activityState?: ActivityState;
 	mode?: "single" | "chain";
 	agents?: string[];
 	currentStep?: number;
@@ -205,6 +242,17 @@ export interface SubagentState {
 	baseCwd: string;
 	currentSessionId: string | null;
 	asyncJobs: Map<string, AsyncJobState>;
+	foregroundControls: Map<string, {
+		runId: string;
+		mode: "single" | "parallel" | "chain";
+		startedAt: number;
+		updatedAt: number;
+		currentAgent?: string;
+		currentIndex?: number;
+		currentActivityState?: ActivityState;
+		interrupt?: () => boolean;
+	}>;
+	lastForegroundControlId: string | null;
 	cleanupTimers: Map<string, ReturnType<typeof setTimeout>>;
 	lastUiContext: ExtensionContext | null;
 	poller: NodeJS.Timeout | null;
@@ -251,9 +299,12 @@ export const INTERCOM_DETACH_RESPONSE_EVENT = "pi-intercom:detach-response";
 export interface RunSyncOptions {
 	cwd?: string;
 	signal?: AbortSignal;
+	interruptSignal?: AbortSignal;
 	allowIntercomDetach?: boolean;
 	intercomEvents?: IntercomEventBus;
 	onUpdate?: (r: import("@mariozechner/pi-agent-core").AgentToolResult<Details>) => void;
+	onControlEvent?: (event: ControlEvent) => void;
+	controlConfig?: ResolvedControlConfig;
 	maxOutput?: MaxOutputConfig;
 	artifactsDir?: string;
 	artifactConfig?: ArtifactConfig;
@@ -291,6 +342,7 @@ export interface ExtensionConfig {
 	forceTopLevelAsync?: boolean;
 	defaultSessionDir?: string;
 	maxSubagentDepth?: number;
+	control?: ControlConfig;
 	parallel?: TopLevelParallelConfig;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;

package/utils.ts

@@ -231,6 +231,7 @@ function compactCompletedProgress(progress: AgentProgress): AgentProgress {
 		index: progress.index,
 		agent: progress.agent,
 		status: progress.status,
+		activityState: progress.activityState,
 		task: progress.task,
 		skills: progress.skills,
 		toolCount: progress.toolCount,