@jopqior/pi-subagents 1.0.0

package/src/observation/record-observer.ts

@@ -0,0 +1,78 @@
+/**
+ * record-observer.ts — Subscribes to session events and accumulates SubagentState stats.
+ *
+ * Replaces the scattered callback-wrapping logic in SubagentManager's startAgent()
+ * and resume() with a single direct subscription. The observer targets the
+ * SubagentState value object directly, so it carries no dependency on Subagent;
+ * the caller forwards itself to its own lifecycle observer via onCompact.
+ */
+
+import type { SubagentState } from "#src/lifecycle/subagent-state";
+import type { CompactionInfo, SubscribableSession } from "#src/types";
+
+export interface SubagentObserverOptions {
+  onCompact?: (info: CompactionInfo) => void;
+}
+
+/**
+ * Subscribe to session events and accumulate stats on the subagent state.
+ *
+ * Handles:
+ * - `tool_execution_start` → `state.addActiveTool(name)`
+ * - `tool_execution_end` → `state.removeActiveTool(name)`, `state.incrementToolUses()`
+ * - `message_start` → `state.resetResponseText()`
+ * - `message_update` (text_delta) → `state.appendResponseText(delta)`
+ * - `message_end` (assistant, with usage) → `state.addUsage(…)`
+ * - `turn_end` → `state.incrementTurnCount()`
+ * - `compaction_end` (not aborted) → `state.incrementCompactions()`, call `onCompact`
+ *
+ * @returns An unsubscribe function.
+ */
+export function subscribeSubagentObserver(
+  session: SubscribableSession,
+  state: SubagentState,
+  options?: SubagentObserverOptions,
+): () => void {
+  return session.subscribe((event) => {
+    if (event.type === "tool_execution_start") {
+      state.addActiveTool(event.toolName);
+    }
+
+    if (event.type === "tool_execution_end") {
+      state.removeActiveTool(event.toolName);
+      state.incrementToolUses();
+    }
+
+    if (event.type === "message_start") {
+      state.resetResponseText();
+    }
+
+    if (
+      event.type === "message_update" &&
+      event.assistantMessageEvent.type === "text_delta"
+    ) {
+      state.appendResponseText(event.assistantMessageEvent.delta);
+    }
+
+    if (event.type === "turn_end") {
+      state.incrementTurnCount();
+    }
+
+    if (event.type === "message_end" && event.message.role === "assistant") {
+      const u = event.message.usage;
+      state.addUsage({
+        input: u.input,
+        output: u.output,
+        cacheWrite: u.cacheWrite,
+      });
+    }
+
+    if (event.type === "compaction_end" && !event.aborted && event.result) {
+      state.incrementCompactions();
+      options?.onCompact?.({
+        reason: event.reason,
+        tokensBefore: event.result.tokensBefore,
+      });
+    }
+  });
+}

package/src/observation/renderer.ts

