pi-subagents-lite 1.2.0 → 1.4.0

package/src/agents/agent-status.ts

@@ -0,0 +1,50 @@
+/**
+ * agent-status.ts — AgentStatus tool implementation.
+ *
+ * A lightweight informational tool that lists all agents (running, queued,
+ * completed, stopped, error) from the manager and returns a clear message
+ * about not polling for status.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentRecord } from "../types.js";
+import { SHORT_ID_LENGTH } from "../types.js";
+import { getManager } from "../shell.js";
+
+/**
+ * Format a single agent record as "type·short_id·status".
+ */
+function formatAgent(record: AgentRecord): string {
+  const shortId = record.id.slice(0, SHORT_ID_LENGTH);
+  return `${record.display.type}·${shortId}·${record.lifecycle.status}`;
+}
+
+/**
+ * Execute the AgentStatus tool.
+ *
+ * Returns a formatted list of all agents with their type, short ID, and status,
+ * followed by a nudge message telling the model not to poll.
+ */
+export async function executeAgentStatusTool(
+  _toolCallId: string,
+  _params: Record<string, unknown>,
+  _signal: AbortSignal | undefined,
+  _onUpdate: ((update: any) => void) | undefined,
+  _ctx: ExtensionContext,
+): Promise<any> {
+  const manager = getManager()!;
+  const agents = manager.listAgents();
+
+  const nudge = "Don't poll — you'll receive notifications when agents complete.";
+
+  if (agents.length === 0) {
+    return {
+      content: [{ type: "text", text: `No agents running or completed.\n\n${nudge}` }],
+    };
+  }
+
+  const formatted = agents.map(formatAgent).join(", ");
+  return {
+    content: [{ type: "text", text: `${formatted}\n\n${nudge}` }],
+  };
+}

package/src/agents/agent-types.ts

