@tintinweb/pi-subagents 0.3.1 → 0.4.1

package/dist/agent-runner.js

@@ -0,0 +1,265 @@
+/**
+ * agent-runner.ts — Core execution engine: creates sessions, runs agents, collects results.
+ */
+import { createAgentSession, DefaultResourceLoader, SessionManager, SettingsManager, } from "@mariozechner/pi-coding-agent";
+import { getToolsForType, getConfig, getAgentConfig } from "./agent-types.js";
+import { buildAgentPrompt } from "./prompts.js";
+import { buildParentContext, extractText } from "./context.js";
+import { detectEnv } from "./env.js";
+/** Names of tools registered by this extension that subagents must NOT inherit. */
+const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
+/** Default max turns to prevent subagents from looping indefinitely. */
+let defaultMaxTurns = 50;
+/** Get the default max turns value. */
+export function getDefaultMaxTurns() { return defaultMaxTurns; }
+/** Set the default max turns value (minimum 1). */
+export function setDefaultMaxTurns(n) { defaultMaxTurns = Math.max(1, n); }
+/** Additional turns allowed after the soft limit steer message. */
+let graceTurns = 5;
+/** Get the grace turns value. */
+export function getGraceTurns() { return graceTurns; }
+/** Set the grace turns value (minimum 1). */
+export function setGraceTurns(n) { graceTurns = Math.max(1, n); }
+/**
+ * Try to find the right model for an agent type.
+ * Priority: explicit option > config.model > parent model.
+ */
+function resolveDefaultModel(parentModel, registry, configModel) {
+    if (configModel) {
+        const slashIdx = configModel.indexOf("/");
+        if (slashIdx !== -1) {
+            const provider = configModel.slice(0, slashIdx);
+            const modelId = configModel.slice(slashIdx + 1);
+            // Build a set of available model keys for fast lookup
+            const available = registry.getAvailable?.();
+            const availableKeys = available
+                ? new Set(available.map((m) => `${m.provider}/${m.id}`))
+                : undefined;
+            const isAvailable = (p, id) => !availableKeys || availableKeys.has(`${p}/${id}`);
+            const found = registry.find(provider, modelId);
+            if (found && isAvailable(provider, modelId))
+                return found;
+        }
+    }
+    return parentModel;
+}
+/**
+ * Subscribe to a session and collect the last assistant message text.
+ * Returns an object with a `getText()` getter and an `unsubscribe` function.
+ */
+function collectResponseText(session) {
+    let text = "";
+    const unsubscribe = session.subscribe((event) => {
+        if (event.type === "message_start") {
+            text = "";
+        }
+        if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+            text += event.assistantMessageEvent.delta;
+        }
+    });
+    return { getText: () => text, unsubscribe };
+}
+/**
+ * Wire an AbortSignal to abort a session.
+ * Returns a cleanup function to remove the listener.
+ */
+function forwardAbortSignal(session, signal) {
+    if (!signal)
+        return () => { };
+    const onAbort = () => session.abort();
+    signal.addEventListener("abort", onAbort, { once: true });
+    return () => signal.removeEventListener("abort", onAbort);
+}
+export async function runAgent(ctx, type, prompt, options) {
+    const config = getConfig(type);
+    const agentConfig = getAgentConfig(type);
+    const env = await detectEnv(options.pi, ctx.cwd);
+    // Get parent system prompt for append-mode agents
+    const parentSystemPrompt = ctx.getSystemPrompt();
+    // Build system prompt from agent config
+    let systemPrompt;
+    if (agentConfig) {
+        systemPrompt = buildAgentPrompt(agentConfig, ctx.cwd, env, parentSystemPrompt);
+    }
+    else {
+        // Unknown type fallback: general-purpose (defensive — unreachable in practice
+        // since index.ts resolves unknown types to "general-purpose" before calling runAgent)
+        systemPrompt = buildAgentPrompt({
+            name: type,
+            description: "General-purpose agent",
+            systemPrompt: "",
+            promptMode: "append",
+            extensions: true,
+            skills: true,
+            inheritContext: false,
+            runInBackground: false,
+            isolated: false,
+        }, ctx.cwd, env, parentSystemPrompt);
+    }
+    const tools = getToolsForType(type, ctx.cwd);
+    // Resolve extensions/skills: isolated overrides to false
+    const extensions = options.isolated ? false : config.extensions;
+    const skills = options.isolated ? false : config.skills;
+    // Load extensions/skills: true or string[] → load; false → don't
+    const loader = new DefaultResourceLoader({
+        cwd: ctx.cwd,
+        noExtensions: extensions === false,
+        noSkills: skills === false,
+        noPromptTemplates: true,
+        noThemes: true,
+        systemPromptOverride: () => systemPrompt,
+    });
+    await loader.reload();
+    // Resolve model: explicit option > config.model > parent model
+    const model = options.model ?? resolveDefaultModel(ctx.model, ctx.modelRegistry, agentConfig?.model);
+    // Resolve thinking level: explicit option > agent config > undefined (inherit)
+    const thinkingLevel = options.thinkingLevel ?? agentConfig?.thinking;
+    const sessionOpts = {
+        cwd: ctx.cwd,
+        sessionManager: SessionManager.inMemory(ctx.cwd),
+        settingsManager: SettingsManager.create(),
+        modelRegistry: ctx.modelRegistry,
+        model,
+        tools,
+        resourceLoader: loader,
+    };
+    if (thinkingLevel) {
+        sessionOpts.thinkingLevel = thinkingLevel;
+    }
+    // createAgentSession's type signature may not include thinkingLevel yet
+    const { session } = await createAgentSession(sessionOpts);
+    // Filter active tools: remove our own tools to prevent nesting,
+    // and apply extension allowlist if specified
+    if (extensions !== false) {
+        const builtinToolNames = new Set(tools.map(t => t.name));
+        const activeTools = session.getActiveToolNames().filter((t) => {
+            if (EXCLUDED_TOOL_NAMES.includes(t))
+                return false;
+            if (builtinToolNames.has(t))
+                return true;
+            if (Array.isArray(extensions)) {
+                return extensions.some(ext => t.startsWith(ext) || t.includes(ext));
+            }
+            return true;
+        });
+        session.setActiveToolsByName(activeTools);
+    }
+    options.onSessionCreated?.(session);
+    // Track turns for graceful max_turns enforcement
+    let turnCount = 0;
+    const maxTurns = options.maxTurns ?? agentConfig?.maxTurns ?? defaultMaxTurns;
+    let softLimitReached = false;
+    let aborted = false;
+    let currentMessageText = "";
+    const unsubTurns = session.subscribe((event) => {
+        if (event.type === "turn_end") {
+            turnCount++;
+            if (!softLimitReached && turnCount >= maxTurns) {
+                softLimitReached = true;
+                session.steer("You have reached your turn limit. Wrap up immediately — provide your final answer now.");
+            }
+            else if (softLimitReached && turnCount >= maxTurns + graceTurns) {
+                aborted = true;
+                session.abort();
+            }
+        }
+        if (event.type === "message_start") {
+            currentMessageText = "";
+        }
+        if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+            currentMessageText += event.assistantMessageEvent.delta;
+            options.onTextDelta?.(event.assistantMessageEvent.delta, currentMessageText);
+        }
+        if (event.type === "tool_execution_start") {
+            options.onToolActivity?.({ type: "start", toolName: event.toolName });
+        }
+        if (event.type === "tool_execution_end") {
+            options.onToolActivity?.({ type: "end", toolName: event.toolName });
+        }
+    });
+    const collector = collectResponseText(session);
+    const cleanupAbort = forwardAbortSignal(session, options.signal);
+    // Build the effective prompt: optionally prepend parent context
+    let effectivePrompt = prompt;
+    if (options.inheritContext) {
+        const parentContext = buildParentContext(ctx);
+        if (parentContext) {
+            effectivePrompt = parentContext + prompt;
+        }
+    }
+    try {
+        await session.prompt(effectivePrompt);
+    }
+    finally {
+        unsubTurns();
+        collector.unsubscribe();
+        cleanupAbort();
+    }
+    return { responseText: collector.getText(), session, aborted, steered: softLimitReached };
+}
+/**
+ * Send a new prompt to an existing session (resume).
+ */
+export async function resumeAgent(session, prompt, options = {}) {
+    const collector = collectResponseText(session);
+    const cleanupAbort = forwardAbortSignal(session, options.signal);
+    const unsubToolUse = options.onToolActivity
+        ? session.subscribe((event) => {
+            if (event.type === "tool_execution_start")
+                options.onToolActivity({ type: "start", toolName: event.toolName });
+            if (event.type === "tool_execution_end")
+                options.onToolActivity({ type: "end", toolName: event.toolName });
+        })
+        : () => { };
+    try {
+        await session.prompt(prompt);
+    }
+    finally {
+        collector.unsubscribe();
+        unsubToolUse();
+        cleanupAbort();
+    }
+    return collector.getText();
+}
+/**
+ * Send a steering message to a running subagent.
+ * The message will interrupt the agent after its current tool execution.
+ */
+export async function steerAgent(session, message) {
+    await session.steer(message);
+}
+/**
+ * Get the subagent's conversation messages as formatted text.
+ */
+export function getAgentConversation(session) {
+    const parts = [];
+    for (const msg of session.messages) {
+        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 textParts = [];
+            const toolCalls = [];
+            for (const c of msg.content) {
+                if (c.type === "text" && c.text)
+                    textParts.push(c.text);
+                else if (c.type === "toolCall")
+                    toolCalls.push(`  Tool: ${c.toolName ?? "unknown"}`);
+            }
+            if (textParts.length > 0)
+                parts.push(`[Assistant]: ${textParts.join("\n")}`);
+            if (toolCalls.length > 0)
+                parts.push(`[Tool Calls]:\n${toolCalls.join("\n")}`);
+        }
+        else if (msg.role === "toolResult") {
+            const text = extractText(msg.content);
+            const truncated = text.length > 200 ? text.slice(0, 200) + "..." : text;
+            parts.push(`[Tool Result (${msg.toolName})]: ${truncated}`);
+        }
+    }
+    return parts.join("\n\n");
+}

