@selesai/code 0.13.39 → 0.14.0

package/dist/extensions/pi-subagents/src/inspectors/{herdr/session-roots-codec.ts → session-roots-codec.ts}

@@ -19,24 +19,13 @@ function parseStringArray(value: unknown): string[] | undefined {
 	return value;
 }
 
-/**
- * Decodes a `--session-roots` argument produced by {@link encodeSessionRoots}.
- * Falls back to parsing the value as raw JSON so any externally-launched
- * inspector runner (a cached copy, or a manual invocation) that still passes
- * the legacy unencoded form keeps working.
- */
+/** Decodes a `--session-roots` argument produced by {@link encodeSessionRoots}. */
 export function decodeSessionRoots(raw: string): string[] {
 	try {
 		const decoded = parseStringArray(JSON.parse(Buffer.from(raw, "base64").toString("utf-8")));
 		if (decoded) return decoded;
 	} catch {
-		// fall through to legacy raw-JSON parsing below
-	}
-	try {
-		const parsed = parseStringArray(JSON.parse(raw));
-		if (parsed) return parsed;
-	} catch {
-		// fall through to the shared error below
+		// Report one stable validation error below.
 	}
-	throw new Error("--session-roots must be a base64-encoded or raw JSON array of strings.");
-}
+	throw new Error("--session-roots must be a base64-encoded JSON array of strings.");
+}

package/dist/extensions/pi-subagents/src/inspectors/{herdr/shell-command.ts → shell-command.ts}

@@ -13,4 +13,4 @@ export function formatShellCommand(exe: string, args: readonly string[], platfor
 	// Nushell treats a leading quoted token as a string, so use a bare invoker for paths that need quoting.
 	const invocation = isBareExecutable(exe) ? exe : `sh -c 'exec "$0" "$@"' ${shellQuote(exe, platform)}`;
 	return [invocation, ...quotedArgs].join(" ");
-}
+}

package/dist/extensions/pi-subagents/src/inspectors/types.ts

@@ -0,0 +1,51 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Details } from "../shared/types.ts";
+
+export const INSPECTOR_ACTIONS = ["inspector.open", "inspector.command", "inspector.status", "inspector.close"] as const;
+export type InspectorAction = typeof INSPECTOR_ACTIONS[number];
+
+export interface InspectorParams {
+	id?: string;
+	runId?: string;
+	dir?: string;
+	index?: number;
+	focus?: boolean;
+}
+
+export interface InspectorTarget {
+	runId: string;
+	asyncDir: string;
+	index?: number;
+	status: {
+		cwd?: string;
+		state: string;
+		steps?: unknown[];
+	};
+}
+
+export interface InspectorContext {
+	cwd: string;
+	signal?: AbortSignal;
+	env: NodeJS.ProcessEnv;
+	now?: () => Date;
+	target: InspectorTarget;
+}
+
+export interface InspectorLaunch {
+	executable: string;
+	argv: string[];
+	displayCommand: string;
+	mission?: { id: string; path: string };
+	allowSteer: boolean;
+	allowStop: boolean;
+	sessionRoots: string[];
+}
+
+export interface InspectorPlugin {
+	readonly name: string;
+	available(context: InspectorContext): Promise<boolean> | boolean;
+	owns(context: InspectorContext): boolean;
+	open(context: InspectorContext, launch: InspectorLaunch, params: InspectorParams): Promise<AgentToolResult<Details>>;
+	status?(context: InspectorContext): Promise<AgentToolResult<Details>>;
+	close?(context: InspectorContext): Promise<AgentToolResult<Details>>;
+}

package/dist/extensions/pi-subagents/src/integrations/herdr-status.ts

@@ -5,6 +5,7 @@ import {
 } from "../shared/types.ts";
 import { previewDisplayText, sanitizeDisplayText } from "../shared/display-text.ts";
 
