@melihmucuk/pi-crew 1.0.13 → 1.0.15

package/extension/runtime/overflow-recovery.ts

@@ -0,0 +1,211 @@
+import type { AgentSession, AgentSessionEvent } from "@mariozechner/pi-coding-agent";
+
+const OVERFLOW_RECOVERY_TIMEOUT_MS = 120_000;
+
+/**
+ * Short grace period for the first terminal agent_end after prompt() resolves.
+ * If this window expires, we still wait the full recovery timeout.
+ */
+const INITIAL_AGENT_END_WAIT_MS = 5_000;
+
+type PhaseWaitResult = "done" | "timeout" | "cancelled";
+
+export type OverflowRecoveryResult = "none" | "recovered" | "failed";
+
+interface DeferredPhase {
+	promise: Promise<void>;
+	resolve: () => void;
+	isDone: () => boolean;
+}
+
+function createDeferredPhase(): DeferredPhase {
+	let done = false;
+	let resolveFn: (() => void) | undefined;
+
+	const promise = new Promise<void>((resolve) => {
+		resolveFn = () => {
+			if (done) return;
+			done = true;
+			resolve();
+		};
+	});
+
+	return {
+		promise,
+		resolve: () => resolveFn?.(),
+		isDone: () => done,
+	};
+}
+
+class OverflowRecoveryTracker {
+	private overflowDetected = false;
+	private compactionWillRetry = false;
+
+	private autoRetryActive = false;
+	private readonly initialAgentEnd = createDeferredPhase();
+	private compactionEnd: DeferredPhase | undefined;
+	private retryAgentEnd: DeferredPhase | undefined;
+	private overflowAutoRetryEnd: DeferredPhase | undefined;
+	private timers: ReturnType<typeof setTimeout>[] = [];
+
+	handleEvent(event: AgentSessionEvent): void {
+		switch (event.type) {
+			case "agent_end":
+				this.onAgentEnd();
+				break;
+			case "compaction_start":
+				this.onCompactionStart(event.reason);
+				break;
+			case "compaction_end":
+				this.onCompactionEnd(event.reason, event.willRetry);
+				break;
+			case "auto_retry_start":
+				this.onAutoRetryStart();
+				break;
+			case "auto_retry_end":
+				this.onAutoRetryEnd();
+				break;
+			default:
+				break;
+		}
+	}
+
+	async awaitCompletion(signal: AbortSignal): Promise<OverflowRecoveryResult> {
+		const cancelPromise = new Promise<void>((resolve) => {
+			if (signal.aborted) {
+				resolve();
+				return;
+			}
+			signal.addEventListener("abort", () => resolve(), { once: true });
+		});
+
+		try {
+			let initialEnd = await this.waitForPhase(
+				this.initialAgentEnd.promise,
+				INITIAL_AGENT_END_WAIT_MS,
+				cancelPromise,
+			);
+
+			if (initialEnd === "timeout") {
+				initialEnd = await this.waitForPhase(
+					this.initialAgentEnd.promise,
+					OVERFLOW_RECOVERY_TIMEOUT_MS,
+					cancelPromise,
+				);
+			}
+
+			if (initialEnd !== "done") {
+				return this.overflowDetected ? "failed" : "none";
+			}
+
+			if (!this.overflowDetected) return "none";
+
+			if (this.compactionEnd) {
+				const compactionEnd = await this.waitForPhase(
+					this.compactionEnd.promise,
+					OVERFLOW_RECOVERY_TIMEOUT_MS,
+					cancelPromise,
+				);
+				if (compactionEnd !== "done") return "failed";
+			}
+
+			if (!this.compactionWillRetry) return "failed";
+
+			if (this.retryAgentEnd) {
+				const retryEnd = await this.waitForPhase(
+					this.retryAgentEnd.promise,
+					OVERFLOW_RECOVERY_TIMEOUT_MS,
+					cancelPromise,
+				);
+				if (retryEnd !== "done") return "failed";
+			}
+
+			if (this.overflowAutoRetryEnd) {
+				const autoRetryEnd = await this.waitForPhase(
+					this.overflowAutoRetryEnd.promise,
+					OVERFLOW_RECOVERY_TIMEOUT_MS,
+					cancelPromise,
+				);
+				if (autoRetryEnd !== "done") return "failed";
+			}
+
+			return "recovered";
+		} finally {
+			for (const timer of this.timers) clearTimeout(timer);
+		}
+	}
+
+	private async waitForPhase(
+		phasePromise: Promise<void>,
+		timeoutMs: number,
+		cancelPromise: Promise<void>,
+	): Promise<PhaseWaitResult> {
+		return Promise.race([
+			phasePromise.then(() => "done" as const),
+			cancelPromise.then(() => "cancelled" as const),
+			new Promise<"timeout">((resolve) => {
+				this.timers.push(setTimeout(() => resolve("timeout"), timeoutMs));
+			}),
+		]);
+	}
+
+	// agent_end can be followed immediately by auto_retry_start in the same
+	// _processAgentEvent tick. Resolve on microtask so we can ignore retrying
+	// attempts and only accept terminal agent_end events.
+	private onAgentEnd(): void {
+		queueMicrotask(() => {
+			if (this.autoRetryActive) return;
+
+			if (!this.initialAgentEnd.isDone()) {
+				this.initialAgentEnd.resolve();
+				return;
+			}
+
+			this.retryAgentEnd?.resolve();
+		});
+	}
+
+	private onCompactionStart(reason: "manual" | "threshold" | "overflow"): void {
+		if (reason !== "overflow") return;
+		this.overflowDetected = true;
+		this.compactionEnd ??= createDeferredPhase();
+	}
+
+	private onCompactionEnd(reason: "manual" | "threshold" | "overflow", willRetry: boolean): void {
+		if (reason !== "overflow") return;
+
+		this.compactionWillRetry = willRetry;
+		if (willRetry) {
+			this.retryAgentEnd ??= createDeferredPhase();
+		}
+		this.compactionEnd?.resolve();
+	}
+
+	private onAutoRetryStart(): void {
+		this.autoRetryActive = true;
+		if (this.overflowDetected) {
+			this.overflowAutoRetryEnd ??= createDeferredPhase();
+		}
+	}
+
+	private onAutoRetryEnd(): void {
+		this.autoRetryActive = false;
+		this.overflowAutoRetryEnd?.resolve();
+	}
+}
+
+export async function runPromptWithOverflowRecovery(
+	session: AgentSession,
+	text: string,
+	signal: AbortSignal,
+): Promise<OverflowRecoveryResult> {
+	const tracker = new OverflowRecoveryTracker();
+	const unsubscribe = session.subscribe((event) => tracker.handleEvent(event));
+
+	try {
+		await session.prompt(text);
+		return await tracker.awaitCompletion(signal);
+	} finally {
+		unsubscribe();
+	}
+}

