pi-subagents-lite 1.3.0 → 1.4.1

package/src/prompt/skill-loader.ts

@@ -0,0 +1,195 @@
+/**
+ * skill-loader.ts — Load skills using Pi's exported APIs.
+ *
+ * Aligns skill discovery with Pi so subagents see the same skills as the parent session.
+ *
+ * Roots, in precedence order (first match wins by name):
+ *   1. Ancestor .agents/skills (cwd → git root, root .md files filtered out)
+ *   2. ~/.agents/skills (root .md files filtered out)
+ *   3. ~/.pi/agent/skills (Pi's user default)
+ *   4. <cwd>/.pi/skills (Pi's project default)
+ *
+ * Pi's loadSkills handles: .gitignore/.ignore/.fdignore, symlinks (follow +
+ * canonical-path dedup), YAML frontmatter, name validation.
+ *
+ * loadSkillsFromDir handles the same for individual .agents/skills directories.
+ * Root .md files from .agents/skills are filtered out because Pi's "agents"
+ * mode (no root files) is not exported.
+ */
+
+import { readFileSync, realpathSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import {
+  loadSkills,
+  loadSkillsFromDir,
+  type Skill,
+} from "@earendil-works/pi-coding-agent";
+import { isUnsafeName } from "../utils.js";
+
+export interface PreloadedSkill {
+  name: string;
+  description: string;
+  content: string;
+}
+
+export interface SkillMeta {
+  name: string;
+  description: string;
+  location: string;
+  /** Whether the skill should be excluded from the <available_skills> prompt block. */
+  disableModelInvocation: boolean;
+  /** Full skill content — present when the skill is preloaded. */
+  content?: string;
+}
+
+/**
+ * Load all skills in correct precedence order.
+ *
+ * Precedence (first match wins by name):
+ *   1. Ancestor .agents/skills directories (cwd → git root)
+ *   2. ~/.agents/skills
+ *   3. Pi defaults: ~/.pi/agent/skills, <cwd>/.pi/skills
+ *
+ * Deduplication: by canonical path (symlink dedup) and by name (first match wins).
+ */
+export function loadAllSkills(cwd: string): Skill[] {
+  const resolvedCwd = resolve(cwd);
+
+  // Ancestor .agents/skills (highest precedence)
+  const ancestorsSkills = loadAncestorAgentsSkills(resolvedCwd);
+
+  // ~/.agents/skills
+  const homeAgentsResult = loadSkillsFromDir({
+    dir: join(homedir(), ".agents", "skills"),
+    source: "agents",
+  });
+  const homeAgentsSkills = filterRootMdFiles(
+    homeAgentsResult.skills,
+    join(homedir(), ".agents", "skills"),
+  );
+
+  // Pi defaults: ~/.pi/agent/skills and <cwd>/.pi/skills
+  const defaultsResult = loadSkills({
+    cwd: resolvedCwd,
+    agentDir: join(homedir(), ".pi", "agent"),
+    skillPaths: [],
+    includeDefaults: true,
+  });
+
+  // Merge in precedence order: ancestors first, then home, then defaults.
+  // First match wins by name and by canonical path.
+  const nameSet = new Set<string>();
+  const realPathSet = new Set<string>();
+  const result: Skill[] = [];
+
+  for (const skill of [...ancestorsSkills, ...homeAgentsSkills, ...defaultsResult.skills]) {
+    const realPath = canonicalizePath(skill.filePath);
+    if (realPathSet.has(realPath) || nameSet.has(skill.name)) continue;
+    nameSet.add(skill.name);
+    realPathSet.add(realPath);
+    result.push(skill);
+  }
+
+  return result;
+}
+
+/**
+ * Walk from cwd up to git root, loading skills from each .agents/skills directory.
+ * Filters out root .md files (Pi's exported API doesn't support "agents" mode).
+ */
+function loadAncestorAgentsSkills(resolvedCwd: string): Skill[] {
+  const gitRoot = findGitRoot(resolvedCwd);
+  const result: Skill[] = [];
+  let dir = resolvedCwd;
+
+  while (true) {
+    const agentsSkillsDir = join(dir, ".agents", "skills");
+    const dirResult = loadSkillsFromDir({
+      dir: agentsSkillsDir,
+      source: "agents",
+    });
+    result.push(...filterRootMdFiles(dirResult.skills, agentsSkillsDir));
+
+    if (dir === gitRoot) break;
+    const parent = resolve(dir, "..");
+    if (parent === dir) break; // filesystem root
+    dir = parent;
+  }
+
+  return result;
+}
+
+/**
+ * Filter out root .md files from .agents/skills directories.
+ *
+ * loadSkillsFromDir always includes root .md files (includeRootFiles: true),
+ * but .agents/skills directories should only contain subdirectory skills.
+ * A root .md skill has a filePath whose parent is the skills root itself.
+ */
+function filterRootMdFiles(skills: Skill[], skillsRoot: string): Skill[] {
+  const normalizedRoot = resolve(skillsRoot);
+  return skills.filter((skill) => {
+    const parent = resolve(skill.filePath, "..");
+    return parent !== normalizedRoot;
+  });
+}
+
+/** Walk up from dir to find the git root (directory containing .git). */
+function findGitRoot(dir: string): string {
+  let current = resolve(dir);
+  while (true) {
+    try {
+      const entries = readdirSync(current);
+      if (entries.includes(".git")) return current;
+    } catch { /* ignore */ }
+    const parent = resolve(current, "..");
+    if (parent === current) return current; // filesystem root
+    current = parent;
+  }
+}
+
+/** Resolve path to canonical form, following symlinks. Falls back to raw path. */
+function canonicalizePath(filePath: string): string {
+  try { return realpathSync(filePath); } catch { return filePath; }
+}
+
+export function preloadSkills(skillNames: string[], cwd: string): PreloadedSkill[] {
+  const skills = loadAllSkills(cwd);
+  return skillNames.map((name) => {
+    if (isUnsafeName(name)) {
+      return { name, description: "", content: `(Skill "${name}" skipped: name contains path traversal characters)` };
+    }
+    const match = skills.find((s) => s.name === name);
+    if (!match) {
+      return { name, description: "", content: `(Skill "${name}" not found in .pi/skills/, .agents/skills/, or global skill locations)` };
+    }
+    try {
+      return { name, description: match.description, content: readFileSync(match.filePath, "utf-8").trim() };
+    } catch {
+      return { name, description: "", content: `(Skill "${name}" not found in .pi/skills/, .agents/skills/, or global skill locations)` };
+    }
+  });
+}
+
+/**
+ * Load skill metadata only (name, description, location) without full content.
+ * Used for the skills whitelist — agent can read full content on-demand.
+ */
+export function loadSkillMeta(skillNames: string[], cwd: string): SkillMeta[] {
+  const skills = loadAllSkills(cwd);
+  return skillNames.map((name) => {
+    const match = skills.find((s) => s.name === name);
+    if (!match) {
+      return { name, description: `(Skill "${name}" not found)`, location: "", disableModelInvocation: false };
+    }
+    return {
+      name,
+      description: match.description,
+      location: match.filePath,
+      disableModelInvocation: match.disableModelInvocation,
+    };
+  });
+}
+
+

package/src/registration.ts

@@ -0,0 +1,101 @@
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { getAvailableTypes } from "./agents/agent-types.js";
+import { executeAgentTool, executeStopAgentTool } from "./agents/tool-execution.js";
+import { executeAgentStatusTool } from "./agents/agent-status.js";
+import { renderAgentToolCall, renderAgentToolResult, renderSubagentResult } from "./ui/renderer.js";
+import { showAgentsMainMenu } from "./ui/menu/menus.js";
+import { getPiInstance, getStore } from "./shell.js";
+
+// ============================================================================
+// Agent tool registration helper — dynamic enum for agent types
+// ============================================================================
+
+/**
+ * Register (or re-register) the Agent tool with current agent types.
+ * At init time only defaults exist; call again from session_start after
+ * user/project agents are loaded to update the enum.
+ */
+export function registerAgentTool(pi: ExtensionAPI): void {
+  const types = getAvailableTypes();
+  // Use plain string to avoid verbose anyOf in prompt.
+  // Available types are listed in description for discoverability.
+  const agentParam = types.length > 0
+    ? Type.Optional(Type.String({ description: types.join(",") }))
+    : Type.Optional(Type.String());
+  // @ts-expect-error — description removed to save prompt tokens
+  pi.registerTool({
+    name: "Agent",
+    label: "Agent",
+    parameters: Type.Object({
+      prompt: Type.String(),
+      description: Type.Optional(Type.String()),
+      agent: agentParam,
+      run_in_background: Type.Optional(Type.Boolean()),
+      worktree_path: Type.Optional(Type.String()),
+    }),
+    execute: executeAgentTool,
+
+    renderCall: (args, theme) => renderAgentToolCall(args as Record<string, unknown>, theme),
+
+    renderResult: (result, options, theme) => {
+      const showCost = getStore().agent.showCost;
+      return renderAgentToolResult(
+        result as { content: Array<{ type: string; text?: string }>; details?: Record<string, unknown>; isError?: boolean },
+        options as { expanded?: boolean },
+        theme,
+        showCost,
+      );
+    },
+  });
+}
+
+// ============================================================================
+// Tool/Command/Message registration
+// ============================================================================
+
+/** Register all tools, commands, and message renderers. */
+export function registerTools(pi: ExtensionAPI): void {
+  // Agent tool — stealth schema with dynamic agent type enum
+  registerAgentTool(pi);
+
+  // StopAgent tool — stealth schema, stop a running agent by ID
+  // @ts-expect-error — description removed to save prompt tokens
+  pi.registerTool({
+    name: "StopAgent",
+    label: "StopAgent",
+    parameters: Type.Object({
+      agent_id: Type.String(),
+    }),
+    execute: executeStopAgentTool,
+  });
+
+  // AgentStatus tool — stealth schema, list all agents and their statuses
+  // @ts-expect-error — description removed to save prompt tokens
+  pi.registerTool({
+    name: "AgentStatus",
+    label: "AgentStatus",
+    parameters: Type.Object({}),
+    execute: executeAgentStatusTool,
+  });
+
+  // Message renderer — subagent-result (background agent completion)
+  pi.registerMessageRenderer("subagent-result", (message, options, theme) => {
+    const showCost = getStore().agent.showCost;
+    return renderSubagentResult(
+      message as { content?: string; details?: Record<string, unknown> },
+      options as { expanded?: boolean },
+      theme,
+      showCost,
+    );
+  });
+
+  // Command registration
+  pi.registerCommand("agents", {
+    description: "Manage subagents: agent briefing, model settings, concurrency, running agents, agent types",
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
+      const modelOptions = ctx.modelRegistry.getAvailable().map((m) => `${m.provider}/${m.id}`);
+      await showAgentsMainMenu(ctx, modelOptions);
+    },
+  });
+}

