@clanker-code/pi-subagents 0.10.7 → 0.11.0

package/src/dashboard-ui.ts

@@ -0,0 +1,270 @@
+/**
+ * dashboard-ui.ts — Register dashboard UI modules for subagent visibility.
+ *
+ * Provides three integration points with pi-agent-dashboard:
+ * 1. Footer-segment decorator showing running/completed agent counts
+ * 2. Management-modal module with a table view of all subagent history
+ * 3. Round-trip event handlers for data fetch, abort, and steer actions
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentManager } from "./agent-manager.js";
+import { formatMs, getDisplayName } from "./ui/agent-widget.js";
+import { getLifetimeTotal } from "./usage.js";
+
+// Dashboard shared types (inlined to avoid adding a dependency)
+interface DecoratorDescriptor {
+  kind: "footer-segment" | "agent-metric" | "breadcrumb" | "gate" | "toast";
+  namespace: string;
+  id: string;
+  payload: Record<string, unknown>;
+}
+
+interface ExtensionUiModule {
+  kind: "management-modal";
+  id: string;
+  command: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  category?: string;
+  view: {
+    kind: "table" | "grid" | "form";
+    dataEvent?: string;
+    rowKey?: string;
+    fields?: Array<{
+      key: string;
+      label: string;
+      kind: string;
+      width?: string | number;
+    }>;
+    rowActions?: Array<{
+      id: string;
+      label: string;
+      icon?: string;
+      variant?: "primary" | "secondary" | "danger";
+      event: string;
+      confirm?: string;
+    }>;
+    emptyState?: string;
+    actions?: Array<{
+      id: string;
+      label: string;
+      icon?: string;
+      variant?: "primary" | "secondary" | "danger";
+      event: string;
+    }>;
+  };
+}
+
+type ModuleProbe = { modules: Array<ExtensionUiModule | DecoratorDescriptor> };
+
+const NAMESPACE = "subagents";
+const MODULE_ID = "subagents-overview";
+const DATA_EVENT = "subagents:rows";
+const INVALIDATE_DEBOUNCE_MS = 500;
+
+/**
+ * Build a row for the management-modal table from an AgentRecord.
+ */
+function buildAgentRow(record: any) {
+  const durationMs = record.completedAt
+    ? record.completedAt - record.startedAt
+    : Date.now() - record.startedAt;
+  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
+
+  return {
+    id: record.id,
+    type: getDisplayName(record.type),
+    description: record.description ?? "",
+    status: record.status,
+    toolUses: record.toolUses ?? 0,
+    tokens: totalTokens > 0 ? formatTokenCount(totalTokens) : "—",
+    duration: formatMs(durationMs),
+    outputFile: record.outputFile ?? "",
+    startedAt: record.startedAt,
+  };
+}
+
+function formatTokenCount(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+  return String(n);
+}
+
+/**
+ * Register all dashboard UI integration points.
+ * Call once during extension setup when pi.events is available.
+ */
+export function registerDashboardModules(pi: ExtensionAPI, manager: AgentManager): void {
+  if (!pi.events) return;
+
+  let invalidateTimer: ReturnType<typeof setTimeout> | undefined;
+
+  function scheduleInvalidate() {
+    if (invalidateTimer) return;
+    invalidateTimer = setTimeout(() => {
+      invalidateTimer = undefined;
+      pi.events.emit("ui:invalidate", {});
+    }, INVALIDATE_DEBOUNCE_MS);
+  }
+
+  // ── 1. Module Discovery (ui:list-modules) ──────────────────────────
+  pi.events.on("ui:list-modules", ((probe: ModuleProbe) => {
+    const agents = manager.listAgents();
+    const running = agents.filter(a => a.status === "running").length;
+    const completed = agents.filter(a => a.status === "completed").length;
+    const total = agents.length;
+
+    // Footer-segment: running/completed counts
+    const parts: string[] = [];
+    if (running > 0) parts.push(`● ${running} running`);
+    if (completed > 0) parts.push(`✓ ${completed} done`);
+    if (total === 0) parts.push("No agents");
+
+    probe.modules.push({
+      kind: "footer-segment",
+      namespace: NAMESPACE,
+      id: "agent-counts",
+      payload: {
+        text: parts.join(" · "),
+        tooltip: `${total} total agents (${running} running, ${completed} completed)`,
+        icon: "mdiRobot",
+      },
+    } as DecoratorDescriptor);
+
+    // Management-modal: subagent overview table
+    probe.modules.push({
+      kind: "management-modal",
+      id: MODULE_ID,
+      command: "/subagents",
+      title: "Subagents",
+      description: "View and manage background subagents",
+      icon: "mdiRobotOutline",
+      category: "subagents",
+      view: {
+        kind: "table",
+        dataEvent: DATA_EVENT,
+        rowKey: "id",
+        fields: [
+          { key: "id", label: "ID", kind: "text", width: 120 },
+          { key: "type", label: "Type", kind: "text", width: 100 },
+          { key: "description", label: "Description", kind: "text" },
+          { key: "status", label: "Status", kind: "text", width: 90 },
+          { key: "toolUses", label: "Tools", kind: "number", width: 60 },
+          { key: "tokens", label: "Tokens", kind: "text", width: 80 },
+          { key: "duration", label: "Duration", kind: "text", width: 80 },
+        ],
+        rowActions: [
+          {
+            id: "view-result",
+            label: "View Result",
+            icon: "mdiEye",
+            variant: "primary",
+            event: "subagents:ui:view-result",
+          },
+          {
+            id: "abort",
+            label: "Abort",
+            icon: "mdiStop",
+            variant: "danger",
+            event: "subagents:ui:abort",
+            confirm: "Abort this running agent?",
+          },
+          {
+            id: "steer",
+            label: "Steer",
+            icon: "mdiMessageArrowRight",
+            variant: "secondary",
+            event: "subagents:ui:steer",
+          },
+        ],
+        emptyState: "No subagents have been spawned in this session.",
+        actions: [
+          {
+            id: "refresh",
+            label: "Refresh",
+            icon: "mdiRefresh",
+            variant: "secondary",
+            event: "subagents:ui:refresh",
+          },
+        ],
+      },
+    } as ExtensionUiModule);
+  }) as any);
+
+  // ── 2. Data Fetch Handler ──────────────────────────────────────────
+  pi.events.on(DATA_EVENT, ((data: any) => {
+    const agents = manager.listAgents();
+    data.items = agents.map(buildAgentRow);
+  }) as any);
+
+  // ── 3. Action Handlers ─────────────────────────────────────────────
+
+  // Refresh: just invalidate to re-probe + re-fetch
+  pi.events.on("subagents:ui:refresh", (() => {
+    scheduleInvalidate();
+  }) as any);
+
+  // View Result: emit the result as a toast so the dashboard shows it
+  pi.events.on("subagents:ui:view-result", ((data: any) => {
+    const agentId = data.params?.id ?? data.id;
+    const record = manager.getRecord(agentId);
+    if (!record) {
+      pi.events.emit("ui:invalidate", { id: MODULE_ID });
+      return;
+    }
+
+    const resultText = record.result?.trim() || "No output yet.";
+    const preview = resultText.length > 2000
+      ? resultText.slice(0, 2000) + "\n…(truncated)"
+      : resultText;
+
+    pi.events.emit("ui:invalidate", { id: MODULE_ID });
+
+    // Return result as items so it shows in a detail view
+    data.items = [{
+      id: record.id,
+      type: getDisplayName(record.type),
+      description: record.description,
+      status: record.status,
+      result: preview,
+      outputFile: record.outputFile ?? "",
+    }];
+  }) as any);
+
+  // Abort: signal the agent to stop
+  pi.events.on("subagents:ui:abort", ((data: any) => {
+    const agentId = data.params?.id ?? data.id;
+    const record = manager.getRecord(agentId);
+    if (record?.session) {
+      // Use the session's abort mechanism
+      try {
+        record.session.dispose?.();
+      } catch {
+        // Ignore disposal errors
+      }
+    }
+    scheduleInvalidate();
+  }) as any);
+
+  // Steer: for now just invalidate — full steer requires a prompt input
+  // which the management-modal form view could support in the future
+  pi.events.on("subagents:ui:steer", ((_data: any) => {
+    // TODO: Could open a form view for entering the steer message
+    scheduleInvalidate();
+  }) as any);
+
+  // ── 4. Invalidate on agent lifecycle events ────────────────────────
+  const lifecycleEvents = [
+    "subagents:created",
+    "subagents:started",
+    "subagents:completed",
+    "subagents:failed",
+    "subagents:compacted",
+  ];
+
+  for (const event of lifecycleEvents) {
+    pi.events.on(event, (() => scheduleInvalidate()) as any);
+  }
+}

