@harms-haus/pi-subagents 0.1.0

package/src/format-transcript.ts

@@ -0,0 +1,151 @@
+import type { SubagentSessionData, ToolCallPart } from "./types";
+import type { Message } from "@earendil-works/pi-ai";
+import { extractTextParts } from "./utils";
+
+const TOOL_CALL_PREVIEW_LENGTH = 120;
+const TOOL_RESULT_TRUNCATION_LENGTH = 500;
+
+/**
+ * Options controlling how transcript runs are formatted.
+ */
+export interface TranscriptOptions {
+  /** Whether to include user messages in the transcript */
+  includeUserMessages: boolean;
+  /** Prefix for user messages */
+  userPrefix: string;
+  /** Prefix for assistant text messages */
+  assistantPrefix: string;
+  /** Prefix format for tool calls. Use `{name}` and `{args}` placeholders */
+  toolCallPrefix: string;
+  /** Prefix for tool result messages */
+  toolResultPrefix: string;
+  /** Maximum characters for tool result text before truncation */
+  toolResultTruncation: number;
+  /** Maximum characters for tool call arguments preview */
+  toolCallPreviewLength: number;
+  /** Separator used between formatted parts/lines */
+  partSeparator: string;
+  /**
+   * Function to format the run header when there are multiple runs.
+   * Receives (runIndex, totalRuns, run). Return undefined to skip header.
+   */
+  runHeader: (runIndex: number, totalRuns: number, run: SubagentSessionData) => string | undefined;
+}
+
+/** Format tool calls from an assistant message's content. */
+function formatToolCalls(
+  content: Message["content"],
+  prefix: string,
+  previewLength: number,
+): string[] {
+  if (typeof content === "string" || !Array.isArray(content)) return [];
+  const results: string[] = [];
+  for (const part of content) {
+    if (part.type === "toolCall") {
+      const toolCall = part as ToolCallPart;
+      const args = JSON.stringify(toolCall.arguments || {}).slice(0, previewLength);
+      results.push(prefix.replace("{name}", toolCall.name).replace("{args}", args));
+    }
+  }
+  return results;
+}
+
+/** Format a single message into transcript lines. */
+function formatMessage(msg: Message, options: TranscriptOptions): string[] {
+  const parts: string[] = [];
+
+  if (msg.role === "user" && options.includeUserMessages) {
+    const text = getTextContent(msg);
+    if (text) parts.push(`${options.userPrefix}${text}`);
+  } else if (msg.role === "assistant") {
+    const text = getTextContent(msg);
+    if (text) parts.push(`${options.assistantPrefix}${text}`);
+    parts.push(
+      ...formatToolCalls(msg.content, options.toolCallPrefix, options.toolCallPreviewLength),
+    );
+  } else if (msg.role === "toolResult") {
+    const text = getTextContent(msg);
+    if (text) {
+      const truncated =
+        text.length > options.toolResultTruncation
+          ? `${text.slice(0, options.toolResultTruncation)}...`
+          : text;
+      parts.push(`${options.toolResultPrefix}${truncated}`);
+    }
+  }
+
+  return parts;
+}
+
+/**
+ * Format a complete transcript from an array of runs.
+ * Iterates over runs, extracts text/tool calls/tool results from messages,
+ * applies role prefixes, truncates tool call args and tool results, and
+ * adds run separators.
+ */
+export function formatTranscript(runs: SubagentSessionData[], options: TranscriptOptions): string {
+  const parts: string[] = [];
+
+  for (let i = 0; i < runs.length; i++) {
+    const run = runs[i];
+    if (!run) continue;
+    const header = options.runHeader(i, runs.length, run);
+    if (header) parts.push(header);
+
+    for (const msg of run.messages) {
+      parts.push(...formatMessage(msg, options));
+    }
+
+    if (run.errorMessage) {
+      parts.push(`[Error: ${run.errorMessage}]`);
+    }
+  }
+
+  return parts.join(options.partSeparator);
+}
+
+/**
+ * Options for formatting runs when resuming a sub-agent session.
+ */
+export const RESUME_OPTIONS: TranscriptOptions = {
+  includeUserMessages: true,
+  userPrefix: "User: ",
+  assistantPrefix: "Assistant: ",
+  toolCallPrefix: "Tool Call: {name}({args})",
+  toolResultPrefix: "Tool Result: ",
+  toolResultTruncation: TOOL_RESULT_TRUNCATION_LENGTH,
+  toolCallPreviewLength: TOOL_CALL_PREVIEW_LENGTH,
+  partSeparator: "\n\n",
+  runHeader: (i, total, run) =>
+    total > 1 ? `--- Run ${i + 1} (${run.status}, ${run.messages.length} messages) ---` : undefined,
+};
+
+/**
+ * Options for formatting runs when retrieving a session transcript via tool.
+ */
+export const RETRIEVAL_OPTIONS: TranscriptOptions = {
+  includeUserMessages: false,
+  userPrefix: "",
+  assistantPrefix: "",
+  toolCallPrefix: "→ {name}: {args}",
+  toolResultPrefix: "[tool result]: ",
+  toolResultTruncation: TOOL_RESULT_TRUNCATION_LENGTH,
+  toolCallPreviewLength: TOOL_CALL_PREVIEW_LENGTH,
+  partSeparator: "\n---\n",
+  runHeader: (i, total, run) =>
+    total > 1 ? `=== Run ${i + 1}/${total} (${run.status}) ===` : undefined,
+};
+
+/**
+ * Format previous runs' session data for inclusion in a resume prompt.
+ * Produces a human-readable transcript of all previous runs.
+ */
+export function formatRunsForResume(runs: SubagentSessionData[]): string {
+  return formatTranscript(runs, RESUME_OPTIONS);
+}
+
+/** Extract text content from a Message */
+export function getTextContent(msg: { content?: unknown }): string | undefined {
+  const parts = extractTextParts(msg);
+  return parts.length > 0 ? parts.join("\n") : undefined;
+}