package/extension/runtime/subagent-registry.ts

@@ -0,0 +1,78 @@
+import type { AgentConfig } from "../agent-discovery.js";
+import type { ActiveAgentSummary, SubagentState } from "./subagent-state.js";
+import {
+	buildActiveAgentSummary,
+	generateId,
+	isAbortableStatus,
+} from "./subagent-state.js";
+
+export class SubagentRegistry {
+	private activeAgents = new Map<string, SubagentState>();
+
+	create(agentConfig: AgentConfig, task: string, ownerSessionId: string): SubagentState {
+		const id = generateId(agentConfig.name, new Set(this.activeAgents.keys()));
+		const state: SubagentState = {
+			id,
+			agentConfig,
+			task,
+			status: "running",
+			ownerSessionId,
+			session: null,
+			turns: 0,
+			contextTokens: 0,
+			model: undefined,
+		};
+
+		this.activeAgents.set(id, state);
+		return state;
+	}
+
+	get(id: string): SubagentState | undefined {
+		return this.activeAgents.get(id);
+	}
+
+	hasState(state: SubagentState): boolean {
+		return this.activeAgents.get(state.id) === state;
+	}
+
+	delete(id: string): void {
+		this.activeAgents.delete(id);
+	}
+
+	countRunningForOwner(ownerSessionId: string, excludeId: string): number {
+		let count = 0;
+		for (const state of this.activeAgents.values()) {
+			if (
+				state.id !== excludeId &&
+				state.ownerSessionId === ownerSessionId &&
+				state.status === "running"
+			) {
+				count++;
+			}
+		}
+		return count;
+	}
+
+	getActiveSummariesForOwner(ownerSessionId: string): ActiveAgentSummary[] {
+		return Array.from(this.activeAgents.values())
+			.filter(
+				(state) => isAbortableStatus(state.status) && state.ownerSessionId === ownerSessionId,
+			)
+			.map(buildActiveAgentSummary);
+	}
+
+	getOwnedAbortableIds(ownerSessionId: string): string[] {
+		return Array.from(this.activeAgents.values())
+			.filter(
+				(state) =>
+					state.ownerSessionId === ownerSessionId && isAbortableStatus(state.status),
+			)
+			.map((state) => state.id);
+	}
+
+	getAllAbortable(): SubagentState[] {
+		return Array.from(this.activeAgents.values()).filter((state) =>
+			isAbortableStatus(state.status),
+		);
+	}
+}

