@tintinweb/pi-subagents 0.2.0

package/src/agent-runner.ts

@@ -0,0 +1,341 @@
+/**
+ * agent-runner.ts — Core execution engine: creates sessions, runs agents, collects results.
+ */
+
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  SessionManager,
+  SettingsManager,
+  type AgentSession,
+  type AgentSessionEvent,
+  type ExtensionAPI,
+} from "@mariozechner/pi-coding-agent";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { Model } from "@mariozechner/pi-ai";
+import { getToolsForType, getConfig, getCustomAgentConfig } from "./agent-types.js";
+import { buildSystemPrompt } from "./prompts.js";
+import { buildParentContext, extractText } from "./context.js";
+import { detectEnv } from "./env.js";
+import type { SubagentType, ThinkingLevel } from "./types.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. */
+const DEFAULT_MAX_TURNS = 50;
+
+/** Additional turns allowed after the soft limit steer message. */
+const GRACE_TURNS = 5;
+
+/** Haiku model IDs to try for Explore agents (in preference order). */
+const HAIKU_MODEL_IDS = [
+  "claude-haiku-4-5-20251001",
+  "claude-3-5-haiku-20241022",
+];
+
+/**
+ * Try to find the right model for an agent type.
+ * Priority: explicit option > custom agent model > type-specific default > parent model.
+ */
+function resolveDefaultModel(
+  type: SubagentType,
+  parentModel: Model<any> | undefined,
+  registry: { find(provider: string, modelId: string): Model<any> | undefined; getAvailable?(): Model<any>[] },
+  customModel?: string,
+): Model<any> | undefined {
+  // Build a set of available model keys for fast lookup
+  const available = registry.getAvailable?.();
+  const availableKeys = available
+    ? new Set(available.map((m: any) => `${m.provider}/${m.id}`))
+    : undefined;
+  const isAvailable = (provider: string, modelId: string) =>
+    !availableKeys || availableKeys.has(`${provider}/${modelId}`);
+
+  // Custom agent model from frontmatter
+  if (customModel) {
+    const slashIdx = customModel.indexOf("/");
+    if (slashIdx !== -1) {
+      const provider = customModel.slice(0, slashIdx);
+      const modelId = customModel.slice(slashIdx + 1);
+      const found = registry.find(provider, modelId);
+      if (found && isAvailable(provider, modelId)) return found;
+    }
+  }
+
+  if (type !== "Explore") return parentModel;
+
+  for (const modelId of HAIKU_MODEL_IDS) {
+    const found = registry.find("anthropic", modelId);
+    if (found && isAvailable("anthropic", modelId)) return found;
+  }
+  return parentModel;
+}
+
+/** Info about a tool event in the subagent. */
+export interface ToolActivity {
+  type: "start" | "end";
+  toolName: string;
+}
+
+export interface RunOptions {
+  /** ExtensionAPI instance — used for pi.exec() instead of execSync. */
+  pi: ExtensionAPI;
+  model?: Model<any>;
+  maxTurns?: number;
+  signal?: AbortSignal;
+  isolated?: boolean;
+  inheritContext?: boolean;
+  thinkingLevel?: ThinkingLevel;
+  /** Override system prompt entirely (for custom agents with promptMode: "replace"). */
+  systemPromptOverride?: string;
+  /** Append to default system prompt (for custom agents with promptMode: "append"). */
+  systemPromptAppend?: string;
+  /** Called on tool start/end with activity info. */
+  onToolActivity?: (activity: ToolActivity) => void;
+  /** Called on streaming text deltas from the assistant response. */
+  onTextDelta?: (delta: string, fullText: string) => void;
+  onSessionCreated?: (session: AgentSession) => void;
+}
+
+export interface RunResult {
+  responseText: string;
+  session: AgentSession;
+  /** True if the agent was hard-aborted (max_turns + grace exceeded). */
+  aborted: boolean;
+  /** True if the agent was steered to wrap up (hit soft turn limit) but finished in time. */
+  steered: boolean;
+}
+
+/**
+ * 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: AgentSession) {
+  let text = "";
+  const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+    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: AgentSession, signal?: AbortSignal): () => void {
+  if (!signal) return () => {};
+  const onAbort = () => session.abort();
+  signal.addEventListener("abort", onAbort, { once: true });
+  return () => signal.removeEventListener("abort", onAbort);
+}
+
+export async function runAgent(
+  ctx: ExtensionContext,
+  type: SubagentType,
+  prompt: string,
+  options: RunOptions,
+): Promise<RunResult> {
+  const config = getConfig(type);
+  const customConfig = getCustomAgentConfig(type);
+  const env = await detectEnv(options.pi, ctx.cwd);
+
+  // Build system prompt: custom override > custom append > built-in
+  let systemPrompt: string;
+  if (options.systemPromptOverride) {
+    systemPrompt = options.systemPromptOverride;
+  } else if (options.systemPromptAppend) {
+    systemPrompt = buildSystemPrompt(type, ctx.cwd, env) + "\n\n" + options.systemPromptAppend;
+  } else {
+    systemPrompt = buildSystemPrompt(type, ctx.cwd, env);
+  }
+
+  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 > custom agent config > type-specific default > parent model
+  const model = options.model ?? resolveDefaultModel(
+    type, ctx.model, ctx.modelRegistry, customConfig?.model,
+  );
+
+  // Resolve thinking level: explicit option > custom agent config > undefined (inherit)
+  const thinkingLevel = options.thinkingLevel ?? customConfig?.thinking;
+
+  const sessionOpts: Record<string, unknown> = {
+    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 as Parameters<typeof createAgentSession>[0]);
+
+  // 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 ?? customConfig?.maxTurns ?? DEFAULT_MAX_TURNS;
+  let softLimitReached = false;
+  let aborted = false;
+
+  let currentMessageText = "";
+  const unsubTurns = session.subscribe((event: AgentSessionEvent) => {
+    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 + GRACE_TURNS) {
+        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: AgentSession,
+  prompt: string,
+  options: { onToolActivity?: (activity: ToolActivity) => void; signal?: AbortSignal } = {},
+): Promise<string> {
+  const collector = collectResponseText(session);
+  const cleanupAbort = forwardAbortSignal(session, options.signal);
+
+  const unsubToolUse = options.onToolActivity
+    ? session.subscribe((event: AgentSessionEvent) => {
+        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: AgentSession,
+  message: string,
+): Promise<void> {
+  await session.steer(message);
+}
+
+/**
+ * Get the subagent's conversation messages as formatted text.
+ */
+export function getAgentConversation(session: AgentSession): string {
+  const parts: string[] = [];
+
+  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: string[] = [];
+      const toolCalls: string[] = [];
+      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 as any).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/src/agent-types.ts

