@agnishc/edb-subagents 0.8.2

package/src/cross-extension-rpc.ts

@@ -0,0 +1,121 @@
+/**
+ * Cross-extension RPC handlers for the subagents extension.
+ *
+ * Exposes ping, spawn, and stop RPCs over the pi.events event bus,
+ * using per-request scoped reply channels.
+ *
+ * Reply envelope follows pi-mono convention:
+ *   success → { success: true, data?: T }
+ *   error   → { success: false, error: string }
+ */
+
+import { type ModelRegistry, resolveModel } from "./model-resolver.js";
+
+/** Minimal event bus interface needed by the RPC handlers. */
+export interface EventBus {
+	on(event: string, handler: (data: unknown) => void): () => void;
+	emit(event: string, data: unknown): void;
+}
+
+/** RPC reply envelope — matches pi-mono's RpcResponse shape. */
+export type RpcReply<T = void> = { success: true; data?: T } | { success: false; error: string };
+
+/** RPC protocol version — bumped when the envelope or method contracts change. */
+export const PROTOCOL_VERSION = 2;
+
+/** Minimal AgentManager interface needed by the spawn/stop RPCs. */
+export interface SpawnCapable {
+	spawn(pi: unknown, ctx: unknown, type: string, prompt: string, options: any): string;
+	abort(id: string): boolean;
+}
+
+export interface RpcDeps {
+	events: EventBus;
+	pi: unknown; // passed through to manager.spawn
+	getCtx: () => unknown | undefined; // returns current ExtensionContext
+	manager: SpawnCapable;
+}
+
+export interface RpcHandle {
+	unsubPing: () => void;
+	unsubSpawn: () => void;
+	unsubStop: () => void;
+}
+
+/**
+ * Wire a single RPC handler: listen on `channel`, run `fn(params)`,
+ * emit the reply envelope on `channel:reply:${requestId}`.
+ */
+function handleRpc<P extends { requestId: string }>(
+	events: EventBus,
+	channel: string,
+	fn: (params: P) => unknown | Promise<unknown>,
+): () => void {
+	return events.on(channel, async (raw: unknown) => {
+		const params = raw as P;
+		try {
+			const data = await fn(params);
+			const reply: { success: true; data?: unknown } = { success: true };
+			if (data !== undefined) reply.data = data;
+			events.emit(`${channel}:reply:${params.requestId}`, reply);
+		} catch (err: any) {
+			events.emit(`${channel}:reply:${params.requestId}`, {
+				success: false,
+				error: err?.message ?? String(err),
+			});
+		}
+	});
+}
+
+/**
+ * Register ping, spawn, and stop RPC handlers on the event bus.
+ * Returns unsub functions for cleanup.
+ */
+export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
+	const { events, pi, getCtx, manager } = deps;
+
+	const unsubPing = handleRpc(events, "subagents:rpc:ping", () => {
+		return { version: PROTOCOL_VERSION };
+	});
+
+	const unsubSpawn = handleRpc<{ requestId: string; type: string; prompt: string; options?: any }>(
+		events,
+		"subagents:rpc:spawn",
+		({ type, prompt, options }) => {
+			const ctx = getCtx();
+			if (!ctx) throw new Error("No active session");
+
+			// Cross-extension RPC callers (e.g. pi-tasks TaskExecute) naturally
+			// forward serializable values, so options.model can be a string like
+			// "openai-codex/gpt-5.5". Resolve it to a real Model instance here
+			// — same pattern the scheduler path already uses — so the spawned
+			// agent's auth lookup doesn't crash with "No API key found for
+			// undefined".
+			let normalizedOptions = options ?? {};
+			if (typeof normalizedOptions.model === "string") {
+				const registry = (ctx as { modelRegistry?: ModelRegistry }).modelRegistry;
+				if (!registry) {
+					throw new Error(
+						`Model override "${normalizedOptions.model}" provided but ctx.modelRegistry is unavailable`,
+					);
+				}
+				const resolved = resolveModel(normalizedOptions.model, registry);
+				if (typeof resolved === "string") {
+					// resolveModel returns a human-readable error string when the
+					// input doesn't match any available model. Surface it instead of
+					// silently falling back so the caller sees the auth/typo issue.
+					throw new Error(resolved);
+				}
+				normalizedOptions = { ...normalizedOptions, model: resolved };
+			}
+
+			return { id: manager.spawn(pi, ctx, type, prompt, normalizedOptions) };
+		},
+	);
+
+	const unsubStop = handleRpc<{ requestId: string; agentId: string }>(events, "subagents:rpc:stop", ({ agentId }) => {
+		if (!manager.abort(agentId)) throw new Error("Agent not found");
+	});
+
+	return { unsubPing, unsubSpawn, unsubStop };
+}

