@gotgenes/pi-subagents 17.5.0 → 18.0.0

package/src/ui/agent-creation-wizard.ts

@@ -1,233 +0,0 @@
-/**
- * agent-creation-wizard.ts — AI-generation and manual-form agent creation flows.
- *
- * Extracted from agent-menu.ts to give each concern a single responsibility.
- * Receives dependencies via injection — no direct `node:fs` imports.
- */
-
-import { join } from "node:path";
-
-import { BUILTIN_TOOL_NAMES } from "#src/config/agent-types";
-import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
-import type { Subagent } from "#src/types";
-import type { AgentFileOps } from "#src/ui/agent-file-ops";
-import { writeAgentFile } from "#src/ui/agent-file-writer";
-import type { MenuUI } from "#src/ui/agent-menu";
-
-// ---- Deps interface ----
-
-/** Narrow manager interface for agent spawning (generate wizard). */
-export interface WizardManager {
-  spawnAndWait: (
-    parentSnapshot: ParentSnapshot,
-    type: string,
-    prompt: string,
-    opts: { description: string; maxTurns: number },
-  ) => Promise<Subagent>;
-}
-
-/** Narrow registry interface for reloading after creation. */
-export interface WizardRegistry {
-  reload(): void;
-}
-
-// ---- Class ----
-
-export class AgentCreationWizard {
-  constructor(
-    private readonly fileOps: AgentFileOps,
-    private readonly manager: WizardManager,
-    private readonly registry: WizardRegistry,
-    private readonly personalAgentsDir: string,
-    private readonly projectAgentsDir: string,
-  ) {}
-
-  async showCreateWizard(ui: MenuUI, parentSnapshot: ParentSnapshot): Promise<void> {
-    const location = await ui.select("Choose location", [
-      "Project (.pi/agents/)",
-      `Personal (${this.personalAgentsDir})`,
-    ]);
-    if (!location) return;
-
-    const targetDir = location.startsWith("Project")
-      ? this.projectAgentsDir
-      : this.personalAgentsDir;
-
-    const method = await ui.select("Creation method", [
-      "Generate with Claude (recommended)",
-      "Manual configuration",
-    ]);
-    if (!method) return;
-
-    if (method.startsWith("Generate")) {
-      await this.showGenerateWizard(ui, parentSnapshot, targetDir);
-    } else {
-      await this.showManualWizard(ui, targetDir);
-    }
-  }
-
-  private async showGenerateWizard(
-    ui: MenuUI,
-    parentSnapshot: ParentSnapshot,
-    targetDir: string,
-  ): Promise<void> {
-    const description = await ui.input("Describe what this agent should do");
-    if (!description) return;
-
-    const name = await ui.input("Agent name (filename, no spaces)");
-    if (!name) return;
-
-    this.fileOps.ensureDir(targetDir);
-
-    const targetPath = join(targetDir, `${name}.md`);
-    if (this.fileOps.exists(targetPath)) {
-      const overwrite = await ui.confirm(
-        "Overwrite",
-        `${targetPath} already exists. Overwrite?`,
-      );
-      if (!overwrite) return;
-    }
-
-    ui.notify("Generating agent definition...", "info");
-
-    const generatePrompt = `Create a custom pi sub-agent definition file based on this description: "${description}"
-
-Write a markdown file to: ${targetPath}
-
-The file format is a markdown file with YAML frontmatter and a system prompt body:
-
-\`\`\`markdown
----
-description: <one-line description shown in UI>
-tools: <comma-separated built-in tools: read, bash, edit, write, grep, find, ls. Use "none" for no tools. Omit for all tools>
-model: <optional model as "provider/modelId", e.g. "anthropic/claude-haiku-4-5-20251001". Omit to inherit parent model>
-thinking: <optional thinking level: off, minimal, low, medium, high, xhigh. Omit to inherit>
-max_turns: <optional max agentic turns. 0 or omit for unlimited (default)>
-prompt_mode: <"replace" (body IS the full system prompt) or "append" (body is appended to default prompt). Default: append>
-inherit_context: <true to fork parent conversation into agent so it sees chat history. Default: false>
-run_in_background: <true to run in background by default. Default: false>
----
-
-<system prompt body — instructions for the agent>
-\`\`\`
-
-Guidelines for choosing settings:
-- For read-only tasks (review, analysis): tools: read, bash, grep, find, ls
-- For code modification tasks: include edit, write
-- Use prompt_mode: append if the agent should keep the default system prompt and add specialization on top
-- Use prompt_mode: replace for fully custom agents with their own personality/instructions
-- Set inherit_context: true if the agent needs to know what was discussed in the parent conversation
-- Only include frontmatter fields that differ from defaults — omit fields where the default is fine
-
-Write the file using the write tool. Only write the file, nothing else.`;
-
-    const record = await this.manager.spawnAndWait(
-      parentSnapshot,
-      "general-purpose",
-      generatePrompt,
-      {
-        description: `Generate ${name} agent`,
-        maxTurns: 5,
-      },
-    );
-
-    if (record.status === "error") {
-      ui.notify(`Generation failed: ${record.error}`, "warning");
-      return;
-    }
-
-    this.registry.reload();
-
-    if (this.fileOps.exists(targetPath)) {
-      ui.notify(`Created ${targetPath}`, "info");
-    } else {
-      ui.notify(
-        "Agent generation completed but file was not created. Check the agent output.",
-        "warning",
-      );
-    }
-  }
-
-  private async showManualWizard(ui: MenuUI, targetDir: string): Promise<void> {
-    const name = await ui.input("Agent name (filename, no spaces)");
-    if (!name) return;
-
-    const description = await ui.input("Description (one line)");
-    if (!description) return;
-
-    const toolChoice = await ui.select("Tools", [
-      "all",
-      "none",
-      "read-only (read, bash, grep, find, ls)",
-      "custom...",
-    ]);
-    if (!toolChoice) return;
-
-    let tools: string;
-    if (toolChoice === "all") {
-      tools = BUILTIN_TOOL_NAMES.join(", ");
-    } else if (toolChoice === "none") {
-      tools = "none";
-    } else if (toolChoice.startsWith("read-only")) {
-      tools = "read, bash, grep, find, ls";
-    } else {
-      const customTools = await ui.input(
-        "Tools (comma-separated)",
-        BUILTIN_TOOL_NAMES.join(", "),
-      );
-      if (!customTools) return;
-      tools = customTools;
-    }
-
-    const modelChoice = await ui.select("Model", [
-      "inherit (parent model)",
-      "haiku",
-      "sonnet",
-      "opus",
-      "custom...",
-    ]);
-    if (!modelChoice) return;
-
-    let modelLine = "";
-    if (modelChoice === "haiku")
-      modelLine = "\nmodel: anthropic/claude-haiku-4-5-20251001";
-    else if (modelChoice === "sonnet")
-      modelLine = "\nmodel: anthropic/claude-sonnet-4-6";
-    else if (modelChoice === "opus")
-      modelLine = "\nmodel: anthropic/claude-opus-4-6";
-    else if (modelChoice === "custom...") {
-      const customModel = await ui.input("Model (provider/modelId)");
-      if (customModel) modelLine = `\nmodel: ${customModel}`;
-    }
-
-    const thinkingChoice = await ui.select("Thinking level", [
-      "inherit",
-      "off",
-      "minimal",
-      "low",
-      "medium",
-      "high",
-      "xhigh",
-    ]);
-    if (!thinkingChoice) return;
-
-    let thinkingLine = "";
-    if (thinkingChoice !== "inherit") thinkingLine = `\nthinking: ${thinkingChoice}`;
-
-    const systemPrompt = await ui.editor("System prompt", "");
-    if (systemPrompt === undefined) return;
-
-    const content = `---
-description: ${description}
-tools: ${tools}${modelLine}${thinkingLine}
-prompt_mode: replace
----
-
-${systemPrompt}
-`;
-
-    const targetPath = join(targetDir, `${name}.md`);
-
-    await writeAgentFile(this.fileOps, ui, this.registry, targetPath, content, "Created");
-  }
-}