+export const HERDR_FOREGROUND_CONTROL_CHANGED_EVENT = "pi-subagents:herdr:foreground-control-changed";
 const DEFAULT_SOURCE = "pi-subagents:herdr";
 const DEFAULT_TTL_MS = 120_000;
 const DEFAULT_REFRESH_MS = 45_000;
@@ -29,10 +30,11 @@ export interface HerdrStatusRun {
 	id: string;
 	agent?: string;
 	agents?: string[];
+	/** A workflow owns busy state but is not itself a child agent. */
+	coordinator?: true;
 	/** Explicit launch/workflow label only; raw prompts never enter pane metadata. */
 	taskLabel?: string;
 	needsAttention?: boolean;
-	attentionLabel?: string;
 }
 
 export interface HerdrStatusBridgeOptions {
@@ -100,10 +102,17 @@ function workflowTaskLabel(data: Record<string, unknown>): string | undefined {
 function startedRun(data: unknown): HerdrStatusRun | undefined {
 	if (!isRecord(data) || typeof data.id !== "string" || !data.id) return undefined;
 	const taskLabel = workflowTaskLabel(data);
+	// The workflow coordinator itself is not a running leaf: it starts with its
+	// own `agent: "workflow"` identity, but its actual leaves each publish their
+	// own start event separately. Counting the coordinator here would double it.
+	const isWorkflowCoordinator = data.mode === "workflow";
 	return {
 		id: data.id,
-		...(typeof data.agent === "string" ? { agent: data.agent } : {}),
-		...(Array.isArray(data.agents) && data.agents.every((agent) => typeof agent === "string") ? { agents: data.agents as string[] } : {}),
+		...(isWorkflowCoordinator ? { coordinator: true as const } : {}),
+		...(!isWorkflowCoordinator && typeof data.agent === "string" ? { agent: data.agent } : {}),
+		...(isWorkflowCoordinator
+			? { agents: [] }
+			: Array.isArray(data.agents) && data.agents.every((agent) => typeof agent === "string") ? { agents: data.agents as string[] } : {}),
 		...(taskLabel ? { taskLabel } : {}),
 	};
 }
@@ -114,15 +123,10 @@ function completedRunId(data: unknown): string | undefined {
 	return typeof id === "string" && id.length > 0 ? id : undefined;
 }
 
-function attentionNotice(data: unknown): { runId: string; label: string } | undefined {
+function attentionRunId(data: unknown): string | undefined {
 	if (!isRecord(data) || data.source !== "async" || !isRecord(data.event)) return undefined;
 	if (data.event.type !== "needs_attention" || typeof data.event.runId !== "string" || !data.event.runId) return undefined;
-	const label = typeof data.noticeText === "string" && data.noticeText
-		? data.noticeText
-		: typeof data.event.message === "string" && data.event.message
-			? data.event.message
-			: "subagent needs attention";
-	return { runId: data.event.runId, label };
+	return data.event.runId;
 }
 
 export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): HerdrStatusBridge {
@@ -134,15 +138,15 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
 	const refreshMs = options.refreshMs ?? DEFAULT_REFRESH_MS;
 	const timers = options.timers ?? { setInterval, clearInterval };
 	const runs = new Map<string, HerdrStatusRun>();
-	const attentionLabels = new Map<string, string>();
+	// Child attention is addressed to the parent agent, so it only adds ⚠ to the
+	// metadata label and never raises Herdr's human-blocked state.
+	const attentionRuns = new Set<string>();
 	const acknowledgedAttention = new Set<string>();
 	const subscriptions: Array<() => void> = [];
 	let rootSession = false;
 	let published = false;
 	let busyRaised = false;
 	let busyLabel: string | undefined;
-	let blockedRaised = false;
-	let blockedLabel: string | undefined;
 	let disposed = false;
 	let pendingReport: readonly string[] | undefined;
 	let draining = false;
@@ -150,7 +154,10 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
 	let refreshTimer: ReturnType<typeof setInterval> | undefined;
 
 	const activeAgentNames = (): string[] => [...new Set([...runs.values()].flatMap((run) => run.agents?.length ? run.agents : run.agent ? [run.agent] : []))];
-	const activeSubagentCount = (): number => [...runs.values()].reduce((total, run) => total + Math.max(1, run.agents?.length ?? (run.agent ? 1 : 0)), 0);
+	// Preserve the minimum count for ordinary runs with incomplete status;
+	// only an empty workflow coordinator contributes zero child agents.
+	const activeSubagentCount = (): number => [...runs.values()].reduce((total, run) =>
+		total + (run.coordinator && !run.agents?.length ? 0 : Math.max(1, run.agents?.length ?? (run.agent ? 1 : 0))), 0);
 	const activeTaskLabel = (): string | undefined => [...runs.values()].reverse().find((run) => run.taskLabel)?.taskLabel;
 
 	const label = (includeAttention = false): string => {
@@ -163,7 +170,7 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
 		const paneText = panes > 0 ? ` · ${panes} pane${panes === 1 ? "" : "s"}` : "";
 		const task = activeTaskLabel();
 		const taskText = task ? ` · ${task}` : "";
-		const attention = includeAttention && attentionLabels.size > 0 ? " ⚠" : "";
+		const attention = includeAttention && attentionRuns.size > 0 ? " ⚠" : "";
 		return `⏳ ${activeCount} subagent${activeCount === 1 ? "" : "s"}${who}${paneText}${taskText}${attention}`;
 	};
 
@@ -173,7 +180,7 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
 		const activeCount = activeSubagentCount();
 		const task = boundedTaskLabel(activeTaskLabel(), MAX_TITLE_TASK_CHARS);
 		const target = task ?? (activeCount === 1 && agentNames.length === 1 ? agentNames[0]! : String(activeCount));
-		return `⏳${target}${attentionLabels.size > 0 ? "⚠" : ""}`;
+		return `⏳${target}${attentionRuns.size > 0 ? "⚠" : ""}`;
 	};
 
 	const enqueue = (args: readonly string[]): void => {
@@ -256,44 +263,22 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
 		}
 	};
 
-	const syncBlocked = (): void => {
-		if (!enabled || !rootSession || disposed) return;
-		const nextLabel = [...attentionLabels.values()].at(-1);
-		if (nextLabel !== undefined) {
-			if (blockedRaised && blockedLabel === nextLabel) return;
-			// Herdr's sibling overlay contract is counted. Lower before changing
-			// the active label so this bridge continues to own exactly one count.
-			if (blockedRaised) options.events.emit("herdr:blocked", { active: false });
-			blockedRaised = true;
-			blockedLabel = nextLabel;
-			options.events.emit("herdr:blocked", { active: true, label: nextLabel });
-			return;
-		}
-		if (blockedRaised) {
-			blockedRaised = false;
-			blockedLabel = undefined;
-			options.events.emit("herdr:blocked", { active: false });
-		}
-	};
-
 	const clearAttention = (): void => {
-		attentionLabels.clear();
-		syncBlocked();
+		attentionRuns.clear();
 		publish();
 	};
 
-	const raiseAttention = (runId: string, labelText: string): void => {
-		if (!rootSession || attentionLabels.has(runId)) return;
+	const raiseAttention = (runId: string): void => {
+		if (!rootSession || attentionRuns.has(runId)) return;
 		acknowledgedAttention.delete(runId);
-		attentionLabels.set(runId, labelText);
-		syncBlocked();
+		attentionRuns.add(runId);
 		publish();
 	};
 
 	const replaceRuns = (nextRuns: Iterable<HerdrStatusRun>): void => {
-		const nextAttention = new Map<string, string>();
 		const activeIds = new Set<string>();
 		runs.clear();
+		attentionRuns.clear();
 		for (const run of nextRuns) {
 			if (!run || typeof run.id !== "string" || !run.id) continue;
 			activeIds.add(run.id);
@@ -303,17 +288,14 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
 			if (!run.needsAttention) {
 				acknowledgedAttention.delete(run.id);
 			} else if (!acknowledgedAttention.has(run.id)) {
-				nextAttention.set(run.id, run.attentionLabel || attentionLabels.get(run.id) || "subagent needs attention");
+				attentionRuns.add(run.id);
 			}
 		}
 		for (const id of acknowledgedAttention) {
 			if (!activeIds.has(id)) acknowledgedAttention.delete(id);
 		}
-		attentionLabels.clear();
-		for (const [id, labelText] of nextAttention) attentionLabels.set(id, labelText);
 		syncBusy();
 		syncRefreshTimer();
-		syncBlocked();
 		publish();
 	};
 
@@ -336,6 +318,9 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
 	};
 
 	if (enabled) {
+		subscribe(HERDR_FOREGROUND_CONTROL_CHANGED_EVENT, () => {
+			if (rootSession && options.getRuns) refresh();
+		});
 		subscribe(SUBAGENT_ASYNC_STARTED_EVENT, (data) => {
 			if (!rootSession) return;
 			const run = startedRun(data);
@@ -351,22 +336,22 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
 			const id = completedRunId(data);
 			if (!id || !runs.delete(id)) return;
 			acknowledgedAttention.delete(id);
-			if (attentionLabels.delete(id)) syncBlocked();
+			attentionRuns.delete(id);
 			syncBusy();
 			syncRefreshTimer();
 			publish();
 		});
 		subscribe(SUBAGENT_CONTROL_EVENT, (data) => {
 			if (!rootSession) return;
-			const notice = attentionNotice(data);
-			if (!notice || !runs.has(notice.runId)) return;
-			raiseAttention(notice.runId, notice.label);
+			const runId = attentionRunId(data);
+			if (!runId || !runs.has(runId)) return;
+			raiseAttention(runId);
 		});
 	}
 
 	return {
 		agentStarted() {
-			for (const id of attentionLabels.keys()) acknowledgedAttention.add(id);
+			for (const id of attentionRuns) acknowledgedAttention.add(id);
 			clearAttention();
 		},
 		sessionStarted({ hasUI, runs: restoredRuns }) {
@@ -393,4 +378,4 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
 			disposed = true;
 		},
 	};
-}
+}

