@ryan_nookpi/pi-extension-subagent 0.4.10 → 0.5.1

package/activity.ts

@@ -0,0 +1,148 @@
+/**
+ * Throttled `subagent-activity` custom entries.
+ *
+ * Lets host UIs (e.g. Picky) observe live activity of headless subagent runs
+ * by appending change-driven, throttled entries to the parent session JSONL.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { CommandRunState } from "./types.js";
+
+export const SUBAGENT_ACTIVITY_CUSTOM_TYPE = "subagent-activity";
+export const SUBAGENT_ACTIVITY_SCHEMA_VERSION = 1;
+export const ACTIVITY_MIN_INTERVAL_MS = 2500;
+export const ACTIVITY_LAST_LINE_MAX_CHARS = 160;
+
+export interface ActivitySnapshot {
+	status: CommandRunState["status"];
+	runId: number;
+	agent: string;
+	batchId?: string;
+	pipelineId?: string;
+	pipelineStepIndex?: number;
+	lastToolName?: string;
+	toolCallCount: number;
+	lastLine?: string;
+	contextTokens?: number;
+}
+
+export interface ActivityPayload {
+	runId: number;
+	agent: string;
+	batchId?: string;
+	pipelineId?: string;
+	pipelineStepIndex?: number;
+	lastToolName?: string;
+	toolCallCount: number;
+	lastLine?: string;
+	contextTokens?: number;
+}
+
+export interface ActivityThrottleState {
+	lastEmittedAt: number;
+	lastEmittedToolName?: string;
+	lastEmittedToolCallCount?: number;
+}
+
+export function createActivityThrottleState(): ActivityThrottleState {
+	return { lastEmittedAt: 0 };
+}
+
+const ANSI_PATTERN =
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequences use control characters by definition.
+	/\u001b\[[0-9;?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)?|[\u0000-\u0008\u000b-\u001f\u007f]/g;
+
+/** Strip ANSI sequences, collapse to a single line, and cap length. */
+export function normalizeActivityLine(text: string | undefined): string | undefined {
+	if (!text) return undefined;
+	const line = text
+		.replace(/\r\n?/g, "\n")
+		.replace(ANSI_PATTERN, "")
+		.split("\n")
+		.map((part) => part.trim())
+		.filter(Boolean)
+		.pop();
+	if (!line) return undefined;
+	return line.length > ACTIVITY_LAST_LINE_MAX_CHARS ? line.slice(0, ACTIVITY_LAST_LINE_MAX_CHARS) : line;
+}
+
+/**
+ * Change-driven throttle policy. Returns a payload to emit, or null.
+ *
+ * Emits only while the run is `running`, only when `lastToolName` or
+ * `toolCallCount` changed since the last emission, and at most once per
+ * `ACTIVITY_MIN_INTERVAL_MS` per run. A change suppressed by the interval
+ * stays pending and emits on a later evaluation.
+ */
+export function evaluateActivityEmission(
+	state: ActivityThrottleState,
+	snapshot: ActivitySnapshot,
+	now: number,
+): ActivityPayload | null {
+	if (snapshot.status !== "running") return null;
+	// Continuations reset toolCalls to 0 while a stale lastToolName may linger
+	// on the run state, so a positive count is required regardless of the name.
+	if (snapshot.toolCallCount <= 0) return null;
+
+	const changed =
+		snapshot.lastToolName !== state.lastEmittedToolName || snapshot.toolCallCount !== state.lastEmittedToolCallCount;
+	if (!changed) return null;
+	if (state.lastEmittedAt !== 0 && now - state.lastEmittedAt < ACTIVITY_MIN_INTERVAL_MS) return null;
+
+	state.lastEmittedAt = now;
+	state.lastEmittedToolName = snapshot.lastToolName;
+	state.lastEmittedToolCallCount = snapshot.toolCallCount;
+
+	const payload: ActivityPayload = {
+		runId: snapshot.runId,
+		agent: snapshot.agent,
+		toolCallCount: snapshot.toolCallCount,
+	};
+	if (snapshot.batchId) payload.batchId = snapshot.batchId;
+	if (snapshot.pipelineId) payload.pipelineId = snapshot.pipelineId;
+	if (snapshot.pipelineStepIndex != null) payload.pipelineStepIndex = snapshot.pipelineStepIndex;
+	if (snapshot.lastToolName) payload.lastToolName = snapshot.lastToolName;
+	const lastLine = normalizeActivityLine(snapshot.lastLine);
+	if (lastLine) payload.lastLine = lastLine;
+	if (snapshot.contextTokens != null && snapshot.contextTokens > 0) payload.contextTokens = snapshot.contextTokens;
+	return payload;
+}
+
+export function snapshotFromRunState(runState: CommandRunState): ActivitySnapshot {
+	return {
+		status: runState.status,
+		runId: runState.id,
+		agent: runState.agent,
+		batchId: runState.batchId,
+		pipelineId: runState.pipelineId,
+		pipelineStepIndex: runState.pipelineStepIndex,
+		lastToolName: runState.lastToolName,
+		toolCallCount: runState.toolCalls,
+		lastLine: runState.lastLine,
+		contextTokens: runState.usage?.contextTokens,
+	};
+}
+
+/**
+ * Best-effort recorder called from run update handlers. Never throws;
+ * activity logging must not affect run execution or completion delivery.
+ */
+export function createRunActivityRecorder(
+	pi: Pick<ExtensionAPI, "appendEntry">,
+	runState: CommandRunState,
+): () => void {
+	const throttleState = createActivityThrottleState();
+	return () => {
+		try {
+			const payload = evaluateActivityEmission(throttleState, snapshotFromRunState(runState), Date.now());
+			if (!payload) return;
+			pi.appendEntry(SUBAGENT_ACTIVITY_CUSTOM_TYPE, {
+				schemaVersion: SUBAGENT_ACTIVITY_SCHEMA_VERSION,
+				recordedAt: new Date().toISOString(),
+				...payload,
+			});
+		} catch {
+			// Session teardown may invalidate the old extension runtime.
+		}
+	};
+}