@@ -0,0 +1,339 @@
+/**
+ * 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 { scanAgentFilesInDir, mergeAgents } from "./agent-discovery.js";
+import { DEFAULT_AGENTS } from "./default-agents.js";
+import type { AgentConfig } from "./types.js";
+
+/**
+ * All tool names that Pi can provide to a session.
+ *
+ * Note: only `read`, `bash`, `edit`, `write` are active by default.
+ * `find` and `grep` must be explicitly activated via setActiveToolsByName().
+ * `ls` was removed — it's a thin wrapper over bash that adds ~180 tokens/turn
+ * with no real benefit.
+ */
+export const BUILTIN_TOOL_NAMES: string[] = ["read", "bash", "edit", "write", "grep", "find"];
+
+/** Unified runtime registry of all agents (defaults + user-defined). */
+const agents = new Map<string, AgentConfig>();
+
+/**
+ * Directories to scan for agent .md files at startup and on-demand.
+ * Set by setAgentScanDirs() during session_start.
+ */
+let userAgentDir = "";
+let projectAgentDir = "";
+
+/** Options for registerAgents. */
+export interface RegisterAgentsOptions {
+  /** When true, skip built-in DEFAULT_AGENTS. */
+  disableDefaultAgents?: boolean;
+}
+
+/**
+ * Register agents into the unified registry.
+ * Starts with DEFAULT_AGENTS, then overlays user agents (overrides defaults with same name).
+ * When options.disableDefaultAgents is true, DEFAULT_AGENTS are skipped.
+ * Hidden agents (hidden === true) are kept in the registry but excluded from spawning.
+ */
+export function registerAgents(userAgents: Map<string, AgentConfig>, options?: RegisterAgentsOptions): void {
+  agents.clear();
+
+  // Start with defaults (unless disabled)
+  if (!options?.disableDefaultAgents) {
+    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);
+  }
+}
+
+/**
+ * Set the agent scan directories for on-demand discovery.
+ * Called during session_start alongside scanAndRegisterAgents.
+ */
+export function setAgentScanDirs(userDir: string, projectDir: string): void {
+  userAgentDir = userDir;
+  projectAgentDir = projectDir;
+}
+
+/**
+ * Scan the known agent directories and register any newly discovered agents
+ * that aren't already in the registry. Returns the number of new agents added.
+ *
+ * @param worktreeDir - Optional absolute path to a worktree's `.pi/agents/` directory.
+ *   When set, agents from this directory are also scanned and added to the registry.
+ *   Worktree-local types use "project" source attribution and follow the same
+ *   parsing and name-uniqueness rules as the parent's project scan.
+ * @param options - Optional settings. disableDefaultAgents skips DEFAULT_AGENTS in the merge.
+ */
+export async function discoverNewAgents(worktreeDir?: string, options?: { disableDefaultAgents?: boolean }): Promise<number> {
+  const [userAgents, projectAgents] = await Promise.all([
+    scanAgentFilesInDir(userAgentDir, "user"),
+    scanAgentFilesInDir(projectAgentDir, "project"),
+  ]);
+
+  const defaults = options?.disableDefaultAgents ? new Map<string, AgentConfig>() : DEFAULT_AGENTS;
+  const merged = mergeAgents(defaults, userAgents, projectAgents);
+
+  let count = 0;
+  for (const [name, config] of merged) {
+    if (!agents.has(name)) {
+      agents.set(name, config);
+      count++;
+    }
+  }
+
+  // Scan worktree-local agents (only when worktreeDir is provided)
+  if (worktreeDir) {
+    const worktreeAgents = await scanAgentFilesInDir(worktreeDir, "project");
+    // Use mergeAgents to convert AgentConfigFromMd to AgentConfig (applies fromMd
+    // and BASE_DEFAULTS), then add only names not already in the registry.
+    const wtMerged = mergeAgents(new Map(), [], worktreeAgents);
+    for (const [name, config] of wtMerged) {
+      if (!agents.has(name)) {
+        agents.set(name, config);
+        count++;
+      }
+    }
+  }
+
+  return count;
+}
+
+/** Resolve a type name case-insensitively. Also matches displayName. Returns the canonical key or undefined. */
+export function resolveType(name: string): string | undefined {
+  if (!name) return undefined;
+  if (agents.has(name)) return name;
+  const lower = name.toLowerCase();
+  for (const [key, config] of agents.entries()) {
+    if (key.toLowerCase() === lower) return key;
+    if ((config.displayName ?? '').toLowerCase() === lower) return key;
+  }
+  return undefined;
+}
+
+/** Get the agent config for a type (case-insensitive). */
+export function getAgentConfig(name: string): AgentConfig | undefined {
+  const key = resolveType(name);
+  return key ? agents.get(key) : undefined;
+}
+
+/** Get all visible type names (for spawning and tool descriptions). */
+export function getAvailableTypes(): string[] {
+  return [...agents.entries()]
+    .filter(([_, config]) => config.hidden !== true)
+    .map(([name]) => name);
+}
+
+/** Get all type names including hidden (for UI listing). */
+export function getAllTypes(): string[] {
+  return [...agents.keys()];
+}
+
+/** Names of tools that subagents must NOT inherit (no sub-subagent policy, ADR 0001). */
+export const EXCLUDED_TOOL_NAMES = ["Agent"];
+
+/**
+ * Resolve tool entries (with ext/* syntax) into concrete tool names.
+ * Supports:
+ *   - bare tool names: "read" → "read"
+ *   - ext/* syntax: "tavily/*" → all tools from the tavily extension
+ *   - ext/tool syntax: "tavily/web_search" → "web_search"
+ */
+function resolveToolEntries(
+  entries: string[],
+  extToolMap: Map<string, string[]> | undefined,
+  notify?: (msg: string) => void,
+): Set<string> {
+  const resolved = new Set<string>();
+
+  for (const entry of entries) {
+    const slashIdx = entry.indexOf("/");
+    if (slashIdx !== -1) {
+      // ext/* or ext/tool syntax
+      const extName = entry.slice(0, slashIdx);
+      const toolPart = entry.slice(slashIdx + 1);
+      if (toolPart === "*") {
+        const extTools = extToolMap?.get(extName);
+        if (extTools && extTools.length > 0) {
+          for (const t of extTools) resolved.add(t);
+        } else {
+          notify?.(`extension "${extName}" is not loaded, "${entry}" will have no effect`);
+        }
+      } else {
+        // ext/tool syntax: e.g. "tavily/web_search"
+        resolved.add(toolPart);
+      }
+    } else {
+      // Bare tool name
+      resolved.add(entry);
+    }
+  }
+
+  return resolved;
+}
+
+/**
+ * Resolve the visible tool set for an agent type from its config.
+ *
+ * Single owner of tool visibility policy. Handles:
+ *   - `tools: true` → all active tools (minus excluded)
+ *   - `tools: string[]` → allowlist (minus excluded, with ext/* expansion)
+ *   - `tools: false` → no tools
+ *   - `tools: undefined` + `excludeTools` → denylist (minus excluded, with ext/* expansion)
+ *   - `tools: undefined` → all active tools (minus EXCLUDED_TOOL_NAMES if any are present)
+ *
+ * `tools` and `excludeTools` are mutually exclusive. If both set, `tools` wins.
+ *
+ * Returns null when no filtering is needed, otherwise the filtered tool list.
+ */
+export function resolveVisibleTools(opts: {
+  activeTools: string[];
+  tools?: true | string[] | false;
+  excludeTools?: string[];
+  extToolMap?: Map<string, string[]>;
+  notify?: (msg: string) => void;
+}): string[] | null {
+  const { activeTools, tools, excludeTools, extToolMap, notify } = opts;
+
+  // Blacklist mode: excludeTools set and tools not set as whitelist
+  if (excludeTools && !Array.isArray(tools)) {
+    const excludeSet = resolveToolEntries(excludeTools, extToolMap, notify);
+    const filtered = activeTools.filter(t =>
+      !EXCLUDED_TOOL_NAMES.includes(t) && !excludeSet.has(t)
+    );
+    return filtered.length !== activeTools.length ? filtered : null;
+  }
+
+  if (Array.isArray(tools)) {
+    // Whitelist mode: resolve entries with ext/* expansion
+    const allBuiltinSet = new Set(BUILTIN_TOOL_NAMES);
+    const allowedTools = resolveToolEntries(tools, extToolMap, notify);
+
+    // Warn about unknown entries
+    for (const entry of tools) {
+      const slashIdx = entry.indexOf("/");
+      if (slashIdx === -1 && !allBuiltinSet.has(entry)) {
+        // Bare name, not a known built-in — check if it's an extension tool
+        let foundInExt = false;
+        for (const [, extToolNames] of extToolMap ?? []) {
+          if (extToolNames.includes(entry)) { foundInExt = true; break; }
+        }
+        if (!foundInExt) {
+          notify?.(`tool "${entry}" not found in any loaded extension`);
+        }
+      }
+    }
+
+    const visibleSet = new Set<string>();
+    for (const t of activeTools) {
+      if (EXCLUDED_TOOL_NAMES.includes(t)) continue;
+      if (allowedTools.has(t)) {
+        visibleSet.add(t);
+      }
+    }
+
+    // Warn if a loaded extension has none of its tools in `tools`
+    if (extToolMap) {
+      for (const [extName, extTools] of extToolMap) {
+        const hasAny = extTools.some(t => allowedTools.has(t));
+        if (!hasAny) {
+          notify?.(`extension "${extName}" is loaded but none of its tools are in tools: [${tools.join(", ")}]`);
+        }
+      }
+    }
+
+    return [...visibleSet];
+  }
+
+  if (tools === false) {
+    return [];
+  }
+
+  // tools: true or undefined — all tools visible (except excluded)
+  const hasExcluded = activeTools.some(t => EXCLUDED_TOOL_NAMES.includes(t));
+  if (!hasExcluded) return null;
+  return activeTools.filter(t => !EXCLUDED_TOOL_NAMES.includes(t));
+}
+
+/** Get built-in tool names for a type (case-insensitive). */
+export function getToolNamesForType(type: string): string[] {
+  const config = getAgentConfig(type);
+  return config?.registeredTools?.length
+    ? config.registeredTools
+    : [...BUILTIN_TOOL_NAMES];
+}
+
+/** Resolved config shape returned by getConfig. */
+export interface ResolvedAgentConfig {
+  displayName: string;
+  description: string;
+  registeredTools: string[];
+  /** Controls tool schema visibility. true = all, string[] = listed, false = none. */
+  tools?: true | string[] | false;
+  extensions: true | string[] | false;
+  skills: true | string[] | false;
+}
+
+/**
+ * Apply global implicit defaults to skills/extensions.
+ * undefined means "not explicitly set" → resolve from global default.
+ * Concrete values (true, false, string[]) pass through unchanged.
+ */
+function applyGlobalDefaults(
+  skills: true | string[] | false | undefined,
+  extensions: true | string[] | false | undefined,
+  loadSkillsImplicitly: boolean,
+  loadExtensionsImplicitly: boolean,
+): { skills: true | string[] | false; extensions: true | string[] | false } {
+  return {
+    skills: skills === undefined ? loadSkillsImplicitly : skills,
+    extensions: extensions === undefined ? loadExtensionsImplicitly : extensions,
+  };
+}
+
+/** Get config for a type (case-insensitive). Falls back to general-purpose. */
+export function getConfig(
+  type: string,
+  loadSkillsImplicitly: boolean = true,
+  loadExtensionsImplicitly: boolean = true,
+): ResolvedAgentConfig {
+  const resolvedKey = resolveType(type);
+  const config = resolvedKey ? agents.get(resolvedKey) : undefined;
+
+  // If config exists and is not hidden, use it; otherwise fall back to general-purpose
+  const activeConfig = config?.hidden !== true
+    ? config
+    : agents.get("general-purpose");
+
+  if (activeConfig && activeConfig.hidden !== true) {
+    const { skills, extensions, ...rest } = activeConfig;
+    const defaults = applyGlobalDefaults(skills, extensions, loadSkillsImplicitly, loadExtensionsImplicitly);
+    return {
+      displayName: rest.displayName ?? rest.name,
+      description: rest.description,
+      registeredTools: rest.registeredTools ?? BUILTIN_TOOL_NAMES,
+      tools: rest.tools,
+      ...defaults,
+    };
+  }
+
+  // Absolute fallback — general-purpose was hidden or missing
+  const defaults = applyGlobalDefaults(undefined, undefined, loadSkillsImplicitly, loadExtensionsImplicitly);
+  return {
+    displayName: "Agent",
+    description: "General-purpose agent for complex, multi-step tasks",
+    registeredTools: BUILTIN_TOOL_NAMES,
+    ...defaults,
+  };
+}

