@mystilleef/pi-subagent 0.3.0 → 0.4.0

package/src/progress.ts

@@ -16,36 +16,19 @@
  * @module progress
  */
 
-import type { ThemeColor } from "@earendil-works/pi-coding-agent";
 import type { Component } from "@earendil-works/pi-tui";
-import { Text } from "@earendil-works/pi-tui";
+import { Box, Text } from "@earendil-works/pi-tui";
 import {
+  formatHeaderStats,
   getProgressState,
   type ProgressStatus,
+  STATUS_BG,
+  STATUS_COLOR,
+  STATUS_ICON,
   type SubagentProgressState,
+  type ThemeBg,
 } from "./progress-state.js";
-import type { SubagentTheme, ThemeBg } from "./ui.js";
-
-const STATUS_COLOR: Record<ProgressStatus, ThemeColor> = {
-  success: "success",
-  error: "error",
-  cancelled: "error",
-  running: "accent",
-};
-
-const STATUS_ICON: Record<ProgressStatus, string> = {
-  success: "✓",
-  error: "✗",
-  cancelled: "⊘",
-  running: "⟳",
-};
-
-const STATUS_BG: Record<ProgressStatus, ThemeBg> = {
-  success: "toolSuccessBg",
-  error: "toolErrorBg",
-  cancelled: "toolErrorBg",
-  running: "toolPendingBg",
-};
+import { formatSubagentTitle, type SubagentTheme } from "./ui.js";
 
 export { makeToolPreview } from "./normalize.js";
 export {
@@ -55,64 +38,21 @@ export {
   extractProgressFromDetails,
   failProgressState,
   finalizeProgressState,
+  formatContextPercent,
+  formatElapsed,
+  formatHeaderStats,
+  formatTokenCount,
   getProgressState,
   makeTaskPreview,
   type ProgressStatus,
   patchProgressState,
   resetProgressStore,
+  STATUS_COLOR,
+  STATUS_ICON,
   type SubagentProgressState,
+  type ThemeBg,
 } from "./progress-state.js";
 
-/**
- * Format a millisecond duration for compact display.
- * Renders sub-minute durations as decimal seconds (`45.2s`),
- * longer durations as minutes and whole seconds (`2m 15s`).
- */
-export function formatElapsed(ms: number): string {
-  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
-  const mins = Math.floor(ms / 60000);
-  const secs = Math.floor((ms % 60000) / 1000);
-  return `${mins}m ${secs}s`;
-}
-
-/**
- * Format a raw token count for compact inline display.
- * Values below 1000 rendered as-is. Larger counts use `k`
- * or `M` suffixes with one decimal place, stripping trailing `.0`.
- */
-export function formatTokenCount(count: number): string {
-  if (count < 1000) return String(count);
-  const unit = count >= 1_000_000 ? "M" : "k";
-  const divisor = count >= 1_000_000 ? 1_000_000 : 1000;
-  return `${trimTrailingZero((count / divisor).toFixed(1))}${unit}`;
-}
-
-/**
- * Format the one-line statistics header for a subagent progress display.
- * Includes tool count, context window usage, and elapsed time.
- * When the subagent is still running (`durationMs` unset), elapsed is
- * computed live from `startTime`.
- *
- * @returns Single line ending in `\n`, e.g. `"3 tools · 45% ctx · 12.3s\n"`
- */
-export function formatHeaderStats(state: SubagentProgressState): string {
-  const elapsedMs = state.durationMs ?? Date.now() - state.startTime;
-  const toolLabel = state.toolCount === 1 ? "tool" : "tools";
-  return `${state.toolCount} ${toolLabel} · ${formatContextPercent(state)} ctx · ${formatElapsed(elapsedMs)}\n`;
-}
-
-function formatContextPercent(state: SubagentProgressState): string {
-  const d = state.contextWindowTokens;
-  if (!d || d <= 0 || !Number.isFinite(d)) return "--%";
-  const n = state.contextTokens;
-  if (!n || n <= 0 || !Number.isFinite(n)) return "0%";
-  return `${Math.round((n / d) * 100)}%`;
-}
-
-function trimTrailingZero(value: string): string {
-  return value.endsWith(".0") ? value.slice(0, -2) : value;
-}
-
 /**
  * Create a live-updating TUI progress component from a pi message.
  *
@@ -156,11 +96,7 @@ class DynamicSubagentProgressText implements Component {
   render(width: number): string[] {
     const state = getProgressState(this.requestId);
     if (!state) return [];
-    const text = formatProgressText(this.requestId, this.options, this.theme);
-    const bg = getProgressBackground(state.status);
-    return text
-      ? new Text(text, 1, 1, (line) => this.theme.bg(bg, line)).render(width)
-      : [];
+    return renderProgressBox(state, this.options, this.theme).render(width);
   }
 }
 
@@ -168,44 +104,97 @@ function getProgressBackground(status: ProgressStatus): ThemeBg {
   return STATUS_BG[status];
 }
 
-function formatProgressText(
-  requestId: string,
+function renderProgressBox(
+  state: SubagentProgressState,
   options: { expanded: boolean },
   theme: SubagentTheme,
-): string | undefined {
-  const state = getProgressState(requestId);
-  if (!state) return undefined;
+): Box {
   const status = state.status;
-  const header = `${theme.fg(STATUS_COLOR[status], STATUS_ICON[status])} ${theme.fg("toolTitle", theme.bold(state.agent))} ${theme.fg("dim", `[${status}]`)} ${theme.fg("muted", formatHeaderStats(state))}`;
-  if (status === "running") {
-    const toolLine = state.lastToolPreview
-      ? `\n  ${formatRunningToolPreview(state.lastToolPreview, theme)}`
-      : "";
-    const taskLine = options.expanded
-      ? `\n  ${theme.fg("dim", state.taskPreview)}`
-      : "";
-    return header + toolLine + taskLine;
+  const title = formatSubagentTitle(state.agent, state.instanceName, theme);
+  const header = `${theme.fg(STATUS_COLOR[status], STATUS_ICON[status])} ${title} ${theme.fg("dim", `[${status}]`)} ${theme.fg("muted", formatHeaderStats(state))}`;
+  const box = new Box(1, 1, (line) =>
+    theme.bg(getProgressBackground(status), line),
+  );
+  box.addChild(new Text(header, 0, 0));
+  addProgressBody(box, state, options, theme);
+  return box;
+}
+
+function addProgressBody(
+  box: Box,
+  state: SubagentProgressState,
+  options: { expanded: boolean },
+  theme: SubagentTheme,
+): void {
+  const body = makeProgressBody(state, options, theme);
+  if (body.length === 0) return;
+  for (const line of body) box.addChild(line);
+}
+
+function makeProgressBody(
+  state: SubagentProgressState,
+  options: { expanded: boolean },
+  theme: SubagentTheme,
+): Text[] {
+  if (state.status === "running")
+    return makeRunningProgressBody(state, options, theme);
+  if (state.status === "error" || state.status === "cancelled") {
+    return makeStoppedProgressBody(state, options, theme);
   }
-  if (status === "error" || status === "cancelled") {
-    const errorLine = state.errorText
-      ? `\n  ${theme.fg("error", state.errorText)}`
-      : "";
-    const taskLine = options.expanded
-      ? `\n  ${theme.fg("dim", state.taskPreview)}`
-      : "";
-    return header + errorLine + taskLine;
+  if (state.status === "success")
+    return makeSuccessProgressBody(state, options, theme);
+  return [];
+}
+
+function makeRunningProgressBody(
+  state: SubagentProgressState,
+  options: { expanded: boolean },
+  theme: SubagentTheme,
+): Text[] {
+  const body: Text[] = [];
+  if (state.lastToolPreview) {
+    body.push(
+      new Text(formatRunningToolPreview(state.lastToolPreview, theme), 2, 0),
+    );
   }
-  if (status === "success") {
-    const output = state.finalOutput?.trim().split("\n")[0] ?? "";
-    if (!options.expanded) {
-      return output ? `${header}\n  ${theme.fg("toolOutput", output)}` : header;
-    }
-    const outputSection = output
-      ? `\n${theme.fg("muted", "─── Output ───")}\n${theme.fg("toolOutput", output)}`
-      : `\n${theme.fg("muted", "(no output)")}`;
-    return `${header}\n  ${theme.fg("dim", state.taskPreview)}${outputSection}`;
+  if (options.expanded)
+    body.push(new Text(theme.fg("dim", state.taskPreview), 2, 0));
+  return body;
+}
+
+function makeStoppedProgressBody(
+  state: SubagentProgressState,
+  options: { expanded: boolean },
+  theme: SubagentTheme,
+): Text[] {
+  const body: Text[] = [];
+  if (state.errorText)
+    body.push(new Text(theme.fg("error", state.errorText), 2, 0));
+  if (options.expanded)
+    body.push(new Text(theme.fg("dim", state.taskPreview), 2, 0));
+  return body;
+}
+
+function makeSuccessProgressBody(
+  state: SubagentProgressState,
+  options: { expanded: boolean },
+  theme: SubagentTheme,
+): Text[] {
+  const output = state.finalOutput?.trim().split("\n")[0] ?? "";
+  if (!options.expanded) {
+    return output ? [new Text(theme.fg("toolOutput", output), 2, 0)] : [];
   }
-  return header;
+  const body = [new Text(theme.fg("dim", state.taskPreview), 2, 0)];
+  body.push(
+    output
+      ? new Text(
+          `${theme.fg("muted", "─── Output ───")}\n${theme.fg("toolOutput", output)}`,
+          0,
+          0,
+        )
+      : new Text(theme.fg("muted", "(no output)"), 0, 0),
+  );
+  return body;
 }
 
 function formatRunningToolPreview(

package/src/run-registry.ts

@@ -1,6 +1,7 @@
 export type RunJob = {
   requestId: string;
   agentName: string;
+  instanceName: string;
   controller: AbortController;
   startedAt: number;
   cancelReason?: string;

package/src/subagent-orchestrator.ts

@@ -11,12 +11,15 @@ import {
   discoverAgents,
   type ThinkingLevel,
 } from "./agents.js";
+import { generateSubagentInstanceName } from "./instance-name.js";
 import { runSingleAgent } from "./process.js";
 import {
   cancelProgressState,
   createProgressState,
   failProgressState,
   finalizeProgressState,
+  formatElapsed,
+  getProgressState,
 } from "./progress.js";
 import {
   createSubagentError,
@@ -26,7 +29,12 @@ import {
   patchProgressFromDetails,
   sanitizeDetailsForDisplay,
 } from "./result-details.js";
-import { type RunJob, registerRunJob, removeRunJob } from "./run-registry.js";
+import {
+  listRunJobs,
+  type RunJob,
+  registerRunJob,
+  removeRunJob,
+} from "./run-registry.js";
 import { formatSubagentResultForParent } from "./summary.js";
 import type {
   OnUpdateCallback,
@@ -167,6 +175,32 @@ function sendSubagentResultMessage(
   });
 }
 
+export function emitCompletionNotification(
+  ctx: ExtensionContext,
+  state: ReturnType<typeof getProgressState>,
+): void {
+  if (!state) return;
+  if (state.status === "cancelled") return;
+  if (!ctx.ui?.notify) return;
+  const tty = (process.stdout as { isTTY?: boolean }).isTTY;
+  if (!tty) return;
+  const icon = state.status === "error" ? "✗" : "✓";
+  const severity =
+    state.status === "error" ? ("error" as const) : ("info" as const);
+  const elapsed = formatElapsed(
+    state.durationMs ?? Date.now() - state.startTime,
+  );
+  const raw = state.errorText ?? state.finalOutput ?? "";
+  const preview = raw.trim().slice(0, 80);
+  const namePart = state.instanceName
+    ? `${state.agent} ${state.instanceName}`
+    : state.agent;
+  const toast = `${namePart} ${icon}  ${elapsed} — "${preview}"`;
+  // Terminal bell to draw attention when all jobs complete
+  process.stdout.write("\x07");
+  ctx.ui.notify(toast, severity);
+}
+
 async function runSubagentWorker(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
@@ -252,11 +286,22 @@ async function runSubagentWorker(
   } finally {
     requestProgressRender();
     removeRunJob(requestId);
+    if (listRunJobs().length === 0) {
+      const state = getProgressState(requestId);
+      if (state) {
+        emitCompletionNotification(ctx, state);
+      }
+    }
   }
 }
 
 export type StartJobResult =
-  | { kind: "started"; requestId: string; makeDetails: DetailsBuilder }
+  | {
+      kind: "started";
+      requestId: string;
+      instanceName: string;
+      makeDetails: DetailsBuilder;
+    }
   | { kind: "cancelled"; makeDetails: DetailsBuilder }
   | { kind: "not_found"; makeDetails: DetailsBuilder };
 
@@ -266,7 +311,7 @@ export function formatStartJobStatus(
 ): string {
   if (result.kind === "not_found") return `Unknown agent: "${agentName}"`;
   if (result.kind === "cancelled") return "Canceled";
-  return `Subagent ${agentName} started (job: ${result.requestId})`;
+  return `Subagent ${agentName} ${result.instanceName} started (job: ${result.requestId})`;
 }
 
 function needsProjectAgentConfirmation(
@@ -305,6 +350,16 @@ export async function startSubagentJob(
   );
   const requested = agents.find((a) => a.name === params.agent);
   if (!requested) return { kind: "not_found", makeDetails };
+  if (hostSignal?.aborted) return { kind: "cancelled", makeDetails };
+  const task = params.task?.trim() ?? "";
+  if (needsProjectAgentConfirmation(ctx, requested)) {
+    const confirmed = await confirmProjectAgentRun(
+      ctx,
+      requested,
+      discovery.projectAgentsDir,
+    );
+    if (!confirmed) return { kind: "cancelled", makeDetails };
+  }
   if (requested.source === "project") {
     const userAgents = discoverAgents(ctx.cwd, "user");
     const hasUserCollision = userAgents.agents.some(
@@ -319,36 +374,34 @@ export async function startSubagentJob(
       });
     }
   }
-  const task = params.task?.trim() ?? "";
-  if (needsProjectAgentConfirmation(ctx, requested)) {
-    const confirmed = await confirmProjectAgentRun(
-      ctx,
-      requested,
-      discovery.projectAgentsDir,
-    );
-    if (!confirmed) return { kind: "cancelled", makeDetails };
-  }
   const parentModel = ctx.model
     ? { provider: ctx.model.provider, id: ctx.model.id }
     : undefined;
   const parentThinking = pi.getThinkingLevel() as ThinkingLevel;
   const requestId = crypto.randomUUID();
+  const instanceName = generateSubagentInstanceName();
   const controller = new AbortController();
   const job: RunJob = registerRunJob({
     requestId,
     agentName: params.agent,
+    instanceName,
     controller,
     startedAt: Date.now(),
   });
   const mergedSignal = hostSignal
     ? AbortSignal.any([hostSignal, job.controller.signal])
     : job.controller.signal;
-  createProgressState(requestId, params.agent, task);
+  const makeStartedDetails: DetailsBuilder = (results, options) =>
+    makeDetails(
+      results.map((result) => ({ ...result, instanceName })),
+      options,
+    );
+  createProgressState(requestId, params.agent, task, instanceName);
   pi.sendMessage({
     customType: "subagent-progress",
     content: "",
     display: true,
-    details: { requestId },
+    details: { agent: params.agent, instanceName, requestId },
   });
   const requestProgressRender = createProgressRenderRequester(ctx, requestId);
   setImmediate(() => {
@@ -366,12 +419,17 @@ export async function startSubagentJob(
       debug,
       parentModel,
       parentThinking,
-      makeDetails,
+      makeStartedDetails,
       requestId,
       job,
       mergedSignal,
     );
   });
   if (mergedSignal.aborted) return { kind: "cancelled", makeDetails };
-  return { kind: "started", requestId, makeDetails };
+  return {
+    kind: "started",
+    requestId,
+    instanceName,
+    makeDetails: makeStartedDetails,
+  };
 }

package/src/termination.ts

@@ -124,10 +124,13 @@ function sendTreeSignal(
     sendDirectSignal(proc, signal, state, options);
     return;
   }
-  if (options.killProcessTree) {
-    options.killProcessTree(proc, signal, platform);
+  const markTreeKilled = () => {
     state.metadata.target = "tree";
     state.metadata.processTreeKilled = true;
+  };
+  if (options.killProcessTree) {
+    options.killProcessTree(proc, signal, platform);
+    markTreeKilled();
     return;
   }
   if (platform !== "win32") {
@@ -137,8 +140,7 @@ function sendTreeSignal(
       options.killProcessGroup ??
       ((pid, nextSignal) => process.kill(pid, nextSignal))
     )(-pid, signal);
-    state.metadata.target = "tree";
-    state.metadata.processTreeKilled = true;
+    markTreeKilled();
     return;
   }
   if (signal === "SIGKILL") {
@@ -148,8 +150,7 @@ function sendTreeSignal(
       "/t",
       "/f",
     ]);
-    state.metadata.target = "tree";
-    state.metadata.processTreeKilled = true;
+    markTreeKilled();
     return;
   }
   throw new Error("unsupported tree termination platform");

package/src/types.ts

@@ -26,6 +26,7 @@ export interface StreamingProgress {
 
 export interface SingleResult {
   agent: string;
+  instanceName?: string;
   agentSource: "user" | "project" | "unknown";
   task: string;
   exitCode: number;