@tintinweb/pi-subagents 0.2.0

package/src/prompts.ts

@@ -0,0 +1,163 @@
+/**
+ * prompts.ts — System prompts per agent type.
+ */
+
+import type { EnvInfo } from "./types.js";
+
+// ---- Reusable prompt blocks ----
+
+const READ_ONLY_PROHIBITION = `You are STRICTLY PROHIBITED from:
+- Creating new files
+- Modifying existing files
+- Deleting files
+- Moving or copying files
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state`;
+
+const READ_ONLY_TOOLS = `# Tool Usage
+- Use the find tool for file pattern matching (NOT the bash find command)
+- Use the grep tool for content search (NOT bash grep/rg command)
+- Use the read tool for reading files (NOT bash cat/head/tail)
+- Use Bash ONLY for read-only operations`;
+
+const FULL_TOOL_USAGE = `# Tool Usage
+- Use the read tool instead of cat/head/tail
+- Use the edit tool instead of sed/awk
+- Use the write tool instead of echo/heredoc
+- Use the find tool instead of bash find/ls for file search
+- Use the grep tool instead of bash grep/rg for content search
+- Make independent tool calls in parallel`;
+
+const GIT_SAFETY = `# Git Safety
+- NEVER update git config
+- NEVER run destructive git commands (push --force, reset --hard, checkout ., restore ., clean -f, branch -D) without explicit request
+- NEVER skip hooks (--no-verify, --no-gpg-sign) unless explicitly asked
+- NEVER force push to main/master — warn the user if they request it
+- Always create NEW commits, never amend existing ones. When a pre-commit hook fails, the commit did NOT happen — so --amend would modify the PREVIOUS commit. Fix the issue, re-stage, and create a NEW commit
+- Stage specific files by name, not git add -A or git add .
+- NEVER commit changes unless the user explicitly asks
+- NEVER push unless the user explicitly asks
+- NEVER use git commands with the -i flag (like git rebase -i or git add -i) — they require interactive input
+- Do not use --no-edit with git rebase commands
+- Do not commit files that likely contain secrets (.env, credentials.json, etc); warn the user if they request it`;
+
+const OUTPUT_RULES = `# Output
+- Use absolute file paths
+- Do not use emojis
+- Be concise but complete`;
+
+export function buildSystemPrompt(type: string, cwd: string, env: EnvInfo): string {
+  const commonHeader = `You are a pi coding agent sub-agent.
+You have been invoked to handle a specific task autonomously.
+
+# Environment
+Working directory: ${cwd}
+${env.isGitRepo ? `Git repository: yes\nBranch: ${env.branch}` : "Not a git repository"}
+Platform: ${env.platform}`;
+
+  switch (type) {
+    case "Explore":
+      return `${commonHeader}
+
+# 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.
+
+${READ_ONLY_PROHIBITION}
+
+Use Bash ONLY for read-only operations: ls, git status, git log, git diff, find, cat, head, tail.
+
+${READ_ONLY_TOOLS}
+- Make independent tool calls in parallel for efficiency
+- Adapt search approach based on thoroughness level specified
+
+# Output
+- Use absolute file paths in all references
+- Report findings as regular messages
+- Do not use emojis
+- Be thorough and precise`;
+
+    case "Plan":
+      return `${commonHeader}
+
+# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
+You are a software architect and planning specialist.
+Your role is EXCLUSIVELY to explore the codebase and design implementation plans.
+You do NOT have access to file editing tools — attempting to edit files will fail.
+
+${READ_ONLY_PROHIBITION}
+
+# Planning Process
+1. Understand requirements
+2. Explore thoroughly (read files, find patterns, understand architecture)
+3. Design solution based on your assigned perspective
+4. Detail the plan with step-by-step implementation strategy
+
+# Requirements
+- Consider trade-offs and architectural decisions
+- Identify dependencies and sequencing
+- Anticipate potential challenges
+- Follow existing patterns where appropriate
+
+${READ_ONLY_TOOLS}
+
+# Output Format
+- Use absolute file paths
+- Do not use emojis
+- End your response with:
+
+### Critical Files for Implementation
+List 3-5 files most critical for implementing this plan:
+- /absolute/path/to/file.ts - [Brief reason]`;
+
+    case "general-purpose":
+      return `${commonHeader}
+
+# Role
+You are a general-purpose coding agent for complex, multi-step tasks.
+You have full access to read, write, edit files, and execute commands.
+Do what has been asked; nothing more, nothing less.
+
+${FULL_TOOL_USAGE}
+
+# File Operations
+- NEVER create files unless absolutely necessary
+- Prefer editing existing files over creating new ones
+- NEVER create documentation files unless explicitly requested
+
+${GIT_SAFETY}
+
+${OUTPUT_RULES}`;
+
+    case "statusline-setup":
+      return `${commonHeader}
+
+# Role
+You configure settings. You can read and edit files only.
+Focus on the specific configuration task requested.
+Use absolute file paths.`;
+
+    case "claude-code-guide":
+      return `${commonHeader}
+
+# Role
+You help answer questions about the tool, its features, and capabilities.
+Search documentation, read config files, and provide accurate answers.
+You have read-only access to the codebase for reference.
+Use absolute file paths.`;
+
+    default:
+      // Custom agents or unknown: general-purpose base without git safety / file ops
+      return `${commonHeader}
+
+# Role
+You are a general-purpose coding agent for complex, multi-step tasks.
+You have full access to read, write, edit files, and execute commands.
+Do what has been asked; nothing more, nothing less.
+
+${FULL_TOOL_USAGE}
+
+${OUTPUT_RULES}`;
+  }
+}