package/src/shell.ts

@@ -0,0 +1,101 @@
+/**
+ * shell.ts — Composition root shell.
+ *
+ * Per ADR 0004, the Shell is the single mutable container for all per-session
+ * state. Created at session_start, disposed at session_shutdown. Handler
+ * modules read from shell via the getter functions — no module-level mutable
+ * globals.
+ *
+ * index.ts populates the shell at session_start; handler modules import
+ * getManager() / getWidget() / etc.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentManager } from "./agents/agent-manager.js";
+import type { AgentWidget } from "./ui/agent-widget.js";
+import type { SpawnCoordinator } from "./spawn/spawn-coordinator.js";
+import { ConfigStore } from "./config/config-store.js";
+
+// ============================================================================
+// Shell type
+// ============================================================================
+
+interface Shell {
+  pi: ExtensionAPI;
+  sessionCtx: ExtensionContext;
+  manager: AgentManager | null;
+  widget: AgentWidget | null;
+  store: ConfigStore;
+  coordinator: SpawnCoordinator | null;
+}
+
+// ============================================================================
+// Mutable module-level shell (populated by index.ts at session_start)
+// ============================================================================
+
+const shell: Shell = {
+  pi: null!,
+  sessionCtx: null!,
+  manager: null,
+  widget: null,
+  store: new ConfigStore(),
+  coordinator: null,
+};
+
+// ============================================================================
+// Getter functions (read current state at call time)
+// ============================================================================
+
+/** The PI extension API instance. Set at init time. */
+export function getPiInstance(): ExtensionAPI {
+  return shell.pi;
+}
+
+/** The current session context. Set at session_start. */
+export function getSessionCtx(): ExtensionContext {
+  return shell.sessionCtx;
+}
+
+/** The current AgentManager, or null if not yet created. */
+export function getManager(): AgentManager | null {
+  return shell.manager;
+}
+
+/** The current AgentWidget, or null if not yet created. */
+export function getWidget(): AgentWidget | null {
+  return shell.widget;
+}
+
+/** The ConfigStore (lives for the lifetime of the extension). */
+export function getStore(): ConfigStore {
+  return shell.store;
+}
+
+/** The current SpawnCoordinator, or null if not yet created. */
+export function getCoordinator(): SpawnCoordinator | null {
+  return shell.coordinator;
+}
+
+// ============================================================================
+// Setter functions (called by index.ts to populate the shell)
+// ============================================================================
+
+export function setPiInstance(pi: ExtensionAPI): void {
+  shell.pi = pi;
+}
+
+export function setSessionCtx(ctx: ExtensionContext): void {
+  shell.sessionCtx = ctx;
+}
+
+export function setManager(m: AgentManager | null): void {
+  shell.manager = m;
+}
+
+export function setWidget(w: AgentWidget | null): void {
+  shell.widget = w;
+}
+
+export function setCoordinator(c: SpawnCoordinator | null): void {
+  shell.coordinator = c;
+}