package/src/default-agents.ts

@@ -34,7 +34,6 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
       builtinToolNames: READ_ONLY_TOOLS,
       extensions: true,
       skills: true,
-      model: "anthropic/claude-haiku-4-5-20251001",
       systemPrompt: `# 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.

package/src/index.ts

@@ -24,8 +24,10 @@ import { getAgentConversation, getCurrentExtensionAgentId, getCurrentExtensionDe
 import { buildAgentToolDescription, getModelLabelFromConfig } from "./agent-tool-description.js";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, isDefaultsDisabled, registerAgents, resolveType, setDefaultsDisabled } from "./agent-types.js";
 import { formatOutputFileHint, limitText, MAX_RESULT_CHARS, MAX_VERBOSE_CHARS } from "./bounded-output.js";
+import { extractText } from "./context.js";
 import { registerRpcHandlers } from "./cross-extension-rpc.js";
 import { loadCustomAgents } from "./custom-agents.js";
+import { registerDashboardModules } from "./dashboard-ui.js";
 import { isModelInScope, readEnabledModels, resolveEnabledModels } from "./enabled-models.js";
 import { GroupJoinManager } from "./group-join.js";
 import { resolveAgentInvocationConfig, resolveJoinMode } from "./invocation-config.js";
@@ -37,11 +39,11 @@ import { SubagentScheduler } from "./schedule.js";
 import { resolveStorePath, ScheduleStore } from "./schedule-store.js";
 import { applyAndEmitLoaded, DEFAULT_WAIT_TIMEOUT_SECONDS, type SubagentsSettings, saveAndEmitChanged, type ToolDescriptionMode } from "./settings.js";
 import { getStatusNote } from "./status-note.js";
+import { registerSubagentListClearTools } from "./subagent-list-clear.js";
 import { type AgentConfig, type AgentInvocation, type AgentRecord, type JoinMode, MAX_RECURSIVE_DEPTH, type NotificationDetails, type SubagentType } from "./types.js";
-import { renderAgentCall, renderAgentResult, renderSteerCall, tailPreview } from "./ui/agent-tool-rendering.js";
+import { renderAgentCall, renderAgentResult, renderSteerCall, snipMiddleLines, tailPreview } from "./ui/agent-tool-rendering.js";
 import {
   type AgentActivity,
-  type AgentDetails,
   AgentWidget,
   buildInvocationTags,
   describeActivity,
@@ -55,15 +57,26 @@ import type { WidgetAgentSnapshot, WidgetDisplayMode } from "./ui/agent-widget-t
 import { menuSelect } from "./ui/menu-select.js";
 import { showSchedulesMenu } from "./ui/schedule-menu.js";
 import { addUsage, getLifetimeTotal, getSessionContextPercent } from "./usage.js";
-import { formatWaitTimeout, raceWait, type WaitOutcome, waitTimeoutMessage } from "./wait.js";
+import { formatWaitTimeout, pollPendingMessages, raceWait, type WaitOutcome, waitTimeoutMessage } from "./wait.js";
 
 // ---- Shared helpers ----
 
 /** Tool execute return value for a text response. */
-function textResult(msg: string, details?: AgentDetails) {
+function textResult(msg: string, details?: unknown) {
   return { content: [{ type: "text" as const, text: msg }], details: details as any };
 }
 
+/** Metadata attached to get_subagent_result for compact UI rendering. */
+interface GetResultDetails {
+  status: AgentRecord["status"];
+  description: string;
+  toolUses: number;
+  tokens: string | null;
+  contextPercent: number | null;
+  duration: string;
+  outputFile?: string;
+}
+
 /**
  * Create an AgentActivity state and spawn callbacks for tracking tool usage.
  * Used by the background spawn path to track tool usage.
@@ -443,6 +456,8 @@ export default function (pi: ExtensionAPI) {
   // Capture ctx from session_start for RPC spawn handler + start the scheduler.
   pi.on("session_start", async (_event, ctx) => {
     currentCtx = ctx;
+    clearBatchState();
+    groupJoin.dispose();
     manager.clearCompleted();
     widget.clearSnapshots();
     retryStash.clear();
@@ -450,8 +465,10 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("session_before_switch", () => {
+    clearBatchState();
+    groupJoin.dispose();
     manager.clearCompleted();
-    widget.clearSnapshots();
+    widget.dispose();
     retryStash.clear();
     scheduler.stop();
   });
@@ -472,13 +489,17 @@ export default function (pi: ExtensionAPI) {
     unsubSpawnRpc();
     unsubStopRpc();
     unsubPingRpc();
+    unsubWidgetCreated?.();
     unsubWidgetStarted?.();
     unsubWidgetCompleted?.();
     unsubWidgetFailed?.();
     currentCtx = undefined;
     delete (globalThis as any)[MANAGER_KEY];
     scheduler.stop();
+    clearBatchState();
+    groupJoin.dispose();
     manager.abortAll();
+    widget.dispose();
     for (const timer of pendingNudges.values()) clearTimeout(timer);
     pendingNudges.clear();
     retryStash.clear();
@@ -491,6 +512,7 @@ export default function (pi: ExtensionAPI) {
     const snapshot = widgetSnapshotFromEvent(payload);
     if (snapshot) widget.upsertSnapshot(snapshot);
   };
+  const unsubWidgetCreated = pi.events.on("subagents:created", upsertWidgetEventSnapshot);
   const unsubWidgetStarted = pi.events.on("subagents:started", upsertWidgetEventSnapshot);
   const unsubWidgetCompleted = pi.events.on("subagents:completed", upsertWidgetEventSnapshot);
   const unsubWidgetFailed = pi.events.on("subagents:failed", upsertWidgetEventSnapshot);
@@ -567,6 +589,14 @@ export default function (pi: ExtensionAPI) {
   let batchFinalizeTimer: ReturnType<typeof setTimeout> | undefined;
   let batchCounter = 0;
 
+  function clearBatchState() {
+    if (batchFinalizeTimer) {
+      clearTimeout(batchFinalizeTimer);
+      batchFinalizeTimer = undefined;
+    }
+    currentBatchAgents = [];
+  }
+
   /** Finalize the current batch: if 2+ smart-mode agents, register as a group. */
   function finalizeBatch() {
     batchFinalizeTimer = undefined;
@@ -679,7 +709,7 @@ export default function (pi: ExtensionAPI) {
       }),
       subagent_type: Type.Optional(
         Type.String({
-          description: `The type of specialized agent to use. Available types: ${getAvailableTypes().join(", ")}. Custom agents from .pi/agents/*.md (project) or ${getAgentDir()}/agents/*.md (global) are also available. OMIT when retrying (preserved by the handle) unless you want to override it.`,
+          description: `The type of specialized agent to use. Defaults to general-purpose when omitted. Available types: ${getAvailableTypes().join(", ")}. Custom agents from .pi/agents/*.md (project) or ${getAgentDir()}/agents/*.md (global) are also available. OMIT when retrying (preserved by the handle) unless you want to override it.`,
         }),
       ),
       model: Type.Optional(
@@ -782,18 +812,16 @@ export default function (pi: ExtensionAPI) {
         const { retry: _omit, ...overrides } = params;
         P = { ...stashed.params, ...overrides } as typeof params;
       }
-      emitPromptPreview(P.prompt, P.description, P.subagent_type);
+      const requestedSubagentType = (P.subagent_type ?? "general-purpose") as SubagentType;
+      emitPromptPreview(P.prompt, P.description, requestedSubagentType);
 
-      // Retry supplied the prompt/type from the stash; otherwise both are required.
-      if (!retryHandle && (!P.prompt || !P.subagent_type)) {
-        return textResult(
-          `Missing required argument${!P.prompt && !P.subagent_type ? "s" : ""}: ` +
-          [!P.prompt && "prompt", !P.subagent_type && "subagent_type"].filter(Boolean).join(", ") +
-          ".",
-        );
+      // Retry supplied the prompt from the stash; otherwise prompt is required.
+      // subagent_type defaults to general-purpose when omitted.
+      if (!retryHandle && !P.prompt) {
+        return textResult("Missing required argument: prompt.");
       }
 
-      const rawType = P.subagent_type as SubagentType;
+      const rawType = requestedSubagentType;
       const resolved = resolveType(rawType);
       if (!resolved) {
         // Unknown agent type — recoverable. List valid types so the orchestrator
@@ -1032,6 +1060,10 @@ export default function (pi: ExtensionAPI) {
         isBackground: true,
         depth: record?.depth ?? nextSubagentDepth,
         parentAgentId: extensionAgentId,
+        status: record?.status ?? "running",
+        startedAt: record?.startedAt,
+        toolUses: record?.toolUses ?? 0,
+        invocation: record?.invocation,
       });
 
       const isQueued = record?.status === "queued";
@@ -1077,7 +1109,58 @@ export default function (pi: ExtensionAPI) {
         }),
       ),
     }),
-    execute: async (_toolCallId, params, signal, _onUpdate, _ctx) => {
+    renderResult(result, { expanded }, theme) {
+      const details = result.details as GetResultDetails | undefined;
+      const text = extractText(result.content);
+
+      // Header: status + stats + description
+      let line = "";
+      if (details) {
+        const icon = details.status === "error" || details.status === "stopped" || details.status === "aborted"
+          ? theme.fg("error", "✗")
+          : details.status === "running" || details.status === "queued"
+            ? theme.fg("accent", "◌")
+            : theme.fg("success", "✓");
+
+        const parts: string[] = [];
+        if (details.toolUses > 0) parts.push(`${details.toolUses} tool use${details.toolUses === 1 ? "" : "s"}`);
+        if (details.tokens) parts.push(details.tokens);
+        if (details.contextPercent !== null) parts.push(`ctx ${Math.round(details.contextPercent)}%`);
+        if (details.duration) parts.push(details.duration);
+        const stats = parts.map(p => theme.fg("dim", p)).join(" " + theme.fg("dim", "·") + " ");
+
+        line = `${icon} ${theme.bold(details.description)} ${theme.fg("dim", details.status)}`;
+        if (stats) line += "\n  " + stats;
+      }
+
+      // Body: snip when collapsed, full when expanded
+      // Extract the body portion (after the first blank line) to keep the
+      // tool-output header always visible and only snip the actual result.
+      if (text.trim()) {
+        const firstBlank = text.indexOf("\n\n");
+        const body = firstBlank >= 0 ? text.slice(firstBlank + 2) : text;
+
+        if (expanded) {
+          for (const l of text.split("\n")) {
+            line += "\n" + theme.fg("dim", `  ${l}`);
+          }
+        } else {
+          // Show the tool-output header verbatim, then snip only the body
+          if (firstBlank >= 0) {
+            for (const l of text.slice(0, firstBlank).split("\n")) {
+              line += "\n" + theme.fg("dim", `  ${l}`);
+            }
+          }
+          for (const l of snipMiddleLines(body, 20)) {
+            line += "\n" + theme.fg("dim", `  ${l}`);
+          }
+        }
+      }
+
+      return new Text(line, 0, 0);
+    },
+
+    execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
       const record = manager.getRecord(params.agent_id);
       if (!record) {
         return textResult(`Agent not found: "${params.agent_id}". It may have been cleaned up.`);
@@ -1099,7 +1182,17 @@ export default function (pi: ExtensionAPI) {
       let waitOutcome: WaitOutcome = "completed";
       if (params.wait && record.status === "running" && record.promise) {
         cancelNudge(params.agent_id);
-        waitOutcome = await raceWait(record.promise, signal, getWaitTimeoutSeconds());
+        // Poll for queued user messages so we can return early and let the
+        // parent LLM process them immediately instead of blocking for the
+        // full wait timeout.
+        const pending = typeof ctx?.hasPendingMessages === "function"
+          ? pollPendingMessages(() => ctx.hasPendingMessages())
+          : undefined;
+        try {
+          waitOutcome = await raceWait(record.promise, signal, getWaitTimeoutSeconds(), pending?.promise);
+        } finally {
+          pending?.cancel();
+        }
         if (waitOutcome === "completed") {
           record.resultConsumed = true;
         }
@@ -1115,6 +1208,16 @@ export default function (pi: ExtensionAPI) {
       if (record.compactionCount) statsParts.push(`Compactions: ${record.compactionCount}`);
       statsParts.push(`Duration: ${duration}`);
 
+      const details: GetResultDetails = {
+        status: record.status,
+        description: record.description,
+        toolUses: record.toolUses,
+        tokens: tokens || null,
+        contextPercent,
+        duration,
+        outputFile: record.outputFile,
+      };
+
       let output =
         `Agent: ${record.id}\n` +
         `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)} | ${statsParts.join(" | ")}\n` +
@@ -1158,7 +1261,7 @@ export default function (pi: ExtensionAPI) {
         }
       }
 
-      return textResult(output);
+      return textResult(output, details);
     },
   }));
 
@@ -1218,6 +1321,11 @@ export default function (pi: ExtensionAPI) {
     },
   }));
 
+  // ---- list_subagents / clear_subagents tools ----
+
+  registerSubagentListClearTools(pi, manager);
+  registerDashboardModules(pi, manager);
+
   // ---- list_models tool ----
 
   pi.registerTool(defineTool({

package/src/peek.ts

@@ -112,6 +112,11 @@ function parseOutputFileLines(path: string): string[] {
     return [];
   }
   const out: string[] = [];
+  const pushRenderedLines = (text: string) => {
+    for (const renderedLine of text.trimEnd().split("\n")) {
+      if (renderedLine.trim()) out.push(renderedLine);
+    }
+  };
   for (const line of raw.split("\n")) {
     const trimmed = line.trim();
     if (!trimmed) continue;
@@ -124,12 +129,12 @@ function parseOutputFileLines(path: string): string[] {
     const content = entry?.message?.content;
     if (!Array.isArray(content)) {
       // Some entries may carry a plain string content.
-      if (typeof content === "string" && content.trim()) out.push(content.trim());
+      if (typeof content === "string" && content.trim()) pushRenderedLines(content);
       continue;
     }
     for (const block of content) {
       if (block?.type === "text" && typeof block.text === "string" && block.text.trim()) {
-        out.push(block.text.trimEnd());
+        pushRenderedLines(block.text);
       }
     }
   }