@gotgenes/pi-subagents 5.8.1 → 5.8.2

package/CHANGELOG.md

@@ -5,6 +5,14 @@ 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).
 
+## [5.8.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.8.1...pi-subagents-v5.8.2) (2026-05-20)
+
+
+### Documentation
+
+* plan inject projectAgentsDir into AgentMenuDeps ([#77](https://github.com/gotgenes/pi-packages/issues/77)) ([d8cf039](https://github.com/gotgenes/pi-packages/commit/d8cf03944d0abc6230541d67655d89582665a615))
+* **retro:** add retro notes for issue [#66](https://github.com/gotgenes/pi-packages/issues/66) ([ce0f04a](https://github.com/gotgenes/pi-packages/commit/ce0f04a3d84523a4c2e8b7bc998b5bec0f16970f))
+
 ## [5.8.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.8.0...pi-subagents-v5.8.1) (2026-05-20)
 
 

package/docs/plans/0077-inject-project-agents-dir.md

@@ -0,0 +1,115 @@
+---
+issue: 77
+issue_title: "refactor: add projectAgentsDir to AgentMenuDeps instead of reading process.cwd() inline"
+---
+
+# Inject projectAgentsDir into AgentMenuDeps
+
+## Problem Statement
+
+`createAgentsMenuHandler` computes the project agents directory by reading `process.cwd()` inline via a lambda on line 63 of `ui/agent-menu.ts`:
+
+```typescript
+const projectAgentsDir = () => join(process.cwd(), ".pi", "agents");
+```
+
+The `AgentMenuDeps` interface already carries `personalAgentsDir: string` as an explicit field, but the project-side equivalent bypasses the injection boundary entirely.
+`projectAgentsDir()` is called in at least five places inside the handler (`findAgentFile`, `ejectAgent`, `disableAgent`, `showCreateWizard`, `showManualWizard`).
+This violates the code-style rule: "Do not read `process.cwd()` inside library/utility functions — accept the value as a parameter."
+
+## Goals
+
+- Add `projectAgentsDir: string` to `AgentMenuDeps`.
+- Remove the inline `projectAgentsDir` lambda from `createAgentsMenuHandler`.
+- Replace all five call sites with `deps.projectAgentsDir`.
+- Wire the value at the call site in `index.ts` as `join(process.cwd(), ".pi", "agents")`.
+- Update the test helper `makeDeps()` in `agent-menu.test.ts` to supply the new field.
+
+## Non-Goals
+
+- Removing other `process.cwd()` calls in `index.ts` (e.g., `loadCustomAgents`, `GitWorktreeManager`).
+  Those are separate concerns tracked or already addressed elsewhere (e.g., #76 for `AgentManager`).
+- Changing `personalAgentsDir` wiring or any other `AgentMenuDeps` fields.
+
+## Background
+
+### Relevant modules
+
+| Module                       | Role                                                                                                                 |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `src/ui/agent-menu.ts`       | Contains `AgentMenuDeps` interface and `createAgentsMenuHandler` factory. Owns the inline `projectAgentsDir` lambda. |
+| `src/index.ts`               | Extension entry point. Constructs the `AgentMenuDeps` object at line 228. Already passes `personalAgentsDir`.        |
+| `test/ui/agent-menu.test.ts` | Tests for the menu handler. Has a `makeDeps()` helper that constructs `AgentMenuDeps`.                               |
+
+### Constraints
+
+From code-style skill:
+
+> Do not read `process.env`, `process.cwd()`, or `process.platform` inside library/utility functions — accept the value as a parameter.
+
+This is the same pattern applied in #76 (inject `cwd` into `AgentManager`), now applied to the UI layer.
+
+`AgentMenuDeps` is internal — the public API surface (`exports` in `package.json`) is `service.ts` only, so this is a non-breaking change for consumers.
+
+## Design Overview
+
+The change is mechanical — add a field, remove a lambda, replace call sites:
+
+1. Add `projectAgentsDir: string` to `AgentMenuDeps` (mirrors the existing `personalAgentsDir` field).
+2. Delete the `const projectAgentsDir = () => join(process.cwd(), ".pi", "agents");` lambda inside `createAgentsMenuHandler`.
+3. Replace all five `projectAgentsDir()` call sites with `deps.projectAgentsDir`:
+   - `findAgentFile` (line 68)
+   - `ejectAgent` (line 312)
+   - `disableAgent` (line 378)
+   - `showCreateWizard` (line 416)
+   - `showManualWizard` — uses the `targetDir` value from `showCreateWizard`, so not a direct call site
+4. At the call site in `index.ts`, add `projectAgentsDir: join(process.cwd(), ".pi", "agents")` to the deps object.
+5. In `makeDeps()`, add `projectAgentsDir: "/test-project/.pi/agents"`.
+
+No new types, no interface changes beyond the one added field.
+
+## Module-Level Changes
+
+### `src/ui/agent-menu.ts`
+
+- Add `projectAgentsDir: string` to the `AgentMenuDeps` interface.
+- Remove the `const projectAgentsDir = () => join(process.cwd(), ".pi", "agents");` lambda.
+- Replace `projectAgentsDir()` with `deps.projectAgentsDir` at all call sites inside the factory closure.
+- The `join` import from `node:path` may become unused in this file if no other call uses it — verify and remove if so.
+
+### `src/index.ts`
+
+- Add `projectAgentsDir: join(process.cwd(), ".pi", "agents")` to the `createAgentsMenuHandler({...})` call.
+- Import `join` from `node:path` if not already imported.
+
+### `test/ui/agent-menu.test.ts`
+
+- Add `projectAgentsDir: "/test-project/.pi/agents"` to `makeDeps()`.
+- No other test logic changes.
+
+## Test Impact Analysis
+
+1. No new unit tests are strictly required — the refactoring is mechanical and preserves behavior.
+   However, a targeted test verifying that `findAgentFile` uses the injected `projectAgentsDir` (not `process.cwd()`) is valuable to prevent regression.
+2. No existing tests become redundant.
+3. All existing tests stay as-is; only the `makeDeps()` helper needs the new field.
+
+## TDD Order
+
+1. **Red: test that the injected projectAgentsDir is used** — add a test in `agent-menu.test.ts` that mocks `existsSync` and verifies `findAgentFile` (exercised via the menu handler) checks a path under the injected `projectAgentsDir`, not under `process.cwd()`.
+   Commit message: `test: verify projectAgentsDir injection in agent menu (#77)`
+
+2. **Green: add projectAgentsDir to AgentMenuDeps and wire it** — add the field to `AgentMenuDeps`, remove the inline lambda, replace all call sites with `deps.projectAgentsDir`, wire the value in `index.ts`, and update `makeDeps()` in the test helper.
+   Commit message: `refactor: inject projectAgentsDir into AgentMenuDeps (#77)`
+
+## Risks and Mitigations
+
+| Risk                                            | Mitigation                                                                                                                                                                            |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Missing a `projectAgentsDir()` call site        | `grep 'projectAgentsDir'` in `agent-menu.ts` confirms exactly five call sites (one definition + four usages). After the change, grep again to verify no `process.cwd()` calls remain. |
+| `join` import becomes unused in `agent-menu.ts` | Check whether `join` is used elsewhere in the file (it is — `findAgentFile` uses `join` for the personal path). The import stays.                                                     |
+| Behavioral change                               | Production call site passes `join(process.cwd(), ".pi", "agents")`, which produces the same value the lambda computed. No behavioral change.                                          |
+
+## Open Questions
+
+None — the issue's proposed change is unambiguous and mirrors the established `personalAgentsDir` pattern.

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

@@ -0,0 +1,44 @@
+---
+issue: 66
+issue_title: "refactor: replace `as any` casts in extracted tool/menu factories with proper SDK types"
+---
+
+# Retro: #66 — replace `as any` casts with proper SDK types
+
+## Final Retrospective (2026-05-20T18:50:00Z)
+
+### Session summary
+
+Replaced all 14 `as any` casts in `src/index.ts` by typing 5 factory dep interfaces with proper SDK types (`ExtensionContext`, `AgentSession`, `ExtensionAPI`, `ModelRegistry`) and the newly-exported `SpawnOptions`.
+Released as `pi-subagents-v5.8.1` with zero behavioral change across 520 tests.
+The plan, implementation, and shipping were completed in a single session with 6 implementation commits.
+
+### Observations
+
+#### What went well
+
+- Thorough context-gathering during planning paid off: reading all 5 dep interfaces, the SDK `.d.ts` files, test mock helpers, and the `ExtensionUIContext` shape before writing the plan meant most steps landed on first `pnpm run check`.
+- The plan's risk table anticipated the cascading `as any` issue on `createAgentTool` and prepared a mitigation ("add explicit `satisfies ToolDefinition<…>` if needed"), which was close to the actual fix needed.
+- Steps 4 and 5 (`GetResultDeps`, `SteerToolDeps`) were trivially clean — single-type-import changes that compiled immediately.
+
+#### What caused friction (agent side)
+
+- `missing-context` — The plan assumed `NotificationDeps.sendMessage.display` could be optional (`display?: boolean`) but the SDK's `CustomMessage.display` is required `boolean`.
+  First `pnpm run check` after step 2 failed; required one extra edit-verify cycle.
+  Impact: added friction but no rework (fixed in the same commit).
+
+- `missing-context` — The plan did not check the `execute` function's full signature in `agent-tool.ts`.
+  Removing the outer `as any` on `createAgentTool({...})` exposed three additional type mismatches: `onUpdate` parameter type (`unknown` vs `AgentToolResult<any>`), `signal` optionality (`AbortSignal` vs `AbortSignal | undefined`), and `params.description` (`unknown` vs `string`).
+  The plan flagged cascading risk but assumed only the return type would be affected.
+  Impact: step 3 required three extra edits and two extra `pnpm run check` cycles, noted as a deviation in the commit body.
+
+- `missing-context` — Steps 6 and 7 had to be folded into one commit.
+  The plan listed them as independent steps but typing `AgentMenuManager.spawnAndWait(ctx: ExtensionContext)` immediately made `MenuContext` incompatible — `showGenerateWizard` passes `ctx: MenuContext` to the dep callback that now expects `ExtensionContext`.
+  The testing skill already warns: "when a TDD plan lists separate steps that share a type definition, changing that type in step N breaks steps N+1…N+k."
+  The planner failed to recognize that `MenuContext` and `AgentMenuManager.spawnAndWait` share a type dependency through `ctx`.
+  Impact: no rework — the steps were folded successfully — but the plan's step count was inaccurate.
+
+#### What caused friction (user side)
+
+- No user-side friction observed.
+  The user ran three sequential prompts (`/plan-issue 66`, `/tdd-plan`, `/ship-issue`) with no corrections or redirects needed.

package/package.json

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

package/src/index.ts

@@ -264,6 +264,7 @@ export default function (pi: ExtensionAPI) {
     ),
     emitEvent: (name, data) => pi.events.emit(name, data),
     personalAgentsDir: join(getAgentDir(), 'agents'),
+    projectAgentsDir: join(process.cwd(), '.pi', 'agents'),
   });
 
   pi.registerCommand('agents', {

package/src/ui/agent-menu.ts

@@ -41,6 +41,7 @@ export interface AgentMenuDeps {
   ) => { message: string; level: string };
   emitEvent: (name: string, data: unknown) => void;
   personalAgentsDir: string;
+  projectAgentsDir: string;
   /** Returns the runtime default max turns (undefined = unlimited). */
   getDefaultMaxTurns: () => number | undefined;
   /** Returns the runtime grace turns value. */
@@ -60,12 +61,10 @@ export interface AgentMenuDeps {
  * Returns a function suitable for `pi.registerCommand("agents", { handler })`.
  */
 export function createAgentsMenuHandler(deps: AgentMenuDeps) {
-  const projectAgentsDir = () => join(process.cwd(), ".pi", "agents");
-
   function findAgentFile(
     name: string,
   ): { path: string; location: "project" | "personal" } | undefined {
-    const projectPath = join(projectAgentsDir(), `${name}.md`);
+    const projectPath = join(deps.projectAgentsDir, `${name}.md`);
     if (existsSync(projectPath)) return { path: projectPath, location: "project" };
     const personalPath = join(deps.personalAgentsDir, `${name}.md`);
     if (existsSync(personalPath)) return { path: personalPath, location: "personal" };
@@ -309,7 +308,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     if (!location) return;
 
     const targetDir = location.startsWith("Project")
-      ? projectAgentsDir()
+      ? deps.projectAgentsDir
       : deps.personalAgentsDir;
     mkdirSync(targetDir, { recursive: true });
 
@@ -375,7 +374,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     if (!location) return;
 
     const targetDir = location.startsWith("Project")
-      ? projectAgentsDir()
+      ? deps.projectAgentsDir
       : deps.personalAgentsDir;
     mkdirSync(targetDir, { recursive: true });
 
@@ -413,7 +412,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     if (!location) return;
 
     const targetDir = location.startsWith("Project")
-      ? projectAgentsDir()
+      ? deps.projectAgentsDir
       : deps.personalAgentsDir;
 
     const method = await ctx.ui.select("Creation method", [