@narumitw/pi-subagents 1.0.1 → 2.0.0

package/src/completion-render.ts

@@ -0,0 +1,189 @@
+import type { MessageRenderer, Theme } from "@earendil-works/pi-coding-agent";
+import { Box, type Component, Spacer, sliceByColumn, visibleWidth } from "@earendil-works/pi-tui";
+import { MAX_TOOL_MESSAGE_BYTES } from "./limits.js";
+import {
+	COLLAPSED_LIST_LIMIT,
+	expansionHint,
+	type RenderStatus,
+	recordList,
+	recordValue,
+	safeBlock,
+	safeLine,
+	statusBadge,
+} from "./render-common.js";
+
+export const SUBAGENT_COMPLETION_MESSAGE_TYPE = "pi-subagent-completion";
+
+export const renderCompletionMessage: MessageRenderer = (message, options, theme) => {
+	const box = new Box(options.outputPad, 1, (text) => theme.bg("customMessageBg", text));
+	if (options.expanded) {
+		box.addChild(
+			new ExactText(
+				theme.fg("customMessageLabel", theme.bold(`[${SUBAGENT_COMPLETION_MESSAGE_TYPE}]`)),
+			),
+		);
+		box.addChild(new Spacer(1));
+		box.addChild(
+			new ExactText(
+				safeBlock(messageText(message.content), "(no completion content)", MAX_TOOL_MESSAGE_BYTES),
+				(text) => theme.fg("customMessageText", text),
+			),
+		);
+		return box;
+	}
+
+	box.addChild(new ExactText(collapsedCompletion(message.content, message.details, theme)));
+	return box;
+};
+
+function collapsedCompletion(contentValue: unknown, detailsValue: unknown, theme: Theme): string {
+	const content = safeBlock(messageText(contentValue), "", MAX_TOOL_MESSAGE_BYTES);
+	const details = recordValue(detailsValue) ?? {};
+	const completions = recordList(details.completions);
+	if (completions.length > 0 || details.completionCount !== undefined) {
+		return collapsedBatch(details, completions, theme);
+	}
+	return collapsedSingle(content, details, theme);
+}
+
+function collapsedSingle(content: string, details: Record<string, unknown>, theme: Theme): string {
+	const agent = optionalLine(details.agent) || extractedField(content, "Agent") || "subagent";
+	const state = optionalLine(details.state) || extractedField(content, "State") || "completed";
+	const task = optionalLine(details.task) || extractedField(content, "Task");
+	const payload = payloadPreview(content);
+	const lines = [
+		`${statusBadge(theme, renderStatus(state))}${theme.fg("muted", " · ")}${theme.fg("customMessageLabel", theme.bold(agent))}`,
+	];
+	if (task) lines.push(`${theme.fg("muted", "Task: ")}${theme.fg("customMessageText", task)}`);
+	if (payload) {
+		lines.push(`${theme.fg("muted", "Payload: ")}${theme.fg("customMessageText", payload)}`);
+	}
+	lines.push(expansionHint());
+	return lines.join("\n");
+}
+
+function collapsedBatch(
+	details: Record<string, unknown>,
+	completions: Record<string, unknown>[],
+	theme: Theme,
+): string {
+	const declaredCount =
+		typeof details.completionCount === "number" && Number.isFinite(details.completionCount)
+			? Math.max(0, Math.floor(details.completionCount))
+			: completions.length;
+	const count = Math.max(declaredCount, completions.length);
+	const statuses = completions.map((completion) => renderStatus(optionalLine(completion.state)));
+	const icon = statuses.includes("failed")
+		? theme.fg("error", "✗")
+		: statuses.some((status) => status !== "completed" && status !== "closed")
+			? theme.fg("warning", "◐")
+			: theme.fg("success", "✓");
+	const lines = [
+		`${icon} ${theme.fg("customMessageLabel", theme.bold(`${count} subagent completions`))}`,
+	];
+	for (const completion of completions.slice(0, COLLAPSED_LIST_LIMIT)) {
+		const agent = optionalLine(completion.agent) || "subagent";
+		const state = optionalLine(completion.state) || "completed";
+		const task = optionalLine(completion.task);
+		lines.push(
+			`${theme.fg("muted", "• ")}${theme.fg("accent", agent)} · ${statusBadge(theme, renderStatus(state))}${task ? theme.fg("dim", ` — ${task}`) : ""}`,
+		);
+	}
+	const visibleCount = Math.min(completions.length, COLLAPSED_LIST_LIMIT);
+	if (count > visibleCount) {
+		lines.push(theme.fg("muted", `… ${count - visibleCount} more`));
+	}
+	lines.push(expansionHint());
+	return lines.join("\n");
+}
+
+function messageText(value: unknown): string {
+	if (typeof value === "string") return value;
+	if (!Array.isArray(value)) return "";
+	return value
+		.flatMap((part) => {
+			const record = recordValue(part);
+			return record?.type === "text" && typeof record.text === "string" ? [record.text] : [];
+		})
+		.join("\n");
+}
+
+function extractedField(content: string, label: string): string {
+	const prefix = `${label}:`;
+	const line = content.split("\n").find((candidate) => candidate.startsWith(prefix));
+	return line ? safeLine(line.slice(prefix.length), "", 512) : "";
+}
+
+function payloadPreview(content: string): string {
+	const marker = "\nPayload:\n";
+	const start = content.indexOf(marker);
+	if (start < 0) return "";
+	for (const line of content.slice(start + marker.length).split("\n")) {
+		const preview = safeLine(line, "", 1024);
+		if (preview) return preview;
+	}
+	return "";
+}
+
+function optionalLine(value: unknown): string {
+	return typeof value === "string" ? safeLine(value, "", 512) : "";
+}
+
+function renderStatus(state: string): RenderStatus {
+	switch (state) {
+		case "failed":
+			return "failed";
+		case "cancelled":
+			return "cancelled";
+		case "interrupted":
+			return "interrupted";
+		case "closed":
+			return "closed";
+		case "blocked":
+		case "needs-input":
+		case "abstained":
+		case "stale":
+			return "warning";
+		default:
+			return "completed";
+	}
+}
+
+class ExactText implements Component {
+	constructor(
+		private readonly value: string,
+		private readonly style: (text: string) => string = (text) => text,
+	) {}
+
+	render(width: number): string[] {
+		const safeWidth = Math.max(1, width);
+		return this.value
+			.split("\n")
+			.flatMap((line) => hardWrapExact(line, safeWidth))
+			.map(this.style);
+	}
+
+	invalidate(): void {}
+}
+
+function hardWrapExact(value: string, width: number): string[] {
+	if (value.length === 0) return [""];
+	const columns = visibleWidth(value);
+	if (columns === 0) return [value];
+	const lines: string[] = [];
+	let column = 0;
+	while (column < columns) {
+		const chunk = sliceByColumn(value, column, width, true);
+		const chunkWidth = visibleWidth(chunk);
+		if (chunkWidth > 0) {
+			lines.push(chunk);
+			column += chunkWidth;
+			continue;
+		}
+		const oversized = sliceByColumn(value, column, width, false);
+		const oversizedWidth = visibleWidth(oversized);
+		lines.push("?".repeat(width));
+		column += Math.max(1, oversizedWidth);
+	}
+	return lines;
+}

