@gotgenes/pi-subagents 7.7.0 → 7.8.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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).
 
+## [7.8.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.7.0...pi-subagents-v7.8.0) (2026-05-26)
+
+
+### Features
+
+* inject agentDir into SettingsManager and loadSettings to remove SDK dependency ([7dcb986](https://github.com/gotgenes/pi-packages/commit/7dcb9868c8ac52c86a3eac0b6fc6648c8d57fc7c))
+* wire agentDir from SDK boundary in index.ts ([#218](https://github.com/gotgenes/pi-packages/issues/218)) ([17e9fc5](https://github.com/gotgenes/pi-packages/commit/17e9fc5f7880ae92168a6bb30e6fbc82748b7b2a))
+
+
+### Documentation
+
+* plan push SDK boundary in settings.ts ([#218](https://github.com/gotgenes/pi-packages/issues/218)) ([19f7cd6](https://github.com/gotgenes/pi-packages/commit/19f7cd6ddfa28290f7e61e6273d966c946868cf6))
+* **retro:** add planning stage notes for issue [#218](https://github.com/gotgenes/pi-packages/issues/218) ([80be50e](https://github.com/gotgenes/pi-packages/commit/80be50e1b6ddf19f743010bd4c3cdf232d901cf1))
+* **retro:** add retro notes for issue [#217](https://github.com/gotgenes/pi-packages/issues/217) ([2140655](https://github.com/gotgenes/pi-packages/commit/21406555e34fbe0d41f48206e3208e1cb7326633))
+* **retro:** add TDD stage notes for issue [#218](https://github.com/gotgenes/pi-packages/issues/218) ([86b4f94](https://github.com/gotgenes/pi-packages/commit/86b4f946d7498e96dbb2b4c513d0ea6331fc5f8c))
+
 ## [7.7.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.6.0...pi-subagents-v7.7.0) (2026-05-26)
 
 

package/docs/architecture/architecture.md

@@ -584,7 +584,10 @@ The IO boundary was split into two focused interfaces:
 export interface EnvironmentIO {
   detectEnv: (exec: ShellExec, cwd: string) => Promise<EnvInfo>;
   getAgentDir: () => string;
-  deriveSessionDir: (parentSessionFile: string | undefined, effectiveCwd: string) => string;
+  deriveSessionDir: (
+    parentSessionFile: string | undefined,
+    effectiveCwd: string,
+  ) => string;
 }
 
 /** Session factory — create SDK objects for a child agent session. */
@@ -592,7 +595,9 @@ export interface SessionFactoryIO {
   createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoaderLike;
   createSessionManager: (cwd: string, sessionDir: string) => SessionManagerLike;
   createSettingsManager: (cwd: string, agentDir: string) => SettingsManager;
-  createSession: (opts: CreateSessionOptions) => Promise<{ session: AgentSession }>;
+  createSession: (
+    opts: CreateSessionOptions,
+  ) => Promise<{ session: AgentSession }>;
   assemblerIO: AssemblerIO;
 }
 
@@ -643,7 +648,7 @@ Three closure factories converted to classes in [#214].
 - Smell: C (coupling — deps hidden in closure scope instead of explicit on class)
 - Outcome: 0 remaining closure factories (excluding pure-function factories), deps visible as constructor parameters
 
-### Step 2: Decompose `buildParentContext` (cognitive 30) — [#215]
+### Step 2: Decompose `buildParentContext` (cognitive 30) — [#215] ✓
 
 `buildParentContext` in `session/context.ts` is the only remaining fallow refactoring target.
 The function loops over branch entries with 3 type-check branches, each with sub-branches for role or summary.
@@ -671,7 +676,7 @@ Extracted:
 - Smell: B (oversized method) + A (duplicated finalization logic in then/catch)
 - Outcome: `startAgent` reduced to ~40 LOC coordinator with zero mutable `let` bindings; `.then()`/`.catch()` are one-liners
 
-### Step 4: Extract overwrite guard from UI — [#217]
+### Step 4: Extract overwrite guard from UI — [#217] ✓
 
 The 20-line pattern duplicated between `agent-config-editor.ts:138–151` and `agent-creation-wizard.ts:231–250` checks file existence, prompts for confirmation, writes the file, reloads the registry, and notifies the user.
 Extract a shared `writeAgentFile(fileOps, ui, registry, targetPath, content, label)` function.
@@ -680,7 +685,7 @@ Extract a shared `writeAgentFile(fileOps, ui, registry, targetPath, content, lab
 - Smell: A (production duplication)
 - Outcome: 0 production clone groups
 
-### Step 5: Push SDK boundary in `settings.ts` — [#218]
+### Step 5: Push SDK boundary in `settings.ts` — [#218] ✓
 
 `globalPath()` calls `getAgentDir()` (a Pi SDK function) at invocation time.
 This hides a platform dependency inside a module that is otherwise pure configuration logic.
@@ -890,7 +895,6 @@ The upstream test suite is run periodically as a regression canary for the agent
 [earendil-works/pi#4207]: https://github.com/earendil-works/pi/issues/4207
 [gotgenes/pi-packages]: https://github.com/gotgenes/pi-packages
 [tintinweb/pi-subagents]: https://github.com/tintinweb/pi-subagents
-
 [166]: https://github.com/gotgenes/pi-packages/issues/166
 [167]: https://github.com/gotgenes/pi-packages/issues/167
 [168]: https://github.com/gotgenes/pi-packages/issues/168

package/docs/plans/0218-push-sdk-boundary-in-settings.md

@@ -0,0 +1,172 @@
+---
+issue: 218
+issue_title: "Push SDK boundary in settings.ts (Phase 13, Step 5)"
+---
+
+# Push SDK boundary in settings.ts
+
+## Problem Statement
+
+`settings.ts` imports `getAgentDir` from the Pi SDK (`@earendil-works/pi-coding-agent`) and calls it inside `globalPath()` at invocation time.
+This hides a platform dependency inside a module that is otherwise pure configuration logic — violating the project's SDK-boundary rule that pure helpers and domain modules should remain SDK-independent.
+The SDK call also forces tests to redirect the env var `PI_CODING_AGENT_DIR` to control `getAgentDir()` output, rather than passing the value directly.
+
+## Goals
+
+- Remove the `getAgentDir` import from `settings.ts` (0 Pi SDK imports).
+- Inject `agentDir: string` into `SettingsManager` constructor deps.
+- Make `loadSettings` accept `agentDir` as an explicit parameter.
+- Eliminate `PI_CODING_AGENT_DIR` env var manipulation from all settings tests.
+
+## Non-Goals
+
+- Removing `process.cwd()` defaults from `loadSettings`/`saveSettings` — that's a separate concern (Node.js API, not Pi SDK).
+- Pushing SDK boundaries in other files (`skill-loader.ts`, `custom-agents.ts`, `agent-runner.ts`) — tracked separately in the Phase 13 roadmap.
+- Changing the `saveSettings` signature — it only calls `projectPath(cwd)` and has no SDK dependency.
+
+## Background
+
+`settings.ts` exports a `SettingsManager` class and two free functions (`loadSettings`, `saveSettings`).
+The only SDK import is `getAgentDir`, used in the private `globalPath()` helper to compute the global settings file path (`~/.pi/agent/subagents.json`).
+
+The `SettingsManager` constructor already accepts a deps bag `{ emit, cwd, onMaxConcurrentChanged? }`.
+Adding `agentDir` to this bag follows the established injection pattern.
+
+In `index.ts`, `getAgentDir` is already imported for several other call sites (agent runner IO, agent tool, `/agents` menu).
+Adding one more usage to the `SettingsManager` construction is zero new imports.
+
+### Relevant AGENTS.md constraints
+
+- **Pi SDK boundaries:** Keep Pi SDK imports out of business-logic modules; accept the value as a parameter or callback.
+- **Code-design skill, DIP:** Default to dependency injection for non-trivial dependencies.
+
+## Design Overview
+
+### Change to `globalPath()`
+
+Currently:
+
+```typescript
+function globalPath(): string {
+  return join(getAgentDir(), "subagents.json");
+}
+```
+
+After:
+
+```typescript
+function globalPath(agentDir: string): string {
+  return join(agentDir, "subagents.json");
+}
+```
+
+### Change to `loadSettings()`
+
+Currently:
+
+```typescript
+export function loadSettings(cwd: string = process.cwd()): SubagentsSettings {
+  return { ...readSettingsFile(globalPath()), ...readSettingsFile(projectPath(cwd)) };
+}
+```
+
+After:
+
+```typescript
+export function loadSettings(agentDir: string, cwd: string = process.cwd()): SubagentsSettings {
+  return { ...readSettingsFile(globalPath(agentDir)), ...readSettingsFile(projectPath(cwd)) };
+}
+```
+
+### Change to `SettingsManager` constructor
+
+Add `agentDir: string` to the deps bag:
+
+```typescript
+constructor(deps: { emit: SettingsEmit; cwd: string; agentDir: string; onMaxConcurrentChanged?: () => void }) {
+  this.emit = deps.emit;
+  this.cwd = deps.cwd;
+  this.agentDir = deps.agentDir;
+  this.onMaxConcurrentChanged = deps.onMaxConcurrentChanged;
+}
+```
+
+`SettingsManager.load()` passes `this.agentDir` to `loadSettings`:
+
+```typescript
+load(): SubagentsSettings {
+  const settings = loadSettings(this.agentDir, this.cwd);
+  // ... rest unchanged
+}
+```
+
+### Wiring in `index.ts`
+
+```typescript
+const settings = new SettingsManager({
+  emit: (event, payload) => pi.events.emit(event, payload),
+  cwd: process.cwd(),
+  agentDir: getAgentDir(),
+  onMaxConcurrentChanged: () => manager.notifyConcurrencyChanged(),
+});
+```
+
+## Module-Level Changes
+
+### `src/settings.ts`
+
+1. Remove `import { getAgentDir } from "@earendil-works/pi-coding-agent"`.
+2. Add `agentDir: string` field to the `SettingsManager` constructor deps interface.
+3. Store `this.agentDir = deps.agentDir` as a private readonly field.
+4. Change `globalPath()` signature to `globalPath(agentDir: string)`.
+5. Change `loadSettings` signature to `loadSettings(agentDir: string, cwd?: string)`.
+6. Update `SettingsManager.load()` to call `loadSettings(this.agentDir, this.cwd)`.
+7. Update the header comment to reflect the new injection pattern.
+
+### `src/index.ts`
+
+1. Add `agentDir: getAgentDir()` to the `SettingsManager` constructor deps object.
+
+### `test/settings.test.ts`
+
+1. Remove all `PI_CODING_AGENT_DIR` env manipulation (`originalAgentDirEnv`, `beforeEach`/`afterEach` stubs).
+2. Pass `globalDir` directly to `loadSettings(globalDir, projectDir)` in free-function tests.
+3. Add `agentDir: globalDir` (or a dummy string for non-load tests) to all `new SettingsManager(...)` calls.
+4. In `SettingsManager.load()` tests, pass `agentDir: globalDir` to the constructor.
+5. In tests that don't exercise `load()`, use `agentDir: "/nonexistent"` or similar — the value is unused.
+
+## Test Impact Analysis
+
+1. **New capability:** Free-function tests (`loadSettings`, `saveSettings`) become pure — pass `globalDir` directly instead of manipulating `PI_CODING_AGENT_DIR`.
+   This is simpler and more reliable.
+2. **Redundant cleanup:** The `originalAgentDirEnv` save/restore pattern in `beforeEach`/`afterEach` can be removed from all `describe` blocks that use it.
+3. **Existing tests stay:** All existing test scenarios remain valid; only their setup mechanics change.
+
+## TDD Order
+
+1. **Red → Green:** Change `loadSettings` signature to accept `agentDir` parameter; update `globalPath` to accept it.
+   Update all free-function tests to pass `globalDir` directly instead of env var.
+   Remove env-var manipulation from the `settings persistence` describe block.
+   Commit: `feat: inject agentDir into loadSettings to remove SDK dependency`
+
+2. **Red → Green:** Add `agentDir` to `SettingsManager` constructor deps; store as private field; thread into `load()`.
+   Update all `new SettingsManager(...)` call sites in tests.
+   Remove env-var manipulation from `SettingsManager` describe blocks.
+   Remove `getAgentDir` import from `settings.ts`.
+   Commit: `feat: inject agentDir into SettingsManager constructor`
+
+3. **Green:** Wire `agentDir: getAgentDir()` into `SettingsManager` construction in `index.ts`.
+   Run `pnpm run check` to confirm no type errors across the package.
+   Commit: `feat: wire agentDir from SDK boundary in index.ts (#218)`
+
+## Risks and Mitigations
+
+| Risk                                                                                  | Mitigation                                                                                                   |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Breaking the `loadSettings` export signature for hypothetical external callers        | The function is only called from `SettingsManager.load()` and tests; no external consumers exist.            |
+| Test count is high (~35 constructor sites) — mechanical updates could introduce typos | Steps 1 and 2 are focused; run `pnpm vitest run test/settings.test.ts` after each to confirm.                |
+| Forgetting a test site that still manipulates `PI_CODING_AGENT_DIR`                   | Grep for `PI_CODING_AGENT_DIR` after step 2 to confirm zero remaining references in `test/settings.test.ts`. |
+
+## Open Questions
+
+None — the issue's proposed change is unambiguous and follows the established injection pattern used in prior Phase 13 steps.

package/docs/retro/0217-extract-overwrite-guard.md

@@ -34,3 +34,30 @@ Test count: 962 → 970 (+8 new tests in `test/ui/agent-file-writer.test.ts`).
 - Both consumer refactors were straightforward one-import-add + one-block-replace edits; all existing tests passed without modification, confirming the extraction preserved exact behavior.
 - The notification label `"Ejected ${name} to"` (with trailing space absorbed by `${targetPath}`) matched the pre-existing message format `"Ejected test-agent to /path"` exactly — no test assertions changed.
 - `FileWriter`, `WriterUI`, and `Reloadable` narrow interfaces are exported from `agent-file-writer.ts`; both consumer files import the concrete types from their original sources, satisfying TypeScript's structural checker without any casts.
+
+## Stage: Final Retrospective (2026-05-26T21:00:00Z)
+
+### Session summary
+
+Full plan → TDD → ship → release lifecycle completed in a single continuous session.
+Released as `pi-subagents-v7.7.0`.
+Zero rework, zero test failures, zero CI issues.
+
+### Observations
+
+#### What went well
+
+- The Phase 13 roadmap's step-level issue decomposition produced an issue (#217) that was right-sized for fully autonomous execution — the entire lifecycle completed without any blocking questions or scope surprises.
+- ISP-narrow interfaces (`FileWriter`, `WriterUI`, `Reloadable`) structurally satisfied both consumer types without casts, confirming the plan's design.
+- Existing tests in both consumer files passed without modification after the refactors, validating that the extraction preserved exact behavior.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — The plan split TDD steps 1 (happy-path tests) and 2 (overwrite-guard tests) for a ~10-line function with a single conditional.
+  Writing all 8 tests at once and implementing the full function body in one pass was natural; splitting them would have been artificial.
+  Self-corrected by folding into one commit.
+  Impact: added friction but no rework — the plan said "implementation should already pass" for step 2, acknowledging the fold was expected.
+
+#### What caused friction (user side)
+
+- Nothing notable — the issue was well-scoped with clear target files, a concrete smell label, and an explicit dependency chain.

package/docs/retro/0218-push-sdk-boundary-in-settings.md

@@ -0,0 +1,35 @@
+---
+issue: 218
+issue_title: "Push SDK boundary in settings.ts (Phase 13, Step 5)"
+---
+
+# Retro: #218 — Push SDK boundary in settings.ts
+
+## Stage: Planning (2026-05-26T17:01:55Z)
+
+### Session summary
+
+Produced a 3-step TDD plan to inject `agentDir: string` into `SettingsManager` and `loadSettings`, removing the only Pi SDK import from `settings.ts`.
+The change is straightforward — a single parameter addition threading through constructor, free function, and boundary wiring.
+
+### Observations
+
+- The change is entirely mechanical: no design ambiguity, no new abstractions, no breaking public API.
+- The main implementation effort is in test updates (~35 `new SettingsManager(...)` call sites plus ~15 `loadSettings(...)` calls), all requiring an `agentDir` argument.
+- All test `describe` blocks that manipulate `PI_CODING_AGENT_DIR` env var can drop that scaffolding entirely, simplifying setup/teardown.
+- `saveSettings` has no SDK dependency and needs no signature change — only `loadSettings` calls `globalPath()`.
+
+## Stage: Implementation — TDD (2026-05-26T17:13:26Z)
+
+### Session summary
+
+Completed all 3 plan steps across 2 commits plus 1 doc commit.
+All 970 tests pass; `settings.ts` now has 0 Pi SDK imports and all `PI_CODING_AGENT_DIR` env var manipulation is gone from `settings.test.ts`.
+
+### Observations
+
+- **Steps 1+2 combined:** Changing `loadSettings(cwd)` to `loadSettings(agentDir, cwd)` forced updating `SettingsManager.load()` in the same commit — they were inseparable (esbuild skips type checks, so the old call compiled but produced wrong runtime behavior).
+  The two production changes landed in one commit with a note in the body.
+- **Test simplification was significant:** Removed `originalAgentDirEnv` save/restore scaffolding from 5 `describe` blocks; the test code shrank by 32 lines net.
+- **`/nonexistent` sentinel:** Tests that construct `SettingsManager` but never call `load()` pass `agentDir: "/nonexistent"` — a clear signal the field is unused in that scope.
+- Architecture doc Step 5 heading marked `✓` and folded into the last `feat:` commit by `pi-autoformat`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "7.7.0",
+  "version": "7.8.0",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/index.ts

@@ -70,6 +70,7 @@ export default function (pi: ExtensionAPI) {
   const settings = new SettingsManager({
     emit: (event, payload) => pi.events.emit(event, payload),
     cwd: process.cwd(),
+    agentDir: getAgentDir(),
     onMaxConcurrentChanged: () => manager.notifyConcurrencyChanged(),
   });
   settings.load();

package/src/settings.ts

@@ -1,10 +1,9 @@
 // Persistence for pi-subagents operational settings.
-// - Global:  ~/.pi/agent/subagents.json (via getAgentDir()) — manual defaults, never written here
+// - Global:  ~/.pi/agent/subagents.json (agentDir injected at construction) — manual defaults, never written here
 // - Project: <cwd>/.pi/subagents.json — written by /agents → Settings; overrides global on load
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 export interface SubagentsSettings {
   maxConcurrent?: number;
   /**
@@ -34,11 +33,13 @@ export class SettingsManager {
 
   private readonly emit: SettingsEmit;
   private readonly cwd: string;
+  private readonly agentDir: string;
   private readonly onMaxConcurrentChanged: (() => void) | undefined;
 
-  constructor(deps: { emit: SettingsEmit; cwd: string; onMaxConcurrentChanged?: () => void }) {
+  constructor(deps: { emit: SettingsEmit; cwd: string; agentDir: string; onMaxConcurrentChanged?: () => void }) {
     this.emit = deps.emit;
     this.cwd = deps.cwd;
+    this.agentDir = deps.agentDir;
     this.onMaxConcurrentChanged = deps.onMaxConcurrentChanged;
   }
 
@@ -84,7 +85,7 @@ export class SettingsManager {
    * Returns the raw loaded settings object.
    */
   load(): SubagentsSettings {
-    const settings = loadSettings(this.cwd);
+    const settings = loadSettings(this.agentDir, this.cwd);
     if (typeof settings.maxConcurrent === "number") this.maxConcurrent = settings.maxConcurrent;
     if (typeof settings.defaultMaxTurns === "number") this.defaultMaxTurns = settings.defaultMaxTurns;
     if (typeof settings.graceTurns === "number") this.graceTurns = settings.graceTurns;
@@ -180,8 +181,8 @@ function sanitize(raw: unknown): SubagentsSettings {
   return out;
 }
 
-function globalPath(): string {
-  return join(getAgentDir(), "subagents.json");
+function globalPath(agentDir: string): string {
+  return join(agentDir, "subagents.json");
 }
 
 function projectPath(cwd: string): string {
@@ -205,8 +206,8 @@ function readSettingsFile(path: string): SubagentsSettings {
 }
 
 /** Load merged settings: global provides defaults, project overrides. */
-export function loadSettings(cwd: string = process.cwd()): SubagentsSettings {
-  return { ...readSettingsFile(globalPath()), ...readSettingsFile(projectPath(cwd)) };
+export function loadSettings(agentDir: string, cwd: string = process.cwd()): SubagentsSettings {
+  return { ...readSettingsFile(globalPath(agentDir)), ...readSettingsFile(projectPath(cwd)) };
 }
 
 /**