pi-subagents 0.19.0 → 0.19.2

package/doctor.ts

@@ -0,0 +1,198 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { discoverAgentsAll, type AgentSource } from "./agents.ts";
+import { isAsyncAvailable } from "./async-execution.ts";
+import { diagnoseIntercomBridge, type IntercomBridgeDiagnostic } from "./intercom-bridge.ts";
+import { discoverAvailableSkills, type SkillSource } from "./skills.ts";
+import {
+	ASYNC_DIR,
+	CHAIN_RUNS_DIR,
+	RESULTS_DIR,
+	TEMP_ROOT_DIR,
+	type ExtensionConfig,
+	type SubagentState,
+} from "./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;
+}
+
+export 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,
+		}), input.context).join("\n")).split("\n"),
+	];
+	return lines.join("\n");
+}

package/index.ts

@@ -421,7 +421,10 @@ MANAGEMENT (use action field, omit agent/task/chain/tasks):
 
 CONTROL:
 • { action: "status", id: "..." } - inspect an async/background run by id or prefix
-• { action: "interrupt", id?: "..." } - soft-interrupt the current child turn and leave the run paused`,
+• { action: "interrupt", id?: "..." } - soft-interrupt the current child turn and leave the run paused
+
+DIAGNOSTICS:
+• { action: "doctor" } - read-only report for runtime paths, discovery, sessions, and intercom`,
 		parameters: SubagentParams,
 
 		execute(id, params, signal, onUpdate, ctx) {

package/intercom-bridge.ts

@@ -25,6 +25,19 @@ export interface IntercomBridgeState {
 	instruction: string;
 }
 
+export interface IntercomBridgeDiagnostic {
+	active: boolean;
+	mode: IntercomBridgeMode;
+	wantsIntercom: boolean;
+	piIntercomAvailable: boolean;
+	extensionDir: string;
+	configPath?: string;
+	orchestratorTarget?: string;
+	reason?: string;
+	intercomConfigEnabled?: boolean;
+	intercomConfigError?: string;
+}
+
 interface ResolveIntercomBridgeInput {
 	config: ExtensionConfig["intercomBridge"];
 	context: "fresh" | "fork" | undefined;
@@ -68,14 +81,13 @@ function resolveIntercomBridgeConfig(value: ExtensionConfig["intercomBridge"]):
 	};
 }
 
