@nklisch/pi-enhanced 0.4.4 → 0.5.0

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/architecture/history/phase-8-testability.md

@@ -1,103 +0,0 @@
-# Phase 8: Testability, display extraction, and menu decomposition
-
-Eliminated `vi.mock()` module mocking in the two most fragile test suites by injecting IO-touching collaborators; consolidated shared test fixtures; extracted display helpers into a reusable module; decomposed the largest UI file.
-
-Steps G and H 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 did not gate encapsulation work.
-The display extraction unblocked menu decomposition.
-
-## Test pain points (resolved)
-
-| Symptom                                                       | Resolution                                                     |
-| ------------------------------------------------------------- | -------------------------------------------------------------- |
-| 7 `vi.mock()` calls in `agent-runner.test.ts`                 | Step H (#133): injected `RunnerIO` stubs                       |
-| 7 `vi.mock()` calls in `agent-runner-extension-tools.test.ts` | Step H (#133): same                                            |
-| 52 `as any` casts across test suite                           | Step I (#134): reduced to 15                                   |
-| 3× duplicated `mockSession()`                                 | Step F (#131): shared `createMockSession()` in `test/helpers/` |
-| 3× duplicated `makeDeps()`                                    | Step F (#131): shared `createToolDeps()` in `test/helpers/`    |
-
-The well-designed test suites - `agent-manager.test.ts` (1 mock, DI via `AgentRunner` interface), `notification.test.ts` (0 mocks, pure functions + DI), and `agent-tool.test.ts` (0 mocks, tests via deps bag) - confirmed the pattern: modules that accept collaborators through injection produce resilient tests; modules that import collaborators directly produce fragile mock-heavy tests.
-
-## Step F: Shared test fixtures (#131)
-
-Consolidated duplicated mock factories into `test/helpers/`.
-
-1. `createMockSession()` - subscribable event bus with `emit()` helper; replaced 3 hand-rolled copies.
-2. `createToolDeps()` - builds `AgentToolDeps` with sensible defaults and override support; replaced 3 `makeDeps()` copies.
-3. `makeRecord()` - `AgentRecord` factory with sensible defaults; replaced scattered inline construction.
-4. `STUB_CTX` - shared stub `ExtensionContext` constant; centralised unavoidable bridge casts.
-
-Impact: reduced test boilerplate; single source of truth for mock shapes; changes to dep interfaces propagate automatically.
-
-## Step G: Inject IO collaborators into session-config (#132)
-
-`assembleSessionConfig` now accepts `io: AssemblerIO` as a required parameter.
-`index.ts` constructs the real `AssemblerIO` from direct imports via the `RunnerIO.assemblerIO` field (wired in Step H).
-`session-config.test.ts` injects stubs - all 4 `vi.mock()` calls eliminated, assertions shifted to `SessionConfig` output properties.
-
-## Step H: Inject SDK boundary into agent-runner (#133)
-
-`runAgent()` now accepts `io: RunnerIO` as a required parameter bundling all IO collaborators: `detectEnv`, `getAgentDir`, `createResourceLoader`, `deriveSessionDir`, `createSessionManager`, `createSettingsManager`, `createSession`, and `assemblerIO`.
-
-`createAgentRunner(io: RunnerIO): AgentRunner` factory captures the boundary at construction time so `AgentManager` and the `AgentRunner` interface remain unchanged.
-`index.ts` constructs the real `RunnerIO` from Pi SDK imports and sibling modules.
-
-Impact: 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)
-
-Reduced `as any` count from 93 to 15 (plus 13 explicit `as unknown as T` bridge casts).
-
-Production changes:
-
-- `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)
-
-`ui/display.ts` now contains all pure formatters, display helpers, constants, and shared types (`Theme`, `AgentDetails`).
-`agent-widget.ts` dropped from 522 → ~340 lines.
-All consumer modules (menu, tools, renderer, conversation viewer) import from `ui/display.ts` directly.
-`test/agent-widget.test.ts` renamed to `test/display.test.ts`.
-
-## Step K: Decompose agent-menu.ts (#136)
-
-`agent-menu.ts` (668 lines) decomposed into four modules:
-
-1. `ui/agent-file-ops.ts` - `AgentFileOps` interface (`exists`, `read`, `write`, `remove`, `ensureDir`, `findAgentFile`) + `FsAgentFileOps` production implementation.
-2. `ui/agent-config-editor.ts` - `showAgentDetail` with edit/delete/reset/eject/disable/enable transitions (~200 lines).
-3. `ui/agent-creation-wizard.ts` - AI-generation and manual-form creation paths (~250 lines).
-4. `ui/agent-menu.ts` - menu orchestration, agent listing, running-agent viewer, settings form (~300 lines).
-
-Impact: `agent-menu.ts` dropped from 668 → 296 lines; extracted modules receive `AgentFileOps` via injection; `vi.mock("node:fs")` eliminated from `agent-menu.test.ts`.
-
-## Step dependencies
-
-```mermaid
-flowchart LR
-    subgraph testability["Testability track"]
-        F["F: Shared fixtures"] --> G["G: session-config IO"] --> H["H: agent-runner SDK"] --> I["I: Reduce as-any"]
-    end
-    subgraph display["Display track"]
-        J["J: Display extraction"] --> K["K: Menu decomposition"]
-    end
-```
-
-The two tracks are independent and can proceed in parallel.
-
-## Related issues
-
-- #131 — Shared test fixtures
-- #132 — Inject IO collaborators into session-config
-- #133 — Inject SDK boundary into agent-runner
-- #134 — Reduce as-any casts in tests
-- #135 — Extract display helpers
-- #136 — Decompose agent-menu.ts

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/architecture/history/phase-9-observation-ctx.md

@@ -1,122 +0,0 @@
-# Phase 9: Observation consolidation, ctx elimination, and remaining mocks
-
-Target: consolidate the dual observation model so stats live in one place; remove `ExtensionContext` from all internal APIs; eliminate remaining `vi.mock()` calls and `as any` casts; split widget rendering from lifecycle; apply dependency bag convention.
-
-## Current smells
-
-| Smell                                             | Location                                                                  | Evidence                                                                                                                       | Severity |
-| ------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------- |
-| `execute` does config resolution for its callees  | `agent-tool.ts` (145-line `execute`)                                      | ~60 lines unpack config, resolve model, compute metadata, repack into 16-field bags for spawners; `ctx` threaded 4 layers deep | Medium   |
-| ~~Wide `ctx` in menu handlers~~                   | ~~`agent-menu.ts`, `agent-config-editor.ts`, `agent-creation-wizard.ts`~~ | Resolved by #146: `MenuUI` interface introduced; 42 `ctx as any` casts eliminated across 5 test files                          | Done     |
-| ~~Direct SDK import in `conversation-viewer.ts`~~ | ~~`conversation-viewer.test.ts`~~                                         | Resolved by #147: `wrapText` injected via `ConversationViewerOptions`; `vi.mock("@earendil-works/pi-tui")` eliminated          | Done     |
-| ~~Widget mixes rendering, lifecycle, and state~~  | ~~`agent-widget.ts` (370 lines)~~                                         | Resolved by #148: rendering extracted to `widget-renderer.ts`; widget is now 198 lines                                         | Done     |
-| `deps.` prefix noise in function bodies           | remaining modules across tools, UI, service-adapter                       | Functions accept a `deps` bag and access every field as `deps.foo`; hides real dependencies and lengthens every call line      | Low      |
-
-## Dependency bag convention
-
-Applied incrementally as each step touches a module:
-
-- **≤4 fields** - accept as plain parameters; drop the interface.
-- **≥5 fields** - keep a named interface but destructure in the function signature (`{ manager, widget }: ForegroundDeps`) so the function body uses bare names, not `deps.foo`.
-
-This eliminates the `deps.` prefix noise across ~124 callsites in 12 modules.
-
-## Step L: Consolidate observation model (#144)
-
-Removed `_toolUses` and `_lifetimeUsage` from `AgentActivityTracker`.
-UI consumers read stats from `AgentRecord` instead of the tracker.
-The UI observer retains event subscriptions for re-render triggers but no longer accumulates stats independently.
-
-Add `session` and `outputFile` convenience getters on `AgentRecord` to hide the `execution?.` traversal.
-The 15+ callsites that navigate `record.execution?.session` simplify to `record.session`.
-
-Apply the dependency bag convention to touched modules: `NotificationDeps` (4 fields) becomes plain parameters on `NotificationManager` constructor.
-
-Impact: eliminates dual counting; removes `??` fallback pattern from widget and conversation viewer; hides `ExecutionState` structure from consumers.
-
-## Step M: Decompose execute and push ExtensionContext to the boundary (#145)
-
-Extracted config resolution into `resolveSpawnConfig` (pure function in `spawn-config.ts`).
-Injected three collaborators (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) into `createAgentTool` so `execute` no longer reads `ctx` beyond `ctx.ui` (already delegated to `widget.setUICtx`).
-`AgentManager.spawn()` and `spawnAndWait()` accept `ParentSnapshot` instead of `ExtensionContext`.
-`service-adapter.ts` calls `buildParentSnapshot(session.ctx)` at its boundary.
-`foreground-runner` and `background-spawner` receive `ResolvedSpawnConfig` + domain values (`snapshot`, `parentSessionFile`, `parentSessionId`) instead of `ctx`.
-
-Dissolved `ForegroundDeps`, `BackgroundDeps`, and `AdapterDeps` into plain parameters.
-`AgentToolDeps` is destructured in the `createAgentTool` signature.
-
-After this step, `ExtensionContext` appears only in:
-
-- `index.ts` closures (wired at extension startup)
-- `service-adapter.ts` (cross-extension boundary)
-- Menu handlers (addressed by Step N)
-
-Impact: `execute` dropped from ~145 to ~25 lines; eliminated 16-field parameter bags; eliminated `vi.mock("../src/parent-snapshot.js")` in `agent-manager.test.ts`; foreground/background runner tests no longer need `ctx` mocks; `AgentManager` operates entirely on domain types.
-
-## Step N: Narrow UI context for menu handlers (#146)
-
-Defined `MenuUI` interface (exported from `agent-menu.ts`) with `select`, `confirm`, `input`, `notify`, `editor`, and `custom` methods — the exact subset `ctx.ui` methods used by menu handlers.
-All inner functions in `agent-menu.ts`, `agent-config-editor.ts`, and `agent-creation-wizard.ts` now accept `(ui: MenuUI)` instead of `(ctx: ExtensionContext)`.
-`index.ts` passes `ctx.ui`, `ctx.modelRegistry`, and `buildParentSnapshot(ctx)` to the handler.
-
-`AgentMenuManager.spawnAndWait` and `WizardManager.spawnAndWait` both accept `ParentSnapshot` (enabled by Step M).
-Creation wizard threads `parentSnapshot` from `showCreateWizard(ui, parentSnapshot)` → `showGenerateWizard(ui, parentSnapshot, targetDir)` → `manager.spawnAndWait(parentSnapshot, ...)`.
-
-Applied the dependency bag convention:
-
-- `AgentConfigEditorDeps` (4 fields), `GetResultDeps` (4 fields), `SteerToolDeps` (4 fields) dissolved into plain parameters.
-- `AgentMenuDeps` (8 fields) and `AgentCreationWizardDeps` (5 fields) kept as interfaces, destructured in the function signature.
-
-After Steps M and N, `ExtensionContext` appears only at true boundaries: `index.ts` closures and `service-adapter.ts` (cross-extension bridge).
-
-Impact: eliminated 42 `ctx as any` casts across 5 test files (`agent-menu.test.ts`: 8, `agent-config-editor.test.ts`: 20, `agent-creation-wizard.test.ts`: 14); tests construct plain `MenuUI`-shaped objects with no cast.
-
-## Step O: Inject text wrapping into ConversationViewer (#147)
-
-Accepted `wrapText: (text: string, width: number) => string[]` via `ConversationViewerOptions`.
-`agent-menu.ts` passes the real `wrapTextWithAnsi` import at the `ConversationViewer` construction site.
-Tests inject a stub or the real function directly via options — no module-level mock needed.
-
-Applied the dependency bag convention: `ConversationViewerOptions` is now destructured in the constructor signature.
-
-Impact: eliminated the hoisted `vi.mock("@earendil-works/pi-tui")` from `conversation-viewer.test.ts`; 1 test deleted (mock-mechanism sentinel); net −1 test.
-
-## Step P: Split AgentWidget rendering (#148)
-
-Extracted pure rendering functions (`renderWidgetLines`, `renderFinishedLine`, `renderRunningLines`) from `AgentWidget` into `ui/widget-renderer.ts`.
-The widget is now a thin lifecycle/polling wrapper (198 lines, down from 374) that delegates to pure render functions.
-Rendering functions receive data (agent list, activity map, registry) and return formatted strings - testable without widget lifecycle. 23 new unit tests cover all status variants, overflow, tree connectors, and empty states.
-
-## Step dependencies
-
-```mermaid
-flowchart LR
-    subgraph observation["Observation track"]
-        L["L: Consolidate observation #144"] --> P["P: Split widget rendering #148"]
-    end
-    subgraph ctx["ctx elimination track"]
-        M["M: Decompose execute / push ctx #145"] --> N["N: Narrow UI context #146"]
-    end
-    O["O: Inject text wrapping #147"]
-```
-
-The three tracks are independent of each other.
-
-## Projected impact
-
-| Metric                             | Before                   | After                    |
-| ---------------------------------- | ------------------------ | ------------------------ |
-| `vi.mock()` calls remaining        | 4                        | 1 (`print-mode.test.ts`) |
-| `as any` casts remaining           | 45                       | ~5                       |
-| Independent tool-use counters      | 2                        | 1                        |
-| `record.execution?.` traversals    | 15+                      | 0                        |
-| `ExtensionContext` in domain types | 1 (`AgentManager.spawn`) | 0                        |
-| `deps.` prefix accesses            | ~124                     | 0                        |
-
-## Related issues
-
-- #144 — Consolidate observation model
-- #145 — Decompose execute and push ExtensionContext to boundary
-- #146 — Narrow UI context for menu handlers
-- #147 — Inject text wrapping into ConversationViewer
-- #148 — Split AgentWidget rendering

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/decisions/0001-deferred-patches.md

@@ -1,80 +0,0 @@
----
-status: superseded
-date: 2026-05-11
----
-
-# 0001 — Deferred fork patches and upstream-PR strategy
-
-## Status
-
-Superseded by [`docs/architecture/architecture.md`](../architecture/architecture.md), which commits to a hard fork with material scope reduction (scheduling removal, `SubagentsAPI` boundary, `index.ts` decomposition).
-The original rationale below remains useful context.
-
-## Context
-
-This fork was created to land three pieces of work identified during RepOne issue [#442](https://github.com/Tiny-IG-Software/repone/issues/442):
-
-1. **Peer-dep rename** — `@mariozechner/pi-*` → `@earendil-works/pi-*`.
-2. **Patch 2 — Re-activate extension tools post-`bindExtensions`** (Spike 3 finding).
-3. **Patch 3 — Inject `<active_agent>` tag** (Spike 4 finding).
-
-A fourth piece of work was scoped during the same spike round but deferred:
-
-- **Patch 1 — Mirror parent's `additionalExtensionPaths` (and siblings) into the child's `DefaultResourceLoader`** (Spike 2 finding).
-
-This ADR records why Patch 1 was deferred and the strategy for upstream PRs back to [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents).
-
-## Decision
-
-### Patch 1 is deferred
-
-The original Spike 2 finding was that the parent's `additionalExtensionPaths` does not propagate to the child's `DefaultResourceLoader`.
-The fix was sketched as "plumb parent's `additionalExtensionPaths` (and siblings) into the child."
-
-During planning for this fork, two implementation constraints surfaced:
-
-1. The parent's `DefaultResourceLoader.additionalExtensionPaths` is **private** — no public getter on `ExtensionContext`.
-2. The parent's CLI flags (e.g., `pi -e <path>`) are parsed in `main.js` and not surfaced through any extension API.
-
-A working patch would have to either:
-
-- Accept new fields in `RunOptions` so callers supply the paths explicitly, **or**
-- Reach into `process.argv` to re-resolve `-e`/`--extensions` flags from the child's perspective.
-
-Neither matches the production need.
-For RepOne (and any consumer that installs extensions via `pi install`), extensions are settings-discoverable: children inherit them independently of the parent's `DefaultResourceLoader` configuration.
-The `pi -e <path>` ephemeral-extension case is the only beneficiary of Patch 1, and it does not appear in our workflow.
-
-We therefore defer Patch 1 rather than carry a speculative patch in the fork's diff against upstream.
-A follow-up issue on the RepOne board (linked from #443) captures the criterion for revisiting: **a workflow that needs `pi -e <path>` ephemeral extensions to reach children**.
-
-### Upstream PRs are open
-
-All three divergences now have upstream PRs, opened after production validation in RepOne:
-
-1. **Peer-dep migration** — [tintinweb/pi-subagents#71](https://github.com/tintinweb/pi-subagents/pull/71) (`fix(deps)!: migrate from deprecated @mariozechner/pi-* to @earendil-works/pi-*`)
-2. **Post-bind re-filter** — [tintinweb/pi-subagents#72](https://github.com/tintinweb/pi-subagents/pull/72) (`fix(agent-runner): re-filter active tools after bindExtensions so extension tools land in child`)
-3. **Active-agent tag** — [tintinweb/pi-subagents#73](https://github.com/tintinweb/pi-subagents/pull/73) (`feat(prompts): inject <active_agent name="..."/> tag for permission resolution`)
-
-If these land upstream, upstream gains the peer-dep fix and the two RepOne patches.
-However, the fork now diverges intentionally beyond those patches — see [`docs/architecture/architecture.md`](../architecture/architecture.md) for the full scope of planned changes.
-
-## Consequences
-
-### Positive
-
-- The fork's diff against upstream stays minimal — three patches plus tooling alignment.
-- We avoid landing a speculative Patch 1 that would need rework if upstream's `ExtensionContext` API changes.
-- Production evidence strengthened the upstream PRs.
-
-### Negative
-
-- The `pi -e <path>` ephemeral-extension case in subagents will not work until Patch 1 lands.
-  We accept this because no consumer in scope uses that pattern.
-
-### Operational
-
-- Upstream PRs are open and linked above.
-  If merged, upstream gains the three patches, but the fork continues independently with broader architectural changes per [`docs/architecture/architecture.md`](../architecture/architecture.md).
-- The architecture document governs the fork's direction going forward; this ADR's original "thin-patch" framing no longer describes the fork's trajectory.
-- When Patch 1 is eventually added, it should be a separate ADR in `docs/decisions/` with its own follow-up.