@mystilleef/pi-subagent 0.3.0

package/src/progress-state.ts

@@ -0,0 +1,233 @@
+import {
+  isStatusOnlyFailure,
+  isStatusOnlySuccess,
+  makeToolPreview,
+  normalizeSummaryValue,
+  normalizeTerminalSentence,
+  TOOL_PREVIEW_MAX_CHARS,
+  truncateText,
+} from "./normalize.js";
+import type { SubagentDetails } from "./types.js";
+
+export type ProgressStatus = "running" | "success" | "error" | "cancelled";
+
+export interface SubagentProgressState {
+  requestId: string;
+  agent: string;
+  taskPreview: string;
+  status: ProgressStatus;
+  startTime: number;
+  durationMs?: number;
+  lastToolPreview?: string;
+  toolCount: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  contextTokens?: number;
+  contextWindowTokens?: number;
+  finalOutput?: string;
+  errorText?: string;
+}
+
+const store = new Map<string, SubagentProgressState>();
+
+export function createProgressState(
+  requestId: string,
+  agent: string,
+  task: string,
+): void {
+  store.set(requestId, {
+    requestId,
+    agent,
+    taskPreview: makeTaskPreview(task),
+    status: "running",
+    startTime: Date.now(),
+    toolCount: 0,
+  });
+}
+
+export function getProgressState(
+  requestId: string,
+): SubagentProgressState | undefined {
+  return store.get(requestId);
+}
+
+export function patchProgressState(
+  requestId: string,
+  patch: Partial<SubagentProgressState>,
+): void {
+  const state = store.get(requestId);
+  if (!state) return;
+  if (state.status !== "running") {
+    store.set(requestId, {
+      ...state,
+      ...patch,
+      lastToolPreview: undefined,
+    });
+    return;
+  }
+  store.set(requestId, { ...state, ...patch });
+}
+
+function storeTerminalProgressState(
+  requestId: string,
+  patch: Partial<SubagentProgressState>,
+): void {
+  const state = store.get(requestId);
+  if (!state) return;
+  const durationMs = state.durationMs ?? Date.now() - state.startTime;
+  store.set(requestId, { ...state, ...patch, durationMs });
+}
+
+export function finalizeProgressState(
+  requestId: string,
+  finalOutput: string,
+): void {
+  storeTerminalProgressState(requestId, {
+    status: "success",
+    finalOutput: makeProgressFinalOutput(finalOutput),
+    lastToolPreview: undefined,
+  });
+}
+
+export function failProgressState(requestId: string, errorText: string): void {
+  const sentence = deriveFailureTerminalSentence(errorText);
+  storeTerminalProgressState(requestId, {
+    status: "error",
+    errorText: sentence,
+    lastToolPreview: undefined,
+  });
+}
+
+export function cancelProgressState(requestId: string, reason?: string): void {
+  storeTerminalProgressState(requestId, {
+    status: "cancelled",
+    lastToolPreview: undefined,
+    ...(reason !== undefined
+      ? { errorText: normalizeTerminalSentence(reason) }
+      : {}),
+  });
+}
+
+export function clearProgressState(requestId: string): void {
+  store.delete(requestId);
+}
+export function resetProgressStore(): void {
+  store.clear();
+}
+
+export function makeTaskPreview(task: string): string {
+  const flat = normalizeSummaryValue(task);
+  return flat || "(agent default)";
+}
+
+function makeProgressFinalOutput(finalOutput: string): string {
+  const lines = finalOutput
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter(Boolean);
+  const outcomeLine = lines.find((line) => /^Outcome:\s*/i.test(line));
+  const selected = outcomeLine ?? lines[0] ?? "";
+  const normalized = normalizeTerminalSentence(selected);
+  if (!normalized) return "";
+  if (isStatusOnlySuccess(normalized)) return "completed task";
+  return normalized;
+}
+
+function deriveFailureTerminalSentence(errorText: string): string {
+  const source = extractProgressSemanticErrorLine(errorText);
+  if (!source || source === "Large unstructured error output omitted.")
+    return source;
+  const normalized = normalizeTerminalSentence(source);
+  if (!normalized || isStatusOnlyFailure(normalized)) return "task failed";
+  return normalized;
+}
+
+function extractProgressSemanticErrorLine(errorText: string): string {
+  const lines = errorText
+    .split(/\r?\n/)
+    .map((line) => normalizeSummaryValue(line))
+    .filter(Boolean);
+  const statusLine = lines.find((line) =>
+    /^(?:status|error|check):\s+/i.test(line),
+  );
+  if (statusLine) return statusLine;
+  const semanticLine = lines.find((line) =>
+    isMeaningfulProgressErrorLine(line),
+  );
+  return semanticLine ?? "Large unstructured error output omitted.";
+}
+
+function isMeaningfulProgressErrorLine(line: string): boolean {
+  if (/^(?:at\s+|traceback\b|stack\b|\{|")/i.test(line)) return false;
+  if (/^(?:debug|info|warn|warning|stderr|stdout|raw log):\s*/i.test(line))
+    return false;
+  if (/^Agent \S+:\s*\S+$/i.test(line)) return false;
+  if (/^[\w.-]+:\d+:\d+/.test(line)) return false;
+  return /[A-Za-z]/.test(line) && /\s/.test(line);
+}
+
+export interface DetailsProgress {
+  lastToolPreview?: string;
+  newToolCallIds: string[];
+}
+
+export function extractProgressFromDetails(
+  details: SubagentDetails,
+  seenToolCallIds: Set<string>,
+): DetailsProgress {
+  const newToolCallIds: string[] = [];
+  let lastToolPreview: string | undefined;
+  const results = Array.isArray(details.results) ? details.results : [];
+  for (const result of results) {
+    if (result.progress) {
+      for (const toolCall of result.progress.toolCalls) {
+        if (!isDerivedToolCall(toolCall)) continue;
+        lastToolPreview = truncateText(
+          normalizeSummaryValue(toolCall.preview),
+          TOOL_PREVIEW_MAX_CHARS,
+        );
+        if (seenToolCallIds.has(toolCall.id)) continue;
+        seenToolCallIds.add(toolCall.id);
+        newToolCallIds.push(toolCall.id);
+      }
+      continue;
+    }
+    const messages = Array.isArray(result.messages) ? result.messages : [];
+    for (const msg of messages) {
+      if (msg.role !== "assistant" || !Array.isArray(msg.content)) continue;
+      for (const part of msg.content) {
+        if (isToolCallPart(part)) {
+          lastToolPreview = makeToolPreview(part.name, part.arguments);
+          if (seenToolCallIds.has(part.id)) continue;
+          seenToolCallIds.add(part.id);
+          newToolCallIds.push(part.id);
+        }
+      }
+    }
+  }
+  return { lastToolPreview, newToolCallIds };
+}
+
+function isDerivedToolCall(part: unknown): part is {
+  id: string;
+  preview: string;
+} {
+  if (typeof part !== "object" || part === null) return false;
+  const maybe = part as { id?: unknown; preview?: unknown };
+  return typeof maybe.id === "string" && typeof maybe.preview === "string";
+}
+
+export function isToolCallPart(part: unknown): part is {
+  type: "toolCall";
+  id: string;
+  name: string;
+  arguments?: Record<string, unknown>;
+} {
+  if (typeof part !== "object" || part === null) return false;
+  const maybe = part as { type?: unknown; id?: unknown; name?: unknown };
+  return (
+    maybe.type === "toolCall" &&
+    typeof maybe.id === "string" &&
+    typeof maybe.name === "string"
+  );
+}

package/src/progress.ts

@@ -0,0 +1,221 @@
+/**
+ * Subagent progress rendering and formatting.
+ *
+ * Aggregates progress-state management (re-exported from `progress-state.js`),
+ * elapsed/token formatters, and the live TUI progress component that renders
+ * subagent execution status inline in the parent agent's output stream.
+ *
+ * `renderSubagentProgress` hooks into the pi message pipeline. It produces a
+ * `DynamicSubagentProgressText` component that re-reads the progress store on
+ * each render tick, so updates from child process streaming appear instantly
+ * without explicit message-passing.
+ *
+ * All progress state lives in the store managed by `progress-state.js`.
+ * This module is purely presentational — it queries state and formats output.
+ *
+ * @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 {
+  getProgressState,
+  type ProgressStatus,
+  type SubagentProgressState,
+} 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",
+};
+
+export { makeToolPreview } from "./normalize.js";
+export {
+  cancelProgressState,
+  clearProgressState,
+  createProgressState,
+  extractProgressFromDetails,
+  failProgressState,
+  finalizeProgressState,
+  getProgressState,
+  makeTaskPreview,
+  type ProgressStatus,
+  patchProgressState,
+  resetProgressStore,
+  type SubagentProgressState,
+} 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.
+ *
+ * Called by the pi message renderer for messages with a `requestId` in
+ * their `details`. Returns `undefined` when no progress state exists for
+ * the request (e.g. before streaming starts or after cleanup).
+ *
+ * The returned `DynamicSubagentProgressText` component re-reads the
+ * progress store on every render tick, so tool counts, context usage,
+ * and output update in real time as the child process streams.
+ *
+ * @param message  - A pi message object. Must carry `details.requestId`.
+ * @param options  - `expanded` controls whether the collapsed or full
+ *                    progress view is rendered.
+ * @param theme    - Subagent color theme for styling the output.
+ * @returns A dynamic TUI component, or `undefined` if no active state.
+ */
+export function renderSubagentProgress(
+  message: {
+    customType?: string;
+    content?: unknown;
+    display?: boolean;
+    details?: unknown;
+  },
+  options: { expanded: boolean },
+  theme: SubagentTheme,
+): Component | undefined {
+  const details = message.details as { requestId?: string } | undefined;
+  const requestId = details?.requestId;
+  if (!requestId || !getProgressState(requestId)) return undefined;
+  return new DynamicSubagentProgressText(requestId, options, theme);
+}
+
+class DynamicSubagentProgressText implements Component {
+  constructor(
+    private readonly requestId: string,
+    private readonly options: { expanded: boolean },
+    private readonly theme: SubagentTheme,
+  ) {}
+  invalidate(): void {}
+  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)
+      : [];
+  }
+}
+
+function getProgressBackground(status: ProgressStatus): ThemeBg {
+  return STATUS_BG[status];
+}
+
+function formatProgressText(
+  requestId: string,
+  options: { expanded: boolean },
+  theme: SubagentTheme,
+): string | undefined {
+  const state = getProgressState(requestId);
+  if (!state) return undefined;
+  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;
+  }
+  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 (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}`;
+  }
+  return header;
+}
+
+function formatRunningToolPreview(
+  preview: string,
+  theme: SubagentTheme,
+): string {
+  const separatorIndex = preview.indexOf(":");
+  const arrow = theme.fg("muted", "→");
+  if (separatorIndex === -1) return `${arrow} ${theme.fg("accent", preview)}`;
+  const toolName = preview.slice(0, separatorIndex);
+  const rest = preview.slice(separatorIndex);
+  return `${arrow} ${theme.fg("accent", toolName)}${theme.fg("dim", rest)}`;
+}

package/src/prompt-contract.ts

@@ -0,0 +1,10 @@
+export const SUBAGENT_RESULT_CONTRACT = `
+- Always present results unchanged to the main agent.
+- End your final response with exactly one line:
+  - Outcome: <short, single, compact lower-case sentence>.
+  - Outcome summarizes the result of your task in a single sentence.
+`;
+
+export function appendSubagentResultContract(prompt: string): string {
+  return `${prompt}\n\n${SUBAGENT_RESULT_CONTRACT}`;
+}

package/src/result-details.ts

@@ -0,0 +1,97 @@
+import { TOOL_RESULT_FAILED_MESSAGE } from "./process.js";
+import {
+  extractProgressFromDetails,
+  getProgressState,
+  patchProgressState,
+} from "./progress.js";
+import {
+  formatSubagentResultForParent,
+  summarizeFeedbackUiFinalOutput,
+} from "./summary.js";
+import type {
+  SingleResult,
+  SubagentDetails,
+  SubagentToolResult,
+} from "./types.js";
+import { detectMessageError } from "./utils.js";
+
+export function hasSubagentFailed(result: SingleResult): boolean {
+  return (
+    result.exitCode !== 0 ||
+    result.stopReason === "error" ||
+    result.stopReason === "aborted" ||
+    Boolean(result.errorMessage?.trim()) ||
+    detectMessageError(result.messages ?? [])
+  );
+}
+
+export function createSubagentError(result: SingleResult): Error {
+  const formatted = formatSubagentResultForParent(result);
+  const errorMessage = result.errorMessage?.trim();
+  if (errorMessage && errorMessage !== TOOL_RESULT_FAILED_MESSAGE)
+    return new Error(`Agent ${result.stopReason || "failed"}: ${errorMessage}`);
+  const msg =
+    formatted ||
+    result.stderr ||
+    errorMessage ||
+    result.finalOutput ||
+    "(no output)";
+  return new Error(`Agent ${result.stopReason || "failed"}: ${msg}`);
+}
+
+export function sanitizeDetailsForDisplay(
+  details: SubagentDetails,
+  includeMessages = false,
+): SubagentDetails {
+  return {
+    ...details,
+    results: details.results.map(({ messages, termination, ...result }) => ({
+      ...result,
+      stderr: includeMessages ? result.stderr : "",
+      ...(includeMessages ? { messages, termination } : {}),
+    })),
+  };
+}
+
+export function patchProgressFromDetails(
+  requestId: string,
+  details: SubagentDetails,
+  seenToolCallIds: Set<string>,
+): void {
+  const latestResult = details.results[0];
+  const { newToolCallIds, lastToolPreview } = extractProgressFromDetails(
+    details,
+    seenToolCallIds,
+  );
+  const current = getProgressState(requestId);
+  if (!current) return;
+  const patch: Record<string, unknown> = {
+    toolCount: current.toolCount + newToolCallIds.length,
+  };
+  if (lastToolPreview) patch.lastToolPreview = lastToolPreview;
+  if (latestResult?.usage) {
+    patch.inputTokens = latestResult.usage.input;
+    patch.outputTokens = latestResult.usage.output;
+    patch.contextTokens = latestResult.usage.contextTokens;
+    patch.contextWindowTokens = latestResult.usage.contextWindowTokens;
+  }
+  patchProgressState(
+    requestId,
+    patch as Parameters<typeof patchProgressState>[1],
+  );
+}
+
+export function getSubagentText(result: SubagentToolResult): string {
+  return (result.content[0] as { text?: string })?.text ?? "";
+}
+
+export function getResultDisplayText(result: SubagentToolResult): string {
+  return result.details.results[0]?.finalOutput ?? getSubagentText(result);
+}
+
+export function getFeedbackSummaryText(result: SubagentToolResult): string {
+  const rawFinalOutput = result.details.results[0]?.finalOutput;
+  if (rawFinalOutput?.trim())
+    return summarizeFeedbackUiFinalOutput(rawFinalOutput);
+  return getSubagentText(result).trim() || "(no output)";
+}

package/src/run-command.ts

@@ -0,0 +1,46 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { startSubagentJob } from "./subagent-orchestrator.js";
+
+export function parseRunArgs(
+  args: string,
+): { agentName: string; task: string; debug: boolean } | undefined {
+  const input = args.trim();
+  if (!input) return undefined;
+  const debug = input.startsWith("--debug ");
+  const command = debug ? input.slice("--debug ".length).trim() : input;
+  if (!command) return undefined;
+  const firstSpace = command.indexOf(" ");
+  if (firstSpace === -1) return { agentName: command, task: "", debug };
+  return {
+    agentName: command.slice(0, firstSpace),
+    task: command.slice(firstSpace + 1).trim(),
+    debug,
+  };
+}
+
+export async function runCommandHandler(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  args: string,
+): Promise<void> {
+  const parsed = parseRunArgs(args);
+  if (!parsed) {
+    ctx.ui.notify("Usage: /run <agent> [task]", "error");
+    return;
+  }
+  const { agentName, task, debug } = parsed;
+  const result = await startSubagentJob(
+    pi,
+    ctx,
+    { agent: agentName, task, debug },
+    ctx.signal,
+  );
+  if (result.kind === "not_found") {
+    ctx.ui.notify(`Unknown agent: ${agentName}`, "error");
+  } else if (result.kind === "cancelled") {
+    ctx.ui.notify("Cancelled", "info");
+  }
+}

package/src/run-registry.ts

@@ -0,0 +1,53 @@
+export type RunJob = {
+  requestId: string;
+  agentName: string;
+  controller: AbortController;
+  startedAt: number;
+  cancelReason?: string;
+};
+
+const jobs = new Map<string, RunJob>();
+
+export function registerRunJob(job: RunJob): RunJob {
+  jobs.set(job.requestId, job);
+  return job;
+}
+
+export function getRunJob(requestId: string): Readonly<RunJob> | undefined {
+  return jobs.get(requestId);
+}
+
+export function listRunJobs(): readonly Readonly<RunJob>[] {
+  return [...jobs.values()];
+}
+
+export function removeRunJob(requestId: string): boolean {
+  return jobs.delete(requestId);
+}
+
+function abortRunJob(job: RunJob, reason: string): void {
+  if (job.controller.signal.aborted) return;
+  job.cancelReason = reason;
+  job.controller.abort(new Error(reason));
+}
+
+export function cancelRunJob(requestId: string, reason = "Cancelled"): boolean {
+  const job = jobs.get(requestId);
+  if (!job) return false;
+  abortRunJob(job, reason);
+  return true;
+}
+
+export function cancelAllRunJobs(reason = "Cancelled"): number {
+  let count = 0;
+  for (const job of jobs.values()) {
+    abortRunJob(job, reason);
+    count += 1;
+  }
+  return count;
+}
+
+export function clearRunJobsForTests(): void {
+  jobs.clear();
+}
+export const resetRunRegistry = clearRunJobsForTests;