@harms-haus/pi-subagents 0.1.0

package/src/tools/retrieval.ts

@@ -0,0 +1,287 @@
+/**
+ * Retrieval Tools
+ *
+ * Tool registrations for retrieving sub-agent output and session data.
+ */
+
+import { Container, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { loadProfiles, profileSummary } from "../profiles";
+import { loadMaxLinesPerWindow } from "../settings";
+import { getLastAssistantText } from "../utils";
+import { formatTranscript, RETRIEVAL_OPTIONS } from "../format-transcript";
+import type { SessionRecord } from "../types";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  Theme,
+  AgentToolResult,
+} from "@earendil-works/pi-coding-agent";
+
+// ── Rendering Helpers ───────────────────────────────────────────────────────
+
+/**
+ * Simple renderResult that extracts and displays the first text content.
+ * Used by list_subagent_profiles (no truncation needed).
+ */
+function createSimpleRenderResult(defaultLabel: string = "(no output)") {
+  return (
+    result: AgentToolResult<unknown>,
+    _options: { expanded: boolean },
+    theme: Theme,
+    _context: unknown,
+  ) => {
+    const text = result.content[0];
+    if (!text) return new Text(theme.fg("toolOutput", defaultLabel), 0, 0);
+    const content = text.type === "text" ? text.text : defaultLabel;
+    return new Text(theme.fg("toolOutput", content), 0, 0);
+  };
+}
+
+/**
+ * Truncating renderResult for sub-agent output/session data.
+ * Shows at most maxLinesPerWindow lines with a truncation indicator.
+ * The full content is still injected into context; only the TUI display is shortened.
+ */
+function createTruncatingRenderResult(defaultLabel: string = "(no output)") {
+  return (
+    result: AgentToolResult<unknown>,
+    _options: { expanded: boolean },
+    theme: Theme,
+    _context: unknown,
+  ) => {
+    const text = result.content[0];
+    if (!text) return new Text(theme.fg("toolOutput", defaultLabel), 0, 0);
+    const content = text.type === "text" ? text.text : defaultLabel;
+    const lines = content.split("\n");
+    const maxLines: number = (result.details as Record<string, unknown>).maxLines as number;
+
+    if (lines.length <= maxLines) {
+      return new Text(theme.fg("toolOutput", content), 0, 0);
+    }
+
+    const shown = lines.slice(0, maxLines);
+    const truncated = lines.length - maxLines;
+    const indicator = theme.fg("dim", `... (${truncated} more line${truncated !== 1 ? "s" : ""})`);
+
+    const container = new Container();
+    container.addChild(new Text(theme.fg("toolOutput", shown.join("\n")), 0, 0));
+    container.addChild(new Text(indicator, 0, 0));
+    return container;
+  };
+}
+
+/**
+ * Create a renderCall function for retrieval tools that take a sessionId.
+ */
+function createSessionRenderCall(toolName: string) {
+  return (args: { sessionId?: string }, theme: Theme, _context: unknown) => {
+    return new Text(
+      theme.fg("toolTitle", theme.bold(`${toolName} `)) +
+        theme.fg("accent", args.sessionId ?? "..."),
+      0,
+      0,
+    );
+  };
+}
+
+// ── Error Constants ─────────────────────────────────────────────────────────
+
+/** Error message when a session ID is not found in the session store. */
+function sessionNotFoundMessage(sessionId: string): string {
+  return `Session "${sessionId}" not found. The session may have expired or the ID is incorrect.`;
+}
+
+/** Shared type for execute context parameter. */
+type ToolExecuteContext = ExtensionContext;
+
+/** Look up a session record, throwing if not found or has no runs. */
+function requireSession(
+  sessionStore: Map<string, SessionRecord>,
+  sessionId: string,
+): SessionRecord {
+  const record = sessionStore.get(sessionId);
+  if (!record || record.runs.length === 0) {
+    throw new Error(sessionNotFoundMessage(sessionId));
+  }
+  return record;
+}
+
+/** Register the get_subagent_output tool. */
+function registerGetSubagentOutput(
+  pi: ExtensionAPI,
+  sessionStore: Map<string, SessionRecord>,
+): void {
+  pi.registerTool({
+    name: "get_subagent_output",
+    label: "Get Sub-agent Output",
+    description: [
+      "Retrieve the last assistant text output from a completed sub-agent session.",
+      "Use this to get the results from a subagent after it finishes, without needing",
+      "the subagent to write to a file. Pass the session ID returned by delegate_to_subagents.",
+      "For resumed sessions, returns the output from the LATEST run.",
+    ].join(" "),
+    parameters: Type.Object({
+      sessionId: Type.String({ description: "The session ID returned by delegate_to_subagents" }),
+    }),
+    promptSnippet: "Get the final text output from a previously completed sub-agent session",
+    promptGuidelines: [
+      "Use get_subagent_output to retrieve the final text output from a sub-agent after",
+      "delegate_to_subagents completes, instead of asking the sub-agent to write to a file.",
+    ],
+
+    async execute(
+      _toolCallId: string,
+      params: { sessionId: string },
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      ctx: ToolExecuteContext,
+    ) {
+      const record = requireSession(sessionStore, params.sessionId);
+      const latestRun = record.runs[record.runs.length - 1];
+      if (!latestRun) throw new Error(sessionNotFoundMessage(params.sessionId));
+      const lastText = getLastAssistantText(latestRun.messages);
+      const maxLines = await loadMaxLinesPerWindow(ctx.cwd);
+      return {
+        content: [{ type: "text", text: lastText || "(no text output from sub-agent)" }],
+        details: {
+          sessionId: params.sessionId,
+          status: latestRun.status,
+          taskName: latestRun.taskName,
+          runCount: record.runs.length,
+          maxLines,
+        },
+      };
+    },
+
+    renderCall: createSessionRenderCall("get_subagent_output"),
+    renderResult: createTruncatingRenderResult("(no output)"),
+  });
+}
+
+/** Register the get_subagent_session tool. */
+function registerGetSubagentSession(
+  pi: ExtensionAPI,
+  sessionStore: Map<string, SessionRecord>,
+): void {
+  pi.registerTool({
+    name: "get_subagent_session",
+    label: "Get Sub-agent Session",
+    description: [
+      "Retrieve the complete session transcript from a sub-agent, including all messages",
+      "(assistant text, tool calls, tool results). Use this for detailed debugging or when",
+      "you need the full conversation history of a sub-agent. Pass the session ID returned",
+      "by delegate_to_subagents. For resumed sessions, returns ALL runs' data concatenated.",
+    ].join(" "),
+    parameters: Type.Object({
+      sessionId: Type.String({ description: "The session ID returned by delegate_to_subagents" }),
+    }),
+    promptSnippet: "Read the full session transcript from a previously completed sub-agent session",
+    promptGuidelines: [
+      "Use get_subagent_session when you need the FULL conversation history of a sub-agent,",
+      "including all tool calls and results. Use get_subagent_output instead when you only",
+      "need the final output.",
+    ],
+
+    async execute(
+      _toolCallId: string,
+      params: { sessionId: string },
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      ctx: ToolExecuteContext,
+    ) {
+      const record = requireSession(sessionStore, params.sessionId);
+      const transcript = formatTranscript(record.runs, RETRIEVAL_OPTIONS);
+      const latestRun = record.runs[record.runs.length - 1];
+      if (!latestRun) throw new Error(sessionNotFoundMessage(params.sessionId));
+      const maxLines = await loadMaxLinesPerWindow(ctx.cwd);
+      return {
+        content: [{ type: "text", text: transcript || "(no messages in session)" }],
+        details: {
+          sessionId: params.sessionId,
+          status: latestRun.status,
+          taskName: latestRun.taskName,
+          messageCount: record.runs.reduce((sum, r) => sum + r.messages.length, 0),
+          exitCode: latestRun.exitCode,
+          model: latestRun.model,
+          runCount: record.runs.length,
+          maxLines,
+        },
+      };
+    },
+
+    renderCall: createSessionRenderCall("get_subagent_session"),
+    renderResult: createTruncatingRenderResult("(no output)"),
+  });
+}
+
+/** Register the list_subagent_profiles tool. */
+function registerListSubagentProfiles(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "list_subagent_profiles",
+    label: "List Sub-agent Profiles",
+    description: [
+      "List all available subagent profiles that can be used with delegate_to_subagents.",
+      "Profiles are stored as .md files in ~/.pi/agent/agent-profiles/ (global) and .pi/agent-profiles/ (project-local).",
+    ].join(" "),
+    parameters: Type.Object({}),
+    promptSnippet: "List available named subagent profiles and their configurations",
+    promptGuidelines: [
+      "Use list_subagent_profiles to see which profiles are available before choosing",
+      "one for delegate_to_subagents.",
+    ],
+
+    async execute(
+      _toolCallId: string,
+      _params: Record<string, unknown>,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      ctx: ToolExecuteContext,
+    ) {
+      const profiles = loadProfiles(ctx.cwd);
+      const names = Object.keys(profiles);
+      if (names.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No subagent profiles found. Add .md files to ~/.pi/agent/agent-profiles/ or .pi/agent-profiles/.",
+            },
+          ],
+          details: { count: 0 },
+        };
+      }
+      const summaries = names
+        .map((n) => {
+          const p = profiles[n];
+          return p ? ([n, profileSummary(n, p)] as const) : null;
+        })
+        .filter((s): s is [string, string] => s !== null);
+      return {
+        content: [{ type: "text", text: summaries.map(([, s]) => s).join("\n") }],
+        details: {
+          count: names.length,
+          profiles: Object.fromEntries(summaries),
+        },
+      };
+    },
+
+    renderCall(_args: unknown, theme: Theme, _context: unknown) {
+      return new Text(theme.fg("toolTitle", theme.bold("list_subagent_profiles")), 0, 0);
+    },
+
+    renderResult: createSimpleRenderResult("(no profiles)"),
+  });
+}
+
+/**
+ * Register the retrieval tools: get_subagent_output, get_subagent_session, and list_subagent_profiles.
+ */
+export function registerRetrievalTools(
+  pi: ExtensionAPI,
+  sessionStore: Map<string, SessionRecord>,
+): void {
+  registerGetSubagentOutput(pi, sessionStore);
+  registerGetSubagentSession(pi, sessionStore);
+  registerListSubagentProfiles(pi);
+}

