@pi-agents/orchid 0.1.0-beta.0

package/src/subagents/extension/control-notices.ts

@@ -0,0 +1,92 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { controlNotificationKey, formatControlNoticeMessage } from "../runs/shared/subagent-control.ts";
+import type { ControlEvent, SubagentState } from "../shared/types.ts";
+
+export const SUBAGENT_CONTROL_MESSAGE_TYPE = "subagent_control_notice";
+
+export interface SubagentControlMessageDetails {
+	event: ControlEvent;
+	source?: "foreground" | "async";
+	asyncDir?: string;
+	childIntercomTarget?: string;
+	noticeText?: string;
+}
+
+export function controlNoticeTarget(details: SubagentControlMessageDetails): string | undefined {
+	return details.childIntercomTarget;
+}
+
+export function formatSubagentControlNotice(details: SubagentControlMessageDetails, content?: string): string {
+	return details.noticeText ?? content ?? formatControlNoticeMessage(details.event, controlNoticeTarget(details));
+}
+
+function noticeTimerKey(details: SubagentControlMessageDetails): string {
+	const childIntercomTarget = controlNoticeTarget(details);
+	return `${details.event.runId}:${controlNotificationKey(details.event, childIntercomTarget)}`;
+}
+
+export function clearPendingForegroundControlNotices(state: SubagentState, runId?: string): void {
+	const pending = state.pendingForegroundControlNotices;
+	if (!pending) return;
+	for (const [key, timer] of pending) {
+		if (runId !== undefined && !key.startsWith(`${runId}:`)) continue;
+		clearTimeout(timer);
+		pending.delete(key);
+	}
+}
+
+function deliverControlNotice(input: {
+	pi: Pick<ExtensionAPI, "sendMessage">;
+	visibleControlNotices: Set<string>;
+	details: SubagentControlMessageDetails;
+}): void {
+	const childIntercomTarget = controlNoticeTarget(input.details);
+	const key = controlNotificationKey(input.details.event, childIntercomTarget);
+	if (input.visibleControlNotices.has(key)) return;
+	input.visibleControlNotices.add(key);
+	const noticeText = input.details.noticeText ?? formatControlNoticeMessage(input.details.event, childIntercomTarget);
+	input.pi.sendMessage(
+		{
+			customType: SUBAGENT_CONTROL_MESSAGE_TYPE,
+			content: noticeText,
+			display: true,
+			details: { ...input.details, childIntercomTarget, noticeText },
+		},
+		{ triggerTurn: input.details.source !== "foreground" },
+	);
+}
+
+function isForegroundNoticeStillActionable(state: SubagentState, details: SubagentControlMessageDetails): boolean {
+	const control = state.foregroundControls.get(details.event.runId);
+	if (!control) return false;
+	if (control.currentAgent && control.currentAgent !== details.event.agent) return false;
+	if (details.event.index !== undefined && control.currentIndex !== details.event.index) return false;
+	return control.currentActivityState === "needs_attention";
+}
+
+export function handleSubagentControlNotice(input: {
+	pi: Pick<ExtensionAPI, "sendMessage">;
+	state: SubagentState;
+	visibleControlNotices: Set<string>;
+	details: SubagentControlMessageDetails;
+	foregroundDelayMs?: number;
+}): void {
+	if (!input.details?.event || input.details.event.type === "active_long_running") return;
+	if (input.details.source !== "foreground") {
+		deliverControlNotice(input);
+		return;
+	}
+
+	const pending = input.state.pendingForegroundControlNotices ?? new Map<string, ReturnType<typeof setTimeout>>();
+	input.state.pendingForegroundControlNotices = pending;
+	const timerKey = noticeTimerKey(input.details);
+	const existing = pending.get(timerKey);
+	if (existing) clearTimeout(existing);
+	const timer = setTimeout(() => {
+		pending.delete(timerKey);
+		if (!isForegroundNoticeStillActionable(input.state, input.details)) return;
+		deliverControlNotice(input);
+	}, input.foregroundDelayMs ?? 1000);
+	timer.unref?.();
+	pending.set(timerKey, timer);
+}