package/extension/runtime/subagent-state.ts

@@ -0,0 +1,59 @@
+import { randomBytes } from "node:crypto";
+import type { AgentSession } from "@mariozechner/pi-coding-agent";
+import type { AgentConfig } from "../agent-discovery.js";
+import type { SubagentStatus } from "../subagent-messages.js";
+
+export interface SubagentState {
+	id: string;
+	agentConfig: AgentConfig;
+	task: string;
+	status: SubagentStatus;
+	ownerSessionId: string;
+	session: AgentSession | null;
+	turns: number;
+	contextTokens: number;
+	model: string | undefined;
+	error?: string;
+	result?: string;
+	promptAbortController?: AbortController;
+	unsubscribe?: () => void;
+}
+
+export interface ActiveAgentSummary {
+	id: string;
+	agentName: string;
+	status: SubagentStatus;
+	turns: number;
+	contextTokens: number;
+	model: string | undefined;
+}
+
+export function generateId(name: string, existingIds: Set<string>): string {
+	for (let i = 0; i < 10; i++) {
+		const id = `${name}-${randomBytes(4).toString("hex")}`;
+		if (!existingIds.has(id)) return id;
+	}
+	return `${name}-${randomBytes(8).toString("hex")}`;
+}
+
+// Status may change externally via abort(). Standalone function avoids TS narrowing.
+export function isAborted(state: SubagentState): boolean {
+	return state.status === "aborted";
+}
+
+export function isAbortableStatus(status: SubagentStatus): boolean {
+	return status === "running" || status === "waiting";
+}
+
+export function buildActiveAgentSummary(
+	state: SubagentState,
+): ActiveAgentSummary {
+	return {
+		id: state.id,
+		agentName: state.agentConfig.name,
+		status: state.status,
+		turns: state.turns,
+		contextTokens: state.contextTokens,
+		model: state.model,
+	};
+}

package/extension/status-widget.ts

