pi-subagents 0.17.3 → 0.17.5

package/execution.ts

@@ -14,6 +14,7 @@ import {
 import {
 	type AgentProgress,
 	type ArtifactPaths,
+	type ControlEvent,
 	type ModelAttempt,
 	type RunSyncOptions,
 	type SingleResult,
@@ -24,6 +25,12 @@ import {
 	truncateOutput,
 	getSubagentDepthEnv,
 } from "./types.ts";
+import {
+	DEFAULT_CONTROL_CONFIG,
+	buildControlEvent,
+	deriveActivityState,
+	shouldEmitControlEvent,
+} from "./subagent-control.ts";
 import {
 	getFinalOutput,
 	findLatestSessionFile,
@@ -86,6 +93,7 @@ function snapshotResult(result: SingleResult, progress: AgentProgress): SingleRe
 				usage: attempt.usage ? { ...attempt.usage } : undefined,
 			}))
 			: undefined,
+		controlEvents: result.controlEvents ? result.controlEvents.map((event) => ({ ...event })) : undefined,
 		progress,
 		progressSummary: result.progressSummary ? { ...result.progressSummary } : undefined,
 		artifactPaths: result.artifactPaths ? { ...result.artifactPaths } : undefined,
@@ -140,11 +148,19 @@ async function runSingleAttempt(
 		skills: shared.resolvedSkillNames,
 		skillsWarning: shared.skillsWarning,
 	};
