pi-subagents 0.45.1 → 0.46.0

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -30,6 +30,7 @@ import { drainOutstandingWork } from "../background/auto-drain.ts";
 const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = "PI_SUBAGENT_INHERIT_PROJECT_CONTEXT";
 const SUBAGENT_INHERIT_SKILLS_ENV = "PI_SUBAGENT_INHERIT_SKILLS";
 export const SUBAGENT_INTERCOM_SESSION_NAME_ENV = "PI_SUBAGENT_INTERCOM_SESSION_NAME";
+const STEERING_LEGACY_SETTLE_FALLBACK_MS = 1000;
 
 const STRUCTURED_OUTPUT_INSTRUCTIONS = [
 	"This subagent step has a strict structured output contract.",
@@ -330,7 +331,7 @@ function registerToolBudget(pi: ExtensionAPI, budget: ResolvedToolBudget | undef
 
 export function registerSteeringInbox(
 	pi: ExtensionAPI,
-	deps: { watch?: typeof fs.watch; nativeRealpath?: (filePath: string) => string } = {},
+	deps: { watch?: typeof fs.watch; nativeRealpath?: (filePath: string) => string; legacySettleFallbackMs?: number } = {},
 ): void {
 	const steerInbox = process.env[SUBAGENT_STEER_INBOX_ENV]?.trim();
 	if (!steerInbox) return;
@@ -343,11 +344,14 @@ export function registerSteeringInbox(
 	let disposed = false;
 	let agentRunning = false;
 	let inTurn = false;
+	let awaitingSettlement = false;
 	let flushing = false;
 	let started = false;
 	let canSteer = typeof sendUserMessage === "function";
 	let watcher: fs.FSWatcher | undefined;
 	let interval: NodeJS.Timeout | undefined;
+	let settleFallback: NodeJS.Timeout | undefined;
+	const legacySettleFallbackMs = deps.legacySettleFallbackMs ?? STEERING_LEGACY_SETTLE_FALLBACK_MS;
 	const acknowledge = (request: SteerRequest, state: "delivered" | "queued" | "failed", message: string, deliveryStatus?: SteerDeliveryStatus): void => {
 		if (!ackDir || !Number.isInteger(childIndex) || childIndex < 0) return;
 		writeSteerAckAt(steerAckPathFromDir(ackDir, request.id), {
@@ -375,7 +379,8 @@ export function registerSteeringInbox(
 					continue;
 				}
 				const requestedMode = request.mode ?? "steer";
-				const delivery = requestedMode === "follow_up" || (requestedMode === "auto" && inTurn) ? "followUp" as const : "steer" as const;
+				const autoCanUseIdle = requestedMode === "auto" && !agentRunning && !awaitingSettlement;
+				const delivery = requestedMode === "follow_up" || (requestedMode === "auto" && (inTurn || awaitingSettlement)) ? "followUp" as const : "steer" as const;
 				const pendingFollowUps = [...pending.values()].reduce((count, entries) => count + entries.filter((entry) => entry.deliveryStatus === "queued").length, 0);
 				if (delivery === "followUp" && queued.length + pendingFollowUps >= MAX_STEER_QUEUE_SIZE) {
 					acknowledge(request, "failed", `Follow-up queue is full (${MAX_STEER_QUEUE_SIZE} messages).`);
@@ -386,7 +391,7 @@ export function registerSteeringInbox(
 				entries.push({ request, deliveryStatus: delivery === "followUp" ? "queued" : "delivered" });
 				pending.set(formatted, entries);
 				try {
-					sendUserMessage(formatted, requestedMode === "auto" && !agentRunning ? undefined : { deliverAs: delivery });
+					sendUserMessage(formatted, autoCanUseIdle ? undefined : { deliverAs: delivery });
 				} catch (error) {
 					entries.pop();
 					if (entries.length === 0) pending.delete(formatted);
@@ -440,14 +445,71 @@ export function registerSteeringInbox(
 		flush();
 		return undefined;
 	};
+	const clearSettleFallback = (): void => {
+		if (!settleFallback) return;
+		clearTimeout(settleFallback);
+		settleFallback = undefined;
+	};
+	const markSettled = (): undefined => {
+		clearSettleFallback();
+		agentRunning = false;
+		inTurn = false;
+		awaitingSettlement = false;
+		return activate();
+	};
+	const armLegacySettleFallback = (): void => {
+		clearSettleFallback();
+		settleFallback = setTimeout(() => {
+			settleFallback = undefined;
+			if (disposed || !awaitingSettlement) return;
+			agentRunning = false;
+			inTurn = false;
+			awaitingSettlement = false;
+			activate();
+		}, legacySettleFallbackMs);
+		settleFallback.unref?.();
+	};
 
 	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: unknown, ctx?: unknown) => unknown) => void;
 	// Register input before the watcher so an accepted extension input cannot race request dispatch.
 	onRuntimeEvent("input", onInput);
 	onRuntimeEvent("session_start", () => start());
-	onRuntimeEvent("agent_start", () => { agentRunning = true; return activate(); });
-	onRuntimeEvent("agent_end", () => { agentRunning = false; inTurn = false; return activate(); });
+	onRuntimeEvent("agent_start", () => {
+		clearSettleFallback();
+		agentRunning = true;
+		awaitingSettlement = false;
+		return activate();
+	});
+	onRuntimeEvent("agent_end", (event) => {
+		inTurn = false;
+		if ((event as { willRetry?: unknown } | undefined)?.willRetry === true) {
+			clearSettleFallback();
+			agentRunning = true;
+			awaitingSettlement = true;
+			return activate();
+		}
+		agentRunning = true;
+		awaitingSettlement = true;
+		armLegacySettleFallback();
+		return activate();
+	});
+	onRuntimeEvent("agent_settled", markSettled);
+	onRuntimeEvent("session_compact", () => {
+		const unresolved = [...pending.values()].flat();
+		pending.clear();
+		for (const entry of unresolved) {
+			try {
+				writeSteerRequestToDir(steerInbox, { ...entry.request, mode: "follow_up" });
+			} catch (error) {
+				acknowledge(entry.request, "failed", `Could not retry steering after compaction: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		}
+		return activate();
+	});
 	onRuntimeEvent("turn_start", () => {
+		clearSettleFallback();
+		agentRunning = true;
+		awaitingSettlement = false;
 		inTurn = true;
 		const next = queued.findIndex((entry) => entry.ready);
 		if (next >= 0) {
@@ -466,7 +528,11 @@ export function registerSteeringInbox(
 	}
 	onRuntimeEvent("session_shutdown", () => {
 		for (const entry of queued) acknowledge(entry.request, "failed", "Run ended before queued follow-up delivery.", "queued");
+		for (const entries of pending.values()) {
+			for (const entry of entries) acknowledge(entry.request, "failed", "Run ended before Pi confirmed steering input delivery.");
+		}
 		disposed = true;
+		clearSettleFallback();
 		try { watcher?.close(); } catch {}
 		if (interval) clearInterval(interval);
 	});

package/src/shared/fork-context.ts

@@ -9,6 +9,7 @@ type SubagentExecutionContext = "fresh" | "fork";
 interface BranchSessionEntry {
 	type: string;
 	id?: string;
+	cwd?: string;
 	parentId?: string | null;
 	timestamp?: string;
 	message?: {
@@ -128,6 +129,18 @@ function readSessionEntries(sessionFile: string): BranchSessionEntry[] {
 	});
 }
 
+/** Keep Pi from restoring a forked session into the parent's cwd instead of the child launch cwd. */
+export function alignForkedSessionCwd(sessionFile: string, cwd: string): void {
+	const entries = readSessionEntries(sessionFile);
+	const header = entries[0];
+	if (header?.type !== "session") throw new Error(`Forked session ${sessionFile} does not start with a session header.`);
+	const resolvedCwd = path.resolve(cwd);
+	const effectiveCwd = fs.realpathSync.native(resolvedCwd);
+	if (header.cwd === effectiveCwd) return;
+	header.cwd = effectiveCwd;
+	fs.writeFileSync(sessionFile, `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`, "utf-8");
+}
+
 export function createForkContextResolver(
 	sessionManager: ForkableSessionManager,
 	requestedContext: unknown,

package/src/shared/prompt-resources.ts

@@ -0,0 +1,51 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseFrontmatter } from "../agents/frontmatter.ts";
+import { getAgentDir, getProjectConfigDir } from "./utils.ts";
+
+const PROMPT_REF_PATTERN = /^(package|user|project):([A-Za-z0-9][A-Za-z0-9._-]{0,127})$/;
+const PROMPT_VARIABLE_PATTERN = /\{\{(\w+)\}\}/g;
+
+type PromptVariable = string | number | boolean;
+
+export function getPromptDirectories(cwd: string) {
+	return {
+		package: path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "prompts"),
+		user: path.join(getAgentDir(), "prompts"),
+		project: path.join(getProjectConfigDir(cwd), "prompts"),
+	};
+}
+
+function promptVariables(vars: unknown): Record<string, PromptVariable> {
+	if (vars === undefined) return {};
+	if (!vars || typeof vars !== "object" || Array.isArray(vars)) throw new Error("prompts.render vars must be a plain object.");
+	const prototype = Object.getPrototypeOf(vars);
+	if (prototype !== null && prototype !== Object.prototype) throw new Error("prompts.render vars must be a plain object.");
+	for (const [name, value] of Object.entries(vars)) {
+		if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+			throw new Error(`prompts.render variable '${name}' must be a string, number, or boolean.`);
+		}
+	}
+	return vars as Record<string, PromptVariable>;
+}
+
+export function renderWorkflowPrompt(ref: string, vars: unknown, cwd: string): string {
+	const match = ref.match(PROMPT_REF_PATTERN);
+	if (!match) throw new Error("prompts.render ref must use package:<name>, user:<name>, or project:<name>.");
+	const scope = match[1] as keyof ReturnType<typeof getPromptDirectories>;
+	const name = match[2]!;
+	const filePath = path.join(getPromptDirectories(cwd)[scope], `${name}.md`);
+	let content: string;
+	try {
+		if (!fs.lstatSync(filePath).isFile()) throw new Error("not a regular file");
+		content = fs.readFileSync(filePath, "utf-8");
+	} catch (error) {
+		const detail = error instanceof Error ? error.message : String(error);
+		throw new Error(`Could not read prompt fragment '${ref}': ${detail}`);
+	}
+	const variables = promptVariables(vars);
+	return parseFrontmatter(content).body.trim().replace(PROMPT_VARIABLE_PATTERN, (placeholder, variable: string) => {
+		return Object.hasOwn(variables, variable) ? String(variables[variable]) : placeholder;
+	});
+}

package/src/shared/types.ts

@@ -969,6 +969,8 @@ export interface WaitCompletion {
 	mode?: string;
 	state?: string;
 	success?: boolean;
+	/** Versioned bounded output archive retained with the durable completion replay. */
+	archivePath?: string;
 	results?: WaitCompletionChild[];
 }
 
@@ -1045,6 +1047,7 @@ export interface Details {
 			operation: "run" | "status";
 			key: string;
 			state: "started" | "completed" | "failed" | "reused";
+			agent?: string;
 			runId?: string;
 			phase?: string;
 			label?: string;
@@ -1538,6 +1541,10 @@ export interface ForegroundChildControl {
 
 export interface ForegroundRunControl {
 	runId: string;
+	/** Workflow shell that owns this live foreground child, when applicable. */
+	parentWorkflowRunId?: string;
+	/** Stable workflow lane key for this live foreground child. */
+	workflowKey?: string;
 	/** Originating parent session; required for public fleet projection. */
 	sessionId?: string;
 	mode: SubagentRunMode;
@@ -1780,12 +1787,34 @@ export interface ScheduledRunsConfig {
 
 export type FleetViewPlacement = "aboveEditor" | "belowEditor";
 
+export const FLEET_KEYBINDING_ACTIONS = [
+	"close",
+	"scrollUp",
+	"scrollDown",
+	"selectUp",
+	"selectDown",
+	"selectFirst",
+	"selectLast",
+	"pageUp",
+	"pageDown",
+	"refresh",
+	"steer",
+	"inspect",
+	"stop",
+	"toggleTools",
+] as const;
+
+export type FleetKeybindingAction = typeof FLEET_KEYBINDING_ACTIONS[number];
+export type FleetKeybindingsConfig = Partial<Record<FleetKeybindingAction, string[]>>;
+
 export interface ExtensionConfig {
 	asyncByDefault?: boolean;
 	/** Show the Claude Code-style navigable fleet. Defaults to true. */
 	fleetView?: boolean;
 	/** Place the persistent FleetView above or below the editor. Defaults to belowEditor. */
 	fleetViewPlacement?: FleetViewPlacement;
+	/** Local keybindings for the full Fleet inspector. */
+	fleetKeybindings?: FleetKeybindingsConfig;
 	/** Show the under-editor async runs widget. Defaults to true, including when FleetView is enabled. */
 	asyncWidget?: boolean;
 	/** Tool description variant registered for the parent-facing subagent tool. Defaults to full. */
@@ -1922,7 +1951,7 @@ export const SLASH_SUBAGENT_CANCEL_EVENT = "subagent:slash:cancel";
 export const POLL_INTERVAL_MS = 250;
 export const MAX_WIDGET_JOBS = 4;
 export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
-export const SUBAGENT_ACTIONS = ["list", "get", "models", "children.list", "create", "update", "delete", "eject", "disable", "enable", "reset", "mission.create", "mission.list", "mission.show", "mission.update", "mission.attach-run", "mission.close", "worktree.discard", "refine", "refine.show", "refine.rollback", "inspector.open", "inspector.status", "inspector.close", "project.open", "project.status", "project.close", "status", "grant-spawn-budget", "interrupt", "resume", "steer", "stop", "append-step", "approve-checkpoint", "reject-checkpoint", "doctor", "watchdog.status", "watchdog.check", "watchdog.configure", "watchdog.recommend-model", "schedule.create", "schedule.list", "schedule.show", "schedule.history", "schedule.pause", "schedule.resume", "schedule.run", "schedule.run-due", "schedule.delete"] as const;
+export const SUBAGENT_ACTIONS = ["list", "get", "models", "children.list", "guide", "create", "update", "delete", "eject", "disable", "enable", "reset", "mission.create", "mission.list", "mission.show", "mission.update", "mission.resolve-decision", "mission.attach-run", "mission.close", "worktree.discard", "refine", "refine.show", "refine.rollback", "inspector.open", "inspector.status", "inspector.close", "project.open", "project.status", "project.close", "status", "grant-spawn-budget", "interrupt", "resume", "steer", "stop", "append-step", "approve-checkpoint", "reject-checkpoint", "doctor", "watchdog.status", "watchdog.check", "watchdog.configure", "watchdog.recommend-model", "schedule.create", "schedule.list", "schedule.show", "schedule.history", "schedule.pause", "schedule.resume", "schedule.run", "schedule.run-due", "schedule.delete"] as const;
 
 export const DEFAULT_FORK_PREAMBLE =
 	"You are a delegated subagent running from a fork of the parent session. " +

package/src/shared/utf8.ts

@@ -0,0 +1,11 @@
+export function decodeUtf8Tail(bytes: Buffer): string {
+	let start = 0;
+	while (start < bytes.length && (bytes[start]! & 0xc0) === 0x80) start += 1;
+	return bytes.subarray(start).toString("utf-8");
+}
+
+export function utf8Tail(value: string, maxBytes: number): { text: string; truncated: boolean } {
+	const bytes = Buffer.from(value, "utf-8");
+	if (bytes.length <= maxBytes) return { text: value, truncated: false };
+	return { text: decodeUtf8Tail(bytes.subarray(bytes.length - maxBytes)), truncated: true };
+}

package/src/slash/prompt-workflows.ts

@@ -1,10 +1,9 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { parseFrontmatter } from "../agents/frontmatter.ts";
 import type { SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
-import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
+import { getPromptDirectories } from "../shared/prompt-resources.ts";
 
 interface PromptWorkflow {
 	name: string;
@@ -32,21 +31,9 @@ const RESERVED_COMMAND_NAMES = new Set([
 	"subagents-models",
 ]);
 
-function packagePromptsDir(): string {
-	return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "prompts");
-}
-
-function promptDirs(cwd: string): string[] {
-	return [
-		packagePromptsDir(),
-		path.join(getAgentDir(), "prompts"),
-		path.join(getProjectConfigDir(cwd), "prompts"),
-	];
-}
-
 function readPromptFiles(cwd: string): string[] {
 	const files: string[] = [];
-	for (const dir of promptDirs(cwd)) {
+	for (const dir of Object.values(getPromptDirectories(cwd))) {
 		let entries: fs.Dirent[];
 		try {
 			entries = fs.readdirSync(dir, { withFileTypes: true });

package/src/slash/slash-commands.ts

@@ -22,6 +22,7 @@ import { SUBAGENT_FANOUT_CHILD_ENV } from "../runs/shared/pi-args.ts";
 import type { SlashSubagentResponse, SlashSubagentUpdate } from "./slash-bridge.ts";
 import { registerPromptWorkflowCommands } from "./prompt-workflows.ts";
 import { openSubagentsAdmin } from "./subagents-admin.ts";
+import { SUBAGENT_GUIDE_TOPICS } from "../extension/subagent-guide.ts";
 import { openSubagentFleet } from "../tui/fleet.ts";
 import {
 	applySlashUpdate,
@@ -40,6 +41,7 @@ import {
 	SLASH_SUBAGENT_UPDATE_EVENT,
 	DIRS,
 	type Details,
+	type FleetKeybindingsConfig,
 	type JsonSchemaObject,
 	type SingleResult,
 	type SubagentState,
@@ -628,6 +630,7 @@ function slashRunWorkflowScript(key: string, child: Record<string, unknown>): st
 export function registerSlashCommands(
 	pi: ExtensionAPI,
 	state: SubagentState,
+	options: { fleetKeybindings?: FleetKeybindingsConfig } = {},
 ): void {
 	let fleetOpen = false;
 	const showFleet = async (ctx: ExtensionContext) => {
@@ -642,7 +645,7 @@ export function registerSlashCommands(
 		}
 		fleetOpen = true;
 		try {
-			await openSubagentFleet(ctx, state, { asyncDirRoot: DIRS.async, resultsDir: DIRS.results });
+			await openSubagentFleet(ctx, state, { asyncDirRoot: DIRS.async, resultsDir: DIRS.results, fleetKeybindings: options.fleetKeybindings });
 		} finally {
 			fleetOpen = false;
 		}
@@ -698,6 +701,21 @@ export function registerSlashCommands(
 		},
 	});
 
+	pi.registerCommand("subagents-guide", {
+		description: "Show a packaged subagents guide topic",
+		getArgumentCompletions: (prefix) => prefix.includes(" ") ? null : SUBAGENT_GUIDE_TOPICS
+			.filter((topic) => topic.startsWith(prefix))
+			.map((topic) => ({ value: topic, label: topic })),
+		handler: async (args, ctx) => {
+			const topic = args.trim();
+			if (topic.includes(" ")) {
+				ctx.ui.notify("Usage: /subagents-guide [topic]", "error");
+				return;
+			}
+			await runSlashSubagent(pi, ctx, { action: "guide", ...(topic ? { topic } : {}) });
+		},
+	});
+
 	pi.registerCommand("subagents-refine", {
 		description: "Generate a bounded project-local refinement overlay for one subagent",
 		getArgumentCompletions: makeAgentCompletions(state),

package/src/tui/fleet-status.ts

@@ -144,6 +144,12 @@ function isStaleExtensionContextError(error: unknown): boolean {
 			|| error.message.includes("Extension context no longer active"));
 }
 
+function foregroundDescription(control: { parentWorkflowRunId?: string; workflowKey?: string }, description: string | undefined): string | undefined {
+	if (!control.parentWorkflowRunId) return description;
+	const workflow = `workflow child: ${control.parentWorkflowRunId}${control.workflowKey ? ` (${control.workflowKey})` : ""}`;
+	return description ? `${workflow} · ${description}` : workflow;
+}
+
 export function collectFleetStatusEntries(state: SubagentState): FleetStatusEntry[] {
 	const entries: FleetStatusEntry[] = [];
 	for (const control of state.foregroundControls.values()) {
@@ -154,7 +160,7 @@ export function collectFleetStatusEntries(state: SubagentState): FleetStatusEntr
 					key: `foreground-active:${control.runId}:${child.index}`,
 					agent: child.agent,
 					...(modelThinking ? { modelThinking } : {}),
-					description: child.description,
+					description: foregroundDescription(control, child.description),
 					startedAt: child.startedAt,
 					tokens: child.tokens ?? 0,
 					state: "running",
@@ -170,7 +176,7 @@ export function collectFleetStatusEntries(state: SubagentState): FleetStatusEntr
 			key: `foreground-active:${control.runId}:${control.currentIndex ?? 0}`,
 			agent: control.currentAgent ?? control.mode,
 			...(modelThinking ? { modelThinking } : {}),
-			description: control.description,
+			description: foregroundDescription(control, control.description),
 			startedAt: control.startedAt,
 			tokens: control.tokens ?? 0,
 			state: "running",