@gotgenes/pi-subagents 1.0.0 → 1.0.2

package/dist/agent-types.js

@@ -1,136 +0,0 @@
-/**
- * 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.
- */
-import { DEFAULT_AGENTS } from "./default-agents.js";
-/** All known built-in tool names. */
-export const BUILTIN_TOOL_NAMES = ["read", "bash", "edit", "write", "grep", "find", "ls"];
-/** Unified runtime registry of all agents (defaults + user-defined). */
-const agents = new Map();
-/**
- * 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 in the registry but excluded from spawning.
- */
-export function registerAgents(userAgents) {
-    agents.clear();
-    // Start with defaults
-    for (const [name, config] of DEFAULT_AGENTS) {
-        agents.set(name, config);
-    }
-    // Overlay user agents (overrides defaults with same name)
-    for (const [name, config] of userAgents) {
-        agents.set(name, config);
-    }
-}
-/** Case-insensitive key resolution. */
-function resolveKey(name) {
-    if (agents.has(name))
-        return name;
-    const lower = name.toLowerCase();
-    for (const key of agents.keys()) {
-        if (key.toLowerCase() === lower)
-            return key;
-    }
-    return undefined;
-}
-/** Resolve a type name case-insensitively. Returns the canonical key or undefined. */
-export function resolveType(name) {
-    return resolveKey(name);
-}
-/** Get the agent config for a type (case-insensitive). */
-export function getAgentConfig(name) {
-    const key = resolveKey(name);
-    return key ? agents.get(key) : undefined;
-}
-/** Get all enabled type names (for spawning and tool descriptions). */
-export function getAvailableTypes() {
-    return [...agents.entries()]
-        .filter(([_, config]) => config.enabled !== false)
-        .map(([name]) => name);
-}
-/** Get all type names including disabled (for UI listing). */
-export function getAllTypes() {
-    return [...agents.keys()];
-}
-/** Get names of default agents currently in the registry. */
-export function getDefaultAgentNames() {
-    return [...agents.entries()]
-        .filter(([_, config]) => config.isDefault === true)
-        .map(([name]) => name);
-}
-/** Get names of user-defined agents (non-defaults) currently in the registry. */
-export function getUserAgentNames() {
-    return [...agents.entries()]
-        .filter(([_, config]) => config.isDefault !== true)
-        .map(([name]) => name);
-}
-/** Check if a type is valid and enabled (case-insensitive). */
-export function isValidType(type) {
-    const key = resolveKey(type);
-    if (!key)
-        return false;
-    return agents.get(key)?.enabled !== false;
-}
-/** Tool names required for memory management. */
-const MEMORY_TOOL_NAMES = ["read", "write", "edit"];
-/**
- * Get memory tool names (read/write/edit) not already in the provided set.
- */
-export function getMemoryToolNames(existingToolNames) {
-    return MEMORY_TOOL_NAMES.filter(n => !existingToolNames.has(n));
-}
-/** Tool names needed for read-only memory access. */
-const READONLY_MEMORY_TOOL_NAMES = ["read"];
-/**
- * Get read-only memory tool names not already in the provided set.
- */
-export function getReadOnlyMemoryToolNames(existingToolNames) {
-    return READONLY_MEMORY_TOOL_NAMES.filter(n => !existingToolNames.has(n));
-}
-/** Get built-in tool names for a type (case-insensitive). */
-export function getToolNamesForType(type) {
-    const key = resolveKey(type);
-    const raw = key ? agents.get(key) : undefined;
-    const config = raw?.enabled !== false ? raw : undefined;
-    const names = config?.builtinToolNames?.length ? config.builtinToolNames : [...BUILTIN_TOOL_NAMES];
-    return names;
-}
-/** Get config for a type (case-insensitive, returns a SubagentTypeConfig-compatible object). Falls back to general-purpose. */
-export function getConfig(type) {
-    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,
-            skills: config.skills,
-            promptMode: config.promptMode,
-        };
-    }
-    // Fallback for unknown/disabled types — general-purpose config
-    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,
-            skills: gp.skills,
-            promptMode: gp.promptMode,
-        };
-    }
-    // Absolute fallback (should never happen)
-    return {
-        displayName: "Agent",
-        description: "General-purpose agent for complex, multi-step tasks",
-        builtinToolNames: BUILTIN_TOOL_NAMES,
-        extensions: true,
-        skills: true,
-        promptMode: "append",
-    };
-}

package/dist/context.d.ts

@@ -1,12 +0,0 @@
-/**
- * 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 declare function extractText(content: unknown[]): string;
-/**
- * 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 declare function buildParentContext(ctx: ExtensionContext): string;

package/dist/context.js

@@ -1,56 +0,0 @@
-/**
- * context.ts — Extract parent conversation context for subagent inheritance.
- */
-/** Extract text from a message content block array. */
-export function extractText(content) {
-    return content
-        .filter((c) => c.type === "text")
-        .map((c) => 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) {
-    const entries = ctx.sessionManager.getBranch();
-    if (!entries || entries.length === 0)
-        return "";
-    const parts = [];
-    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/dist/cross-extension-rpc.d.ts

@@ -1,46 +0,0 @@
-/**
- * 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

@@ -1,54 +0,0 @@
-/**
- * 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

@@ -1,14 +0,0 @@
-/**
- * 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

@@ -1,127 +0,0 @@
-/**
- * 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

@@ -1,7 +0,0 @@
-/**
- * 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

@@ -1,119 +0,0 @@
-/**
- * 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

@@ -1,6 +0,0 @@
-/**
- * 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

@@ -1,28 +0,0 @@
-/**
- * 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

@@ -1,32 +0,0 @@
-/**
- * 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;
-}