@mystilleef/pi-subagent 0.8.0 → 0.10.1

package/src/orchestration/subagent-orchestrator.ts

@@ -1,5 +1,5 @@
 import type { AgentToolUpdateCallback } from "@earendil-works/pi-agent-core";
-import { type Message, StringEnum } from "@earendil-works/pi-ai";
+import { StringEnum } from "@earendil-works/pi-ai";
 import type {
   ExtensionAPI,
   ExtensionContext,
@@ -12,6 +12,12 @@ import type {
   ThinkingLevel,
 } from "../agent/agents.js";
 import { runSingleAgent, SubagentAbortError } from "../child/process.js";
+import { deliverNotification } from "../notification/delivery.js";
+import {
+  buildNotificationRequest,
+  isDesktopNotificationsEnabled,
+  isPerJobNotificationEnabled,
+} from "../notification/desktop-notification.js";
 import { formatSubagentResultForParent } from "../output/summary.js";
 import {
   cancelProgressState,
@@ -22,12 +28,13 @@ import {
 } from "../progress/progress.js";
 import {
   createSubagentError,
+  type DetailsOptions,
   getFeedbackSummaryText,
   getLatestResult,
   getResultDisplayText,
-  hasSubagentFailed,
   patchProgressFromDetails,
   sanitizeDetailsForDisplay,
+  sanitizeResultDetails,
 } from "../progress/result-details.js";
 import { generateSubagentInstanceName } from "../shared/instance-name.js";
 import type {
@@ -36,7 +43,7 @@ import type {
   SubagentDetails,
   SubagentToolResult,
 } from "../shared/types.js";
-import { getSubagentDepth } from "../shared/utils.js";
+import { getSubagentDepth, hasSubagentFailed } from "../shared/utils.js";
 import {
   listRunJobs,
   type RunJob,
@@ -71,12 +78,15 @@ export const SubagentParams = Type.Object({
 
 export type { SubagentToolResult };
 
-type DetailsOptions = { includeMessages?: boolean; recentMessages?: Message[] };
 type DetailsBuilder = (
   results: SingleResult[],
   options?: DetailsOptions,
 ) => SubagentDetails;
 
+function isDebugDetailsAuthorized(debugRequested: boolean): boolean {
+  return debugRequested && process.env.PI_SUBAGENT_DEBUG_ENABLED === "1";
+}
+
 interface LifecycleContext {
   pi: ExtensionAPI;
   ctx: ExtensionContext;
@@ -90,7 +100,7 @@ interface LifecycleContext {
   task: string;
   parentModel: { provider: string; id: string } | undefined;
   parentThinking: ThinkingLevel;
-  hostOnUpdate?: AgentToolUpdateCallback<SubagentDetails>;
+  hostOnUpdate?: AgentToolUpdateCallback<SubagentDetails> | undefined;
 }
 
 function createDetailsBuilder(
@@ -108,63 +118,6 @@ function createDetailsBuilder(
   });
 }
 
-function sanitizeResultDetails(
-  result: SingleResult,
-  includeDebugMessages: boolean,
-  options: DetailsOptions | undefined,
-): SingleResult {
-  const includeMessages =
-    includeDebugMessages && (options?.includeMessages ?? true);
-  const { messages, termination, progress, stderr, usage, ...core } = result;
-  const { contextWindowTokens, ...usageBase } = usage;
-  const sanitized: Record<string, unknown> = {
-    ...core,
-    stderr: includeDebugMessages ? stderr : "",
-    usage: { ...usageBase },
-  };
-  if (contextWindowTokens !== undefined) {
-    (sanitized.usage as Record<string, unknown>).contextWindowTokens =
-      contextWindowTokens;
-  }
-  if (progress !== undefined) {
-    const {
-      activityText,
-      activeToolActivity,
-      lastToolPreview,
-      toolResultCompleted,
-      ...progBase
-    } = progress;
-    sanitized.progress = {
-      toolCalls: progBase.toolCalls.map((tc) => ({
-        id: tc.id,
-        preview: tc.preview,
-      })),
-      ...(activityText !== undefined && { activityText }),
-      ...(activeToolActivity !== undefined && { activeToolActivity }),
-      ...(lastToolPreview !== undefined && { lastToolPreview }),
-      ...(toolResultCompleted !== undefined && { toolResultCompleted }),
-    };
-  }
-  if (includeMessages) {
-    sanitized.messages = options?.recentMessages
-      ? [...options.recentMessages]
-      : messages !== undefined
-        ? [...messages]
-        : undefined;
-    if (includeDebugMessages && termination !== undefined) {
-      const { cancelReason, terminationSignal, fallbackCause, ...termBase } =
-        termination;
-      sanitized.termination = {
-        ...termBase,
-        ...(cancelReason !== undefined && { cancelReason }),
-        ...(terminationSignal !== undefined && { terminationSignal }),
-        ...(fallbackCause !== undefined && { fallbackCause }),
-      };
-    }
-  }
-  return sanitized as unknown as SingleResult;
-}
-
 function createProgressRenderRequester(
   ctx: ExtensionContext,
   requestId: string,
@@ -194,11 +147,26 @@ function sendSubagentResultMessage(
   });
 }
 
+function deliverDesktopCompletionNotification(
+  state: NonNullable<ReturnType<typeof getProgressState>>,
+): void {
+  if (state.status === "cancelled") return;
+  const request = buildNotificationRequest(state);
+  deliverNotification(request).catch(() => {});
+}
+
 export function emitCompletionAlert(
   state: ReturnType<typeof getProgressState>,
 ): void {
   if (!state) return;
   if (state.status === "cancelled") return;
+  if (
+    isDesktopNotificationsEnabled() &&
+    !isPerJobNotificationEnabled() &&
+    getSubagentDepth() === 0
+  ) {
+    deliverDesktopCompletionNotification(state);
+  }
   const tty = (process.stdout as { isTTY?: boolean }).isTTY;
   if (!tty) return;
   process.stdout.write("\x07");
@@ -268,10 +236,11 @@ function createPayloadFingerprint(payload: {
   const contentText = payload.content[0]?.text ?? "";
   const latestResult = payload.details.results[0];
   const activityText = latestResult?.progress?.activityText ?? "";
-  const toolCallIds =
-    [...new Set(latestResult?.progress?.toolCalls?.map((tc) => tc.id))]
-      .sort()
-      .join(",") ?? "";
+  const toolCallIds = [
+    ...new Set(latestResult?.progress?.toolCalls?.map((tc) => tc.id)),
+  ]
+    .sort()
+    .join(",");
   const exitCode = latestResult?.exitCode ?? 0;
   const stopReason = latestResult?.stopReason ?? "";
   return `${contentText}|${activityText}|${toolCallIds}|${exitCode}|${stopReason}`;
@@ -318,6 +287,7 @@ async function runSubagentLifecycle(
       lc.makeDetails,
       lc.parentModel,
       lc.parentThinking,
+      lc.debug,
     );
     return finishLifecycleResult(lc, result);
   } catch (error) {
@@ -332,15 +302,25 @@ async function runSubagentLifecycle(
     clearInterval(timerTick);
     requestProgressRender();
     removeRunJob(lc.requestId);
-    if (listRunJobs().length === 0) {
-      const state = getProgressState(lc.requestId);
-      if (state) {
-        emitCompletionAlert(state);
-      }
-    }
+    const state = getProgressState(lc.requestId);
+    if (state) deliverLifecycleCompletionNotification(state);
   }
 }
 
+function deliverLifecycleCompletionNotification(
+  state: NonNullable<ReturnType<typeof getProgressState>>,
+): void {
+  if (
+    isDesktopNotificationsEnabled() &&
+    isPerJobNotificationEnabled() &&
+    getSubagentDepth() === 0
+  ) {
+    deliverDesktopCompletionNotification(state);
+    return;
+  }
+  if (listRunJobs().length === 0) emitCompletionAlert(state);
+}
+
 type StartJobResult =
   | {
       kind: "started";
@@ -358,11 +338,10 @@ type PrepareSubagentJobResult =
       lc: LifecycleContext;
       instanceName: string;
       requestProgressRender: () => void;
-      hostOnUpdate?: AgentToolUpdateCallback<SubagentDetails>;
+      hostOnUpdate?: AgentToolUpdateCallback<SubagentDetails> | undefined;
     }
   | { kind: "not_found"; makeDetails: DetailsBuilder }
-  | { kind: "cancelled"; makeDetails: DetailsBuilder }
-  | { kind: "aborted"; makeDetails: DetailsBuilder };
+  | { kind: "cancelled"; makeDetails: DetailsBuilder };
 
 export function formatSubagentToolResult(
   agentName: string,
@@ -409,7 +388,7 @@ async function prepareSubagentJob(
   const agentScope: AgentScope = params.agentScope ?? "both";
   const discovery = await getCachedAgentDiscovery(ctx.cwd, agentScope);
   const agents = discovery.agents;
-  const debug = params.debug === true;
+  const debug = isDebugDetailsAuthorized(params.debug === true);
   const makeDetails = createDetailsBuilder(
     agentScope,
     discovery.projectAgentsDir,
@@ -474,7 +453,7 @@ async function prepareSubagentJob(
   if (mergedSignal.aborted) {
     cancelStartedJob(job, job.cancelReason ?? "Aborted");
     requestProgressRender();
-    return { kind: "aborted", makeDetails: makeStartedDetails };
+    return { kind: "cancelled", makeDetails: makeStartedDetails };
   }
   return {
     kind: "ready",
@@ -513,11 +492,7 @@ export async function startSubagentJob(
     hostSignal,
     hostOnUpdate,
   );
-  if (prepared.kind !== "ready") {
-    if (prepared.kind === "aborted")
-      return { kind: "cancelled", makeDetails: prepared.makeDetails };
-    return prepared;
-  }
+  if (prepared.kind !== "ready") return prepared;
   const { lc, instanceName, requestProgressRender } = prepared;
   if (getSubagentDepth() > 0) {
     const result = await runSubagentLifecycle(lc);

package/src/output/normalize.ts

@@ -1,4 +1,4 @@
-export const TERMINAL_SENTENCE_MAX_CHARS = 100;
+const TERMINAL_SENTENCE_MAX_CHARS = 100;
 
 export function normalizeSummaryValue(value: string): string {
   const normalized = value.trim().replace(/\s+/g, " ");
@@ -67,7 +67,7 @@ export function normalizeTerminalSentence(
   return truncateText(collapsed, limit);
 }
 
-export const TOOL_PREVIEW_MAX_CHARS = 120;
+const TOOL_PREVIEW_MAX_CHARS = 120;
 
 export function normalizeAndTruncate(
   text: string,

package/src/output/ui.ts

@@ -11,6 +11,8 @@ import type { AgentScope } from "../agent/agents.js";
 import {
   formatContextPercent,
   formatElapsed,
+} from "../progress/progress-format.js";
+import {
   type ProgressStatus,
   STATUS_BG,
   STATUS_COLOR,
@@ -18,8 +20,8 @@ import {
   type SubagentProgressState,
   type ThemeBg,
 } from "../progress/progress-state.js";
-import { hasSubagentFailed } from "../progress/result-details.js";
 import type { SubagentDetails, UsageStats } from "../shared/types.js";
+import { hasSubagentFailed } from "../shared/utils.js";
 import {
   extractSemanticToolTarget,
   normalizeSummaryValue,
@@ -115,9 +117,6 @@ export function formatResultFooter(usage: UsageStats, model?: string): string {
   return parts.join(" · ");
 }
 
-/**
- * Formats a tool call for the UI, optionally extracting a semantic target for clarity.
- */
 export function formatToolCall(
   toolName: string,
   args: Record<string, unknown>,
@@ -131,9 +130,6 @@ export function formatToolCall(
   return themeFg("accent", toolName) + themeFg("dim", ` ${target}`);
 }
 
-/**
- * Extracts the final text response from an array of assistant messages.
- */
 export function getFinalOutput(messages: Message[]): string {
   const lastAsst = messages.findLast((m) => m.role === "assistant");
   const lastText = lastAsst?.content.findLast((p) => p.type === "text");
@@ -148,9 +144,6 @@ function stripOutcomeLineForResultUi(output: string): string {
   return stripped.trim() ? stripped : output;
 }
 
-/**
- * Maps subagent theme colors to Markdown rendering components.
- */
 function makeMarkdownTheme(theme: SubagentTheme): MarkdownTheme {
   const fg = (c: ThemeColor) => (text: string) => theme.fg(c, text);
   return {
@@ -172,9 +165,6 @@ function makeMarkdownTheme(theme: SubagentTheme): MarkdownTheme {
   };
 }
 
-/**
- * Renders the pending subagent call UI component.
- */
 export function renderSubagentCall(
   args: { agent?: string; task?: string; agentScope?: AgentScope },
   theme: SubagentTheme,
@@ -205,7 +195,7 @@ export function renderSubagentToolResult(
 export function renderSubagentResult(
   result: { content: { type: string; text?: string }[]; details?: unknown },
   theme: SubagentTheme,
-  _display?: { isPartial?: boolean },
+  display?: { isPartial?: boolean },
   bodyOverride?: string,
 ): Component {
   const details = result.details as SubagentDetails | undefined;
@@ -228,7 +218,7 @@ export function renderSubagentResult(
   const finalOutput = r.finalOutput ?? getFinalOutput(r.messages ?? []);
   const title = formatSubagentTitle(r.agent, r.instanceName, theme);
   let effectiveBody = bodyOverride ?? finalOutput;
-  if (_display?.isPartial && !finalOutput?.trim() && !bodyOverride) {
+  if (display?.isPartial && !finalOutput?.trim() && !bodyOverride) {
     effectiveBody =
       result.content[0]?.text ||
       r.progress?.activityText ||
@@ -241,7 +231,7 @@ export function renderSubagentResult(
   const ctxPercent = formatContextPercent({
     contextTokens: r.usage.contextTokens,
     contextWindowTokens: r.usage.contextWindowTokens,
-  } as SubagentProgressState);
+  });
   const metadata = `${toolLabel} · ${ctxPercent} ctx · ${formatElapsed(r.durationMs ?? 0)}`;
   const usageStr = formatResultFooter(r.usage, r.model);
   return renderStatusCard(
@@ -285,7 +275,7 @@ function renderStatusCard(
     : "";
   box.addChild(new Text(`${icon} ${options.title} ${status}${metadata}`, 0, 0));
   box.addChild(makeStatusCardBody(options, theme));
-  if (options.variant === "full" && options.footer)
+  if (options.footer)
     box.addChild(new Text(theme.fg("dim", options.footer), 0, 0));
   return box;
 }
@@ -294,7 +284,7 @@ function makeStatusCardBody(
   options: StatusCardOptions,
   theme: SubagentTheme,
 ): Box {
-  const body = new Box(2, options.variant === "full" ? 1 : 0);
+  const body = new Box(2, options.variant === "full" || options.footer ? 1 : 0);
   const bodyText = options.body ?? "";
   if (bodyText && options.variant === "full") {
     body.addChild(
@@ -336,16 +326,15 @@ function renderJobCard(
     bodyText.length > BODY_PREVIEW_MAX
       ? `${bodyText.slice(0, BODY_PREVIEW_MAX - 1)}…`
       : bodyText;
-  return renderStatusCard(
-    {
-      status: state.status,
-      title,
-      variant: "abridged",
-      metadata,
-      body: preview,
-    },
-    theme,
-  );
+  const options: StatusCardOptions = {
+    status: state.status,
+    title,
+    variant: "abridged",
+    metadata,
+    body: preview,
+  };
+  if (state.modelDisplay) options.footer = state.modelDisplay;
+  return renderStatusCard(options, theme);
 }
 
 function sortByStartTimeDesc(

package/src/progress/progress-format.ts

@@ -0,0 +1,111 @@
+/**
+ * Formatting and rendering helpers for subagent progress display.
+ *
+ * Pure presentation logic extracted from progress-state.js. No state
+ * management or store access — only transforms data into display strings.
+ */
+
+import {
+  normalizeAndTruncate,
+  normalizeSummaryValue,
+  truncateText,
+} from "../output/normalize.js";
+import type { ToolActivity } from "../shared/types.js";
+import type { SubagentProgressState } from "./progress-state.js";
+
+export const SENSITIVE_PATTERN = /secret|token|password/i;
+
+const REDACTED_PLACEHOLDER = "(running...)";
+const REDACTED_PLACEHOLDER_LENGTH = REDACTED_PLACEHOLDER.length;
+
+function redactOrTruncate(text: string, maxChars: number): string {
+  if (SENSITIVE_PATTERN.test(text))
+    return maxChars >= REDACTED_PLACEHOLDER_LENGTH ? REDACTED_PLACEHOLDER : "";
+  return truncateText(text, maxChars);
+}
+
+function walkActivityTree(activity: ToolActivity): string[] {
+  const parts: string[] = [];
+  let current: ToolActivity | undefined = activity;
+  while (current) {
+    if (current.inputSummary) {
+      const annotated = current.instanceName
+        ? `${current.inputSummary} [${current.instanceName}]`
+        : current.inputSummary;
+      parts.push(annotated);
+    }
+    current = current.child;
+  }
+  return parts;
+}
+
+/**
+ * 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`;
+}
+
+export function formatContextPercent(state: {
+  contextTokens?: number | undefined;
+  contextWindowTokens?: number | undefined;
+}): string {
+  const windowTokens = state.contextWindowTokens;
+  if (!windowTokens || windowTokens <= 0 || !Number.isFinite(windowTokens))
+    return "--%";
+  const usedTokens = state.contextTokens;
+  if (!usedTokens || usedTokens <= 0 || !Number.isFinite(usedTokens))
+    return "0%";
+  return `${Math.round((usedTokens / windowTokens) * 100)}%`;
+}
+
+/**
+ * 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, e.g. `"3 tools · 45% ctx · 12.3s"`
+ */
+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)}`;
+}
+
+/**
+ * Renders a ToolActivity tree for storage. Each segment is
+ * independently normalized and truncated to TOOL_PREVIEW_MAX_CHARS (120).
+ */
+export function renderToolActivity(
+  activity: ToolActivity | undefined,
+): string | undefined {
+  if (!activity) return undefined;
+  const parts = walkActivityTree(activity);
+  if (parts.length === 0) return activity.toolName;
+  const result = parts.map((p) => normalizeAndTruncate(p)).join(" - ");
+  if (SENSITIVE_PATTERN.test(result)) return REDACTED_PLACEHOLDER;
+  return result;
+}
+
+/**
+ * Renders a ToolActivity tree for display with a caller-provided truncation
+ * budget. Segments are normalized without individual truncation so the
+ * joined result shares one post-join display budget.
+ */
+export function renderToolActivityForDisplay(
+  activity: ToolActivity | undefined,
+  maxChars: number,
+): string | undefined {
+  if (!activity) return undefined;
+  if (maxChars <= 0) return "";
+  const parts = walkActivityTree(activity);
+  if (parts.length === 0) return redactOrTruncate(activity.toolName, maxChars);
+  const joined = parts.map((p) => normalizeSummaryValue(p)).join(" - ");
+  return redactOrTruncate(joined, maxChars);
+}