@gotgenes/pi-subagents 18.0.0 → 18.0.2

package/docs/plans/0057-structured-debug-logging.md

@@ -1,154 +0,0 @@
----
-issue: 57
-issue_title: "feat: structured debug logging for silenced catch blocks"
----
-
-# Structured debug logging for silenced catch blocks
-
-## Problem Statement
-
-The codebase contains ~20 `catch { /* ignore */ }` blocks spread across `agent-manager.ts`, `worktree.ts`, `output-file.ts`, `skill-loader.ts`, `custom-agents.ts`, `memory.ts`, `env.ts`, and `notification.ts`.
-Each block correctly suppresses a non-essential side-effect failure, but in development the silence makes it impossible to diagnose what is actually failing inside those paths.
-
-## Goals
-
-- Add a `debugLog(context, err)` utility in `src/debug.ts` gated on
-  `PI_SUBAGENTS_DEBUG=1`.
-- Thread `debugLog` into every silenced `catch` block listed in the issue scope.
-- Leave production behavior **completely unchanged** — no new log output unless
-  the env var is explicitly set.
-- Provide a `debug.test.ts` unit test covering the on/off branching.
-
-## Non-Goals
-
-- `usage.ts` catch blocks — they return `0`/`null` on failure and are already
-  recoverable, not truly "silent drops"; they are out of scope.
-- `settings.ts` catch block — it returns `false` on failure, already surfaced
-  to the caller; out of scope.
-- Log rotation, structured JSON output, or stderr vs. stdout routing.
-- Wiring debug output to the Pi UI; `console.warn` to stderr is sufficient.
-
-## Background
-
-The `AGENTS.md` rule "prefer explicit configuration over hidden behavior" aligns with gating noise behind an opt-in env var rather than always-on logging.
-The code-style skill notes that business logic should remain pure — `debug.ts` must not import the Pi SDK; it only reads `process.env`.
-
-The `DEBUG` constant is evaluated once at module import time (top-level `const`).
-That matches how similar opt-in env vars work in Node.js tooling and keeps the hot path to a single boolean branch.
-
-### Catch blocks in scope
-
-| File               | Line(s)                              | Context label(s)                                        |
-| ------------------ | ------------------------------------ | ------------------------------------------------------- |
-| `env.ts`           | 15, 23                               | `"git rev-parse"`, `"git branch"`                       |
-| `skill-loader.ts`  | 74                                   | `"readdirSync skill root"`                              |
-| `custom-agents.ts` | 37, 47                               | `"readdirSync agents dir"`, `"readFileSync agent file"` |
-| `memory.ts`        | 33, 47                               | `"lstatSync"`, `"readFileSync"`                         |
-| `output-file.ts`   | 83                                   | `"write JSONL chunk"`                                   |
-| `worktree.ts`      | 40, 56, 110, 130, 132, 147, 151, 161 | `"git rev-parse"`, `"git worktree add"`, etc.           |
-| `agent-manager.ts` | 233, 249, 266, 275, 480              | `"outputCleanup"`, `"onComplete callback"`, etc.        |
-| `notification.ts`  | 145                                  | `"notification render"`                                 |
-
-## Design Overview
-
-### `src/debug.ts`
-
-```typescript
-export const DEBUG = process.env.PI_SUBAGENTS_DEBUG === "1";
-
-export function debugLog(context: string, err: unknown): void {
-  if (DEBUG) console.warn(`[pi-subagents:debug] ${context}:`, err);
-}
-```
-
-The module-level `DEBUG` constant is the canonical source.
-`debugLog` is a pure side-effect function: no return value, no SDK dependency, no coupling to Pi types.
-
-### Threading pattern
-
-Every silenced `catch` block is updated from:
-
-```typescript
-} catch { /* ignore */ }
-```
-
-to:
-
-```typescript
-} catch (err) { debugLog("<context label>", err); }
-```
-
-When the block already had a named error (`catch (err)`), only the `debugLog` call is added; the existing comment, if descriptive, is removed in favour of the context string.
-
-### Context label convention
-
-Labels read as `"<verb> <noun>"`, lower-case, mirroring the surrounding function name when unambiguous (e.g., `"removeWorktree"`, `"outputCleanup"`).
-
-## Module-Level Changes
-
-| File                   | Change                                                                       |
-| ---------------------- | ---------------------------------------------------------------------------- |
-| `src/debug.ts`         | **New.** Exports `DEBUG` constant and `debugLog` function.                   |
-| `test/debug.test.ts`   | **New.** Unit tests for `debugLog` on/off behaviour.                         |
-| `src/env.ts`           | Add `debugLog` import; name the two bare `catch` errors; call `debugLog`.    |
-| `src/skill-loader.ts`  | Add `debugLog` import; name the bare `catch` error; call `debugLog`.         |
-| `src/custom-agents.ts` | Add `debugLog` import; name the two bare `catch` errors; call `debugLog`.    |
-| `src/memory.ts`        | Add `debugLog` import; name the two bare `catch` errors; call `debugLog`.    |
-| `src/output-file.ts`   | Add `debugLog` import; name the bare `catch` error; call `debugLog`.         |
-| `src/worktree.ts`      | Add `debugLog` import; name the eight bare `catch` errors; call `debugLog`.  |
-| `src/agent-manager.ts` | Add `debugLog` import; name/update the five `catch` blocks; call `debugLog`. |
-| `src/notification.ts`  | Add `debugLog` import; name the bare `catch` error; call `debugLog`.         |
-
-## Test Impact Analysis
-
-1. **New tests enabled** — `debug.test.ts` can directly unit-test `debugLog` in isolation.
-   Asserting `console.warn` is/isn't called based on the env var is now trivial.
-   Previously this path was entirely untested.
-
-2. **Existing tests become redundant** — None.
-   The catch blocks were never exercised by existing tests (they were silent drops), so no existing test coverage needs to be removed.
-
-3. **Tests that must stay as-is** — All existing tests remain valid.
-   The threading adds a call inside each catch but does not change control flow, return values, or thrown exceptions; no test expectations change.
-
-## TDD Order
-
-1. **`src/debug.ts` + `test/debug.test.ts`** Test surface: `debugLog` calls `console.warn` when `PI_SUBAGENTS_DEBUG=1`; does nothing when unset or `"0"`.
-   Use `vi.spyOn(console, 'warn')` + `vi.stubEnv('PI_SUBAGENTS_DEBUG', '1')` + `vi.resetModules()` + dynamic import to exercise both branches.
-   Suggested commit: `feat: add debugLog utility gated on PI_SUBAGENTS_DEBUG (#57)`
-
-2. **Thread into `env.ts`** Test surface: `env.test.ts` — existing tests still pass (no new assertions required because the catch paths are tested implicitly by the non-git-dir test already covering the swallowed failures).
-   Suggested commit: `feat: thread debugLog into env catch blocks (#57)`
-
-3. **Thread into `skill-loader.ts`** Test surface: `skill-loader.test.ts` — existing tests still pass.
-   The readdirSync-error catch is exercised when the skill root does not exist (covered by existing "not found" test paths).
-   Suggested commit: `feat: thread debugLog into skill-loader catch block (#57)`
-
-4. **Thread into `custom-agents.ts` and `memory.ts`** These two files have structurally identical filesystem-error catch blocks and can land in a single step.
-   Test surface: `custom-agents.test.ts`, `memory.test.ts` — existing tests still pass.
-   Suggested commit: `feat: thread debugLog into custom-agents and memory catch blocks (#57)`
-
-5. **Thread into `output-file.ts`** Test surface: `output-file.test.ts` — existing tests still pass.
-   Suggested commit: `feat: thread debugLog into output-file catch block (#57)`
-
-6. **Thread into `worktree.ts`** Test surface: `worktree.test.ts` — existing tests still pass.
-   Eight catch sites; name each with its enclosing function for label clarity.
-   Suggested commit: `feat: thread debugLog into worktree catch blocks (#57)`
-
-7. **Thread into `agent-manager.ts` and `notification.ts`** Test surface: `agent-manager.test.ts`, `notification.test.ts` — existing tests still pass.
-   Suggested commit: `feat: thread debugLog into agent-manager and notification catch blocks (#57)`
-
-## Risks and Mitigations
-
-| Risk                                                                                                          | Mitigation                                                                                                                                  |
-| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `DEBUG` is a module-level constant — `vi.stubEnv` alone won't flip it mid-test                                | Use `vi.resetModules()` + dynamic `import()` inside a test that sets the env var before re-importing; the test skill documents this pattern |
-| Adding `(err)` to a bare `catch` in TypeScript is type-safe (`unknown`) but a `noImplicitAny`-adjacent change | `tsconfig` already uses `"useUnknownInCatchVariables": true` (default in strict mode); no cast needed                                       |
-| Verbose worktree.ts threading (8 sites) could miss one                                                        | The TDD step runs `pnpm vitest run worktree` and `pnpm run check` before committing                                                         |
-
-## Open Questions
-
-- Should a future issue expose `debugLog` as part of the public `service.ts` API so consumer extensions can share the same debug flag?
-  Deferred — out of scope for this change; no consumer currently needs it.
-- Should `PI_SUBAGENTS_DEBUG` be documented in the package `README.md`?
-  Likely yes, but deferred to a follow-up doc PR.