package/src/ui/agent-file-ops.ts

@@ -1,59 +0,0 @@
-/**
- * agent-file-ops.ts — Filesystem abstraction for agent .md file operations.
- *
- * Decouples menu sub-modules from direct `node:fs` imports, making them
- * testable via plain stub objects without `vi.mock()`.
- */
-
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-
-// ---- Interface ----
-
-/** Filesystem operations for agent `.md` files. */
-export interface AgentFileOps {
-  exists(filePath: string): boolean;
-  read(filePath: string): string | undefined;
-  write(filePath: string, content: string): void;
-  remove(filePath: string): void;
-  ensureDir(dirPath: string): void;
-  findAgentFile(name: string, dirs: string[]): string | undefined;
-}
-
-// ---- Production implementation ----
-
-/** Production implementation wrapping `node:fs` synchronous APIs. */
-export class FsAgentFileOps implements AgentFileOps {
-  exists(filePath: string): boolean {
-    return existsSync(filePath);
-  }
-
-  read(filePath: string): string | undefined {
-    try {
-      return readFileSync(filePath, "utf-8");
-    } catch {
-      return undefined;
-    }
-  }
-
-  write(filePath: string, content: string): void {
-    mkdirSync(dirname(filePath), { recursive: true });
-    writeFileSync(filePath, content, "utf-8");
-  }
-
-  remove(filePath: string): void {
-    unlinkSync(filePath);
-  }
-
-  ensureDir(dirPath: string): void {
-    mkdirSync(dirPath, { recursive: true });
-  }
-
-  findAgentFile(name: string, dirs: string[]): string | undefined {
-    for (const dir of dirs) {
-      const p = join(dir, `${name}.md`);
-      if (existsSync(p)) return p;
-    }
-    return undefined;
-  }
-}