package/dist/agent-types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 type { AgentTool } from "@mariozechner/pi-agent-core";
+import type { AgentConfig } from "./types.js";
+/** All known built-in tool names, derived from the factory registry. */
+export declare const BUILTIN_TOOL_NAMES: string[];
+/**
+ * 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 declare function registerAgents(userAgents: Map<string, AgentConfig>): void;
+/** Resolve a type name case-insensitively. Returns the canonical key or undefined. */
+export declare function resolveType(name: string): string | undefined;
+/** Get the agent config for a type (case-insensitive). */
+export declare function getAgentConfig(name: string): AgentConfig | undefined;
+/** Get all enabled type names (for spawning and tool descriptions). */
+export declare function getAvailableTypes(): string[];
+/** Get all type names including disabled (for UI listing). */
+export declare function getAllTypes(): string[];
+/** Get names of default agents currently in the registry. */
+export declare function getDefaultAgentNames(): string[];
+/** Get names of user-defined agents (non-defaults) currently in the registry. */
+export declare function getUserAgentNames(): string[];
+/** Check if a type is valid and enabled (case-insensitive). */
+export declare function isValidType(type: string): boolean;
+/** Get built-in tools for a type (case-insensitive). */
+export declare function getToolsForType(type: string, cwd: string): AgentTool<any>[];
+/** Get config for a type (case-insensitive, returns a SubagentTypeConfig-compatible object). Falls back to general-purpose. */
+export declare function getConfig(type: string): {
+    displayName: string;
+    description: string;
+    builtinToolNames: string[];
+    extensions: true | string[] | false;
+    skills: true | string[] | false;
+    promptMode: "replace" | "append";
+};