package/src/types.ts

@@ -0,0 +1,84 @@
+/**
+ * types.ts — Type definitions for the subagent system.
+ */
+
+import type { AgentSession } from "@mariozechner/pi-coding-agent";
+import type { ThinkingLevel } from "@mariozechner/pi-agent-core";
+
+export type { ThinkingLevel };
+
+/** Built-in agent types. Custom agents use arbitrary string names. */
+export type BuiltinSubagentType = "general-purpose" | "Explore" | "Plan" | "statusline-setup" | "claude-code-guide";
+
+/** Agent type: built-in or custom (any string). */
+export type SubagentType = BuiltinSubagentType | (string & {});
+
+/** Display name mapping for built-in types. */
+export const DISPLAY_NAMES: Record<BuiltinSubagentType, string> = {
+  "general-purpose": "Agent",
+  "Explore": "Explore",
+  "Plan": "Plan",
+  "statusline-setup": "Config",
+  "claude-code-guide": "Guide",
+};
+
+export const SUBAGENT_TYPES: BuiltinSubagentType[] = [
+  "general-purpose",
+  "Explore",
+  "Plan",
+  "statusline-setup",
+  "claude-code-guide",
+];
+
+export interface SubagentTypeConfig {
+  displayName: string;
+  description: string;
+  builtinToolNames: string[];
+  /** true = inherit all, string[] = only listed, false = none */
+  extensions: true | string[] | false;
+  /** true = inherit all, string[] = only listed, false = none */
+  skills: true | string[] | false;
+}
+
+/** Configuration for a custom agent loaded from .pi/agents/<name>.md */
+export interface CustomAgentConfig {
+  name: string;
+  description: string;
+  builtinToolNames: string[];
+  /** true = inherit all, string[] = only listed, false = none */
+  extensions: true | string[] | false;
+  /** true = inherit all, string[] = only listed, false = none */
+  skills: true | string[] | false;
+  model?: string;
+  thinking?: ThinkingLevel;
+  maxTurns?: number;
+  systemPrompt: string;
+  promptMode: "replace" | "append";
+  /** Default for spawn: fork parent conversation */
+  inheritContext: boolean;
+  /** Default for spawn: run in background */
+  runInBackground: boolean;
+  /** Default for spawn: no extension tools */
+  isolated: boolean;
+}
+
+export interface AgentRecord {
+  id: string;
+  type: SubagentType;
+  description: string;
+  status: "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+  result?: string;
+  error?: string;
+  toolUses: number;
+  startedAt: number;
+  completedAt?: number;
+  session?: AgentSession;
+  abortController?: AbortController;
+  promise?: Promise<string>;
+}
+
+export interface EnvInfo {
+  isGitRepo: boolean;
+  branch: string;
+  platform: string;
+}