@@ -0,0 +1,161 @@
+import { Text } from "@earendil-works/pi-tui";
+import {
+  isTerminalErrorStatus,
+  type SubagentStatus,
+} from "#src/lifecycle/subagent-state";
+import type {
+  NotificationDetails,
+  UpdateDetails,
+  WorkspaceNoticeDetails,
+} from "#src/observation/notification";
+import { formatMs, formatTokens, formatTurns } from "#src/ui/display";
+import { GLYPHS } from "#src/ui/glyphs";
+
+/** 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 message interface for the update renderer. */
+interface UpdateMessage {
+  details?: UpdateDetails;
+}
+
+/** Narrow message interface for the workspace-notice renderer. */
+interface WorkspaceNoticeMessage {
+  details?: WorkspaceNoticeDetails;
+}
+
+/** Narrow render options — only the fields the renderer reads. */
+interface RenderOptions {
+  expanded: boolean;
+}
+
+// ---- Pure helpers (exported for unit testing) ----
+
+/** Resolved status→presentation product: icon glyph/style and status label. */
+export interface StatusPresentation {
+  iconGlyph: string;
+  iconStyle: string;
+  statusText: string;
+}
+
+/** Decide the icon and status label for a notification's status, once. */
+export function resolveStatusPresentation(status: SubagentStatus): StatusPresentation {
+  if (isTerminalErrorStatus(status))
+    return { iconGlyph: GLYPHS.failure, iconStyle: "error", statusText: status };
+  const statusText = status === "steered" ? "completed (steered)" : "completed";
+  return { iconGlyph: GLYPHS.success, iconStyle: "success", statusText };
+}
+
+/** Fields `buildStatsParts` reads from a `NotificationDetails`. */
+type StatsSource = Pick<
+  NotificationDetails,
+  "turnCount" | "maxTurns" | "toolUses" | "totalTokens" | "durationMs"
+>;
+
+/** Assemble the stats-line parts (turns, tool uses, tokens, duration), omitting zero fields. */
+export function buildStatsParts(d: StatsSource): string[] {
+  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));
+  return parts;
+}
+
+/**
+ * Content lines for the result preview: the whole result (capped at 30 lines)
+ * when expanded, or just the first line (capped at 80 columns) when collapsed.
+ */
+export function buildPreviewLines(resultPreview: string, expanded: boolean): string[] {
+  if (expanded) return resultPreview.split("\n").slice(0, 30);
+  return [resultPreview.split("\n")[0]?.slice(0, 80) ?? ""];
+}
+
+/**
+ * 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 { iconGlyph, iconStyle, statusText } = resolveStatusPresentation(d.status);
+
+    // Line 1: icon + agent description + status
+    let line = `${theme.fg(iconStyle, iconGlyph)} ${theme.bold(d.description)} ${theme.fg("dim", statusText)}`;
+
+    // Line 2: stats
+    const parts = buildStatsParts(d);
+    if (parts.length) {
+      line += "\n  " + parts.map((p) => theme.fg("dim", p)).join(" " + theme.fg("dim", "·") + " ");
+    }
+
+    // Line 3: result preview (collapsed) or full (expanded)
+    const previewLines = buildPreviewLines(d.resultPreview, expanded);
+    if (expanded) {
+      for (const l of previewLines) line += "\n" + theme.fg("dim", `  ${l}`);
+    } else {
+      line += "\n  " + theme.fg("dim", `${GLYPHS.subLine}  ${previewLines[0] ?? ""}`);
+    }
+
+    // Line 4: output file link (if present)
+    if (d.outputFile) {
+      line += "\n  " + theme.fg("muted", `transcript: ${d.outputFile}`);
+    }
+
+    return new Text(line, 0, 0);
+  };
+}
+
+/**
+ * Create the mid-run update renderer for `pi.registerMessageRenderer`.
+ *
+ * Separate from the completion renderer because the agent has not finished:
+ * `resolveStatusPresentation` speaks only terminal statuses, so reusing it
+ * would draw a still-running child as completed.
+ */
+export function createUpdateRenderer() {
+  return (message: UpdateMessage, { expanded }: RenderOptions, theme: RendererTheme): Text | undefined => {
+    const d = message.details;
+    if (!d) return undefined;
+
+    let line = `${theme.fg("info", GLYPHS.agentsActive)} ${theme.bold(d.description)} ${theme.fg("dim", "update")}`;
+    for (const l of buildPreviewLines(d.message, expanded)) {
+      line += "\n  " + theme.fg("dim", expanded ? `  ${l}` : `${GLYPHS.subLine}  ${l}`);
+    }
+    return new Text(line, 0, 0);
+  };
+}
+
+/**
+ * Create the workspace-notice renderer for `pi.registerMessageRenderer`.
+ *
+ * Separate from the completion renderer because the agent's outcome was
+ * reported long ago and has not changed: this reports only what a teardown did
+ * with the child's work, so it carries no status, stats, or result preview.
+ */
+export function createWorkspaceNoticeRenderer() {
+  return (
+    message: WorkspaceNoticeMessage,
+    { expanded }: RenderOptions,
+    theme: RendererTheme,
+  ): Text | undefined => {
+    const d = message.details;
+    if (!d) return undefined;
+
+    let line = `${theme.fg("warning", GLYPHS.success)} ${theme.bold(d.description)} ${theme.fg("dim", "workspace")}`;
+    for (const l of buildPreviewLines(d.notice.trim(), expanded)) {
+      line += "\n  " + theme.fg("dim", expanded ? `  ${l}` : `${GLYPHS.subLine}  ${l}`);
+    }
+    return new Text(line, 0, 0);
+  };
+}

package/src/observation/subagent-events-observer.ts