package/dist/agent-types.js

@@ -0,0 +1,130 @@
+/**
+ * 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 { createReadTool, createBashTool, createEditTool, createWriteTool, createGrepTool, createFindTool, createLsTool, } from "@mariozechner/pi-coding-agent";
+import { DEFAULT_AGENTS } from "./default-agents.js";
+const TOOL_FACTORIES = {
+    read: (cwd) => createReadTool(cwd),
+    bash: (cwd) => createBashTool(cwd),
+    edit: (cwd) => createEditTool(cwd),
+    write: (cwd) => createWriteTool(cwd),
+    grep: (cwd) => createGrepTool(cwd),
+    find: (cwd) => createFindTool(cwd),
+    ls: (cwd) => createLsTool(cwd),
+};
+/** All known built-in tool names, derived from the factory registry. */
+export const BUILTIN_TOOL_NAMES = Object.keys(TOOL_FACTORIES);
+/** 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;
+}
+/** Get built-in tools for a type (case-insensitive). */
+export function getToolsForType(type, cwd) {
+    const key = resolveKey(type);
+    const raw = key ? agents.get(key) : undefined;
+    const config = raw?.enabled !== false ? raw : undefined;
+    const toolNames = config?.builtinToolNames?.length ? config.builtinToolNames : BUILTIN_TOOL_NAMES;
+    return toolNames.filter((n) => n in TOOL_FACTORIES).map((n) => TOOL_FACTORIES[n](cwd));
+}
+/** 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

@@ -0,0 +1,12 @@
+/**
+ * context.ts — Extract parent conversation context for subagent inheritance.
+ */
+import type { ExtensionContext } from "@mariozechner/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

@@ -0,0 +1,56 @@
+/**
+ * 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/custom-agents.d.ts

@@ -0,0 +1,14 @@
+/**
+ * custom-agents.ts — Load user-defined agents from project (.pi/agents/) and global (~/.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/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,100 @@
+/**
+ * custom-agents.ts — Load user-defined agents from project (.pi/agents/) and global (~/.pi/agent/agents/) locations.
+ */
+import { parseFrontmatter } from "@mariozechner/pi-coding-agent";
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+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/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(homedir(), ".pi", "agent", "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),
+            extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
+            skills: inheritField(fm.skills ?? fm.inherit_skills),
+            model: str(fm.model),
+            thinking: str(fm.thinking),
+            maxTurns: positiveInt(fm.max_turns),
+            systemPrompt: body.trim(),
+            promptMode: fm.prompt_mode === "append" ? "append" : "replace",
+            inheritContext: fm.inherit_context === true,
+            runInBackground: fm.run_in_background === true,
+            isolated: fm.isolated === true,
+            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 positive integer or undefined. */
+function positiveInt(val) {
+    return typeof val === "number" && val >= 1 ? val : undefined;
+}
+/**
+ * Parse a comma-separated list field.
+ * omitted → defaults; "none"/empty → []; csv → listed items.
+ */
+function csvList(val, defaults) {
+    if (val === undefined || val === null)
+        return defaults;
+    const s = String(val).trim();
+    if (!s || s === "none")
+        return [];
+    return s.split(",").map(t => t.trim()).filter(Boolean);
+}
+/**
+ * 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>;