@@ -0,0 +1,137 @@
+/**
+ * agent-types.ts — Agent type registry: tool sets and configs per subagent type.
+ *
+ * Supports both built-in types and custom agents loaded from .pi/agents/*.md.
+ */
+
+import {
+  createReadTool,
+  createBashTool,
+  createEditTool,
+  createWriteTool,
+  createGrepTool,
+  createFindTool,
+  createLsTool,
+} from "@mariozechner/pi-coding-agent";
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import type { BuiltinSubagentType, SubagentType, SubagentTypeConfig, CustomAgentConfig } from "./types.js";
+
+type ToolFactory = (cwd: string) => AgentTool<any>;
+
+const TOOL_FACTORIES: Record<string, ToolFactory> = {
+  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);
+
+const BUILTIN_CONFIGS: Record<BuiltinSubagentType, SubagentTypeConfig> = {
+  "general-purpose": {
+    displayName: "Agent",
+    description: "General-purpose agent for complex, multi-step tasks",
+    builtinToolNames: BUILTIN_TOOL_NAMES,
+    extensions: true,
+    skills: true,
+  },
+  "Explore": {
+    displayName: "Explore",
+    description: "Fast codebase exploration agent (read-only)",
+    builtinToolNames: ["read", "bash", "grep", "find", "ls"],
+    extensions: true,
+    skills: true,
+  },
+  "Plan": {
+    displayName: "Plan",
+    description: "Software architect for implementation planning (read-only)",
+    builtinToolNames: ["read", "bash", "grep", "find", "ls"],
+    extensions: true,
+    skills: true,
+  },
+  "statusline-setup": {
+    displayName: "Config",
+    description: "Configuration editor (read + edit only)",
+    builtinToolNames: ["read", "edit"],
+    extensions: false,
+    skills: false,
+  },
+  "claude-code-guide": {
+    displayName: "Guide",
+    description: "Documentation and help queries",
+    builtinToolNames: ["read", "grep", "find"],
+    extensions: false,
+    skills: false,
+  },
+};
+
+/** Runtime registry of custom agent configs. */
+const customAgents = new Map<string, CustomAgentConfig>();
+
+/** Register custom agents into the runtime registry. */
+export function registerCustomAgents(agents: Map<string, CustomAgentConfig>): void {
+  customAgents.clear();
+  for (const [name, config] of agents) {
+    customAgents.set(name, config);
+  }
+}
+
+/** Get the custom agent config if it exists. */
+export function getCustomAgentConfig(name: string): CustomAgentConfig | undefined {
+  return customAgents.get(name);
+}
+
+/** Get all available type names (built-in + custom). */
+export function getAvailableTypes(): string[] {
+  return [...Object.keys(BUILTIN_CONFIGS), ...customAgents.keys()];
+}
+
+/** Get all custom agent names. */
+export function getCustomAgentNames(): string[] {
+  return [...customAgents.keys()];
+}
+
+/** Check if a type is valid (built-in or custom). */
+export function isValidType(type: string): boolean {
+  return type in BUILTIN_CONFIGS || customAgents.has(type);
+}
+
+/** Get built-in tools for a type. Works for both built-in and custom agents. */
+export function getToolsForType(type: SubagentType, cwd: string): AgentTool<any>[] {
+  const config = BUILTIN_CONFIGS[type as BuiltinSubagentType];
+  if (config) {
+    return config.builtinToolNames.map((n) => TOOL_FACTORIES[n](cwd));
+  }
+  const custom = customAgents.get(type);
+  if (custom) {
+    return custom.builtinToolNames
+      .filter((n) => n in TOOL_FACTORIES)
+      .map((n) => TOOL_FACTORIES[n](cwd));
+  }
+  // Fallback: all tools
+  return BUILTIN_TOOL_NAMES.map((n) => TOOL_FACTORIES[n](cwd));
+}
+
+/** Get config for a type. Works for both built-in and custom agents. */
+export function getConfig(type: SubagentType): SubagentTypeConfig {
+  const builtin = BUILTIN_CONFIGS[type as BuiltinSubagentType];
+  if (builtin) return builtin;
+
+  const custom = customAgents.get(type);
+  if (custom) {
+    return {
+      displayName: custom.name,
+      description: custom.description,
+      builtinToolNames: custom.builtinToolNames,
+      extensions: custom.extensions,
+      skills: custom.skills,
+    };
+  }
+
+  // Fallback for unknown types — general-purpose config
+  return BUILTIN_CONFIGS["general-purpose"];
+}