package/src/ui/agent-widget.ts

@@ -0,0 +1,326 @@
+/**
+ * agent-widget.ts — Persistent widget showing running/completed agents above the editor.
+ *
+ * Displays a tree of agents with animated spinners, live stats, and activity descriptions.
+ * Uses the callback form of setWidget for themed rendering.
+ */
+
+import type { AgentManager } from "../agent-manager.js";
+import type { SubagentType } from "../types.js";
+import { getConfig } from "../agent-types.js";
+
+// ---- Constants ----
+
+/** Braille spinner frames for animated running indicator. */
+export const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/** Statuses that indicate an error/non-success outcome (used for linger behavior and icon rendering). */
+export const ERROR_STATUSES = new Set(["error", "aborted", "steered", "stopped"]);
+
+/** Tool name → human-readable action for activity descriptions. */
+const TOOL_DISPLAY: Record<string, string> = {
+  read: "reading",
+  bash: "running command",
+  edit: "editing",
+  write: "writing",
+  grep: "searching",
+  find: "finding files",
+  ls: "listing",
+};
+
+// ---- Types ----
+
+export type Theme = {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+};
+
+export type UICtx = {
+  setStatus(key: string, text: string | undefined): void;
+  setWidget(
+    key: string,
+    content: undefined | ((tui: any, theme: Theme) => { render(): string[]; invalidate(): void }),
+    options?: { placement?: "aboveEditor" | "belowEditor" },
+  ): void;
+};
+
+/** Per-agent live activity state. */
+export interface AgentActivity {
+  activeTools: Map<string, string>;
+  toolUses: number;
+  tokens: string;
+  responseText: string;
+  session?: { getSessionStats(): { tokens: { total: number } } };
+}
+
+/** Metadata attached to Agent tool results for custom rendering. */
+export interface AgentDetails {
+  displayName: string;
+  description: string;
+  subagentType: string;
+  toolUses: number;
+  tokens: string;
+  durationMs: number;
+  status: "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error" | "background";
+  /** Human-readable description of what the agent is currently doing. */
+  activity?: string;
+  /** Current spinner frame index (for animated running indicator). */
+  spinnerFrame?: number;
+  /** Short model name if different from parent (e.g. "haiku", "sonnet"). */
+  modelName?: string;
+  /** Notable config tags (e.g. ["thinking: high", "isolated"]). */
+  tags?: string[];
+  agentId?: string;
+  error?: string;
+}
+
+// ---- Formatting helpers ----
+
+/** Format a token count as "33.8k tokens" or "1.2M tokens". */
+export function formatTokens(count: number): string {
+  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M tokens`;
+  if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k tokens`;
+  return `${count} tokens`;
+}
+
+/** Format milliseconds as human-readable duration. */
+export function formatMs(ms: number): string {
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+/** Format duration from start/completed timestamps. */
+export function formatDuration(startedAt: number, completedAt?: number): string {
+  if (completedAt) return formatMs(completedAt - startedAt);
+  return `${formatMs(Date.now() - startedAt)} (running)`;
+}
+
+/** Get display name for any agent type (built-in or custom). */
+export function getDisplayName(type: SubagentType): string {
+  return getConfig(type).displayName;
+}
+
+/** Truncate text to a single line, max `len` chars. */
+function truncateLine(text: string, len = 60): string {
+  const line = text.split("\n").find(l => l.trim())?.trim() ?? "";
+  if (line.length <= len) return line;
+  return line.slice(0, len) + "…";
+}
+
+/** Build a human-readable activity string from currently-running tools or response text. */
+export function describeActivity(activeTools: Map<string, string>, responseText?: string): string {
+  if (activeTools.size > 0) {
+    const groups = new Map<string, number>();
+    for (const toolName of activeTools.values()) {
+      const action = TOOL_DISPLAY[toolName] ?? toolName;
+      groups.set(action, (groups.get(action) ?? 0) + 1);
+    }
+
+    const parts: string[] = [];
+    for (const [action, count] of groups) {
+      if (count > 1) {
+        parts.push(`${action} ${count} ${action === "searching" ? "patterns" : "files"}`);
+      } else {
+        parts.push(action);
+      }
+    }
+    return parts.join(", ") + "…";
+  }
+
+  // No tools active — show truncated response text if available
+  if (responseText && responseText.trim().length > 0) {
+    return truncateLine(responseText);
+  }
+
+  return "thinking…";
+}
+
+// ---- Widget manager ----
+
+export class AgentWidget {
+  private uiCtx: UICtx | undefined;
+  private widgetFrame = 0;
+  private widgetInterval: ReturnType<typeof setInterval> | undefined;
+  /** Tracks how many turns each finished agent has survived. Key: agent ID, Value: turns since finished. */
+  private finishedTurnAge = new Map<string, number>();
+  /** How many extra turns errors/aborted agents linger (completed agents clear after 1 turn). */
+  private static readonly ERROR_LINGER_TURNS = 2;
+
+  constructor(
+    private manager: AgentManager,
+    private agentActivity: Map<string, AgentActivity>,
+  ) {}
+
+  /** Set the UI context (grabbed from first tool execution). */
+  setUICtx(ctx: UICtx) {
+    this.uiCtx = ctx;
+  }
+
+  /**
+   * Called on each new turn (tool_execution_start).
+   * Ages finished agents and clears those that have lingered long enough.
+   */
+  onTurnStart() {
+    // Age all finished agents
+    for (const [id, age] of this.finishedTurnAge) {
+      this.finishedTurnAge.set(id, age + 1);
+    }
+    // Trigger a widget refresh (will filter out expired agents)
+    this.update();
+  }
+
+  /** Ensure the widget update timer is running. */
+  ensureTimer() {
+    if (!this.widgetInterval) {
+      this.widgetInterval = setInterval(() => this.update(), 80);
+    }
+  }
+
+  /** Check if a finished agent should still be shown in the widget. */
+  private shouldShowFinished(agentId: string, status: string): boolean {
+    const age = this.finishedTurnAge.get(agentId) ?? 0;
+    const maxAge = ERROR_STATUSES.has(status) ? AgentWidget.ERROR_LINGER_TURNS : 1;
+    return age < maxAge;
+  }
+
+  /** Record an agent as finished (call when agent completes). */
+  markFinished(agentId: string) {
+    if (!this.finishedTurnAge.has(agentId)) {
+      this.finishedTurnAge.set(agentId, 0);
+    }
+  }
+
+  /** Render a finished agent line. */
+  private renderFinishedLine(a: { type: SubagentType; status: string; description: string; toolUses: number; startedAt: number; completedAt?: number; error?: string }, theme: Theme): string {
+    const name = getDisplayName(a.type);
+    const duration = formatMs((a.completedAt ?? Date.now()) - a.startedAt);
+
+    let icon: string;
+    let statusText: string;
+    if (a.status === "completed") {
+      icon = theme.fg("success", "✓");
+      statusText = "";
+    } else if (a.status === "steered") {
+      icon = theme.fg("warning", "✓");
+      statusText = theme.fg("warning", " (turn limit)");
+    } else if (a.status === "stopped") {
+      icon = theme.fg("dim", "■");
+      statusText = theme.fg("dim", " stopped");
+    } else if (a.status === "error") {
+      icon = theme.fg("error", "✗");
+      const errMsg = a.error ? `: ${a.error.slice(0, 60)}` : "";
+      statusText = theme.fg("error", ` error${errMsg}`);
+    } else {
+      // aborted
+      icon = theme.fg("error", "✗");
+      statusText = theme.fg("warning", " aborted");
+    }
+
+    const parts: string[] = [];
+    if (a.toolUses > 0) parts.push(`${a.toolUses} tool use${a.toolUses === 1 ? "" : "s"}`);
+    parts.push(duration);
+
+    return `${icon} ${theme.fg("dim", name)}  ${theme.fg("dim", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", parts.join(" · "))}${statusText}`;
+  }
+
+  /** Force an immediate widget update. */
+  update() {
+    if (!this.uiCtx) return;
+    const allAgents = this.manager.listAgents();
+    const running = allAgents.filter(a => a.status === "running");
+    const queued = allAgents.filter(a => a.status === "queued");
+    const finished = allAgents.filter(a =>
+      a.status !== "running" && a.status !== "queued" && a.completedAt
+      && this.shouldShowFinished(a.id, a.status),
+    );
+
+    const hasActive = running.length > 0 || queued.length > 0;
+    const hasFinished = finished.length > 0;
+
+    // Nothing to show — clear widget
+    if (!hasActive && !hasFinished) {
+      this.uiCtx.setWidget("agents", undefined);
+      this.uiCtx.setStatus("subagents", undefined);
+      if (this.widgetInterval) { clearInterval(this.widgetInterval); this.widgetInterval = undefined; }
+      // Clean up stale entries
+      for (const [id] of this.finishedTurnAge) {
+        if (!allAgents.some(a => a.id === id)) this.finishedTurnAge.delete(id);
+      }
+      return;
+    }
+
+    // Status bar
+    if (hasActive) {
+      const statusParts: string[] = [];
+      if (running.length > 0) statusParts.push(`${running.length} running`);
+      if (queued.length > 0) statusParts.push(`${queued.length} queued`);
+      const total = running.length + queued.length;
+      this.uiCtx.setStatus("subagents", `${statusParts.join(", ")} agent${total === 1 ? "" : "s"}`);
+    } else {
+      this.uiCtx.setStatus("subagents", undefined);
+    }
+
+    this.widgetFrame++;
+    const frame = SPINNER[this.widgetFrame % SPINNER.length];
+
+    this.uiCtx.setWidget("agents", (_tui, theme) => {
+      const headingColor = hasActive ? "accent" : "dim";
+      const headingIcon = hasActive ? "●" : "○";
+      const lines: string[] = [theme.fg(headingColor, headingIcon) + " " + theme.fg(headingColor, "Agents")];
+
+      // --- Finished agents (shown first, dimmed) ---
+      for (let i = 0; i < finished.length; i++) {
+        const a = finished[i];
+        const isLast = !hasActive && i === finished.length - 1;
+        const connector = isLast ? "└─" : "├─";
+        lines.push(theme.fg("dim", connector) + " " + this.renderFinishedLine(a, theme));
+      }
+
+      // --- Running agents ---
+      const isLastSection = queued.length === 0;
+      for (let i = 0; i < running.length; i++) {
+        const a = running[i];
+        const isLast = isLastSection && i === running.length - 1;
+        const connector = isLast ? "└─" : "├─";
+        const name = getDisplayName(a.type);
+        const elapsed = formatMs(Date.now() - a.startedAt);
+
+        const bg = this.agentActivity.get(a.id);
+        const toolUses = bg?.toolUses ?? a.toolUses;
+        let tokenText = "";
+        if (bg?.session) {
+          try { tokenText = formatTokens(bg.session.getSessionStats().tokens.total); } catch { /* */ }
+        }
+
+        const parts: string[] = [];
+        if (toolUses > 0) parts.push(`${toolUses} tool use${toolUses === 1 ? "" : "s"}`);
+        if (tokenText) parts.push(tokenText);
+        parts.push(elapsed);
+        const statsText = parts.join(" · ");
+
+        const activity = bg ? describeActivity(bg.activeTools, bg.responseText) : "thinking…";
+
+        lines.push(theme.fg("dim", connector) + ` ${theme.fg("accent", frame)} ${theme.bold(name)}  ${theme.fg("muted", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", statsText)}`);
+        const indent = isLast ? "   " : "│  ";
+        lines.push(theme.fg("dim", indent) + theme.fg("dim", `  ⎿  ${activity}`));
+      }
+
+      // --- Queued agents (collapsed) ---
+      if (queued.length > 0) {
+        lines.push(theme.fg("dim", "└─") + ` ${theme.fg("muted", "◦")} ${theme.fg("dim", `${queued.length} queued`)}`);
+      }
+
+      return { render: () => lines, invalidate: () => {} };
+    }, { placement: "aboveEditor" });
+  }
+
+  dispose() {
+    if (this.widgetInterval) {
+      clearInterval(this.widgetInterval);
+      this.widgetInterval = undefined;
+    }
+    if (this.uiCtx) {
+      this.uiCtx.setWidget("agents", undefined);
+      this.uiCtx.setStatus("subagents", undefined);
+    }
+  }
+}