package/src/types.ts

@@ -0,0 +1,232 @@
+/**
+ * pi-subagents Extension Types
+ *
+ * Core type definitions and configuration constants for the subagent system.
+ */
+
+import type { Message } from "@earendil-works/pi-ai";
+
+// ── Configuration ────────────────────────────────────────────────────
+
+/** Maximum number of parallel sub-agent tasks that can be spawned */
+export const MAX_PARALLEL_TASKS = 16;
+
+/** Maximum number of concurrent sub-agent processes */
+export const MAX_CONCURRENCY = 4;
+
+/** Maximum number of messages to store per session (prevents unbounded memory growth) */
+export const MAX_MESSAGES_PER_SESSION = 500;
+
+/** Default timeout for sub-agent tasks (in seconds) */
+export const DEFAULT_TIMEOUT = 600;
+
+/** Error message for loop detection kills */
+export const LOOP_DETECTED_MESSAGE = "Loop detected: sub-agent is repeating the same tool calls";
+
+/** Custom entry type identifier for persisting subagent session data */
+export const CUSTOM_ENTRY_TYPE = "pi-subagents";
+
+// ── Types ────────────────────────────────────────────────────────────
+
+/** Tool call part in a message (used internally for type narrowing) */
+export interface ToolCallPart {
+  type: "toolCall";
+  name: string;
+  arguments?: Record<string, unknown>;
+}
+
+/** A content part from a Message — text, thinking, or tool call */
+export interface TextPart {
+  type: "text";
+  text: string;
+}
+
+export type ContentPart = TextPart | ToolCallPart | { type: string; [key: string]: unknown };
+
+/** Tool result message (used internally for message processing) */
+export interface ToolResultMessage {
+  role: "toolResult";
+  content: Array<{
+    type: string;
+    text?: string;
+  }>;
+}
+
+/** A file to inject into the sub-agent prompt, specified as a path string or an object with range options */
+export type FileSpec =
+  | string
+  | { path: string; start?: number; end?: number }
+  | { path: string; tail: number }
+  | { path: string; head: number };
+
+/** Task definition for spawning a sub-agent */
+export interface SubAgentTask {
+  name: string;
+  prompt: string;
+  cwd?: string;
+  /** Named profile from an agent-profiles/*.md file */
+  profile?: string;
+  /** Timeout in seconds (default: 600) */
+  timeout?: number;
+  /** Previous session ID to resume from */
+  resume?: string;
+  /** Files to read and prepend to the prompt */
+  files?: FileSpec[];
+}
+
+/** A single line in a sub-agent's rolling window */
+export interface WindowLine {
+  text: string;
+  kind: "text" | "tool";
+}
+
+/** Shared state fields between SubAgentWindow and SubagentSessionData */
+export interface SubagentState {
+  sessionId: string;
+  status: "running" | "completed" | "error";
+  exitCode: number | null;
+  model?: string;
+  stopReason?: string;
+  errorMessage?: string;
+  profileName?: string;
+}
+
+/** Live window tracking a sub-agent's progress */
+export interface SubAgentWindow extends SubagentState {
+  name: string;
+  lines: WindowLine[];
+  allMessages: WindowLine[];
+  /** Human-readable profile summary for display */
+  profileInfo?: string;
+  /** Provider from the agent profile (e.g. "anthropic", "openai") */
+  provider?: string;
+  /** Thinking level from the agent profile */
+  thinkingLevel?: string;
+  /** Date.now() timestamp when the sub-agent started */
+  startedAt: number;
+  /** Date.now() timestamp when the sub-agent completed (if applicable) */
+  completedAt?: number;
+  /** Task timeout in seconds */
+  timeout: number;
+  /** Total number of todo items written */
+  todoTotal?: number;
+  /** Number of completed todo items */
+  todoCompleted?: number;
+  /** Number of unique tools available to this sub-agent */
+  toolCount: number;
+  /** Number of files passed to this sub-agent */
+  fileCount: number;
+  /** Recent tool call signatures for loop detection (serialized name+args) */
+  recentToolCalls?: string[];
+}
+
+/** Persistent session data stored for retrieval */
+export interface SubagentSessionData extends SubagentState {
+  taskName: string;
+  prompt: string;
+  cwd?: string;
+  messages: Message[];
+  startedAt: number;
+}
+
+/** A record of all runs for a session ID (supports resume/multi-run) */
+export interface SessionRecord {
+  /** All runs for this session, in chronological order */
+  runs: SubagentSessionData[];
+}
+
+// ── Helper Functions ───────────────────────────────────────────────────
+
+/**
+ * Sync shared state fields from a source SubagentState to a target SubagentState.
+ * This ensures that SubAgentWindow and SubagentSessionData stay in sync.
+ */
+export function syncState(source: SubagentState, target: SubagentState): void {
+  target.status = source.status;
+  target.exitCode = source.exitCode;
+  target.model = source.model;
+  target.stopReason = source.stopReason;
+  target.errorMessage = source.errorMessage;
+}
+
+/**
+ * Serialize SubagentSessionData for storage in a custom entry.
+ * Data is already JSON-compatible by construction (parsed from child process stdout).
+ */
+export function serializeSessionData(session: SubagentSessionData): unknown {
+  return session;
+}
+
+/** Valid session status values */
+const VALID_STATUSES = new Set(["running", "completed", "error"]);
+
+/**
+ * Check if raw data has valid top-level session fields.
+ * Returns the typed record if valid, or null.
+ */
+function validateSessionShape(data: unknown): Record<string, unknown> | null {
+  if (!data || typeof data !== "object") return null;
+  const d = data as Record<string, unknown>;
+  if (
+    typeof d.sessionId !== "string" ||
+    typeof d.taskName !== "string" ||
+    typeof d.prompt !== "string" ||
+    typeof d.status !== "string" ||
+    !Array.isArray(d.messages) ||
+    d.messages.length > 1000
+  ) {
+    return null;
+  }
+  if (!VALID_STATUSES.has(d.status)) return null;
+  return d;
+}
+
+/**
+ * Check that every message in the array has a valid string `role` field.
+ */
+function validateMessages(messages: unknown[]): boolean {
+  for (const msg of messages) {
+    if (
+      !msg ||
+      typeof msg !== "object" ||
+      !("role" in msg) ||
+      typeof (msg as Record<string, unknown>).role !== "string"
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Deserialize and validate session data from a custom entry.
+ * Returns null if the data is malformed or missing required fields.
+ * Stale "running" sessions (from crashes) are converted to "error" status.
+ */
+export function deserializeSessionData(data: unknown): SubagentSessionData | null {
+  const d = validateSessionShape(data);
+  if (!d) return null;
+  if (!validateMessages(d.messages as unknown[])) return null;
+
+  const result = d as unknown as SubagentSessionData;
+
+  // Stale "running" sessions from a crash should be marked as "error"
+  if (result.status === "running") {
+    result.status = "error";
+    result.errorMessage =
+      result.errorMessage || "Session was interrupted (main agent session ended unexpectedly)";
+  }
+
+  return result;
+}
+
+// Re-export from format-transcript to maintain backward compatibility
+export { formatRunsForResume, getTextContent } from "./format-transcript";
+
+/** Details passed to the UI for rendering sub-agent windows */
+export interface WindowedSubagentDetails {
+  windows: SubAgentWindow[];
+  maxLinesPerWindow: number;
+  globalStatus: "running" | "done";
+  sessionIds: string[];
+}

package/src/utils.ts

@@ -0,0 +1,168 @@
+/**
+ * pi-subagents Extension Utilities
+ *
+ * Helper functions for subagent processing, output formatting, and concurrency management.
+ */
+
+import { MAX_MESSAGES_PER_SESSION } from "./types";
+import type { SubAgentWindow } from "./types";
+import type { Message } from "@earendil-works/pi-ai";
+
+// ── ANSI Stripping ───────────────────────────────────────────────────
+
+/** Regex to match ANSI escape codes */
+// eslint-disable-next-line no-control-regex
+const ANSI_REGEX = /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g;
+
+/**
+ * Remove ANSI escape codes from text.
+ */
+export function stripAnsi(text: string): string {
+  return text.replace(ANSI_REGEX, "");
+}
+
+// ── Rolling Buffer ─────────────────────────────────────────────────────
+
+/**
+ * Append a line to a sub-agent window, maintaining a rolling buffer.
+ * The window keeps only the latest N lines but stores all messages separately.
+ */
+export function appendLineToWindow(
+  win: SubAgentWindow,
+  line: string,
+  maxLines: number,
+  kind: "text" | "tool" = "text",
+): void {
+  const clean = stripAnsi(line).trimEnd();
+  if (!clean) {
+    return;
+  }
+  const entry = { text: clean, kind };
+  win.lines.push(entry);
+  while (win.lines.length > maxLines) {
+    win.lines.shift();
+  }
+  win.allMessages.push(entry);
+  while (win.allMessages.length > MAX_MESSAGES_PER_SESSION) {
+    win.allMessages.shift();
+  }
+}
+
+// ── Session Helpers ──────────────────────────────────────────────────
+
+/**
+ * Extract text parts from a message's content, regardless of role.
+ * Handles string content, array-of-parts content, and gracefully returns
+ * an empty array for anything else.
+ */
+export function extractTextParts(msg: { content?: unknown }): string[] {
+  if (!msg.content) return [];
+  if (typeof msg.content === "string") return [msg.content];
+  if (Array.isArray(msg.content)) {
+    return msg.content
+      .filter(
+        (part): part is { type: "text"; text: string } =>
+          part != null &&
+          typeof part === "object" &&
+          (part as { type?: string }).type === "text" &&
+          typeof (part as { text?: unknown }).text === "string",
+      )
+      .map((part) => part.text);
+  }
+  return [];
+}
+
+/**
+ * Extract all text content parts from an assistant message.
+ * Returns an array of text strings from the message content.
+ */
+export function getTextParts(msg: Message): string[] {
+  if (msg.role !== "assistant") return [];
+  return extractTextParts(msg);
+}
+
+/**
+ * Extract the last assistant text from a message array.
+ * Scans backwards through messages to find the most recent assistant response.
+ */
+export function getLastAssistantText(messages: Message[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (!msg) continue;
+    const parts = getTextParts(msg);
+    if (parts.length > 0 && parts[0] !== undefined) {
+      return parts[0];
+    }
+  }
+  return "";
+}
+
+// ── Summary Formatting ───────────────────────────────────────────────
+
+/**
+ * Count windows by status.
+ * Returns an object with counts for running, completed, and error states.
+ */
+export function countWindowStatuses(windows: SubAgentWindow[]): {
+  running: number;
+  completed: number;
+  error: number;
+} {
+  return {
+    running: windows.filter((w) => w.status === "running").length,
+    completed: windows.filter((w) => w.status === "completed").length,
+    error: windows.filter((w) => w.status === "error").length,
+  };
+}
+
+/**
+ * Generate a one-line status summary for multiple sub-agent windows.
+ */
+export function getSummaryText(windows: SubAgentWindow[]): string {
+  const { running, completed: done, error: errors } = countWindowStatuses(windows);
+  const parts: string[] = [];
+  if (running > 0) {
+    parts.push(`${running} running`);
+  }
+  if (done > 0) {
+    parts.push(`${done} done`);
+  }
+  if (errors > 0) {
+    parts.push(`${errors} error${errors > 1 ? "s" : ""}`);
+  }
+  return parts.join(", ") || "processing...";
+}
+
+// ── Concurrency Helper ───────────────────────────────────────────────
+
+/**
+ * Map an array with a concurrency limit.
+ * Processes items in parallel but never more than `concurrency` at a time.
+ */
+export async function mapWithConcurrencyLimit<TIn, TOut>(
+  items: TIn[],
+  concurrency: number,
+  fn: (item: TIn, index: number) => Promise<TOut>,
+): Promise<TOut[]> {
+  if (items.length === 0) {
+    return [];
+  }
+  const limit = Math.max(1, Math.min(concurrency, items.length));
+  const results: TOut[] = new Array<TOut>(items.length);
+  let nextIndex = 0;
+  const workers = new Array(limit).fill(null).map(async () => {
+    for (;;) {
+      const current = nextIndex++;
+      if (current >= items.length) {
+        return;
+      }
+      const item = items[current];
+      if (item === undefined) continue;
+      results[current] = await fn(item, current);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+// ── Sub-Agent Spawner ────────────────────────────────────────────────