@@ -0,0 +1,107 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import type { ActiveAgentSummary } from "./runtime/crew-runtime.js";
+import type { CrewRuntime } from "./runtime/crew-runtime.js";
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const SPINNER_INTERVAL_MS = 80;
+
+function formatTokens(tokens: number): string {
+	if (tokens >= 1_000_000) return `${(tokens / 1_000_000).toFixed(1)}M`;
+	if (tokens >= 1_000) return `${(tokens / 1_000).toFixed(1)}k`;
+	return String(tokens);
+}
+
+function buildLine(agent: ActiveAgentSummary, frame: string): string {
+	const model = agent.model ?? "…";
+	const icon = agent.status === "waiting" ? "⏳" : frame;
+	return `${icon} ${agent.id} (${model}) · turn ${agent.turns} · ${formatTokens(agent.contextTokens)} ctx`;
+}
+
+interface WidgetState {
+	ctx: ExtensionContext;
+	text: Text;
+	// biome-ignore lint: TUI type from factory param
+	tui: any;
+	timer: ReturnType<typeof setInterval>;
+	frameIndex: number;
+}
+
+let widget: WidgetState | undefined;
+
+function disposeWidget(state: WidgetState): void {
+	clearInterval(state.timer);
+	if (widget === state) {
+		widget = undefined;
+	}
+}
+
+function clearWidget(): void {
+	const current = widget;
+	if (!current) return;
+	disposeWidget(current);
+	current.ctx.ui.setWidget("crew-status", undefined);
+}
+
+function hasRunningAgent(agents: ActiveAgentSummary[]): boolean {
+	return agents.some((agent) => agent.status === "running");
+}
+
+function syncWidgetText(state: WidgetState, agents: ActiveAgentSummary[]): void {
+	const frame = SPINNER_FRAMES[state.frameIndex % SPINNER_FRAMES.length];
+	const lines = agents.map((agent) => buildLine(agent, frame));
+	state.text.setText(lines.join("\n"));
+	state.tui.requestRender();
+}
+
+export function updateWidget(ctx: ExtensionContext, crew: CrewRuntime): void {
+	if (!ctx.hasUI) {
+		clearWidget();
+		return;
+	}
+
+	const ownerSessionId = ctx.sessionManager.getSessionId();
+	const running = crew.getActiveSummariesForOwner(ownerSessionId);
+	if (running.length === 0) {
+		clearWidget();
+		return;
+	}
+
+	if (widget && widget.ctx !== ctx) {
+		clearWidget();
+	}
+
+	if (widget) {
+		syncWidgetText(widget, running);
+		return;
+	}
+
+	ctx.ui.setWidget("crew-status", (tui, _theme) => {
+		const text = new Text("", 1, 0);
+		const state: WidgetState = {
+			ctx,
+			text,
+			tui,
+			frameIndex: 0,
+			timer: setInterval(() => {
+				const agents = crew.getActiveSummariesForOwner(ownerSessionId);
+				if (agents.length === 0) {
+					clearWidget();
+					return;
+				}
+				if (!hasRunningAgent(agents)) return;
+				state.frameIndex++;
+				syncWidgetText(state, agents);
+			}, SPINNER_INTERVAL_MS),
+		};
+
+		widget = state;
+		syncWidgetText(state, running);
+
+		return Object.assign(text, {
+			dispose() {
+				disposeWidget(state);
+			},
+		});
+	});
+}

package/extension/subagent-messages.ts

@@ -0,0 +1,124 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export type SubagentStatus = "running" | "waiting" | "done" | "error" | "aborted";
+
+export type SendMessageFn = ExtensionAPI["sendMessage"];
+
+export const STATUS_ICON: Record<SubagentStatus, string> = {
+	running: "⏳",
+	waiting: "⏳",
+	done: "✅",
+	error: "❌",
+	aborted: "⏹️",
+};
+
+export const STATUS_LABEL: Record<SubagentStatus, string> = {
+	running: "running",
+	waiting: "waiting for response",
+	done: "done",
+	error: "failed",
+	aborted: "aborted",
+};
+
+export interface SteeringPayload {
+	id: string;
+	agentName: string;
+	sessionFile?: string;
+	status: SubagentStatus;
+	result?: string;
+	error?: string;
+}
+
+export interface CrewResultMessageDetails {
+	agentId: string;
+	agentName: string;
+	sessionFile?: string;
+	status: SubagentStatus;
+	body?: string;
+}
+
+export function getCrewResultTitle(details: {
+	agentId: string;
+	agentName: string;
+	status: SubagentStatus;
+}): string {
+	return `Subagent '${details.agentName}' (${details.agentId}) ${STATUS_LABEL[details.status]}`;
+}
+
+function getSteeringBody(payload: SteeringPayload): string | undefined {
+	return (payload.status === "error" || payload.status === "aborted")
+		? (payload.error ?? payload.result)
+		: (payload.result ?? payload.error);
+}
+
+export function sendSteeringMessage(
+	payload: SteeringPayload,
+	sendMessage: SendMessageFn,
+	opts: { isIdle: boolean; triggerTurn: boolean },
+): void {
+	const body = getSteeringBody(payload);
+	const title = getCrewResultTitle({
+		agentId: payload.id,
+		agentName: payload.agentName,
+		status: payload.status,
+	});
+	const content = body
+		? `**${STATUS_ICON[payload.status]} ${title}**\n\n${body}`
+		: `**${STATUS_ICON[payload.status]} ${title}**`;
+
+	const message = {
+		customType: "crew-result",
+		content,
+		display: true,
+		details: {
+			agentId: payload.id,
+			agentName: payload.agentName,
+			sessionFile: payload.sessionFile,
+			status: payload.status,
+			body,
+		} satisfies CrewResultMessageDetails,
+	};
+
+	sendMessage(
+		message,
+		opts.isIdle
+			? { triggerTurn: opts.triggerTurn }
+			: { deliverAs: "steer", triggerTurn: opts.triggerTurn },
+	);
+}
+
+export function sendRemainingNote(
+	remainingCount: number,
+	sendMessage: SendMessageFn,
+	opts: { isIdle: boolean; triggerTurn: boolean },
+): void {
+	if (remainingCount <= 0) return;
+
+	sendMessage(
+		{
+			customType: "crew-remaining",
+			content: `⏳ ${remainingCount} subagent(s) still running`,
+			display: true,
+		},
+		opts.isIdle
+			? { triggerTurn: opts.triggerTurn }
+			: { deliverAs: "steer", triggerTurn: opts.triggerTurn },
+	);
+}
+
+export function sendCrewListActiveWarning(
+	sendMessage: SendMessageFn,
+	opts: { isIdle: boolean; triggerTurn: boolean },
+): void {
+	sendMessage(
+		{
+			customType: "crew-list-warning",
+			content:
+				"⚠ Active subagents detected. Do not poll crew_list for completion — results arrive as steering messages. Continue with unrelated work or end your turn and wait for the steering messages.",
+			display: true,
+		},
+		opts.isIdle
+			? { triggerTurn: opts.triggerTurn }
+			: { deliverAs: "steer", triggerTurn: opts.triggerTurn },
+	);
+}