+	const startTime = Date.now();
+	const controlConfig = options.controlConfig ?? DEFAULT_CONTROL_CONFIG;
+	let hasSeenActivity = false;
+	let pausedByInterrupt = false;
+	let interruptedByControl = false;
+	const allControlEvents: ControlEvent[] = [];
+	let pendingControlEvents: ControlEvent[] = [];
 
 	const progress: AgentProgress = {
 		index: options.index ?? 0,
 		agent: agent.name,
 		status: "running",
+		activityState: controlConfig.enabled ? "starting" : undefined,
 		task,
 		skills: shared.resolvedSkillNames,
 		recentTools: [],
@@ -152,11 +168,9 @@ async function runSingleAttempt(
 		toolCount: 0,
 		tokens: 0,
 		durationMs: 0,
-		lastActivityAt: Date.now(),
+		lastActivityAt: startTime,
 	};
 	result.progress = progress;
-
-	const startTime = Date.now();
 	const spawnEnv = { ...process.env, ...sharedEnv, ...getSubagentDepthEnv(options.maxSubagentDepth) };
 
 	const exitCode = await new Promise<number>((resolve) => {
@@ -173,6 +187,8 @@ async function runSingleAttempt(
 		let detached = false;
 		let intercomStarted = false;
 		let removeAbortListener: (() => void) | undefined;
+		let removeInterruptListener: (() => void) | undefined;
+		let activityTimer: NodeJS.Timeout | undefined;
 
 		const detachForIntercom = () => {
 			detached = true;
@@ -241,18 +257,64 @@ async function runSingleAttempt(
 			settled = true;
 			clearFinalDrainTimers();
 			clearStdioGuard();
+			if (activityTimer) {
+				clearInterval(activityTimer);
+				activityTimer = undefined;
+			}
 			unsubscribeIntercomDetach?.();
 			removeAbortListener?.();
+			removeInterruptListener?.();
 			resolve(code);
 		};
 
+		const drainPendingControlEvents = (): ControlEvent[] | undefined => {
+			if (pendingControlEvents.length === 0) return undefined;
+			const events = pendingControlEvents;
+			pendingControlEvents = [];
+			return events;
+		};
+
+		const updateActivityState = (now: number): boolean => {
+			const next = deriveActivityState({
+				config: controlConfig,
+				startedAt: startTime,
+				lastActivityAt: progress.lastActivityAt,
+				hasSeenActivity,
+				paused: pausedByInterrupt,
+				now,
+			});
+			if (!next || next === progress.activityState) return false;
+			const previous = progress.activityState;
+			progress.activityState = next;
+			if (shouldEmitControlEvent(controlConfig, previous, next)) {
+				const event = buildControlEvent({
+					from: previous,
+					to: next,
+					runId: options.runId,
+					agent: agent.name,
+					index: options.index,
+					ts: now,
+				});
+				allControlEvents.push(event);
+				pendingControlEvents.push(event);
+				options.onControlEvent?.(event);
+			}
+			return true;
+		};
+
 		const emitUpdateSnapshot = (text: string) => {
 			if (!options.onUpdate || processClosed) return;
 			const progressSnapshot = snapshotProgress(progress);
 			const resultSnapshot = snapshotResult(result, progressSnapshot);
+			const controlEvents = drainPendingControlEvents();
 			options.onUpdate({
 				content: [{ type: "text", text }],
-				details: { mode: "single", results: [resultSnapshot], progress: [progressSnapshot] },
+				details: {
+					mode: "single",
+					results: [resultSnapshot],
+					progress: [progressSnapshot],
+					controlEvents,
+				},
 			});
 		};
 
@@ -276,6 +338,8 @@ async function runSingleAttempt(
 			const now = Date.now();
 			progress.durationMs = now - startTime;
 			progress.lastActivityAt = now;
+			hasSeenActivity = true;
+			updateActivityState(now);
 
 			if (evt.type === "tool_execution_start") {
 				if (options.allowIntercomDetach && evt.toolName === "intercom") {
@@ -336,6 +400,18 @@ async function runSingleAttempt(
 			}
 		};
 
+		if (controlConfig.enabled) {
+			activityTimer = setInterval(() => {
+				if (processClosed || settled || detached) return;
+				const now = Date.now();
+				if (updateActivityState(now)) {
+					progress.durationMs = now - startTime;
+					fireUpdate();
+				}
+			}, 1000);
+			activityTimer.unref?.();
+		}
+
 		let stderrBuf = "";
 
 		const clearStdioGuard = attachPostExitStdioGuard(proc, { idleMs: 2000, hardMs: 8000 });
@@ -400,8 +476,62 @@ async function runSingleAttempt(
 				removeAbortListener = () => options.signal?.removeEventListener("abort", kill);
 			}
 		}
+
+		if (options.interruptSignal) {
+			const interrupt = () => {
+				if (processClosed || detached || settled) return;
+				interruptedByControl = true;
+				pausedByInterrupt = true;
+				progress.status = "running";
+				progress.durationMs = Date.now() - startTime;
+				result.interrupted = true;
+				result.finalOutput = "Interrupted. Waiting for explicit next action.";
+				const now = Date.now();
+				const previous = progress.activityState;
+				progress.activityState = "paused";
+				if (shouldEmitControlEvent(controlConfig, previous, "paused")) {
+					const event = buildControlEvent({
+						from: previous,
+						to: "paused",
+						runId: options.runId,
+						agent: agent.name,
+						index: options.index,
+						ts: now,
+					});
+					allControlEvents.push(event);
+					pendingControlEvents.push(event);
+					options.onControlEvent?.(event);
+				}
+				fireUpdate();
+				trySignalChild(proc, "SIGINT");
+				setTimeout(() => {
+					if (settled || processClosed || detached) return;
+					trySignalChild(proc, "SIGTERM");
+				}, 1000).unref?.();
+			};
+			if (options.interruptSignal.aborted) interrupt();
+			else {
+				options.interruptSignal.addEventListener("abort", interrupt, { once: true });
+				removeInterruptListener = () => options.interruptSignal?.removeEventListener("abort", interrupt);
+			}
+		}
 	});
 	result.exitCode = exitCode;
+	if (interruptedByControl) {
+		result.exitCode = 0;
+		result.interrupted = true;
+		result.error = undefined;
+		result.finalOutput = result.finalOutput || "Interrupted. Waiting for explicit next action.";
+		result.controlEvents = allControlEvents.length ? allControlEvents : undefined;
+		progress.activityState = "paused";
+		progress.durationMs = Date.now() - startTime;
+		result.progressSummary = {
+			toolCount: progress.toolCount,
+			tokens: progress.tokens,
+			durationMs: progress.durationMs,
+		};
+		return result;
+	}
 	if (result.detached) {
 		result.exitCode = 0;
 		result.finalOutput = "Detached for intercom coordination.";

package/index.ts

@@ -153,6 +153,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		baseCwd: process.cwd(),
 		currentSessionId: null,
 		asyncJobs: new Map(),
+		foregroundControls: new Map(),
+		lastForegroundControlId: null,
 		cleanupTimers: new Map(),
 		lastUiContext: null,
 		poller: null,
@@ -265,11 +267,14 @@ Example: { chain: [{agent:"scout", task:"Analyze {task}"}, {agent:"planner", tas
 
 MANAGEMENT (use action field, omit agent/task/chain/tasks):
 • { action: "list" } - discover agents/chains
-• { action: "get", agent: "name" } - full agent detail
+• { action: "get", agent: "name" } - full detail
 • { action: "create", config: { name, systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, ... } }
 • { action: "update", agent: "name", config: { ... } } - merge
 • { action: "delete", agent: "name" }
-• Use chainName for chain operations`,
+• Use chainName for chain operations
+
+CONTROL:
+• { action: "interrupt", runId?: "..." } - soft-interrupt the current child turn and leave the run paused`, 
 		parameters: SubagentParams,
 
 		execute(id, params, signal, onUpdate, ctx) {
@@ -389,13 +394,17 @@ MANAGEMENT (use action field, omit agent/task/chain/tasks):
 
 					const lines = [
 						`Run: ${status.runId}`,
-						`State: ${status.state}`,
+						`State: ${status.activityState ? `${status.state}/${status.activityState}` : status.state}`,
 						`Mode: ${status.mode}`,
 						stepLine,
 						`Started: ${started}`,
 						`Updated: ${updated}`,
 						`Dir: ${asyncDir}`,
 					];
+					for (const [index, step] of (status.steps ?? []).entries()) {
+						const stepState = step.activityState ? `${step.status}/${step.activityState}` : step.status;
+						lines.push(`Step ${index + 1}: ${step.agent} ${stepState}`);
+					}
 					if (status.sessionFile) lines.push(`Session: ${status.sessionFile}`);
 					if (fs.existsSync(logPath)) lines.push(`Log: ${logPath}`);
 					if (fs.existsSync(eventsPath)) lines.push(`Events: ${eventsPath}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.17.3",
+  "version": "0.17.5",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -30,6 +30,7 @@
     "!*.test.ts",
     "*.mjs",
     "agents/",
+    "skills/**/*",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -44,6 +45,9 @@
     "extensions": [
       "./index.ts",
       "./notify.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "peerDependencies": {

package/pi-spawn.ts

@@ -83,12 +83,15 @@ export function resolveWindowsPiCliScript(deps: PiSpawnDeps = {}): string | unde
 }
 
 export function getPiSpawnCommand(args: string[], deps: PiSpawnDeps = {}): PiSpawnCommand {
-	const piCliPath = resolveWindowsPiCliScript(deps);
-	if (piCliPath) {
-		return {
-			command: deps.execPath ?? process.execPath,
-			args: [piCliPath, ...args],
-		};
+	const platform = deps.platform ?? process.platform;
+	if (platform === "win32") {
+		const piCliPath = resolveWindowsPiCliScript(deps);
+		if (piCliPath) {
+			return {
+				command: deps.execPath ?? process.execPath,
+				args: [piCliPath, ...args],
+			};
+		}
 	}
 
 	return { command: "pi", args };

package/render.ts

@@ -83,7 +83,7 @@ let lastWidgetHash = "";
 
 function computeWidgetHash(jobs: AsyncJobState[]): string {
 	return jobs.slice(0, MAX_WIDGET_JOBS).map(job =>
-		`${job.asyncId}:${job.status}:${job.currentStep}:${job.updatedAt}:${job.totalTokens?.total ?? 0}`
+		`${job.asyncId}:${job.status}:${job.activityState}:${job.currentStep}:${job.updatedAt}:${job.totalTokens?.total ?? 0}`
 	).join("|");
 }
 
@@ -142,6 +142,11 @@ function buildLiveStatusLine(progress: Pick<AgentProgress, "lastActivityAt">): s
 	return formatActivityLabel(progress.lastActivityAt);
 }
 
+function formatActivityState(state: AgentProgress["activityState"]): string | undefined {
+	if (!state) return undefined;
+	return `activity: ${state}`;
+}
+
 /**
  * Render the async jobs widget
  */
@@ -175,7 +180,9 @@ export function renderWidget(ctx: ExtensionContext, jobs: AsyncJobState[]): void
 				? theme.fg("success", "complete")
 				: job.status === "failed"
 					? theme.fg("error", "failed")
-					: theme.fg("warning", "running");
+					: job.status === "paused"
+						? theme.fg("warning", "paused")
+						: theme.fg("warning", "running");
 
 		const stepsTotal = job.stepsTotal ?? (job.agents?.length ?? 1);
 		const stepIndex = job.currentStep !== undefined ? job.currentStep + 1 : undefined;
@@ -185,12 +192,12 @@ export function renderWidget(ctx: ExtensionContext, jobs: AsyncJobState[]): void
 		const agentLabel = job.agents ? job.agents.join(" -> ") : (job.mode ?? "single");
 
 		const tokenText = job.totalTokens ? ` | ${formatTokens(job.totalTokens.total)} tok` : "";
-		const activityText = job.status === "running" ? getLastActivity(job.outputFile) : "";
+		const activityText = job.activityState ?? (job.status === "running" ? getLastActivity(job.outputFile) : "");
 		const activitySuffix = activityText ? ` | ${theme.fg("dim", activityText)}` : "";
 
 		lines.push(truncLine(`- ${id} ${status} | ${agentLabel} | ${stepText}${elapsed ? ` | ${elapsed}` : ""}${tokenText}${activitySuffix}`, w));
 
-		if (job.status === "running" && job.outputFile) {
+		if ((job.status === "running" || job.status === "paused") && job.outputFile) {
 			const tail = getOutputTail(job.outputFile, 3);
 			for (const line of tail) {
 				lines.push(truncLine(theme.fg("dim", `  > ${line}`), w));
@@ -259,6 +266,10 @@ export function renderSubagentResult(
 			if (toolLine) {
 				c.addChild(new Text(fit(theme.fg("warning", `> ${toolLine}`)), 0, 0));
 			}
+			const activityStateLine = formatActivityState(r.progress.activityState);
+			if (activityStateLine) {
+				c.addChild(new Text(fit(theme.fg("accent", activityStateLine)), 0, 0));
+			}
 			const liveStatusLine = buildLiveStatusLine(r.progress);
 			if (liveStatusLine) {
 				c.addChild(new Text(fit(theme.fg("accent", liveStatusLine)), 0, 0));
@@ -467,6 +478,10 @@ export function renderSubagentResult(
 			if (toolLine) {
 				c.addChild(new Text(fit(theme.fg("warning", `    > ${toolLine}`)), 0, 0));
 			}
+			const activityStateLine = formatActivityState(rProg.activityState);
+			if (activityStateLine) {
+				c.addChild(new Text(fit(theme.fg("accent", `    ${activityStateLine}`)), 0, 0));
+			}
 			const liveStatusLine = buildLiveStatusLine(rProg);
 			if (liveStatusLine) {
 				c.addChild(new Text(fit(theme.fg("accent", `    ${liveStatusLine}`)), 0, 0));

package/schemas.ts

@@ -57,12 +57,22 @@ export const ParallelStepSchema = Type.Object({
 // Note: Using Type.Any() for Google API compatibility (doesn't support anyOf)
 export const ChainItem = Type.Any({ description: "Chain step: either {agent, task?, ...} for sequential or {parallel: [...]} for concurrent execution" });
 
+export const ControlOverrides = Type.Object({
+	enabled: Type.Optional(Type.Boolean({ description: "Enable/disable subagent control activity tracking for this run" })),
+	quietAfterMs: Type.Optional(Type.Integer({ minimum: 1, description: "Idle window before activity moves from active to quiet" })),
+	stalledAfterMs: Type.Optional(Type.Integer({ minimum: 1, description: "Idle window before activity moves from quiet to stalled" })),
+	parentMode: Type.Optional(Type.String({ enum: ["transitions", "verbose"], description: "Parent-visible control event mode" })),
+});
+
 export const SubagentParams = Type.Object({
 	agent: Type.Optional(Type.String({ description: "Agent name (SINGLE mode) or target for management get/update/delete" })),
 	task: Type.Optional(Type.String({ description: "Task (SINGLE mode)" })),
 	// Management action (when present, tool operates in management mode)
 	action: Type.Optional(Type.String({
-		description: "Management action: 'list' (discover agents/chains), 'get' (full detail), 'create', 'update', 'delete'. Omit for execution mode."
+		description: "Action: management ('list','get','create','update','delete') or control ('interrupt'). Omit for execution mode."
+	})),
+	runId: Type.Optional(Type.String({
+		description: "Target run ID for action='interrupt'. Defaults to the most recently active controllable run in this session."
 	})),
 	// Chain identifier for management (can't reuse 'chain' — that's the execution array)
 	chainName: Type.Optional(Type.String({
@@ -96,6 +106,7 @@ export const SubagentParams = Type.Object({
 	),
 	// Clarification TUI
 	clarify: Type.Optional(Type.Boolean({ description: "Show TUI to preview/edit before execution (default: true for chains, false for single/parallel). Implies sync mode." })),
+	control: Type.Optional(ControlOverrides),
 	// Solo agent overrides
 	output: Type.Optional(Type.Any({ description: "Output file for single agent (string), or false to disable. Relative paths resolve against cwd." })),
 	skill: Type.Optional(SkillOverride),