@gotgenes/pi-subagents 6.11.0 → 6.12.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.12.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.11.0...pi-subagents-v6.12.0) (2026-05-22)
+
+
+### Features
+
+* narrow runtime widget field to WidgetLike interface ([#134](https://github.com/gotgenes/pi-packages/issues/134)) ([afa70ab](https://github.com/gotgenes/pi-packages/commit/afa70ab430109248a8f61ccd182b0f3acd1fa7e1))
+* use SDK types in CreateSessionOptions ([#134](https://github.com/gotgenes/pi-packages/issues/134)) ([c2452af](https://github.com/gotgenes/pi-packages/commit/c2452af0ee3d47d778878443a634ca787f8d0bfb))
+
+
+### Bug Fixes
+
+* replace message-shape as-any casts with type guards ([#134](https://github.com/gotgenes/pi-packages/issues/134)) ([d7ad65a](https://github.com/gotgenes/pi-packages/commit/d7ad65a61267790ae1ae8414b0c2aa9ebc8ad59c))
+
+
+### Documentation
+
+* plan as-any cast reduction in test suite ([#134](https://github.com/gotgenes/pi-packages/issues/134)) ([f7cb1aa](https://github.com/gotgenes/pi-packages/commit/f7cb1aac0963021ae0545b73c88f950a7adb5fd2))
+* **retro:** add retro notes for issue [#133](https://github.com/gotgenes/pi-packages/issues/133) ([be32640](https://github.com/gotgenes/pi-packages/commit/be32640048943059a98fc79797a35dfefd70fc34))
+* update architecture doc for Step I completion ([#134](https://github.com/gotgenes/pi-packages/issues/134)) ([fd4aca7](https://github.com/gotgenes/pi-packages/commit/fd4aca79c74da2b8c4e3c58e2376e0612941d7d9))
+
 ## [6.11.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.10.0...pi-subagents-v6.11.0) (2026-05-22)
 
 

package/docs/architecture/architecture.md

@@ -517,7 +517,7 @@ They are included here because the display extraction unblocks menu decompositio
 | ----------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------- |
 | ~~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     |
+| ~~52 `as any` casts~~         | ~~Across test suite~~                                   | ~~Reduced to 15 by Step I (#134)~~                                |
 | 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                                       |
 | Weak assertions               | lifecycle, renderer, session-config tests               | `toHaveBeenCalled()` without args, `toContain()` on large strings |
@@ -549,16 +549,20 @@ Impact: reduces test boilerplate; single source of truth for mock shapes; change
 
 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)
+### Step I: Reduce `as any` casts in tests (#134) ✓ done
 
-With Steps G and H, many `as any` casts disappear because tests construct narrow injectable interfaces instead of wide SDK types.
-Remaining casts are addressed by:
+Reduced `as any` count from 93 to 15 (plus 13 explicit `as unknown as T` bridge casts).
 
-1. Defining a `TestSession` type in `test/helpers/` that satisfies `SubscribableSession` + the fields tests actually read.
-2. Replacing `const mockCtx = { cwd: "/tmp" } as any` with properly typed `AssemblerContext` or `ParentSnapshot` objects.
-3. Using `satisfies` assertions where possible instead of `as any`.
+Production changes:
 
-Target: reduce `as any` count from 52 to under 10.
+- `ResourceLoaderOptions.appendSystemPromptOverride` typed to match `DefaultResourceLoaderOptions`; `createResourceLoader` factory cast removed from `index.ts`.
+- `CreateSessionOptions.settingsManager` / `RunnerIO.createSettingsManager` typed as `SettingsManager`.
+- `WidgetLike` interface in `runtime.ts` narrows the widget field.
+- Local `ToolCallContent` / `BashExecutionMessage` type guards replace `as any` duck-typing in `conversation-viewer.ts` and `agent-runner.ts`.
+- `textResult()` return no longer casts `details as any`.
+- `toAgentSession()` helper and `STUB_CTX` constant centralise unavoidable bridge casts.
+
+Remaining 15 `as any` casts are: 8 menu-handler `ctx as any` (deferred — requires `AgentManager.spawn` to accept `ParentSnapshot` directly), 2 `print-mode.test.ts` (same ExtensionContext/API pattern), 2 private-field test access, 1 `createSession` SDK bridge in `index.ts`, 1 `foreground-runner.ts` `AgentToolResult<any>` detail, 1 `stub-ctx.ts` comment.
 
 ### Step J: Extract display helpers (#135)
 

package/docs/plans/0134-reduce-as-any-casts.md

@@ -0,0 +1,366 @@
+---
+issue: 134
+issue_title: "Reduce `as any` casts in test suite"
+---
+
+# Reduce as-any casts in test suite
+
+## Problem Statement
+
+The test suite contains 93 `as any` casts (plus 2 `as any[]`).
+These casts silence the type checker, hiding real errors — if a production interface adds a required field, tests silently pass with incomplete mocks instead of failing at compile time.
+The heaviest offenders are `renderer.test.ts` (29), `runtime.test.ts` (10), `agent-menu.test.ts` (8), and `helpers.test.ts` (7).
+The production source has 8 `as any` casts — 2 SDK bridge casts in `index.ts` and 6 message-shape casts in `conversation-viewer.ts` and `agent-runner.ts`.
+
+## Goals
+
+- Target near-zero `as any` casts across both source and test code.
+- Widen `CreateSessionOptions` and `ResourceLoaderOptions` to use SDK types, eliminating the SDK bridge casts in `index.ts`.
+- Define local message-content types and type guards in `conversation-viewer.ts` and `agent-runner.ts`, eliminating polymorphic duck-typing casts.
+- Define narrow production interfaces (`MenuCtx`, `WidgetLike`) where SDK types are too wide for test construction.
+- Define typed test factories where partial mocks currently require casting.
+- Preserve existing test coverage — no behavior changes.
+
+## Non-Goals
+
+- Changing production behavior or public API shapes.
+- Reaching literally zero — 1–3 casts may remain for private-field test access (`(manager as any).cleanupInterval`) where the alternative (exposing internals) is worse than the cast.
+
+## Background
+
+### Prerequisites
+
+Issues #132 and #133 (IO injection) are both closed.
+These eliminated the `vi.mock()`-heavy test patterns and introduced narrow injectable interfaces (`AssemblerIO`, `RunnerIO`), which already removed some `as any` casts from `agent-runner.test.ts` and `session-config.test.ts`.
+
+### Current as-any inventory by pattern
+
+| Pattern                                          | Count | Primary files                                                                                                       |
+| ------------------------------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------- |
+| Renderer — theme, message, result access         | 29    | `renderer.test.ts`                                                                                                  |
+| Context — `ctx as any` for handler/menu          | 14    | `agent-menu.test.ts`, `agent-manager.test.ts`, `print-mode.test.ts`, `parent-snapshot.test.ts`, `make-deps.test.ts` |
+| Session — `{ session: {} as any }`               | 10    | tool tests, `service-adapter.test.ts`, `print-mode.test.ts`, `agent-manager.test.ts`                                |
+| Runtime/widget — `fakeWidget as any`             | 9     | `runtime.test.ts`                                                                                                   |
+| Conversation viewer — message shapes             | 8     | `conversation-viewer.test.ts`, `src/conversation-viewer.ts`                                                         |
+| Helpers — registry, activity, details            | 7     | `helpers.test.ts`                                                                                                   |
+| RunOptions — `} as any, io)`                     | 3     | `agent-runner.test.ts`                                                                                              |
+| Tool execute — `{} as any` for ctx               | 5     | `steer-tool.test.ts`, `get-result-tool.test.ts`, `make-deps.test.ts`                                                |
+| SDK bridge — `opts as any` in index.ts           | 2     | `src/index.ts`                                                                                                      |
+| Other — `messages: [] as any[]`, internal access | 6     | `agent-runner*.test.ts`, `usage.test.ts`, `agent-manager.test.ts`                                                   |
+
+### Constraints from AGENTS.md
+
+- Avoid `any` unless absolutely necessary.
+- Prefer explicit configuration over hidden behavior.
+- Keep scope tight; prefer small, reversible changes.
+
+## Design Overview
+
+### Production changes that make the test changes easy
+
+Three targeted source-code changes remove the structural blockers that force casts elsewhere.
+
+#### 1. SDK-typed option interfaces (eliminates 2 source casts)
+
+`CreateSessionOptions` and `ResourceLoaderOptions` currently use `unknown` for opaque fields (`settingsManager`, `modelRegistry`, `model`).
+Tests never construct these option objects — they mock `io.createSession` and `io.createResourceLoader` at the function level.
+The `unknown` fields don't buy testability; the function-level mock does.
+
+The SDK exports `CreateAgentSessionOptions` with all fields optional, using `ModelRegistry`, `Model<any>`, `ResourceLoader`, `SessionManager`, `SettingsManager`.
+Widening `CreateSessionOptions` to use these SDK types makes the `as any` cast in `index.ts` unnecessary while preserving full test mockability.
+
+```typescript
+// Before (agent-runner.ts)
+export interface CreateSessionOptions {
+  settingsManager: unknown;
+  modelRegistry: unknown;
+  model?: unknown;
+  // ...
+}
+
+// After — use SDK types (type-only imports)
+import type { Model } from "@earendil-works/pi-ai";
+import type {
+  ModelRegistry,
+  ResourceLoader,
+  SessionManager,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+
+export interface CreateSessionOptions {
+  settingsManager: SettingsManager;
+  modelRegistry: ModelRegistry;
+  model?: Model<any>;
+  resourceLoader: ResourceLoader;
+  sessionManager: SessionManager;
+  // ...
+}
+```
+
+The `RunnerIO.createSettingsManager` return type also changes from `unknown` to `SettingsManager`.
+
+For `ResourceLoaderOptions`, the options are all primitives and callbacks — the SDK's `DefaultResourceLoader` constructor accepts them structurally.
+The fix is to ensure the option interface matches the constructor's parameter type so `new DefaultResourceLoader(opts)` works without `as any`.
+
+#### 2. Local message-content types + type guards (eliminates 6 source casts)
+
+`conversation-viewer.ts` and `agent-runner.ts` both do:
+
+```typescript
+(c as any).name ?? (c as any).toolName ?? "unknown"
+(msg as any).role === "bashExecution"
+const bash = msg as any;
+```
+
+Fix: define local discriminated-union types for the content items and message roles the code actually handles, plus type guards:
+
+```typescript
+/** Tool-call content item — SDK doesn't export a narrow type for this variant. */
+interface ToolCallContent {
+  type: "toolCall";
+  name?: string;
+  toolName?: string;
+}
+
+function getToolCallName(c: { type: string }): string | undefined {
+  if (c.type !== "toolCall") return undefined;
+  const tc = c as ToolCallContent;
+  return tc.name ?? tc.toolName;
+}
+
+/** Bash execution message — not in the standard role union. */
+interface BashExecutionMessage {
+  role: "bashExecution";
+  command: string;
+  output?: string;
+}
+
+function isBashExecution(msg: { role: string }): msg is BashExecutionMessage {
+  return msg.role === "bashExecution";
+}
+```
+
+These are small, file-local types that document the shapes the code already handles at runtime.
+They make the duck-typing explicit and compile-time checked.
+
+#### 3. Narrow production interfaces (`MenuCtx`, `WidgetLike`)
+
+Already described in the test-side patterns below.
+These are production-code changes that make the test-side casts disappear.
+
+### Test-side patterns
+
+#### Pattern A: renderer.test.ts (29 casts → 0)
+
+The renderer already defines narrow interfaces (`RendererMessage`, `RendererTheme`, `RenderOptions`).
+The test casts because it doesn't use them — `stubTheme()` and `{ details: makeDetails() }` already satisfy the interfaces structurally.
+The return type `Text` has a `.text` property — `(result as any).text` can become `result!.text` (non-null assertion after `expect(result).toBeDefined()`).
+
+Fix: remove the casts; structural typing handles it.
+For result access, define a minimal `{ text: string }` type or use non-null assertion.
+
+#### Pattern B: context casts (14 casts → 0)
+
+- `agent-menu.test.ts` (8): define `MenuCtx` in production; type `makeCtx()` return.
+- `agent-manager.test.ts` (1): `mockCtx` is consumed by a mocked `buildParentSnapshot` — type as `unknown`.
+- `parent-snapshot.test.ts` (1): define a test-local interface matching the fields `buildParentSnapshot` reads.
+- `print-mode.test.ts` (2): type `makeHeadlessCtx()` return.
+- `runtime.test.ts` (1): pass a structurally valid `UICtx` (fixed by `WidgetLike` step).
+- `make-deps.test.ts` (3): type ctx args or use `unknown`.
+
+#### Pattern C: session casts (10 casts → ~1)
+
+Most are `{ session: {} as any, outputFile: ... }` for `record.execution`.
+Fix: expand `createMockSession()` to include the fields these tests need (`dispose`, `steer`, `getSessionStats`), then use it.
+One cast may remain for truly minimal session stubs.
+
+#### Pattern D: runtime/widget casts (9 casts → 0)
+
+Define `WidgetLike` in `runtime.ts`; change the `widget` field type.
+Use real `AgentActivityTracker` instances (constructor takes only `maxTurns?`).
+
+#### Pattern E: tool-execute ctx casts (5 casts → 0)
+
+Define a `STUB_CTX` constant in `test/helpers/` satisfying the tool execute's context parameter.
+
+#### Pattern F: RunOptions casts (3 casts → 0)
+
+Check whether `defaultMaxTurns` and `graceTurns` are on `RunOptions` — they are.
+The `as any` casts are vestigial; remove them.
+
+#### Pattern G: helpers.test.ts (7 casts → 0)
+
+Construct typed `TypeListRegistry` mocks.
+Fix `textResult` return type to avoid `details as any`.
+Use real `AgentActivityTracker` instances.
+
+#### Pattern H: conversation-viewer test casts (4 test casts → ~1)
+
+Type message mock objects using the local types from production change #2.
+Keep `(viewer as any).buildContentLines()` (private method access — the alternative of exposing the method is worse).
+
+#### Pattern I: other (6 casts → ~2)
+
+- `messages: [] as any[]` → type as `unknown[]`.
+- `(manager as any).cleanupInterval` → keep (private field assertion is intentional).
+- `usage.test.ts` (2) → type mock objects.
+
+## Module-Level Changes
+
+### Modified source files
+
+1. `src/agent-runner.ts`
+   - Import SDK types (`Model`, `ModelRegistry`, `SettingsManager`, `SessionManager`, `ResourceLoader`) as type-only imports.
+   - Widen `CreateSessionOptions` fields from `unknown` to SDK types.
+   - Change `RunnerIO.createSettingsManager` return type from `unknown` to `SettingsManager`.
+   - Define `getToolCallName()` helper and local `ToolCallContent` interface.
+   - Replace `(c as any).name ?? (c as any).toolName` with `getToolCallName(c)` in `getAgentConversation`.
+
+2. `src/ui/conversation-viewer.ts`
+   - Define local `ToolCallContent`, `BashExecutionMessage` interfaces and type guards.
+   - Replace `(c as any).name ?? (c as any).toolName` with typed helper.
+   - Replace `(msg as any).role === "bashExecution"` / `const bash = msg as any` with type guard.
+
+3. `src/ui/agent-menu.ts`
+   - Define and export `MenuCtx` interface.
+   - Change handler parameter type from `ExtensionContext` to `MenuCtx`.
+
+4. `src/runtime.ts`
+   - Define and export `WidgetLike` interface.
+   - Change `widget` field type from `AgentWidget | null` to `WidgetLike | null`.
+
+5. `src/tools/helpers.ts`
+   - Change `textResult` to avoid `details as any` — type the return properly.
+
+6. `src/index.ts`
+   - Remove `opts as any` casts in `createResourceLoader` and `createSession` factories (enabled by SDK-typed option interfaces).
+
+### Modified test files
+
+1. `test/renderer.test.ts` — remove all 29 casts.
+2. `test/runtime.test.ts` — use `WidgetLike` stubs and real `AgentActivityTracker`.
+3. `test/ui/agent-menu.test.ts` — type `makeCtx()` as `MenuCtx`.
+4. `test/tools/helpers.test.ts` — typed registry mocks, real `AgentActivityTracker`.
+5. `test/conversation-viewer.test.ts` — typed message mocks.
+6. `test/agent-runner.test.ts` — remove `as any` on RunOptions; type messages.
+7. `test/agent-runner-extension-tools.test.ts` — type messages.
+8. `test/agent-manager.test.ts` — type `mockCtx`.
+9. `test/print-mode.test.ts` — type `makeHeadlessCtx()`.
+10. `test/parent-snapshot.test.ts` — type mock context.
+11. `test/service-adapter.test.ts` — use `createMockSession()`.
+12. `test/tools/steer-tool.test.ts` — stub ctx, use `createMockSession()`.
+13. `test/tools/get-result-tool.test.ts` — stub ctx, use `createMockSession()`.
+14. `test/tools/foreground-runner.test.ts` — use `createMockSession()`.
+15. `test/tools/background-spawner.test.ts` — use `createMockSession()`.
+16. `test/tools/agent-tool.test.ts` — use `createMockSession()`.
+17. `test/helpers/make-deps.test.ts` — type ctx args.
+18. `test/usage.test.ts` — type mock objects.
+
+## Test Impact Analysis
+
+1. No new test coverage — this is a type-safety improvement on existing tests.
+2. No tests become redundant.
+3. All existing tests stay as-is in terms of assertions; only type annotations and mock construction change.
+4. `pnpm run check` is the primary validation — every step must pass type checking since the goal is eliminating type holes.
+5. Expanding `createMockSession()` affects multiple consumers — diff existing defaults before changing (per testing skill).
+
+## TDD Order
+
+Steps are ordered by independence and impact (production changes first, then largest cast-count test reductions).
+
+1. **Widen option interfaces to SDK types; remove index.ts casts (2 source casts → 0).**
+   Import SDK types as type-only in `agent-runner.ts`.
+   Widen `CreateSessionOptions` fields (`settingsManager`, `modelRegistry`, `model`, `resourceLoader`, `sessionManager`) to SDK types.
+   Change `RunnerIO.createSettingsManager` return type to `SettingsManager`.
+   Remove `as any` casts from `index.ts` factories.
+   Run `pnpm run check` + full suite.
+   Commit: `feat: use SDK types in CreateSessionOptions (#134)`
+
+2. **Add message-content type guards; remove viewer and runner source casts (6 source casts → 0).**
+   Define `ToolCallContent` interface and `getToolCallName()` helper in `conversation-viewer.ts`.
+   Define `BashExecutionMessage` interface and `isBashExecution()` guard in `conversation-viewer.ts`.
+   Replace all source `as any` casts in `conversation-viewer.ts`.
+   Define the same `getToolCallName()` helper (or extract a shared one) in `agent-runner.ts` and replace its cast.
+   Run `pnpm run check` + affected tests.
+   Commit: `fix: replace message-shape as-any casts with type guards (#134)`
+
+3. **Remove renderer test casts (29 → 0).**
+   Remove all `as any` casts on `stubTheme()`, message objects, and result access.
+   Use `result!.text` (non-null assertion after `toBeDefined()` guard) for result access.
+   Run `pnpm run check` + `pnpm vitest run test/renderer.test.ts`.
+   Commit: `test: remove as-any casts in renderer tests (#134)`
+
+4. **Add `MenuCtx` interface; remove menu-test casts (8 → 0).**
+   Define `MenuCtx` in `agent-menu.ts`.
+   Change handler parameter from `ExtensionContext` to `MenuCtx`.
+   Type `makeCtx()` return in test.
+   Run `pnpm run check` + `pnpm vitest run test/ui/agent-menu.test.ts`.
+   Commit: `feat: narrow menu handler to MenuCtx interface (#134)`
+
+5. **Add `WidgetLike`; remove runtime casts (9 → 0).**
+   Define `WidgetLike` in `runtime.ts`.
+   Change `widget` field type.
+   Update `runtime.test.ts`: typed stubs, real `AgentActivityTracker` instances.
+   Run `pnpm run check` + `pnpm vitest run test/runtime.test.ts`.
+   Commit: `feat: narrow runtime widget field to WidgetLike interface (#134)`
+
+6. **Expand `createMockSession`; remove session casts (10 → ~1).**
+   Add fields to `createMockSession()` that tool/service tests need.
+   Use it in tool tests, service-adapter, agent-manager for `record.execution.session`.
+   Run `pnpm run check` + full suite.
+   Commit: `test: use createMockSession for session execution casts (#134)`
+
+7. **Remove helpers.test.ts casts (7 → 0).**
+   Typed `TypeListRegistry` mocks.
+   Fix `textResult` return type in `src/tools/helpers.ts`.
+   Real `AgentActivityTracker` instances.
+   Run `pnpm run check` + `pnpm vitest run test/tools/helpers.test.ts`.
+   Commit: `test: remove as-any casts in helpers tests (#134)`
+
+8. **Remove context casts across remaining test files (6 → 0).**
+   Type `mockCtx` in `agent-manager.test.ts`.
+   Type `makeHeadlessCtx()` in `print-mode.test.ts`.
+   Type mock context in `parent-snapshot.test.ts`.
+   Type `{} as any` in `make-deps.test.ts`.
+   Run `pnpm run check` + full suite.
+   Commit: `test: remove remaining context as-any casts (#134)`
+
+9. **Remove RunOptions and message-array casts (5 → 0).**
+   Remove vestigial `as any` on RunOptions objects.
+   Type `messages` arrays as `unknown[]`.
+   Run `pnpm run check` + affected tests.
+   Commit: `test: remove RunOptions and message-array casts (#134)`
+
+10. **Remove tool-execute ctx casts (5 → 0).**
+    Define `STUB_CTX` in `test/helpers/`.
+    Use it in `steer-tool.test.ts`, `get-result-tool.test.ts`, `make-deps.test.ts`.
+    Run `pnpm run check` + affected tests.
+    Commit: `test: remove tool-execute context casts (#134)`
+
+11. **Clean up conversation-viewer test and usage casts (6 → ~2).**
+    Type message mocks in `conversation-viewer.test.ts`.
+    Type usage mock objects in `usage.test.ts`.
+    Keep `(viewer as any).buildContentLines()` and `(manager as any).cleanupInterval` (private access, intentional).
+    Run `pnpm run check` + full suite.
+    Commit: `test: remove conversation-viewer and usage as-any casts (#134)`
+
+## Risks and Mitigations
+
+| Risk                                                                                            | Mitigation                                                                                                                                                                       |
+| ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Widening `CreateSessionOptions` to SDK types re-couples `agent-runner.ts` to SDK                | These are type-only imports — no runtime coupling. Tests still mock at the `RunnerIO` function level. The `RunnerIO` interface is the decoupling boundary, not the option types. |
+| Narrowing `widget` to `WidgetLike` could break callers accessing `AgentWidget`-specific methods | Grep all `runtime.widget` access sites first; verify they only use `update()`, `markFinished()`, `setUICtx()`.                                                                   |
+| Narrowing menu handler to `MenuCtx` could break callers passing `ExtensionContext`              | `ExtensionContext` is structurally a superset of `MenuCtx` — callers pass it unchanged.                                                                                          |
+| Expanding `createMockSession()` could break consumers with different default expectations       | Diff existing consumers' default expectations before adding fields (per testing skill).                                                                                          |
+| Message type guards add code to conversation-viewer and agent-runner                            | Each guard is 2–4 lines; they replace unsafe `as any` access with documented, compile-checked types. Net code stays similar.                                                     |
+| 11-step plan is large                                                                           | Each step is independently committable. No step depends on a subsequent one. Steps can be reordered or skipped.                                                                  |
+
+## Open Questions
+
+- Should `getToolCallName()` be shared between `conversation-viewer.ts` and `agent-runner.ts`, or duplicated?
+  Both files handle the same SDK message shape.
+  A shared helper in a common module (e.g., `context.ts` which already has `extractText`) avoids duplication.
+  Alternatively, the duplication is cheap (3 lines) and the two files have different concerns.
+- Should `STUB_CTX` live in `test/helpers/stub-ctx.ts` or inline?
+  Centralize — 3+ tool tests share the pattern.
+- Estimated final count: 2–3 remaining casts (`(viewer as any).buildContentLines()`, `(manager as any).cleanupInterval`, possibly 1 more for an unexported SDK type).

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

@@ -0,0 +1,45 @@
+---
+issue: 133
+issue_title: "Inject SDK boundary into `agent-runner`"
+---
+
+# Retro: #133 — Inject SDK boundary into agent-runner
+
+## Final Retrospective (2026-05-22T13:15:00Z)
+
+### Session summary
+
+Injected all SDK and IO dependencies into `runAgent()` via a `RunnerIO` interface and `createAgentRunner(io)` factory.
+Eliminated all 14 `vi.mock()` calls across `agent-runner.test.ts` (7) and `agent-runner-extension-tools.test.ts` (7).
+Released as `pi-subagents-v6.11.0`.
+
+### Observations
+
+#### What went well
+
+- The `createAgentRunner(io)` factory pattern was a clean design choice that kept the `AgentRunner` interface and `AgentManager` completely unchanged — zero downstream impact.
+- Folding plan steps 1 and 2 into a single commit was the right call given `tsconfig.json` includes `test/` — recognized the constraint before attempting a broken intermediate commit.
+
+#### What caused friction (agent side)
+
+1. `wrong-abstraction` — Annotated `createRunnerIO(): RunnerIO` in the test helper, which erased the `Mock<...>` type information from `vi.fn()` stubs.
+   TypeScript then rejected `.mockResolvedValue()` on `io.createSession` across 18 call sites.
+   Required removing the annotation plus a follow-up edit to remove the now-unused `type RunnerIO` import flagged by Biome.
+   Impact: two extra edit rounds and a type-check cycle before the fix landed.
+
+2. `missing-context` — Added `SettingsManager` to the SDK import block in `index.ts` without checking that the name was already imported from `./settings.js`.
+   Biome caught the redeclaration and the `noRedeclare` lint error required an alias fix (`SettingsManager as SdkSettingsManager`).
+   Impact: one extra edit round triggered by the autoformat failure.
+
+3. `premature-convergence` — Spent excessive reasoning time deliberating commit-boundary strategy (whether to combine steps 1+2, how to handle broken intermediate states, whether step 4 would have remaining work).
+   The answer was straightforward once the `tsconfig` `include` was checked, but the check came late in the deliberation.
+   Impact: added friction but no rework — the final decision was correct.
+
+#### What caused friction (user side)
+
+- None identified.
+  The plan and issue were well-specified, and the user's only intervention was "Please, continue" after a message boundary, which was appropriate.
+
+### Changes made
+
+1. `.pi/skills/testing/SKILL.md` — added rule: do not annotate test factory return types with production interface types (erases `Mock<...>` methods).

package/package.json

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

package/src/agent-runner.ts

@@ -6,6 +6,7 @@ import type { Model } from "@earendil-works/pi-ai";
 import {
   type AgentSession,
   type AgentSessionEvent,
+  type SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import type { AgentConfigLookup } from "./agent-types.js";
 import { extractText } from "./context.js";
@@ -17,6 +18,23 @@ import type { ShellExec, SubagentType, ThinkingLevel } from "./types.js";
 /** Names of tools registered by this extension that subagents must NOT inherit. */
 const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
 
+// ── Local message-shape types ───────────────────────────────────────────────
+// The Pi SDK does not export a narrow type for tool-call content variants.
+
+/** Tool-call content item — SDK exposes this variant at runtime but doesn’t export the narrow type. */
+interface ToolCallContent {
+  type: "toolCall";
+  name?: string;
+  toolName?: string;
+}
+
+/** Extracts the display name from a tool-call content item. */
+function getToolCallName(c: { type: string }): string {
+  if (c.type !== "toolCall") return "unknown";
+  const tc = c as ToolCallContent;
+  return tc.name ?? tc.toolName ?? "unknown";
+}
+
 /**
  * Filter the session's active tool names according to extension/denylist rules.
  *
@@ -82,7 +100,8 @@ export interface ResourceLoaderOptions {
   noThemes?: boolean;
   noContextFiles?: boolean;
   systemPromptOverride?: () => string;
-  appendSystemPromptOverride?: () => unknown[];
+  /** Override the append system prompt. Receives the current base value; return the replacement. */
+  appendSystemPromptOverride?: (base: string[]) => string[];
 }
 
 /** Options passed to RunnerIO.createSession. */
@@ -90,7 +109,7 @@ export interface CreateSessionOptions {
   cwd: string;
   agentDir: string;
   sessionManager: SessionManagerLike;
-  settingsManager: unknown;
+  settingsManager: SettingsManager;
   modelRegistry: unknown;
   model?: unknown;
   tools: string[];
@@ -110,7 +129,7 @@ export interface RunnerIO {
   createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoaderLike;
   deriveSessionDir: (parentSessionFile: string | undefined, effectiveCwd: string) => string;
   createSessionManager: (cwd: string, sessionDir: string) => SessionManagerLike;
-  createSettingsManager: (cwd: string, agentDir: string) => unknown;
+  createSettingsManager: (cwd: string, agentDir: string) => SettingsManager;
   createSession: (opts: CreateSessionOptions) => Promise<{ session: AgentSession }>;
   assemblerIO: AssemblerIO;
 }
@@ -446,9 +465,7 @@ export function getAgentConversation(session: AgentSession): string {
       for (const c of msg.content) {
         if (c.type === "text" && c.text) textParts.push(c.text);
         else if (c.type === "toolCall")
-          toolCalls.push(
-            `  Tool: ${(c as any).name ?? (c as any).toolName ?? "unknown"}`,
-          );
+          toolCalls.push(`  Tool: ${getToolCallName(c)}`);
       }
       if (textParts.length > 0)
         parts.push(`[Assistant]: ${textParts.join("\n")}`);

package/src/index.ts

@@ -136,7 +136,7 @@ export default function (pi: ExtensionAPI) {
   const runnerIO: RunnerIO = {
     detectEnv,
     getAgentDir,
-    createResourceLoader: (opts) => new DefaultResourceLoader(opts as any),
+    createResourceLoader: (opts) => new DefaultResourceLoader(opts),
     deriveSessionDir: deriveSubagentSessionDir,
     createSessionManager: (cwd, dir) => SessionManager.create(cwd, dir),
     createSettingsManager: (cwd, dir) => SdkSettingsManager.create(cwd, dir),

package/src/runtime.ts

@@ -7,7 +7,19 @@
  */
 
 import type { AgentActivityTracker } from "./ui/agent-activity-tracker.js";
-import type { AgentWidget, UICtx } from "./ui/agent-widget.js";
+import type { UICtx } from "./ui/agent-widget.js";
+
+/**
+ * Narrow widget interface consumed by SubagentRuntime delegation methods.
+ * AgentWidget satisfies this structurally; tests use plain stubs.
+ */
+export interface WidgetLike {
+  setUICtx(ctx: UICtx): void;
+  onTurnStart(): void;
+  markFinished(id: string): void;
+  update(): void;
+  ensureTimer(): void;
+}
 
 /**
  * Narrow config subset read by AgentManager when constructing RunOptions.
@@ -37,7 +49,7 @@ export class SubagentRuntime {
    * Persistent widget reference. Null until constructed after AgentManager.
    * Delegation methods use optional chaining so callers never need `widget!`.
    */
-  widget: AgentWidget | null = null;
+  widget: WidgetLike | null = null;
 
   // ── Session-context methods ──────────────────────────────────────────────
 

package/src/tools/agent-tool.ts

@@ -21,7 +21,7 @@ import {
 } from "../ui/agent-widget.js";
 import { spawnBackground } from "./background-spawner.js";
 import { runForeground } from "./foreground-runner.js";
-import { buildDetails, buildTypeListText, formatLifetimeTokens, getStatusNote, textResult } from "./helpers.js";
+import { buildDetails, buildTypeListText, textResult } from "./helpers.js";
 
 // ---- Deps interface ----
 

package/src/tools/helpers.ts

@@ -48,7 +48,7 @@ export function buildDetails(
 
 /** Tool execute return value for a text response. */
 export function textResult(msg: string, details?: unknown) {
-  return { content: [{ type: "text" as const, text: msg }], details: details as any };
+  return { content: [{ type: "text" as const, text: msg }], details };
 }
 
 /** Format an agent's lifetime token total, or "" when zero. */

package/src/ui/conversation-viewer.ts

@@ -14,6 +14,37 @@ import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
 import type { AgentActivityTracker } from "./agent-activity-tracker.js";
 import { buildInvocationTags, describeActivity, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel, type Theme } from "./agent-widget.js";
 
+// ── Local message-shape types ───────────────────────────────────────────────
+// The Pi SDK does not export narrow types for all message content variants.
+// These file-local types document the runtime shapes this module handles.
+
+/** Tool-call content item — SDK exposes this variant at runtime but doesn't export the narrow type. */
+interface ToolCallContent {
+  type: "toolCall";
+  name?: string;
+  toolName?: string;
+}
+
+/** Extracts the tool name from a content item, falling back to 'unknown'. */
+function getToolCallName(c: { type: string }): string {
+  if (c.type !== "toolCall") return "unknown";
+  const tc = c as ToolCallContent;
+  return tc.name ?? tc.toolName ?? "unknown";
+}
+
+/** Bash execution message — 'bashExecution' role is not in the SDK's AgentSession message role union. */
+interface BashExecutionMessage {
+  role: "bashExecution";
+  command: string;
+  output?: string;
+}
+
+function isBashExecution(msg: { role: string }): msg is BashExecutionMessage {
+  return msg.role === "bashExecution";
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
 /** Base lines consumed by chrome: top border + header + header sep + footer sep + footer + bottom border. */
 const CHROME_LINES_BASE = 6;
 const MIN_VIEWPORT = 3;
@@ -228,7 +259,7 @@ export class ConversationViewer implements Component {
         for (const c of msg.content) {
           if (c.type === "text" && c.text) textParts.push(c.text);
           else if (c.type === "toolCall") {
-            toolCalls.push((c as any).name ?? (c as any).toolName ?? "unknown");
+            toolCalls.push(getToolCallName(c));
           }
         }
         if (needsSeparator) lines.push(th.fg("dim", "───"));
@@ -250,14 +281,13 @@ export class ConversationViewer implements Component {
         for (const line of wrapTextWithAnsi(truncated.trim(), width)) {
           lines.push(th.fg("dim", line));
         }
-      } else if ((msg as any).role === "bashExecution") {
-        const bash = msg as any;
+      } else if (isBashExecution(msg)) {
         if (needsSeparator) lines.push(th.fg("dim", "───"));
-        lines.push(truncateToWidth(th.fg("muted", `  $ ${bash.command}`), width));
-        if (bash.output?.trim()) {
-          const out = bash.output.length > 500
-            ? bash.output.slice(0, 500) + "... (truncated)"
-            : bash.output;
+        lines.push(truncateToWidth(th.fg("muted", `  $ ${msg.command}`), width));
+        if (msg.output?.trim()) {
+          const out = msg.output.length > 500
+            ? msg.output.slice(0, 500) + "... (truncated)"
+            : msg.output;
           for (const line of wrapTextWithAnsi(out.trim(), width)) {
             lines.push(th.fg("dim", line));
           }