package/src/index.ts

@@ -0,0 +1,117 @@
+/**
+ * pi-subagents Extension
+ *
+ * Allows the main agent to spawn parallel sub-agents, with each sub-agent's
+ * latest output rendered in a rolling TUI window inline with the main agent's
+ * conversation history.
+ *
+ * Supports named profiles defined as markdown files in the
+ * agent-profiles/ directory, each pre-configuring provider/model, system
+ * prompts, thinking levels, and other model settings per profile.
+ *
+ * Tools provided:
+ *   delegate_to_subagents — spawn parallel sub-agents
+ *   get_subagent_output   — retrieve last assistant text from a sub-agent session
+ *   get_subagent_session  — retrieve full session transcript from a sub-agent
+ *   list_subagent_profiles — list available named profiles
+ *
+ * Usage (from the LLM):
+ *   delegate_to_subagents({ tasks: [{ name: "test", prompt: "...", profile: "code-reviewer" }] })
+ *   get_subagent_output({ sessionId: "abc12345def45678" })
+ *   get_subagent_session({ sessionId: "abc12345def45678" })
+ *   list_subagent_profiles({})
+ */
+
+import { registerProfileCommand } from "./commands/profile";
+import { registerDelegateTool } from "./tools/delegate";
+import { registerRetrievalTools } from "./tools/retrieval";
+import { CUSTOM_ENTRY_TYPE, deserializeSessionData } from "./types";
+import type { SessionRecord, SubagentSessionData } from "./types";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  // ── In-memory session store ──────────────────────────────────────
+  const sessionStore = new Map<string, SessionRecord>();
+  const MAX_STORED_SESSIONS = 32;
+  const MAX_RUNS_PER_SESSION = 10;
+
+  function registerSession(session: SubagentSessionData): void {
+    const existing = sessionStore.get(session.sessionId);
+    if (existing) {
+      // Resume: append to existing record
+      existing.runs.push(session);
+      // Cap runs per session to prevent unbounded memory growth
+      while (existing.runs.length > MAX_RUNS_PER_SESSION) {
+        existing.runs.shift();
+      }
+    } else {
+      // New session: create a new record
+      if (sessionStore.size >= MAX_STORED_SESSIONS) {
+        let oldestKey: string | null = null;
+        let oldestTime = Infinity;
+        for (const [key, val] of sessionStore) {
+          // Skip sessions with running tasks — don't evict active sessions
+          if (val.runs.some((r) => r.status === "running")) continue;
+          const firstRun = val.runs[0];
+          if (firstRun && firstRun.startedAt < oldestTime) {
+            oldestTime = firstRun.startedAt;
+            oldestKey = key;
+          }
+        }
+        if (oldestKey) {
+          sessionStore.delete(oldestKey);
+        }
+      }
+      sessionStore.set(session.sessionId, { runs: [session] });
+    }
+  }
+
+  function getActiveSessionIds(): Set<string> {
+    const active = new Set<string>();
+    for (const [, record] of sessionStore) {
+      if (record.runs.some((r) => r.status === "running")) {
+        const firstRun = record.runs[0];
+        if (firstRun) {
+          active.add(firstRun.sessionId);
+        }
+      }
+    }
+    return active;
+  }
+
+  // Reconstruct session store from persisted custom entries on session load
+  pi.on("session_start", (event, ctx) => {
+    // New sessions have no prior data to reconstruct
+    if (event.reason === "new") {
+      return;
+    }
+
+    try {
+      const entries = ctx.sessionManager.getEntries();
+      for (const entry of entries) {
+        if (
+          entry.type === "custom" &&
+          "customType" in entry &&
+          entry.customType === CUSTOM_ENTRY_TYPE
+        ) {
+          const sessionData = deserializeSessionData(entry.data);
+          if (sessionData) {
+            registerSession(sessionData);
+          }
+        }
+      }
+    } catch (err) {
+      console.warn("[pi-subagents] Failed to reconstruct session data:", err);
+    }
+  });
+
+  pi.on("session_shutdown", () => {
+    sessionStore.clear();
+  });
+
+  // ── Register tools and commands ──────────────────────────────────
+
+  registerDelegateTool(pi, sessionStore, registerSession, getActiveSessionIds);
+  registerRetrievalTools(pi, sessionStore);
+  registerProfileCommand(pi);
+}