package/src/spawn/spawn-coordinator.ts

@@ -0,0 +1,232 @@
+import { getStatusNote } from "../status-note.js";
+/**
+ * spawn-coordinator.ts — Spawn-and-track coordination for subagents.
+ *
+ * Single entry point for both LLM tool and menu spawn paths.
+ * Owns: LiveView store, Nudge system (schedule/batch/emit), background agent tracking.
+ * Delegates concurrency and record lifecycle to AgentManager (peers, not ownership).
+ *
+ * Decision refs: D3 (forward events to live-view), D4 (stats on record only),
+ * D6 (Nudge owned here), D2 (peers with AgentManager).
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentRecord, SpawnConfig, ToolActivity } from "../types.js";
+import type { AgentManager, SpawnOptions } from "../agents/agent-manager.js";
+import { buildAgentDetails } from "../agents/tool-execution.js";
+import { getWidget } from "../shell.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Coordinator-owned per-agent live display state. Only transient UI state. */
+export interface LiveView {
+  activeTools: Map<string, string>;  // keyed by toolName_timestamp
+  responseText: string;
+}
+
+/** Input for spawn(). Built by each caller from its own validation. */
+export interface SpawnIntent extends SpawnConfig {
+  type: string;
+  prompt: string;
+  runInBackground: boolean;
+  /** Narrowed to required — all callers resolve this before spawn. */
+  graceTurns: number;
+}
+
+export interface SpawnResult {
+  agentId: string;
+  record: AgentRecord;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Batch delay for nudges — only emit one update per batch window (ms). */
+const NUDGE_DELAY_MS = 200;
+
+// ============================================================================
+// SpawnCoordinator
+// ============================================================================
+
+export class SpawnCoordinator {
+  /** Per-agent live display state. Widget reads from here + record for stats. */
+  private liveViews = new Map<string, LiveView>();
+
+  /** Agent IDs spawned as background — only these trigger a nudge on completion. */
+  private backgroundAgentIds = new Set<string>();
+
+  /** Pending nudge agent IDs, batched within the delay window. */
+  private pendingNudges = new Set<string>();
+
+  /** Active nudge timer. */
+  private nudgeTimer: ReturnType<typeof setTimeout> | null = null;
+
+  /** The pi API reference for sending messages. */
+  private pi: ExtensionAPI | null = null;
+
+  constructor(private manager: AgentManager, pi?: ExtensionAPI) {
+    if (pi) this.pi = pi;
+  }
+
+  /**
+   * Spawn + wire tracking + (foreground) await.
+   * Single entry point for LLM tool executor and menu wizard.
+   */
+  async spawn(
+    pi: ExtensionAPI,
+    ctx: ExtensionContext,
+    intent: SpawnIntent,
+  ): Promise<SpawnResult> {
+    // Store pi for nudge emission
+    this.pi = pi;
+
+    // Create live view BEFORE spawn so callbacks can close over it
+    const liveView: LiveView = {
+      activeTools: new Map(),
+      responseText: "",
+    };
+    const liveViewCallbacks = this.createLiveViewCallbacks(liveView);
+
+    // Shared config fields (SpawnConfig) pass through unchanged; only the
+    // intent-only fields (type/prompt/runInBackground) need translation.
+    const { type, prompt, runInBackground, ...config } = intent;
+    const spawnOptions: SpawnOptions = {
+      ...config,
+      isBackground: runInBackground,
+      ...liveViewCallbacks,
+    };
+
+    const agentId = this.manager.spawn(pi, ctx, type, prompt, spawnOptions);
+
+    // Register live view
+    this.liveViews.set(agentId, liveView);
+
+    // Ensure widget timer is running so it displays the new agent
+    // (menu path calls this explicitly, but tool path doesn't)
+    const widget = getWidget();
+    if (widget) {
+      widget.ensureTimer();
+    }
+
+    // Track background agents
+    if (intent.runInBackground) {
+      this.backgroundAgentIds.add(agentId);
+    }
+
+    const record = this.manager.getRecord(agentId)!;
+
+    if (!intent.runInBackground) {
+      // Foreground: await completion
+      await record.execution.promise;
+
+      // Clean up live view (foreground completion handled inline)
+      this.liveViews.delete(agentId);
+    }
+
+    return { agentId, record };
+  }
+
+  /** Read the live view for an agent. Widget calls this. */
+  liveView(id: string): LiveView | undefined {
+    return this.liveViews.get(id);
+  }
+
+  /** Check if an agent was spawned as background. */
+  isBackground(agentId: string): boolean {
+    return this.backgroundAgentIds.has(agentId);
+  }
+
+  /**
+   * Schedule a nudge for a background agent.
+   * Batches with NUDGE_DELAY_MS window to coalesce rapid completions.
+   */
+  scheduleNudge(agentId: string): void {
+    this.pendingNudges.add(agentId);
+
+    if (this.nudgeTimer) return;
+
+    this.nudgeTimer = setTimeout(() => {
+      this.nudgeTimer = null;
+      const batch = [...this.pendingNudges];
+      this.pendingNudges.clear();
+
+      for (const id of batch) {
+        this.emitIndividualNudge(id);
+      }
+    }, NUDGE_DELAY_MS);
+  }
+
+  /**
+   * Called by AgentManager's onComplete callback (wired at session_start).
+   * Owns the completion side-effects: nudge scheduling, live-view cleanup.
+   */
+  onAgentComplete(record: AgentRecord): void {
+    // Schedule nudge for background agents
+    if (this.backgroundAgentIds.has(record.id)) {
+      this.scheduleNudge(record.id);
+      this.backgroundAgentIds.delete(record.id);
+    }
+
+    // Clean up live view
+    this.liveViews.delete(record.id);
+  }
+
+  /** Dispose: clear timer, live views, and background tracking. */
+  dispose(): void {
+    if (this.nudgeTimer) {
+      clearTimeout(this.nudgeTimer);
+      this.nudgeTimer = null;
+    }
+    this.pendingNudges.clear();
+    this.liveViews.clear();
+    this.backgroundAgentIds.clear();
+    this.pi = null;
+  }
+
+  // ── Private ──
+
+  /** Create callbacks that bridge manager events to a specific live view. */
+  private createLiveViewCallbacks(view: LiveView): Pick<SpawnOptions, "onToolActivity" | "onTextDelta"> {
+    return {
+      onToolActivity: (activity: ToolActivity) => {
+        if (activity.type === "start") {
+          view.activeTools.set(`${activity.toolName}_${Date.now()}`, activity.toolName);
+        } else {
+          for (const [key, name] of view.activeTools) {
+            if (name === activity.toolName) { view.activeTools.delete(key); break; }
+          }
+        }
+      },
+      onTextDelta: (_delta: string, fullText: string) => {
+        view.responseText = fullText;
+      },
+    };
+  }
+
+  /** Emit an individual nudge for a completed background agent. */
+  private emitIndividualNudge(agentId: string): void {
+    const record = this.manager.getRecord(agentId);
+    if (!record || !this.pi) return;
+
+    const details = buildAgentDetails(record, {
+      includeStats: true,
+      includeStatus: true,
+    });
+
+    this.pi.sendMessage(
+      {
+        customType: "subagent-result",
+        content: `[Subagent "${record.display.type}" ${record.lifecycle.status}]\n\n${record.result ?? ""} ${getStatusNote(record.lifecycle.status)}`,
+        details,
+        display: true,
+      },
+      {
+        deliverAs: "steer",
+        triggerTurn: true,
+      },
+    );
+  }
+}

package/src/status-note.ts

@@ -0,0 +1,10 @@
+const NOTES: Record<string, string> = {
+  stopped: "STOPPED BY THE USER before completion — output is partial; the task was NOT finished",
+  aborted: "hit the turn limit before completion; output may be incomplete",
+  turn_limited: "wrapped up at the turn limit — output may be partial",
+};
+
+export function getStatusNote(status: string): string {
+  const note = NOTES[status];
+  return note ? ` (${note})` : "";
+}