@gotgenes/pi-subagents 6.12.1 → 6.13.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.13.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.12.1...pi-subagents-v6.13.0) (2026-05-23)
+
+
+### Features
+
+* add AgentFileOps interface and FsAgentFileOps ([#136](https://github.com/gotgenes/pi-packages/issues/136)) ([9625de6](https://github.com/gotgenes/pi-packages/commit/9625de60ace3cf58ad59c2d533f18fd7cdb8bba9))
+
+
+### Documentation
+
+* plan agent-menu decomposition ([#136](https://github.com/gotgenes/pi-packages/issues/136)) ([41ca6a6](https://github.com/gotgenes/pi-packages/commit/41ca6a6612cbc167a5b3d336ffb94d3f9666868f))
+* **retro:** add retro notes for issue [#135](https://github.com/gotgenes/pi-packages/issues/135) ([83e255b](https://github.com/gotgenes/pi-packages/commit/83e255b4a5e6a56a287c933e4a5fa0b28121529e))
+* update architecture for agent-menu decomposition ([#136](https://github.com/gotgenes/pi-packages/issues/136)) ([dba90e8](https://github.com/gotgenes/pi-packages/commit/dba90e86693e3480004a7c305d5082cb5a930d3f))
+
 ## [6.12.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.12.0...pi-subagents-v6.12.1) (2026-05-22)
 
 

package/docs/architecture/architecture.md

@@ -273,7 +273,10 @@ src/
 │   └── tool-start.ts         — tool_execution_start handler
 ├── notification.ts           — completion nudges, custom renderer
 ├── renderer.ts               — notification TUI component
-├── ui/agent-menu.ts          — /agents slash command menu
+├── ui/agent-menu.ts          — /agents slash command menu (orchestration, listing, settings)
+├── ui/agent-config-editor.ts — agent detail view (edit/delete/eject/disable/enable)
+├── ui/agent-creation-wizard.ts — agent creation (AI-generation and manual-form)
+├── ui/agent-file-ops.ts      — AgentFileOps interface + FsAgentFileOps implementation
 ├── service-adapter.ts        — SubagentsService implementation wrapping AgentManager
 └── (existing domain modules unchanged)
 ```
@@ -572,17 +575,16 @@ Remaining 15 `as any` casts are: 8 menu-handler `ctx as any` (deferred — requi
 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)
+### Step K: Decompose agent-menu.ts (#136) ✅
 
-`agent-menu.ts` (650 lines) has 8 distinct responsibilities: menu FSM, agent listing, config editing, agent ejection, two creation wizards, running-agent viewer, and settings form.
-Filesystem operations (read/write/delete agent `.md` files) are scattered throughout.
+`agent-menu.ts` (668 lines) decomposed into four modules:
 
-1. Extract `AgentFileOps` interface — `read`, `write`, `delete`, `findAgentFile` — abstracting the fs calls.
-2. Extract `ui/agent-config-editor.ts` — `showAgentDetail` with enable/disable/reset/delete transitions.
-3. Extract `ui/agent-creation-wizard.ts` — both AI-generation and manual form paths.
-4. Leave menu orchestration, settings form, and running-agent viewer in `agent-menu.ts` (~200 lines).
+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` drops from 650 → ~200 lines; extracted modules receive `AgentFileOps` via injection; wizard logic becomes independently testable.
+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
 

package/docs/plans/0136-decompose-agent-menu.md

@@ -0,0 +1,300 @@
+---
+issue: 136
+issue_title: "Decompose `agent-menu.ts`"
+---
+
+# Decompose agent-menu into config editor, creation wizard, and file-ops abstraction
+
+## Problem Statement
+
+`agent-menu.ts` (668 lines) has 8 distinct responsibilities: menu FSM orchestration, agent listing, config editing, agent ejection, two creation wizards, running-agent viewer, and settings form.
+Filesystem operations (`readFileSync`, `writeFileSync`, `unlinkSync`, `existsSync`, `mkdirSync`) are scattered across 10+ call sites with no abstraction layer, forcing tests to use `vi.mock("node:fs")` rather than injecting stubs.
+
+## Goals
+
+- Extract an `AgentFileOps` interface abstracting all filesystem calls, with a production `FsAgentFileOps` implementation.
+- Extract `ui/agent-config-editor.ts` (~170 lines) containing `showAgentDetail` with eject/disable/enable/edit/delete/reset transitions.
+- Extract `ui/agent-creation-wizard.ts` (~200 lines) containing both the AI-generation and manual-form creation paths.
+- Leave menu FSM, agent listing, running-agent viewer, and settings form in `agent-menu.ts` (~280 lines).
+- Each extracted module receives dependencies via injection — no direct `node:fs` imports outside `FsAgentFileOps`.
+- Enable unit testing of config editor and creation wizard without `vi.mock("node:fs")`.
+
+## Non-Goals
+
+- Refactoring the settings form or running-agent viewer — they stay in `agent-menu.ts`.
+- Changing any user-facing behavior or menu flow.
+- Extracting `showAllAgentsList` — it is menu orchestration (presents the list, delegates to editor for detail).
+- Deduplicating the YAML frontmatter builders in eject and manual wizard (structurally different content shapes).
+
+## Background
+
+### Prerequisite
+
+Issue #135 (extract display helpers) is **implemented** — `ui/display.ts` exists and provides `formatDuration`, `getDisplayName`, and other formatters.
+Extracted menu sub-modules can import display helpers without pulling in the widget.
+
+### Existing IO-injection convention
+
+The codebase uses injectable IO interfaces to decouple domain logic from `node:fs` and the Pi SDK:
+
+- `AssemblerIO` in `session-config.ts` — 4 methods for prompt assembly IO.
+- `RunnerIO` in `agent-runner.ts` — 7 methods for session creation IO.
+
+Both follow the same pattern: interface defined in the module that uses it, production implementation wired at the edge (`index.ts`), test stubs injected directly.
+
+### Current fs call inventory in agent-menu.ts
+
+| Function                         | fs calls                                                      |
+| -------------------------------- | ------------------------------------------------------------- |
+| `findAgentFile`                  | `existsSync` ×2                                               |
+| `showAgentDetail` (edit)         | `readFileSync`, `writeFileSync`                               |
+| `showAgentDetail` (delete/reset) | `unlinkSync`                                                  |
+| `ejectAgent`                     | `mkdirSync`, `existsSync`, `writeFileSync`                    |
+| `disableAgent`                   | `readFileSync`, `writeFileSync`, `mkdirSync`, `writeFileSync` |
+| `enableAgent`                    | `readFileSync`, `writeFileSync`, `unlinkSync`                 |
+| `showGenerateWizard`             | `mkdirSync`, `existsSync` ×2                                  |
+| `showManualWizard`               | `mkdirSync`, `existsSync`, `writeFileSync`                    |
+
+### Current test file
+
+`agent-menu.test.ts` (212 lines) uses `vi.mock("node:fs")` with `vi.hoisted` stubs.
+Only 7 tests exist — they cover the top-level menu, agent listing, projectAgentsDir injection, and settings delegation.
+No tests exercise config-editor transitions (edit/delete/eject/disable/enable) or creation wizards.
+
+## Design Overview
+
+### AgentFileOps interface
+
+A narrow interface abstracting all agent `.md` file operations:
+
+```typescript
+interface AgentFileOps {
+  exists(filePath: string): boolean;
+  read(filePath: string): string | undefined;
+  write(filePath: string, content: string): void;
+  remove(filePath: string): void;
+  ensureDir(dirPath: string): void;
+  findAgentFile(name: string, dirs: string[]): string | undefined;
+}
+```
+
+Design notes:
+
+- `read` returns `undefined` when the file does not exist (wraps `readFileSync` with a try/catch).
+- `write` ensures parent directories exist before writing (internalizes `mkdirSync`).
+- `ensureDir` is needed separately because `showGenerateWizard` creates the directory before spawning an agent that writes via Pi's tool (not via `AgentFileOps.write`).
+- `findAgentFile` takes an ordered list of directories and returns the first matching path.
+  The current code returns `{ path, location }` but only `showAgentDetail` uses `location` (for a confirmation dialog) — the full path already conveys the location to the user, so a plain `string | undefined` return suffices.
+
+### FsAgentFileOps production implementation
+
+Thin wrapper over `node:fs` synchronous APIs:
+
+```typescript
+class FsAgentFileOps implements AgentFileOps {
+  exists(filePath: string): boolean {
+    return existsSync(filePath);
+  }
+  read(filePath: string): string | undefined {
+    try { return readFileSync(filePath, "utf-8"); }
+    catch { return undefined; }
+  }
+  write(filePath: string, content: string): void {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, content, "utf-8");
+  }
+  remove(filePath: string): void {
+    unlinkSync(filePath);
+  }
+  ensureDir(dirPath: string): void {
+    mkdirSync(dirPath, { recursive: true });
+  }
+  findAgentFile(name: string, dirs: string[]): string | undefined {
+    for (const dir of dirs) {
+      const p = join(dir, `${name}.md`);
+      if (existsSync(p)) return p;
+    }
+    return undefined;
+  }
+}
+```
+
+### Extracted module patterns
+
+Both extracted modules follow the existing factory-function pattern (`createAgentsMenuHandler(deps)`) with narrow deps interfaces per ISP:
+
+Config editor call-site sketch (from orchestrator):
+
+```typescript
+const editor = createAgentConfigEditor({
+  fileOps: deps.fileOps,
+  registry: deps.registry,
+  personalAgentsDir: deps.personalAgentsDir,
+  projectAgentsDir: deps.projectAgentsDir,
+});
+// ...
+await editor.showAgentDetail(ctx, agentName);
+```
+
+Creation wizard call-site sketch (from orchestrator):
+
+```typescript
+const wizard = createAgentCreationWizard({
+  fileOps: deps.fileOps,
+  manager: deps.manager,
+  registry: deps.registry,
+  personalAgentsDir: deps.personalAgentsDir,
+  projectAgentsDir: deps.projectAgentsDir,
+});
+// ...
+await wizard.showCreateWizard(ctx);
+```
+
+### Deps interfaces (ISP-compliant)
+
+```typescript
+// agent-config-editor.ts
+interface AgentConfigEditorDeps {
+  fileOps: AgentFileOps;
+  registry: AgentTypeRegistry;
+  personalAgentsDir: string;
+  projectAgentsDir: string;
+}
+
+// agent-creation-wizard.ts
+interface AgentCreationWizardDeps {
+  fileOps: AgentFileOps;
+  manager: AgentMenuManager;
+  registry: AgentTypeRegistry;
+  personalAgentsDir: string;
+  projectAgentsDir: string;
+}
+```
+
+The config editor does not need `manager` (no agent spawning).
+The creation wizard does not need `agentActivity`, `getModelLabel`, or `settings`.
+
+### Updated AgentMenuDeps
+
+```typescript
+interface AgentMenuDeps {
+  manager: AgentMenuManager;
+  registry: AgentTypeRegistry;
+  agentActivity: AgentActivityReader;
+  getModelLabel: (type: string, registry?: ModelRegistry) => string;
+  settings: AgentMenuSettings;
+  fileOps: AgentFileOps;          // ← new
+  personalAgentsDir: string;
+  projectAgentsDir: string;
+}
+```
+
+The single new field (`fileOps`) replaces all direct `node:fs` imports.
+
+## Module-Level Changes
+
+### New files
+
+1. `src/ui/agent-file-ops.ts` — `AgentFileOps` interface + `FsAgentFileOps` class.
+2. `src/ui/agent-config-editor.ts` — `AgentConfigEditorDeps` interface, `createAgentConfigEditor` factory.
+   Moves in: `showAgentDetail`, `ejectAgent`, `disableAgent`, `enableAgent`.
+3. `src/ui/agent-creation-wizard.ts` — `AgentCreationWizardDeps` interface, `createAgentCreationWizard` factory.
+   Moves in: `showCreateWizard`, `showGenerateWizard`, `showManualWizard`.
+4. `test/ui/agent-file-ops.test.ts` — unit tests for `FsAgentFileOps`.
+5. `test/ui/agent-config-editor.test.ts` — unit tests for config editor transitions with injected `AgentFileOps` stubs.
+6. `test/ui/agent-creation-wizard.test.ts` — unit tests for wizard paths with injected stubs.
+
+### Modified files
+
+1. `src/ui/agent-menu.ts`:
+   - Remove `import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs"`.
+   - Remove `findAgentFile`, `showAgentDetail`, `ejectAgent`, `disableAgent`, `enableAgent`, `showCreateWizard`, `showGenerateWizard`, `showManualWizard` (~375 lines removed).
+   - Add `fileOps: AgentFileOps` to `AgentMenuDeps`.
+   - Import and instantiate `createAgentConfigEditor` and `createAgentCreationWizard`.
+   - Update `showAllAgentsList` to call `editor.showAgentDetail(ctx, agentName)`.
+   - Update `showAgentsMenu` to call `wizard.showCreateWizard(ctx)`.
+   - Re-export `AgentMenuManager` (still needed by the wizard deps).
+   - Net result: ~280 lines (orchestration, listing, running agents, settings).
+2. `src/index.ts`:
+   - Import `FsAgentFileOps` from `./ui/agent-file-ops.js`.
+   - Construct `new FsAgentFileOps()` and pass as `fileOps` in the `createAgentsMenuHandler` call.
+3. `test/ui/agent-menu.test.ts`:
+   - Remove `vi.mock("node:fs")` and `vi.hoisted` stubs entirely.
+   - Add `fileOps` stub to `makeDeps` factory.
+   - Rewrite the "projectAgentsDir injection" test to verify that the orchestrator delegates to the editor (or move to `agent-config-editor.test.ts`).
+
+### Removed symbols
+
+Grep confirms these functions are only referenced within `agent-menu.ts` (closures inside `createAgentsMenuHandler`) — no external consumers:
+
+- `findAgentFile` — moves to `agent-config-editor.ts` (reimplemented via `AgentFileOps.findAgentFile`).
+- `showAgentDetail`, `ejectAgent`, `disableAgent`, `enableAgent` — move to `agent-config-editor.ts`.
+- `showCreateWizard`, `showGenerateWizard`, `showManualWizard` — move to `agent-creation-wizard.ts`.
+
+## Test Impact Analysis
+
+### New unit tests enabled by extraction
+
+1. **Config editor transitions** — `showAgentDetail` has 6 menu paths (edit, delete, reset, eject, disable, enable) with sub-branches (confirm/cancel, file exists/not-exists, default/custom agent).
+   Currently untestable in isolation because the functions are closures inside `createAgentsMenuHandler`.
+   After extraction, each transition is testable with injected `AgentFileOps` stubs — no `vi.mock("node:fs")` needed.
+2. **Creation wizard flows** — generate wizard (spawn + check result) and manual wizard (multi-step form → write file) are currently untested.
+   After extraction, both are testable with injected stubs for `AgentFileOps` and `AgentMenuManager.spawnAndWait`.
+3. **FsAgentFileOps** — thin tests verifying the production fs wrapper (read returns undefined on missing file, write ensures parent dirs, findAgentFile checks directories in order).
+
+### Existing tests that become redundant
+
+The "projectAgentsDir injection" test (`agent-menu.test.ts`) navigates through the main menu → agent types → agent detail, then asserts `mockExistsSync` was called with the correct path.
+After extraction, this end-to-end path tests orchestration + editor together; a focused test in `agent-config-editor.test.ts` replaces it.
+The orchestrator test can be simplified to verify it delegates to the editor.
+
+### Existing tests that stay as-is
+
+- Menu structure tests (shows options, reload, running agents) — these test the orchestrator directly.
+- Settings delegation tests — these test code that remains in `agent-menu.ts`.
+
+## TDD Order
+
+### Cycle 1: AgentFileOps interface and FsAgentFileOps
+
+1. `test:` write `test/ui/agent-file-ops.test.ts` — tests for `read` (existing file, missing file), `write` (ensures parent dir), `remove`, `exists`, `ensureDir`, `findAgentFile` (first-match ordering, no match).
+2. `feat:` implement `src/ui/agent-file-ops.ts` — interface + `FsAgentFileOps` class.
+3. Commit: `feat: add AgentFileOps interface and FsAgentFileOps (#136)`.
+
+### Cycle 2: Extract agent-config-editor
+
+1. `test:` write `test/ui/agent-config-editor.test.ts` — tests for `showAgentDetail` transitions: edit (save/cancel), delete (confirm/cancel), reset-to-default (confirm/cancel), eject (project/personal location, overwrite check), disable (existing file toggle, new disable-only file), enable (remove enabled:false line, remove empty override file).
+   All tests inject stub `AgentFileOps` — no `vi.mock`.
+2. `refactor:` create `src/ui/agent-config-editor.ts` — move `showAgentDetail`, `ejectAgent`, `disableAgent`, `enableAgent` from `agent-menu.ts`.
+   Replace direct fs calls with `deps.fileOps.*` calls.
+   Replace the closure `findAgentFile` with `deps.fileOps.findAgentFile(name, [deps.projectAgentsDir, deps.personalAgentsDir])`.
+3. `refactor:` update `src/ui/agent-menu.ts` — add `fileOps` to `AgentMenuDeps`, import `createAgentConfigEditor`, wire into `showAllAgentsList`.
+4. `refactor:` update `src/index.ts` — import `FsAgentFileOps`, pass `fileOps: new FsAgentFileOps()` in deps.
+5. `test:` update `test/ui/agent-menu.test.ts` — add `fileOps` stub to `makeDeps`, rewrite the "projectAgentsDir injection" test to verify orchestrator→editor delegation.
+6. Run `pnpm run check` (interface change).
+7. Commit: `refactor: extract agent-config-editor from agent-menu (#136)`.
+
+### Cycle 3: Extract agent-creation-wizard
+
+1. `test:` write `test/ui/agent-creation-wizard.test.ts` — tests for `showCreateWizard` (location + method selection), `showGenerateWizard` (spawn success, spawn error, overwrite check), `showManualWizard` (full form flow, overwrite check, tool/model/thinking selections).
+   All tests inject stub `AgentFileOps` + `AgentMenuManager` — no `vi.mock`.
+2. `refactor:` create `src/ui/agent-creation-wizard.ts` — move `showCreateWizard`, `showGenerateWizard`, `showManualWizard` from `agent-menu.ts`.
+   Replace direct fs calls with `deps.fileOps.*` calls.
+3. `refactor:` update `src/ui/agent-menu.ts` — import `createAgentCreationWizard`, wire into `showAgentsMenu`.
+   Remove the `import { ... } from "node:fs"` line (no longer needed).
+4. `test:` remove `vi.mock("node:fs")` and `vi.hoisted` stubs from `test/ui/agent-menu.test.ts` entirely.
+5. Run `pnpm run check`.
+6. Commit: `refactor: extract agent-creation-wizard from agent-menu (#136)`.
+
+## Risks and Mitigations
+
+| Risk                                                                                                      | Mitigation                                                                                                                                                                                            |
+| --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Circular dependency between orchestrator and editor (editor calling back to menu)                         | The editor's `showAgentDetail` does not recurse to the agent list — the orchestrator does (`showAllAgentsList` calls editor then recurses itself). No circular dependency.                            |
+| `FsAgentFileOps.write` silently creates parent directories when callers expect the directory to not exist | `write` mirrors current behavior — every call site already calls `mkdirSync` before `writeFileSync`. The consolidation only changes where the `mkdirSync` happens, not whether it runs.               |
+| Adding `fileOps` to `AgentMenuDeps` breaks existing test factory                                          | Cycle 2 updates `makeDeps` in the same commit — the interface change and call-site update land together per the testing skill's single-call-site rule.                                                |
+| Generate wizard spawns an agent that writes via Pi tools, not via `AgentFileOps.write`                    | The wizard uses `fileOps.ensureDir` for directory creation and `fileOps.exists` for the post-spawn success check. The spawned agent's file write is outside the menu's control and is not abstracted. |
+
+## Open Questions
+
+- None — the issue's proposed changes section is unambiguous and the prerequisite (#135) is already implemented.

package/docs/retro/0135-extract-display-helpers.md

@@ -0,0 +1,38 @@
+---
+issue: 135
+issue_title: "Extract display helpers from `agent-widget.ts`"
+---
+
+# Retro: #135 — Extract display helpers from agent-widget.ts
+
+## Final Retrospective (2026-05-22T19:00:00Z)
+
+### Session summary
+
+Extracted 11 helper functions, 3 constants, and 2 types from `agent-widget.ts` into a new `ui/display.ts` module.
+Updated 10 source consumers and 2 test consumers.
+Pure code-motion refactoring — no behavior change, no test-count delta (714 tests throughout).
+
+### Observations
+
+#### What went well
+
+- Plan accurately identified all 10 source and 2 test import sites with no misses — the consumer import table in the plan mapped 1:1 to actual changes.
+- TDD execution was mechanical and smooth: create module → update source imports → rename test file → verify.
+  Zero surprises or deviations from the plan.
+
+#### What caused friction (agent side)
+
+- `rabbit-hole` — During `/ship-issue`, wasted ~6 tool calls investigating whether `pi-subagents-v6.12.0` was at HEAD.
+  Ran `git log --oneline HEAD --not --remotes=origin/main` which dumped the entire repo history (50KB truncation), then misread `git describe --tags --abbrev=0` (nearest ancestor tag) as confirming the tag was at HEAD.
+  `git tag --points-at HEAD` returned empty, disproving the assumption, but I still spent cycles reasoning about CI release-please behavior.
+  Impact: added friction but no rework — the close comment and release-please merge were correct.
+
+#### What caused friction (user side)
+
+- None observed.
+  The issue was unambiguous, the architecture doc prescribed the exact extraction set, and no user intervention was needed during implementation.
+
+### Changes made
+
+1. Created `packages/pi-subagents/docs/retro/0135-extract-display-helpers.md` (this file).

package/package.json

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

package/src/index.ts

@@ -41,6 +41,7 @@ import { createAgentTool } from "./tools/agent-tool.js";
 import { createGetResultTool } from "./tools/get-result-tool.js";
 import { getModelLabelFromConfig } from "./tools/helpers.js";
 import { createSteerTool } from "./tools/steer-tool.js";
+import { FsAgentFileOps } from "./ui/agent-file-ops.js";
 import { createAgentsMenuHandler } from "./ui/agent-menu.js";
 import {
   AgentWidget,
@@ -248,6 +249,7 @@ export default function (pi: ExtensionAPI) {
       return getModelLabelFromConfig(cfg.model);
     },
     settings,
+    fileOps: new FsAgentFileOps(),
     personalAgentsDir: join(getAgentDir(), 'agents'),
     projectAgentsDir: join(process.cwd(), '.pi', 'agents'),
   });

package/src/ui/agent-config-editor.ts

@@ -0,0 +1,202 @@
+/**
+ * agent-config-editor.ts — Agent detail view with edit/delete/eject/disable/enable transitions.
+ *
+ * Extracted from agent-menu.ts to give each concern a single responsibility.
+ * Receives dependencies via injection — no direct `node:fs` imports.
+ */
+
+import { join } from "node:path";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentTypeRegistry } from "../agent-types.js";
+import type { AgentConfig } from "../types.js";
+import type { AgentFileOps } from "./agent-file-ops.js";
+
+// ---- Deps interface ----
+
+export interface AgentConfigEditorDeps {
+  fileOps: AgentFileOps;
+  registry: AgentTypeRegistry;
+  personalAgentsDir: string;
+  projectAgentsDir: string;
+}
+
+// ---- Factory ----
+
+export function createAgentConfigEditor(deps: AgentConfigEditorDeps) {
+  function agentDirs(): string[] {
+    return [deps.projectAgentsDir, deps.personalAgentsDir];
+  }
+
+  async function showAgentDetail(ctx: ExtensionContext, name: string) {
+    if (deps.registry.resolveType(name) == null) {
+      ctx.ui.notify(`Agent config not found for "${name}".`, "warning");
+      return;
+    }
+    const cfg = deps.registry.resolveAgentConfig(name);
+
+    const file = deps.fileOps.findAgentFile(name, agentDirs());
+    const isDefault = cfg.isDefault === true;
+    const disabled = cfg.enabled === false;
+
+    let menuOptions: string[];
+    if (disabled && file) {
+      menuOptions = isDefault
+        ? ["Enable", "Edit", "Reset to default", "Delete", "Back"]
+        : ["Enable", "Edit", "Delete", "Back"];
+    } else if (isDefault && !file) {
+      menuOptions = ["Eject (export as .md)", "Disable", "Back"];
+    } else if (isDefault && file) {
+      menuOptions = ["Edit", "Disable", "Reset to default", "Delete", "Back"];
+    } else {
+      menuOptions = ["Edit", "Disable", "Delete", "Back"];
+    }
+
+    const choice = await ctx.ui.select(name, menuOptions);
+    if (!choice || choice === "Back") return;
+
+    if (choice === "Edit" && file) {
+      const content = deps.fileOps.read(file);
+      if (content !== undefined) {
+        const edited = await ctx.ui.editor(`Edit ${name}`, content);
+        if (edited !== undefined && edited !== content) {
+          deps.fileOps.write(file, edited);
+          deps.registry.reload();
+          ctx.ui.notify(`Updated ${file}`, "info");
+        }
+      }
+    } else if (choice === "Delete") {
+      if (file) {
+        const confirmed = await ctx.ui.confirm(
+          "Delete agent",
+          `Delete ${name} (${file})?`,
+        );
+        if (confirmed) {
+          deps.fileOps.remove(file);
+          deps.registry.reload();
+          ctx.ui.notify(`Deleted ${file}`, "info");
+        }
+      }
+    } else if (choice === "Reset to default" && file) {
+      const confirmed = await ctx.ui.confirm(
+        "Reset to default",
+        `Delete override ${file} and restore embedded default?`,
+      );
+      if (confirmed) {
+        deps.fileOps.remove(file);
+        deps.registry.reload();
+        ctx.ui.notify(`Restored default ${name}`, "info");
+      }
+    } else if (choice.startsWith("Eject")) {
+      await ejectAgent(ctx, name, cfg);
+    } else if (choice === "Disable") {
+      await disableAgent(ctx, name);
+    } else if (choice === "Enable") {
+      await enableAgent(ctx, name);
+    }
+  }
+
+  async function ejectAgent(ctx: ExtensionContext, name: string, cfg: AgentConfig) {
+    const location = await ctx.ui.select("Choose location", [
+      "Project (.pi/agents/)",
+      `Personal (${deps.personalAgentsDir})`,
+    ]);
+    if (!location) return;
+
+    const targetDir = location.startsWith("Project")
+      ? deps.projectAgentsDir
+      : deps.personalAgentsDir;
+
+    const targetPath = join(targetDir, `${name}.md`);
+    if (deps.fileOps.exists(targetPath)) {
+      const overwrite = await ctx.ui.confirm(
+        "Overwrite",
+        `${targetPath} already exists. Overwrite?`,
+      );
+      if (!overwrite) return;
+    }
+
+    const fmFields: string[] = [];
+    fmFields.push(`description: ${cfg.description}`);
+    if (cfg.displayName) fmFields.push(`display_name: ${cfg.displayName}`);
+    fmFields.push(`tools: ${cfg.builtinToolNames?.join(", ") || "all"}`);
+    if (cfg.model) fmFields.push(`model: ${cfg.model}`);
+    if (cfg.thinking) fmFields.push(`thinking: ${cfg.thinking}`);
+    if (cfg.maxTurns) fmFields.push(`max_turns: ${cfg.maxTurns}`);
+    fmFields.push(`prompt_mode: ${cfg.promptMode}`);
+    if (cfg.extensions === false) fmFields.push("extensions: false");
+    else if (Array.isArray(cfg.extensions))
+      fmFields.push(`extensions: ${cfg.extensions.join(", ")}`);
+    if (cfg.skills === false) fmFields.push("skills: false");
+    else if (Array.isArray(cfg.skills))
+      fmFields.push(`skills: ${cfg.skills.join(", ")}`);
+    if (cfg.disallowedTools?.length)
+      fmFields.push(`disallowed_tools: ${cfg.disallowedTools.join(", ")}`);
+    if (cfg.inheritContext) fmFields.push("inherit_context: true");
+    if (cfg.runInBackground) fmFields.push("run_in_background: true");
+    if (cfg.isolated) fmFields.push("isolated: true");
+    if (cfg.memory) fmFields.push(`memory: ${cfg.memory}`);
+    if (cfg.isolation) fmFields.push(`isolation: ${cfg.isolation}`);
+
+    const content = `---\n${fmFields.join("\n")}\n---\n\n${cfg.systemPrompt}\n`;
+
+    deps.fileOps.write(targetPath, content);
+    deps.registry.reload();
+    ctx.ui.notify(`Ejected ${name} to ${targetPath}`, "info");
+  }
+
+  async function disableAgent(ctx: ExtensionContext, name: string) {
+    const file = deps.fileOps.findAgentFile(name, agentDirs());
+    if (file) {
+      const content = deps.fileOps.read(file);
+      if (content?.includes("\nenabled: false\n")) {
+        ctx.ui.notify(`${name} is already disabled.`, "info");
+        return;
+      }
+      if (content) {
+        const updated = content.replace(/^---\n/, "---\nenabled: false\n");
+        deps.fileOps.write(file, updated);
+        deps.registry.reload();
+        ctx.ui.notify(`Disabled ${name} (${file})`, "info");
+      }
+      return;
+    }
+
+    const location = await ctx.ui.select("Choose location", [
+      "Project (.pi/agents/)",
+      `Personal (${deps.personalAgentsDir})`,
+    ]);
+    if (!location) return;
+
+    const targetDir = location.startsWith("Project")
+      ? deps.projectAgentsDir
+      : deps.personalAgentsDir;
+
+    const targetPath = join(targetDir, `${name}.md`);
+    deps.fileOps.write(targetPath, "---\nenabled: false\n---\n");
+    deps.registry.reload();
+    ctx.ui.notify(`Disabled ${name} (${targetPath})`, "info");
+  }
+
+  async function enableAgent(ctx: ExtensionContext, name: string) {
+    const file = deps.fileOps.findAgentFile(name, agentDirs());
+    if (!file) return;
+
+    const content = deps.fileOps.read(file);
+    if (!content) return;
+
+    const updated = content.replace(/^(---\n)enabled: false\n/, "$1");
+
+    if (updated.trim() === "---\n---" || updated.trim() === "---\n---\n") {
+      deps.fileOps.remove(file);
+      deps.registry.reload();
+      ctx.ui.notify(`Enabled ${name} (removed ${file})`, "info");
+    } else {
+      deps.fileOps.write(file, updated);
+      deps.registry.reload();
+      ctx.ui.notify(`Enabled ${name} (${file})`, "info");
+    }
+  }
+
+  return { showAgentDetail };
+}