@gotgenes/pi-subagents 1.0.0

package/dist/cross-extension-rpc.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 }
+ */
+/** 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 declare 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;
+    getCtx: () => unknown | undefined;
+    manager: SpawnCapable;
+}
+export interface RpcHandle {
+    unsubPing: () => void;
+    unsubSpawn: () => void;
+    unsubStop: () => void;
+}
+/**
+ * Register ping, spawn, and stop RPC handlers on the event bus.
+ * Returns unsub functions for cleanup.
+ */
+export declare function registerRpcHandlers(deps: RpcDeps): RpcHandle;

package/dist/cross-extension-rpc.js

@@ -0,0 +1,54 @@
+/**
+ * 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 }
+ */
+/** RPC protocol version — bumped when the envelope or method contracts change. */
+export const PROTOCOL_VERSION = 2;
+/**
+ * Wire a single RPC handler: listen on `channel`, run `fn(params)`,
+ * emit the reply envelope on `channel:reply:${requestId}`.
+ */
+function handleRpc(events, channel, fn) {
+    return events.on(channel, async (raw) => {
+        const params = raw;
+        try {
+            const data = await fn(params);
+            const reply = { success: true };
+            if (data !== undefined)
+                reply.data = data;
+            events.emit(`${channel}:reply:${params.requestId}`, reply);
+        }
+        catch (err) {
+            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) {
+    const { events, pi, getCtx, manager } = deps;
+    const unsubPing = handleRpc(events, "subagents:rpc:ping", () => {
+        return { version: PROTOCOL_VERSION };
+    });
+    const unsubSpawn = handleRpc(events, "subagents:rpc:spawn", ({ type, prompt, options }) => {
+        const ctx = getCtx();
+        if (!ctx)
+            throw new Error("No active session");
+        return { id: manager.spawn(pi, ctx, type, prompt, options ?? {}) };
+    });
+    const unsubStop = handleRpc(events, "subagents:rpc:stop", ({ agentId }) => {
+        if (!manager.abort(agentId))
+            throw new Error("Agent not found");
+    });
+    return { unsubPing, unsubSpawn, unsubStop };
+}

package/dist/custom-agents.d.ts

@@ -0,0 +1,14 @@
+/**
+ * custom-agents.ts — Load user-defined agents from project (.pi/agents/) and global ($PI_CODING_AGENT_DIR/agents/, default ~/.pi/agent/agents/) locations.
+ */
+import type { AgentConfig } 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 declare function loadCustomAgents(cwd: string): Map<string, AgentConfig>;

package/dist/custom-agents.js

@@ -0,0 +1,127 @@
+/**
+ * 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";
+/**
+ * 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) {
+    const globalDir = join(getAgentDir(), "agents");
+    const projectDir = join(cwd, ".pi", "agents");
+    const agents = new Map();
+    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, agents, source) {
+    if (!existsSync(dir))
+        return;
+    let files;
+    try {
+        files = readdirSync(dir).filter(f => f.endsWith(".md"));
+    }
+    catch {
+        return;
+    }
+    for (const file of files) {
+        const name = basename(file, ".md");
+        let content;
+        try {
+            content = readFileSync(join(dir, file), "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const { frontmatter: fm, body } = parseFrontmatter(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),
+            thinking: str(fm.thinking),
+            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) {
+    return typeof val === "string" ? val : undefined;
+}
+/** Extract a non-negative integer or undefined. 0 means unlimited for max_turns. */
+function nonNegativeInt(val) {
+    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) {
+    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, defaults) {
+    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) {
+    return parseCsvField(val);
+}
+/**
+ * Parse a memory scope field.
+ * omitted → undefined; "user"/"project"/"local" → MemoryScope.
+ */
+function parseMemory(val) {
+    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) {
+    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/dist/default-agents.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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";
+export declare const DEFAULT_AGENTS: Map<string, AgentConfig>;

package/dist/default-agents.js

@@ -0,0 +1,119 @@
+/**
+ * default-agents.ts — Embedded default agent configurations.
+ *
+ * These are always available but can be overridden by user .md files with the same name.
+ */
+const READ_ONLY_TOOLS = ["read", "bash", "grep", "find", "ls"];
+export const DEFAULT_AGENTS = 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/dist/env.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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 declare function detectEnv(pi: ExtensionAPI, cwd: string): Promise<EnvInfo>;

package/dist/env.js

@@ -0,0 +1,28 @@
+/**
+ * env.ts — Detect environment info (git, platform) for subagent system prompts.
+ */
+export async function detectEnv(pi, cwd) {
+    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/dist/group-join.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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;
+export declare class GroupJoinManager {
+    private deliverCb;
+    private groupTimeout;
+    private groups;
+    private agentToGroup;
+    constructor(deliverCb: DeliveryCallback, groupTimeout?: number);
+    /** Register a group of agent IDs that should be joined. */
+    registerGroup(groupId: string, agentIds: string[]): void;
+    /**
+     * 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';
+    private onTimeout;
+    private deliver;
+    private cleanupGroup;
+    /** Check if an agent is in a group. */
+    isGrouped(agentId: string): boolean;
+    dispose(): void;
+}

package/dist/group-join.js

@@ -0,0 +1,116 @@
+/**
+ * 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.
+ */
+/** 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 {
+    deliverCb;
+    groupTimeout;
+    groups = new Map();
+    agentToGroup = new Map();
+    constructor(deliverCb, groupTimeout = DEFAULT_TIMEOUT) {
+        this.deliverCb = deliverCb;
+        this.groupTimeout = groupTimeout;
+    }
+    /** Register a group of agent IDs that should be joined. */
+    registerGroup(groupId, agentIds) {
+        const group = {
+            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) {
+        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';
+    }
+    onTimeout(group) {
+        if (group.delivered)
+            return;
+        group.timeoutHandle = undefined;
+        // Partial delivery — some agents still running
+        const remaining = new Set();
+        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
+    }
+    deliver(group, partial) {
+        if (group.timeoutHandle) {
+            clearTimeout(group.timeoutHandle);
+            group.timeoutHandle = undefined;
+        }
+        group.delivered = true;
+        this.deliverCb([...group.completedRecords.values()], partial);
+        this.cleanupGroup(group.groupId);
+    }
+    cleanupGroup(groupId) {
+        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) {
+        return this.agentToGroup.has(agentId);
+    }
+    dispose() {
+        for (const group of this.groups.values()) {
+            if (group.timeoutHandle)
+                clearTimeout(group.timeoutHandle);
+        }
+        this.groups.clear();
+        this.agentToGroup.clear();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * pi-agents — A pi extension providing Claude Code-style autonomous sub-agents.
+ *
+ * Tools:
+ *   Agent             — LLM-callable: spawn a sub-agent
+ *   get_subagent_result  — LLM-callable: check background agent status/result
+ *   steer_subagent       — LLM-callable: send a steering message to a running agent
+ *
+ * Commands:
+ *   /agents                 — Interactive agent management menu
+ */
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function (pi: ExtensionAPI): void;