@@ -0,0 +1,148 @@
+import type { SubagentManagerObserver } from "#src/lifecycle/subagent-manager";
+import { buildEventData, type NotificationSystem } from "#src/observation/notification";
+import type { CompactionInfo, Subagent } from "#src/types";
+
+/** Emit callback — a subset of `pi.events.emit`. */
+export type EventEmit = (channel: string, data: unknown) => void;
+
+/** Append callback — a subset of `pi.appendEntry`. */
+export type AppendEntry = (customType: string, data: unknown) => void;
+
+export interface SubagentEventsObserverDeps {
+	emit: EventEmit;
+	appendEntry: AppendEntry;
+	notifications: NotificationSystem;
+}
+
+/**
+ * Receives agent lifecycle notifications from SubagentManager and dispatches
+ * them to three concerns: pi.events lifecycle events, session-entry persistence,
+ * and completion notifications.
+ *
+ * Constructed with narrow deps (emit, appendEntry, NotificationSystem) so all
+ * three concerns are unit-testable without booting the extension.
+ */
+export class SubagentEventsObserver implements SubagentManagerObserver {
+	private readonly emit: EventEmit;
+	private readonly appendEntry: AppendEntry;
+	private readonly notifications: NotificationSystem;
+
+	constructor(deps: SubagentEventsObserverDeps) {
+		this.emit = deps.emit;
+		this.appendEntry = deps.appendEntry;
+		this.notifications = deps.notifications;
+	}
+
+	onSubagentStarted(record: Subagent): void {
+		// Emit started event when agent transitions to running (including from queue).
+		this.emit("subagents:started", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+		});
+	}
+
+	onSubagentCompleted(record: Subagent): void {
+		// Emit lifecycle event based on terminal status.
+		const isError = record.isTerminalError();
+		const eventData = buildEventData(record);
+		if (isError) {
+			this.emit("subagents:failed", eventData);
+		} else {
+			this.emit("subagents:completed", eventData);
+		}
+
+		this.persistAndNotify(record);
+	}
+
+	/**
+	 * A settled agent went back to running. Announced only, and on its own
+	 * channel: `subagents:started` reports the first run, and a consumer counting
+	 * it once per agent must not see it twice. Nothing is persisted — the session
+	 * entry records outcomes, and a run that has just begun is not one.
+	 */
+	onSubagentResuming(record: Subagent): void {
+		this.emit("subagents:resuming", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+		});
+	}
+
+	onSubagentResumed(record: Subagent): void {
+		// A resumed run terminates only as completed or error; a single distinct
+		// channel carries both — the payload's status/error discriminate. Existing
+		// subagents:completed/failed subscribers keep their once-per-run semantics.
+		this.emit("subagents:resumed", buildEventData(record));
+		this.persistAndNotify(record);
+	}
+
+	/**
+	 * Persist the terminal record for cross-extension history reconstruction and
+	 * announce completion. Shared by every terminal-state handler (fresh and
+	 * resumed). Whether a nudge is actually owed is the notification manager's
+	 * decision — it suppresses itself when a carrier has claimed the outcome or
+	 * the parent has already consumed it. Both are domain state on the record,
+	 * not owned here.
+	 */
+	private persistAndNotify(record: Subagent): void {
+		this.appendEntry("subagents:record", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+			status: record.status,
+			result: record.result,
+			error: record.error,
+			startedAt: record.startedAt,
+			completedAt: record.completedAt,
+		});
+		this.notifications.sendCompletion(record);
+	}
+
+	/**
+	 * A still-running child sent its parent a message. Announced, never
+	 * persisted: the session entry reconstructs terminal outcomes, and this is
+	 * not one.
+	 */
+	onSubagentUpdate(record: Subagent, message: string): void {
+		this.emit("subagents:update", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+			message,
+		});
+		this.notifications.sendUpdate(record, message);
+	}
+
+	/**
+	 * A teardown after the child's result was delivered reported where its work
+	 * went. Announced only: no event channel, because no consumer asks for one,
+	 * and nothing is persisted — the outcome this belongs to was recorded when
+	 * the run ended.
+	 */
+	onSubagentWorkspaceNotice(record: Subagent, notice: string): void {
+		this.notifications.sendWorkspaceNotice(record, notice);
+	}
+
+	onSubagentCompacted(record: Subagent, info: CompactionInfo): void {
+		// Emit compacted event when agent's session compacts (preserves count on record).
+		this.emit("subagents:compacted", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+			reason: info.reason,
+			tokensBefore: info.tokensBefore,
+			compactionCount: record.compactionCount,
+		});
+	}
+
+	onSubagentCreated(record: Subagent): void {
+		// Emit created event for background agents (before limiter admission).
+		this.emit("subagents:created", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+			isBackground: record.isBackground,
+		});
+	}
+}

package/src/runtime.ts

