@narumitw/pi-subagents 1.0.1 → 2.0.0

package/src/subagents.ts

@@ -21,11 +21,8 @@ import type {
 	DelegationCwdPolicy,
 	SubagentSettings,
 } from "./agents/types.js";
-import {
-	type AutomationRegistrationDependencies,
-	registerSubagentAutomation,
-} from "./automation-registration.js";
 import { cachedModuleLoader, throwIfAborted } from "./cached-module-loader.js";
+import { renderCompletionMessage, SUBAGENT_COMPLETION_MESSAGE_TYPE } from "./completion-render.js";
 import {
 	type ConfigRegistrationDependencies,
 	registerSubagentConfigCommand,
@@ -60,13 +57,13 @@ type BlockingExecutionModule = Pick<typeof import("./execution.js"), "executeSub
 export interface SubagentsDependencies {
 	loadBlockingExecution?: () => Promise<BlockingExecutionModule>;
 	loadStatefulTransport?: () => Promise<SubagentTransport>;
-	automation?: AutomationRegistrationDependencies;
 	config?: ConfigRegistrationDependencies;
 	consult?: ConsultRegistrationDependencies;
 	inspect?: InspectRegistrationDependencies;
 }
 
 export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies = {}) {
+	pi.registerMessageRenderer(SUBAGENT_COMPLETION_MESSAGE_TYPE, renderCompletionMessage);
 	const loadBlockingExecution = cachedModuleLoader(
 		dependencies.loadBlockingExecution ?? (() => import("./execution.js")),
 	);
@@ -78,9 +75,6 @@ export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies =
 	const refreshBlockingCatalog = blockingEnabled
 		? registerBlockingSubagent(pi, () => currentSettings, loadBlockingExecution)
 		: () => undefined;
-	if (blockingEnabled) {
-		registerSubagentAutomation(pi, { getSettings: () => currentSettings }, dependencies.automation);
-	}
 	let refreshStatefulCatalog: (catalog: string) => void = () => undefined;
 	let refreshConsultCatalog: (catalog: string) => void = () => undefined;
 
@@ -225,7 +219,11 @@ function registerBlockingSubagent(
 		].join(" ");
 	const promptGuidelines = () => [
 		"Use subagent only when delegation fits; the main agent should decide how many subagents to spawn from task shape instead of waiting for the user to specify a count.",
+		"The main agent retains overall planning, immediate critical-path work, integration, final verification, and the final answer.",
 		"Use no subagent for simple answers, quick targeted edits, latency-sensitive one-step work, tasks requiring frequent user back-and-forth, or critical-path work the main agent can perform directly.",
+		"One ordinary implementation worker should not replace work the main agent can perform directly; use a blocking single only when intentional synchronous isolation or a user-requested specialist justifies waiting.",
+		"Keep ordinary planning in the main agent, or use explicit workflow mode when a genuine dependency graph requires caller-authored orchestration.",
+		"Keep ordinary review in the main agent with a review skill and deterministic checks; reserve panel mode or custom verifier agents for consequential independent verification.",
 		"Use the blocking subagent tool only when delegated outputs are required before the main agent's next action and waiting is intentional; the main agent cannot process queued steering until the call returns.",
 		"Use a blocking subagent single, parallel, chain, workflow, panel, or fan-in call only when synchronous context or output isolation is worth making the main agent unavailable while it runs.",
 		`If a blocking parallel subagent call is genuinely required, keep tasks independent, stay within the configured max ${resolveBlockingMaxParallelTasks(getSettings())}, and avoid write-heavy implementation touching the same files or shared state.`,
@@ -310,7 +308,6 @@ function appendAgentCatalog(baseDescription: string, catalog: string): string {
 
 export { parsePositiveInteger } from "./execution/runtime-policy.js";
 export { buildPiArgs } from "./pi-args.js";
-export { formatTokens, formatUsageStats } from "./render.js";
 export {
 	DEFAULT_CONSULT_RESOURCE_POLICY,
 	DEFAULT_CONSULTATION_CWD_POLICY,
@@ -339,3 +336,4 @@ export {
 	updateDelegationWorkflowSetting,
 	updateStatefulLimitSetting,
 } from "./settings.js";
+export { formatTokens, formatUsageStats } from "./usage-format.js";

package/src/subprocess-transport.ts

@@ -1,5 +1,11 @@
 import { discoverAgents } from "./agents/discovery.js";
 import type { AgentConfig, SubagentSettings, SubagentThinkingLevel } from "./agents/types.js";
+import {
+	CHILD_PEER_TOOL_NAMES,
+	childPeerBridgePath,
+	type PeerTransportRuntime,
+	peerBridgeEnvironment,
+} from "./peer-transport.js";
 import { resolvePiPromptResources } from "./prompt-resources.js";
 import type { ManagedAgent, TurnOutcome } from "./registry.js";
 import { getResultFinalOutput, runSingleAgent, type SubagentDetails } from "./runner.js";
@@ -17,6 +23,7 @@ export function resolveStatefulSubprocessThinkingLevel(
 
 export interface SubprocessTransportOptions {
 	getSettings?: () => SubagentSettings | undefined;
+	peerRuntime?: PeerTransportRuntime;
 }
 
 export class SubprocessTransport implements SubagentTransport {
@@ -54,35 +61,49 @@ export class SubprocessTransport implements SubagentTransport {
 			projectAgentsDir: discovery.projectAgentsDir,
 			results,
 		});
-		const single = await runSingleAgent(
-			record.cwd,
-			discovery.agents,
-			record.agent,
-			boundedTask.text,
-			undefined,
-			undefined,
-			signal,
-			resolveStatefulSubprocessThinkingLevel(discovery.agents, record),
-			record.currentTimeoutMs ?? record.timeoutMs ?? resolveStatefulTurnTimeout(agent),
-			undefined,
-			makeDetails,
-			undefined,
-			{
-				projectTrust,
-				...(record.executionPlan ? { tools: record.executionPlan.effectiveTools } : {}),
-				appendSystemPromptPaths: promptResources?.appendSystemPromptPaths,
-				timeoutResultFormat: record.resultFormat,
-				turnLimits: {
-					idleTimeoutMs: record.currentIdleTimeoutMs ?? record.idleTimeoutMs,
-					maxTurns: record.currentMaxTurns ?? record.maxTurns,
-					maxToolCalls: record.currentMaxToolCalls ?? record.maxToolCalls,
+		const credentials = this.options.peerRuntime
+			? await this.options.peerRuntime.issueCredentials(
+					record.id,
+					record.currentTurnGeneration ?? record.turnGeneration ?? 1,
+				)
+			: undefined;
+		let single: Awaited<ReturnType<typeof runSingleAgent>>;
+		try {
+			single = await runSingleAgent(
+				record.cwd,
+				discovery.agents,
+				record.agent,
+				boundedTask.text,
+				undefined,
+				undefined,
+				signal,
+				resolveStatefulSubprocessThinkingLevel(discovery.agents, record),
+				record.currentTimeoutMs ?? record.timeoutMs ?? resolveStatefulTurnTimeout(agent),
+				undefined,
+				makeDetails,
+				undefined,
+				{
+					projectTrust,
+					...(record.executionPlan ? { tools: record.executionPlan.effectiveTools } : {}),
+					appendSystemPromptPaths: promptResources?.appendSystemPromptPaths,
+					extensionPaths: credentials ? [childPeerBridgePath()] : undefined,
+					additionalTools: credentials ? [...CHILD_PEER_TOOL_NAMES] : undefined,
+					env: credentials ? peerBridgeEnvironment(credentials) : undefined,
+					timeoutResultFormat: record.resultFormat,
+					turnLimits: {
+						idleTimeoutMs: record.currentIdleTimeoutMs ?? record.idleTimeoutMs,
+						maxTurns: record.currentMaxTurns ?? record.maxTurns,
+						maxToolCalls: record.currentMaxToolCalls ?? record.maxToolCalls,
+					},
+					resultFormat: record.resultFormat,
+					contract: record.contract,
+					executionPlan: record.executionPlan,
+					displayTask: task,
 				},
-				resultFormat: record.resultFormat,
-				contract: record.contract,
-				executionPlan: record.executionPlan,
-				displayTask: task,
-			},
-		);
+			);
+		} finally {
+			this.options.peerRuntime?.revoke(record.id);
+		}
 		const settledAt = Date.now();
 		const telemetry: TransportTelemetry = {
 			...starting,

package/src/task-path.ts

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+
+export const ROOT_TASK_PATH = "/root";
+export const MAX_TASK_NAME_LENGTH = 128;
+export const MAX_TASK_PATH_LENGTH = 2_048;
+
+const TASK_NAME_PATTERN = /^[a-z0-9_]+$/u;
+
+export function validateTaskName(value: string): string {
+	if (!value) throw new Error("Subagent taskName must not be empty");
+	if (value === "root" || value === "." || value === "..") {
+		throw new Error(`Subagent taskName ${JSON.stringify(value)} is reserved`);
+	}
+	if (value.length > MAX_TASK_NAME_LENGTH) {
+		throw new Error(`Subagent taskName cannot exceed ${MAX_TASK_NAME_LENGTH} characters`);
+	}
+	if (value.includes("/")) throw new Error("Subagent taskName must not contain `/`");
+	if (!TASK_NAME_PATTERN.test(value)) {
+		throw new Error(
+			"Subagent taskName must use only lowercase ASCII letters, digits, and underscores",
+		);
+	}
+	return value;
+}
+
+export function validateTaskPath(value: string): string {
+	if (!value.startsWith(`${ROOT_TASK_PATH}/`) && value !== ROOT_TASK_PATH) {
+		throw new Error("Canonical subagent task paths must start with `/root`");
+	}
+	if (value.length > MAX_TASK_PATH_LENGTH) {
+		throw new Error(
+			`Canonical subagent task paths cannot exceed ${MAX_TASK_PATH_LENGTH} characters`,
+		);
+	}
+	if (value.endsWith("/") || value.includes("//")) {
+		throw new Error("Canonical subagent task paths must not contain empty segments");
+	}
+	for (const segment of value.slice(ROOT_TASK_PATH.length + 1).split("/")) {
+		if (segment) validateTaskName(segment);
+	}
+	return value;
+}
+
+export function joinTaskPath(parentPath: string, taskName: string): string {
+	const parent = validateTaskPath(parentPath);
+	const name = validateTaskName(taskName);
+	return validateTaskPath(`${parent}/${name}`);
+}
+
+export function resolveTaskPath(senderPath: string, reference: string): string {
+	if (!reference) throw new Error("Subagent task path reference must not be empty");
+	if (reference.startsWith("/")) return validateTaskPath(reference);
+	const sender = validateTaskPath(senderPath);
+	if (reference.endsWith("/")) {
+		throw new Error("Relative subagent task paths must not end with `/`");
+	}
+	let path = sender;
+	for (const segment of reference.split("/")) path = joinTaskPath(path, segment);
+	return path;
+}
+
+export function deriveTaskName(agentId: string): string {
+	const digest = createHash("sha256").update(agentId).digest("hex").slice(0, 32);
+	return `agent_${digest}`;
+}

package/src/transport-ui.ts

@@ -148,12 +148,6 @@ export function responsivenessSetupScreen(runtime: TransportUiRuntime) {
 				description: "Choose separately whether an idle root resumes for synthesis",
 				to: "settings" as const,
 			},
-			{
-				id: "thinking",
-				label: "Thinking profiles",
-				description: "Preview explicit Fast, Balanced, or Deep per-agent defaults",
-				to: "execution-profiles" as const,
-			},
 			{ id: "back", label: "Back", action: "back" as const },
 		],
 		hint: "back" as const,

package/src/transport.ts

@@ -1,4 +1,4 @@
-import type { ManagedAgent, TurnOutcome } from "./registry.js";
+import type { AgentMailboxMessage, ManagedAgent, TurnOutcome } from "./registry.js";
 import type { TransportProgressCallback } from "./transport-types.js";
 
 export interface SubagentTransport {
@@ -9,6 +9,7 @@ export interface SubagentTransport {
 		signal: AbortSignal,
 		onProgress?: TransportProgressCallback,
 	): Promise<TurnOutcome>;
+	deliverMessage?(agent: ManagedAgent, message: AgentMailboxMessage): Promise<boolean>;
 	release?(agent: ManagedAgent): Promise<void>;
 	shutdown?(): Promise<void>;
 }

package/src/usage-format.ts

@@ -0,0 +1,42 @@
+import type { SubagentThinkingLevel } from "./agents/types.js";
+import { safeLine } from "./render-common.js";
+
+export function formatTokens(count: number): string {
+	if (count < 1000) return count.toString();
+	if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+	if (count < 1000000) return `${Math.round(count / 1000)}k`;
+	return `${(count / 1000000).toFixed(1)}M`;
+}
+
+export function formatUsageStats(
+	usage: {
+		input: number;
+		output: number;
+		cacheRead: number;
+		cacheWrite: number;
+		cost: number;
+		contextTokens?: number;
+		turns?: number;
+	},
+	model?: string,
+	thinkingLevel?: SubagentThinkingLevel,
+	actualProvider?: string,
+	actualModel?: string,
+): string {
+	const parts: string[] = [];
+	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+	if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
+	if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
+	if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
+	if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
+	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+	if (usage.contextTokens && usage.contextTokens > 0)
+		parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
+	const safeProvider = actualProvider ? safeLine(actualProvider, "", 256) : undefined;
+	const safeModel = actualModel ? safeLine(actualModel, "", 256) : undefined;
+	const actual =
+		safeProvider && safeModel ? `${safeProvider}/${safeModel}` : (safeModel ?? safeProvider);
+	if (actual ?? model) parts.push(actual ?? safeLine(model, "", 256));
+	if (thinkingLevel) parts.push(`requested-thinking:${safeLine(thinkingLevel, "", 128)}`);
+	return parts.join(" ");
+}

package/src/workflow-ui.ts

@@ -46,15 +46,15 @@ function workflowEffects(current: DelegationWorkflow, next: DelegationWorkflow):
 	if (blockingEnabled(current) !== blockingEnabled(next)) {
 		effects.push(
 			blockingEnabled(next)
-				? "Add blocking `subagent`, explicit `subagent_auto`, and read-only `subagent_consult`"
-				: "Remove blocking `subagent`, explicit `subagent_auto`, and read-only `subagent_consult`",
+				? "Add blocking `subagent` and read-only `subagent_consult`"
+				: "Remove blocking `subagent` and read-only `subagent_consult`",
 		);
 	}
 	if (asyncEnabled(current) !== asyncEnabled(next)) {
 		effects.push(
 			asyncEnabled(next)
-				? "Add reusable async lifecycle tools"
-				: "Remove reusable async lifecycle tools",
+				? "Add async `subagent_spawn`, `subagent_send`, `subagent_manage`, and `subagent_mailbox`"
+				: "Remove async `subagent_spawn`, `subagent_send`, `subagent_manage`, and `subagent_mailbox`",
 		);
 	}
 	return effects;