package/src/profile-editor.ts

@@ -0,0 +1,356 @@
+/**
+ * Interactive Profile Editor
+ *
+ * Interactive wizard for creating and editing subagent profiles.
+ * Uses the extension API's UI methods to prompt for profile settings.
+ */
+
+import {
+  formatProfileDetail,
+  saveProfile,
+  type ProfileScope,
+  type SubagentProfile,
+  type ThinkingLevel,
+} from "./profiles";
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+
+/** Subset of ExtensionContext used by the profile editor. */
+type ProfileEditorUIContext = ExtensionUIContext;
+
+type ProfileEditorContext = {
+  ui: ProfileEditorUIContext;
+  cwd: string;
+};
+
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
+
+/** Sentinel returned by step helpers when the user cancels. */
+const CANCELLED = Symbol("CANCELLED");
+type StepResult = typeof CANCELLED | true;
+
+// ── Individual Editor Steps ──────────────────────────────────────────
+
+async function promptScope(
+  ui: ProfileEditorUIContext,
+  name: string,
+): Promise<ProfileScope | typeof CANCELLED> {
+  const scope = await ui.select("Save to which scope?", [
+    `Global (~/.pi/agent-profiles/${name}.md)`,
+    `Project (.pi/agent-profiles/${name}.md)`,
+  ]);
+  if (!scope) return CANCELLED;
+  return scope.startsWith("Global") ? "global" : "project";
+}
+
+async function promptProvider(
+  ui: ProfileEditorUIContext,
+  profile: SubagentProfile,
+): Promise<StepResult> {
+  const value = await ui.input(
+    "Provider (e.g. anthropic, openai, dashscope):",
+    profile.provider ?? "",
+  );
+  if (value === undefined) return CANCELLED;
+  if (value) {
+    profile.provider = value;
+  } else {
+    delete profile.provider;
+  }
+  return true;
+}
+
+async function promptModel(
+  ui: ProfileEditorUIContext,
+  profile: SubagentProfile,
+): Promise<StepResult> {
+  const value = await ui.input(
+    "Model (supports provider/id and :thinking shorthand):",
+    profile.model ?? "",
+  );
+  if (value === undefined) return CANCELLED;
+  if (value) {
+    profile.model = value;
+  } else {
+    delete profile.model;
+  }
+  return true;
+}
+
+async function promptSystemPrompt(
+  ui: ProfileEditorUIContext,
+  profile: SubagentProfile,
+): Promise<StepResult> {
+  const hasSystem = await ui.confirm(
+    "System prompt?",
+    profile.systemPrompt
+      ? "A custom system prompt is set. Keep it?"
+      : "Set a custom system prompt?",
+  );
+  if (hasSystem) {
+    const sp = await ui.editor(
+      "System prompt:",
+      profile.systemPrompt ?? "You are a helpful coding assistant.",
+    );
+    if (sp === undefined) return CANCELLED;
+    profile.systemPrompt = sp;
+  } else {
+    delete profile.systemPrompt;
+  }
+  return true;
+}
+
+async function promptAppendSystemPrompt(
+  ui: ProfileEditorUIContext,
+  profile: SubagentProfile,
+): Promise<StepResult> {
+  const hasAppend = await ui.confirm(
+    "Append to system prompt?",
+    profile.appendSystemPrompt
+      ? "An appended system prompt is set. Keep it?"
+      : "Append text to the default system prompt?",
+  );
+  if (hasAppend) {
+    const ap = await ui.input("Append text:", profile.appendSystemPrompt ?? "");
+    if (ap === undefined) return CANCELLED;
+    if (ap) {
+      profile.appendSystemPrompt = ap;
+    }
+  } else {
+    delete profile.appendSystemPrompt;
+  }
+  return true;
+}
+
+async function promptThinkingLevel(
+  ui: ProfileEditorUIContext,
+  profile: SubagentProfile,
+): Promise<StepResult> {
+  const hasThinking = await ui.confirm(
+    "Thinking level?",
+    profile.thinkingLevel
+      ? `Thinking level is ${profile.thinkingLevel}. Set one?`
+      : "Set a thinking level?",
+  );
+  if (hasThinking) {
+    const tl = await ui.select("Thinking level:", THINKING_LEVELS);
+    if (tl) {
+      profile.thinkingLevel = tl as ThinkingLevel;
+    }
+  } else {
+    delete profile.thinkingLevel;
+  }
+  return true;
+}
+
+async function promptToolListInput(
+  ui: ProfileEditorUIContext,
+  label: string,
+  current: string | undefined,
+): Promise<string[] | undefined> {
+  const str = await ui.input(label, current ?? "");
+  if (str === undefined) return undefined;
+  if (str.trim()) {
+    return str
+      .split(",")
+      .map((t: string) => t.trim())
+      .filter(Boolean);
+  }
+  return [];
+}
+
+async function promptToolsConfig(
+  ui: ProfileEditorUIContext,
+  profile: SubagentProfile,
+): Promise<StepResult> {
+  const hasTools = await ui.confirm(
+    "Configure tools?",
+    profile.tools || profile.excludeTools || profile.noTools
+      ? "Tool config is set. Change it?"
+      : "Restrict which tools the subagent can use?",
+  );
+  if (!hasTools) return true;
+
+  const noTools = await ui.confirm("Disable all tools?", "");
+  if (noTools) {
+    profile.noTools = true;
+    delete profile.tools;
+    delete profile.excludeTools;
+    return true;
+  }
+
+  delete profile.noTools;
+  const toolMode = await ui.select("Select tool mode:", [
+    "Allowlist (only these tools)",
+    "Blacklist (all tools except these)",
+  ]);
+  if (!toolMode) return CANCELLED;
+
+  if (toolMode.startsWith("Blacklist")) {
+    delete profile.tools;
+    const list = await promptToolListInput(
+      ui,
+      "Tool blacklist (comma-separated, e.g. read,bash,grep):",
+      profile.excludeTools?.join(","),
+    );
+    if (list === undefined) return CANCELLED;
+    if (list.length > 0) {
+      profile.excludeTools = list;
+    } else {
+      delete profile.excludeTools;
+    }
+  } else {
+    delete profile.excludeTools;
+    const list = await promptToolListInput(
+      ui,
+      "Tool allowlist (comma-separated, e.g. read,bash,grep):",
+      profile.tools?.join(","),
+    );
+    if (list === undefined) return CANCELLED;
+    if (list.length > 0) {
+      profile.tools = list;
+    } else {
+      delete profile.tools;
+    }
+  }
+  return true;
+}
+
+async function promptExtensionsConfig(
+  ui: ProfileEditorUIContext,
+  profile: SubagentProfile,
+): Promise<StepResult> {
+  const hasExts = await ui.confirm(
+    "Configure extensions?",
+    profile.noExtensions || profile.extensions
+      ? "Extension config is set. Change it?"
+      : "Configure extension loading?",
+  );
+  if (!hasExts) return true;
+
+  const noExt = await ui.confirm("Disable all extensions?", "");
+  if (noExt) {
+    profile.noExtensions = true;
+    delete profile.extensions;
+    return true;
+  }
+
+  delete profile.noExtensions;
+  const extStr = await ui.input(
+    "Extension paths (comma-separated):",
+    profile.extensions?.join(",") ?? "",
+  );
+  if (extStr === undefined) return CANCELLED;
+  if (extStr.trim()) {
+    profile.extensions = extStr
+      .split(",")
+      .map((e: string) => e.trim())
+      .filter(Boolean);
+  } else {
+    delete profile.extensions;
+  }
+  return true;
+}
+
+async function promptSkillsConfig(
+  ui: ProfileEditorUIContext,
+  profile: SubagentProfile,
+): Promise<StepResult> {
+  if (profile.suggestedSkills || profile.loadSkills) {
+    const remove = await ui.confirm(
+      "Remove skills?",
+      "Skill config is set. Remove existing skill configuration?",
+    );
+    if (remove) {
+      delete profile.suggestedSkills;
+      delete profile.loadSkills;
+    }
+    return true;
+  }
+
+  const add = await ui.confirm("Configure skills?", "Configure skill loading for the subagent?");
+  if (!add) return true;
+
+  const suggestedStr = await ui.input(
+    "Suggested skills (comma-separated skill names, model chooses to load):",
+    "",
+  );
+  if (suggestedStr === undefined) return CANCELLED;
+  if (suggestedStr.trim()) {
+    profile.suggestedSkills = suggestedStr
+      .split(",")
+      .map((s: string) => s.trim())
+      .filter(Boolean);
+  }
+
+  const loadStr = await ui.input(
+    "Pre-loaded skills (comma-separated skill names, content injected into system prompt):",
+    "",
+  );
+  if (loadStr === undefined) return CANCELLED;
+  if (loadStr.trim()) {
+    profile.loadSkills = loadStr
+      .split(",")
+      .map((s: string) => s.trim())
+      .filter(Boolean);
+  }
+  return true;
+}
+
+// ── Main Wizard ──────────────────────────────────────────────────────
+
+/**
+ * Interactive profile editor wizard.
+ *
+ * Prompts the user through a series of UI dialogs to configure or edit a profile.
+ * Returns undefined if the user cancels at any point.
+ */
+export async function editProfileInteractive(
+  name: string,
+  initial: SubagentProfile,
+  ctx: ProfileEditorContext,
+): Promise<void> {
+  const profile = { ...initial };
+
+  const scopeValue = await promptScope(ctx.ui, name);
+  if (scopeValue === CANCELLED) return;
+
+  let result: StepResult;
+
+  result = await promptProvider(ctx.ui, profile);
+  if (result === CANCELLED) return;
+
+  result = await promptModel(ctx.ui, profile);
+  if (result === CANCELLED) return;
+
+  result = await promptSystemPrompt(ctx.ui, profile);
+  if (result === CANCELLED) return;
+
+  result = await promptAppendSystemPrompt(ctx.ui, profile);
+  if (result === CANCELLED) return;
+
+  result = await promptThinkingLevel(ctx.ui, profile);
+  if (result === CANCELLED) return;
+
+  result = await promptToolsConfig(ctx.ui, profile);
+  if (result === CANCELLED) return;
+
+  result = await promptExtensionsConfig(ctx.ui, profile);
+  if (result === CANCELLED) return;
+
+  result = await promptSkillsConfig(ctx.ui, profile);
+  if (result === CANCELLED) return;
+
+  // Review and save
+  const summary = formatProfileDetail(name, profile);
+  const confirmed = await ctx.ui.confirm(
+    `Save profile "${name}"?`,
+    `${summary}\n\nSave this profile?`,
+  );
+  if (!confirmed) {
+    ctx.ui.notify("Cancelled.", "info");
+    return;
+  }
+
+  await saveProfile(name, profile, scopeValue, ctx.cwd);
+  ctx.ui.notify(`Profile "${name}" saved to ${scopeValue} agent-profiles.`, "info");
+}