package/extension/tool-registry.ts

@@ -0,0 +1,19 @@
+const SUPPORTED_TOOL_NAMES_LITERAL = [
+	"read",
+	"bash",
+	"edit",
+	"write",
+	"grep",
+	"find",
+	"ls",
+] as const;
+
+export type SupportedToolName = (typeof SUPPORTED_TOOL_NAMES_LITERAL)[number];
+
+export const SUPPORTED_TOOL_NAMES = Object.freeze(
+	[...SUPPORTED_TOOL_NAMES_LITERAL] as SupportedToolName[],
+);
+
+export function isSupportedToolName(name: string): name is SupportedToolName {
+	return SUPPORTED_TOOL_NAMES.includes(name as SupportedToolName);
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@melihmucuk/pi-crew",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "type": "module",
   "description": "Non-blocking subagent orchestration for pi coding agent",
   "files": [
-    "dist/",
+    "extension/",
     "agents/",
-    "prompts/",
-    "docs/architecture.md"
+    "skills/",
+    "prompts/"
   ],
   "author": "Melih Mucuk",
   "license": "MIT",
@@ -21,7 +21,10 @@
   ],
   "pi": {
     "extensions": [
-      "./dist/index.js"
+      "./extension/index.ts"
+    ],
+    "skills": [
+      "./skills"
     ],
     "prompts": [
       "./prompts"
@@ -29,10 +32,7 @@
     "video": "https://monkeys-team.ams3.cdn.digitaloceanspaces.com/pi-crew-demo.mp4"
   },
   "scripts": {
-    "clean": "rm -rf dist",
-    "build": "npm run clean && tsc",
-    "typecheck": "tsc --noEmit",
-    "prepare": "npm run build"
+    "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
     "@mariozechner/pi-agent-core": "*",
@@ -42,12 +42,12 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@mariozechner/pi-agent-core": "^0.70.0",
-    "@mariozechner/pi-ai": "^0.70.0",
-    "@mariozechner/pi-coding-agent": "^0.70.0",
-    "@mariozechner/pi-tui": "^0.70.0",
+    "@mariozechner/pi-agent-core": "^0.73.0",
+    "@mariozechner/pi-ai": "^0.73.0",
+    "@mariozechner/pi-coding-agent": "^0.73.0",
+    "@mariozechner/pi-tui": "^0.73.0",
     "@types/node": "^22.19.17",
-    "typebox": "^1.1.33",
+    "typebox": "^1.1.37",
     "typescript": "^5.9.3"
   }
 }