package/src/completion-routing.ts

@@ -0,0 +1,24 @@
+import type { ManagedAgent, PersistedAgentCompletion } from "./registry-types.js";
+import { ROOT_TASK_PATH } from "./task-path.js";
+
+export type CompletionRecipient = Pick<PersistedAgentCompletion, "recipientId" | "recipientPath">;
+
+export function resolveCompletionRecipient(
+	agent: Pick<ManagedAgent, "id" | "parentId">,
+	getAgent: (
+		id: string,
+	) => Pick<ManagedAgent, "id" | "parentId" | "state" | "taskPath"> | undefined,
+): CompletionRecipient {
+	const visited = new Set([agent.id]);
+	let parentId = agent.parentId;
+	while (parentId && !visited.has(parentId)) {
+		visited.add(parentId);
+		const parent = getAgent(parentId);
+		if (!parent) break;
+		if (parent.state !== "closed") {
+			return { recipientId: parent.id, recipientPath: parent.taskPath ?? parent.id };
+		}
+		parentId = parent.parentId;
+	}
+	return { recipientId: "root", recipientPath: ROOT_TASK_PATH };
+}

package/src/config-registration.ts

@@ -1,6 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { cachedModuleLoader } from "./cached-module-loader.js";
-import { showSubagentHelp, showSubagentStatus } from "./config-status.js";
 import type { SubagentMenuOwner, SubagentSettingsRuntime } from "./config-ui.js";
 
 const SUBCOMMANDS = [
@@ -14,8 +13,14 @@ type ConfigUiModule = Pick<
 	"showSubagentManager" | "showSubagentSettings"
 >;
 
+type ConfigStatusModule = Pick<
+	typeof import("./config-status.js"),
+	"showSubagentHelp" | "showSubagentStatus"
+>;
+
 export interface ConfigRegistrationDependencies {
 	loadConfigUi?: () => Promise<ConfigUiModule>;
+	loadConfigStatus?: () => Promise<ConfigStatusModule>;
 }
 
 export function registerSubagentConfigLifecycle(pi: ExtensionAPI): SubagentMenuOwner {
@@ -41,6 +46,9 @@ export function registerSubagentConfigCommand(
 	const loadConfigUi = cachedModuleLoader(
 		dependencies.loadConfigUi ?? (() => import("./config-ui.js")),
 	);
+	const loadConfigStatus = cachedModuleLoader<ConfigStatusModule>(
+		dependencies.loadConfigStatus ?? (() => import("./config-status.js")),
+	);
 	pi.registerCommand("subagents", {
 		description: "Manage current-session subagents and user settings",
 		getArgumentCompletions(prefix: string) {
@@ -50,16 +58,33 @@ export function registerSubagentConfigCommand(
 		},
 		async handler(args, ctx) {
 			const subcommand = args.trim().toLowerCase();
+			const runStatusCommand = async (show: (status: ConfigStatusModule) => void) => {
+				const generation = owner.generation;
+				const controller = owner.controller;
+				const isCurrent = () =>
+					generation === owner.generation &&
+					controller === owner.controller &&
+					!controller.signal.aborted;
+				let status: ConfigStatusModule;
+				try {
+					status = await loadConfigStatus();
+				} catch (error) {
+					if (!isCurrent()) return;
+					throw error;
+				}
+				if (!isCurrent()) return;
+				show(status);
+			};
 			if (!subcommand && ctx.mode !== "tui") {
-				showSubagentStatus(ctx, runtime);
+				await runStatusCommand((status) => status.showSubagentStatus(ctx, runtime));
 				return;
 			}
 			if (subcommand === "status") {
-				showSubagentStatus(ctx, runtime);
+				await runStatusCommand((status) => status.showSubagentStatus(ctx, runtime));
 				return;
 			}
 			if (subcommand === "help") {
-				showSubagentHelp(ctx, runtime);
+				await runStatusCommand((status) => status.showSubagentHelp(ctx, runtime));
 				return;
 			}
 			if (!subcommand || subcommand === "settings") {

package/src/config-ui.ts

@@ -22,12 +22,10 @@ import {
 	applyAgentModel,
 	applyAgentThinking,
 	applyAgentTimeout,
-	applyExecutionProfileFromUi,
 	executionAgentPickerScreen,
 	executionAgentScreen,
 	executionModelInputScreen,
 	executionModelScreen,
-	executionProfileScreen,
 	executionThinkingScreen,
 	executionTimeoutInputScreen,
 	resetAgentExecution,
@@ -195,7 +193,6 @@ export async function showSubagentManager(
 		| "performance"
 		| "responsiveness"
 		| "transport"
-		| "execution-profiles"
 		| "execution-agent-picker"
 		| "execution-agent"
 		| "execution-thinking"
@@ -213,7 +210,6 @@ export async function showSubagentManager(
 		| "set-workflow"
 		| "clear-agents"
 		| "set-transport"
-		| "apply-execution-profile"
 		| "pick-execution-agent"
 		| "set-agent-thinking"
 		| "set-agent-model"
@@ -246,7 +242,7 @@ export async function showSubagentManager(
 						{
 							id: "workflow",
 							label: "Change delegation",
-							description: "Choose all methods, async only, or blocking only",
+							description: "Choose async only (recommended) or a compatibility workflow",
 							to: "workflow",
 						},
 						{
@@ -280,6 +276,8 @@ export async function showSubagentManager(
 					title: "Change Delegation",
 					lines: [
 						`Current: ${workflowLabel(active)}`,
+						"Recommended: Async only keeps the main agent responsive and omits blocking delegation and consultation.",
+						"Final-answer-dependent detached work needs automatic resume.",
 						...(snapshot.value !== active
 							? [`Configured after reload: ${workflowLabel(snapshot.value)}`]
 							: []),
@@ -294,21 +292,21 @@ export async function showSubagentManager(
 						? []
 						: [
 								{
-									id: "all",
-									label: "All delegation methods",
-									description: "Allow blocking batches and reusable async agents",
+									id: "async-only",
+									label: "Async only · Recommended",
+									description: "Detached lifecycle plus inspection; omit blocking and consultation",
 									action: "set-workflow" as const,
 								},
 								{
-									id: "async-only",
-									label: "Async only",
-									description: "Keep the root responsive; remove blocking subagent",
+									id: "all",
+									label: "All delegation methods",
+									description: "Compatibility: async, blocking, inspection, and consultation",
 									action: "set-workflow" as const,
 								},
 								{
 									id: "blocking-only",
 									label: "Blocking only",
-									description: "Keep blocking batches; remove reusable async agents",
+									description: "Compatibility: blocking and consultation without async lifecycle",
 									action: "set-workflow" as const,
 								},
 							],
@@ -378,7 +376,7 @@ export async function showSubagentManager(
 						{
 							id: "performance",
 							label: "Performance and execution",
-							description: "Transport, responsiveness, profiles, and agent defaults",
+							description: "Transport, responsiveness, and agent defaults",
 							to: "performance",
 						},
 						{ id: "back", label: "Back", action: "back" },
@@ -397,7 +395,6 @@ export async function showSubagentManager(
 						to: "responsiveness",
 					},
 					{ id: "transport", label: "Detached transport", to: "transport" },
-					{ id: "profiles", label: "Execution profiles", to: "execution-profiles" },
 					{
 						id: "agents",
 						label: "Agent execution defaults",
@@ -410,7 +407,6 @@ export async function showSubagentManager(
 			}),
 			responsiveness: () => responsivenessSetupScreen(runtime),
 			transport: () => transportSettingsScreen(runtime),
-			"execution-profiles": () => executionProfileScreen(),
 			"execution-agent-picker": () => executionAgentPickerScreen(availableAgents),
 			"execution-agent": () => executionAgentScreen(selectedExecutionAgent),
 			"execution-thinking": () => executionThinkingScreen(selectedExecutionAgent),
@@ -568,8 +564,6 @@ export async function showSubagentManager(
 			},
 			"set-transport": async ({ itemId, signal }) =>
 				applyTransportSetting(itemId, ctx, runtime, signal, isCurrent),
-			"apply-execution-profile": async ({ itemId, signal }) =>
-				applyExecutionProfileFromUi(itemId, ctx, signal, isCurrent),
 			"pick-execution-agent": async ({ itemId }) => {
 				selectedExecutionAgent = availableAgents.find((agent) => agent.name === itemId);
 				return selectedExecutionAgent

package/src/consult-registration.ts

@@ -49,9 +49,10 @@ export function registerSubagentConsult(
 		description: baseDescription(),
 		promptSnippet: "Consult one constrained read-only subagent and wait for its answer",
 		promptGuidelines: [
-			"Use subagent_consult for bounded reconnaissance, planning, or review whose result is required in the current turn.",
+			"Use subagent_consult only for bounded read-only evidence gathering when an independent perspective is worth making the main agent wait.",
+			"Keep ordinary planning and review in the main agent with applicable skills and deterministic checks; use subagent_consult only when synchronous read-only isolation adds concrete value.",
 			"Set subagent_consult timeoutMs to the shortest realistic work deadline for the task difficulty; split oversized consultations instead of extending the deadline merely to compensate for broad scope.",
-			"Implementation-shaped tasks remain read-only and can return only analysis or instructions.",
+			"Implementation-shaped subagent_consult tasks remain read-only and can return only analysis or instructions.",
 		],
 		parameters: SubagentConsultParams,
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {

package/src/consult-render.ts

@@ -6,7 +6,6 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import type { ConsultDetails, SubagentConsultParams } from "./consult.js";
-import { formatUsageStats } from "./render.js";
 import {
 	COLLAPSED_ANSWER_LINES,
 	COLLAPSED_LIST_LIMIT,
@@ -25,6 +24,7 @@ import {
 	textResult,
 	toolHeader,
 } from "./render-common.js";
+import { formatUsageStats } from "./usage-format.js";
 
 export function renderConsultCall(args: Partial<SubagentConsultParams>, theme: Theme) {
 	const scope = args.agentScope ?? "user";

package/src/create-stateful-transport.ts

@@ -2,7 +2,8 @@ import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 import type { SubagentSettings, SubagentTransportKind } from "./agents/types.js";
 import { cachedModuleLoader, throwIfAborted } from "./cached-module-loader.js";
 import type { ChildSessionFactory, ParentRuntimeSnapshot } from "./in-process-transport.js";
-import type { ManagedAgent, TurnOutcome } from "./registry.js";
+import type { PeerTransportRuntime } from "./peer-transport.js";
+import type { AgentMailboxMessage, ManagedAgent, TurnOutcome } from "./registry.js";
 import type { SubagentTransport } from "./transport.js";
 import type { TransportProgressCallback } from "./transport-types.js";
 
@@ -12,6 +13,7 @@ export interface CreateStatefulTransportOptions {
 	getParentRuntime(): ParentRuntimeSnapshot;
 	getSettings(): SubagentSettings | undefined;
 	createInProcessSession?: ChildSessionFactory;
+	peerRuntime?: PeerTransportRuntime;
 	loadTransport?: () => Promise<SubagentTransport>;
 }
 
@@ -58,6 +60,12 @@ class LazyStatefulTransport implements SubagentTransport {
 		return transport.runTurn(agent, task, signal, onProgress);
 	}
 
+	async deliverMessage(agent: ManagedAgent, message: AgentMailboxMessage): Promise<boolean> {
+		const transport = this.loaded;
+		if (!transport?.deliverMessage || this.closed) return false;
+		return transport.deliverMessage(agent, message);
+	}
+
 	async release(agent: ManagedAgent): Promise<void> {
 		const transport =
 			this.loaded ?? (this.loading ? await this.loading.catch(() => undefined) : undefined);
@@ -100,7 +108,10 @@ async function loadStatefulTransport(
 ): Promise<SubagentTransport> {
 	const subprocess = async () => {
 		const { SubprocessTransport } = await import("./subprocess-transport.js");
-		return new SubprocessTransport({ getSettings: options.getSettings });
+		return new SubprocessTransport({
+			getSettings: options.getSettings,
+			peerRuntime: options.peerRuntime,
+		});
 	};
 	const inProcess = async () => {
 		const [{ discoverAgents }, { InProcessTransport }] = await Promise.all([
@@ -109,6 +120,7 @@ async function loadStatefulTransport(
 		]);
 		return new InProcessTransport({
 			modelRegistry: options.modelRegistry,
+			peerRuntime: options.peerRuntime,
 			getParentRuntime: options.getParentRuntime,
 			createSession: options.createInProcessSession,
 			discoverAgent: (agent) =>
@@ -122,6 +134,7 @@ async function loadStatefulTransport(
 		return new RpcTransport({
 			getSettings: options.getSettings,
 			getParentRuntime: options.getParentRuntime,
+			peerRuntime: options.peerRuntime,
 		});
 	};
 	switch (options.kind) {

package/src/execution-ui.ts

@@ -1,77 +1,9 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig, SubagentThinkingLevel } from "./agents/types.js";
-import {
-	applyExecutionProfile,
-	EXECUTION_PROFILES,
-	type ExecutionProfile,
-	executionProfileDescription,
-	executionProfileLabel,
-	executionProfilePreview,
-	inspectExecutionProfile,
-} from "./execution-profiles.js";
 import { MAX_SUBAGENT_TIMEOUT_MS } from "./limits.js";
 import { safeTerminalLine as safeTerminalText } from "./safe-text.js";
 import { readSubagentSettings, updateAgentSettingsPatch } from "./settings.js";
 
-export function executionProfileScreen() {
-	const current = inspectExecutionProfile();
-	return {
-		kind: "actions" as const,
-		title: "Execution Profiles",
-		lines: [
-			`Current built-in mapping: ${current === "custom" ? "Custom or inherited" : executionProfileLabel(current)}`,
-			"Profiles change only built-in agent thinking defaults.",
-			"Models, timeouts, tools, transport, context, and explicit tool-call values are preserved.",
-		],
-		items: [
-			...EXECUTION_PROFILES.map((profile) => ({
-				id: profile,
-				label: executionProfileLabel(profile),
-				description: executionProfileDescription(profile),
-				action: "apply-execution-profile" as const,
-			})),
-			{ id: "back", label: "Back", action: "back" as const },
-		],
-		hint: "back" as const,
-	};
-}
-
-export async function applyExecutionProfileFromUi(
-	profileValue: string,
-	ctx: ExtensionCommandContext,
-	signal: AbortSignal,
-	isCurrent: () => boolean,
-) {
-	if (!EXECUTION_PROFILES.includes(profileValue as ExecutionProfile)) {
-		return { kind: "rejected" as const };
-	}
-	const profile = profileValue as ExecutionProfile;
-	const before = executionSettingsFingerprint();
-	const confirmed = await ctx.ui.confirm(
-		`Apply ${executionProfileLabel(profile)} profile?`,
-		[
-			executionProfileDescription(profile),
-			...executionProfilePreview(profile),
-			"Existing model, timeout, and tool overrides remain unchanged.",
-		].join("\n"),
-		{ signal },
-	);
-	if (signal.aborted || !isCurrent()) return { kind: "close" as const };
-	if (!confirmed) return { kind: "rejected" as const };
-	if (before !== executionSettingsFingerprint()) {
-		ctx.ui.notify("Agent execution settings changed while confirming; review again.", "warning");
-		return { kind: "rejected" as const };
-	}
-	try {
-		applyExecutionProfile(profile);
-		ctx.ui.notify(`Applied ${executionProfileLabel(profile)} profile.`, "info");
-		return { kind: "stay" as const };
-	} catch (error) {
-		ctx.ui.notify(`Execution profile was not saved: ${formatError(error)}`, "error");
-		return { kind: "rejected" as const };
-	}
-}
-
 export function executionAgentPickerScreen(agents: readonly AgentConfig[]) {
 	const configured = readSubagentSettings()?.agents ?? {};
 	return {
@@ -311,10 +243,6 @@ function hasTerminalControl(value: string): boolean {
 	});
 }
 
-function executionSettingsFingerprint(): string {
-	return JSON.stringify(readSubagentSettings()?.agents ?? {});
-}
-
 function formatError(error: unknown): string {
 	return safeTerminalText(error instanceof Error ? error.message : String(error));
 }