@gotgenes/pi-subagents 6.10.0 → 6.11.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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)
 
 

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.
-`agent-runner.test.ts` accounts for 7 of 8 remaining `vi.mock()` calls and relies 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. (Step G resolved `session-config.test.ts`, which previously held 4 of the 12 total mocks.)
+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 |
-| 7 `vi.mock()` calls           | `agent-runner.test.ts`                                  | Runner imports prompts, memory, skills, env, session-dir 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                                       |
@@ -538,30 +537,17 @@ Impact: reduces test boilerplate; single source of truth for mock shapes; change
 ### Step G: Inject IO collaborators into session-config (#132) ✓ done
 
 `assembleSessionConfig` now accepts `io: AssemblerIO` as a required parameter.
-`agent-runner.ts` constructs the real `AssemblerIO` from direct imports and passes it through.
+`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.
 
-### Step H: Inject SDK boundary into agent-runner (#133)
+### Step H: Inject SDK boundary into agent-runner (#133) ✓ done
 
-`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.
+`runAgent()` now accepts `io: RunnerIO` as a required parameter bundling all IO collaborators: `detectEnv`, `getAgentDir`, `createResourceLoader`, `deriveSessionDir`, `createSessionManager`, `createSettingsManager`, `createSession`, and `assemblerIO`.
 
-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:
+`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.
 
-```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;
-}
-```
-
-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()`.
-
-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/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/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.10.0",
+  "version": "6.11.0",
   "exports": {
     ".": "./src/service.ts"
   },

package/src/agent-runner.ts

@@ -6,21 +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 { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
+import type { EnvInfo } from "./env.js";
 import type { ParentSnapshot } from "./parent-snapshot.js";
-import { buildAgentPrompt } from "./prompts.js";
 import { type AssemblerIO, assembleSessionConfig } from "./session-config.js";
-import { deriveSubagentSessionDir } from "./session-dir.js";
-import { preloadSkills } from "./skill-loader.js";
 import type { ShellExec, SubagentType, ThinkingLevel } from "./types.js";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
@@ -68,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(). */
@@ -125,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.
@@ -170,23 +232,20 @@ 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 io: AssemblerIO = {
-    preloadSkills,
-    buildMemoryBlock,
-    buildReadOnlyMemoryBlock,
-    buildAgentPrompt,
-  };
   const cfg = assembleSessionConfig(
     type,
     {
@@ -203,10 +262,10 @@ export async function runAgent(
     },
     env,
     options.registry,
-    io,
+    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
@@ -214,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,
@@ -230,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,