@ryan_nookpi/pi-extension-subagent 0.4.9 → 0.5.0

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/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 {
@@ -1399,6 +1400,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 +1430,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,102 +1,103 @@
 {
-	"name": "@ryan_nookpi/pi-extension-subagent",
-	"version": "0.4.9",
-	"description": "Asynchronous subagent delegation for pi with run, batch, chain, and continuation workflows.",
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/Jonghakseo/pi-extension.git",
-		"directory": "packages/subagent"
-	},
-	"bugs": {
-		"url": "https://github.com/Jonghakseo/pi-extension/issues"
-	},
-	"homepage": "https://github.com/Jonghakseo/pi-extension/tree/main/packages/subagent#readme",
-	"type": "module",
-	"keywords": [
-		"pi-package",
-		"subagent",
-		"delegation"
-	],
-	"files": [
-		"above-widget.ts",
-		"agents.ts",
-		"claude-args.ts",
-		"claude-sdk-runner.ts",
-		"claude-sdk-stream-adapter.ts",
-		"claude-sidecar-writer.ts",
-		"claude-stream-parser.ts",
-		"cli.ts",
-		"commands.ts",
-		"config.ts",
-		"constants.ts",
-		"context-limits.ts",
-		"diagnostics.ts",
-		"display-task.ts",
-		"escalation.ts",
-		"failure-telemetry.ts",
-		"format.ts",
-		"group-pending.ts",
-		"index.ts",
-		"lifecycle.ts",
-		"invocation-queue.ts",
-		"live-preview.ts",
-		"mentions.ts",
-		"persisted-session.ts",
-		"replay.ts",
-		"registration-manifest.ts",
-		"retry.ts",
-		"run-utils.ts",
-		"runner.ts",
-		"session.ts",
-		"starter-pack.ts",
-		"store.ts",
-		"tool-execute.ts",
-		"tool-render.ts",
-		"types.ts",
-		"widget.ts",
-		"utils/agent-utils.ts",
-		"utils/short-label.ts",
-		"utils/string-utils.ts",
-		"utils/format-utils.ts",
-		"utils/time-utils.ts",
-		"seeds",
-		"README.md"
-	],
-	"pi": {
-		"extensions": [
-			"./index.ts"
-		]
-	},
-	"dependencies": {
-		"@anthropic-ai/claude-agent-sdk": "^0.2.98",
-		"yaml": "^2.9.0"
-	},
-	"peerDependencies": {
-		"@earendil-works/pi-ai": "*",
-		"@earendil-works/pi-agent-core": "*",
-		"@earendil-works/pi-coding-agent": "*",
-		"@earendil-works/pi-tui": "*",
-		"typebox": "*"
-	},
-	"peerDependenciesMeta": {
-		"@earendil-works/pi-ai": {
-			"optional": true
-		},
-		"@earendil-works/pi-agent-core": {
-			"optional": true
-		},
-		"@earendil-works/pi-coding-agent": {
-			"optional": true
-		},
-		"@earendil-works/pi-tui": {
-			"optional": true
-		},
-		"typebox": {
-			"optional": true
-		}
-	},
-	"publishConfig": {
-		"access": "public"
-	}
-}
+  "name": "@ryan_nookpi/pi-extension-subagent",
+  "version": "0.5.0",
+  "description": "Asynchronous subagent delegation for pi with run, batch, chain, and continuation workflows.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Jonghakseo/pi-extension.git",
+    "directory": "packages/subagent"
+  },
+  "bugs": {
+    "url": "https://github.com/Jonghakseo/pi-extension/issues"
+  },
+  "homepage": "https://github.com/Jonghakseo/pi-extension/tree/main/packages/subagent#readme",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "subagent",
+    "delegation"
+  ],
+  "files": [
+    "above-widget.ts",
+    "activity.ts",
+    "agents.ts",
+    "claude-args.ts",
+    "claude-sdk-runner.ts",
+    "claude-sdk-stream-adapter.ts",
+    "claude-sidecar-writer.ts",
+    "claude-stream-parser.ts",
+    "cli.ts",
+    "commands.ts",
+    "config.ts",
+    "constants.ts",
+    "context-limits.ts",
+    "diagnostics.ts",
+    "display-task.ts",
+    "escalation.ts",
+    "failure-telemetry.ts",
+    "format.ts",
+    "group-pending.ts",
+    "index.ts",
+    "lifecycle.ts",
+    "invocation-queue.ts",
+    "live-preview.ts",
+    "mentions.ts",
+    "persisted-session.ts",
+    "replay.ts",
+    "registration-manifest.ts",
+    "retry.ts",
+    "run-utils.ts",
+    "runner.ts",
+    "session.ts",
+    "starter-pack.ts",
+    "store.ts",
+    "tool-execute.ts",
+    "tool-render.ts",
+    "types.ts",
+    "widget.ts",
+    "utils/agent-utils.ts",
+    "utils/short-label.ts",
+    "utils/string-utils.ts",
+    "utils/format-utils.ts",
+    "utils/time-utils.ts",
+    "seeds",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.98",
+    "yaml": "^2.9.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-agent-core": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

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 {
@@ -1314,6 +1315,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 +1329,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"), {