package/src/custom-agents.ts

@@ -0,0 +1,140 @@
+/**
+ * custom-agents.ts — Load user-defined agents from project (.pi/agents/) and global ($PI_CODING_AGENT_DIR/agents/, default ~/.pi/agent/agents/) locations.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
+import type { AgentConfig, MemoryScope, ThinkingLevel } from "./types.js";
+
+/**
+ * Scan for custom agent .md files from multiple locations.
+ * Discovery hierarchy (higher priority wins):
+ *   1. Project: <cwd>/.pi/agents/*.md
+ *   2. Global:  $PI_CODING_AGENT_DIR/agents/*.md (default: ~/.pi/agent/agents/*.md)
+ *
+ * Project-level agents override global ones with the same name.
+ * Any name is allowed — names matching defaults (e.g. "Explore") override them.
+ */
+export function loadCustomAgents(cwd: string): Map<string, AgentConfig> {
+	const globalDir = join(getAgentDir(), "agents");
+	const projectDir = join(cwd, ".pi", "agents");
+
+	const agents = new Map<string, AgentConfig>();
+	loadFromDir(globalDir, agents, "global"); // lower priority
+	loadFromDir(projectDir, agents, "project"); // higher priority (overwrites)
+	return agents;
+}
+
+/** Load agent configs from a directory into the map. */
+function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "project" | "global"): void {
+	if (!existsSync(dir)) return;
+
+	let files: string[];
+	try {
+		files = readdirSync(dir).filter((f) => f.endsWith(".md"));
+	} catch {
+		return;
+	}
+
+	for (const file of files) {
+		const name = basename(file, ".md");
+
+		let content: string;
+		try {
+			content = readFileSync(join(dir, file), "utf-8");
+		} catch {
+			continue;
+		}
+
+		const { frontmatter: fm, body } = parseFrontmatter<Record<string, unknown>>(content);
+
+		agents.set(name, {
+			name,
+			displayName: str(fm.display_name),
+			description: str(fm.description) ?? name,
+			builtinToolNames: csvList(fm.tools, BUILTIN_TOOL_NAMES),
+			disallowedTools: csvListOptional(fm.disallowed_tools),
+			extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
+			skills: inheritField(fm.skills ?? fm.inherit_skills),
+			model: str(fm.model),
+			fallbackModels: csvListOptional(fm.fallback_models),
+			thinking: str(fm.thinking) as ThinkingLevel | undefined,
+			maxTurns: nonNegativeInt(fm.max_turns),
+			systemPrompt: body.trim(),
+			promptMode: fm.prompt_mode === "append" ? "append" : "replace",
+			inheritContext: fm.inherit_context != null ? fm.inherit_context === true : undefined,
+			runInBackground: fm.run_in_background != null ? fm.run_in_background === true : undefined,
+			isolated: fm.isolated != null ? fm.isolated === true : undefined,
+			memory: parseMemory(fm.memory),
+			isolation: fm.isolation === "worktree" ? "worktree" : undefined,
+			enabled: fm.enabled !== false, // default true; explicitly false disables
+			source,
+		});
+	}
+}
+
+// ---- Field parsers ----
+// All follow the same convention: omitted → default, "none"/empty → nothing, value → exact.
+
+/** Extract a string or undefined. */
+function str(val: unknown): string | undefined {
+	return typeof val === "string" ? val : undefined;
+}
+
+/** Extract a non-negative integer or undefined. 0 means unlimited for max_turns. */
+function nonNegativeInt(val: unknown): number | undefined {
+	return typeof val === "number" && val >= 0 ? val : undefined;
+}
+
+/**
+ * Parse a raw CSV field value into items, or undefined if absent/empty/"none".
+ */
+function parseCsvField(val: unknown): string[] | undefined {
+	if (val === undefined || val === null) return undefined;
+	const s = String(val).trim();
+	if (!s || s === "none") return undefined;
+	const items = s
+		.split(",")
+		.map((t) => t.trim())
+		.filter(Boolean);
+	return items.length > 0 ? items : undefined;
+}
+
+/**
+ * Parse a comma-separated list field with defaults.
+ * omitted → defaults; "none"/empty → []; csv → listed items.
+ */
+function csvList(val: unknown, defaults: string[]): string[] {
+	if (val === undefined || val === null) return defaults;
+	return parseCsvField(val) ?? [];
+}
+
+/**
+ * Parse an optional comma-separated list field.
+ * omitted → undefined; "none"/empty → undefined; csv → listed items.
+ */
+function csvListOptional(val: unknown): string[] | undefined {
+	return parseCsvField(val);
+}
+
+/**
+ * Parse a memory scope field.
+ * omitted → undefined; "user"/"project"/"local" → MemoryScope.
+ */
+function parseMemory(val: unknown): MemoryScope | undefined {
+	if (val === "user" || val === "project" || val === "local") return val;
+	return undefined;
+}
+
+/**
+ * Parse an inherit field (extensions, skills).
+ * omitted/true → true (inherit all); false/"none"/empty → false; csv → listed names.
+ */
+function inheritField(val: unknown): true | string[] | false {
+	if (val === undefined || val === null || val === true) return true;
+	if (val === false || val === "none") return false;
+	const items = csvList(val, []);
+	return items.length > 0 ? items : false;
+}