package/dist/extensions/pi-subagents/src/integrations/pi-web-session-liveness.ts

@@ -34,11 +34,17 @@ function resolveRegistry(): PiWebSessionLivenessRegistry | null {
 	return registry as PiWebSessionLivenessRegistry;
 }
 
-export function retainLiveForegroundNestedRoute(state: Pick<SubagentState, "retainedForegroundNestedRoutes">, route: NestedRouteInfo): boolean {
+export function retainLiveForegroundNestedRoute(state: Pick<SubagentState, "retainedForegroundNestedRoutes" | "retainedForegroundNestedChildren"> & Partial<Pick<SubagentState, "currentSessionId" | "foregroundControls">>, route: NestedRouteInfo): boolean {
 	const nested = projectNestedEvents(route);
 	if (!hasLiveNestedDescendants(nested.children)) return false;
 	state.retainedForegroundNestedRoutes ??= new Map();
 	state.retainedForegroundNestedRoutes.set(route.rootRunId, route);
+	if (state.currentSessionId) {
+		state.retainedForegroundNestedChildren ??= new Map();
+		const owner = state.foregroundControls?.get(route.rootRunId);
+		const workflowId = owner?.parentWorkflowRunId ?? (owner?.mode === "workflow" ? owner.runId : undefined);
+		state.retainedForegroundNestedChildren.set(route.rootRunId, { sessionId: state.currentSessionId, ...(workflowId ? { workflowId } : {}), children: nested.children });
+	}
 	return true;
 }
 

package/dist/extensions/pi-subagents/src/intercom/intercom-bridge.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentConfig } from "../agents/agents.ts";
+import { agentDefinitionDigest } from "../shared/launch-contract.ts";
 import type { ExtensionConfig, IntercomBridgeConfig, IntercomBridgeMode } from "../shared/types.ts";
 import { getAgentDir } from "../shared/utils.ts";
 