package/src/ui/agent-file-writer.ts

@@ -1,55 +0,0 @@
-/**
- * agent-file-writer.ts — Shared overwrite-guard + write + reload + notify helper.
- *
- * Extracted from AgentConfigEditor.ejectAgent and AgentCreationWizard.showManualWizard
- * to eliminate the duplicated 20-line pattern. Uses narrow interfaces (ISP) so callers
- * are not forced to depend on the full AgentFileOps or MenuUI shapes.
- */
-
-// ---- Narrow interfaces ----
-
-/** Minimal file operations needed by the overwrite-guard-and-write pattern. */
-export interface FileWriter {
-	exists(filePath: string): boolean;
-	write(filePath: string, content: string): void;
-}
-
-/** Minimal UI needed by the overwrite-guard-and-write pattern. */
-export interface WriterUI {
-	confirm(title: string, message: string): Promise<boolean>;
-	notify(message: string, level: "info" | "warning" | "error"): void;
-}
-
-/** Registry that can be reloaded after file changes. */
-export interface Reloadable {
-	reload(): void;
-}
-
-// ---- Function ----
-
-/**
- * Write an agent `.md` file with an overwrite guard.
- *
- * If `targetPath` already exists, prompts the user for confirmation before writing.
- * On write: reloads the registry and notifies the user as `"${label} ${targetPath}"`.
- *
- * Returns `true` if the file was written, `false` if the user declined to overwrite.
- */
-export async function writeAgentFile(
-	fileOps: FileWriter,
-	ui: WriterUI,
-	registry: Reloadable,
-	targetPath: string,
-	content: string,
-	label: string,
-): Promise<boolean> {
-	if (fileOps.exists(targetPath)) {
-		const overwrite = await ui.confirm("Overwrite", `${targetPath} already exists. Overwrite?`);
-		if (!overwrite) return false;
-	}
-
-	fileOps.write(targetPath, content);
-	registry.reload();
-	ui.notify(`${label} ${targetPath}`, "info");
-	return true;
-}

package/src/ui/agent-menu.ts