package/src/default-agents.ts

@@ -0,0 +1,123 @@
+/**
+ * default-agents.ts — Embedded default agent configurations.
+ *
+ * These are always available but can be overridden by user .md files with the same name.
+ */
+
+import type { AgentConfig } from "./types.js";
+
+const READ_ONLY_TOOLS = ["read", "bash", "grep", "find", "ls"];
+
+export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
+	[
+		"general-purpose",
+		{
+			name: "general-purpose",
+			displayName: "Agent",
+			description: "General-purpose agent for complex, multi-step tasks",
+			// builtinToolNames omitted — means "all available tools" (resolved at lookup time)
+			// inheritContext / runInBackground / isolated omitted — strategy fields, callers decide per-call.
+			// Setting them to false would lock callsite intent (see resolveAgentInvocationConfig in invocation-config.ts).
+			extensions: true,
+			skills: true,
+			systemPrompt: "",
+			promptMode: "append",
+			isDefault: true,
+		},
+	],
+	[
+		"Explore",
+		{
+			name: "Explore",
+			displayName: "Explore",
+			description: "Fast codebase exploration agent (read-only)",
+			builtinToolNames: READ_ONLY_TOOLS,
+			extensions: true,
+			skills: true,
+			model: "anthropic/claude-haiku-4-5-20251001",
+			systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
+You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools.
+
+You are STRICTLY PROHIBITED from:
+- Creating new files
+- Modifying existing files
+- Deleting files
+- Moving or copying files
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Use Bash ONLY for read-only operations: ls, git status, git log, git diff, find, cat, head, tail.
+
+# Tool Usage
+- Use the find tool for file pattern matching (NOT the bash find command)
+- Use the grep tool for content search (NOT bash grep/rg command)
+- Use the read tool for reading files (NOT bash cat/head/tail)
+- Use Bash ONLY for read-only operations
+- Make independent tool calls in parallel for efficiency
+- Adapt search approach based on thoroughness level specified
+
+# Output
+- Use absolute file paths in all references
+- Report findings as regular messages
+- Do not use emojis
+- Be thorough and precise`,
+			promptMode: "replace",
+			isDefault: true,
+		},
+	],
+	[
+		"Plan",
+		{
+			name: "Plan",
+			displayName: "Plan",
+			description: "Software architect for implementation planning (read-only)",
+			builtinToolNames: READ_ONLY_TOOLS,
+			extensions: true,
+			skills: true,
+			systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
+You are a software architect and planning specialist.
+Your role is EXCLUSIVELY to explore the codebase and design implementation plans.
+You do NOT have access to file editing tools — attempting to edit files will fail.
+
+You are STRICTLY PROHIBITED from:
+- Creating new files
+- Modifying existing files
+- Deleting files
+- Moving or copying files
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+# Planning Process
+1. Understand requirements
+2. Explore thoroughly (read files, find patterns, understand architecture)
+3. Design solution based on your assigned perspective
+4. Detail the plan with step-by-step implementation strategy
+
+# Requirements
+- Consider trade-offs and architectural decisions
+- Identify dependencies and sequencing
+- Anticipate potential challenges
+- Follow existing patterns where appropriate
+
+# Tool Usage
+- Use the find tool for file pattern matching (NOT the bash find command)
+- Use the grep tool for content search (NOT bash grep/rg command)
+- Use the read tool for reading files (NOT bash cat/head/tail)
+- Use Bash ONLY for read-only operations
+
+# Output Format
+- Use absolute file paths
+- Do not use emojis
+- End your response with:
+
+### Critical Files for Implementation
+List 3-5 files most critical for implementing this plan:
+- /absolute/path/to/file.ts - [Brief reason]`,
+			promptMode: "replace",
+			isDefault: true,
+		},
+	],
+]);

