@xynogen/pix-subagent 0.1.0

package/src/agent-types.ts

@@ -0,0 +1,152 @@
+/**
+ * agent-types.ts — Unified agent type registry.
+ *
+ * Merges embedded default agents with user-defined agents from .pi/agents/*.md.
+ * User agents override defaults with the same name. Disabled agents are kept
+ * but excluded from spawning.
+ *
+ * Ported from tintinweb/pi-subagents (MIT). Trimmed: dropped memory tool helpers.
+ */
+
+import {
+	createCodingTools,
+	createReadOnlyTools,
+} from "@earendil-works/pi-coding-agent";
+import { DEFAULT_AGENTS } from "./default-agents.ts";
+import type { AgentConfig } from "./types.ts";
+
+/**
+ * All known built-in tool names, derived from pi's own tool factories so the
+ * set tracks pi-mono if it adds/renames a built-in. The `cwd` only binds tool
+ * operations we never invoke — we read each tool's `.name` and discard it.
+ */
+export const BUILTIN_TOOL_NAMES: string[] = [
+	...new Set(
+		[...createCodingTools("."), ...createReadOnlyTools(".")].map((t) => t.name),
+	),
+];
+
+/** Unified runtime registry of all agents (defaults + user-defined). */
+const agents = new Map<string, AgentConfig>();
+
+/** When true, DEFAULT_AGENTS are skipped during registration. */
+let disableDefaults = false;
+
+export function isDefaultsDisabled(): boolean {
+	return disableDefaults;
+}
+
+export function setDefaultsDisabled(b: boolean): void {
+	disableDefaults = b;
+}
+
+/**
+ * Register agents into the unified registry.
+ * Starts with DEFAULT_AGENTS, then overlays user agents (overrides defaults with same name).
+ * Disabled agents (enabled === false) are kept but excluded from spawning.
+ */
+export function registerAgents(userAgents: Map<string, AgentConfig>): void {
+	agents.clear();
+
+	if (!disableDefaults) {
+		for (const [name, config] of DEFAULT_AGENTS) {
+			agents.set(name, config);
+		}
+	}
+
+	for (const [name, config] of userAgents) {
+		agents.set(name, config);
+	}
+}
+
+/** Case-insensitive key resolution. */
+function resolveKey(name: string): string | undefined {
+	if (agents.has(name)) return name;
+	const lower = name.toLowerCase();
+	for (const key of agents.keys()) {
+		if (key.toLowerCase() === lower) return key;
+	}
+	return undefined;
+}
+
+export function resolveType(name: string): string | undefined {
+	return resolveKey(name);
+}
+
+export function getAgentConfig(name: string): AgentConfig | undefined {
+	const key = resolveKey(name);
+	return key ? agents.get(key) : undefined;
+}
+
+/** Get all enabled type names (for spawning and tool descriptions). */
+export function getAvailableTypes(): string[] {
+	return [...agents.entries()]
+		.filter(([, config]) => config.enabled !== false)
+		.map(([name]) => name);
+}
+
+export function getAllTypes(): string[] {
+	return [...agents.keys()];
+}
+
+export function isValidType(type: string): boolean {
+	const key = resolveKey(type);
+	if (!key) return false;
+	return agents.get(key)?.enabled !== false;
+}
+
+/** Get built-in tool names for a type (case-insensitive). */
+export function getToolNamesForType(type: string): string[] {
+	const key = resolveKey(type);
+	const raw = key ? agents.get(key) : undefined;
+	const config = raw?.enabled !== false ? raw : undefined;
+	// undefined → all built-ins; explicit [] → zero built-ins.
+	return config?.builtinToolNames ?? [...BUILTIN_TOOL_NAMES];
+}
+
+/** Get config for a type, falling back to general-purpose. */
+export function getConfig(type: string): {
+	displayName: string;
+	description: string;
+	builtinToolNames: string[];
+	extensions: true | string[] | false;
+	excludeExtensions?: string[];
+	skills: true | string[] | false;
+	promptMode: "replace" | "append";
+} {
+	const key = resolveKey(type);
+	const config = key ? agents.get(key) : undefined;
+	if (config && config.enabled !== false) {
+		return {
+			displayName: config.displayName ?? config.name,
+			description: config.description,
+			builtinToolNames: config.builtinToolNames ?? BUILTIN_TOOL_NAMES,
+			extensions: config.extensions,
+			excludeExtensions: config.excludeExtensions,
+			skills: config.skills,
+			promptMode: config.promptMode,
+		};
+	}
+
+	const gp = agents.get("general-purpose");
+	if (gp && gp.enabled !== false) {
+		return {
+			displayName: gp.displayName ?? gp.name,
+			description: gp.description,
+			builtinToolNames: gp.builtinToolNames ?? BUILTIN_TOOL_NAMES,
+			extensions: gp.extensions,
+			excludeExtensions: gp.excludeExtensions,
+			skills: gp.skills,
+			promptMode: gp.promptMode,
+		};
+	}
+
+	return {
+		displayName: "Agent",
+		description: "General-purpose agent for complex, multi-step tasks",
+		builtinToolNames: BUILTIN_TOOL_NAMES,
+		extensions: true,
+		skills: true,
+		promptMode: "append",
+	};
+}