package/agents.ts

@@ -140,25 +140,30 @@ function loadAgentsFromDir(dir: string, source: "user" | "project", options: Loa
 			continue;
 		}
 
-		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
-		if (!frontmatter.name || !frontmatter.description) continue;
-
-		const tools = normalizeTools(frontmatter.tools, format);
-		const model = normalizeModel(frontmatter.model, format);
-		const thinking = normalizeThinkingLevel(frontmatter.thinking);
-		const runtime: AgentRuntime = frontmatter.runtime === "claude" ? "claude" : "pi";
-
-		agents.push({
-			name: frontmatter.name,
-			description: frontmatter.description,
-			tools,
-			model,
-			thinking,
-			systemPrompt: attachCommonSubagentRule(body, runtime),
-			source,
-			filePath,
-			runtime,
-		});
+		try {
+			const { frontmatter, body } = parseFrontmatter<Record<string, unknown>>(content);
+			if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") continue;
+			if (!frontmatter.name || !frontmatter.description) continue;
+
+			const tools = normalizeTools(frontmatter.tools, format);
+			const model = normalizeModel(typeof frontmatter.model === "string" ? frontmatter.model : undefined, format);
+			const thinking = normalizeThinkingLevel(
+				typeof frontmatter.thinking === "string" ? frontmatter.thinking : undefined,
+			);
+			const runtime: AgentRuntime = frontmatter.runtime === "claude" ? "claude" : "pi";
+
+			agents.push({
+				name: frontmatter.name,
+				description: frontmatter.description,
+				tools,
+				model,
+				thinking,
+				systemPrompt: attachCommonSubagentRule(body, runtime),
+				source,
+				filePath,
+				runtime,
+			});
+		} catch {}
 	}
 
 	return agents;

package/commands.ts

@@ -9,6 +9,7 @@
 import * as fs from "node:fs";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Container, Key, matchesKey, Spacer, Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { createRunActivityRecorder } from "./activity.js";
 import { discoverAgents } from "./agents.js";
 import { loadSubagentConfig } from "./config.js";
 import {
@@ -1249,6 +1250,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): SubagentReg
 				runState.model = undefined;
 				runState.retryCount = 0;
 				runState.lastRetryReason = undefined;
+				runState.errorClass = undefined;
+				runState.autoAbortReason = undefined;
 				runState.removed = false;
 				runState.deliveryMode = deliveryMode;
 				runState.turnCount = Math.max(DEFAULT_TURN_COUNT, runState.turnCount || DEFAULT_TURN_COUNT) + 1;
@@ -1399,6 +1402,7 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): SubagentReg
 			}, RUN_TICK_INTERVAL_MS);
 
 			let claudeCheckpointSent = !!runState.claudeSessionId;
