@narumitw/pi-subagents 1.0.2 → 2.0.1

package/src/rpc-transport.ts

@@ -5,6 +5,7 @@ import * as path from "node:path";
 import type { RpcSessionState } from "@earendil-works/pi-coding-agent";
 import { discoverAgents } from "./agents/discovery.js";
 import type { AgentConfig, SubagentSettings } from "./agents/types.js";
+import { formatPeerMessage } from "./child-peer-tools.js";
 import {
 	buildCurrentTurnPrompt,
 	type ParentRuntimeSnapshot,
@@ -16,10 +17,16 @@ import {
 	DEFAULT_MAX_STDERR_BYTES,
 	truncateUtf8,
 } from "./limits.js";
+import {
+	CHILD_PEER_TOOL_NAMES,
+	childPeerBridgePath,
+	type PeerTransportRuntime,
+	peerBridgeEnvironment,
+} from "./peer-transport.js";
 import { type PiInvocation, resolvePiInvocation } from "./pi-invocation.js";
 import { resolvePiPromptResources } from "./prompt-resources.js";
 import { JsonLineDecoder } from "./protocol.js";
-import type { ManagedAgent, TurnOutcome } from "./registry.js";
+import type { AgentMailboxMessage, ManagedAgent, TurnOutcome } from "./registry.js";
 import { finalizeTimedOutRpcTurn } from "./rpc-timeout-finalization.js";
 import {
 	boundedError,
@@ -197,6 +204,10 @@ export class RpcProtocolClient {
 		await this.request({ type: "prompt", message }, timeoutMs);
 	}
 
+	async steer(message: string, timeoutMs?: number): Promise<void> {
+		await this.request({ type: "steer", message }, timeoutMs);
+	}
+
 	async abort(): Promise<void> {
 		await this.request(
 			{ type: "abort" },
@@ -365,6 +376,7 @@ export interface RpcTransportOptions {
 	defaultTimeoutMs?: number;
 	abortGraceMs?: number;
 	timeoutFinalizationMs?: number;
+	peerRuntime?: PeerTransportRuntime;
 }
 
 interface RpcChildRecord {
@@ -694,6 +706,13 @@ export class RpcTransport implements SubagentTransport {
 		}
 	}
 
+	async deliverMessage(agent: ManagedAgent, message: AgentMailboxMessage): Promise<boolean> {
+		const child = this.children.get(agent.id);
+		if (!child) return false;
+		await child.client.steer(formatPeerMessage(message));
+		return true;
+	}
+
 	async release(agent: ManagedAgent): Promise<void> {
 		await this.releaseById(agent.id);
 	}
@@ -732,41 +751,48 @@ export class RpcTransport implements SubagentTransport {
 			cleanupRolePrompt(temporaryPrompt);
 			throw abortError("RPC subagent start aborted");
 		}
-		const client = this.createClient({
-			cwd: agent.cwd,
-			abortTimeoutMs: this.options.abortGraceMs ?? ABORT_GRACE_MS,
-			terminationGraceMs: this.options.abortGraceMs ?? ABORT_GRACE_MS,
-			args: buildRpcArgs(
-				agent,
-				agentConfig,
-				this.options.getParentRuntime(),
-				temporaryPrompt?.filePath,
-				resources.appendSystemPromptPaths,
-			),
-			env: {
-				PI_SUBAGENT_DEPTH: String(
-					(Number.parseInt(process.env.PI_SUBAGENT_DEPTH ?? "0", 10) || 0) + 1,
-				),
-				PI_SUBAGENT_RPC_PROTOCOL: PI_SUBAGENTS_RPC_PROTOCOL,
-			},
-		});
+		let client: RpcProtocolClient | undefined;
 		try {
+			const credentials = this.options.peerRuntime
+				? await this.options.peerRuntime.issueCredentials(
+						agent.id,
+						agent.currentTurnGeneration ?? agent.turnGeneration ?? 1,
+					)
+				: undefined;
+			if (signal.aborted) throw abortError("RPC subagent start aborted");
+			client = this.createClient({
+				cwd: agent.cwd,
+				abortTimeoutMs: this.options.abortGraceMs ?? ABORT_GRACE_MS,
+				terminationGraceMs: this.options.abortGraceMs ?? ABORT_GRACE_MS,
+				args: buildRpcArgs(
+					agent,
+					agentConfig,
+					this.options.getParentRuntime(),
+					temporaryPrompt?.filePath,
+					resources.appendSystemPromptPaths,
+					credentials !== undefined,
+				),
+				env: {
+					PI_SUBAGENT_DEPTH: String(
+						(Number.parseInt(process.env.PI_SUBAGENT_DEPTH ?? "0", 10) || 0) + 1,
+					),
+					PI_SUBAGENT_RPC_PROTOCOL: PI_SUBAGENTS_RPC_PROTOCOL,
+					...(credentials ? peerBridgeEnvironment(credentials) : {}),
+				},
+			});
 			const snapshot = await client.start(signal);
+			if (signal.aborted) throw abortError("RPC subagent start aborted");
 			const record: RpcChildRecord = {
 				client,
 				state: snapshot.state,
 				started: false,
 				temporaryPrompt,
 			};
-			if (signal.aborted) {
-				await client.stop();
-				cleanupRolePrompt(temporaryPrompt);
-				throw abortError("RPC subagent start aborted");
-			}
 			this.children.set(agent.id, record);
 			return record;
 		} catch (error) {
-			await client.stop().catch(() => undefined);
+			await client?.stop().catch(() => undefined);
+			this.options.peerRuntime?.revoke(agent.id);
 			cleanupRolePrompt(temporaryPrompt);
 			throw error;
 		}
@@ -776,6 +802,7 @@ export class RpcTransport implements SubagentTransport {
 		const child = this.children.get(agentId);
 		if (!child) return;
 		this.children.delete(agentId);
+		this.options.peerRuntime?.revoke(agentId);
 		try {
 			await child.client.abort().catch(() => undefined);
 			await child.client.stop();
@@ -799,8 +826,10 @@ export function buildRpcArgs(
 	parentRuntime: ParentRuntimeSnapshot,
 	rolePromptPath?: string,
 	appendSystemPromptPaths: readonly string[] = [],
+	peerBridge = false,
 ): string[] {
 	const args = ["--mode", "rpc", "--no-session", "--no-extensions"];
+	if (peerBridge) args.push("-e", childPeerBridgePath());
 	const model =
 		agentConfig.model ??
 		(parentRuntime.model ? `${parentRuntime.model.provider}/${parentRuntime.model.id}` : undefined);
@@ -816,7 +845,8 @@ export function buildRpcArgs(
 	if (agent.target?.trust.projectTrusted ?? false) args.push("--approve");
 	else args.push("--no-approve");
 	if (Array.isArray(agentConfig.tools)) {
-		if (agentConfig.tools.length > 0) args.push("--tools", agentConfig.tools.join(","));
+		const tools = [...agentConfig.tools, ...(peerBridge ? CHILD_PEER_TOOL_NAMES : [])];
+		if (tools.length > 0) args.push("--tools", [...new Set(tools)].join(","));
 		else args.push("--no-tools");
 	}
 	for (const promptPath of appendSystemPromptPaths) {

package/src/runner.ts

@@ -389,6 +389,12 @@ export interface ChildLaunchPolicy {
 	projectTrust?: boolean;
 	baseSystemPrompt?: string;
 	appendSystemPromptPaths?: string[];
+	/** Package-owned explicit child extensions loaded even when unrelated extensions are disabled. */
+	extensionPaths?: string[];
+	/** Package-owned tools added to the child allowlist without changing delegated execution tools. */
+	additionalTools?: string[];
+	/** Ephemeral child-process environment consumed and cleared by a package-owned bridge. */
+	env?: NodeJS.ProcessEnv;
 	/** Internal timeout recovery control; omitted means enabled. */
 	finalizeOnTimeout?: boolean;
 	/** Internal hard deadline for the summary attempt. */
@@ -560,10 +566,14 @@ export async function runSingleAgent(
 
 		const effectiveTools =
 			launchPolicy && Object.hasOwn(launchPolicy, "tools") ? launchPolicy.tools : agent.tools;
+		const selectedTools =
+			effectiveTools === undefined
+				? undefined
+				: [...new Set([...effectiveTools, ...(launchPolicy?.additionalTools ?? [])])];
 		const args = buildPiArgs({
 			model: agent.model,
 			thinkingLevel,
-			tools: effectiveTools,
+			tools: selectedTools,
 			disableExtensions: launchPolicy?.disableExtensions,
 			disableSkills: launchPolicy?.disableSkills,
 			disablePromptTemplates: launchPolicy?.disablePromptTemplates,
@@ -571,6 +581,7 @@ export async function runSingleAgent(
 			projectTrust: launchPolicy?.projectTrust,
 			baseSystemPromptPath: baseSystemPromptPath ?? undefined,
 			appendSystemPromptPaths: launchPolicy?.appendSystemPromptPaths,
+			extensionPaths: launchPolicy?.extensionPaths,
 			systemPromptPath: tmpPromptPath ?? undefined,
 			task,
 		});
@@ -623,6 +634,7 @@ export async function runSingleAgent(
 					stdio: ["ignore", "pipe", "pipe"],
 					env: {
 						...process.env,
+						...launchPolicy?.env,
 						PI_SUBAGENT_DEPTH: String(
 							(Number.parseInt(process.env.PI_SUBAGENT_DEPTH ?? "0", 10) || 0) + 1,
 						),

package/src/spawn-idempotency.ts

@@ -7,6 +7,7 @@ export const MAX_SPAWN_IDEMPOTENCY_KEY_LENGTH = 256;
 
 export interface CanonicalSpawnRequest {
 	agent: string;
+	taskName?: string;
 	task: string;
 	cwd: string;
 	agentScope: AgentScope;
@@ -29,6 +30,7 @@ export function hashSpawnRequest(request: CanonicalSpawnRequest): string {
 		.update(
 			JSON.stringify({
 				agent: request.agent,
+				...(request.taskName === undefined ? {} : { taskName: request.taskName }),
 				task: request.task,
 				cwd: request.cwd,
 				agentScope: request.agentScope,

package/src/stateful-agent-view.ts

@@ -24,12 +24,14 @@ export function formatStatefulAgentLine(agent: ManagedAgent, now = Date.now()):
 	const transport = agent.telemetry?.transport ? ` transport:${agent.telemetry.transport}` : "";
 	const phase = agent.telemetry?.phase ? ` phase:${agent.telemetry.phase}` : "";
 	const queued = agent.telemetry?.queuePosition ? ` queue:${agent.telemetry.queuePosition}` : "";
-	return `${indent}${sanitizeStatusLine(agent.id, 128)} ${sanitizeStatusLine(agent.agent, 128)} ${agent.state} ${elapsedSeconds}s${thinking}${timeoutText}${idleText}${turnsText}${toolsText}${transport}${phase}${queued} unread:${unread} [${actions}]${task}`;
+	return `${indent}${sanitizeStatusLine(agent.taskPath ?? agent.id, 256)} (${sanitizeStatusLine(agent.id, 128)}) ${sanitizeStatusLine(agent.agent, 128)} ${agent.state} ${elapsedSeconds}s${thinking}${timeoutText}${idleText}${turnsText}${toolsText}${transport}${phase}${queued} unread:${unread} [${actions}]${task}`;
 }
 
 export function summarizeStatefulAgent(agent: ManagedAgent) {
 	return {
 		id: agent.id,
+		taskName: agent.taskName,
+		taskPath: agent.taskPath,
 		agent: agent.agent,
 		parentId: agent.parentId,
 		rootId: agent.rootId,

package/src/stateful-guidance.ts

@@ -7,29 +7,29 @@ export function createSpawnPromptGuidelines(
 	const deliveryGuidance =
 		completionDelivery === "auto-resume"
 			? blockingEnabled
-				? "With subagent_spawn completion delivery set to auto-resume, prefer one subagent_spawn for broad asynchronous research or review that covers related branches even when the final answer depends on its result; do not choose blocking parallel fan-out merely to keep delegation in the same turn."
-				: "With subagent_spawn completion delivery set to auto-resume, prefer one subagent_spawn for broad asynchronous research or review that covers related branches even when the final answer depends on its result."
+				? "With subagent_spawn completion delivery set to auto-resume, prefer one subagent_spawn for broad asynchronous research or consequential independent review that covers related branches even when the final answer depends on its result; do not choose blocking parallel fan-out merely to keep delegation in the same turn."
+				: "With subagent_spawn completion delivery set to auto-resume, prefer one subagent_spawn for broad asynchronous research or consequential independent review that covers related branches even when the final answer depends on its result."
 			: blockingEnabled
-				? "With subagent_spawn completion delivery set to next-turn (the default), prefer one subagent_spawn for broad asynchronous research or review only when the current response does not depend on its result; use the blocking subagent when the final answer depends on the detached result."
+				? "With subagent_spawn completion delivery set to next-turn (the default), prefer one subagent_spawn for broad asynchronous research or consequential independent review only when the current response does not depend on its result; use the blocking subagent when the final answer depends on the detached result."
 				: "With subagent_spawn completion delivery set to next-turn (the default), use subagent_spawn only when the current response does not depend on its result; complete final-answer-dependent work directly because an idle root is not awakened.";
-	const noLocalWorkGuidance =
-		completionDelivery === "auto-resume"
-			? "After subagent_spawn returns, do useful non-overlapping local work immediately. If none remains, briefly tell the user what subagent_spawn launched and end the response; auto-resume will request a synthesis turn after completion."
-			: "After subagent_spawn returns, do useful non-overlapping local work immediately. If none remains, briefly tell the user what subagent_spawn launched and end the response only when the current response does not depend on its result; next-turn delivery will not wake an idle root.";
 	return [
-		"Do not use subagent_spawn for simple or critical-path work that the main agent can perform directly.",
+		"Do not use subagent_spawn for simple or critical-path work that the main agent can perform directly. The main agent retains overall planning, immediate critical-path work, integration, final verification, and the final answer.",
+		"Before one ordinary subagent_spawn, identify concrete useful non-overlapping main-agent work you can start immediately and a supported completion integration path. If none exists, perform the task directly instead of calling subagent_spawn.",
+		"Give subagent_spawn a concise unique taskName using lowercase letters, digits, and underscores so the retained agent has a stable canonical task path.",
 		"Set subagent_spawn thinkingLevel to the lowest sufficient thinking level for the delegated task: use off or minimal for extraction, formatting, or mechanical work; low for straightforward bounded work; medium for ordinary multi-step research or implementation; high for complex debugging, design, review, or cross-file analysis; xhigh for highly ambiguous, cross-system, or high-risk analysis; and max only for the hardest tasks when quality clearly outweighs latency and cost. Omit subagent_spawn thinkingLevel only to preserve the agent or child default.",
 		"Set subagent_spawn timeoutMs to the shortest realistic work deadline for the task difficulty; use idleTimeoutMs for stalled work and maxTurns or maxToolCalls to stop repeated work without progress. Split oversized tasks instead of extending budgets merely to compensate for broad scope. Omit these fields only to preserve the retained agent or configured defaults.",
 		deliveryGuidance,
-		"Use a single subagent_spawn only for a concrete bounded subtask that can run independently and has an isolation or specialization benefit such as independent review, bounded context/output, a distinct model/tool profile, or workspace isolation.",
+		"Keep ordinary review in the main agent with a review skill and deterministic checks; use subagent_spawn for detached review only when consequential independent verification has concrete parallel value.",
+		"Use a single subagent_spawn for a bounded implementation slice with clear ownership only when it can run beside the identified main-agent work.",
+		"Use a single subagent_spawn without concurrent main-agent work only for an explicit user-requested specialist model, tool profile, or isolation boundary.",
 		...(blockingEnabled
 			? [
 					"Use the blocking subagent instead of subagent_spawn when synchronous output is required before the main agent can continue and waiting is intentional; queued steering cannot be processed until that blocking call returns.",
 					"When subagent_spawn fits the completion-delivery policy, do not choose a blocking parallel subagent merely to keep delegation in the same turn.",
 				]
 			: []),
-		"Add another subagent_spawn only for truly independent work with safe workspace concurrency.",
-		noLocalWorkGuidance,
+		"Add another subagent_spawn only for truly independent work with safe workspace concurrency and disjoint write ownership; shared workspaces permit concurrent writes by default, so use workspaceMode worktree when repository isolation is required. The main agent still owns integration.",
+		"After subagent_spawn returns, immediately continue the identified local task; do not merely announce the spawn, wait, poll, or end the response while useful local work remains.",
 		'Consume and synthesize available subagent_spawn completion messages; use subagent_manage with action "interrupt" or "close" for agents that are no longer needed.',
 		'Completion from subagent_spawn is delivered automatically. Do not poll with subagent_inspect or subagent_mailbox action "read", repeatedly check progress, or duplicate the delegated work.',
 	];

package/src/stateful-safety.ts

@@ -3,54 +3,9 @@ import * as path from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { discoverAgents } from "./agents/discovery.js";
 import type { AgentScope, SubagentSettings } from "./agents/types.js";
-import type { AgentRegistry, ManagedAgent } from "./registry.js";
 import { safeTerminalLine } from "./safe-text.js";
 import { readSubagentSettings } from "./settings.js";
 
-export function assertNoSharedWriteConflict(
-	registry: AgentRegistry,
-	agentName: string,
-	cwd: string,
-	scope: AgentScope,
-	settings?: SubagentSettings,
-): void {
-	const agents = discoverAgents(cwd, scope, settings ?? readSubagentSettings()).agents;
-	const requested = agents.find((agent) => agent.name === agentName);
-	if (!isWriteCapable(requested?.tools)) return;
-	for (const active of registry.list()) {
-		if (
-			!isSameCwd(active.cwd, cwd) ||
-			(active.state !== "running" && active.state !== "starting")
-		) {
-			continue;
-		}
-		const activeConfig = agents.find((agent) => agent.name === active.agent);
-		if (isWriteCapable(activeConfig?.tools)) {
-			throw new Error(
-				`Write-capable subagent ${active.id} is already active in shared workspace ${cwd}. ` +
-					"Prefer one subagent_spawn covering combined asynchronous work. Use the blocking subagent parallel mode only when concurrent synchronous outputs justify making the main agent unavailable. Otherwise let the active agent finish or close it; set allowConcurrentWrites only when overlapping writes are knowingly safe, or use workspaceMode worktree when repository isolation is needed.",
-			);
-		}
-	}
-}
-
-export function assertFollowUpWriteAllowed(
-	registry: AgentRegistry,
-	agent: ManagedAgent,
-	allowConcurrentWrites: boolean,
-	isolatedWorkspace: boolean,
-	settings?: SubagentSettings,
-): void {
-	if (allowConcurrentWrites || isolatedWorkspace) return;
-	assertNoSharedWriteConflict(
-		registry,
-		agent.agent,
-		agent.cwd,
-		agent.agentScope ?? "user",
-		settings,
-	);
-}
-
 export function isWriteCapable(tools: string[] | undefined): boolean {
 	if (!tools) return true;
 	return tools.some((tool) => ["bash", "write", "edit"].includes(tool));

package/src/stateful-tool-params.ts

@@ -11,7 +11,10 @@ export const ManageParamsSchema = Type.Object(
 			description: "Interrupt active work or close an agent and release its resources.",
 		}),
 		agentId: Type.Optional(
-			Type.String({ minLength: 1, description: "Required for interrupt and close." }),
+			Type.String({
+				minLength: 1,
+				description: "Required agent ID or canonical task path for interrupt and close.",
+			}),
 		),
 		subtree: Type.Optional(
 			Type.Boolean({
@@ -28,7 +31,10 @@ export const MailboxParamsSchema = Type.Object(
 		action: StringEnum(MAILBOX_ACTIONS, {
 			description: "Use send for queue-only delivery or read to inspect unread mailbox messages.",
 		}),
-		agentId: Type.String({ minLength: 1, description: "Mailbox owner or message recipient." }),
+		agentId: Type.String({
+			minLength: 1,
+			description: "Mailbox owner or recipient agent ID or canonical task path.",
+		}),
 		message: Type.Optional(
 			Type.String({
 				minLength: 1,
@@ -36,7 +42,9 @@ export const MailboxParamsSchema = Type.Object(
 				description: "Message content required by send; sending does not start a turn.",
 			}),
 		),
-		senderId: Type.Optional(Type.String({ description: "Optional same-tree sender identity." })),
+		senderId: Type.Optional(
+			Type.String({ description: "Optional sender agent ID or canonical task path." }),
+		),
 		deduplicationKey: Type.Optional(
 			Type.String({ maxLength: 256, description: "Optional idempotency key for send." }),
 		),