-function intercomEnabled(configPath: string): boolean {
-	if (!fs.existsSync(configPath)) return true;
+function intercomConfigStatus(configPath: string): { enabled: boolean; error?: unknown } {
+	if (!fs.existsSync(configPath)) return { enabled: true };
 	try {
 		const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8")) as { enabled?: unknown };
-		return parsed.enabled !== false;
+		return { enabled: parsed.enabled !== false };
 	} catch (error) {
-		console.warn(`Failed to parse intercom config at '${configPath}'. Assuming enabled.`, error);
-		return true;
+		return { enabled: true, error };
 	}
 }
 
@@ -119,6 +131,44 @@ function buildIntercomBridgeInstruction(orchestratorTarget: string, template: st
 ${instruction}`;
 }
 
+export function diagnoseIntercomBridge(input: ResolveIntercomBridgeInput): IntercomBridgeDiagnostic {
+	const config = resolveIntercomBridgeConfig(input.config);
+	const mode = config.mode;
+	const extensionDir = path.resolve(input.extensionDir ?? DEFAULT_INTERCOM_EXTENSION_DIR);
+	const orchestratorTarget = input.orchestratorTarget?.trim();
+	const configPath = path.resolve(input.configPath ?? DEFAULT_INTERCOM_CONFIG_PATH);
+	const wantsIntercom = mode !== "off" && !(mode === "fork-only" && input.context !== "fork");
+	const piIntercomAvailable = fs.existsSync(extensionDir);
+	let configStatus: ReturnType<typeof intercomConfigStatus> | undefined;
+	let reason: string | undefined;
+	if (mode === "off") reason = "bridge mode is off";
+	else if (mode === "fork-only" && input.context !== "fork") reason = "bridge mode is fork-only and context is not fork";
+	else if (!orchestratorTarget) reason = "orchestrator target is not available";
+	else if (!piIntercomAvailable) reason = "pi-intercom extension was not found";
+	else {
+		configStatus = intercomConfigStatus(configPath);
+		if (!configStatus.enabled) reason = "intercom config is disabled";
+	}
+	let intercomConfigError: string | undefined;
+	if (configStatus?.error) {
+		const error = configStatus.error;
+		intercomConfigError = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+	}
+
+	return {
+		active: reason === undefined,
+		mode,
+		wantsIntercom,
+		piIntercomAvailable,
+		extensionDir,
+		configPath,
+		...(orchestratorTarget ? { orchestratorTarget } : {}),
+		...(reason ? { reason } : {}),
+		...(configStatus ? { intercomConfigEnabled: configStatus.enabled } : {}),
+		...(intercomConfigError ? { intercomConfigError } : {}),
+	};
+}
+
 export function resolveIntercomBridge(input: ResolveIntercomBridgeInput): IntercomBridgeState {
 	const config = resolveIntercomBridgeConfig(input.config);
 	const mode = config.mode;
@@ -144,7 +194,9 @@ export function resolveIntercomBridge(input: ResolveIntercomBridgeInput): Interc
 	}
 
 	const configPath = path.resolve(input.configPath ?? DEFAULT_INTERCOM_CONFIG_PATH);
-	if (!intercomEnabled(configPath)) {
+	const intercomStatus = intercomConfigStatus(configPath);
+	if (intercomStatus.error) console.warn(`Failed to parse intercom config at '${configPath}'. Assuming enabled.`, intercomStatus.error);
+	if (!intercomStatus.enabled) {
 		return { active: false, mode, extensionDir, instruction: defaultInstruction };
 	}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.19.0",
+  "version": "0.19.2",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",

package/prompts/gather-context-and-clarify.md

@@ -0,0 +1,13 @@
+---
+description: Use subagents to gather context, then ask clarifying questions
+---
+
+Based on our discussion and my intent, launch focused context-gathering subagents before planning or implementing.
+
+Use `scout` to inspect the relevant local files, existing patterns, constraints, tests, and likely integration points. Use `researcher` when external docs, recent sources, ecosystem context, or primary evidence would improve the answer.
+
+Give each subagent a specific meta prompt. Ask them to return concise findings plus the remaining clarification questions that matter for implementation confidence.
+
+After they return, synthesize what we know and use the `interview` tool to ask me the unresolved questions needed to reach a shared understanding.
+
+$@

package/prompts/oracle-executor.md

@@ -0,0 +1,9 @@
+---
+description: Send an explicitly approved task to oracle-executor with full inherited context.
+subagent: oracle-executor
+inheritContext: true
+---
+
+Launch the oracle-executor subagent with a strict implementation meta prompt that points it at the plan and asks it to execute:
+
+$@

package/prompts/parallel-research.md

@@ -0,0 +1,50 @@
+---
+description: Parallel subagents research
+---
+
+Launch parallel research subagents to build a grounded answer to the current question or decision.
+
+Use fresh context, not forked context, unless I explicitly ask for forked context. Researchers and scouts should inspect sources directly instead of relying on the main conversation history.
+
+Use a combination of `researcher` and `scout` subagents:
+- Use `researcher` for web, docs, standards, ecosystem, recent changes, benchmarks, and primary-source evidence.
+- Use `scout` for local codebase context, existing implementation patterns, repo constraints, and files that would be affected.
+
+Give each subagent a distinct angle. Unless I specify angles, use these three:
+
+1. External evidence
+   Use `researcher` to find current, authoritative sources: official docs, specs, release notes, benchmarks, issue threads, or primary explanations.
+
+2. Local code context
+   Use `scout` to inspect the repository for relevant files, existing patterns, constraints, tests, and likely integration points.
+
+3. Practical tradeoffs
+   Use `researcher` or `scout`, whichever fits the question, to compare options, risks, edge cases, maintenance cost, and what would be easiest to validate.
+
+Adapt the angles when the question calls for it:
+- Library/API questions: include official docs and recent examples.
+- Architecture decisions: include local module boundaries, dependency direction, and migration cost.
+- Debugging questions: include likely failure modes, local call paths, and exact error evidence.
+- UI/product questions: include user flow, accessibility, design precedent, and implementation constraints.
+- Time-sensitive topics: include a recent-developments angle and prefer 2026/2025 sources.
+
+Prefer two or three strong subagents over many vague ones. The parent agent should frame the question and assign angles; the child agents should research or scout, not invent broad plans.
+
+Ask each subagent to return concise findings with evidence:
+- file paths and line ranges for local findings
+- source links for external findings
+- confidence level and gaps
+- recommended next step or decision implication
+
+Do not ask subagents to edit files. This is a research pass only unless I explicitly ask for implementation.
+
+After the subagents return, synthesize the answer into:
+- what we know
+- what the local codebase implies
+- tradeoffs and risks
+- gaps or assumptions
+- the recommended next move
+
+If findings disagree, call out the disagreement instead of smoothing it over.
+
+$@

package/prompts/parallel-review.md

@@ -1,8 +1,38 @@
 ---
 description: Parallel subagents review
 ---
-Great. Now let's launch parallel reviewers to conduct an adversarial review.
 
-Important: launch reviewers with fresh context, not forked context. Reviewers should inspect the repository and current diff directly from files and commands, without inheriting the main agent chat. Use forked context only if I explicitly ask for it.
+Launch parallel reviewers for an adversarial review of the current work.
+
+Use fresh context, not forked context, unless I explicitly ask for forked context. Reviewers should inspect the repository, relevant instructions, and current diff directly from files and commands. Do not rely on the main conversation history.
+
+Give each reviewer a distinct angle. Unless I specify angles, use these three:
+
+1. Correctness and regressions
+   Check whether the change satisfies the request, preserves existing behavior, handles edge cases, and avoids hidden runtime failures.
+
+2. Tests and validation
+   Check whether tests or validation were added at the right layer, whether assertions are meaningful, and whether the chosen verification commands are enough.
+
+3. Simplicity and maintainability
+   Check for unnecessary complexity, duplicate structure, single-use wrappers, brittle abstractions, confusing names, verbosity, and cleanup that is clearly worth doing.
+
+Adapt the angles when the work calls for it:
+- TypeScript-heavy changes: include type safety, source-of-truth types, casts, and error-boundary discipline.
+- UI-heavy changes: include UX, accessibility, copy, and visual quality.
+- Security-sensitive changes: include unsafe input/output handling, auth boundaries, privacy, and data exposure.
+- Docs-heavy changes: include clarity, accuracy, completeness, reader flow, and non-robotic prose.
+- Large multi-file changes: consider a fourth reviewer for structural friction, module boundaries, and testability.
+
+Prefer three strong reviewers over many vague reviewers.
+
+Give every reviewer a specific task prompt naming its angle. Ask reviewers to return concise, evidence-backed findings with file/line references and suggested fixes. The response should be review feedback, not a context summary. Reviewers must not edit files unless I explicitly ask for a writer pass.
+
+While reviewers run, do your own narrow inspection if useful. After they return, synthesize the feedback into:
+- fixes worth doing now
+- optional improvements
+- feedback to ignore or defer, with a short reason
+
+Do not blindly apply every reviewer suggestion. Ask before applying fixes unless I already told you to address review feedback.
 
 $@

package/schemas.ts

@@ -106,7 +106,7 @@ export const SubagentParams = Type.Object({
 	task: Type.Optional(Type.String({ description: "Task (SINGLE mode, optional for self-contained agents)" })),
 	// Management action (when present, tool operates in management mode)
 	action: Type.Optional(Type.String({
-		description: "Action: management ('list','get','create','update','delete') or control ('status','interrupt'). Omit for execution mode."
+		description: "Action: 'list', 'get', 'create', 'update', 'delete', 'status', 'interrupt', or 'doctor'. Omit for execution mode."
 	})),
 	id: Type.Optional(Type.String({
 		description: "Run id or prefix for action='status' or action='interrupt'."