@gotgenes/pi-subagents 6.9.4 → 6.11.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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).
 
+## [6.11.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.10.0...pi-subagents-v6.11.0) (2026-05-22)
+
+
+### Features
+
+* inject SDK boundary into agent-runner via RunnerIO ([#133](https://github.com/gotgenes/pi-packages/issues/133)) ([a9f6a9e](https://github.com/gotgenes/pi-packages/commit/a9f6a9e8c71e307b71600409e865fb539312f539))
+
+
+### Documentation
+
+* plan SDK boundary injection into agent-runner ([#133](https://github.com/gotgenes/pi-packages/issues/133)) ([1706ebc](https://github.com/gotgenes/pi-packages/commit/1706ebcc1452c6798dafb733ec8c68e6ee9e8512))
+* **retro:** add retro notes for issue [#132](https://github.com/gotgenes/pi-packages/issues/132) ([d0af140](https://github.com/gotgenes/pi-packages/commit/d0af1409ddc18099dfdda94ab37af2b99bc46c3c))
+* update architecture doc for Step H completion ([#133](https://github.com/gotgenes/pi-packages/issues/133)) ([f6b1258](https://github.com/gotgenes/pi-packages/commit/f6b1258f50a038df18ca1f33e3681c7bc258f4fc))
+
+## [6.10.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.9.4...pi-subagents-v6.10.0) (2026-05-22)
+
+
+### Features
+
+* inject IO collaborators into assembleSessionConfig ([#132](https://github.com/gotgenes/pi-packages/issues/132)) ([74d3dbf](https://github.com/gotgenes/pi-packages/commit/74d3dbf5e67cf28f75683e55240719ad2be86490))
+
+
+### Documentation
+
+* mark Step G complete in Phase 8 roadmap ([#132](https://github.com/gotgenes/pi-packages/issues/132)) ([95512bd](https://github.com/gotgenes/pi-packages/commit/95512bdec3757d5955d13e22261a90da41cea40e))
+* plan IO collaborator injection into assembleSessionConfig ([#132](https://github.com/gotgenes/pi-packages/issues/132)) ([23c3b62](https://github.com/gotgenes/pi-packages/commit/23c3b624e8c0afb8fda72c1b5fba86cb165f78dd))
+* **retro:** add retro notes for issue [#131](https://github.com/gotgenes/pi-packages/issues/131) ([b91cee9](https://github.com/gotgenes/pi-packages/commit/b91cee9ef69f8b1ab41be986663bad22e77a8c67))
+
 ## [6.9.4](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.9.3...pi-subagents-v6.9.4) (2026-05-22)
 
 

package/docs/architecture/architecture.md

@@ -505,9 +505,8 @@ E2 (Type housekeeping) ── can start after A1, runs parallel to later steps
 Phase 7 eliminated all structural smells (mutable state, closure bags, callback threading, wide dependency bags).
 Phase 8 targets the next layer: testability friction, display module cohesion, and menu decomposition.
 
-The test suite (690 tests, 1.4:1 test-to-code ratio) is comprehensive but uneven in quality.
-Two files — `session-config.test.ts` and `agent-runner.test.ts` — account for 11 of 12 total `vi.mock()` calls and rely heavily on verifying internal call sequences rather than observable outputs.
-This fragility is a symptom of production code that imports IO-touching collaborators directly instead of receiving them through injection.
+The test suite (714 tests) is comprehensive but uneven in quality.
+Steps G and H have eliminated 11 of the original 12 `vi.mock()` calls in the runner tests, removing fragile call-sequence assertions in favour of injected stubs. (Step G resolved `session-config.test.ts`; Step H resolved both `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts`.)
 
 The display and menu improvements were identified during Phase 7 but deferred because they don't gate encapsulation work.
 They are included here because the display extraction unblocks menu decomposition.
@@ -516,8 +515,8 @@ They are included here because the display extraction unblocks menu decompositio
 
 | Symptom                       | Location                                                | Root cause                                                        |
 | ----------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------- |
-| 7 `vi.mock()` calls           | `agent-runner.test.ts`                                  | Runner imports prompts, memory, skills, env, session-dir directly |
-| 4 `vi.mock()` calls           | `session-config.test.ts`                                | Assembler imports prompts, memory, skills directly                |
+| ~~7 `vi.mock()` calls~~       | ~~`agent-runner.test.ts`~~                              | ~~Resolved by Step H (#133)~~                                     |
+| ~~7 `vi.mock()` calls~~       | ~~`agent-runner-extension-tools.test.ts`~~              | ~~Resolved by Step H (#133)~~                                     |
 | 52 `as any` casts             | Across test suite                                       | SDK session/context interfaces too wide to construct in tests     |
 | 3× duplicated `mockSession()` | agent-manager, record-observer, ui-observer tests       | No shared test fixture                                            |
 | 3× duplicated `makeDeps()`    | agent-tool, background-spawner, foreground-runner tests | No shared tool-deps fixture                                       |
@@ -535,48 +534,20 @@ Consolidate duplicated mock factories into `test/helpers/`.
 
 Impact: reduces test boilerplate; single source of truth for mock shapes; changes to dep interfaces propagate automatically.
 
-### Step G: Inject IO collaborators into session-config (#132)
+### Step G: Inject IO collaborators into session-config (#132) ✓ done
 
-`assembleSessionConfig` is described as a pure assembler, but it directly imports three IO-touching functions: `preloadSkills` (reads `.pi/skills` files), `buildMemoryBlock` (reads `MEMORY.md`), and `buildReadOnlyMemoryBlock` (reads `MEMORY.md`).
-It also imports `buildAgentPrompt`, which is pure but mocked anyway because tests verify call arguments instead of output properties.
+`assembleSessionConfig` now accepts `io: AssemblerIO` as a required parameter.
+`index.ts` constructs the real `AssemblerIO` from direct imports via the `RunnerIO.assemblerIO` field (wired in Step H).
+`session-config.test.ts` injects stubs — all 4 `vi.mock()` calls eliminated, assertions shifted to `SessionConfig` output properties.
 
-Inject these as an `AssemblerIO` parameter:
+### Step H: Inject SDK boundary into agent-runner (#133) ✓ done
 
-```typescript
-export interface AssemblerIO {
-  preloadSkills: (skills: string[], cwd: string) => PreloadedSkill[];
-  buildMemoryBlock: (name: string, scope: MemoryScope, cwd: string) => string;
-  buildReadOnlyMemoryBlock: (name: string, scope: MemoryScope, cwd: string) => string;
-  buildAgentPrompt: (config: AgentPromptConfig, cwd: string, env: EnvInfo, parentPrompt: string, extras: PromptExtras) => string;
-}
-```
-
-The production call site in `agent-runner.ts` passes the real implementations.
-Tests pass stubs or let real implementations run against controlled inputs.
-
-Impact: eliminates all 4 `vi.mock()` calls in `session-config.test.ts`; tests verify `SessionConfig` output properties instead of mock call arguments; the assembler becomes truly pure.
-
-### Step H: Inject SDK boundary into agent-runner (#133)
-
-`agent-runner.ts` has 7 module mocks because it imports `createAgentSession`, `DefaultResourceLoader`, `SessionManager`, and `SettingsManager` from the Pi SDK, plus `detectEnv`, `deriveSubagentSessionDir`, and `assembleSessionConfig` from sibling modules.
-
-After Step G, `assembleSessionConfig` no longer needs mocking (its own IO is injected).
-The remaining SDK dependencies can be injected via a narrow `RunnerIO` interface:
-
-```typescript
-export interface RunnerIO {
-  createSession: (opts: SessionOptions) => AgentSession;
-  createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoader;
-  createSessionManager: (cwd: string) => SessionManager;
-  detectEnv: (exec: ShellExec, cwd: string) => Promise<EnvInfo>;
-  deriveSessionDir: (parentFile: string) => string;
-}
-```
+`runAgent()` now accepts `io: RunnerIO` as a required parameter bundling all IO collaborators: `detectEnv`, `getAgentDir`, `createResourceLoader`, `deriveSessionDir`, `createSessionManager`, `createSettingsManager`, `createSession`, and `assemblerIO`.
 
-The production call site in `agent-manager.ts` passes a `RunnerIO` built from the real SDK imports.
-Tests pass a stub `RunnerIO` without `vi.mock()`.
+`createAgentRunner(io: RunnerIO): AgentRunner` factory captures the boundary at construction time so `AgentManager` and the `AgentRunner` interface remain unchanged.
+`index.ts` constructs the real `RunnerIO` from Pi SDK imports and sibling modules.
 
-Impact: eliminates 5–7 `vi.mock()` calls in `agent-runner.test.ts`; tests verify behavior (turn limits, tool filtering, response collection) through injected fakes; refactoring internal structure no longer breaks tests.
+Impact: all 7 `vi.mock()` calls eliminated from both `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts`; tests verify behavior (turn limits, tool filtering, response collection) through injected stubs; SDK imports moved to the extension entry point.
 
 ### Step I: Reduce `as any` casts in tests (#134)
 

package/docs/plans/0132-inject-io-into-session-config.md

@@ -0,0 +1,219 @@
+---
+issue: 132
+issue_title: "Inject IO collaborators into `assembleSessionConfig`"
+---
+
+# Inject IO collaborators into session-config
+
+## Problem Statement
+
+`assembleSessionConfig` is described as a pure configuration assembler, but it directly imports three IO-touching functions (`preloadSkills`, `buildMemoryBlock`, `buildReadOnlyMemoryBlock`) and one pure function (`buildAgentPrompt`).
+This forces `session-config.test.ts` to use 4 `vi.mock()` calls, 8 hoisted mock functions, and assertions that verify internal call sequences rather than output properties.
+The result is fragile tests that break on any internal restructuring even when observable behavior is unchanged.
+
+## Goals
+
+- Define an `AssemblerIO` interface bundling the four collaborators.
+- Add `io: AssemblerIO` as a parameter to `assembleSessionConfig()`.
+- Replace direct imports of the four functions with calls through `io`.
+- Update the single production call site in `agent-runner.ts` to pass real implementations.
+- Eliminate all 4 `vi.mock()` calls in `session-config.test.ts`.
+- Shift test assertions toward output-property verification.
+
+## Non-Goals
+
+- SDK boundary injection into `agent-runner` (Step H, #133) — depends on this change but is deferred to its own issue.
+- Consolidating shared test fixtures (#131) — independent refactor that can land before or after.
+- Changing the behavior of `assembleSessionConfig` — this is a pure structural refactor.
+- Injecting `getMemoryToolNames` / `getReadOnlyMemoryToolNames` — these are pure utility functions with no IO; they stay as direct imports.
+
+## Background
+
+### Current state
+
+`session-config.ts` imports four functions used during assembly:
+
+| Function                   | Module            | IO?                            | Purpose in assembler                    |
+| -------------------------- | ----------------- | ------------------------------ | --------------------------------------- |
+| `preloadSkills`            | `skill-loader.ts` | Yes (reads `.pi/skills` files) | Loads skill content into prompt extras  |
+| `buildMemoryBlock`         | `memory.ts`       | Yes (reads `MEMORY.md`)        | Builds read-write memory prompt section |
+| `buildReadOnlyMemoryBlock` | `memory.ts`       | Yes (reads `MEMORY.md`)        | Builds read-only memory prompt section  |
+| `buildAgentPrompt`         | `prompts.ts`      | No (pure)                      | Assembles final system prompt string    |
+
+The test file mocks all four via `vi.mock()` plus mocks `getMemoryToolNames` and `getReadOnlyMemoryToolNames` from `agent-types.ts` (pure functions that are mocked only for call-argument verification).
+
+### Established DI pattern
+
+`AgentManager` already injects `AgentRunner` via its constructor options — the same tell-don't-ask pattern used here.
+`assembleSessionConfig` already receives an `AgentConfigLookup` registry by parameter (migrated in #80/#108), demonstrating the incremental injection approach.
+
+### Architecture reference
+
+Phase 8, Step G in `docs/architecture/architecture.md`.
+
+### Constraints from AGENTS.md
+
+- Keep scope tight; prefer small, reversible changes.
+- Prefer explicit configuration over hidden behavior.
+- Business logic should be pure functions — keep IO at the edges.
+
+## Design Overview
+
+### `AssemblerIO` interface
+
+Defined in `session-config.ts` alongside the existing assembler types:
+
+```typescript
+export interface AssemblerIO {
+  preloadSkills: (skills: string[], cwd: string) => PreloadedSkill[];
+  buildMemoryBlock: (
+    name: string,
+    scope: MemoryScope,
+    cwd: string,
+  ) => string;
+  buildReadOnlyMemoryBlock: (
+    name: string,
+    scope: MemoryScope,
+    cwd: string,
+  ) => string;
+  buildAgentPrompt: (
+    config: AgentPromptConfig,
+    cwd: string,
+    env: EnvInfo,
+    parentPrompt?: string,
+    extras?: PromptExtras,
+  ) => string;
+}
+```
+
+The interface uses the same parameter types as the real functions.
+The assembler calls `io.preloadSkills(...)` etc. instead of the direct imports.
+
+### Call site in `agent-runner.ts`
+
+```typescript
+import { preloadSkills } from "./skill-loader.js";
+import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
+import { buildAgentPrompt } from "./prompts.js";
+
+const io: AssemblerIO = {
+  preloadSkills,
+  buildMemoryBlock,
+  buildReadOnlyMemoryBlock,
+  buildAgentPrompt,
+};
+
+const cfg = assembleSessionConfig(type, ctx, options, env, registry, io);
+```
+
+The runner constructs the real IO object once and passes it through.
+This keeps IO at the edge (runner) and makes the assembler a genuine pure function.
+
+### Test-side stubs
+
+Tests create a plain object with `vi.fn()` stubs satisfying `AssemblerIO`:
+
+```typescript
+const io: AssemblerIO = {
+  preloadSkills: vi.fn(() => []),
+  buildMemoryBlock: vi.fn(() => "memory block"),
+  buildReadOnlyMemoryBlock: vi.fn(() => "read-only memory block"),
+  buildAgentPrompt: vi.fn(() => "assembled system prompt"),
+};
+```
+
+This replaces all four `vi.mock()` calls and the hoisted mocks for those modules.
+
+### Pure utility functions stay as direct imports
+
+`getMemoryToolNames` and `getReadOnlyMemoryToolNames` from `agent-types.ts` are pure functions (no IO, no filesystem access).
+After the IO injection, the test's `vi.mock("../src/agent-types.js", ...)` can be removed and real implementations used.
+Tests that previously controlled these mocks to verify call arguments will instead set up input tool names to produce the desired output from the real functions, then assert on the returned `SessionConfig.toolNames`.
+
+## Module-Level Changes
+
+### Modified files
+
+1. `src/session-config.ts`
+   - Add `AssemblerIO` interface export.
+   - Add `io: AssemblerIO` parameter to `assembleSessionConfig()` (after `registry`).
+   - Replace `preloadSkills(...)` with `io.preloadSkills(...)`.
+   - Replace `buildMemoryBlock(...)` with `io.buildMemoryBlock(...)`.
+   - Replace `buildReadOnlyMemoryBlock(...)` with `io.buildReadOnlyMemoryBlock(...)`.
+   - Replace `buildAgentPrompt(...)` with `io.buildAgentPrompt(...)`.
+   - Remove imports of `preloadSkills`, `buildMemoryBlock`, `buildReadOnlyMemoryBlock`, `buildAgentPrompt`.
+   - Keep imports of `getMemoryToolNames`, `getReadOnlyMemoryToolNames` (pure, no change).
+
+2. `src/agent-runner.ts`
+   - Add imports for `preloadSkills`, `buildMemoryBlock`, `buildReadOnlyMemoryBlock`, `buildAgentPrompt`.
+   - Import `AssemblerIO` type from `session-config.ts`.
+   - Construct `AssemblerIO` object from real implementations.
+   - Pass `io` to `assembleSessionConfig()`.
+
+3. `test/session-config.test.ts`
+   - Remove all 4 `vi.mock()` calls and the corresponding hoisted mocks.
+   - Create `io` stub object with `vi.fn()` implementations.
+   - Pass `io` to every `assembleSessionConfig()` call.
+   - Update memory-section tests to use real `getMemoryToolNames` / `getReadOnlyMemoryToolNames`.
+   - Migrate mock-call assertions to output-property assertions where the output already captures the information.
+
+## Test Impact Analysis
+
+1. The IO injection enables testing `assembleSessionConfig` without any module mocking.
+   Tests can choose to inject real implementations with controlled inputs (integration-style) or stubs (unit-style).
+   Previously this was impossible without `vi.mock()`.
+
+2. Several existing tests that only verified mock-call arguments become redundant once we verify the same information through output properties (e.g., "calls buildAgentPrompt with env, cwd, parentSystemPrompt, and extras" is redundant if we verify `result.systemPrompt` reflects those inputs).
+   These can be simplified or removed.
+
+3. Tests for model resolution, isolated mode, thinking level, and unknown-type fallback stay as-is — they already assert output properties and are unaffected by the IO injection.
+
+## TDD Order
+
+1. **Define `AssemblerIO` and inject into `assembleSessionConfig`.**
+   Add the `AssemblerIO` interface to `session-config.ts`.
+   Add `io: AssemblerIO` as a required parameter.
+   Replace the 4 direct function calls with `io.*` calls.
+   Remove the 4 function imports from `session-config.ts`.
+   Add the 4 imports to `agent-runner.ts` and construct the `io` object at the call site.
+   Run `pnpm run check` to verify types compile.
+   Commit: `feat: inject IO collaborators into assembleSessionConfig (#132)`
+
+2. **Migrate test file to use injected IO stubs.**
+   Create an `io` stub object with `vi.fn()` stubs matching the existing hoisted mocks' default return values.
+   Pass `io` to all `assembleSessionConfig()` calls.
+   Remove the 3 `vi.mock()` calls for `prompts.js`, `memory.js`, and `skill-loader.js`.
+   Remove the corresponding hoisted mock variables (`mockBuildAgentPrompt`, `mockBuildMemoryBlock`, `mockBuildReadOnlyMemoryBlock`, `mockPreloadSkills`).
+   Update `beforeEach` to reset the `io` stubs instead.
+   All existing tests pass with the same assertions (io stubs replace module mocks).
+   Commit: `test: replace vi.mock with injected IO stubs in session-config tests`
+
+3. **Drop the `agent-types.js` mock; use real pure functions.**
+   Remove the `vi.mock("../src/agent-types.js", ...)` call and the `importOriginal` pattern.
+   Remove hoisted `mockGetMemoryToolNames` and `mockGetReadOnlyMemoryToolNames`.
+   Update memory-section tests to set up `mockGetToolNamesForType` return values that produce the desired output from the real `getMemoryToolNames` / `getReadOnlyMemoryToolNames`.
+   Assertions shift from "mock was called with Set" to "result.toolNames contains expected names".
+   Commit: `test: use real getMemoryToolNames in session-config tests`
+
+4. **Shift remaining mock-call assertions to output-property checks.**
+   Replace `expect(io.buildAgentPrompt).toHaveBeenCalledWith(...)` with assertions on `result.systemPrompt` (requires io.buildAgentPrompt stub to echo identifying values).
+   Replace `expect(io.preloadSkills).toHaveBeenCalledWith(skillList, "/tmp")` with `result.extras.skillBlocks` checks (already partially present).
+   Remove test cases that are now fully redundant with output-based tests in the same describe block.
+   Clean up any unused imports and variables.
+   Commit: `test: verify output properties in session-config tests (#132)`
+
+## Risks and Mitigations
+
+| Risk                                                                                                      | Mitigation                                                                                                                                                                              |
+| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Adding a parameter to `assembleSessionConfig` breaks the `agent-runner.ts` call site                      | Only one production call site exists; updated in the same commit (step 1). `pnpm run check` verifies.                                                                                   |
+| Removing `vi.mock()` causes tests to accidentally call real IO functions                                  | The real functions are no longer imported by `session-config.ts` after step 1. The module simply doesn't reach them. Vitest will error if any unmocked import is called.                |
+| Using real `getMemoryToolNames` / `getReadOnlyMemoryToolNames` makes tests depend on their implementation | These are pure, stable utility functions (return tool names from a set). Their behavior is well-defined and unlikely to change. Using real implementations is more robust than mocking. |
+| Step 2 touches 40+ call sites in the test file                                                            | All changes are mechanical (add `, io` argument). A find-and-replace handles it. Each call already passes `mockAgentLookup` as the last arg; the new arg follows the same pattern.      |
+
+## Open Questions
+
+- Should `AssemblerIO` be co-located in `session-config.ts` or extracted to a separate `session-config-types.ts`?
+  The interface is small (4 methods) and tightly coupled to the assembler.
+  Co-location in `session-config.ts` follows the existing pattern (`AssemblerContext`, `AssemblerOptions`, `SessionConfig` are all in the same file).
+  Extract only if it grows or gains consumers beyond `agent-runner.ts`.

package/docs/plans/0133-inject-sdk-boundary-into-agent-runner.md

@@ -0,0 +1,373 @@
+---
+issue: 133
+issue_title: "Inject SDK boundary into `agent-runner`"
+---
+
+# Inject SDK boundary into agent-runner
+
+## Problem Statement
+
+`agent-runner.ts` directly imports five Pi SDK symbols (`createAgentSession`, `DefaultResourceLoader`, `getAgentDir`, `SessionManager`, `SettingsManager`) and two sibling modules (`detectEnv`, `deriveSubagentSessionDir`).
+It also imports four functions (`preloadSkills`, `buildMemoryBlock`, `buildReadOnlyMemoryBlock`, `buildAgentPrompt`) solely to construct the `AssemblerIO` object introduced in #132.
+This forces `agent-runner.test.ts` to use 7 `vi.mock()` calls, a `vi.hoisted()` block with 5+ mock factories, and a `beforeEach` that manually resets 6+ mocks.
+Tests verify internal call patterns ("defaultResourceLoaderCtor was called with `noContextFiles: true`") rather than behavioral outcomes, making any internal restructuring break multiple tests without changing observable behavior.
+The same 7-mock pattern is duplicated in `agent-runner-extension-tools.test.ts`.
+
+## Goals
+
+- Define a `RunnerIO` interface bundling all SDK and IO collaborators used by `runAgent()`.
+- Add `io: RunnerIO` as a parameter to `runAgent()`.
+- Provide a `createAgentRunner(io: RunnerIO): AgentRunner` factory so the `AgentRunner` interface and `AgentManager` remain unchanged.
+- Replace direct SDK and sibling-module imports in `runAgent()` with calls through `io`.
+- Update the wiring in `index.ts` to construct a real `RunnerIO` and use `createAgentRunner()`.
+- Eliminate all 7 `vi.mock()` calls in `agent-runner.test.ts`.
+- Eliminate all 7 `vi.mock()` calls in `agent-runner-extension-tools.test.ts`.
+- Shift test assertions toward behavioral outcomes (turn limits enforced, tool filtering correct, response text collected).
+
+## Non-Goals
+
+- Changing `resumeAgent` — it receives an already-created `AgentSession` and has no SDK/IO deps to inject.
+- Injecting `assembleSessionConfig` itself — the function is pure (after #132) and stays as a direct import; only its `AssemblerIO` collaborators move into `RunnerIO`.
+- Injecting `getMemoryToolNames` / `getReadOnlyMemoryToolNames` — these are pure utility functions with no IO; they remain as direct imports in `session-config.ts`.
+- Refactoring `filterActiveTools` or the turn-limit logic — out of scope.
+- Consolidating shared test fixtures (#131) — independent work.
+
+## Background
+
+### Prerequisite
+
+Issue #132 (inject IO into session-config) is closed.
+`assembleSessionConfig` now receives an `AssemblerIO` parameter and no longer imports IO functions directly.
+However, `agent-runner.ts` still imports those four functions to construct the `AssemblerIO` object, and the SDK factories remain as direct imports.
+
+### Current vi.mock inventory in agent-runner.test.ts
+
+| #   | Module                            | Symbols mocked                                                                                    | Why mocked                            |
+| --- | --------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| 1   | `@earendil-works/pi-coding-agent` | `createAgentSession`, `DefaultResourceLoader`, `getAgentDir`, `SessionManager`, `SettingsManager` | SDK constructors and factories        |
+| 2   | `../src/agent-types.js`           | `getMemoryToolNames`, `getReadOnlyMemoryToolNames`                                                | Pure functions used by session-config |
+| 3   | `../src/env.js`                   | `detectEnv`                                                                                       | Async IO (shell exec)                 |
+| 4   | `../src/prompts.js`               | `buildAgentPrompt`                                                                                | Relayed to AssemblerIO                |
+| 5   | `../src/memory.js`                | `buildMemoryBlock`, `buildReadOnlyMemoryBlock`                                                    | Relayed to AssemblerIO                |
+| 6   | `../src/skill-loader.js`          | `preloadSkills`                                                                                   | Relayed to AssemblerIO                |
+| 7   | `../src/session-dir.js`           | `deriveSubagentSessionDir`                                                                        | Path derivation                       |
+
+`agent-runner-extension-tools.test.ts` has an identical set.
+
+### Established DI patterns
+
+- `AgentManager` already receives `AgentRunner` via constructor injection — the same boundary this issue pushes down one layer.
+- `AssemblerIO` (#132) bundles four IO collaborators into a single injectable interface.
+- `AgentManagerLike` in `service-adapter.ts` defines a narrow interface for the concrete `AgentManager` class, avoiding coupling to the concrete type.
+
+### Architecture reference
+
+Phase 8, Step H in `docs/architecture/architecture.md`.
+
+### Constraints from AGENTS.md
+
+- Keep scope tight; prefer small, reversible changes.
+- Prefer explicit configuration over hidden behavior.
+- Business logic should be pure functions — keep IO at the edges.
+- Keep Pi SDK imports out of business-logic modules.
+
+## Design Overview
+
+### `RunnerIO` interface
+
+Defined in `agent-runner.ts` alongside the existing runner types.
+Bundles all IO dependencies that `runAgent()` uses:
+
+```typescript
+/** Minimal resource-loader contract used by the runner. */
+export interface ResourceLoaderLike {
+  reload(): Promise<void>;
+}
+
+/** Minimal session-manager contract used by the runner. */
+export interface SessionManagerLike {
+  newSession(opts: { parentSession?: string }): void;
+  getSessionFile(): string | undefined;
+}
+
+/** Options passed to RunnerIO.createResourceLoader. */
+export interface ResourceLoaderOptions {
+  cwd: string;
+  agentDir: string;
+  noExtensions?: boolean;
+  noSkills?: boolean;
+  noPromptTemplates?: boolean;
+  noThemes?: boolean;
+  noContextFiles?: boolean;
+  systemPromptOverride?: () => string;
+  appendSystemPromptOverride?: () => unknown[];
+}
+
+/** Options passed to RunnerIO.createSession. */
+export interface CreateSessionOptions {
+  cwd: string;
+  agentDir: string;
+  sessionManager: SessionManagerLike;
+  settingsManager: unknown;
+  modelRegistry: unknown;
+  model?: unknown;
+  tools: string[];
+  resourceLoader: ResourceLoaderLike;
+  thinkingLevel?: ThinkingLevel;
+}
+
+/**
+ * IO boundary injected into runAgent().
+ *
+ * Decouples the runner from direct Pi SDK imports and sibling-module IO,
+ * making it testable via plain stub objects without vi.mock().
+ */
+export interface RunnerIO {
+  detectEnv: (exec: ShellExec, cwd: string) => Promise<EnvInfo>;
+  getAgentDir: () => string;
+  createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoaderLike;
+  deriveSessionDir: (
+    parentSessionFile: string | undefined,
+    effectiveCwd: string,
+  ) => string;
+  createSessionManager: (
+    cwd: string,
+    sessionDir: string,
+  ) => SessionManagerLike;
+  createSettingsManager: (cwd: string, agentDir: string) => unknown;
+  createSession: (
+    opts: CreateSessionOptions,
+  ) => Promise<{ session: AgentSession }>;
+  assemblerIO: AssemblerIO;
+}
+```
+
+The interface has 8 fields (7 functions + 1 nested `AssemblerIO`).
+All 8 are consumed by `runAgent()` — no field is relayed without use.
+
+### `createAgentRunner` factory
+
+```typescript
+export function createAgentRunner(io: RunnerIO): AgentRunner {
+  return {
+    run: (snapshot, type, prompt, options) =>
+      runAgent(snapshot, type, prompt, options, io),
+    resume: resumeAgent,
+  };
+}
+```
+
+This keeps the `AgentRunner` interface unchanged.
+`AgentManager` continues to receive an `AgentRunner` — it never sees `RunnerIO`.
+
+### Call site in `index.ts`
+
+```typescript
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  getAgentDir,
+  SessionManager,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import { detectEnv } from "./env.js";
+import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
+import { buildAgentPrompt } from "./prompts.js";
+import { deriveSubagentSessionDir } from "./session-dir.js";
+import { preloadSkills } from "./skill-loader.js";
+
+const runnerIO: RunnerIO = {
+  detectEnv,
+  getAgentDir,
+  createResourceLoader: (opts) => new DefaultResourceLoader(opts),
+  deriveSessionDir: deriveSubagentSessionDir,
+  createSessionManager: (cwd, dir) => SessionManager.create(cwd, dir),
+  createSettingsManager: (cwd, dir) => SettingsManager.create(cwd, dir),
+  createSession: createAgentSession,
+  assemblerIO: {
+    preloadSkills,
+    buildMemoryBlock,
+    buildReadOnlyMemoryBlock,
+    buildAgentPrompt,
+  },
+};
+
+const manager = new AgentManager({
+  runner: createAgentRunner(runnerIO),
+  // ... rest unchanged
+});
+```
+
+SDK and IO imports move from `agent-runner.ts` to `index.ts` — the extension entry point, which is the natural IO edge.
+
+### Test-side stubs
+
+Tests create a plain `RunnerIO` object with `vi.fn()` stubs:
+
+```typescript
+function createRunnerIO(): RunnerIO {
+  return {
+    detectEnv: vi.fn(async () => ({
+      isGitRepo: false,
+      branch: "",
+      platform: "linux",
+    })),
+    getAgentDir: vi.fn(() => "/mock/agent-dir"),
+    createResourceLoader: vi.fn(() => ({ reload: vi.fn() })),
+    deriveSessionDir: vi.fn(() => "/mock/session-dir/tasks"),
+    createSessionManager: vi.fn(() => ({
+      newSession: vi.fn(),
+      getSessionFile: vi.fn(() => "/sessions/child.jsonl"),
+    })),
+    createSettingsManager: vi.fn(() => ({ kind: "settings-manager" })),
+    createSession: vi.fn(),
+    assemblerIO: {
+      preloadSkills: vi.fn(() => []),
+      buildMemoryBlock: vi.fn(() => ""),
+      buildReadOnlyMemoryBlock: vi.fn(() => ""),
+      buildAgentPrompt: vi.fn(() => "system prompt"),
+    },
+  };
+}
+```
+
+This replaces all 7 `vi.mock()` calls, the `vi.hoisted()` block, and most of the `beforeEach` resets.
+Each test calls `runAgent(snapshot, type, prompt, options, io)` directly with a stub `io`.
+
+### Interaction verification — consumer call site (Tell-Don't-Ask check)
+
+```typescript
+// In index.ts — the consumer constructs RunnerIO and hands it off:
+const runnerIO: RunnerIO = { detectEnv, getAgentDir, ... };
+const manager = new AgentManager({
+  runner: createAgentRunner(runnerIO),
+});
+// AgentManager calls runner.run(...) — never reaches through to runnerIO.
+// Tell-Don't-Ask: ✓  Manager tells runner to run; runner uses its own IO.
+```
+
+### Pure functions stay as direct imports
+
+`assembleSessionConfig` (pure after #132), `filterActiveTools` (module-private), `normalizeMaxTurns` (pure exported), `collectResponseText`, `getLastAssistantText`, and `forwardAbortSignal` remain as direct code — they have no IO dependencies.
+
+`getMemoryToolNames` / `getReadOnlyMemoryToolNames` in `session-config.ts` remain as direct imports (pure, no IO).
+The `vi.mock("../src/agent-types.js", ...)` in both test files can be removed because the mock agent config has no `memory` field, so the memory branch in `assembleSessionConfig` is never entered and those functions are never called.
+
+## Module-Level Changes
+
+### Modified files
+
+1. `src/agent-runner.ts`
+   - Add `RunnerIO`, `ResourceLoaderLike`, `SessionManagerLike`, `ResourceLoaderOptions`, `CreateSessionOptions` interface exports.
+   - Add `createAgentRunner(io: RunnerIO): AgentRunner` factory export.
+   - Add `io: RunnerIO` parameter to `runAgent()`.
+   - Replace `detectEnv(...)` with `io.detectEnv(...)`.
+   - Replace `getAgentDir()` with `io.getAgentDir()`.
+   - Replace `new DefaultResourceLoader(...)` with `io.createResourceLoader(...)`.
+   - Replace `deriveSubagentSessionDir(...)` with `io.deriveSessionDir(...)`.
+   - Replace `SessionManager.create(...)` with `io.createSessionManager(...)`.
+   - Replace `SettingsManager.create(...)` with `io.createSettingsManager(...)`.
+   - Replace `createAgentSession(...)` with `io.createSession(...)`.
+   - Replace inline `AssemblerIO` construction with `io.assemblerIO`.
+   - Remove imports: `createAgentSession`, `DefaultResourceLoader`, `getAgentDir`, `SessionManager`, `SettingsManager` from `@earendil-works/pi-coding-agent`; `detectEnv` from `./env.js`; `deriveSubagentSessionDir` from `./session-dir.js`; `preloadSkills` from `./skill-loader.js`; `buildMemoryBlock`, `buildReadOnlyMemoryBlock` from `./memory.js`; `buildAgentPrompt` from `./prompts.js`.
+   - Keep imports: `type AgentSession`, `type AgentSessionEvent` from SDK (used in function signatures and event handling); `type AssemblerIO` from `./session-config.js`; `assembleSessionConfig` from `./session-config.js`; `extractText` from `./context.js`.
+
+2. `src/index.ts`
+   - Add imports: `detectEnv` from `./env.js`; `deriveSubagentSessionDir` from `./session-dir.js`; `preloadSkills` from `./skill-loader.js`; `buildMemoryBlock`, `buildReadOnlyMemoryBlock` from `./memory.js`; `buildAgentPrompt` from `./prompts.js`.
+   - Add import: `createAgentRunner`, `type RunnerIO` from `./agent-runner.js`.
+   - Remove import: `runAgent` from `./agent-runner.js` (replaced by factory).
+   - Construct `runnerIO` object from real implementations.
+   - Replace `runner: { run: runAgent, resume: resumeAgent }` with `runner: createAgentRunner(runnerIO)`.
+
+3. `test/agent-runner.test.ts`
+   - Remove all 7 `vi.mock()` calls and the `vi.hoisted()` block.
+   - Add `createRunnerIO()` factory function returning a stub `RunnerIO`.
+   - Pass `io` to all `runAgent()` calls.
+   - Simplify `beforeEach` to reset `io.createSession` (the only mock that needs per-test setup).
+   - Remove `mockAgentLookup.resolveAgentConfig` and `mockAgentLookup.getToolNamesForType` resets that are now unnecessary.
+   - Update assertions that verify SDK constructor arguments (e.g., `defaultResourceLoaderCtor` calls) to verify `io.createResourceLoader` calls instead.
+   - Remove the `agent-types.js` mock — pure functions run against controlled inputs.
+
+4. `test/agent-runner-extension-tools.test.ts`
+   - Same structural changes as `agent-runner.test.ts`: remove all 7 `vi.mock()` calls, inject `RunnerIO` stubs.
+   - Keep the `createSessionWithExtensionToolRegistration` helper — it creates mock sessions for testing post-bind tool filtering, which is behavioral.
+   - Update assertions to use `io.createResourceLoader` / `io.createSession` stubs.
+
+### Unchanged files
+
+- `src/agent-manager.ts` — receives `AgentRunner` via injection; unaffected by `RunnerIO`.
+- `test/agent-manager.test.ts` — already injects a mock `AgentRunner`; unaffected.
+- `src/session-config.ts` — pure function, already receives `AssemblerIO`; unaffected.
+- `test/session-config.test.ts` — tests the pure assembler directly; unaffected.
+- `test/agent-runner-settings.test.ts` — tests `normalizeMaxTurns` (pure, no mocks); unaffected.
+- `test/print-mode.test.ts` — mocks `runAgent` itself at the module level; unaffected (it tests `index.ts` notification wiring, not the runner internals).
+
+## Test Impact Analysis
+
+1. The `RunnerIO` injection enables testing `runAgent` without any module mocking.
+   Tests create plain stub objects satisfying `RunnerIO` — no `vi.mock()`, no `vi.hoisted()`, no module-level mock variable management.
+   This was previously impossible because `runAgent` hard-imported SDK constructors.
+
+2. Several existing tests that verify mock constructor arguments become redundant or shift to verifying `io.*` stub calls:
+   - "passes effective cwd and agentDir to the loader and settings manager" → verifies `io.createResourceLoader` and `io.createSettingsManager` were called with expected args (simpler, no `defaultResourceLoaderCtor` indirection).
+   - "suppresses AGENTS.md/CLAUDE.md/APPEND_SYSTEM.md for subagents" → verifies `io.createResourceLoader` was called with `noContextFiles: true` and an `appendSystemPromptOverride` that returns `[]`.
+
+3. Tests for turn-limit enforcement, abort forwarding, and response-text collection stay as-is — they already test behavioral outcomes through the mock session, not through SDK mock call patterns.
+
+4. The extension-tools tests (Patch 2) remain behavioral — they verify `setActiveToolsByName` calls before/after `bindExtensions`.
+   The only change is how the session is created (via `io.createSession` stub instead of a module mock).
+
+5. The `agent-types.js` mock can be removed from both test files because the mock agent configs have no `memory` field, so the code path through `getMemoryToolNames` / `getReadOnlyMemoryToolNames` is never reached.
+
+## TDD Order
+
+1. **Define `RunnerIO` and `createAgentRunner`; inject IO into `runAgent`.**
+   Add the `RunnerIO`, `ResourceLoaderLike`, `SessionManagerLike`, `ResourceLoaderOptions`, and `CreateSessionOptions` interfaces to `agent-runner.ts`.
+   Add `io: RunnerIO` parameter to `runAgent()`.
+   Add `createAgentRunner(io)` factory export.
+   Replace all direct SDK and IO imports with `io.*` calls inside `runAgent()`.
+   Remove the now-unused direct imports.
+   Update `index.ts` to construct `runnerIO` from real implementations and use `createAgentRunner(runnerIO)`.
+   Run `pnpm run check` to verify types compile.
+   Commit: `feat: inject SDK boundary into agent-runner via RunnerIO (#133)`
+
+2. **Migrate `agent-runner.test.ts` to use injected `RunnerIO` stubs.**
+   Add `createRunnerIO()` helper returning a fully-stubbed `RunnerIO`.
+   Pass `io` to all `runAgent()` calls.
+   Remove all 7 `vi.mock()` calls and the `vi.hoisted()` block.
+   Simplify `beforeEach` to reset only `io.createSession`.
+   Update assertions that referenced hoisted mocks (e.g., `defaultResourceLoaderCtor`, `sessionManagerCreate`, `settingsManagerCreate`, `getAgentDir`) to reference `io.*` stubs.
+   Remove the `mockAgentLookup` mock resets that are now unnecessary.
+   All existing tests pass with equivalent assertions.
+   Commit: `test: replace vi.mock with RunnerIO stubs in agent-runner tests (#133)`
+
+3. **Migrate `agent-runner-extension-tools.test.ts` to use injected `RunnerIO` stubs.**
+   Same structural changes as step 2: remove all 7 `vi.mock()` calls, inject `RunnerIO` stubs.
+   Keep `createSessionWithExtensionToolRegistration` helper (tests tool filtering behavior).
+   Simplify `beforeEach` and update stub references.
+   Commit: `test: replace vi.mock with RunnerIO stubs in extension-tools tests (#133)`
+
+4. **Shift constructor-argument assertions to behavioral checks.**
+   In `agent-runner.test.ts`, update tests that verify internal SDK call arguments:
+   - Replace `expect(defaultResourceLoaderCtor).toHaveBeenCalledWith(expect.objectContaining({...}))` with `expect(io.createResourceLoader).toHaveBeenCalledWith(expect.objectContaining({...}))`.
+   - Where the assertion only verified plumbing (e.g., "settings manager gets the right cwd"), simplify to a behavioral assertion or remove if covered by other tests.
+   - Keep assertions that verify meaningful configuration decisions (e.g., `noContextFiles: true`, `appendSystemPromptOverride` returns `[]`).
+   Run full test suite.
+   Commit: `test: shift agent-runner assertions toward behavioral checks (#133)`
+
+## Risks and Mitigations
+
+| Risk                                                                                                    | Mitigation                                                                                                                                                                                                            |
+| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `RunnerIO` at 8 fields may seem wide                                                                    | All 8 are consumed by the single consumer (`runAgent`). No field is relayed without use. The interface represents a genuine IO boundary — further narrowing would require splitting `runAgent` itself (out of scope). |
+| Removing the `agent-types.js` mock could cause failures if a test unexpectedly enters the memory branch | The mock agent config has no `memory` field (`undefined`), so the memory branch is guarded by `if (agentConfig.memory)`. Verified by reading the test's `resolveAgentConfig` mock return value.                       |
+| `index.ts` accumulates many new imports                                                                 | The imports move from `agent-runner.ts` to `index.ts` — the extension entry point is the natural IO edge. The total import count across the two files is unchanged.                                                   |
+| `createAgentRunner` factory adds indirection                                                            | The factory is a one-liner that captures `io` in a closure. The `AgentRunner` interface and `AgentManager` are completely unchanged. No new abstraction layer — just a construction-time binding.                     |
+| Steps 2–3 touch many call sites in two test files (add `, io` argument)                                 | All changes are mechanical. Each `runAgent(snapshot, type, prompt, {...})` becomes `runAgent(snapshot, type, prompt, {...}, io)`. A single find-and-replace handles it.                                               |
+| `print-mode.test.ts` mocks `runAgent` at the module level — does the new `io` parameter break it?       | `print-mode.test.ts` mocks the entire `runAgent` export with `vi.mock("../src/agent-runner.js", ...)`. The mock replaces the function entirely, so the new parameter has no effect on that test.                      |
+
+## Open Questions
+
+- Should `RunnerIO` live in `agent-runner.ts` or be extracted to a separate types file?
+  The interface is tightly coupled to `runAgent()` — co-location follows the `AssemblerIO` precedent in `session-config.ts`.
+  Extract only if a second consumer appears.

package/docs/retro/0131-consolidate-shared-test-fixtures.md

@@ -0,0 +1,46 @@
+---
+issue: 131
+issue_title: Consolidate shared test fixtures
+---
+
+# Retro: #131 — Consolidate shared test fixtures
+
+## Final Retrospective (2026-05-22T11:30:00Z)
+
+### Session summary
+
+Planned and implemented the consolidation of six duplicated test factories into two shared helpers (`createMockSession` in `test/helpers/mock-session.ts`, `createToolDeps` in `test/helpers/make-deps.ts`).
+All 715 tests pass, released as `pi-subagents-v6.9.4`.
+The implementation was a pure test refactor with no production code changes.
+
+### Observations
+
+#### What went well
+
+- The lift-and-shift approach worked cleanly: create factory → migrate one consumer at a time → verify green after each step.
+  Each migration commit was small and isolated, making failures easy to diagnose.
+- Structural typing as a strategy proved out — `createToolDeps()` returns `AgentToolDeps` (the superset), and `spawnBackground(deps, ...)` and `runForeground(deps, ...)` accept their narrow `BackgroundDeps`/`ForegroundDeps` interfaces without any casting.
+
+#### What caused friction (agent side)
+
+- `missing-context` — Plan used `registry.resolve("general-purpose", "/dir")` in the `make-deps.test.ts` test, but `AgentTypeRegistry` has no `resolve` method — the correct method is `resolveAgentConfig()`.
+  Impact: one test failure during step 5 red→green, fixed immediately with no rework.
+
+- `missing-context` — Default values differed between the old narrow factories and the new shared factory: `"bg-1"` vs `"agent-1"` for spawn IDs (`background-spawner.test.ts`), `"Task done."` vs `"All done."` for result text (`foreground-runner.test.ts`).
+  Impact: two test failures in step 7, one in step 8, each requiring assertion updates before the migration step could pass.
+
+- `missing-context` — `MockSession` interface used `ReturnType<typeof vi.fn>` which expands to `Mock<Procedure | Constructable>` in Vitest v4 — a union type TypeScript cannot call.
+  Impact: `pnpm run check` failed after all TDD steps were done, requiring a separate `style:` commit to switch to explicitly parameterized `Mock<() => void>` etc.
+
+- `missing-context` — Removed the `AgentToolDeps` import from `agent-tool.test.ts` without checking that the `execute()` helper still referenced it.
+  Impact: caught in the same `pnpm run check` pass, fixed in the same `style:` commit.
+
+#### What caused friction (user side)
+
+- No user-side friction observed.
+  The plan was unambiguous, and the session ran autonomously through all 8 TDD steps plus post-checks without intervention.
+
+### Changes made
+
+1. `.pi/skills/testing/SKILL.md` — added TDD planning rule for diffing default values when consolidating duplicate test factories.
+2. `.pi/skills/testing/SKILL.md` — added Vitest mock pattern rule for typing mock fields with `Mock<specific-signature>` instead of `ReturnType<typeof vi.fn>`.

package/docs/retro/0132-inject-io-into-session-config.md

@@ -0,0 +1,33 @@
+---
+issue: 132
+issue_title: "Inject IO collaborators into `assembleSessionConfig`"
+---
+
+# Retro: #132 — Inject IO collaborators into `assembleSessionConfig`
+
+## Final Retrospective (2026-05-22T12:25:00Z)
+
+### Session summary
+
+Defined an `AssemblerIO` interface bundling four IO/prompt collaborators, injected it into `assembleSessionConfig`, and updated `agent-runner.ts` to pass real implementations.
+Eliminated all 4 `vi.mock()` calls in `session-config.test.ts`, flattened the `vi.hoisted()` block into plain `vi.fn()` declarations, and shifted assertions from mock-call verification to output-property checks.
+Released as `pi-subagents-v6.10.0`.
+
+### Observations
+
+#### What went well
+
+- Perl two-pass replacement (multi-line then single-line) handled 40+ `assembleSessionConfig` call-site updates in one command with zero manual errors.
+- Flattening `vi.hoisted()` into regular `vi.fn()` declarations in step 3 was a clean simplification — hoisting was only needed when the mocks were referenced inside `vi.mock()` factories.
+- Real `getMemoryToolNames` / `getReadOnlyMemoryToolNames` worked as drop-in replacements with no test rework needed — the pure functions' behavior matched what the mocks were configured to return for all existing test scenarios.
+
+#### What caused friction (agent side)
+
+- `missing-context` — `mockBuildAgentPrompt` was declared as `vi.fn(() => "assembled system prompt")` which inferred `Mock<() => string>`.
+  When step 4 used `mockImplementationOnce` with a parameterized function, TypeScript rejected it.
+  The testing skill already documents `Mock<specific-signature>` for this exact case.
+  Impact: one type-check failure, fixed by adding `Mock<AssemblerIO["buildAgentPrompt"]>` annotation; added friction but no rework.
+
+#### What caused friction (user side)
+
+- Nothing notable — standard prompt-template workflow with no corrections needed.

package/package.json

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

package/src/agent-runner.ts

@@ -6,18 +6,12 @@ import type { Model } from "@earendil-works/pi-ai";
 import {
   type AgentSession,
   type AgentSessionEvent,
-  createAgentSession,
-  DefaultResourceLoader,
-  getAgentDir,
-  SessionManager,
-  SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import type { AgentConfigLookup } from "./agent-types.js";
 import { extractText } from "./context.js";
-import { detectEnv } from "./env.js";
+import type { EnvInfo } from "./env.js";
 import type { ParentSnapshot } from "./parent-snapshot.js";
-import { assembleSessionConfig } from "./session-config.js";
-import { deriveSubagentSessionDir } from "./session-dir.js";
+import { type AssemblerIO, assembleSessionConfig } from "./session-config.js";
 import type { ShellExec, SubagentType, ThinkingLevel } from "./types.js";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
@@ -65,6 +59,63 @@ export function normalizeMaxTurns(n: number | undefined): number | undefined {
   return Math.max(1, n);
 }
 
+// ── IO boundary ───────────────────────────────────────────────────────────────
+
+/** Minimal resource-loader contract used by the runner. */
+export interface ResourceLoaderLike {
+  reload(): Promise<void>;
+}
+
+/** Minimal session-manager contract used by the runner. */
+export interface SessionManagerLike {
+  newSession(opts: { parentSession?: string }): void;
+  getSessionFile(): string | undefined;
+}
+
+/** Options passed to RunnerIO.createResourceLoader. */
+export interface ResourceLoaderOptions {
+  cwd: string;
+  agentDir: string;
+  noExtensions?: boolean;
+  noSkills?: boolean;
+  noPromptTemplates?: boolean;
+  noThemes?: boolean;
+  noContextFiles?: boolean;
+  systemPromptOverride?: () => string;
+  appendSystemPromptOverride?: () => unknown[];
+}
+
+/** Options passed to RunnerIO.createSession. */
+export interface CreateSessionOptions {
+  cwd: string;
+  agentDir: string;
+  sessionManager: SessionManagerLike;
+  settingsManager: unknown;
+  modelRegistry: unknown;
+  model?: unknown;
+  tools: string[];
+  resourceLoader: ResourceLoaderLike;
+  thinkingLevel?: ThinkingLevel;
+}
+
+/**
+ * IO boundary injected into runAgent().
+ *
+ * Decouples the runner from direct Pi SDK imports and sibling-module IO,
+ * making it testable via plain stub objects without vi.mock().
+ */
+export interface RunnerIO {
+  detectEnv: (exec: ShellExec, cwd: string) => Promise<EnvInfo>;
+  getAgentDir: () => string;
+  createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoaderLike;
+  deriveSessionDir: (parentSessionFile: string | undefined, effectiveCwd: string) => string;
+  createSessionManager: (cwd: string, sessionDir: string) => SessionManagerLike;
+  createSettingsManager: (cwd: string, agentDir: string) => unknown;
+  createSession: (opts: CreateSessionOptions) => Promise<{ session: AgentSession }>;
+  assemblerIO: AssemblerIO;
+}
+
+// ── Public interfaces ─────────────────────────────────────────────────────────
 
 export interface RunOptions {
   /** Shell-exec callback for detectEnv — injected from pi.exec(). */
@@ -122,6 +173,20 @@ export interface AgentRunner {
   resume(session: AgentSession, prompt: string, options?: ResumeOptions): Promise<string>;
 }
 
+/**
+ * Create an AgentRunner backed by the given IO boundary.
+ *
+ * Captures io at construction time so AgentManager remains IO-unaware.
+ */
+export function createAgentRunner(io: RunnerIO): AgentRunner {
+  return {
+    run: (snapshot, type, prompt, options) => runAgent(snapshot, type, prompt, options, io),
+    resume: resumeAgent,
+  };
+}
+
+// ── Private helpers ───────────────────────────────────────────────────────────
+
 /**
  * Subscribe to a session and collect the last assistant message text.
  * Returns an object with a `getText()` getter and an `unsubscribe` function.
@@ -167,15 +232,18 @@ function forwardAbortSignal(
   return () => signal.removeEventListener("abort", onAbort);
 }
 
+// ── Public functions ──────────────────────────────────────────────────────────
+
 export async function runAgent(
   snapshot: ParentSnapshot,
   type: SubagentType,
   prompt: string,
   options: RunOptions,
+  io: RunnerIO,
 ): Promise<RunResult> {
   // Resolve working directory upfront — needed for detectEnv before assembly.
   const effectiveCwd = options.cwd ?? snapshot.cwd;
-  const env = await detectEnv(options.exec, effectiveCwd);
+  const env = await io.detectEnv(options.exec, effectiveCwd);
 
   // Assemble session configuration (synchronous, no SDK objects).
   const cfg = assembleSessionConfig(
@@ -194,9 +262,10 @@ export async function runAgent(
     },
     env,
     options.registry,
+    io.assemblerIO,
   );
 
-  const agentDir = getAgentDir();
+  const agentDir = io.getAgentDir();
 
   // Load extensions/skills: true or string[] → load; false → don't.
   // Suppress AGENTS.md/CLAUDE.md and APPEND_SYSTEM.md — upstream's
@@ -204,7 +273,7 @@ export async function runAgent(
   // would defeat prompt_mode: replace and isolated: true. Parent context, if
   // wanted, reaches the subagent via prompt_mode: append (parentSystemPrompt
   // is embedded in systemPromptOverride) or inherit_context (conversation).
-  const loader = new DefaultResourceLoader({
+  const loader = io.createResourceLoader({
     cwd: cfg.effectiveCwd,
     agentDir,
     noExtensions: cfg.extensions === false,
@@ -220,25 +289,21 @@ export async function runAgent(
   // Create a persisted SessionManager so transcripts are written in Pi's
   // official JSONL format. Falls back to a temp directory when the parent
   // session is not persisted (e.g. headless/API mode).
-  const sessionDir = deriveSubagentSessionDir(options.parentSessionFile, cfg.effectiveCwd);
-  const sessionManager = SessionManager.create(cfg.effectiveCwd, sessionDir);
+  const sessionDir = io.deriveSessionDir(options.parentSessionFile, cfg.effectiveCwd);
+  const sessionManager = io.createSessionManager(cfg.effectiveCwd, sessionDir);
   sessionManager.newSession({ parentSession: options.parentSessionId });
 
-  const sessionOpts: Parameters<typeof createAgentSession>[0] = {
+  const { session } = await io.createSession({
     cwd: cfg.effectiveCwd,
     agentDir,
     sessionManager,
-    settingsManager: SettingsManager.create(cfg.effectiveCwd, agentDir),
-    modelRegistry: snapshot.modelRegistry as any,
-    model: cfg.model as Model<any> | undefined,
+    settingsManager: io.createSettingsManager(cfg.effectiveCwd, agentDir),
+    modelRegistry: snapshot.modelRegistry,
+    model: cfg.model,
     tools: cfg.toolNames,
     resourceLoader: loader,
-  };
-  if (cfg.thinkingLevel) {
-    sessionOpts.thinkingLevel = cfg.thinkingLevel;
-  }
-
-  const { session } = await createAgentSession(sessionOpts);
+    thinkingLevel: cfg.thinkingLevel,
+  });
 
   // Filter active tools: remove our own tools to prevent nesting,
   // apply extension allowlist if specified, and apply disallowedTools denylist.

package/src/index.ts

@@ -11,19 +11,32 @@
  */
 
 import { join } from "node:path";
-import { defineTool, type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  defineTool,
+  type ExtensionAPI,
+  getAgentDir,
+  SettingsManager as SdkSettingsManager,
+  SessionManager,
+} from "@earendil-works/pi-coding-agent";
 import { AgentManager, type AgentManagerObserver } from "./agent-manager.js";
-import { getAgentConversation, resumeAgent, runAgent, steerAgent } from "./agent-runner.js";
+import { createAgentRunner, getAgentConversation, type RunnerIO, steerAgent } from "./agent-runner.js";
 import { AgentTypeRegistry } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
+import { detectEnv } from "./env.js";
 import { SessionLifecycleHandler, ToolStartHandler } from "./handlers/index.js";
+import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
 import { buildEventData, type NotificationDetails, NotificationManager } from "./notification.js";
+import { buildAgentPrompt } from "./prompts.js";
 import { createNotificationRenderer } from "./renderer.js";
 import { createSubagentRuntime } from "./runtime.js";
 import { publishSubagentsService, unpublishSubagentsService } from "./service.js";
 import { createSubagentsService } from "./service-adapter.js";
+import { deriveSubagentSessionDir } from "./session-dir.js";
 import { SettingsManager } from "./settings.js";
+import { preloadSkills } from "./skill-loader.js";
 import { createAgentTool } from "./tools/agent-tool.js";
 import { createGetResultTool } from "./tools/get-result-tool.js";
 import { getModelLabelFromConfig } from "./tools/helpers.js";
@@ -120,8 +133,24 @@ export default function (pi: ExtensionAPI) {
     },
   };
 
+  const runnerIO: RunnerIO = {
+    detectEnv,
+    getAgentDir,
+    createResourceLoader: (opts) => new DefaultResourceLoader(opts as any),
+    deriveSessionDir: deriveSubagentSessionDir,
+    createSessionManager: (cwd, dir) => SessionManager.create(cwd, dir),
+    createSettingsManager: (cwd, dir) => SdkSettingsManager.create(cwd, dir),
+    createSession: (opts) => createAgentSession(opts as any),
+    assemblerIO: {
+      preloadSkills,
+      buildMemoryBlock,
+      buildReadOnlyMemoryBlock,
+      buildAgentPrompt,
+    },
+  };
+
   const manager = new AgentManager({
-    runner: { run: runAgent, resume: resumeAgent },
+    runner: createAgentRunner(runnerIO),
     worktrees: new GitWorktreeManager(process.cwd()),
     exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
     registry,

package/src/session-config.ts

@@ -16,13 +16,42 @@ import {
   getReadOnlyMemoryToolNames,
 } from "./agent-types.js";
 import type { EnvInfo } from "./env.js";
-import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
-import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
-import { preloadSkills } from "./skill-loader.js";
-import type { SubagentType, ThinkingLevel } from "./types.js";
+import type { PromptExtras } from "./prompts.js";
+import type { PreloadedSkill } from "./skill-loader.js";
+import type {
+  AgentPromptConfig,
+  MemoryScope,
+  SubagentType,
+  ThinkingLevel,
+} from "./types.js";
 
 // ── Public interfaces ────────────────────────────────────────────────────────
 
+/**
+ * IO collaborators injected into `assembleSessionConfig`.
+ *
+ * Bundling the four IO-touching (or promptly testable) functions into a single
+ * interface keeps the assembler free of direct module imports and makes it
+ * trivially testable without `vi.mock()` — callers inject real implementations
+ * at the edge (`agent-runner.ts`) or stubs in tests.
+ */
+export interface AssemblerIO {
+  preloadSkills: (skills: string[], cwd: string) => PreloadedSkill[];
+  buildMemoryBlock: (name: string, scope: MemoryScope, cwd: string) => string;
+  buildReadOnlyMemoryBlock: (
+    name: string,
+    scope: MemoryScope,
+    cwd: string,
+  ) => string;
+  buildAgentPrompt: (
+    config: AgentPromptConfig,
+    cwd: string,
+    env: EnvInfo,
+    parentPrompt?: string,
+    extras?: PromptExtras,
+  ) => string;
+}
+
 /**
  * Narrow context the assembler reads from the parent session.
  * Tests construct plain objects satisfying this interface — no SDK mocking needed.
@@ -132,8 +161,8 @@ function resolveDefaultModel(
 /**
  * Assemble all configuration needed to create an agent session.
  *
- * Synchronous and side-effect-free (beyond calling `preloadSkills` which reads
- * the filesystem). The caller is responsible for resolving `EnvInfo` beforehand
+ * Synchronous and side-effect-free — all IO is delegated through the `io`
+ * parameter. The caller is responsible for resolving `EnvInfo` beforehand
  * via `detectEnv()`.
  *
  * @param type       The subagent type name (case-insensitive registry lookup).
@@ -141,6 +170,7 @@ function resolveDefaultModel(
  * @param options    Per-call overrides (cwd, isolated, model, thinkingLevel).
  * @param env        Pre-resolved environment info from `detectEnv()`.
  * @param registry   Agent config lookup — provides resolveAgentConfig and getToolNamesForType.
+ * @param io         IO collaborators (skill loader, memory builder, prompt builder).
  */
 export function assembleSessionConfig(
   type: SubagentType,
@@ -148,6 +178,7 @@ export function assembleSessionConfig(
   options: AssemblerOptions,
   env: EnvInfo,
   registry: AgentConfigLookup,
+  io: AssemblerIO,
 ): SessionConfig {
   const agentConfig = registry.resolveAgentConfig(type);
 
@@ -162,7 +193,7 @@ export function assembleSessionConfig(
 
   // Skill preloading: when skills is string[], preload their content into the prompt
   if (Array.isArray(skills)) {
-    const loaded = preloadSkills(skills, effectiveCwd);
+    const loaded = io.preloadSkills(skills, effectiveCwd);
     if (loaded.length > 0) {
       extras.skillBlocks = loaded;
     }
@@ -185,7 +216,7 @@ export function assembleSessionConfig(
     if (hasWriteTools) {
       const extraNames = getMemoryToolNames(existingNames);
       if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
-      extras.memoryBlock = buildMemoryBlock(
+      extras.memoryBlock = io.buildMemoryBlock(
         agentConfig.name,
         agentConfig.memory,
         effectiveCwd,
@@ -193,7 +224,7 @@ export function assembleSessionConfig(
     } else {
       const extraNames = getReadOnlyMemoryToolNames(existingNames);
       if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
-      extras.memoryBlock = buildReadOnlyMemoryBlock(
+      extras.memoryBlock = io.buildReadOnlyMemoryBlock(
         agentConfig.name,
         agentConfig.memory,
         effectiveCwd,
@@ -202,7 +233,7 @@ export function assembleSessionConfig(
   }
 
   // Build system prompt from the resolved agent config
-  const systemPrompt = buildAgentPrompt(
+  const systemPrompt = io.buildAgentPrompt(
     agentConfig,
     effectiveCwd,
     env,