@@ -1,331 +0,0 @@
-/* eslint-disable @typescript-eslint/no-unsafe-assignment -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
-import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
-import { AgentTypeRegistry } from "#src/config/agent-types";
-import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
-import { type ModelRegistry, resolveModel } from "#src/session/model-resolver";
-import { getModelLabelFromConfig } from "#src/tools/helpers";
-import type { AgentConfig, Subagent } from "#src/types";
-import { AgentConfigEditor } from "#src/ui/agent-config-editor";
-import { AgentCreationWizard } from "#src/ui/agent-creation-wizard";
-import type { AgentFileOps } from "#src/ui/agent-file-ops";
-import { formatDuration, getDisplayName } from "#src/ui/display";
-
-// ---- Narrow interfaces ----
-
-/** Narrow manager interface for menu operations. */
-export interface AgentMenuManager {
-  listAgents: () => Subagent[];
-  getRecord: (id: string) => Subagent | undefined;
-  /** Used by generate wizard to spawn an agent that writes the .md file. */
-  spawnAndWait: (
-    parentSnapshot: ParentSnapshot,
-    type: string,
-    prompt: string,
-    opts: { description: string; maxTurns: number },
-  ) => Promise<Subagent>;
-}
-
-/** Narrow settings interface required by the agent menu. */
-export interface AgentMenuSettings {
-  readonly maxConcurrent: number;
-  readonly defaultMaxTurns: number | undefined;
-  readonly graceTurns: number;
-  applyMaxConcurrent(n: number): { message: string; level: "info" | "warning" };
-  applyDefaultMaxTurns(n: number): { message: string; level: "info" | "warning" };
-  applyGraceTurns(n: number): { message: string; level: "info" | "warning" };
-}
-
-// ---- Narrow UI context types ----
-
-/** Narrow UI interface — only the ctx.ui methods menu handlers actually call. */
-export interface MenuUI {
-  select(title: string, options: string[]): Promise<string | undefined>;
-  confirm(title: string, message: string): Promise<boolean>;
-  input(title: string, defaultValue?: string): Promise<string | undefined>;
-  notify(message: string, level: "info" | "warning" | "error"): void;
-  editor(title: string, content: string): Promise<string | undefined>;
-  custom<R>(component: any, options?: any): Promise<R>;
-}
-
-// ---- Class ----
-
-/**
- * Handler for the `/agents` slash command.
- *
- * Call `handle(ctx)` from the Pi command registration to open the interactive menu.
- */
-export class AgentsMenuHandler {
-  private readonly editor: AgentConfigEditor;
-  private readonly wizard: AgentCreationWizard;
-
-  constructor(
-    private readonly manager: AgentMenuManager,
-    private readonly registry: AgentTypeRegistry,
-    private readonly settings: AgentMenuSettings,
-    fileOps: AgentFileOps,
-    personalAgentsDir: string,
-    projectAgentsDir: string,
-  ) {
-    this.editor = new AgentConfigEditor(
-      fileOps,
-      registry,
-      personalAgentsDir,
-      projectAgentsDir,
-    );
-    this.wizard = new AgentCreationWizard(
-      fileOps,
-      manager,
-      registry,
-      personalAgentsDir,
-      projectAgentsDir,
-    );
-  }
-
-  async handle({
-    ui,
-    modelRegistry,
-    parentSnapshot,
-  }: {
-    ui: MenuUI;
-    modelRegistry: ModelRegistry;
-    parentSnapshot: ParentSnapshot;
-  }): Promise<void> {
-    await this.showAgentsMenu(ui, modelRegistry, parentSnapshot);
-  }
-
-  private getModelLabel(type: string, modelRegistry?: ModelRegistry): string {
-    const cfg = this.registry.resolveAgentConfig(type);
-    if (!cfg.model) return "inherit";
-    if (modelRegistry) {
-      const resolved = resolveModel(cfg.model, modelRegistry);
-      if (typeof resolved === "string") return "inherit";
-    }
-    return getModelLabelFromConfig(cfg.model);
-  }
-
-  private async showAgentsMenu(
-    ui: MenuUI,
-    modelRegistry: ModelRegistry,
-    parentSnapshot: ParentSnapshot,
-  ): Promise<void> {
-    this.registry.reload();
-    const allNames = this.registry.getAllTypes();
-
-    const options: string[] = [];
-
-    const agents = this.manager.listAgents();
-    if (agents.length > 0) {
-      const running = agents.filter(
-        (a) => a.status === "running" || a.status === "queued",
-      ).length;
-      const done = agents.filter(
-        (a) => a.status === "completed" || a.status === "steered",
-      ).length;
-      options.push(
-        `Running agents (${agents.length}) — ${running} running, ${done} done`,
-      );
-    }
-
-    if (allNames.length > 0) {
-      options.push(`Agent types (${allNames.length})`);
-    }
-
-    options.push("Create new agent");
-    options.push("Settings");
-
-    const noAgentsMsg =
-      allNames.length === 0 && agents.length === 0
-        ? "No agents found. Create specialized subagents that can be delegated to.\n\n" +
-          "Each subagent has its own context window, custom system prompt, and specific tools.\n\n" +
-          "Try creating: Code Reviewer, Security Auditor, Test Writer, or Documentation Writer.\n\n"
-        : "";
-
-    if (noAgentsMsg) {
-      ui.notify(noAgentsMsg, "info");
-    }
-
-    const choice = await ui.select("Agents", options);
-    if (!choice) return;
-
-    if (choice.startsWith("Running agents (")) {
-      await this.showRunningAgents(ui);
-      await this.showAgentsMenu(ui, modelRegistry, parentSnapshot);
-    } else if (choice.startsWith("Agent types (")) {
-      await this.showAllAgentsList(ui, modelRegistry);
-      await this.showAgentsMenu(ui, modelRegistry, parentSnapshot);
-    } else if (choice === "Create new agent") {
-      await this.wizard.showCreateWizard(ui, parentSnapshot);
-    } else if (choice === "Settings") {
-      await this.showSettings(ui);
-      await this.showAgentsMenu(ui, modelRegistry, parentSnapshot);
-    }
-  }
-
-  private async showAllAgentsList(ui: MenuUI, modelRegistry: ModelRegistry): Promise<void> {
-    const allNames = this.registry.getAllTypes();
-    if (allNames.length === 0) {
-      ui.notify("No agents.", "info");
-      return;
-    }
-
-    const sourceIndicator = (cfg: AgentConfig | undefined) => {
-      const disabled = cfg?.enabled === false;
-      if (cfg?.source === "project") return disabled ? "✕• " : "•  ";
-      if (cfg?.source === "global") return disabled ? "✕◦ " : "◦  ";
-      if (disabled) return "✕  ";
-      return "   ";
-    };
-
-    const entries = allNames.map((name) => {
-      const cfg = this.registry.resolveAgentConfig(name);
-      const disabled = cfg.enabled === false;
-      const model = this.getModelLabel(name, modelRegistry);
-      const indicator = sourceIndicator(cfg);
-      const prefix = `${indicator}${name} · ${model}`;
-      const desc = disabled ? "(disabled)" : cfg.description;
-      return { name, prefix, desc };
-    });
-    const maxPrefix = Math.max(...entries.map((e) => e.prefix.length));
-
-    const hasCustom = allNames.some((n) => {
-      const c = this.registry.resolveAgentConfig(n);
-      return !c.isDefault && c.enabled !== false;
-    });
-    const hasDisabled = allNames.some(
-      (n) => this.registry.resolveAgentConfig(n).enabled === false,
-    );
-    const legendParts: string[] = [];
-    if (hasCustom) legendParts.push("• = project  ◦ = global");
-    if (hasDisabled) legendParts.push("✕ = disabled");
-    const legend = legendParts.length ? "\n" + legendParts.join("  ") : "";
-
-    const options = entries.map(
-      ({ prefix, desc }) => `${prefix.padEnd(maxPrefix)} — ${desc}`,
-    );
-    if (legend) options.push(legend);
-
-    const choice = await ui.select("Agent types", options);
-    if (!choice) return;
-
-    const agentName = choice
-      .split(" · ")[0]
-      .replace(/^[•◦✕\s]+/, "")
-      .trim();
-    if (this.registry.resolveType(agentName) != null) {
-      await this.editor.showAgentDetail(ui, agentName);
-      await this.showAllAgentsList(ui, modelRegistry);
-    }
-  }
-
-  private async showRunningAgents(ui: MenuUI): Promise<void> {
-    const agents = this.manager.listAgents();
-    if (agents.length === 0) {
-      ui.notify("No agents.", "info");
-      return;
-    }
-
-    const options = agents.map((a) => {
-      const dn = getDisplayName(a.type, this.registry);
-      const dur = formatDuration(a.startedAt, a.completedAt);
-      return `${dn} (${a.description}) · ${a.toolUses} tools · ${a.status} · ${dur}`;
-    });
-
-    const choice = await ui.select("Running agents", options);
-    if (!choice) return;
-
-    const idx = options.indexOf(choice);
-    if (idx < 0) return;
-    const record = agents[idx];
-
-    await this.viewAgentConversation(ui, record);
-    await this.showRunningAgents(ui);
-  }
-
-  private async viewAgentConversation(ui: MenuUI, record: Subagent): Promise<void> {
-    if (!record.isSessionReady()) {
-      ui.notify(
-        `Agent is ${record.status === "queued" ? "queued" : "expired"} — no session available.`,
-        "info",
-      );
-      return;
-    }
-
-    const { ConversationViewer, VIEWPORT_HEIGHT_PCT } = await import(
-      "./conversation-viewer"
-    );
-
-    await ui.custom<undefined>(
-      (tui: any, theme: any, _keybindings: any, done: any) => {
-        return new ConversationViewer({
-          tui,
-          record,
-          theme,
-          done,
-          registry: this.registry,
-          wrapText: wrapTextWithAnsi,
-        });
-      },
-      {
-        overlay: true,
-        overlayOptions: {
-          anchor: "center",
-          width: "90%",
-          maxHeight: `${VIEWPORT_HEIGHT_PCT}%`,
-        },
-      },
-    );
-  }
-
-  private async showSettings(ui: MenuUI): Promise<void> {
-    const choice = await ui.select("Settings", [
-      `Max concurrency (current: ${this.settings.maxConcurrent})`,
-      `Default max turns (current: ${this.settings.defaultMaxTurns ?? "unlimited"})`,
-      `Grace turns (current: ${this.settings.graceTurns})`,
-    ]);
-    if (!choice) return;
-
-    if (choice.startsWith("Max concurrency")) {
-      const val = await ui.input(
-        "Max concurrent background agents",
-        String(this.settings.maxConcurrent),
-      );
-      if (val) {
-        const n = parseInt(val, 10);
-        if (n >= 1) {
-          const toast = this.settings.applyMaxConcurrent(n);
-          ui.notify(toast.message, toast.level);
-        } else {
-          ui.notify("Must be a positive integer.", "warning");
-        }
-      }
-    } else if (choice.startsWith("Default max turns")) {
-      const val = await ui.input(
-        "Default max turns before wrap-up (0 = unlimited)",
-        String(this.settings.defaultMaxTurns ?? 0),
-      );
-      if (val) {
-        const n = parseInt(val, 10);
-        if (n >= 0) {
-          const toast = this.settings.applyDefaultMaxTurns(n);
-          ui.notify(toast.message, toast.level);
-        } else {
-          ui.notify("Must be 0 (unlimited) or a positive integer.", "warning");
-        }
-      }
-    } else if (choice.startsWith("Grace turns")) {
-      const val = await ui.input(
-        "Grace turns after wrap-up steer",
-        String(this.settings.graceTurns),
-      );
-      if (val) {
-        const n = parseInt(val, 10);
-        if (n >= 1) {
-          const toast = this.settings.applyGraceTurns(n);
-          ui.notify(toast.message, toast.level);
-        } else {
-          ui.notify("Must be a positive integer.", "warning");
-        }
-      }
-    }
-  }
-}