package/docs/plans/0061-session-format-transcript.md

@@ -1,284 +0,0 @@
----
-issue: 61
-issue_title: "feat: port subagent transcript logging to Pi's official JSONL session format"
----
-
-# Port subagent transcripts to Pi's official session format
-
-## Problem Statement
-
-Subagent conversation transcripts are written as JSONL by `output-file.ts`, but use a bespoke flat format (`{ isSidechain, agentId, type, message, timestamp, cwd }`) that does not conform to Pi's official session file format.
-Pi's `SessionManager` writes tree-structured JSONL with a session header, UUIDv7 entry IDs, `parentId` tree structure, and typed entry discriminants (`"message"`, `"compaction"`, etc.).
-The bespoke format cannot be loaded by Pi's session tooling (session selector, export-html, resume) and requires manual `jq` inspection for debugging.
-
-## Goals
-
-- Subagent transcripts written in Pi's official JSONL session format via `SessionManager`.
-- Transcripts discoverable via the parent session path (nested under a parent-session-relative directory).
-- Parent session linkage via the `parentSession` header field.
-- Delete `output-file.ts` — the SDK's `SessionManager` handles all JSONL writing natively.
-- Existing debugging use case preserved (full turn-by-turn history on disk).
-
-## Non-Goals
-
-- Making subagent sessions resumable via Pi's `/resume` command (future work; requires session selection UX changes).
-- Cross-extension parent-session resolution (issue #22 — separate track).
-- Changing the `SessionManager` usage for the child `AgentSession` itself (the child session already uses `SessionManager.inMemory()`; we replace it with a persisted one).
-
-## Background
-
-### Current flow
-
-1. `agent-tool.ts` calls `createOutputFilePath(cwd, agentId, parentSessionId)` → creates `/tmp/pi-subagents-<uid>/<encoded-cwd>/<parentSessionId>/tasks/<agentId>.output`.
-2. `writeInitialEntry(path, agentId, prompt, cwd)` writes the first user message in the bespoke format.
-3. `streamToOutputFile(session, path, agentId, cwd)` subscribes to `turn_end` events and appends bespoke JSONL entries.
-4. `agent-manager.ts` calls the cleanup function on completion/error to do a final flush and unsubscribe.
-
-### Pi's SessionManager API
-
-`SessionManager` from `@earendil-works/pi-coding-agent` provides:
-
-- `SessionManager.create(cwd, sessionDir?)` — creates a persisted session file in the given directory.
-- `newSession({ parentSession? })` — writes a `SessionHeader` with `parentSession` linking.
-- `appendMessage(message)` — writes a `SessionMessageEntry` with auto-generated UUIDv7 `id` and `parentId` (tree structure).
-- `appendCompaction(...)`, `appendCustomEntry(...)` — first-class support for all entry types.
-- `getSessionFile()` — returns the path to the JSONL file on disk.
-
-The child `AgentSession` (created by `createAgentSession`) accepts a `sessionManager` option.
-Currently set to `SessionManager.inMemory(cwd)`, switching to `SessionManager.create(cwd, sessionDir)` makes the SDK write official-format JSONL automatically — no manual streaming code needed.
-
-### Reference implementations
-
-nicobailon/pi-subagents places subagent sessions under `<parent-session-dir>/<parent-session-basename>/<runId>/`.
-This keeps them discoverable via the parent session path without cluttering the main session list.
-Our approach follows the same pattern: derive a `sessionDir` from the parent session file.
-
-### Constraints
-
-- `agent-runner.ts` already imports `SessionManager` for the `inMemory()` call — switching to `create()` adds no new dependency.
-- `ctx.sessionManager` is `ReadonlySessionManager` and provides `getSessionId()`, `getSessionFile()`, and `getSessionDir()`.
-- The `code-style` skill requires keeping IO at the edges and not hiding dependencies.
-  The session directory derivation should be a pure function that receives the parent session file path.
-
-## Design Overview
-
-### Core change: persisted SessionManager in agent-runner
-
-Replace `SessionManager.inMemory(cwd)` with `SessionManager.create(cwd, sessionDir)` inside `runAgent()`.
-The `sessionDir` is derived from the parent's session file path, and the `parentSession` option links the child to the parent.
-
-The key insight is that the SDK's `createAgentSession` already writes all messages through the `SessionManager` it receives.
-By switching from in-memory to persisted, every message the child agent produces is automatically written in official JSONL format — no manual subscription or streaming code required.
-
-### Session directory derivation
-
-```typescript
-/**
- * Derive the session directory for a subagent from the parent session file.
- * Layout: <parent-dir>/<parent-basename>/tasks/
- *
- * Example:
- *   parent: ~/.pi/agent/sessions/--home-user-project--/2026-05-20T12-00-00Z_.jsonl
- *   result: ~/.pi/agent/sessions/--home-user-project--/2026-05-20T12-00-00Z_/tasks/
- *
- * Falls back to a temp directory when the parent session is not persisted.
- */
-function deriveSubagentSessionDir(
-  parentSessionFile: string | undefined,
-  cwd: string,
-): string;
-```
-
-### Data flow (after)
-
-1. `agent-tool.ts` passes `parentSessionFile` (from `ctx.sessionManager.getSessionFile()`) and `parentSessionId` to `agent-manager.ts` via `SpawnOptions`.
-2. `agent-manager.ts` threads them to `agent-runner.ts` via `RunOptions`.
-3. `agent-runner.ts` calls `deriveSubagentSessionDir(parentSessionFile, cwd)` and creates `SessionManager.create(cwd, sessionDir)` with `{ parentSession: parentSessionId }`.
-4. The `createAgentSession` SDK call receives this persisted `SessionManager`.
-5. All messages are written to disk automatically by the SDK.
-6. `agent-runner.ts` returns the session file path in `RunResult` (via `sessionManager.getSessionFile()`).
-7. `agent-tool.ts` stores the path on `AgentRecord.outputFile` for display in notifications/UI.
-
-### What gets deleted
-
-- `output-file.ts` — entirely replaced by the persisted `SessionManager`.
-- `output-file.test.ts` — the `encodeCwd` tests are no longer needed (Pi's `SessionManager` handles directory encoding internally).
-- `streamToOutputFile`, `writeInitialEntry`, `createOutputFilePath` imports from `agent-tool.ts`.
-- `outputCleanup` field from `AgentRecord` (no manual cleanup needed; the `SessionManager` is append-only).
-- The `onSessionCreated` wrapper in `agent-tool.ts` that wires output-file streaming.
-
-### What changes
-
-- `RunOptions` gains `parentSessionFile?: string` and `parentSessionId?: string`.
-- `RunResult` gains `sessionFile?: string` (path to the persisted session JSONL).
-- `SpawnOptions` gains `parentSessionFile?: string` and `parentSessionId?: string`.
-- `AgentRecord.outputCleanup` is removed (no manual flush/unsubscribe lifecycle).
-- `agent-manager.ts` removes the `outputCleanup` calls in completion/error paths.
-- `agent-tool.ts` sets `record.outputFile` from the `RunResult.sessionFile` instead of calling `createOutputFilePath`.
-- `notification.ts`, `renderer.ts`, `types.ts` — `outputFile` field semantics unchanged (still a path string); only the source changes.
-
-### Edge cases
-
-1. **Parent session not persisted** (e.g., API/headless mode where the parent uses `SessionManager.inMemory()`): `ctx.sessionManager.getSessionFile()` returns `undefined`.
-   Fallback: use a temp directory under `/tmp/pi-subagents-<uid>/` (similar to current behavior) so transcripts are still written to disk.
-2. **Worktree isolation**: `effectiveCwd` differs from `ctx.cwd`.
-   The `SessionManager.create()` call uses `effectiveCwd` (same as current `inMemory` call), but the `sessionDir` is still derived from the parent session — the session header's `cwd` field correctly records the worktree path.
-
-## Module-Level Changes
-
-### New file: `src/session-dir.ts`
-
-Pure function `deriveSubagentSessionDir(parentSessionFile, cwd)`.
-Extracts the parent session basename, constructs `<parent-dir>/<parent-basename>/tasks/`.
-Falls back to a temp directory when `parentSessionFile` is undefined.
-
-### Modified: `src/agent-runner.ts`
-
-- Import `deriveSubagentSessionDir` from `session-dir.ts`.
-- Add `parentSessionFile?: string` and `parentSessionId?: string` to `RunOptions`.
-- Add `sessionFile?: string` to `RunResult`.
-- Replace `SessionManager.inMemory(cfg.effectiveCwd)` with:
-
-```typescript
-const sessionDir = deriveSubagentSessionDir(options.parentSessionFile, cfg.effectiveCwd);
-const sessionManager = SessionManager.create(cfg.effectiveCwd, sessionDir);
-sessionManager.newSession({ parentSession: options.parentSessionId });
-```
-
-- After `session.prompt()`, capture `sessionManager.getSessionFile()` into `RunResult.sessionFile`.
-
-### Modified: `src/agent-manager.ts`
-
-- Add `parentSessionFile?: string` and `parentSessionId?: string` to `SpawnOptions`.
-- Thread them to `RunOptions` in the `runner.run()` call.
-- Remove `outputCleanup` calls from the completion and error handlers.
-
-### Modified: `src/tools/agent-tool.ts`
-
-- Remove import of `createOutputFilePath`, `streamToOutputFile`, `writeInitialEntry`.
-- Remove the `onSessionCreated` wrapper that wired output-file streaming.
-- Pass `parentSessionFile: ctx.sessionManager.getSessionFile()` and `parentSessionId: ctx.sessionManager.getSessionId()` in `SpawnOptions`.
-- After spawn, set `record.outputFile` from the returned session file path (available via `onSessionCreated` callback which gives access to the session's `sessionManager`).
-
-### Modified: `src/types.ts`
-
-- Remove `outputCleanup?: () => void` from `AgentRecord`.
-
-### Deleted: `src/output-file.ts`
-
-Entire file removed.
-
-### Deleted: `test/output-file.test.ts`
-
-Entire file removed.
-
-### Unchanged: `src/notification.ts`, `src/renderer.ts`
-
-These read `record.outputFile` (a path string) — the field still exists, just populated differently.
-The `NotificationDetails.outputFile` field is unchanged.
-
-## Test Impact Analysis
-
-### New tests enabled by extraction
-
-1. `test/session-dir.test.ts` — unit tests for `deriveSubagentSessionDir`:
-   - Parent session file present → derives correct nested path.
-   - Parent session file undefined → falls back to temp directory.
-   - Various path shapes (POSIX, Windows-like).
-
-2. `test/agent-runner.test.ts` — updated tests verifying:
-   - `SessionManager.create` is called (not `inMemory`) when `parentSessionFile` is provided.
-   - `newSession({ parentSession })` is called with the parent session ID.
-   - `RunResult.sessionFile` is populated from the session manager.
-
-### Tests that become redundant
-
-- `test/output-file.test.ts` (`encodeCwd` tests) — the directory encoding is now handled by `deriveSubagentSessionDir` with a different layout.
-  The `encodeCwd` function is deleted.
-
-### Tests that stay as-is
-
-- All `agent-manager.test.ts` tests that mock the runner — they don't depend on `output-file` internals.
-- All `notification.test.ts` and `renderer.test.ts` tests — they read `record.outputFile` which remains a string.
-- The `onSessionCreated` callback tests in `agent-tool.test.ts` need updating to remove the output-file wiring expectations.
-
-## TDD Order
-
-### Step 1: Add `deriveSubagentSessionDir` with tests
-
-1. Create `src/session-dir.ts` with the pure function.
-2. Create `test/session-dir.test.ts` with tests for parent-present and fallback cases.
-3. Commit: `feat: add deriveSubagentSessionDir for session directory derivation (#61)`
-
-### Step 2: Thread parent session info through SpawnOptions and RunOptions
-
-1. Add `parentSessionFile?: string` and `parentSessionId?: string` to `SpawnOptions` in `agent-manager.ts`.
-2. Add `parentSessionFile?: string` and `parentSessionId?: string` to `RunOptions` in `agent-runner.ts`.
-3. Add `sessionFile?: string` to `RunResult` in `agent-runner.ts`.
-4. Thread the new fields from `SpawnOptions` → `RunOptions` in `agent-manager.ts`.
-5. Update tests to verify the new fields are threaded.
-6. Commit: `feat: thread parent session info through spawn and run options (#61)`
-
-### Step 3: Switch agent-runner to persisted SessionManager
-
-1. In `runAgent()`, replace `SessionManager.inMemory(cfg.effectiveCwd)` with the persisted variant using `deriveSubagentSessionDir`.
-2. Call `sessionManager.newSession({ parentSession: options.parentSessionId })`.
-3. Capture `sessionManager.getSessionFile()` into `RunResult.sessionFile`.
-4. Update `agent-runner.test.ts` mocks to expect `SessionManager.create` instead of `SessionManager.inMemory`.
-5. Commit: `feat: use persisted SessionManager for subagent sessions (#61)`
-
-### Step 4: Remove output-file wiring from agent-tool and agent-manager
-
-1. Remove the `onSessionCreated` output-file wrapper in `agent-tool.ts`.
-2. Remove `createOutputFilePath`, `writeInitialEntry`, `streamToOutputFile` imports.
-3. Set `record.outputFile` from the session manager's file path (via `onSessionCreated` callback).
-4. Pass `parentSessionFile` and `parentSessionId` in spawn options.
-5. Remove `outputCleanup` calls from `agent-manager.ts` completion/error handlers.
-6. Remove `outputCleanup` from `AgentRecord` in `types.ts`.
-7. Update agent-tool and agent-manager tests.
-8. Commit: `feat: wire session file path through agent-tool, remove output-file streaming (#61)`
-
-### Step 5: Delete output-file.ts and its tests
-
-1. Delete `src/output-file.ts`.
-2. Delete `test/output-file.test.ts`.
-3. Run full test suite to verify no remaining references.
-4. Commit: `feat!: remove bespoke output-file transcript format (#61)`
-
-### Step 6: Documentation update
-
-1. Update `docs/architecture/architecture.md` — remove `output-file.ts` from the module listing, add `session-dir.ts`, mark #61 as complete.
-2. Commit: `docs: update architecture for session format migration (#61)`
-
-## Risks and Mitigations
-
-### Risk: SessionManager.create may fail in environments without a writable home directory
-
-The temp-directory fallback in `deriveSubagentSessionDir` handles this case.
-When the parent session file is unavailable (headless/API mode), we fall back to a temp directory just like the current implementation.
-
-### Risk: Persisted sessions accumulate disk space over time
-
-Pi's session tooling already manages session storage.
-Subagent sessions nested under the parent session directory are cleaned up when the parent session is deleted.
-This is an improvement over the current `/tmp` location where files persist until system cleanup.
-
-### Risk: Tests that mock SessionManager.inMemory need updating
-
-Step 3 explicitly plans for updating these mocks.
-The change is localized to `agent-runner.ts` and its direct test file.
-
-### Risk: Breaking change for consumers that read outputFile paths
-
-The `outputFile` field changes from `/tmp/pi-subagents-<uid>/.../tasks/<agentId>.output` to `~/.pi/agent/sessions/.../<timestamp>_<uuid>.jsonl`.
-Consumers that parse the path (unlikely) would break, but the field is internal to the extension and only used for display.
-The format of the file content changes from bespoke JSONL to Pi's official format — this is the intentional breaking change.
-
-## Open Questions
-
-1. Should the plan add a `sessionDir` field to `AgentRecord` alongside `outputFile`, or is the session file path sufficient for all use cases?
-   Deferred — start with `outputFile` pointing to the session file; add `sessionDir` if needed later.
-2. Should foreground agents also get persisted sessions, or only background agents?
-   The current `output-file` code only runs for background agents.
-   Persisted sessions are valuable for both — the plan applies the change in `agent-runner.ts` which serves both paths.
-   If this proves too noisy, a follow-up can gate it behind a setting.

package/docs/plans/0066-replace-as-any-with-sdk-types.md

@@ -1,215 +0,0 @@
----
-issue: 66
-issue_title: "refactor: replace `as any` casts in extracted tool/menu factories with proper SDK types"
----
-
-# Replace `as any` casts in factory dep interfaces with proper SDK types
-
-## Problem Statement
-
-The decomposition in #54 introduced 14 `as any` casts at the wiring boundary in `src/index.ts`.
-These exist because the factory dep interfaces (`AgentToolManager`, `GetResultDeps`, `SteerToolDeps`, `AgentMenuDeps`, `NotificationDeps`) declare `unknown` or `object` for parameters that are actually well-typed SDK exports.
-Every cast papers over a real type that the SDK already exports.
-For comparison, `pi-permission-system` imports SDK types directly in its internal interfaces and has zero `as any` casts.
-
-## Goals
-
-- Replace every `as any` cast in `src/index.ts` by typing the corresponding dep interface parameter with the actual SDK type.
-- Keep factory modules decoupled from `AgentManager` where possible — use shared types (`types.ts`) or SDK imports.
-- No runtime behavior change — this is purely a type-safety improvement.
-- Existing tests continue to pass without modification (factory `execute` methods use `ctx: any` or `ctx: unknown`, so test mocks are unaffected).
-
-## Non-Goals
-
-- Fixing `as any` casts in `agent-runner.ts`, `conversation-viewer.ts`, `tools/helpers.ts`, or `tools/agent-tool.ts:550` — those access untyped SDK message internals, a different concern.
-- Removing the `ctx as UICtx` cast (line 196) — that is a named cast, not `as any`.
-- Removing `as any` from test files (e.g., `agent-menu.test.ts`'s `ctx as any`) — test mocks are intentionally narrow.
-
-## Background
-
-### Current cast inventory (`src/index.ts`)
-
-| Line | Cast                                            | Root cause                                                                  |
-| ---- | ----------------------------------------------- | --------------------------------------------------------------------------- |
-| 59   | `msg as any, opts as any`                       | `NotificationDeps.sendMessage(msg: unknown, opts: unknown)`                 |
-| 188  | `ctx as any, opts as any`                       | `AgentToolManager.spawn(ctx: unknown, …, opts: object)`                     |
-| 189  | `ctx as any, opts as any`                       | `AgentToolManager.spawnAndWait(ctx: unknown, …, opts: object)`              |
-| 208  | `}) as any`                                     | Cascading from above — `createAgentTool` return doesn't match `defineTool`  |
-| 215  | `session as any`                                | `GetResultDeps.getConversation(session: unknown)`                           |
-| 223  | `session as any`                                | `SteerToolDeps.steerAgent(session: unknown, …)`                             |
-| 232  | `(piArg ?? pi) as any, ctx as any, opts as any` | `AgentMenuManager.spawnAndWait(pi: unknown, ctx: unknown, …, opts: object)` |
-| 242  | `registry as any`                               | `AgentMenuDeps.getModelLabel(…, registry?: unknown)`                        |
-| 271  | `ctx as any`                                    | `MenuContext` not structurally compatible with `ExtensionCommandContext`    |
-
-### SDK types available
-
-All are exported from `@earendil-works/pi-coding-agent`:
-
-- `ExtensionContext` — tool execute context (has `ui`, `modelRegistry`, `cwd`, etc.)
-- `ExtensionCommandContext` — command handler context (extends `ExtensionContext`)
-- `ExtensionAPI` — the `pi` object passed to extensions
-- `AgentSession` — session handle (has `steer()`, `messages`, etc.)
-
-`ModelRegistry` is already defined locally in `src/model-resolver.ts` and matches the SDK shape.
-`SpawnOptions` is defined locally in `src/agent-manager.ts` (not currently exported).
-
-### Relevant AGENTS.md constraints
-
-- "Avoid `any` unless absolutely necessary."
-- "Keep Pi SDK imports out of business-logic modules."
-  Tool definitions, event handlers, and command handlers are SDK consumers — they may import SDK types directly.
-  The restriction targets pure helpers, utilities, and domain modules.
-- "When writing event handlers that consume Pi SDK types, prefer lean local payload interfaces over full SDK event types."
-
-The factory modules (`tools/agent-tool.ts`, `tools/get-result-tool.ts`, `tools/steer-tool.ts`, `ui/agent-menu.ts`) are SDK consumers (they define tools and command handlers), so importing SDK types is acceptable.
-The notification module (`notification.ts`) is a pure helper — it should use narrow local types rather than SDK imports.
-
-## Design Overview
-
-### Strategy per interface
-
-1. **`NotificationDeps.sendMessage`** — define narrow inline parameter types matching `ExtensionAPI.sendMessage`'s shape.
-   No SDK import needed; the notification module stays SDK-independent.
-
-2. **`AgentToolManager`** — import `ExtensionContext` for `ctx`, export + import `SpawnOptions` from `agent-manager.ts` for `opts`.
-   The tool module is an SDK consumer, so SDK imports are acceptable.
-
-3. **`AgentToolWidget.setUICtx`** — stays `ctx: unknown` (not `as any`; currently `ctx as UICtx`).
-   Out of scope.
-
-4. **`GetResultDeps.getConversation`** — import `AgentSession` for `session`.
-
-5. **`SteerToolDeps.steerAgent`** — import `AgentSession` for `session`.
-
-6. **`AgentMenuManager.spawnAndWait`** — import `ExtensionAPI` for `pi`, `ExtensionContext` for `ctx`, export + import `SpawnOptions` for `opts`.
-
-7. **`AgentMenuDeps.getModelLabel`** — import `ModelRegistry` from `../model-resolver.js` for `registry`.
-
-8. **`MenuContext` structural compatibility** — switch `MenuUI` from property syntax (strict function types) to method syntax (bivariant), and type `modelRegistry` as `ModelRegistry`.
-   This makes `ExtensionCommandContext` structurally assignable to `MenuContext`, removing the cast without broadening the handler's dependency on the full SDK type.
-   Tests continue using narrow mocks because the handler's parameter is still the narrow `MenuContext`.
-
-### `SpawnOptions` export
-
-`SpawnOptions` in `agent-manager.ts` is currently a private interface.
-Exporting it as a named `type` export adds no runtime cost and avoids duplicating the 15-field type in each factory.
-Both `tools/agent-tool.ts` and `ui/agent-menu.ts` already import `AgentRecord` from `types.ts`, so an intra-package `import type` from `agent-manager.ts` follows the same pattern.
-
-### Cascading cast resolution
-
-The `createAgentTool({…}) as any` cast on line 208 exists because TypeScript cannot verify the returned object satisfies `ToolDefinition` when inner types are `unknown`/`object`.
-Once the inner types are correct, the factory return type matches `ToolDefinition` naturally, and the outer `as any` cast resolves without further changes.
-
-## Module-Level Changes
-
-### `src/agent-manager.ts`
-
-- Export the existing `SpawnOptions` interface (add `export` keyword).
-
-### `src/notification.ts`
-
-- Replace `sendMessage: (msg: unknown, opts: unknown) => void` with narrow inline types:
-
-```typescript
-sendMessage: (
-  msg: { customType: string; content: string; display?: boolean; details?: unknown },
-  opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
-) => void;
-```
-
-### `src/tools/agent-tool.ts`
-
-- Add `import type { ExtensionContext } from "@earendil-works/pi-coding-agent";`
-- Add `import type { SpawnOptions } from "../agent-manager.js";`
-- `AgentToolManager.spawn`: `ctx: unknown` → `ctx: ExtensionContext`, `opts: object` → `opts: SpawnOptions`
-- `AgentToolManager.spawnAndWait`: same changes, opts as `Omit<SpawnOptions, "isBackground">`
-
-### `src/tools/get-result-tool.ts`
-
-- Add `import type { AgentSession } from "@earendil-works/pi-coding-agent";`
-- `GetResultDeps.getConversation`: `session: unknown` → `session: AgentSession`
-
-### `src/tools/steer-tool.ts`
-
-- Add `import type { AgentSession } from "@earendil-works/pi-coding-agent";`
-- `SteerToolDeps.steerAgent`: `session: unknown` → `session: AgentSession`
-
-### `src/ui/agent-menu.ts`
-
-- Add `import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";`
-- Add `import type { SpawnOptions } from "../agent-manager.js";`
-- Add `import type { ModelRegistry } from "../model-resolver.js";`
-- `AgentMenuManager.spawnAndWait`: `pi: unknown` → `pi: ExtensionAPI | null`, `ctx: unknown` → `ctx: ExtensionContext`, `opts: object` → `opts: Omit<SpawnOptions, "isBackground">`
-- `AgentMenuDeps.getModelLabel`: `registry?: unknown` → `registry?: ModelRegistry`
-- `MenuUI`: switch from property syntax to method syntax for structural compatibility with `ExtensionUIContext`.
-  Update `notify` second parameter from `level: string` to `type?: string` to match SDK.
-- `MenuContext.modelRegistry`: `unknown` → `ModelRegistry`
-
-### `src/index.ts`
-
-- Remove all 14 `as any` casts.
-- No new imports needed (types already used transitively).
-
-## Test Impact Analysis
-
-1. **No new unit tests needed** — this is a type-only refactoring with no behavioral change.
-2. **No existing tests become redundant** — the tests exercise tool execution and menu behavior, not type signatures.
-3. **Existing tests must stay as-is** — factory `execute` methods use `ctx: any` or `ctx: unknown`, so `makeCtx()` test helpers remain compatible.
-   Test-side `as any` casts (e.g., `handler(ctx as any)` in `agent-menu.test.ts`) are out of scope.
-
-## TDD Order
-
-Since this is a type-only change, each step is verified by `pnpm run check` (tsc) rather than new vitest tests.
-The full test suite (`pnpm vitest run`) is run at the end as a regression check.
-
-1. **Export `SpawnOptions`** — add `export` to the existing `interface SpawnOptions` in `agent-manager.ts`.
-   Verify: `pnpm run check`.
-   Commit: `refactor: export SpawnOptions from agent-manager`
-
-2. **Type `NotificationDeps`** — replace `(msg: unknown, opts: unknown)` with narrow inline types in `notification.ts`.
-   Remove `msg as any, opts as any` casts (line 59) in `index.ts`.
-   Verify: `pnpm run check`.
-   Commit: `refactor: type NotificationDeps.sendMessage parameters (#66)`
-
-3. **Type `AgentToolManager`** — import `ExtensionContext` and `SpawnOptions`, update `spawn` and `spawnAndWait` signatures in `agent-tool.ts`.
-   Remove `ctx as any, opts as any` casts (lines 188–189) and the cascading `}) as any` cast (line 208) in `index.ts`.
-   Verify: `pnpm run check`.
-   Commit: `refactor: type AgentToolManager with ExtensionContext and SpawnOptions (#66)`
-
-4. **Type `GetResultDeps`** — import `AgentSession`, update `getConversation` in `get-result-tool.ts`.
-   Remove `session as any` cast (line 215) in `index.ts`.
-   Verify: `pnpm run check`.
-   Commit: `refactor: type GetResultDeps.getConversation with AgentSession (#66)`
-
-5. **Type `SteerToolDeps`** — import `AgentSession`, update `steerAgent` in `steer-tool.ts`.
-   Remove `session as any` cast (line 223) in `index.ts`.
-   Verify: `pnpm run check`.
-   Commit: `refactor: type SteerToolDeps.steerAgent with AgentSession (#66)`
-
-6. **Type `AgentMenuManager` + `AgentMenuDeps`** — import `ExtensionAPI`, `ExtensionContext`, `SpawnOptions`, `ModelRegistry`.
-   Update `spawnAndWait` and `getModelLabel` signatures in `agent-menu.ts`.
-   Remove `(piArg ?? pi) as any, ctx as any, opts as any` (line 232) and `registry as any` (line 242) casts in `index.ts`.
-   Verify: `pnpm run check`.
-   Commit: `refactor: type AgentMenu interfaces with SDK types (#66)`
-
-7. **Align `MenuContext` with `ExtensionCommandContext`** — switch `MenuUI` to method syntax, fix `notify` parameter, type `modelRegistry` as `ModelRegistry`.
-   Remove `ctx as any` cast (line 271) in `index.ts`.
-   Verify: `pnpm run check`.
-   Commit: `refactor: align MenuContext for structural ExtensionCommandContext compat (#66)`
-
-8. **Final verification** — run `pnpm vitest run` for the full test suite.
-   Grep `src/index.ts` for remaining `as any` — expect zero.
-   Commit: none (verification only).
-
-## Risks and Mitigations
-
-| Risk                                                                                           | Mitigation                                                                                                                                                                              |
-| ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Exporting `SpawnOptions` from `agent-manager.ts` couples factory modules to the manager's type | The coupling is type-only (`import type`), adds no runtime dependency, and follows the existing pattern (`AgentRecord` in `types.ts` is already shared).                                |
-| `MenuUI` method-syntax change could break structural compatibility with test mocks             | Test mocks use `vi.fn()` which is bivariant; method syntax on the `MenuUI` interface only affects how TypeScript checks assignability from `ExtensionUIContext`, not from mock objects. |
-| SDK type exports could change in a future Pi release                                           | The SDK types used (`ExtensionContext`, `AgentSession`, `ExtensionAPI`) are stable public API. `ModelRegistry` is a local interface.                                                    |
-| Cascading `as any` on `createAgentTool` may not resolve automatically                          | If TypeScript still cannot infer the return type, add explicit `satisfies ToolDefinition<…>` or a return type annotation. Verified in step 3.                                           |
-
-## Open Questions
-
-- None — the issue's "Proposed change" section is unambiguous and all SDK types are confirmed available.