+			const recordActivity = hiddenFromMain ? () => {} : createRunActivityRecorder(pi, runState);
 			void (async () => {
 				try {
 					const { result, retryCount } = await invokeWithAutoRetry({
@@ -1428,6 +1432,7 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): SubagentReg
 										const current = partial.details?.results?.[0];
 										if (!current) return;
 										updateRunFromResult(runState, current);
+										recordActivity();
 										if (!claudeCheckpointSent && runState.claudeSessionId) {
 											claudeCheckpointSent = true;
 											if (!hiddenFromMain) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryan_nookpi/pi-extension-subagent",
-  "version": "0.4.10",
+  "version": "0.5.1",
   "description": "Asynchronous subagent delegation for pi with run, batch, chain, and continuation workflows.",
   "license": "MIT",
   "repository": {
@@ -20,6 +20,7 @@
   ],
   "files": [
     "above-widget.ts",
+    "activity.ts",
     "agents.ts",
     "claude-args.ts",
     "claude-sdk-runner.ts",

package/tool-execute.ts

@@ -8,6 +8,7 @@
 
 import * as fs from "node:fs";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createRunActivityRecorder } from "./activity.js";
 import { discoverAgents } from "./agents.js";
 import { parseSubagentToolCommand, SUBAGENT_CLI_HELP_TEXT } from "./cli.js";
 import {
@@ -1253,6 +1254,10 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 				runState.lastOutput = "";
 				runState.usage = undefined;
 				runState.model = undefined;
+				runState.retryCount = 0;
+				runState.lastRetryReason = undefined;
+				runState.errorClass = undefined;
+				runState.autoAbortReason = undefined;
 				runState.removed = false;
 				runState.turnCount = Math.max(DEFAULT_TURN_COUNT, runState.turnCount || DEFAULT_TURN_COUNT) + 1;
 				runState.contextMode = runState.contextMode ?? (config.inheritMainContext ? "main" : "sub");
@@ -1314,6 +1319,7 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 
 		function launchRunInBackground(runState: CommandRunState, taskForAgent: string): Promise<FinalizedRun> {
 			let claudeCheckpointSent = !!runState.claudeSessionId;
+			const recordActivity = createRunActivityRecorder(pi, runState);
 			return enqueueSubagentInvocation(() =>
 				runSingleAgent(
 					ctx.cwd,
@@ -1327,6 +1333,7 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 						const current = partial.details?.results?.[0];
 						if (!current) return;
 						updateRunFromResult(runState, current);
+						recordActivity();
 						if (shouldRunAsync && !claudeCheckpointSent && runState.claudeSessionId) {
 							claudeCheckpointSent = true;
 							pi.sendMessage(buildRunStartMessage(runState, "started"), {
@@ -1976,7 +1983,14 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 						pipeline.stepRunIds.push(runState.id);
 						chainLaunches.push(toLaunchSummary(runState, "chain"));
 
-						const finalized = await launchRunInBackground(runState, taskForAgent);
+						let finalized: FinalizedRun;
+						try {
+							finalized = await launchRunInBackground(runState, taskForAgent);
+						} catch (error: unknown) {
+							finalized = finalizeRunError(runState, error);
+						} finally {
+							clearRunAbortState(runState);
+						}
 						if (runState.removed) {
 							terminalStatus = finalized.isError ? "error" : "stopped";
 							pipeline.stepResults.push({

package/utils/agent-utils.ts

@@ -88,12 +88,10 @@ export const CLAUDE_MODEL_ALIAS_MAP: Record<string, string> = {
  * Normalize a comma-separated tool list according to the given format.
  * For "claude" format, maps Claude tool names to pi equivalents.
  */
-export function normalizeTools(rawTools: string | undefined, format: "pi" | "claude"): string[] | undefined {
-	if (!rawTools) return undefined;
-
-	const parsed = rawTools
-		.split(",")
-		.map((t) => t.trim())
+export function normalizeTools(rawTools: unknown, format: "pi" | "claude"): string[] | undefined {
+	const parsed = (Array.isArray(rawTools) ? rawTools : typeof rawTools === "string" ? rawTools.split(",") : [])
+		.filter((tool): tool is string => typeof tool === "string")
+		.map((tool) => tool.trim())
 		.filter(Boolean);
 
 	if (parsed.length === 0) return undefined;