package/src/subagents/extension/doctor.ts

@@ -0,0 +1,199 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { discoverAgentsAll, type AgentSource } from "../agents/agents.ts";
+import { isAsyncAvailable } from "../runs/background/async-execution.ts";
+import { diagnoseIntercomBridge, type IntercomBridgeDiagnostic } from "../intercom/intercom-bridge.ts";
+import { discoverAvailableSkills, type SkillSource } from "../agents/skills.ts";
+import {
+	ASYNC_DIR,
+	CHAIN_RUNS_DIR,
+	RESULTS_DIR,
+	TEMP_ROOT_DIR,
+	type ExtensionConfig,
+	type SubagentState,
+} from "../shared/types.ts";
+
+interface DoctorPaths {
+	tempRootDir: string;
+	asyncDir: string;
+	resultsDir: string;
+	chainRunsDir: string;
+}
+
+interface DoctorDeps {
+	isAsyncAvailable: () => boolean;
+	discoverAgentsAll: typeof discoverAgentsAll;
+	discoverAvailableSkills: typeof discoverAvailableSkills;
+	diagnoseIntercomBridge: typeof diagnoseIntercomBridge;
+}
+
+interface DoctorReportInput {
+	cwd: string;
+	config: ExtensionConfig;
+	state: SubagentState;
+	context?: "fresh" | "fork";
+	requestedSessionDir?: string;
+	currentSessionFile?: string | null;
+	currentSessionId?: string | null;
+	orchestratorTarget?: string;
+	sessionError?: string;
+	expandTilde?: (value: string) => string;
+	paths?: DoctorPaths;
+	deps?: Partial<DoctorDeps>;
+}
+
+const DEFAULT_PATHS: DoctorPaths = {
+	tempRootDir: TEMP_ROOT_DIR,
+	asyncDir: ASYNC_DIR,
+	resultsDir: RESULTS_DIR,
+	chainRunsDir: CHAIN_RUNS_DIR,
+};
+
+const DEFAULT_DEPS: DoctorDeps = {
+	isAsyncAvailable,
+	discoverAgentsAll,
+	discoverAvailableSkills,
+	diagnoseIntercomBridge,
+};
+
+function errorText(error: unknown): string {
+	return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+}
+
+function lineFromCheck(label: string, check: () => string): string {
+	try {
+		return check();
+	} catch (error) {
+		return `- ${label}: failed — ${errorText(error)}`;
+	}
+}
+
+function formatExistingDirectory(label: string, dirPath: string): string {
+	try {
+		if (!fs.existsSync(dirPath)) return `- ${label}: missing (${dirPath})`;
+		const stats = fs.statSync(dirPath);
+		if (!stats.isDirectory()) throw new Error(`not a directory: ${dirPath}`);
+		fs.accessSync(dirPath, fs.constants.R_OK | fs.constants.W_OK);
+		return `- ${label}: ok (${dirPath})`;
+	} catch (error) {
+		return `- ${label}: failed (${dirPath}) — ${errorText(error)}`;
+	}
+}
+
+function formatSourceCounts(counts: Record<AgentSource, number>): string {
+	return `builtin ${counts.builtin}, user ${counts.user}, project ${counts.project}`;
+}
+
+function formatSkillSourceCounts(skills: Array<{ source: SkillSource }>): string {
+	const counts = new Map<SkillSource, number>();
+	for (const skill of skills) counts.set(skill.source, (counts.get(skill.source) ?? 0) + 1);
+	const ordered: SkillSource[] = [
+		"project",
+		"project-settings",
+		"project-package",
+		"user",
+		"user-settings",
+		"user-package",
+		"extension",
+		"builtin",
+		"unknown",
+	];
+	const parts = ordered
+		.map((source) => `${source} ${counts.get(source) ?? 0}`)
+		.filter((part) => !part.endsWith(" 0"));
+	return parts.length > 0 ? parts.join(", ") : "none";
+}
+
+function formatConfiguredSessionDir(input: DoctorReportInput): string {
+	if (input.requestedSessionDir) {
+		return path.resolve(input.expandTilde?.(input.requestedSessionDir) ?? input.requestedSessionDir);
+	}
+	if (input.config.defaultSessionDir) {
+		return path.resolve(input.expandTilde?.(input.config.defaultSessionDir) ?? input.config.defaultSessionDir);
+	}
+	return "not configured";
+}
+
+function formatSessionLines(input: DoctorReportInput): string[] {
+	const sessionFile = input.currentSessionFile ?? null;
+	const lines = [
+		lineFromCheck("configured session dir", () => `- configured session dir: ${formatConfiguredSessionDir(input)}`),
+		`- current session file: ${sessionFile ?? "not available"}`,
+		`- current session dir: ${sessionFile ? path.dirname(sessionFile) : "not available"}`,
+		`- current session id: ${input.currentSessionId ?? input.state.currentSessionId ?? "not available"}`,
+	];
+	if (input.sessionError) lines.push(`- session manager: failed — ${input.sessionError}`);
+	return lines;
+}
+
+function formatDiscovery(input: DoctorReportInput, deps: DoctorDeps): string[] {
+	return [
+		lineFromCheck("agents/chains", () => {
+			const discovered = deps.discoverAgentsAll(input.cwd);
+			const agentCounts = {
+				builtin: discovered.builtin.length,
+				user: discovered.user.length,
+				project: discovered.project.length,
+			};
+			const chainCounts = discovered.chains.reduce<Record<AgentSource, number>>((counts, chain) => {
+				counts[chain.source] += 1;
+				return counts;
+			}, { builtin: 0, user: 0, project: 0 });
+			return [
+				`- agents: total ${agentCounts.builtin + agentCounts.user + agentCounts.project} (${formatSourceCounts(agentCounts)})`,
+				`- chains: total ${discovered.chains.length} (${formatSourceCounts(chainCounts)})`,
+			].join("\n");
+		}),
+		lineFromCheck("skills", () => {
+			const skills = deps.discoverAvailableSkills(input.cwd);
+			return `- skills: total ${skills.length} (${formatSkillSourceCounts(skills)})`;
+		}),
+	];
+}
+
+function formatIntercomDiagnostic(diagnostic: IntercomBridgeDiagnostic, context: "fresh" | "fork" | undefined): string[] {
+	const lines = [
+		`- bridge: ${diagnostic.active ? "active" : "inactive"}${diagnostic.reason ? ` (${diagnostic.reason})` : ""}`,
+		`- mode: ${diagnostic.mode}; context: ${context ?? "unspecified"}`,
+		`- orchestrator target: ${diagnostic.orchestratorTarget ?? "not available"}`,
+		`- pi-intercom: ${diagnostic.piIntercomAvailable ? "available" : "unavailable"} at ${diagnostic.extensionDir}`,
+	];
+	if (diagnostic.configPath && diagnostic.intercomConfigEnabled !== undefined) {
+		lines.push(`- intercom config: ${diagnostic.intercomConfigEnabled === false ? "disabled" : "enabled or absent"} (${diagnostic.configPath})`);
+	}
+	if (diagnostic.intercomConfigError) {
+		lines.push(`- intercom config warning: ${diagnostic.intercomConfigError}; runtime assumes enabled`);
+	}
+	return lines;
+}
+
+export function buildDoctorReport(input: DoctorReportInput): string {
+	const paths = input.paths ?? DEFAULT_PATHS;
+	const deps = { ...DEFAULT_DEPS, ...input.deps };
+	const lines = [
+		"Subagents doctor report",
+		"",
+		"Runtime",
+		`- cwd: ${input.cwd}`,
+		lineFromCheck("async support", () => `- async support: ${deps.isAsyncAvailable() ? "available" : "unavailable"}`),
+		...formatSessionLines(input),
+		"",
+		"Filesystem",
+		formatExistingDirectory("temp root", paths.tempRootDir),
+		formatExistingDirectory("async runs", paths.asyncDir),
+		formatExistingDirectory("results", paths.resultsDir),
+		formatExistingDirectory("chain runs", paths.chainRunsDir),
+		"",
+		"Discovery",
+		...formatDiscovery(input, deps),
+		"",
+		"Intercom bridge",
+		...lineFromCheck("intercom bridge", () => formatIntercomDiagnostic(deps.diagnoseIntercomBridge({
+			config: input.config.intercomBridge,
+			context: input.context,
+			orchestratorTarget: input.orchestratorTarget,
+			cwd: input.cwd,
+		}), input.context).join("\n")).split("\n"),
+	];
+	return lines.join("\n");
+}