package/src/{default-agents.ts → agents/default-agents.ts}

@@ -17,8 +17,7 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
       displayName: "Agent",
       description: "General-purpose agent for complex, multi-step tasks",
       // registeredTools omitted — means "all available tools" (resolved at lookup time)
-      extensions: true,
-      skills: true,
+      // extensions and skills intentionally omitted — resolved by global default
       systemPrompt: "",
       isDefault: true,
     },
@@ -30,9 +29,7 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
       displayName: "Explore",
       description: "Fast codebase exploration agent (read-only)",
       registeredTools: READ_ONLY_TOOLS,
-      extensions: true,
-      skills: true,
-      model: "anthropic/claude-haiku-4-5-20251001",
+      // extensions and skills intentionally omitted — resolved by global default,
       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.

package/src/{output-file.ts → agents/output-file.ts}

@@ -10,7 +10,7 @@ import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
 import { formatTokens } from "./usage.js";
-import { summarizeToolArgs } from "./format.js";
+import { summarizeToolArgs } from "../ui/format.js";
 
 /** Max content length for full tool result display — longer results get a summary line. */
 const MAX_TOOL_RESULT_DISPLAY_LENGTH = 500;
@@ -193,3 +193,70 @@ export function streamToOutputFile(
     unsubscribe();
   };
 }
