@gotgenes/pi-subagents 4.0.0 → 4.1.1

package/src/model-resolver.ts

@@ -14,6 +14,45 @@ export interface ModelRegistry {
   getAvailable?(): any[];
 }
 
+/** Successful model resolution — `model` is the resolved or inherited model instance. */
+export interface ModelResolutionResult {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  model: any;
+  error?: undefined;
+}
+
+/** Failed model resolution when the model was user-specified (params) — surface the error. */
+export interface ModelResolutionError {
+  model?: undefined;
+  error: string;
+}
+
+/** Discriminated union returned by `resolveInvocationModel`. */
+export type ModelResolution = ModelResolutionResult | ModelResolutionError;
+
+/**
+ * Resolve the effective model for an agent invocation.
+ *
+ * Encapsulates the three-branch fallback policy used in `Agent.execute`:
+ * 1. No `modelInput` → inherit `parentModel`.
+ * 2. `modelInput` resolves → return the resolved model.
+ * 3. `modelInput` fails:
+ *    - `modelFromParams` true  → return `{ error }` so the caller can surface it.
+ *    - `modelFromParams` false → silent fallback to `parentModel`.
+ */
+export function resolveInvocationModel(
+  parentModel: unknown,
+  modelInput: string | undefined,
+  modelFromParams: boolean,
+  registry: ModelRegistry,
+): ModelResolution {
+  if (!modelInput) return { model: parentModel };
+  const resolved = resolveModel(modelInput, registry);
+  if (typeof resolved !== "string") return { model: resolved };
+  if (modelFromParams) return { error: resolved };
+  return { model: parentModel };
+}
+
 /**
  * Resolve a model string to a Model instance.
  * Tries exact match first ("provider/modelId"), then fuzzy match against all available models.

package/src/notification.ts

@@ -0,0 +1,188 @@
+import type { AgentRecord, NotificationDetails } from "./types.js";
+import type { AgentActivity } from "./ui/agent-widget.js";
+import { getLifetimeTotal, getSessionContextPercent } from "./usage.js";
+
+// ---- Pure helpers (exported for unit testing) ----
+
+/** Escape XML special characters to prevent injection in structured notifications. */
+export function escapeXml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** Human-readable status label for agent completion. */
+export function getStatusLabel(status: string, error?: string): string {
+  switch (status) {
+    case "error":
+      return `Error: ${error ?? "unknown"}`;
+    case "aborted":
+      return "Aborted (max turns exceeded)";
+    case "steered":
+      return "Wrapped up (turn limit)";
+    case "stopped":
+      return "Stopped";
+    default:
+      return "Done";
+  }
+}
+
+/** Format a structured task notification matching Claude Code's <task-notification> XML. */
+export function formatTaskNotification(record: AgentRecord, resultMaxLen: number): string {
+  const status = getStatusLabel(record.status, record.error);
+  const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
+  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
+  const contextPercent = getSessionContextPercent(record.session);
+  const ctxXml = contextPercent !== null ? `<context_percent>${Math.round(contextPercent)}</context_percent>` : "";
+  const compactXml = record.compactionCount ? `<compactions>${record.compactionCount}</compactions>` : "";
+
+  const resultPreview = record.result
+    ? record.result.length > resultMaxLen
+      ? record.result.slice(0, resultMaxLen) + "\n...(truncated, use get_subagent_result for full output)"
+      : record.result
+    : "No output.";
+
+  return [
+    "<task-notification>",
+    `<task-id>${record.id}</task-id>`,
+    record.toolCallId ? `<tool-use-id>${escapeXml(record.toolCallId)}</tool-use-id>` : null,
+    record.outputFile ? `<output-file>${escapeXml(record.outputFile)}</output-file>` : null,
+    `<status>${escapeXml(status)}</status>`,
+    `<summary>Agent "${escapeXml(record.description)}" ${record.status}</summary>`,
+    `<result>${escapeXml(resultPreview)}</result>`,
+    `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses>${ctxXml}${compactXml}<duration_ms>${durationMs}</duration_ms></usage>`,
+    "</task-notification>",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+/** Build notification details for the custom message renderer. */
+export function buildNotificationDetails(
+  record: AgentRecord,
+  resultMaxLen: number,
+  activity?: AgentActivity,
+): NotificationDetails {
+  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
+
+  return {
+    id: record.id,
+    description: record.description,
+    status: record.status,
+    toolUses: record.toolUses,
+    turnCount: activity?.turnCount ?? 0,
+    maxTurns: activity?.maxTurns,
+    totalTokens,
+    durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
+    outputFile: record.outputFile,
+    error: record.error,
+    resultPreview: record.result
+      ? record.result.length > resultMaxLen
+        ? record.result.slice(0, resultMaxLen) + "…"
+        : record.result
+      : "No output.",
+  };
+}
+
+/** Build event data for lifecycle events from an AgentRecord. */
+export function buildEventData(record: AgentRecord) {
+  const durationMs = record.completedAt ? record.completedAt - record.startedAt : Date.now() - record.startedAt;
+  const u = record.lifetimeUsage;
+  const total = getLifetimeTotal(u);
+  const tokens =
+    total > 0
+      ? { input: u.input, output: u.output, total }
+      : undefined;
+  return {
+    id: record.id,
+    type: record.type,
+    description: record.description,
+    result: record.result,
+    error: record.error,
+    status: record.status,
+    toolUses: record.toolUses,
+    durationMs,
+    tokens,
+  };
+}
+
+// ---- Notification system factory ----
+
+/** Narrow deps for the notification system — only the methods it actually calls. */
+export interface NotificationDeps {
+  sendMessage: (msg: unknown, opts: unknown) => void;
+  agentActivity: Map<string, AgentActivity>;
+  markFinished: (id: string) => void;
+  updateWidget: () => void;
+}
+
+export interface NotificationSystem {
+  cancelNudge: (key: string) => void;
+  sendCompletion: (record: AgentRecord) => void;
+  cleanupCompleted: (id: string) => void;
+  dispose: () => void;
+}
+
+const NUDGE_HOLD_MS = 200;
+
+export function createNotificationSystem(deps: NotificationDeps): NotificationSystem {
+  const pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
+
+  function cancelNudge(key: string) {
+    const timer = pendingNudges.get(key);
+    if (timer != null) {
+      clearTimeout(timer);
+      pendingNudges.delete(key);
+    }
+  }
+
+  function scheduleNudge(key: string, send: () => void, delay = NUDGE_HOLD_MS) {
+    cancelNudge(key);
+    pendingNudges.set(
+      key,
+      setTimeout(() => {
+        pendingNudges.delete(key);
+        try {
+          send();
+        } catch {
+          /* ignore stale completion side-effect errors */
+        }
+      }, delay),
+    );
+  }
+
+  function emitIndividualNudge(record: AgentRecord) {
+    if (record.resultConsumed) return;
+
+    const notification = formatTaskNotification(record, 500);
+    const footer = record.outputFile ? `\nFull transcript available at: ${record.outputFile}` : "";
+
+    deps.sendMessage(
+      {
+        customType: "subagent-notification",
+        content: notification + footer,
+        display: true,
+        details: buildNotificationDetails(record, 500, deps.agentActivity.get(record.id)),
+      },
+      { deliverAs: "followUp", triggerTurn: true },
+    );
+  }
+
+  function sendCompletion(record: AgentRecord) {
+    deps.agentActivity.delete(record.id);
+    deps.markFinished(record.id);
+    scheduleNudge(record.id, () => emitIndividualNudge(record));
+    deps.updateWidget();
+  }
+
+  function cleanupCompleted(id: string) {
+    deps.agentActivity.delete(id);
+    deps.markFinished(id);
+    deps.updateWidget();
+  }
+
+  function dispose() {
+    for (const timer of pendingNudges.values()) clearTimeout(timer);
+    pendingNudges.clear();
+  }
+
+  return { cancelNudge, sendCompletion, cleanupCompleted, dispose };
+}

package/src/renderer.ts

@@ -0,0 +1,67 @@
+import { Text } from "@earendil-works/pi-tui";
+import type { NotificationDetails } from "./types.js";
+import { formatMs, formatTokens, formatTurns } from "./ui/agent-widget.js";
+
+/** Narrow theme interface — only the methods the renderer actually calls. */
+interface RendererTheme {
+  fg(style: string, text: string): string;
+  bold(text: string): string;
+}
+
+/** Narrow message interface — only the fields the renderer reads. */
+interface RendererMessage {
+  details?: NotificationDetails;
+}
+
+/** Narrow render options — only the fields the renderer reads. */
+interface RenderOptions {
+  expanded: boolean;
+}
+
+/**
+ * Create the notification renderer callback for `pi.registerMessageRenderer`.
+ * Returns a factory so the renderer is independently testable without the Pi SDK.
+ */
+export function createNotificationRenderer() {
+  return (message: RendererMessage, { expanded }: RenderOptions, theme: RendererTheme): Text | undefined => {
+    const d = message.details;
+    if (!d) return undefined;
+
+    const isError = d.status === "error" || d.status === "stopped" || d.status === "aborted";
+    const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");
+    const statusText = isError
+      ? d.status
+      : d.status === "steered"
+        ? "completed (steered)"
+        : "completed";
+
+    // Line 1: icon + agent description + status
+    let line = `${icon} ${theme.bold(d.description)} ${theme.fg("dim", statusText)}`;
+
+    // Line 2: stats
+    const parts: string[] = [];
+    if (d.turnCount > 0) parts.push(formatTurns(d.turnCount, d.maxTurns));
+    if (d.toolUses > 0) parts.push(`${d.toolUses} tool use${d.toolUses === 1 ? "" : "s"}`);
+    if (d.totalTokens > 0) parts.push(formatTokens(d.totalTokens));
+    if (d.durationMs > 0) parts.push(formatMs(d.durationMs));
+    if (parts.length) {
+      line += "\n  " + parts.map((p) => theme.fg("dim", p)).join(" " + theme.fg("dim", "·") + " ");
+    }
+
+    // Line 3: result preview (collapsed) or full (expanded)
+    if (expanded) {
+      const lines = d.resultPreview.split("\n").slice(0, 30);
+      for (const l of lines) line += "\n" + theme.fg("dim", `  ${l}`);
+    } else {
+      const preview = d.resultPreview.split("\n")[0]?.slice(0, 80) ?? "";
+      line += "\n  " + theme.fg("dim", `⎿  ${preview}`);
+    }
+
+    // Line 4: output file link (if present)
+    if (d.outputFile) {
+      line += "\n  " + theme.fg("muted", `transcript: ${d.outputFile}`);
+    }
+
+    return new Text(line, 0, 0);
+  };
+}