package/src/context.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 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,94 @@
+/**
+ * custom-agents.ts — Load user-defined agents from .pi/agents/*.md files.
+ */
+
+import { parseFrontmatter } from "@mariozechner/pi-coding-agent";
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, basename } from "node:path";
+import { SUBAGENT_TYPES, type CustomAgentConfig, type ThinkingLevel } from "./types.js";
+import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
+
+/**
+ * Scan .pi/agents/*.md and return a map of custom agent configs.
+ * Filename (without .md) becomes the agent name.
+ */
+export function loadCustomAgents(cwd: string): Map<string, CustomAgentConfig> {
+  const dir = join(cwd, ".pi", "agents");
+  if (!existsSync(dir)) return new Map();
+
+  let files: string[];
+  try {
+    files = readdirSync(dir).filter(f => f.endsWith(".md"));
+  } catch {
+    return new Map();
+  }
+
+  const agents = new Map<string, CustomAgentConfig>();
+
+  for (const file of files) {
+    const name = basename(file, ".md");
+    if ((SUBAGENT_TYPES as readonly string[]).includes(name)) continue;
+
+    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,
+      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) as ThinkingLevel | undefined,
+      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,
+    });
+  }
+
+  return agents;
+}
+
+// ---- 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 positive integer or undefined. */
+function positiveInt(val: unknown): number | undefined {
+  return typeof val === "number" && val >= 1 ? val : undefined;
+}
+
+/**
+ * Parse a comma-separated list field.
+ * omitted → defaults; "none"/empty → []; csv → listed items.
+ */
+function csvList(val: unknown, defaults: string[]): string[] {
+  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: 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/env.ts

@@ -0,0 +1,33 @@
+/**
+ * env.ts — Detect environment info (git, platform) for subagent system prompts.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/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,
+  };
+}