package/src/context.ts

@@ -0,0 +1,59 @@
+/**
+ * context.ts — Extract parent conversation context for subagent inheritance.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/** Extract text from a message content block array. */
+export function extractText(content: unknown[]): string {
+	return content
+		.filter((c: any) => c.type === "text")
+		.map((c: any) => c.text ?? "")
+		.join("\n");
+}
+
+/**
+ * Build a text representation of the parent conversation context.
+ * Used when inherit_context is true to give the subagent visibility
+ * into what has been discussed/done so far.
+ */
+export function buildParentContext(ctx: ExtensionContext): string {
+	const entries = ctx.sessionManager.getBranch();
+	if (!entries || entries.length === 0) return "";
+
+	const parts: string[] = [];
+
+	for (const entry of entries) {
+		if (entry.type === "message") {
+			const msg = entry.message;
+			if (msg.role === "user") {
+				const text =
+					typeof msg.content === "string"
+						? msg.content
+						: extractText(msg.content);
+				if (text.trim()) parts.push(`[User]: ${text.trim()}`);
+			} else if (msg.role === "assistant") {
+				const text = extractText(msg.content);
+				if (text.trim()) parts.push(`[Assistant]: ${text.trim()}`);
+			}
+			// Skip toolResult messages — too verbose for context
+		} else if (entry.type === "compaction") {
+			// Include compaction summaries — they're already condensed
+			if (entry.summary) {
+				parts.push(`[Summary]: ${entry.summary}`);
+			}
+		}
+	}
+
+	if (parts.length === 0) return "";
+
+	return `# Parent Conversation Context
+The following is the conversation history from the parent session that spawned you.
+Use this context to understand what has been discussed and decided so far.
+
+${parts.join("\n\n")}
+
+---
+# Your Task (below)
+`;
+}

package/src/custom-agents.ts

@@ -0,0 +1,165 @@
+/**
+ * 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.ts";
+import type { AgentConfig, ThinkingLevel } from "./types.ts";
+
+/**
+ * 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);
+
+		const { builtinToolNames, extSelectors } = parseToolsField(fm.tools);
+
+		agents.set(name, {
+			name,
+			displayName: str(fm.display_name),
+			description: str(fm.description) ?? name,
+			builtinToolNames,
+			extSelectors,
+			disallowedTools: csvListOptional(fm.disallowed_tools),
+			extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
+			excludeExtensions: csvListOptional(fm.exclude_extensions),
+			skills: inheritField(fm.skills ?? fm.inherit_skills),
+			model: str(fm.model),
+			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,
+			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) ?? [];
+}
+
+/**
+ * Partition the `tools:` CSV into the built-in tool allowlist and raw `ext:` selectors.
+ * `*` (and the case-insensitive alias `all`, for `tools: all`) expands to all
+ * built-ins; plain entries are built-in names; `ext:` entries are extension-tool
+ * selectors parsed later by the runner. omitted → all built-ins, no selectors.
+ * `tools:` present with only `ext:` entries → zero built-ins (use `*`).
+ */
+function parseToolsField(val: unknown): {
+	builtinToolNames: string[];
+	extSelectors: string[] | undefined;
+} {
+	const entries = csvList(val, BUILTIN_TOOL_NAMES);
+	const isWildcard = (e: string) => e === "*" || e.toLowerCase() === "all";
+	const hasWildcard = entries.some(isWildcard);
+	const plain = entries.filter((e) => !isWildcard(e) && !e.startsWith("ext:"));
+	const extEntries = entries.filter((e) => e.startsWith("ext:"));
+	return {
+		builtinToolNames: hasWildcard
+			? [...new Set([...BUILTIN_TOOL_NAMES, ...plain])]
+			: plain,
+		extSelectors: extEntries.length > 0 ? extEntries : undefined,
+	};
+}
+
+/**
+ * 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 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,126 @@
+/**
+ * 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.ts";
+
+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 researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you.",
+			// 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 read-only search agent for locating code. Use it to find files by pattern (eg. "src/components/**/*.tsx"), grep for symbols or keywords (eg. "API endpoints"), or answer "where is X defined / which files reference Y." Do NOT use it for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis — it reads excerpts rather than whole files and will miss content past its read window. When calling, specify search breadth: "quick" for a single targeted lookup, "medium" for moderate exploration, or "very thorough" to search across multiple locations and naming conventions.',
+			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 agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.",
+			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,43 @@
+/**
+ * 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/extension.ts

@@ -0,0 +1,9 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import registerPixSubagent from "./index.ts";
+import { once } from "./once.ts";
+
+export default function pixSubagentExtension(pi: ExtensionAPI): void {
+	once(pi, "pix-subagent", () => {
+		registerPixSubagent(pi);
+	});
+}