@gotgenes/pi-subagents 5.7.0 → 5.8.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.8.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.7.0...pi-subagents-v5.8.0) (2026-05-20)
+
+
+### Features
+
+* add SessionLifecycleHandler ([d8d95fa](https://github.com/gotgenes/pi-packages/commit/d8d95fa92561e0068444c3c925f21b50825a741c))
+* add ToolStartHandler ([c293e41](https://github.com/gotgenes/pi-packages/commit/c293e41e25d9742f807f85d0efe0a0e5605b29a6))
+
+
+### Documentation
+
+* **retro:** add retro notes for issue [#87](https://github.com/gotgenes/pi-packages/issues/87) ([1701fe4](https://github.com/gotgenes/pi-packages/commit/1701fe41d582d7180b2622c2e03db954e8d2c2af))
+
 ## [5.7.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.6.0...pi-subagents-v5.7.0) (2026-05-20)
 
 

package/docs/retro/0087-evolve-subagent-runtime-methods.md

@@ -0,0 +1,42 @@
+---
+issue: 87
+issue_title: "refactor: evolve SubagentRuntime from data bag to object with methods"
+---
+
+# Retro: #87 — evolve SubagentRuntime from data bag to object with methods
+
+## Final Retrospective (2026-05-20T18:00:00Z)
+
+### Session summary
+
+Planned, implemented, and shipped #87 — converting `SubagentRuntime` from a plain interface + factory into a class with session-context methods (`setSessionContext`, `clearSessionContext`) and widget delegation methods (`setUICtx`, `onTurnStart`, `markFinished`, `updateWidget`, `ensureTimer`).
+All 10 call sites in `index.ts` were migrated, eliminating raw `currentCtx` field writes and `runtime.widget!` reach-throughs.
+Released as `pi-subagents-v5.7.0`.
+
+### Observations
+
+#### What went well
+
+- The 3-step TDD cycle executed cleanly with zero rework or deviations from the plan.
+  Test count went from 5 → 16 in `runtime.test.ts`; all 512 package tests stayed green throughout.
+- The user identified a missing architecture update and a pre-existing hallucination (`@earendil-works/pi-subagents` → `@gotgenes/pi-subagents`) after the plan commit.
+  The fix was a single well-scoped commit (`ddee1a0`) that corrected 10 scope references, updated the dependency graph to include #87 as a precursor to #70, and fixed list numbering per phase heading.
+- The plan's "Call sites to migrate" tables with exact line numbers and before/after code made step 3 (the refactoring commit) purely mechanical — no design decisions at implementation time.
+
+#### What caused friction (agent side)
+
+- `missing-context` — In TDD step 2, the new `describe` block used `vi.fn()` but the test file's import was `{ describe, expect, it }` without `vi`.
+  The first red run surfaced this immediately (`ReferenceError: vi is not defined`) and it was fixed before the green step.
+  Impact: one extra test run, no rework commits.
+- `scope-drift` — The `/plan-issue` prompt does not instruct updating `architecture.md`, but the user noticed #87 was missing from the roadmap's dependency graph.
+  The agent hadn't checked `architecture.md` during planning even though #87 is explicitly listed as a precursor to #70 in the #70 plan.
+  Impact: user-caught; required a follow-up edit pass after the plan commit.
+
+#### What caused friction (user side)
+
+No friction observed.
+The user's correction about `architecture.md` was well-targeted and caught a real gap.
+
+### Changes made
+
+1. Retro file created at `packages/pi-subagents/docs/retro/0087-evolve-subagent-runtime-methods.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "5.7.0",
+  "version": "5.8.0",
   "exports": {
     ".": "./src/service.ts"
   },

package/src/handlers/index.ts

@@ -0,0 +1,6 @@
+export {
+  type LifecycleManager,
+  type LifecycleRuntime,
+  SessionLifecycleHandler,
+} from "./lifecycle.js";
+export { ToolStartHandler, type ToolStartRuntime } from "./tool-start.js";

package/src/handlers/lifecycle.ts

@@ -0,0 +1,62 @@
+/**
+ * Session lifecycle event handlers: session_start, session_before_switch, session_shutdown.
+ *
+ * Extracted from index.ts so each handler can be tested in isolation
+ * with mocked narrow interfaces.
+ */
+
+/** Narrow manager interface — only the methods lifecycle handlers call. */
+export interface LifecycleManager {
+  clearCompleted(): void;
+  abortAll(): void;
+  dispose(): void;
+}
+
+/** Narrow runtime interface — only the methods lifecycle handlers call. */
+export interface LifecycleRuntime {
+  setSessionContext(pi: unknown, ctx: unknown): void;
+  clearSessionContext(): void;
+}
+
+/**
+ * Handles session lifecycle events.
+ *
+ * Constructor deps:
+ * - `pi` — the ExtensionAPI instance, stored in runtime on session_start
+ * - `runtime` — owns session context state
+ * - `manager` — manages agent lifecycle (clear, abort, dispose)
+ * - `disposeNotifications` — tears down the notification system on shutdown
+ * - `unpublishService` — unpublishes the SubagentsService symbol on shutdown
+ */
+export class SessionLifecycleHandler {
+  constructor(
+    private readonly pi: unknown,
+    private readonly runtime: LifecycleRuntime,
+    private readonly manager: LifecycleManager,
+    private readonly disposeNotifications: () => void,
+    private readonly unpublishService: () => void,
+  ) {}
+
+  handleSessionStart(_event: unknown, ctx: unknown): void {
+    this.runtime.setSessionContext(this.pi, ctx);
+    this.manager.clearCompleted();
+  }
+
+  handleSessionBeforeSwitch(): void {
+    this.manager.clearCompleted();
+  }
+
+  // Cleanup order matters:
+  // 1. Unpublish service — prevent new cross-extension calls
+  // 2. Clear session context — no more session state
+  // 3. Abort all agents — stop running work
+  // 4. Dispose notifications — cancel pending nudges/timers
+  // 5. Dispose manager — final cleanup
+  async handleSessionShutdown(): Promise<void> {
+    this.unpublishService();
+    this.runtime.clearSessionContext();
+    this.manager.abortAll();
+    this.disposeNotifications();
+    this.manager.dispose();
+  }
+}

package/src/handlers/tool-start.ts

@@ -0,0 +1,32 @@
+/**
+ * tool_execution_start event handler.
+ *
+ * Extracted from index.ts so the handler can be tested in isolation
+ * with a mocked narrow runtime interface.
+ */
+
+/** Narrow runtime interface — only the widget-delegation methods the handler calls. */
+export interface ToolStartRuntime {
+  setUICtx(ctx: unknown): void;
+  onTurnStart(): void;
+}
+
+/** Minimal context shape for tool_execution_start — only the field the handler reads. */
+interface ToolStartCtx {
+  ui: unknown;
+}
+
+/**
+ * Handles tool_execution_start events.
+ *
+ * Grabs UI context from the first tool execution of each turn
+ * and signals the widget to clear lingering state.
+ */
+export class ToolStartHandler {
+  constructor(private readonly runtime: ToolStartRuntime) {}
+
+  handleToolExecutionStart(_event: unknown, ctx: ToolStartCtx): void {
+    this.runtime.setUICtx(ctx.ui);
+    this.runtime.onTurnStart();
+  }
+}

package/src/index.ts

@@ -16,6 +16,7 @@ import { AgentManager } from "./agent-manager.js";
 import { getAgentConversation, normalizeMaxTurns, resumeAgent, runAgent, steerAgent } from "./agent-runner.js";
 import { getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveAgentConfig, } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
+import { SessionLifecycleHandler, ToolStartHandler } from "./handlers/index.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
 import { buildEventData, createNotificationSystem } from "./notification.js";
 import { createNotificationRenderer } from "./renderer.js";
@@ -122,33 +123,24 @@ export default function (pi: ExtensionAPI) {
   });
   publishSubagentsService(service);
 
-  pi.on("session_start", async (_event, ctx) => {
-    runtime.setSessionContext(pi, ctx);
-    manager.clearCompleted();
-  });
-
-  pi.on("session_before_switch", () => {
-    manager.clearCompleted();
-  });
+  const lifecycle = new SessionLifecycleHandler(
+    pi,
+    runtime,
+    manager,
+    () => notifications.dispose(),
+    unpublishSubagentsService,
+  );
 
-  // On shutdown, abort all agents immediately and clean up.
-  // If the session is going down, there's nothing left to consume agent results.
-  pi.on("session_shutdown", async () => {
-    unpublishSubagentsService();
-    runtime.clearSessionContext();
-    manager.abortAll();
-    notifications.dispose();
-    manager.dispose();
-  });
+  pi.on("session_start", (event, ctx) => lifecycle.handleSessionStart(event, ctx));
+  pi.on("session_before_switch", () => lifecycle.handleSessionBeforeSwitch());
+  pi.on("session_shutdown", () => lifecycle.handleSessionShutdown());
 
   // Live widget: show running agents above editor
   runtime.widget = new AgentWidget(manager, runtime.agentActivity);
 
   // Grab UI context from first tool execution + clear lingering widget on new turn
-  pi.on("tool_execution_start", async (_event, ctx) => {
-    runtime.setUICtx(ctx.ui as UICtx);
-    runtime.onTurnStart();
-  });
+  const toolStart = new ToolStartHandler(runtime);
+  pi.on("tool_execution_start", (event, ctx) => toolStart.handleToolExecutionStart(event, ctx));
 
   /** Build the full type list text dynamically from the unified registry. */
   const buildTypeListText = () => {