@@ -0,0 +1,137 @@
+/**
+ * runtime.ts — SubagentRuntime: composition root for all mutable extension state.
+ *
+ * Eliminates module-scope state in agent-runner.ts and closure-scoped state
+ * in index.ts by consolidating them into a single, testable object.
+ * Follows the same pattern as pi-permission-system's ExtensionRuntime.
+ */
+
+import {
+  buildParentSnapshot,
+  type ParentPromptOptions,
+  type ParentSnapshot,
+} from "#src/lifecycle/parent-snapshot";
+import type { SelectionScopeHandle } from "#src/lifecycle/selection-scope";
+import { SpawnSelectionScope } from "#src/lifecycle/spawn-selection";
+import type { SpawnSelectionProvider, SpawnSelectionRegistration } from "#src/service/service";
+import type { ModelInfo } from "#src/tools/spawn-config";
+import type { SessionContext } from "#src/types";
+
+/**
+ * Narrow config subset read by Agent when driving the turn loop (defaultMaxTurns, graceTurns).
+ * Kept separate so callers can satisfy it without depending on the full runtime.
+ */
+export interface RunConfig {
+  readonly defaultMaxTurns: number | undefined;
+  readonly graceTurns: number;
+  /** Whether a background child gets the `notify_parent` channel. */
+  readonly midRunUpdates: boolean;
+}
+
+/**
+ * All mutable state owned by the pi-subagents extension.
+ *
+ * Created once inside `piSubagentsExtension()` via `createSubagentRuntime()`.
+ * Tests construct a fresh runtime per test for full isolation.
+ */
+export class SubagentRuntime {
+  // ── Session state (was closure-scoped in index.ts) ───────────────────────
+  /** Active Pi session context — set on session_start, cleared on session_shutdown. */
+  currentCtx: SessionContext | undefined = undefined;
+
+  /**
+   * Prompt options Pi assembled for the parent's latest turn, captured from
+   * `before_agent_start`. Undefined until the parent has run one.
+   */
+  private lastPromptOptions: ParentPromptOptions | undefined = undefined;
+
+  // ── Spawn selection ─────────────────────────────────────────────────────────
+  /**
+   * The selection scope this runtime retains: an owned root scope when the
+   * factory found no ambient construction context, an inherited child handle
+   * when it did. Captured once at factory initialization — never re-read from
+   * ambient state later.
+   */
+  private readonly selectionScope: SelectionScopeHandle;
+
+  constructor(selectionScope?: SelectionScopeHandle) {
+    this.selectionScope = selectionScope ?? new SpawnSelectionScope();
+  }
+
+  /**
+   * Register a spawn-selection provider on the retained scope — `owned` on a
+   * root, `inherited` (nothing installed) on a descendant.
+   */
+  registerSpawnSelectionProvider(provider: SpawnSelectionProvider): SpawnSelectionRegistration {
+    return this.selectionScope.register(provider);
+  }
+
+  /**
+   * Close the retained scope: owner-aware — a root revokes its lease and every
+   * descendant handle; a child frees only its own subtree. First operation of
+   * session shutdown, before anything that could still be observed by a
+   * pending selection.
+   */
+  closeSelectionScope(): void {
+    this.selectionScope.close();
+  }
+
+  // ── Session-context methods ──────────────────────────────────────────────
+
+  /** Store the active Pi session context (called from session_start). */
+  setSessionContext(ctx: SessionContext): void {
+    this.currentCtx = ctx;
+  }
+
+  /** Clear the session context (called from session_shutdown). */
+  clearSessionContext(): void {
+    this.currentCtx = undefined;
+  }
+
+  /**
+   * Record the prompt options Pi assembled for the parent's latest turn.
+   *
+   * Captured from `before_agent_start`, which is the only event carrying them:
+   * `getSystemPromptOptions()` is attached to a command context, not to the
+   * session context this runtime holds.
+   */
+  setSystemPromptOptions(options: ParentPromptOptions): void {
+    this.lastPromptOptions = options;
+  }
+
+  /**
+   * Build a parent snapshot from the current session context.
+   * Only valid during an active session (currentCtx is defined).
+   */
+  buildSnapshot(inheritContext: boolean): ParentSnapshot {
+
+    return buildParentSnapshot(this.currentCtx!, inheritContext, this.lastPromptOptions);
+  }
+
+  /** Extract model info from the current session context. */
+  getModelInfo(): ModelInfo {
+    return {
+      parentModel: this.currentCtx?.model,
+      modelRegistry: this.currentCtx?.modelRegistry,
+    };
+  }
+
+  /** Extract session identity from the current session context. */
+  getSessionInfo(): { parentSessionFile: string; parentSessionId: string } {
+    return {
+      parentSessionFile: this.currentCtx?.sessionManager.getSessionFile() ?? "",
+      parentSessionId: this.currentCtx?.sessionManager.getSessionId() ?? "",
+    };
+  }
+}
+
+/**
+ * Create a fully-initialized SubagentRuntime.
+ *
+ * Call once at extension startup with the captured selection scope (a root
+ * lease here, an inherited handle in a child); pass the result to factories
+ * and handlers.
+ */
+export function createSubagentRuntime(selectionScope?: SelectionScopeHandle): SubagentRuntime {
+  return new SubagentRuntime(selectionScope);
+}