pi-open-agents 0.1.0

package/src/subagent/tool.ts

@@ -0,0 +1,299 @@
+/**
+ * Subagent tool registration.
+ *
+ * Registers the "subagent" tool that the LLM can call to delegate tasks
+ * to named subagents running in isolated child pi processes.
+ *
+ * The tool:
+ * - Filters available agents by mode (subagent|all) and allowedAgents
+ * - Checks recursion depth via PI_OPEN_AGENTS_* env vars
+ * - Spawns the child process via the executor
+ * - Renders progress and results in the TUI
+ */
+
+import type {
+  AgentToolUpdateCallback,
+  ExtensionAPI,
+  ExtensionContext,
+  ThemeColor,
+} from "@earendil-works/pi-coding-agent";
+import { getMarkdownTheme, keyHint } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+import type { AgentDefinition } from "../types.ts";
+import { spawnableAgents } from "../discovery/loader.ts";
+import {
+  availableSubagentsForAgent,
+  resolveSubagentSession,
+  runSubagent,
+  type AgentProgress,
+  type AgentResult,
+  type SubagentSessionMode,
+} from "./executor.ts";
+import {
+  contextUsageSeverity,
+  formatSubagentCall,
+  formatResultLines,
+  formatUsage,
+} from "./render.ts";
+import { allowedAgentNames, isPastMaxDepth, type RecursionEnv } from "./env.ts";
+import { preview, shortenPath, stringArg } from "../utils/format.ts";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+interface SubagentParams {
+  agent: string;
+  task: string;
+  cwd?: string;
+  session?: SubagentSessionMode;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+type ThemeLike = {
+  fg: (name: ThemeColor, text: string) => string;
+  bold: (text: string) => string;
+};
+
+function availableAgentsText(agents: AgentDefinition[]): string {
+  return (
+    agents
+      .map((agent) => agent.name)
+      .sort()
+      .join(", ") || "none"
+  );
+}
+
+function toToolResult(result: AgentResult) {
+  return {
+    content: [{ type: "text" as const, text: result.output || "(no output)" }],
+    details: result,
+    isError: result.isError,
+  };
+}
+
+function toProgressResult(progress: AgentProgress) {
+  return {
+    content: [{ type: "text" as const, text: progress.output || "(running...)" }],
+    details: progress,
+  };
+}
+
+// ─── Styled Rendering ────────────────────────────────────────────────────────
+
+function styledPathArg(args: Record<string, unknown>, theme: ThemeLike, fallback?: string): string {
+  const p = shortenPath(args.path ?? args.file_path) ?? fallback;
+  return p ? theme.fg("accent", p) : theme.fg("toolOutput", "...");
+}
+
+function styledLineRange(args: Record<string, unknown>, theme: ThemeLike): string {
+  if (args.offset === undefined && args.limit === undefined) return "";
+  const start = (args.offset as number) ?? 1;
+  const limit = args.limit as number | undefined;
+  const end = limit !== undefined ? start + limit - 1 : undefined;
+  return theme.fg("warning", `:${start}${end !== undefined ? `-${end}` : ""}`);
+}
+
+function styledToolTitle(name: string, args: Record<string, unknown>, theme: ThemeLike): string {
+  switch (name) {
+    case "read":
+      return `${theme.fg("toolTitle", theme.bold("read"))} ${styledPathArg(args, theme)}${styledLineRange(args, theme)}`;
+    case "bash": {
+      const cmd = stringArg(args, "command") ?? "";
+      return `${theme.fg("toolTitle", theme.bold(`$ ${cmd || "..."}`))}`;
+    }
+    case "edit":
+      return `${theme.fg("toolTitle", theme.bold("edit"))} ${styledPathArg(args, theme)}`;
+    case "write":
+      return `${theme.fg("toolTitle", theme.bold("write"))} ${styledPathArg(args, theme)}`;
+    case "grep": {
+      const pattern = stringArg(args, "pattern") ?? "";
+      return `${theme.fg("toolTitle", theme.bold("grep"))} ${theme.fg("syntaxKeyword", `/${pattern}/`)}`;
+    }
+    case "subagent": {
+      const agent = stringArg(args, "agent") ?? "";
+      const task = stringArg(args, "task");
+      return `${theme.fg("toolTitle", theme.bold("subagent"))} ${theme.fg("accent", agent)}${task ? ` ${theme.fg("dim", JSON.stringify(preview(task, 60)))}` : ""}`.trimEnd();
+    }
+    default: {
+      const values = Object.values(args).filter((v) => typeof v === "string") as string[];
+      return `${theme.fg("toolTitle", theme.bold(name))}${values.length > 0 ? ` ${theme.fg("dim", JSON.stringify(preview(values[0], 80)))}` : ""}`;
+    }
+  }
+}
+
+function styledCollapsedLine(
+  line: { kind: string; text: string; tool?: { name: string; args: Record<string, unknown>; status: string } },
+  details: AgentResult | AgentProgress,
+  theme: ThemeLike,
+): string {
+  if (line.kind === "status")
+    return theme.fg(details.status === "error" ? "error" : "success", line.text);
+  if (line.kind === "hint") return theme.fg("dim", line.text);
+  if (line.kind === "tool" && line.tool) {
+    const prefix = line.tool.status === "running" ? theme.fg("warning", "▸") : " ";
+    return `${prefix} ${styledToolTitle(line.tool.name, line.tool.args, theme)}`;
+  }
+  if (line.kind === "usage") return theme.fg(contextUsageSeverity(details.usage), line.text);
+  return line.text;
+}
+
+function renderResultLines(
+  details: AgentResult | AgentProgress,
+  theme: ThemeLike,
+  options: { expanded: boolean; suppressOutput?: boolean; suppressUsage?: boolean; expandHint?: string },
+): Container {
+  const container = new Container();
+  for (const line of formatResultLines(details, options)) {
+    if (line.kind === "blank") {
+      container.addChild(new Spacer(1));
+      continue;
+    }
+    container.addChild(new Text(styledCollapsedLine(line, details, theme), 0, 0));
+  }
+  return container;
+}
+
+// ─── Tool Registration ───────────────────────────────────────────────────────
+
+export interface RegisterSubagentToolOptions {
+  agents: AgentDefinition[];
+  run?: typeof runSubagent;
+  env?: RecursionEnv;
+  agentDir?: string;
+  /** Returns the currently active primary agent, if any. Used for allowedAgents filtering. */
+  getActiveAgent?: () => AgentDefinition | undefined;
+}
+
+/**
+ * Register the subagent tool.
+ *
+ * Does nothing if past max recursion depth or no spawnable agents.
+ */
+export function registerSubagentTool(
+  pi: ExtensionAPI,
+  options: RegisterSubagentToolOptions,
+): void {
+  const env: RecursionEnv = options.env ?? process.env;
+  if (isPastMaxDepth(env)) return;
+
+  // Filter by parent's allowed agents
+  const allowed = allowedAgentNames(env);
+  const allSpawnable = spawnableAgents(options.agents);
+  const agents = allowed
+    ? allSpawnable.filter((a) => allowed.has(a.name))
+    : allSpawnable;
+
+  if (agents.length === 0) return;
+
+  const runner = options.run ?? runSubagent;
+  const availableSubagents = agents.map((a) => a.name);
+  const agentNames = [...availableSubagents].sort().join(", ");
+  const sessionGuideline =
+    'Use session: "fork" when the delegated task depends on the current conversation, prior discussion, or parent session history. Use the default session: "none" for self-contained tasks.';
+  const promptGuidelines =
+    agentNames.length > 0 ? [`Available subagents: ${agentNames}`, sessionGuideline] : undefined;
+
+  pi.registerTool({
+    name: "subagent",
+    label: "Subagent",
+    description: "Delegate a task to a named sub-agent running in an isolated pi process.",
+    promptSnippet: "Delegate isolated tasks with subagent({ agent, task, cwd?, session? }).",
+    promptGuidelines,
+    parameters: Type.Object({
+      agent: Type.String({ description: "Name of the agent to invoke" }),
+      task: Type.String({ description: "Task to delegate to the agent" }),
+      cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
+      session: Type.Optional(
+        Type.Union([Type.Literal("none"), Type.Literal("fork")], {
+          description: 'Parent session handling: none starts a fresh subagent session, fork branches from the current session',
+        }),
+      ),
+    }),
+
+    async execute(
+      _toolCallId: string,
+      params: SubagentParams,
+      signal: AbortSignal | undefined,
+      onUpdate: AgentToolUpdateCallback<AgentProgress> | undefined,
+      ctx: ExtensionContext,
+    ) {
+      const agent = agents.find((a) => a.name === params.agent);
+      if (!agent) {
+        throw new Error(
+          `Unknown agent: ${params.agent}. Available agents: ${availableAgentsText(agents)}.`,
+        );
+      }
+
+      // Check active agent's allowedAgents whitelist
+      const activeAgent = options.getActiveAgent?.();
+      if (activeAgent?.allowedAgents && activeAgent.allowedAgents.length > 0) {
+        if (!activeAgent.allowedAgents.includes(agent.name)) {
+          throw new Error(
+            `Agent "${activeAgent.name}" can only delegate to: ${activeAgent.allowedAgents.join(", ")}. "${agent.name}" is not in the list.`,
+          );
+        }
+      }
+
+      const childCwd = params.cwd ?? ctx.cwd;
+      const session = resolveSubagentSession(
+        params.session,
+        childCwd,
+        ctx.sessionManager?.getSessionFile(),
+        ctx.sessionManager?.getLeafId(),
+        options.agentDir,
+      );
+
+      const result = await runner({
+        agent,
+        task: params.task,
+        cwd: childCwd,
+        signal,
+        depth: Number(env.PI_OPEN_AGENTS_DEPTH ?? "0") + 1,
+        availableAgents: availableSubagentsForAgent(agent, availableSubagents),
+        agentDir: options.agentDir,
+        session,
+        onProgress: (progress) => onUpdate?.(toProgressResult(progress)),
+      });
+
+      return toToolResult(result);
+    },
+
+    renderCall(args, theme, context) {
+      const typedArgs = args as SubagentParams;
+      const title = `${theme.fg("toolTitle", theme.bold("subagent"))} ${theme.fg("accent", typedArgs.agent ?? "...")}`;
+      if (context.expanded) return new Text(`${title}\n${theme.fg("dim", typedArgs.task ?? "...")}`, 0, 0);
+      const callText = formatSubagentCall({ agent: typedArgs.agent, task: typedArgs.task });
+      return new Text(`${title} ${theme.fg("dim", callText.replace(/^subagent \S+ /, ""))}`, 0, 0);
+    },
+
+    renderResult(result, renderOpts, theme) {
+      const details = result.details as AgentResult | AgentProgress | undefined;
+      if (!details) {
+        const first = result.content[0];
+        return new Text(first?.type === "text" ? first.text : "(no output)", 0, 0);
+      }
+
+      if (renderOpts.expanded) {
+        const container = renderResultLines(details, theme, {
+          expanded: true,
+          suppressOutput: true,
+          suppressUsage: true,
+        });
+        container.addChild(new Spacer(1));
+        container.addChild(new Markdown(details.output || "(no output)", 0, 0, getMarkdownTheme()));
+        container.addChild(new Spacer(1));
+        container.addChild(
+          new Text(theme.fg(contextUsageSeverity(details.usage), formatUsage(details)), 0, 0),
+        );
+        return container;
+      }
+
+      return renderResultLines(details, theme, {
+        expanded: false,
+        expandHint: keyHint("app.tools.expand", "to expand"),
+      });
+    },
+  });
+}

package/src/tui/banner.ts

@@ -0,0 +1,49 @@
+/**
+ * Status banner widget for the TUI.
+ *
+ * Shows the active agent name, model, and description above the editor.
+ */
+
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import type { AgentDefinition } from "../types.ts";
+
+/**
+ * Update the status widget to reflect the active agent.
+ * Pass undefined to show "no agent selected" hint.
+ */
+export function updateBanner(
+  ui: ExtensionUIContext,
+  activeAgent: AgentDefinition | undefined,
+  selectableCount: number,
+): void {
+  if (activeAgent) {
+    const parts: string[] = [];
+    parts.push(ui.theme.bold(ui.theme.fg("accent", activeAgent.name)));
+
+    if (activeAgent.description) {
+      parts.push(ui.theme.fg("muted", `— ${activeAgent.description}`));
+    }
+
+    if (activeAgent.model) {
+      parts.push(ui.theme.fg("dim", `[${activeAgent.model}]`));
+    }
+
+    if (activeAgent.thinking !== "off") {
+      parts.push(ui.theme.fg("dim", `{${activeAgent.thinking}}`));
+    }
+
+    const banner = ui.theme.fg("accent", "▸ ") + parts.join(" ");
+    ui.setWidget("open-agents-banner", [banner]);
+  } else {
+    // Show hint when agents are available but none active
+    if (selectableCount > 0) {
+      const hint = ui.theme.fg(
+        "dim",
+        "[No agent selected — /agent, Ctrl+Shift+M, Alt+S]",
+      );
+      ui.setWidget("open-agents-banner", [hint]);
+    } else {
+      ui.setWidget("open-agents-banner", undefined);
+    }
+  }
+}

package/src/tui/selector.ts

@@ -0,0 +1,331 @@
+/**
+ * TUI selectors for agent switching.
+ *
+ * Implements:
+ * - Agent picker (selectlist with primary|all agents)
+ * - Cycle shortcut (Ctrl+Shift+M)
+ * - Search (Alt+S, /agent-search)
+ * - Commands (/agent, /agents, /agent-search)
+ */
+
+import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  Key,
+  type SelectItem,
+  SelectList,
+  Text,
+} from "@earendil-works/pi-tui";
+import type { AgentDefinition } from "../types.ts";
+import { selectableAgents } from "../discovery/loader.ts";
+import type { AgentManager } from "../primary/manager.ts";
+import { updateBanner } from "./banner.ts";
+
+// ─── Search Helpers ──────────────────────────────────────────────────────────
+
+interface SearchResult {
+  name: string;
+  agent: AgentDefinition;
+  score: number;
+  snippets: string[];
+}
+
+/**
+ * Score an agent against a search query.
+ */
+function scoreAgent(agent: AgentDefinition, query: string): number {
+  const q = query.toLowerCase();
+  let score = 0;
+
+  if (agent.name.toLowerCase() === q) score += 100;
+  else if (agent.name.toLowerCase().includes(q)) score += 50;
+
+  if (agent.description?.toLowerCase().includes(q)) score += 30;
+  if (agent.model?.toLowerCase().includes(q)) score += 20;
+
+  const bodyLower = agent.prompt.toLowerCase();
+  const bodyMatches = (bodyLower.match(new RegExp(q, "g")) || []).length;
+  score += Math.min(bodyMatches * 5, 25);
+
+  return score;
+}
+
+/**
+ * Extract context snippets around query matches.
+ */
+function extractSnippets(text: string, query: string, max = 2, len = 40): string[] {
+  const q = query.toLowerCase();
+  const lower = text.toLowerCase();
+  const snippets: string[] = [];
+  let pos = 0;
+
+  while (pos < lower.length && snippets.length < max) {
+    const idx = lower.indexOf(q, pos);
+    if (idx === -1) break;
+
+    const start = Math.max(0, idx - len);
+    const end = Math.min(text.length, idx + q.length + len);
+    let snippet = text.slice(start, end).replace(/\n/g, " ");
+    if (start > 0) snippet = "…" + snippet;
+    if (end < text.length) snippet += "…";
+
+    snippets.push(snippet);
+    pos = idx + q.length;
+  }
+
+  return snippets;
+}
+
+/**
+ * Search agents and return ranked results.
+ */
+function searchAgents(agents: AgentDefinition[], query: string, min = 1): SearchResult[] {
+  if (!query.trim()) return [];
+
+  const results: SearchResult[] = [];
+  for (const agent of agents) {
+    const score = scoreAgent(agent, query);
+    if (score >= min) {
+      const snippets: string[] = [];
+      if (agent.description) {
+        snippets.push(...extractSnippets(agent.description, query, 1, 30));
+      }
+      snippets.push(...extractSnippets(agent.prompt, query, 2, 35));
+      results.push({ name: agent.name, agent, score, snippets });
+    }
+  }
+
+  return results.sort((a, b) => b.score - a.score);
+}
+
+// ─── Description Builder ─────────────────────────────────────────────────────
+
+function buildDescription(agent: AgentDefinition): string {
+  const parts: string[] = [];
+  if (agent.model) parts.push(agent.model);
+  if (agent.thinking !== "off") parts.push(`thinking:${agent.thinking}`);
+  if (agent.description) parts.push(agent.description);
+  return parts.join(" | ") || "No description";
+}
+
+// ─── Picker UI ───────────────────────────────────────────────────────────────
+
+/**
+ * Render a generic agent picker using pi's custom component API.
+ */
+async function showPicker(
+  ctx: ExtensionContext,
+  items: SelectItem[],
+  headerText: string,
+  maxVisible: number,
+): Promise<string | null> {
+  return ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+    const container = new Container();
+    container.addChild(new DynamicBorder((s) => theme.fg("accent", s)));
+    container.addChild(new Text(theme.fg("accent", theme.bold(headerText))));
+
+    const selectList = new SelectList(items, Math.min(items.length, maxVisible), {
+      selectedPrefix: (text: string) => theme.fg("accent", text),
+      selectedText: (text: string) => theme.fg("accent", text),
+      description: (text: string) => theme.fg("muted", text),
+      scrollInfo: (text: string) => theme.fg("dim", text),
+      noMatch: (text: string) => theme.fg("warning", text),
+    });
+
+    selectList.onSelect = (item) => done(item.value);
+    selectList.onCancel = () => done(null);
+    container.addChild(selectList);
+    container.addChild(new Text(theme.fg("dim", "↑↓ navigate • enter select • esc cancel")));
+    container.addChild(new DynamicBorder((s) => theme.fg("accent", s)));
+
+    return {
+      render(width: number) {
+        return container.render(width);
+      },
+      invalidate() {
+        container.invalidate();
+      },
+      handleInput(data: string) {
+        selectList.handleInput(data);
+        tui.requestRender();
+      },
+    };
+  });
+}
+
+// ─── Selection Handlers ──────────────────────────────────────────────────────
+
+async function handleSelection(
+  result: string | null,
+  manager: AgentManager,
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+): Promise<void> {
+  if (!result) return;
+
+  if (result === "(none)") {
+    await manager.clear(pi, ctx);
+    ctx.ui.notify("Agent cleared, defaults restored", "info");
+    updateBanner(ctx.ui, manager.getActive(), selectableAgents(manager.getAgents()).length);
+    return;
+  }
+
+  const success = await manager.apply(result, pi, ctx);
+  if (success) {
+    updateBanner(ctx.ui, manager.getActive(), selectableAgents(manager.getAgents()).length);
+  }
+}
+
+// ─── Public Functions ────────────────────────────────────────────────────────
+
+/**
+ * Show the agent selector UI (all primary|all agents).
+ */
+export async function showAgentSelector(
+  manager: AgentManager,
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+): Promise<void> {
+  const agents = selectableAgents(manager.getAgents());
+
+  if (agents.length === 0) {
+    ctx.ui.notify(
+      "No selectable agents found. Create agent .md files in ~/.pi/agent/agents/ or .pi/agents/",
+      "warning",
+    );
+    return;
+  }
+
+  const items: SelectItem[] = agents.map((agent) => ({
+    value: agent.name,
+    label: manager.isActive(agent.name) ? `${agent.name} (active)` : agent.name,
+    description: buildDescription(agent),
+  }));
+
+  items.push({
+    value: "(none)",
+    label: "(none)",
+    description: "Clear active agent, restore defaults",
+  });
+
+  const result = await showPicker(ctx, items, "Select Agent", 10);
+  await handleSelection(result, manager, pi, ctx);
+}
+
+/**
+ * Show search results UI.
+ */
+export async function showSearchResults(
+  manager: AgentManager,
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  query: string,
+): Promise<void> {
+  const agents = selectableAgents(manager.getAgents());
+  const results = searchAgents(agents, query);
+
+  if (results.length === 0) {
+    ctx.ui.notify(`No agents found matching "${query}"`, "warning");
+    return;
+  }
+
+  const items: SelectItem[] = results.map((r) => {
+    const snippet = r.snippets.length > 0 ? r.snippets[0].slice(0, 80) : buildDescription(r.agent);
+    const active = manager.isActive(r.name) ? " (active)" : "";
+    return {
+      value: r.name,
+      label: `${r.name}${active} [${r.score}]`,
+      description: snippet,
+    };
+  });
+
+  const result = await showPicker(ctx, items, `Search: "${query}" (${results.length} found)`, 8);
+  await handleSelection(result, manager, pi, ctx);
+}
+
+// ─── Command + Shortcut Registration ─────────────────────────────────────────
+
+/**
+ * Register all TUI commands, shortcuts, and CLI flags.
+ */
+export function registerTuiControls(manager: AgentManager, pi: ExtensionAPI): void {
+  // Ctrl+Shift+M: Cycle agents
+  pi.registerShortcut(Key.ctrlShift("m"), {
+    description: "Cycle agents",
+    handler: async (ctx) => {
+      await manager.cycle(pi, ctx);
+      updateBanner(ctx.ui, manager.getActive(), selectableAgents(manager.getAgents()).length);
+    },
+  });
+
+  // Alt+S: Search agents
+  pi.registerShortcut("alt+s", {
+    description: "Search agents",
+    handler: async (ctx) => {
+      const query = await ctx.ui.input("Search agents:", "name, description, or content");
+      if (query?.trim()) {
+        await showSearchResults(manager, pi, ctx, query.trim());
+      }
+    },
+  });
+
+  // /agent command
+  pi.registerCommand("agent", {
+    description: "Switch active agent",
+    handler: async (args, ctx: ExtensionCommandContext) => {
+      if (args?.trim()) {
+        const name = args.trim();
+        if (name === "none" || name === "clear") {
+          await manager.clear(pi, ctx);
+          ctx.ui.notify("Agent cleared, defaults restored", "info");
+          updateBanner(ctx.ui, manager.getActive(), selectableAgents(manager.getAgents()).length);
+          return;
+        }
+        const success = await manager.apply(name, pi, ctx);
+        if (!success) {
+          const available = manager.getAgents().map((a) => a.name).join(", ") || "(none defined)";
+          ctx.ui.notify(`Unknown agent "${name}". Available: ${available}`, "error");
+          return;
+        }
+        updateBanner(ctx.ui, manager.getActive(), selectableAgents(manager.getAgents()).length);
+        return;
+      }
+      await showAgentSelector(manager, pi, ctx);
+    },
+  });
+
+  // /agents command
+  pi.registerCommand("agents", {
+    description: "List available agents",
+    handler: async (_args, ctx) => {
+      const agents = manager.getAgents();
+      if (agents.length === 0) {
+        ctx.ui.notify("No agents found.", "warning");
+        return;
+      }
+      const lines = agents.map((a) => {
+        const marker = manager.isActive(a.name) ? "● " : "○ ";
+        const mode = a.mode === "all" ? "" : ` [${a.mode}]`;
+        const desc = a.description ? ` - ${a.description}` : "";
+        return `${marker}${a.name}${mode}${desc}`;
+      });
+      ctx.ui.notify(`Available agents:\n${lines.join("\n")}`, "info");
+    },
+  });
+
+  // /agent-search command
+  pi.registerCommand("agent-search", {
+    description: "Search agents by name, description, or content",
+    handler: async (args, ctx: ExtensionCommandContext) => {
+      if (args?.trim()) {
+        await showSearchResults(manager, pi, ctx, args.trim());
+        return;
+      }
+      const query = await ctx.ui.input("Search agents:", "name, description, or content");
+      if (query?.trim()) {
+        await showSearchResults(manager, pi, ctx, query.trim());
+      }
+    },
+  });
+}