+
+// ---------------------------------------------------------------------------
+//  AgentOutputLog — lifecycle wrapper for per-agent output streaming
+// ---------------------------------------------------------------------------
+
+/** Final stats written to the DONE line at agent completion. */
+export interface OutputFinalStats {
+  turnCount: number;
+  toolUseCount: number;
+  totalTokens: number;
+  cost: number;
+}
+
+/**
+ * Manages a single agent's output log lifecycle: create path → write initial
+ * entry → attach session stream → finalize with stats → close.
+ *
+ * The manager holds one instance per agent. At spawn time the constructor
+ * creates the file and writes the [USER] entry. When the session is ready,
+ * `attach()` subscribes to streaming events. At completion, `finalize()`
+ * flushes remaining messages, writes the [DONE] line, and unsubscribes.
+ */
+export class AgentOutputLog {
+  readonly path: string;
+  private cleanup?: () => void;
+  private statsRef?: OutputFinalStats;
+
+  constructor(agentId: string, prompt: string, baseDir?: string) {
+    this.path = createOutputFilePath(agentId, baseDir);
+    writeInitialEntry(this.path, prompt);
+  }
+
+  /**
+   * Subscribe to session events so messages stream to the output file.
+   * Internally passes a mutable stats reference that `finalize()` populates
+   * before the DONE line is written.
+   */
+  attach(session: AgentSession): void {
+    this.statsRef = { turnCount: 0, toolUseCount: 0, totalTokens: 0, cost: 0 };
+    this.cleanup = streamToOutputFile(session, this.path, this.statsRef);
+  }
+
+  /**
+   * Flush remaining messages, write the [DONE] line with final stats,
+   * and unsubscribe from session events.
+   *
+   * Safe to call without a prior `attach()` — writes the DONE line only.
+   */
+  finalize(stats: OutputFinalStats): void {
+    if (this.cleanup && this.statsRef) {
+      // Populate the mutable stats ref so streamToOutputFile's cleanup
+      // writes the actual final values to the DONE line.
+      this.statsRef.turnCount = stats.turnCount;
+      this.statsRef.toolUseCount = stats.toolUseCount;
+      this.statsRef.totalTokens = stats.totalTokens;
+      this.statsRef.cost = stats.cost;
+      this.cleanup();
+      this.cleanup = undefined;
+      this.statsRef = undefined;
+    } else {
+      // No attach was called — write DONE directly
+      const tokensStr = `${formatTokens(stats.totalTokens)} tokens`;
+      const costStr = `$${stats.cost.toFixed(3)}`;
+      safeAppend(this.path, `${timestamp()} [DONE] ${stats.turnCount} turns, ${stats.toolUseCount} tool uses, ${tokensStr}, ${costStr}\n`);
+    }
+  }
+}