package/src/env.ts

@@ -0,0 +1,33 @@
+/**
+ * env.ts — Detect environment info (git, platform) for subagent system prompts.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { EnvInfo } from "./types.js";
+
+export async function detectEnv(pi: ExtensionAPI, cwd: string): Promise<EnvInfo> {
+	let isGitRepo = false;
+	let branch = "";
+
+	try {
+		const result = await pi.exec("git", ["rev-parse", "--is-inside-work-tree"], { cwd, timeout: 5000 });
+		isGitRepo = result.code === 0 && result.stdout.trim() === "true";
+	} catch {
+		// Not a git repo or git not installed
+	}
+
+	if (isGitRepo) {
+		try {
+			const result = await pi.exec("git", ["branch", "--show-current"], { cwd, timeout: 5000 });
+			branch = result.code === 0 ? result.stdout.trim() : "unknown";
+		} catch {
+			branch = "unknown";
+		}
+	}
+
+	return {
+		isGitRepo,
+		branch,
+		platform: process.platform,
+	};
+}

package/src/group-join.ts

@@ -0,0 +1,141 @@
+/**
+ * group-join.ts — Manages grouped background agent completion notifications.
+ *
+ * Instead of each agent individually nudging the main agent on completion,
+ * agents in a group are held until all complete (or a timeout fires),
+ * then a single consolidated notification is sent.
+ */
+
+import type { AgentRecord } from "./types.js";
+
+export type DeliveryCallback = (records: AgentRecord[], partial: boolean) => void;
+
+interface AgentGroup {
+	groupId: string;
+	agentIds: Set<string>;
+	completedRecords: Map<string, AgentRecord>;
+	timeoutHandle?: ReturnType<typeof setTimeout>;
+	delivered: boolean;
+	/** Shorter timeout for stragglers after a partial delivery. */
+	isStraggler: boolean;
+}
+
+/** Default timeout: 30s after first completion in a group. */
+const DEFAULT_TIMEOUT = 30_000;
+/** Straggler re-batch timeout: 15s. */
+const STRAGGLER_TIMEOUT = 15_000;
+
+export class GroupJoinManager {
+	private groups = new Map<string, AgentGroup>();
+	private agentToGroup = new Map<string, string>();
+
+	constructor(
+		private deliverCb: DeliveryCallback,
+		private groupTimeout = DEFAULT_TIMEOUT,
+	) {}
+
+	/** Register a group of agent IDs that should be joined. */
+	registerGroup(groupId: string, agentIds: string[]): void {
+		const group: AgentGroup = {
+			groupId,
+			agentIds: new Set(agentIds),
+			completedRecords: new Map(),
+			delivered: false,
+			isStraggler: false,
+		};
+		this.groups.set(groupId, group);
+		for (const id of agentIds) {
+			this.agentToGroup.set(id, groupId);
+		}
+	}
+
+	/**
+	 * Called when an agent completes.
+	 * Returns:
+	 * - 'pass'      — agent is not grouped, caller should send individual nudge
+	 * - 'held'      — result held, waiting for group completion
+	 * - 'delivered'  — this completion triggered the group notification
+	 */
+	onAgentComplete(record: AgentRecord): "delivered" | "held" | "pass" {
+		const groupId = this.agentToGroup.get(record.id);
+		if (!groupId) return "pass";
+
+		const group = this.groups.get(groupId);
+		if (!group || group.delivered) return "pass";
+
+		group.completedRecords.set(record.id, record);
+
+		// All done — deliver immediately
+		if (group.completedRecords.size >= group.agentIds.size) {
+			this.deliver(group, false);
+			return "delivered";
+		}
+
+		// First completion in this batch — start timeout
+		if (!group.timeoutHandle) {
+			const timeout = group.isStraggler ? STRAGGLER_TIMEOUT : this.groupTimeout;
+			group.timeoutHandle = setTimeout(() => {
+				this.onTimeout(group);
+			}, timeout);
+		}
+
+		return "held";
+	}
+
+	private onTimeout(group: AgentGroup): void {
+		if (group.delivered) return;
+		group.timeoutHandle = undefined;
+
+		// Partial delivery — some agents still running
+		const remaining = new Set<string>();
+		for (const id of group.agentIds) {
+			if (!group.completedRecords.has(id)) remaining.add(id);
+		}
+
+		// Clean up agentToGroup for delivered agents (they won't complete again)
+		for (const id of group.completedRecords.keys()) {
+			this.agentToGroup.delete(id);
+		}
+
+		// Deliver what we have
+		this.deliverCb([...group.completedRecords.values()], true);
+
+		// Set up straggler group for remaining agents
+		group.completedRecords.clear();
+		group.agentIds = remaining;
+		group.isStraggler = true;
+		// Timeout will be started when the next straggler completes
+	}
+
+	private deliver(group: AgentGroup, partial: boolean): void {
+		if (group.timeoutHandle) {
+			clearTimeout(group.timeoutHandle);
+			group.timeoutHandle = undefined;
+		}
+		group.delivered = true;
+		this.deliverCb([...group.completedRecords.values()], partial);
+		this.cleanupGroup(group.groupId);
+	}
+
+	private cleanupGroup(groupId: string): void {
+		const group = this.groups.get(groupId);
+		if (!group) return;
+		for (const id of group.agentIds) {
+			this.agentToGroup.delete(id);
+		}
+		this.groups.delete(groupId);
+	}
+
+	/** Check if an agent is in a group. */
+	isGrouped(agentId: string): boolean {
+		return this.agentToGroup.has(agentId);
+	}
+
+	dispose(): void {
+		for (const group of this.groups.values()) {
+			if (group.timeoutHandle) clearTimeout(group.timeoutHandle);
+		}
+		this.groups.clear();
+		this.agentToGroup.clear();
+	}
+}