package/src/subagents/extension/fanout-child.ts

@@ -0,0 +1,170 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { discoverAgents } from "../agents/agents.ts";
+import { getArtifactsDir } from "../shared/artifacts.ts";
+import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
+import { SUBAGENT_CHILD_ENV, SUBAGENT_FANOUT_CHILD_ENV } from "../runs/shared/pi-args.ts";
+import { readNestedControlRequests, resolveNestedRouteFromEnv, writeNestedControlResult } from "../runs/shared/nested-events.ts";
+import { deliverSubagentIntercomMessageEvent } from "../intercom/result-intercom.ts";
+import { resolveSubagentIntercomTarget } from "../intercom/intercom-bridge.ts";
+import { SubagentParams } from "./schemas.ts";
+import { loadConfig } from "./config.ts";
+import { type Details, type SubagentState } from "../shared/types.ts";
+
+function getSubagentSessionRoot(parentSessionFile: string | null): string {
+	if (parentSessionFile) {
+		const baseName = path.basename(parentSessionFile, ".jsonl");
+		const sessionsDir = path.dirname(parentSessionFile);
+		return path.join(sessionsDir, baseName);
+	}
+	return fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-session-"));
+}
+
+function expandTilde(p: string): string {
+	return p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p;
+}
+
+function createChildSafeState(): SubagentState {
+	return {
+		baseCwd: "",
+		currentSessionId: null,
+		asyncJobs: new Map(),
+		foregroundRuns: new Map(),
+		foregroundControls: new Map(),
+		lastForegroundControlId: null,
+		pendingForegroundControlNotices: new Map(),
+		cleanupTimers: new Map(),
+		lastUiContext: null,
+		poller: null,
+		completionSeen: new Map(),
+		watcher: null,
+		watcherRestartTimer: null,
+		resultFileCoalescer: {
+			schedule: () => false,
+			clear: () => {},
+		},
+	};
+}
+
+function startNestedControlInboxListener(pi: ExtensionAPI, state: SubagentState): NodeJS.Timeout | undefined {
+	let route;
+	try {
+		route = resolveNestedRouteFromEnv();
+	} catch {
+		return undefined;
+	}
+	if (!route) return undefined;
+	const seen = new Set<string>();
+	const inFlight = new Set<string>();
+	const pendingResults = new Map<string, Parameters<typeof writeNestedControlResult>[1]>();
+	const timer = setInterval(() => {
+		try {
+			for (const request of readNestedControlRequests(route)) {
+				if (seen.has(request.requestId) || inFlight.has(request.requestId)) continue;
+				inFlight.add(request.requestId);
+				void (async () => {
+					try {
+						let result = pendingResults.get(request.requestId);
+						if (!result) {
+							let ok = false;
+							let message = "Control request failed.";
+							try {
+								const control = state.foregroundControls.get(request.targetRunId);
+								if (!control) {
+									message = `Nested run ${request.targetRunId} is not active in this fanout child.`;
+								} else if (request.action === "interrupt") {
+									ok = control.interrupt?.() === true;
+									message = ok
+										? `Interrupt requested for nested run ${request.targetRunId}.`
+										: `Nested run ${request.targetRunId} has no active child step to interrupt.`;
+								} else if (!request.message?.trim()) {
+									message = "Nested resume requires message.";
+								} else if (!control.currentAgent) {
+									message = `Nested run ${request.targetRunId} has no active child message route.`;
+								} else {
+									const index = control.currentIndex ?? 0;
+									const target = resolveSubagentIntercomTarget(request.targetRunId, control.currentAgent, index);
+									ok = await deliverSubagentIntercomMessageEvent(
+										pi.events,
+										target,
+										`Follow-up for nested run ${request.targetRunId} (${control.currentAgent}):\n\n${request.message.trim()}`,
+										500,
+										{ source: "nested-resume", runId: request.targetRunId, agent: control.currentAgent, index },
+									);
+									message = ok
+										? `Delivered follow-up to live nested run ${request.targetRunId}.`
+										: `Nested child intercom target is not registered: ${target}`;
+								}
+							} catch (error) {
+								message = error instanceof Error ? error.message : String(error);
+							}
+							result = { ts: Date.now(), requestId: request.requestId, targetRunId: request.targetRunId, ok, message };
+						}
+						try {
+							writeNestedControlResult(route, result);
+						} catch (error) {
+							pendingResults.set(request.requestId, result);
+							console.error(`Failed to write nested control result for request '${request.requestId}' targeting '${request.targetRunId}' via inbox '${route.controlInbox}'; keeping request for retry:`, error);
+							return;
+						}
+						pendingResults.delete(request.requestId);
+						seen.add(request.requestId);
+						try { fs.unlinkSync(request.filePath); } catch {}
+					} finally {
+						inFlight.delete(request.requestId);
+					}
+				})();
+			}
+		} catch (error) {
+			console.error(`Failed to poll nested control inbox '${route.controlInbox}' for root '${route.rootRunId}':`, error);
+		}
+	}, 200);
+	timer.unref?.();
+	return timer;
+}
+
+export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI): void {
+	if (process.env[SUBAGENT_CHILD_ENV] !== "1" || process.env[SUBAGENT_FANOUT_CHILD_ENV] !== "1") return;
+
+	const globalStore = globalThis as Record<string, unknown>;
+	const registeredKey = "__piSubagentFanoutChildRegisteredApis";
+	const registeredApis = globalStore[registeredKey] instanceof WeakSet
+		? globalStore[registeredKey] as WeakSet<ExtensionAPI>
+		: new WeakSet<ExtensionAPI>();
+	globalStore[registeredKey] = registeredApis;
+	if (registeredApis.has(pi)) return;
+	registeredApis.add(pi);
+
+	const config = loadConfig();
+	const state = createChildSafeState();
+	const executor = createSubagentExecutor({
+		pi,
+		state,
+		config,
+		asyncByDefault: config.asyncByDefault === true,
+		tempArtifactsDir: getArtifactsDir(null),
+		getSubagentSessionRoot,
+		expandTilde,
+		discoverAgents,
+		allowMutatingManagementActions: false,
+	});
+
+	const tool: ToolDefinition<typeof SubagentParams, Details> = {
+		name: "subagent",
+		label: "Subagent",
+		description: [
+			"Delegate to subagents from child-safe fanout mode.",
+			"Allowed management/control actions: list, get, status, interrupt, resume, doctor.",
+			"Agent config mutation actions create, update, and delete are blocked in this mode.",
+		].join("\n"),
+		parameters: SubagentParams,
+		execute(id, params, signal, onUpdate, ctx) {
+			return executor.execute(id, params as SubagentParamsLike, signal, onUpdate, ctx);
+		},
+	};
+
+	pi.registerTool(tool);
+	startNestedControlInboxListener(pi, state);
+}