@@ -18,9 +19,13 @@ function defaultSubagentConfigDir(agentDir = defaultAgentDir()): string {
 const DEFAULT_INTERCOM_TARGET_PREFIX = "subagent-chat";
 export const PI_INTERCOM_SESSION_ID_ENV = "PI_INTERCOM_SESSION_ID";
 export const INTERCOM_BRIDGE_MARKER = "Intercom orchestration channel:";
+const ORCHESTRATOR_TARGET_PLACEHOLDER = "{orchestratorTarget}";
+// The default template must stay session-independent: the child reads the
+// supervisor target from its runtime config, and a prompt that names the
+// parent session would make the launch digest vary per session (#2127).
 const DEFAULT_INTERCOM_BRIDGE_TEMPLATE = `The inherited thread is reference-only. Do not continue that conversation or send questions, status updates, or completion handoffs to the supervisor in normal assistant text.
 
-Use contact_supervisor first. It resolves the supervisor session "{orchestratorTarget}" and run metadata automatically.
+Use contact_supervisor first. It resolves the supervisor session and run metadata automatically.
 - Need a decision, blocked, approval, or product/API/scope ambiguity: contact_supervisor({ reason: "need_decision", message: "<question>" })
 - Need structured supervisor input rather than a freeform reply: contact_supervisor({ reason: "interview_request", message: "<what input is needed>", interview: { title: "...", questions: [] } })
 - After contact_supervisor with reason "need_decision" or "interview_request", stay alive and continue only after the reply arrives. Do not finish your final response with a choose-one question.
@@ -36,6 +41,32 @@ export interface IntercomBridgeState {
 	orchestratorTarget?: string;
 	extensionDir: string;
 	instruction: string;
+	/** True when the instruction template names the supervisor session, which ties the child prompt to the parent session. */
+	interpolatesOrchestratorTarget: boolean;
+}
+
+export type IntercomBridgeConfigValidation =
+	| { ok: true; value: IntercomBridgeConfig }
+	| { ok: false; error: string };
+
+/** Validates untrusted bridge config from descriptors or delegation requests; `label` prefixes each error. */
+export function validateIntercomBridgeConfig({ value, label }: { value: unknown; label: string }): IntercomBridgeConfigValidation {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return { ok: false, error: `${label} must be an object.` };
+	const bridge = value as Record<string, unknown>;
+	for (const field of Object.keys(bridge)) {
+		if (field !== "mode" && field !== "instructionFile" && field !== "resultDelivery") return { ok: false, error: `${label}.${field} is not supported.` };
+	}
+	if (bridge.mode !== undefined && bridge.mode !== "off" && bridge.mode !== "fork-only" && bridge.mode !== "always") return { ok: false, error: `${label}.mode is invalid.` };
+	if (bridge.instructionFile !== undefined && typeof bridge.instructionFile !== "string") return { ok: false, error: `${label}.instructionFile must be a string.` };
+	if (bridge.resultDelivery !== undefined && typeof bridge.resultDelivery !== "boolean") return { ok: false, error: `${label}.resultDelivery must be a boolean.` };
+	return {
+		ok: true,
+		value: {
+			...(bridge.mode !== undefined ? { mode: bridge.mode as IntercomBridgeMode } : {}),
+			...(bridge.instructionFile !== undefined ? { instructionFile: bridge.instructionFile as string } : {}),
+			...(bridge.resultDelivery !== undefined ? { resultDelivery: bridge.resultDelivery as boolean } : {}),
+		},
+	};
 }
 
 export interface IntercomBridgeDiagnostic {
@@ -59,6 +90,8 @@ interface ResolveIntercomBridgeInput {
 	agentDir?: string;
 }
 
+// Inside a child, callers pass the child's intercom route instead of its session
+// name: the name is a readable label and need not be unique.
 export function resolveIntercomSessionTarget(sessionName: string | undefined, sessionId: string, intercomSessionId = process.env[PI_INTERCOM_SESSION_ID_ENV]): string {
 	const trimmedName = sessionName?.trim();
 	if (trimmedName) return trimmedName;
@@ -114,7 +147,7 @@ function resolveInstructionTemplate(instructionFile: string, settingsDir: string
 }
 
 function buildIntercomBridgeInstruction(orchestratorTarget: string, template: string): string {
-	const instruction = template.replaceAll("{orchestratorTarget}", orchestratorTarget).trim();
+	const instruction = template.replaceAll(ORCHESTRATOR_TARGET_PLACEHOLDER, orchestratorTarget).trim();
 	if (instruction.startsWith(INTERCOM_BRIDGE_MARKER)) return instruction;
 	return `${INTERCOM_BRIDGE_MARKER}\n${instruction}`;
 }
@@ -149,24 +182,34 @@ export function resolveIntercomBridge(input: ResolveIntercomBridgeInput): Interc
 	const orchestratorTarget = input.orchestratorTarget?.trim();
 	const agentDir = path.resolve(input.agentDir ?? defaultAgentDir());
 	const settingsDir = path.resolve(input.settingsDir ?? defaultSubagentConfigDir(agentDir));
-	const defaultInstruction = buildIntercomBridgeInstruction(
-		orchestratorTarget || "{orchestratorTarget}",
-		DEFAULT_INTERCOM_BRIDGE_TEMPLATE,
-	);
 	const reason = inactiveReason(mode, input.context, orchestratorTarget);
 	if (reason || !orchestratorTarget) {
-		return { active: false, mode, resultDelivery: config.resultDelivery, extensionDir: NATIVE_INTERCOM_EXTENSION_DIR, instruction: defaultInstruction };
+		return {
+			active: false,
+			mode,
+			resultDelivery: config.resultDelivery,
+			extensionDir: NATIVE_INTERCOM_EXTENSION_DIR,
+			instruction: buildIntercomBridgeInstruction(ORCHESTRATOR_TARGET_PLACEHOLDER, DEFAULT_INTERCOM_BRIDGE_TEMPLATE),
+			interpolatesOrchestratorTarget: false,
+		};
 	}
+	const template = resolveInstructionTemplate(config.instructionFile, settingsDir);
 	return {
 		active: true,
 		mode,
 		resultDelivery: config.resultDelivery,
 		orchestratorTarget,
 		extensionDir: NATIVE_INTERCOM_EXTENSION_DIR,
-		instruction: buildIntercomBridgeInstruction(orchestratorTarget, resolveInstructionTemplate(config.instructionFile, settingsDir)),
+		instruction: buildIntercomBridgeInstruction(orchestratorTarget, template),
+		interpolatesOrchestratorTarget: template.includes(ORCHESTRATOR_TARGET_PLACEHOLDER),
 	};
 }
 
+/**
+ * Rewrites the launch prompt and tools for an active bridge. The parsed
+ * definition digest is captured first so launch identity keeps describing the
+ * agent file rather than this runtime overlay.
+ */
 export function applyIntercomBridgeToAgent(agent: AgentConfig, bridge: IntercomBridgeState): AgentConfig {
 	if (!bridge.active || !bridge.orchestratorTarget) return agent;
 
@@ -185,7 +228,8 @@ export function applyIntercomBridgeToAgent(agent: AgentConfig, bridge: IntercomB
 	if (tools === agent.tools && systemPrompt === agent.systemPrompt) return agent;
 	return {
 		...agent,
+		definitionDigest: agentDefinitionDigest(agent),
 		tools,
 		systemPrompt,
 	};
-}
+}