@gotgenes/pi-subagents 7.0.0 → 7.1.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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).
 
+## [7.1.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.0.0...pi-subagents-v7.1.0) (2026-05-24)
+
+
+### Features
+
+* **pi-subagents:** define SessionContext narrow interface ([#192](https://github.com/gotgenes/pi-packages/issues/192)) ([a043d4d](https://github.com/gotgenes/pi-packages/commit/a043d4d970a8aacc084a125d9a07b860a7fb6e9b))
+
+
+### Documentation
+
+* **pi-subagents:** archive Phase 10, propose Phase 11 roadmap ([d474eef](https://github.com/gotgenes/pi-packages/commit/d474eef98c1a39757d933da291725ff126f1b8ac))
+* **pi-subagents:** revise Phase 11 roadmap — layered class conversion ([35d1083](https://github.com/gotgenes/pi-packages/commit/35d1083445aece783e344c37fc949395e190f9e5))
+* plan SessionContext narrow interface ([#192](https://github.com/gotgenes/pi-packages/issues/192)) ([95cb16e](https://github.com/gotgenes/pi-packages/commit/95cb16e46aa630ecc34f423aaaa4ff02845ed5b5))
+* **retro:** add planning stage notes for issue [#192](https://github.com/gotgenes/pi-packages/issues/192) ([31fd729](https://github.com/gotgenes/pi-packages/commit/31fd7290985b0ef1d240cd5afd5e0e0e7eec9131))
+* **retro:** add retro notes for issue [#185](https://github.com/gotgenes/pi-packages/issues/185) ([66e49cf](https://github.com/gotgenes/pi-packages/commit/66e49cfb4129b9bba3b78e0850402bc61d99dda8))
+* **retro:** add TDD stage notes for issue [#192](https://github.com/gotgenes/pi-packages/issues/192) ([6cf3f95](https://github.com/gotgenes/pi-packages/commit/6cf3f95f6c39f3f81c1d335348d5abd74d948ff3))
+
 ## [7.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.19.1...pi-subagents-v7.0.0) (2026-05-24)
 
 

package/docs/architecture/architecture.md

@@ -314,16 +314,16 @@ The widget reads agent state by polling a shared `Map<string, AgentActivityTrack
 
 ```mermaid
 flowchart TD
-    subgraph core["@gotgenes/pi-subagents (this package)"]
+    subgraph core["@gotgenes/pi-subagents"]
         direction TB
-        exports["SubagentsService interface\npublish / getSubagentsService()\nSubagentRecord, SubagentStatus, LifetimeUsage\nSUBAGENT_EVENTS constants"]
-        engine["Agent + get_subagent_result + steer_subagent tools\nAgentManager, agent-runner, agent-types\npublishSubagentsService() called at init"]
-        ui_int["Internal UI: widget, viewer, /agents menu\n(candidate for extraction to pi-subagents-ui)"]
+        exports["SubagentsService API<br/>publish / getSubagentsService<br/>SubagentRecord, SubagentStatus"]
+        engine["Tools: Agent, get_subagent_result,<br/>steer_subagent<br/>AgentManager, agent-runner"]
+        ui_int["Internal UI: widget, viewer,<br/>/agents menu"]
     end
 
-    core -- "Symbol.for() on globalThis" --> sched["scheduling extension\n(hypothetical)"]
-    core -- "Symbol.for() on globalThis" --> subui["pi-subagents-ui\n(deferred)"]
-    core -- "Symbol.for() on globalThis" --> future["any future extension"]
+    core -- "Symbol.for on globalThis" --> sched["scheduling extension<br/>(hypothetical)"]
+    core -- "Symbol.for on globalThis" --> subui["pi-subagents-ui<br/>(deferred)"]
+    core -- "Symbol.for on globalThis" --> future["any future extension"]
 ```
 
 Consumers call `getSubagentsService()?.spawn(...)` at runtime.
@@ -599,121 +599,218 @@ export type RunnerIO = EnvironmentIO & SessionFactoryIO;
 `RunnerIO` is kept as a type alias for the intersection.
 All existing consumers satisfy both sub-interfaces via structural typing with no call-site changes.
 
-## Improvement roadmap (Phase 10)
+## Improvement roadmap (Phase 11)
 
-Phase 10 addresses the structural gaps identified in this analysis: flat code organization, oversized dependency bags, and complexity hotspots.
+Phase 11 converts closure factories to classes, eliminating the adapter closure density in `index.ts` (the package's #1 churn hotspot: 128 commits, accelerating, fan-out 25).
+The approach is layered: each step makes the next step trivial.
 
-### Step 1: Reorganize source into domain directories ([#164][164]) ✓ Done
+> "Make the change that makes the change easy." —Kent Beck
 
-Moved files into `config/`, `session/`, `lifecycle/`, `observation/`, and `service/` subdirectories.
-All `src/` internal imports now use `#src/` path aliases (same style as `test/` files), eliminating relative depth arithmetic for future moves.
+### Findings
 
-- Domain model is now visible in the filesystem.
-- Root reduced to 5 files + 8 directories (was 31 files + 3 directories).
-- All subsequent steps can move or extract files without `../` import churn.
+| Metric                    | Value                                   |
+| ------------------------- | --------------------------------------- |
+| Health score              | 75/100 (B)                              |
+| #1 hotspot                | `index.ts` (128 commits, accelerating)  |
+| Dead exports              | 1 (`getToolCallName` re-export)         |
+| Production duplication    | 0                                       |
+| Test duplication          | 1,396 lines (69 clone groups, 22 files) |
+| `as any` casts in index   | 5                                       |
+| Adapter closures in index | 44                                      |
+| Index fan-out             | 25 imports                              |
 
-### Step 2: Decompose ResolvedSpawnConfig ([#165][165])
+### Root cause
 
-Split the 15-field bag into `SpawnIdentity`, `SpawnExecution`, and `SpawnPresentation`.
-Each consumer declares its real dependencies.
-Enables Step 3 (narrowing AgentSpawnConfig, [#166][166]).
+The 44 adapter closures in `index.ts` exist because the tool factories accept narrow interfaces that don't structurally match the real objects.
+The real objects can't satisfy the interfaces because:
 
-### Step 3: Extract ParentSessionInfo from AgentSpawnConfig ([#166][166]) — Complete
+1. `SubagentRuntime.currentCtx` is typed `{ pi: unknown; ctx: unknown }` — so every consumer must `as any` cast to read fields.
+2. Context queries (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) live as closures in index.ts instead of methods on the state holder.
+3. `AgentToolManager` mixes fields from `AgentManager` and `SettingsManager` (source mismatch).
+4. `AgentToolWidget` uses different method names than `SubagentRuntime` (name mismatch).
 
-Extracted `parentSessionFile`, `parentSessionId`, `toolCallId` into `ParentSessionInfo`.
-`AgentSpawnConfig`, `BackgroundParams`, `ForegroundParams`, and `RunOptions` all carry the nested group.
+Fix these structural misalignments and the class conversions become mechanical.
 
-### Step 4: Narrow RunnerIO ([#167][167]) ✓ Done
+### Layer 0: Define `SessionContext` narrow interface ([#192][192])
 
-`RunnerIO` split into `EnvironmentIO` (3 methods: environment discovery) and `SessionFactoryIO` (5 methods + `assemblerIO`: SDK object creation).
-`RunnerIO` kept as a backward-compatible type alias for the intersection.
-All existing consumers satisfy both sub-interfaces via structural typing with no call-site changes.
+`SubagentRuntime` currently types its context as `unknown` to avoid SDK coupling.
+But `ExtensionContext` is exported by the SDK — the `unknown` is a historical choice, not a constraint.
+Define a narrow `SessionContext` interface capturing the 5 fields runtime actually needs:
 
-### Step 5: Extract ToolFilterConfig from SessionConfig ([#168][168]) ✓ Done
+```typescript
+export interface SessionContext {
+  readonly cwd: string;
+  readonly model: unknown;
+  readonly modelRegistry: ModelRegistry | undefined;
+  getSystemPrompt(): string;
+  readonly sessionManager: {
+    getSessionFile(): string | undefined;
+    getSessionId(): string;
+    getBranch(): unknown[];
+  };
+}
+```
 
-`ToolFilterConfig` extracted from `SessionConfig`, grouping `toolNames`, `disallowedSet`, and `extensions`.
-`filterActiveTools` now accepts a single `ToolFilterConfig` argument.
-`SessionConfig` reduced from 10 to 8 top-level fields.
+- Target: `src/types.ts`
+- Smell: Category C (platform type threading)
+- Outcome: typed foundation for Layers 1–4; no `as any` needed by consumers of `SubagentRuntime`
+
+### Layer 1: `SubagentRuntime` stores typed context, owns its queries ([#193][193])
+
+Change `currentCtx` from `{ pi: unknown; ctx: unknown }` to `SessionContext | undefined`.
+The single `as SessionContext` cast moves into `handleSessionStart` — the boundary where the SDK hands us the value.
+Add typed methods: `buildSnapshot(inheritContext)`, `getModelInfo()`, `getSessionInfo()`.
+
+- Target: `src/runtime.ts`, `src/handlers/lifecycle.ts`
+- Smell: Category C (closure queries on mutable field → methods on state owner)
+- Outcome: 3 closure queries in index.ts → 0; `SubagentRuntime` is self-sufficient for tool deps
+- Enables: Layer 3 (tools accept `SubagentRuntime` directly)
+
+### Layer 2: Align interfaces so real objects satisfy tool deps structurally ([#194][194])
 
-### Step 6: Extract RunContext from RunOptions ([#169][169]) ✓ Done
+Three alignment changes:
 
-Extracted `exec`, `registry`, `cwd`, and `parentSession` into `RunContext`, nested as `RunOptions.context`.
-`RunOptions` reduced from 12 to 9 fields (1 nested `context` + 8 flat execution fields).
+1. **Move `getMaxConcurrent` off `AgentToolManager`** — it reads from `SettingsManager`, not `AgentManager`.
+   The tool already receives `settings`; read it from there.
+2. **Rename widget methods** — align `SubagentRuntime` method names with `AgentToolWidget` (either rename `updateWidget()` → `update()` on runtime, or rename the interface to match).
+3. **Remove dead re-export** — `getToolCallName` in `ui/message-formatters.ts` (fallow finding).
 
-### Step 7: Reduce buildContentLines complexity ([#170][170]) ✓ Done
+After this step, `AgentManager` structurally satisfies `AgentToolManager` and `SubagentRuntime` structurally satisfies `AgentToolWidget`.
 
-Extracted formatting sub-functions for each content type (user, assistant, tool result, bash execution, streaming indicator) into `ui/message-formatters.ts`.
-`buildContentLines` in `conversation-viewer.ts` is now a ~30-line dispatch loop delegating to `formatMessage` and `formatStreamingIndicator`.
+- Target: `src/tools/agent-tool.ts` (interface), `src/runtime.ts` (method names), `src/ui/message-formatters.ts`
+- Smell: Category C (source mismatch, name mismatch) + Category A (dead export)
+- Outcome: structural typing connects real objects to tool interfaces without adapters
+- Enables: Layer 3 (class constructors accept real objects directly)
 
-### Step 8: Reduce renderResult complexity ([#171][171]) ✓ Done
+### Layer 3: Convert closure factories to classes ([#195][195], [#196][196])
 
-Extracted per-status result formatting from `renderResult` in `agent-tool.ts` into `tools/result-renderer.ts`.
-`renderResult` reduced from ~80 lines (cognitive complexity 43) to a 10-line guard + `renderAgentResult` dispatcher.
-The inline `stats()` closure became the exported `renderStats` helper, shared by all status renderers.
+With Layers 0–2 complete, each factory is a mechanical conversion:
 
-### Step 9: Extract shared turn-formatting logic ([#172][172]) ✓ Done
+| Factory                          | Class                          | Constructor params                                  |
+| -------------------------------- | ------------------------------ | --------------------------------------------------- |
+| `createAgentTool({...})`         | `AgentTool`                    | `manager`, `runtime`, `settings`, `registry`        |
+| `createGetResultTool(...)`       | `GetResultTool`                | `manager`, `notifications`, `registry`              |
+| `createSteerTool(...)`           | `SteerTool`                    | `manager`, `events`                                 |
+| `createAgentRunner(runnerIO)`    | `AgentRunner` (concrete class) | `io: RunnerIO`                                      |
+| `createAgentsMenuHandler({...})` | `AgentsMenuHandler`            | `manager`, `registry`, `settings`, `fileOps`, paths |
 
-Extracted `ToolCallContent`, `getToolCallName`, and `extractAssistantContent` into `session/content-items.ts`.
-Both `lifecycle/agent-runner.ts` (`getAgentConversation`) and `ui/message-formatters.ts` (`formatAssistantMessage`) now import from the shared module.
-Eliminates the 18-line production-duplication finding.
+Each class satisfies the existing interface via structural typing.
+The `defineTool()` wrapper moves into a `toToolDefinition()` method on each tool class.
+
+- Target: `src/tools/*.ts`, `src/lifecycle/agent-runner.ts`, `src/ui/agent-menu.ts`
+- Smell: Category C (closure factories masquerading as classes)
+- Outcome: deps are constructor params (inspectable, testable); no captured closures
+- Enables: Layer 4 (index.ts simplification)
+
+### Layer 4: Simplify index.ts (included in [#196][196])
+
+With real objects satisfying tool interfaces and queries living on `SubagentRuntime`, the composition root becomes pure construction:
+
+```typescript
+const runtime = new SubagentRuntime();
+const settings = new SettingsManager(...);
+const manager = new AgentManager(...);
+const agentTool = new AgentTool(manager, runtime, settings, registry);
+pi.registerTool(agentTool.toToolDefinition());
+```
+
+No adapter closures.
+No `as any`.
+Fan-out drops from 25 to ~15 (internal factories eliminated).
+
+- Target: `src/index.ts`
+- Smell: Category B (god file) + Category C (adapter closure density)
+- Outcome: index.ts shrinks from 280 to ~150 lines; churn hotspot stabilizes
 
 ### Step dependencies
 
 ```mermaid
 flowchart LR
-    subgraph organization["Code organization"]
-        S1["#164: Domain directories"]
-    end
-    subgraph bags["Dependency bags"]
-        S2["#165: ResolvedSpawnConfig"] --> S3["#166: AgentSpawnConfig"]
-        S4["#167: RunnerIO"]
-        S5["#168: SessionConfig"]
-        S6["#169: RunOptions"]
-    end
-    subgraph complexity["Complexity reduction"]
-        S7["#170: buildContentLines"]
-        S8["#171: renderResult"]
-        S9["#172: Shared turn-formatting"]
-    end
-    S1 --> S2 & S4 & S5 & S6
-    S1 --> S7 & S8 & S9
+    L0["Layer 0: SessionContext interface"] --> L1["Layer 1: Runtime owns queries"]
+    L1 --> L3["Layer 3: Classes replace factories"]
+    L2["Layer 2: Align interfaces"] --> L3
+    L3 --> L4["Layer 4: Simplify index.ts"]
 ```
 
-Step 1 ([#164][164], directory restructuring) unblocks all other steps by co-locating related files.
-Steps 2–6 (bag decomposition) and Steps 7–9 (complexity reduction) are independent tracks that can proceed in parallel.
-Within the bag track, Step 2 ([#165][165], ResolvedSpawnConfig) enables Step 3 ([#166][166], AgentSpawnConfig).
+Layers 0 and 2 are independent of each other.
+Layer 1 depends on Layer 0.
+Layer 3 depends on both Layer 1 and Layer 2.
+Layer 4 depends on Layer 3.
+
+## Improvement roadmap (Phase 12)
+
+Phase 12 addresses the remaining fallow refactoring targets and test duplication.
+These are independent of Phase 11 and can proceed in parallel if desired.
+
+### Step 1: Decompose `renderWidgetLines` (cognitive 44)
+
+`renderWidgetLines` in `ui/widget-renderer.ts` handles agent-status formatting, tree connectors, overflow, and empty states.
+Extract per-status renderers and a tree-connector utility.
+
+- Target: `src/ui/widget-renderer.ts`
+- Outcome: cognitive complexity < 10
+
+### Step 2: Decompose `showAgentDetail` (cognitive 33)
+
+`showAgentDetail` in `ui/agent-config-editor.ts` handles display, edit, eject, and delete flows.
+Extract sub-functions per menu action.
+
+- Target: `src/ui/agent-config-editor.ts`
+- Outcome: cognitive complexity < 10
+
+### Step 3: Decompose `update` in `agent-widget.ts` (cognitive 31)
+
+`update` mixes timer lifecycle, agent list assembly, render delegation, and visibility state.
+Extract `assembleWidgetState` (pure) and timer management.
+
+- Target: `src/ui/agent-widget.ts`
+- Outcome: cognitive complexity < 10
+
+### Step 4: Extract shared test fixtures
+
+The 3 heaviest clone families:
+
+- `agent-runner.test.ts` + `agent-runner-extension-tools.test.ts` (60-line shared setup)
+- `agent-menu.test.ts` + `agent-creation-wizard.test.ts` + `agent-config-editor.test.ts` (54+51+24 lines)
+- `agent-manager.test.ts` (18 internal clone groups, 210 duplicated lines)
+
+Extract shared factories into `test/fixtures/` modules.
+
+- Target: new `test/fixtures/` modules
+- Outcome: test duplication reduced by ~400 lines
 
 ## Refactoring history
 
-Phases 1–5 and 7–9 are complete.
+Phases 1–5 and 7–10 are complete.
 Phase 6 (UI extraction to a separate package) is deferred.
 Detailed records are preserved in per-phase history files:
 
-| Phase | Title                                               | Status   | History                                                                    |
-| ----- | --------------------------------------------------- | -------- | -------------------------------------------------------------------------- |
-| 1     | Export SubagentsService API boundary                | Complete | [phase-1-api-boundary.md](history/phase-1-api-boundary.md)                 |
-| 2     | Remove scheduling subsystem                         | Complete | [phase-2-remove-scheduling.md](history/phase-2-remove-scheduling.md)       |
-| 3     | Remove group-join, RPC; replace output-file         | Complete | [phase-3-remove-rpc-groupjoin.md](history/phase-3-remove-rpc-groupjoin.md) |
-| 4     | Implement and publish SubagentsService              | Complete | [phase-4-implement-service.md](history/phase-4-implement-service.md)       |
-| 5     | Decompose index.ts                                  | Complete | [phase-5-decompose-index.md](history/phase-5-decompose-index.md)           |
-| 6     | Extract UI to separate package                      | Deferred | —                                                                          |
-| 7     | Encapsulation and dependency narrowing              | Complete | [phase-7-encapsulation.md](history/phase-7-encapsulation.md)               |
-| 8     | Testability, display extraction, menu decomposition | Complete | [phase-8-testability.md](history/phase-8-testability.md)                   |
-| 9     | Observation consolidation, ctx elimination          | Complete | [phase-9-observation-ctx.md](history/phase-9-observation-ctx.md)           |
+| Phase | Title                                               | Status   | History                                                                              |
+| ----- | --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------ |
+| 1     | Export SubagentsService API boundary                | Complete | [phase-1-api-boundary.md](history/phase-1-api-boundary.md)                           |
+| 2     | Remove scheduling subsystem                         | Complete | [phase-2-remove-scheduling.md](history/phase-2-remove-scheduling.md)                 |
+| 3     | Remove group-join, RPC; replace output-file         | Complete | [phase-3-remove-rpc-groupjoin.md](history/phase-3-remove-rpc-groupjoin.md)           |
+| 4     | Implement and publish SubagentsService              | Complete | [phase-4-implement-service.md](history/phase-4-implement-service.md)                 |
+| 5     | Decompose index.ts                                  | Complete | [phase-5-decompose-index.md](history/phase-5-decompose-index.md)                     |
+| 6     | Extract UI to separate package                      | Deferred | —                                                                                    |
+| 7     | Encapsulation and dependency narrowing              | Complete | [phase-7-encapsulation.md](history/phase-7-encapsulation.md)                         |
+| 8     | Testability, display extraction, menu decomposition | Complete | [phase-8-testability.md](history/phase-8-testability.md)                             |
+| 9     | Observation consolidation, ctx elimination          | Complete | [phase-9-observation-ctx.md](history/phase-9-observation-ctx.md)                     |
+| 10    | Domain organization, bag decomposition, complexity  | Complete | [phase-10-structural-decomposition.md](history/phase-10-structural-decomposition.md) |
 
 ### Structural refactoring issues
 
-| Phase              | Issue                                                      | Summary                                                                                                                        |
-| ------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| Foundation         | #69, #71, #76, #80                                         | SubagentRuntime, pure assembler, cwd injection, config consolidation                                                           |
-| Core decomposition | #84, #72, #87, #70                                         | WorktreeManager, AgentManager DI, runtime methods, handler extraction                                                          |
-| Interface polish   | #66, #77                                                   | SDK types, projectAgentsDir                                                                                                    |
-| Features           | #61                                                        | JSONL session transcripts                                                                                                      |
-| AgentManager       | #98, #99, #100, #102                                       | Record state machine, ParentSnapshot, session-event observation, test factory                                                  |
-| Encapsulation      | #108, #109, #110, #111, #112, #113, #114, #115, #116, #118 | Registry, settings, activity tracker, record lifecycle, observer, spawn options, deps narrowing, tool split, type housekeeping |
-| Testability        | #131, #132, #133, #134, #135, #136                         | Shared fixtures, session-config IO, runner SDK boundary, as-any reduction, display extraction, menu decomposition              |
-| Observation/ctx    | #144, #145, #146, #147, #148                               | Observation consolidation, execute decomposition, UI context, text wrapping injection, widget rendering split                  |
-| Phase 10           | #164, #166, #167, #168, #169, #170, #171                   | Domain directories, ParentSessionInfo, RunnerIO split, ToolFilterConfig, RunContext, buildContentLines, renderResult           |
+| Phase              | Issue                                                      | Summary                                                                                                                                                  |
+| ------------------ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Foundation         | #69, #71, #76, #80                                         | SubagentRuntime, pure assembler, cwd injection, config consolidation                                                                                     |
+| Core decomposition | #84, #72, #87, #70                                         | WorktreeManager, AgentManager DI, runtime methods, handler extraction                                                                                    |
+| Interface polish   | #66, #77                                                   | SDK types, projectAgentsDir                                                                                                                              |
+| Features           | #61                                                        | JSONL session transcripts                                                                                                                                |
+| AgentManager       | #98, #99, #100, #102                                       | Record state machine, ParentSnapshot, session-event observation, test factory                                                                            |
+| Encapsulation      | #108, #109, #110, #111, #112, #113, #114, #115, #116, #118 | Registry, settings, activity tracker, record lifecycle, observer, spawn options, deps narrowing, tool split, type housekeeping                           |
+| Testability        | #131, #132, #133, #134, #135, #136                         | Shared fixtures, session-config IO, runner SDK boundary, as-any reduction, display extraction, menu decomposition                                        |
+| Observation/ctx    | #144, #145, #146, #147, #148                               | Observation consolidation, execute decomposition, UI context, text wrapping injection, widget rendering split                                            |
+| Phase 10           | #164, #165, #166, #167, #168, #169, #170, #171, #172       | Domain directories, ResolvedSpawnConfig, ParentSessionInfo, RunnerIO split, ToolFilterConfig, RunContext, buildContentLines, renderResult, content-items |
 
 The remaining open issue is #22 (parent-session resolution), a cross-extension track that does not gate the structural work.
 
@@ -733,12 +830,12 @@ The upstream test suite is run periodically as a regression canary for the agent
 [gotgenes/pi-packages]: https://github.com/gotgenes/pi-packages
 [tintinweb/pi-subagents]: https://github.com/tintinweb/pi-subagents
 
-[164]: https://github.com/gotgenes/pi-packages/issues/164
-[165]: https://github.com/gotgenes/pi-packages/issues/165
 [166]: https://github.com/gotgenes/pi-packages/issues/166
 [167]: https://github.com/gotgenes/pi-packages/issues/167
 [168]: https://github.com/gotgenes/pi-packages/issues/168
 [169]: https://github.com/gotgenes/pi-packages/issues/169
-[170]: https://github.com/gotgenes/pi-packages/issues/170
-[171]: https://github.com/gotgenes/pi-packages/issues/171
-[172]: https://github.com/gotgenes/pi-packages/issues/172
+[192]: https://github.com/gotgenes/pi-packages/issues/192
+[193]: https://github.com/gotgenes/pi-packages/issues/193
+[194]: https://github.com/gotgenes/pi-packages/issues/194
+[195]: https://github.com/gotgenes/pi-packages/issues/195
+[196]: https://github.com/gotgenes/pi-packages/issues/196

package/docs/architecture/history/phase-10-structural-decomposition.md

@@ -0,0 +1,141 @@
+# Phase 10: Domain organization, bag decomposition, and complexity reduction
+
+Target: reorganize source into domain directories; decompose remaining wide parameter bags into focused value objects; reduce cyclomatic complexity in rendering functions; eliminate production code duplication.
+
+## Current smells
+
+| Smell                                                   | Location                                           | Evidence                                                                                                              | Severity |
+| ------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------- |
+| Flat `src/` directory                                   | `src/` root                                        | 20+ files in a single directory with no domain grouping; hard to see module boundaries                                | Medium   |
+| `ResolvedSpawnConfig` is a 15-field bag                 | `spawn-config.ts`                                  | Mixes identity (name, slug), execution (model, permissions), and presentation (icon, color) concerns in one interface | Medium   |
+| `AgentSpawnConfig` threads parent session fields        | `agent-manager.ts`                                 | `parentSessionFile`, `parentSessionId`, `toolCallId` always travel together but are separate parameters               | Low      |
+| `RunnerIO` is too wide                                  | `foreground-runner.ts`                             | 9 methods spanning environment concerns (cwd, env) and session factory concerns (create, attach, resume)              | Medium   |
+| `SessionConfig` mixes tool filtering with session setup | `session-config.ts`                                | `toolNames`, `disallowedSet`, `extensions` are a cohesive filter group buried in a larger config                      | Low      |
+| `RunOptions` is a 12-field bag                          | `foreground-runner.ts`                             | Mixes execution context (exec, registry, cwd) with per-run options (model, prompt, permissions)                       | Medium   |
+| `buildContentLines` high complexity                     | `ui/build-content-lines.ts`                        | ~60-line function with a switch over every content type; each branch is an independent formatter                      | Medium   |
+| `renderResult` high complexity                          | `tools/agent-tool.ts`                              | ~80-line function with status-based branching; each status is an independent rendering concern                        | Medium   |
+| Duplicated turn-formatting logic                        | `session/session-runner.ts`, `tools/agent-tool.ts` | 18 lines of identical `ToolCallContent` extraction and `getToolCallName` logic in two production files                | Low      |
+
+## Step 1: Reorganize source into domain directories (#164)
+
+Moved files into `config/`, `session/`, `lifecycle/`, `observation/`, and `service/` subdirectories.
+All `src/` internal imports now use `#src/` path aliases.
+Root `src/` reduced to 5 files + 8 directories.
+
+Impact: domain boundaries are visible in the directory tree; imports communicate intent via path alias.
+
+## Step 2: Decompose ResolvedSpawnConfig (#165)
+
+Split the 15-field `ResolvedSpawnConfig` into three focused value objects:
+
+- `SpawnIdentity` — name, slug, key
+- `SpawnExecution` — model, permissions, tools, prompt, systemPrompt
+- `SpawnPresentation` — icon, color, description
+
+`ResolvedSpawnConfig` composes these three plus the remaining spawn-level fields.
+
+Impact: each consumer receives only the fields it needs; adding a presentation field no longer touches execution code.
+
+## Step 3: Extract ParentSessionInfo from AgentSpawnConfig (#166)
+
+Extracted `parentSessionFile`, `parentSessionId`, and `toolCallId` into `ParentSessionInfo`.
+`AgentSpawnConfig` and `AgentManager.spawn()` accept the single value object instead of three separate parameters.
+
+Impact: eliminated parameter co-travel; the three fields that always move together are now a single concept.
+
+## Step 4: Narrow RunnerIO (#167)
+
+Split `RunnerIO` into two focused interfaces:
+
+- `EnvironmentIO` (3 methods) — cwd, env, platform concerns
+- `SessionFactoryIO` (5+1 methods) — create, attach, resume, and related session lifecycle
+
+`RunnerIO` kept as a backward-compatible type alias (`EnvironmentIO & SessionFactoryIO`).
+
+Impact: consumers declare which IO surface they actually need; test doubles shrink to the relevant subset.
+
+## Step 5: Extract ToolFilterConfig from SessionConfig (#168)
+
+Grouped `toolNames`, `disallowedSet`, and `extensions` into `ToolFilterConfig`.
+`filterActiveTools` accepts a single `ToolFilterConfig` argument instead of three separate parameters.
+
+Impact: tool-filtering concern is encapsulated; `SessionConfig` is narrower and more focused.
+
+## Step 6: Extract RunContext from RunOptions (#169)
+
+Extracted `exec`, `registry`, `cwd`, and `parentSession` into `RunContext`.
+`RunOptions` reduced from 12 fields to 9 (the 4 extracted fields replaced by a single `context` field, plus the remaining per-run options).
+
+Impact: execution context is a reusable value object; `RunOptions` focuses on per-run configuration.
+
+## Step 7: Reduce buildContentLines complexity (#170)
+
+Extracted per-content-type formatters into `ui/message-formatters.ts`.
+Each content type (text, tool-use, tool-result, image, etc.) has a dedicated pure function.
+`buildContentLines` is now a ~30-line dispatch loop that delegates to the appropriate formatter.
+
+Impact: cyclomatic complexity of `buildContentLines` dropped from ~15 to ~5; each formatter is independently testable.
+
+## Step 8: Reduce renderResult complexity (#171)
+
+Extracted per-status formatters into `tools/result-renderer.ts`.
+Each result status (success, error, timeout, cancelled) has a dedicated pure function.
+`renderResult` reduced from ~80 lines to a 10-line guard that dispatches to the appropriate renderer.
+
+Impact: cyclomatic complexity of `renderResult` dropped from ~10 to ~3; status rendering is independently testable.
+
+## Step 9: Extract shared turn-formatting logic (#172)
+
+Extracted `ToolCallContent`, `getToolCallName`, and `extractAssistantContent` into `session/content-items.ts`.
+Both `session/session-runner.ts` and `tools/agent-tool.ts` import from the shared module.
+
+Impact: eliminated 18 lines of production code duplication; single source of truth for turn-content extraction.
+
+## Step dependencies
+
+```mermaid
+flowchart LR
+    subgraph bag["Bag decomposition track"]
+        S2["2: Decompose ResolvedSpawnConfig #165"] --> S3["3: Extract ParentSessionInfo #166"]
+        S4["4: Narrow RunnerIO #167"]
+        S5["5: Extract ToolFilterConfig #168"]
+        S6["6: Extract RunContext #169"]
+    end
+    subgraph complexity["Complexity reduction track"]
+        S7["7: Reduce buildContentLines #170"]
+        S8["8: Reduce renderResult #171"]
+        S9["9: Extract turn-formatting #172"]
+    end
+    S1["1: Reorganize into domain dirs #164"] --> bag
+    S1 --> complexity
+```
+
+Step 1 unblocked all other steps.
+Within the bag decomposition track, Step 2 enabled Step 3.
+The bag decomposition and complexity reduction tracks were independent of each other.
+
+## Impact
+
+| Metric                         | Before                         | After                                         |
+| ------------------------------ | ------------------------------ | --------------------------------------------- |
+| Health score                   | ~65                            | 75                                            |
+| `src/` root files              | 20+                            | 5 files + 8 directories                       |
+| `ResolvedSpawnConfig` fields   | 15                             | 3 composed value objects                      |
+| `RunOptions` fields            | 12                             | 9                                             |
+| `RunnerIO` methods             | 9                              | 3 (`EnvironmentIO`) + 6 (`SessionFactoryIO`)  |
+| `buildContentLines` complexity | ~15                            | ~5                                            |
+| `renderResult` lines           | ~80                            | ~10                                           |
+| Production duplication         | 18 lines                       | 0                                             |
+| Test duplication               | ~1,400 lines (69 clone groups) | ~1,400 lines (69 clone groups) — not targeted |
+
+## Related issues
+
+- #164 — Reorganize source into domain directories
+- #165 — Decompose ResolvedSpawnConfig
+- #166 — Extract ParentSessionInfo from AgentSpawnConfig
+- #167 — Narrow RunnerIO
+- #168 — Extract ToolFilterConfig from SessionConfig
+- #169 — Extract RunContext from RunOptions
+- #170 — Reduce buildContentLines complexity
+- #171 — Reduce renderResult complexity
+- #172 — Extract shared turn-formatting logic

package/docs/plans/0192-define-session-context-interface.md

@@ -0,0 +1,107 @@
+---
+issue: 192
+issue_title: "Define SessionContext narrow interface"
+---
+
+# Define `SessionContext` narrow interface
+
+## Problem Statement
+
+`SubagentRuntime.currentCtx` is typed `{ pi: unknown; ctx: unknown }`.
+Every consumer must cast through `as any` to read fields from the SDK context.
+This forces context queries (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) to live as closures in `index.ts` with repeated `as any` casts, rather than as typed methods on the state holder.
+
+The SDK exports `ExtensionContext` — the `unknown` typing is a historical choice, not a constraint.
+
+## Goals
+
+- Define a narrow `SessionContext` interface in `src/types.ts` capturing the 5 fields `SubagentRuntime` actually reads.
+- Pure additive — no consumers change in this step.
+- Provide the typed foundation for Layer 1 (#193) and subsequent closure-to-class conversion issues.
+
+## Non-Goals
+
+- Changing `SubagentRuntime.currentCtx` type (that's #193).
+- Converting closure factories to classes (#195, #196).
+- Removing any `as any` casts from `index.ts` (that's #193).
+
+## Background
+
+Phase 11, Layer 0 in `docs/architecture/architecture.md`.
+This is the first step in a 5-issue sequence (issues #192–#196) that converts closure factories to classes, eliminating 44 adapter closures in `index.ts`.
+
+The SDK's `ExtensionContext` interface (in `@earendil-works/pi-coding-agent`) is broad — it exposes `ui`, `abort()`, `shutdown()`, `compact()`, etc.
+ISP (Interface Segregation Principle) from `code-design` mandates a narrow interface capturing only what `SubagentRuntime` needs.
+
+The 5 fields consumed by runtime (traced from `index.ts` lines 214–223 and `lifecycle/parent-snapshot.ts`):
+
+1. `cwd` — working directory for agent sessions.
+2. `model` — parent model instance for fallback resolution.
+3. `modelRegistry` — resolving config model strings.
+4. `getSystemPrompt()` — system prompt for append-mode agents.
+5. `sessionManager.getSessionFile()` / `.getSessionId()` / `.getBranch()` — session identification and context inheritance.
+
+The local `ModelRegistry` interface (in `src/session/model-resolver.ts`) already exists as a narrow ISP interface.
+`SessionContext` will reference it rather than redeclaring model-registry methods inline.
+
+## Design Overview
+
+```typescript
+import type { ModelRegistry } from "#src/session/model-resolver";
+
+/**
+ * Narrow interface capturing the 5 ExtensionContext fields SubagentRuntime needs.
+ * Avoids coupling runtime to the full SDK ExtensionContext surface.
+ */
+export interface SessionContext {
+  readonly cwd: string;
+  readonly model: unknown;
+  readonly modelRegistry: ModelRegistry | undefined;
+  getSystemPrompt(): string;
+  readonly sessionManager: {
+    getSessionFile(): string | undefined;
+    getSessionId(): string;
+    getBranch(): unknown[];
+  };
+}
+```
+
+Design decisions:
+
+1. `model` stays `unknown` — the runtime only passes it through to `resolveModel`; narrowing it gains nothing and would couple to `@earendil-works/pi-ai`'s `Model<Api>` generic.
+2. `modelRegistry` is `ModelRegistry | undefined` — the SDK type says `ModelRegistry` (non-optional), but `SubagentRuntime.currentCtx` can be undefined, and the architecture doc specifies this signature.
+   The `| undefined` reflects reality at the cast boundary (pre-bind, the registry may not exist).
+3. `sessionManager` uses an inline structural type rather than importing `ReadonlySessionManager` — we only need 3 of its 13 methods; a separate named type would be over-engineering for a nested structural slice.
+4. `getBranch()` returns `unknown[]` — the runtime passes entries through to `buildParentContext()` which already type-narrows internally.
+
+## Module-Level Changes
+
+| File           | Change                                                                                                         |
+| -------------- | -------------------------------------------------------------------------------------------------------------- |
+| `src/types.ts` | Add `SessionContext` interface export. Add `import type { ModelRegistry }` from `#src/session/model-resolver`. |
+
+No other files change — this is pure additive.
+
+## Test Impact Analysis
+
+1. No new unit tests are needed — `SessionContext` is a pure type definition with no runtime behavior.
+2. No existing tests become redundant.
+3. A compile-time check (`pnpm run check`) verifies the interface is well-formed and the import resolves.
+
+## TDD Order
+
+1. **Add `SessionContext` interface to `src/types.ts`** — add the interface with its import.
+   Verify with `pnpm run check` (type-check passes).
+   Commit: `feat(pi-subagents): define SessionContext narrow interface (#192)`
+
+## Risks and Mitigations
+
+| Risk                                                             | Mitigation                                                                                                                 |
+| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Interface shape doesn't match real `ExtensionContext` at runtime | Traced all 5 fields against SDK `.d.ts` declarations; shapes align exactly.                                                |
+| Circular import from `types.ts` → `session/model-resolver.ts`    | `model-resolver.ts` does not import from `types.ts`; no cycle.                                                             |
+| Future SDK changes break the narrow interface                    | The cast boundary (Layer 1, #193) will be the single enforcement point — structural typing ensures compile-time detection. |
+
+## Open Questions
+
+None — the issue's "Proposed change" section fully specifies the interface shape.

package/docs/retro/0185-remove-persistent-agent-memory.md

@@ -37,3 +37,37 @@ New file `safe-fs.test.ts` was created with 13 tests for the extracted utilities
   Fix: inline the literal union `"user" | "project" | "local"` directly in `memory.ts` as a local type, so it compiles cleanly until deletion in step 4.
 - The `SKILL.md` for `package-pi-subagents` also listed `memory.ts` in the session domain table — updated alongside `architecture.md` in the docs commit.
 - No deviations from the plan other than the two minor bugs above (both self-corrected within the same TDD step).
+
+## Stage: Final Retrospective (2026-05-24T22:47:55Z)
+
+### Session summary
+
+Shipped issue #185 as `pi-subagents-v7.0.0`.
+CI passed, issue closed, release-please PR #190 merged.
+Three sessions total: planning, TDD (5 steps / 5 commits), shipping.
+
+### Observations
+
+#### What went well
+
+- The issue's "Scope" section was precise enough that the planning session required no `ask_user` and the Explore agent's trace matched the final commit diff exactly.
+- Consumers-first, declaration-last ordering kept each commit independently compilable (after the two self-corrected fixes).
+- The `SKILL.md` domain table update was caught naturally during the docs step even though the plan didn't list it.
+
+#### What caused friction (agent side)
+
+- `missing-context` — In TDD step 1, `memory.ts` was updated to re-export `isUnsafeName` from `safe-fs`, but the function was not imported into `memory.ts`'s own scope.
+  `resolveMemoryDir` threw a `ReferenceError` at runtime.
+  Impact: one extra test-run cycle (~5 seconds) and a trivial one-line fix; no rework commit.
+- `missing-context` — In TDD step 3, removing `MemoryScope` from `types.ts` broke `memory.ts` (scheduled for deletion in step 4).
+  The plan said "consumers-first" but didn't account for the doomed module itself being a consumer of the type.
+  Impact: one extra `pnpm run check` cycle and a local type inline; no rework commit.
+  Both share the same root cause: incremental deletion plans must account for doomed files' own imports at each intermediate step.
+
+#### What caused friction (user side)
+
+- None observed — all three sessions ran without user corrections or redirections.
+
+### Changes made
+
+1. Added a TDD planning rule to `.pi/skills/testing/SKILL.md` about accounting for doomed modules' own imports during multi-step deletion.

package/docs/retro/0192-define-session-context-interface.md

@@ -0,0 +1,35 @@
+---
+issue: 192
+issue_title: "Define SessionContext narrow interface"
+---
+
+# Retro: #192 — Define SessionContext narrow interface
+
+## Stage: Planning (2026-05-24T16:00:00Z)
+
+### Session summary
+
+Planned the pure-additive `SessionContext` interface for `src/types.ts`.
+Traced all 5 consumed fields against the SDK's `ExtensionContext` type declarations to confirm shape alignment.
+Single TDD step: add the interface and verify with `pnpm run check`.
+
+### Observations
+
+- The interface is trivial in scope — one new export with no consumers changing.
+  This is intentionally the smallest possible first step to unblock Layer 1 (#193).
+- `ModelRegistry` already exists as a local narrow interface in `src/session/model-resolver.ts`; `SessionContext` imports it rather than redeclaring.
+- `sessionManager` uses an inline structural type (3 methods) rather than importing the SDK's `ReadonlySessionManager` (13 methods) — ISP applies here.
+- No design ambiguity required `ask_user`; the issue's proposed change section was fully specified.
+
+## Stage: Implementation — TDD (2026-05-24T19:55:00Z)
+
+### Session summary
+
+Added the `SessionContext` interface to `src/types.ts` with an `import type { ModelRegistry }` from `#src/session/model-resolver`.
+Single compile-time step — no runtime tests needed for a pure type definition.
+Baseline: 53 test files, 848 tests; final: unchanged.
+
+### Observations
+
+- Pre-existing lint failure in `docs/architecture/architecture.md` (5 unused MD053 link references for issues #164, #165, #170, #171, #172) was fixed as part of the baseline verification and included in the feat commit.
+- The interface landed exactly as planned — no deviations from the plan's Design Overview.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/types.ts

@@ -4,6 +4,7 @@
 
 import type { ThinkingLevel } from "@earendil-works/pi-ai";
 import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { ModelRegistry } from "#src/session/model-resolver";
 
 
 export { AgentRecord } from "#src/lifecycle/agent-record";
@@ -77,6 +78,26 @@ export interface AgentInvocation {
   isolation?: IsolationMode;
 }
 
+/**
+ * Narrow shell-exec callback replacing `ExtensionAPI` in `detectEnv()`.
+ * Matches the shape of `pi.exec()` without carrying an SDK dependency.
+ */
+/**
+ * Narrow interface capturing the ExtensionContext fields SubagentRuntime needs.
+ * Avoids coupling runtime to the full SDK ExtensionContext surface (ISP).
+ */
+export interface SessionContext {
+  readonly cwd: string;
+  readonly model: unknown;
+  readonly modelRegistry: ModelRegistry | undefined;
+  getSystemPrompt(): string;
+  readonly sessionManager: {
+    getSessionFile(): string | undefined;
+    getSessionId(): string;
+    getBranch(): unknown[];
+  };
+}
+
 /**
  * Narrow shell-exec callback replacing `ExtensionAPI` in `detectEnv()`.
  * Matches the shape of `pi.exec()` without carrying an SDK dependency.