@melihmucuk/pi-crew 1.0.16 → 1.0.17

package/extension/runtime/{delivery-coordinator.ts → owner-session-coordinator.ts}

@@ -1,8 +1,8 @@
+import type { SendMessageFn } from "../message-delivery-policy.js";
 import {
 	type SteeringPayload,
 	sendRemainingNote,
 	sendSteeringMessage,
-	type SendMessageFn,
 } from "../subagent-messages.js";
 
 export interface ActiveRuntimeBinding {
@@ -17,25 +17,43 @@ interface PendingMessage {
 	queuedAt: number;
 }
 
-export class DeliveryCoordinator {
+interface OwnerSessionCoordinatorDeps {
+	countRunningForOwner: (ownerSessionId: string, excludeId: string) => number;
+	onRefreshOwnerSession: (ownerSessionId: string) => void;
+	now?: () => number;
+	scheduleFlush?: (callback: () => void) => void;
+}
+
+const PENDING_MESSAGE_TTL_MS = 86_400_000;
+
+export class OwnerSessionCoordinator {
 	private binding: ActiveRuntimeBinding | undefined;
 	private pendingMessages: PendingMessage[] = [];
 	private flushScheduled = false;
+	private readonly countRunningForOwner: (ownerSessionId: string, excludeId: string) => number;
+	private readonly onRefreshOwnerSession: (ownerSessionId: string) => void;
+	private readonly now: () => number;
+	private readonly scheduleFlush: (callback: () => void) => void;
+
+	constructor(deps: OwnerSessionCoordinatorDeps) {
+		this.countRunningForOwner = deps.countRunningForOwner;
+		this.onRefreshOwnerSession = deps.onRefreshOwnerSession;
+		this.now = deps.now ?? Date.now;
+		this.scheduleFlush = deps.scheduleFlush ?? ((callback) => setTimeout(callback, 0));
+	}
 
-	activateSession(
-		binding: ActiveRuntimeBinding,
-		countRunningForOwner: (ownerSessionId: string, excludeId: string) => number,
-	): void {
+	activateSession(binding: ActiveRuntimeBinding): void {
 		this.binding = binding;
+
 		// Delay flush to next macrotask. session_start fires before pi-core
 		// calls _reconnectToAgent(), so synchronous delivery would emit agent
 		// events while the session listener is disconnected, losing JSONL persistence.
 		if (this.pendingMessages.some((entry) => entry.ownerSessionId === binding.sessionId)) {
 			this.flushScheduled = true;
-			setTimeout(() => {
+			this.scheduleFlush(() => {
 				this.flushScheduled = false;
-				this.flushPending(countRunningForOwner);
-			}, 0);
+				this.flushPending();
+			});
 		}
 	}
 
@@ -45,38 +63,34 @@ export class DeliveryCoordinator {
 		}
 	}
 
-	deliver(
-		ownerSessionId: string,
-		payload: SteeringPayload,
-		countRunningForOwner: (ownerSessionId: string, excludeId: string) => number,
-	): void {
+	refresh(ownerSessionId: string): void {
+		this.onRefreshOwnerSession(ownerSessionId);
+	}
+
+	deliver(ownerSessionId: string, payload: SteeringPayload): void {
 		if (!this.binding || ownerSessionId !== this.binding.sessionId || this.flushScheduled) {
-			this.pendingMessages.push({ ownerSessionId, payload, queuedAt: Date.now() });
+			this.queue(ownerSessionId, payload);
 			return;
 		}
 
-		this.send(ownerSessionId, payload, countRunningForOwner);
+		this.send(ownerSessionId, payload);
+	}
+
+	private queue(ownerSessionId: string, payload: SteeringPayload): void {
+		this.pendingMessages.push({ ownerSessionId, payload, queuedAt: this.now() });
 	}
 
-	/**
-	 * Remove pending messages older than the TTL.
-	 * Called during activateSession to prevent unbounded memory growth.
-	 */
 	private cleanStaleMessages(): void {
-		const maxAgeMs = 86_400_000; // 24 hours
-		const cutoff = Date.now() - maxAgeMs;
+		const cutoff = this.now() - PENDING_MESSAGE_TTL_MS;
 		this.pendingMessages = this.pendingMessages.filter(
 			(entry) => entry.queuedAt >= cutoff,
 		);
 	}
 
-	private flushPending(
-		countRunningForOwner: (ownerSessionId: string, excludeId: string) => number,
-	): void {
+	private flushPending(): void {
 		if (!this.binding) return;
 		const targetSessionId = this.binding.sessionId;
 
-		// Clean up stale messages first (older than TTL)
 		this.cleanStaleMessages();
 
 		const toDeliver: PendingMessage[] = [];
@@ -86,17 +100,14 @@ export class DeliveryCoordinator {
 			if (entry.ownerSessionId === targetSessionId) {
 				toDeliver.push(entry);
 			} else {
-				// Keep all other messages - they may be for sessions that will be reactivated later
 				remaining.push(entry);
 			}
 		}
 
-		// Keep messages for other sessions
 		this.pendingMessages = remaining;
 
-		// Deliver messages for the active session
 		for (const entry of toDeliver) {
-			this.send(entry.ownerSessionId, entry.payload, countRunningForOwner);
+			this.send(entry.ownerSessionId, entry.payload);
 		}
 	}
 
@@ -105,17 +116,13 @@ export class DeliveryCoordinator {
 	 * owner is idle, queue the result without triggering, then queue the separate
 	 * remaining note with triggerTurn so the next turn sees both in order.
 	 */
-	private send(
-		ownerSessionId: string,
-		payload: SteeringPayload,
-		countRunningForOwner: (ownerSessionId: string, excludeId: string) => number,
-	): void {
+	private send(ownerSessionId: string, payload: SteeringPayload): void {
 		if (!this.binding || this.binding.sessionId !== ownerSessionId) {
-			this.pendingMessages.push({ ownerSessionId, payload, queuedAt: Date.now() });
+			this.queue(ownerSessionId, payload);
 			return;
 		}
 
-		const remaining = countRunningForOwner(ownerSessionId, payload.id);
+		const remaining = this.countRunningForOwner(ownerSessionId, payload.id);
 		const isIdle = this.binding.isIdle();
 		const triggerResultTurn = !(isIdle && remaining > 0);
 

package/extension/runtime/subagent-lifecycle.ts

@@ -0,0 +1,203 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { BootstrapContext } from "../bootstrap-session.js";
+import { bootstrapSession } from "../bootstrap-session.js";
+import type { SubagentStatus } from "../subagent-messages.js";
+import { runPromptWithOverflowRecovery } from "./overflow-recovery.js";
+import type { SubagentState } from "./subagent-registry.js";
+import { isAborted } from "./subagent-transitions.js";
+
+interface PromptOutcome {
+	status: Extract<SubagentStatus, "done" | "waiting" | "error" | "aborted">;
+	result?: string;
+	error?: string;
+}
+
+interface StartOptions {
+	cwd: string;
+	ctx: BootstrapContext;
+	extensionResolvedPath: string;
+	onWarning?: (message: string) => void;
+}
+
+interface SubagentLifecycleCallbacks {
+	isCurrent: (state: SubagentState) => boolean;
+	onProgress: (ownerSessionId: string) => void;
+	onSettled: (
+		state: SubagentState,
+		status: Extract<SubagentStatus, "done" | "waiting" | "error" | "aborted">,
+		outcome: { result?: string; error?: string },
+	) => void;
+}
+
+function getLastAssistantMessage(
+	messages: AgentMessage[],
+): AssistantMessage | undefined {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role === "assistant") {
+			return msg as AssistantMessage;
+		}
+	}
+	return undefined;
+}
+
+function getAssistantText(
+	message: AssistantMessage | undefined,
+): string | undefined {
+	if (!message) return undefined;
+
+	const texts: string[] = [];
+	for (const part of message.content) {
+		if (part.type === "text") {
+			texts.push(part.text);
+		}
+	}
+
+	return texts.length > 0 ? texts.join("\n") : undefined;
+}
+
+function getPromptOutcome(state: SubagentState): PromptOutcome {
+	const lastAssistant = getLastAssistantMessage(state.session!.messages);
+	const text = getAssistantText(lastAssistant);
+
+	if (lastAssistant?.stopReason === "error") {
+		return {
+			status: "error",
+			error: lastAssistant.errorMessage ?? text ?? "(no output)",
+		};
+	}
+
+	if (lastAssistant?.stopReason === "aborted") {
+		return {
+			status: "aborted",
+			error: lastAssistant.errorMessage ?? text ?? "(no output)",
+		};
+	}
+
+	return {
+		status: state.agentConfig.interactive ? "waiting" : "done",
+		result: text ?? "(no output)",
+	};
+}
+
+export class SubagentLifecycle {
+	constructor(private readonly callbacks: SubagentLifecycleCallbacks) {}
+
+	start(state: SubagentState, opts: StartOptions): void {
+		void this.spawnSession(state, opts);
+	}
+
+	respond(state: SubagentState, message: string): void {
+		void this.runPromptCycle(state, message);
+	}
+
+	abortPrompt(state: SubagentState): void {
+		state.promptAbortController?.abort();
+		state.promptAbortController = undefined;
+		state.session?.abortCompaction();
+		state.session?.abortRetry();
+		state.session?.abort().catch(() => {});
+	}
+
+	private attachSessionListeners(
+		state: SubagentState,
+		session: AgentSession,
+	): void {
+		state.unsubscribe = session.subscribe((event) => {
+			if (event.type !== "turn_end") return;
+
+			state.turns++;
+			const msg = event.message;
+			if (msg.role === "assistant") {
+				const assistantMsg = msg as AssistantMessage;
+				state.contextTokens = assistantMsg.usage.totalTokens;
+				state.model = assistantMsg.model;
+			}
+			this.callbacks.onProgress(state.ownerSessionId);
+		});
+	}
+
+	private attachSpawnedSession(
+		state: SubagentState,
+		session: AgentSession,
+	): boolean {
+		if (!this.callbacks.isCurrent(state)) {
+			session.dispose();
+			return false;
+		}
+
+		state.session = session;
+		return true;
+	}
+
+	private async runPromptCycle(
+		state: SubagentState,
+		prompt: string,
+	): Promise<void> {
+		if (isAborted(state)) return;
+
+		const abortController = new AbortController();
+		state.promptAbortController = abortController;
+
+		try {
+			const recovery = await runPromptWithOverflowRecovery(
+				state.session!,
+				prompt,
+				abortController.signal,
+			);
+			if (isAborted(state)) return;
+
+			const outcome = getPromptOutcome(state);
+
+			if (recovery === "failed" && outcome.status !== "error") {
+				this.callbacks.onSettled(state, "error", {
+					error: "Context overflow recovery failed",
+				});
+				return;
+			}
+
+			this.callbacks.onSettled(state, outcome.status, outcome);
+		} catch (err) {
+			if (isAborted(state)) return;
+
+			const error = err instanceof Error ? err.message : String(err);
+			this.callbacks.onSettled(state, "error", { error });
+		} finally {
+			state.promptAbortController = undefined;
+		}
+	}
+
+	private async spawnSession(
+		state: SubagentState,
+		opts: StartOptions,
+	): Promise<void> {
+		try {
+			if (isAborted(state)) return;
+
+			const { session, warnings } = await bootstrapSession({
+				agentConfig: state.agentConfig,
+				cwd: opts.cwd,
+				ctx: opts.ctx,
+				extensionResolvedPath: opts.extensionResolvedPath,
+			});
+
+			for (const warning of warnings) {
+				opts.onWarning?.(warning);
+			}
+
+			if (!this.attachSpawnedSession(state, session)) return;
+
+			this.attachSessionListeners(state, session);
+			await this.runPromptCycle(state, state.task);
+		} catch (err) {
+			if (isAborted(state)) return;
+
+			if (state.status === "running") {
+				const error = err instanceof Error ? err.message : String(err);
+				this.callbacks.onSettled(state, "error", { error });
+			}
+		}
+	}
+}

package/extension/runtime/subagent-registry.ts

@@ -1,10 +1,54 @@
+import { randomBytes } from "node:crypto";
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig } from "../agent-discovery.js";
-import type { ActiveAgentSummary, SubagentState } from "./subagent-state.js";
-import {
-	buildActiveAgentSummary,
-	generateId,
-	isAbortableStatus,
-} from "./subagent-state.js";
+import type { SubagentStatus } from "../subagent-messages.js";
+import { isAbortableStatus } from "./subagent-transitions.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;
+}
+
+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")}`;
+}
+
+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,
+	};
+}
 
 export class SubagentRegistry {
 	private activeAgents = new Map<string, SubagentState>();

package/extension/runtime/subagent-transitions.ts

@@ -0,0 +1,100 @@
+import type { SubagentStatus } from "../subagent-messages.js";
+import type { SubagentState } from "./subagent-registry.js";
+
+export type SettledSubagentStatus = Extract<
+	SubagentStatus,
+	"done" | "waiting" | "error" | "aborted"
+>;
+
+export interface SubagentTransitionOutcome {
+	result?: string;
+	error?: string;
+}
+
+type SubagentTransitionResult =
+	| { ok: true; state: SubagentState }
+	| { ok: false; error: string };
+
+export function isAborted(state: SubagentState): boolean {
+	return state.status === "aborted";
+}
+
+export function isAbortableStatus(status: SubagentStatus): boolean {
+	return status === "running" || status === "waiting";
+}
+
+export function canAbortSubagent(
+	state: SubagentState | undefined,
+): state is SubagentState {
+	return Boolean(state && isAbortableStatus(state.status));
+}
+
+function validateOwnedSubagent(
+	state: SubagentState | undefined,
+	id: string,
+	callerSessionId: string,
+	missingMessage: string,
+): SubagentTransitionResult {
+	if (!state) return { ok: false, error: missingMessage };
+	if (state.ownerSessionId !== callerSessionId) {
+		return { ok: false, error: `Subagent "${id}" belongs to a different session` };
+	}
+	return { ok: true, state };
+}
+
+export function startSubagentResponse(
+	state: SubagentState | undefined,
+	id: string,
+	callerSessionId: string,
+): SubagentTransitionResult {
+	const owned = validateOwnedSubagent(
+		state,
+		id,
+		callerSessionId,
+		`No subagent with id "${id}"`,
+	);
+	if (!owned.ok) return owned;
+
+	if (owned.state.status !== "waiting") {
+		return {
+			ok: false,
+			error: `Subagent "${id}" is not waiting for a response (status: ${owned.state.status})`,
+		};
+	}
+	if (!owned.state.session) {
+		return { ok: false, error: `Subagent "${id}" has no active session` };
+	}
+
+	owned.state.status = "running";
+	return owned;
+}
+
+export function validateSubagentDone(
+	state: SubagentState | undefined,
+	id: string,
+	callerSessionId: string,
+): SubagentTransitionResult {
+	const owned = validateOwnedSubagent(
+		state,
+		id,
+		callerSessionId,
+		`No active subagent with id "${id}"`,
+	);
+	if (!owned.ok) return owned;
+
+	if (owned.state.status !== "waiting") {
+		return { ok: false, error: `Subagent "${id}" is not in waiting state` };
+	}
+
+	return owned;
+}
+
+export function settleSubagent(
+	state: SubagentState,
+	status: SettledSubagentStatus,
+	outcome: SubagentTransitionOutcome,
+): void {
+	state.status = status;
+	state.result = outcome.result;
+	state.error = outcome.error;
+}

package/extension/subagent-messages.ts

@@ -1,9 +1,8 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { sendWithDeliveryPolicy, type SendMessageFn } from "./message-delivery-policy.js";
 
+export type { SendMessageFn } from "./message-delivery-policy.js";
 export type SubagentStatus = "running" | "waiting" | "done" | "error" | "aborted";
 
-export type SendMessageFn = ExtensionAPI["sendMessage"];
-
 export const STATUS_ICON: Record<SubagentStatus, string> = {
 	running: "⏳",
 	waiting: "⏳",
@@ -79,12 +78,7 @@ export function sendSteeringMessage(
 		} satisfies CrewResultMessageDetails,
 	};
 
-	sendMessage(
-		message,
-		opts.isIdle
-			? { triggerTurn: opts.triggerTurn }
-			: { deliverAs: "steer", triggerTurn: opts.triggerTurn },
-	);
+	sendWithDeliveryPolicy(message, sendMessage, opts);
 }
 
 export function sendRemainingNote(
@@ -94,15 +88,14 @@ export function sendRemainingNote(
 ): void {
 	if (remainingCount <= 0) return;
 
-	sendMessage(
+	sendWithDeliveryPolicy(
 		{
 			customType: "crew-remaining",
 			content: `⏳ ${remainingCount} subagent(s) still running`,
 			display: true,
 		},
-		opts.isIdle
-			? { triggerTurn: opts.triggerTurn }
-			: { deliverAs: "steer", triggerTurn: opts.triggerTurn },
+		sendMessage,
+		opts,
 	);
 }
 
@@ -110,15 +103,14 @@ export function sendCrewListActiveWarning(
 	sendMessage: SendMessageFn,
 	opts: { isIdle: boolean; triggerTurn: boolean },
 ): void {
-	sendMessage(
+	sendWithDeliveryPolicy(
 		{
 			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 },
+		sendMessage,
+		opts,
 	);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melihmucuk/pi-crew",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "type": "module",
   "description": "Non-blocking subagent orchestration for pi coding agent",
   "files": [
@@ -32,7 +32,8 @@
     "video": "https://monkeys-team.ams3.cdn.digitaloceanspaces.com/pi-crew-demo.mp4"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/**/*.test.ts"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
@@ -42,11 +43,12 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.74.0",
-    "@earendil-works/pi-ai": "^0.74.0",
-    "@earendil-works/pi-coding-agent": "^0.74.0",
-    "@earendil-works/pi-tui": "^0.74.0",
+    "@earendil-works/pi-agent-core": "^0.75.4",
+    "@earendil-works/pi-ai": "^0.75.4",
+    "@earendil-works/pi-coding-agent": "^0.75.4",
+    "@earendil-works/pi-tui": "^0.75.4",
     "@types/node": "^22.19.17",
+    "tsx": "^4.22.3",
     "typebox": "^1.1.38",
     "typescript": "^5.9.3"
   }

package/prompts/pi-crew-plan.md

@@ -6,31 +6,32 @@ description: Orchestrate scouts and planner to produce an implementation plan.
 
 Additional instructions: `$ARGUMENTS`
 
-You are a planning orchestrator, not a scout, planner, or implementer. Resolve the task and scope, gather only minimal orientation context, delegate discovery to scouts when available, pass cleaned findings to the planner, and manage the planner lifecycle. Do not perform deep investigation, write the plan yourself, or modify files.
+You are a planning orchestrator, not a scout, planner, or implementer. Resolve the task and scope, gather only minimal task-specific context, delegate discovery to scouts when available, pass cleaned findings to the planner, and manage the planner lifecycle. Do not perform deep investigation, write the plan yourself, or modify files.
 
 ## Task and Context
 
 Use additional instructions when provided; otherwise use the current conversation task. If the task or scope is decision-critical unclear or conflicting, ask the user before proceeding.
 
-Build shared context for subagents:
+Build compact shared context for subagents. Include only information that helps this planning task beyond the selected subagent’s obvious role:
 
-- user task;
-- project root;
-- constraints and additional instructions;
-- user-provided references as paths/URLs and why they matter;
-- scope boundary: in scope, out of scope, assumptions;
-- minimal orientation already gathered;
-- known stack, dependencies, conventions when relevant.
+- user intent and expected outcome;
+- user-provided references, plus a concise summary after reading them when practical;
+- task-specific decisions, constraints, and assumptions not already covered by repo guidance;
+- non-default scope boundaries, when needed;
+- minimal orientation already gathered, only when it clarifies where to look;
+- exact errors/output or verification context, when relevant.
 
-Do not copy full reference contents. Subagents cannot see conversation context unless you include it.
+Do not copy full reference contents. Do not include project root/cwd, generic repo conventions, default scope, edit permissions, output format, or role boilerplate. Subagents run in the same repo cwd and can inspect repo guidance themselves.
 
-Gather only enough orientation to assign scout scopes or brief the planner: top-level structure, key config, README/AGENTS when relevant, and targeted searches or entrypoint checks. Do not read full files, trace call chains, or analyze implementations.
+If the user provides a plan, spec, issue, doc, design, URL, or file as the source of intent, read it when practical and summarize the relevant intent instead of merely passing the path.
+
+Gather only enough orientation to assign scout scopes or brief the planner: targeted searches, likely entry points, and small config or structure checks when they materially affect delegation. Do not read full implementation files, trace call chains, or analyze implementations. Do not read README/AGENTS just to repeat generic repo guidance.
 
 ## Scouts
 
 Call `crew_list` and check for `scout`. If unavailable, continue to planner with minimal context and note the missing scout coverage.
 
-If available, spawn up to 4 scouts for distinct, non-overlapping focus areas. Keep each task narrow and include shared context, explicit investigation scope, requested facts, read-only constraints, and no build/test/install/format/codegen/server-start commands.
+If available, spawn up to 4 scouts for distinct, non-overlapping focus areas. Keep each task narrow and include only task-specific context, the investigation focus, requested facts, and relevant paths or entry points. Do not restate scout role boilerplate, default read-only behavior, output format, or generic command restrictions.
 
 Wait for scout results without polling or fabrication. If a scout fails or returns no useful findings, retry or reformulate once. If it still fails, record the gap and continue.
 
@@ -40,7 +41,7 @@ Before planner handoff, perform only mechanical cleanup: remove duplicates, irre
 
 Call `crew_list` and check for `planner`. If unavailable, tell the user and stop; do not write the plan yourself.
 
-Spawn the planner with shared context, cleaned scout findings, and gaps. The planner is interactive and may return **Blocking Questions**, **Implementation Plan**, or **No plan needed**.
+Spawn the planner with compact shared context, cleaned scout findings, and gaps. Keep the handoff focused on intent, decisions, constraints, facts, paths, relationships, and unresolved questions. Do not restate planner role boilerplate, output format, edit permissions, or obvious next steps.
 
 Do not rewrite planner output that is already visible as a steering message.