@gotgenes/pi-subagents 6.18.0 → 6.18.1

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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.18.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.18.0...pi-subagents-v6.18.1) (2026-05-24)
+
+
+### Documentation
+
+* plan decompose ResolvedSpawnConfig ([#165](https://github.com/gotgenes/pi-packages/issues/165)) ([1b14d56](https://github.com/gotgenes/pi-packages/commit/1b14d56aaada427a7344ec22adb4bbf8d7ce0bf7))
+* **retro:** add planning stage notes for issue [#165](https://github.com/gotgenes/pi-packages/issues/165) ([8e0476a](https://github.com/gotgenes/pi-packages/commit/8e0476afa991953884455c7dd09c7ffb742cb329))
+* **retro:** add TDD stage notes for issue [#165](https://github.com/gotgenes/pi-packages/issues/165) ([68248e5](https://github.com/gotgenes/pi-packages/commit/68248e572d38ad6e0cdb61bdd22f2b46193eaac6))
+
 ## [6.18.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.17.2...pi-subagents-v6.18.0) (2026-05-24)
 
 

package/docs/plans/0165-decompose-resolved-spawn-config.md

@@ -0,0 +1,157 @@
+---
+issue: 165
+issue_title: "refactor(pi-subagents): decompose ResolvedSpawnConfig (15 fields)"
+---
+
+# Decompose ResolvedSpawnConfig into domain-aligned sub-interfaces
+
+## Problem Statement
+
+`ResolvedSpawnConfig` in `tools/spawn-config.ts` has 15 fields mixing identity, execution, and presentation concerns.
+Each consumer uses a different subset but receives the full bag — violating ISP and making the real dependencies of `foreground-runner` and `background-spawner` invisible.
+
+## Goals
+
+- Split `ResolvedSpawnConfig` into three focused interfaces: `SpawnIdentity`, `SpawnExecution`, `SpawnPresentation`.
+- Each consumer declares its real dependencies explicitly.
+- Preserve existing behavior — pure structural refactor with no behavioral changes.
+
+## Non-Goals
+
+- Extracting `ParentSessionInfo` from `AgentSpawnConfig` — that's #166.
+- Changing how `resolveSpawnConfig` computes values internally.
+- Modifying the `AgentSpawnConfig` interface passed to `AgentManager`.
+
+## Background
+
+`resolveSpawnConfig` is called by `agent-tool.ts` and produces a single flat config object.
+Three consumers read from it:
+
+1. `agent-tool.ts` — reads `inheritContext` (to build snapshot), `runInBackground` (to branch), and `detailBase` (for resume result).
+2. `foreground-runner.ts` — reads identity fields for fallback messages, execution fields for spawn options, and `detailBase` for result formatting.
+3. `background-spawner.ts` — reads identity fields for launch message, execution fields for spawn options, and `detailBase` for result formatting.
+
+Two fields (`modelName`, `agentTags`) are never accessed by any external consumer — they're intermediate values used only inside `resolveSpawnConfig` to build `detailBase`.
+They belong on `SpawnPresentation` for transparency but could also be made internal-only.
+
+The `code-design` skill's ISP and dependency-width guidance both apply: clients should not depend on properties they don't use, and a shared bag where each consumer only touches a subset hides real dependencies.
+
+## Design Overview
+
+### New interfaces
+
+```typescript
+/** Identity: who is being spawned. */
+export interface SpawnIdentity {
+  subagentType: string;
+  rawType: SubagentType;
+  fellBack: boolean;
+  displayName: string;
+}
+
+/** Execution: how the agent will run. */
+export interface SpawnExecution {
+  prompt: string;
+  description: string;
+  model: Model<any> | undefined;
+  effectiveMaxTurns: number | undefined;
+  thinking: ThinkingLevel | undefined;
+  inheritContext: boolean;
+  runInBackground: boolean;
+  isolated: boolean;
+  isolation: IsolationMode | undefined;
+  agentInvocation: AgentInvocation;
+}
+
+/** Presentation: display/UI values derived from identity + execution. */
+export interface SpawnPresentation {
+  modelName: string | undefined;
+  agentTags: string[];
+  detailBase: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">;
+}
+
+/** Fully resolved config — now a composition of domain-aligned sub-interfaces. */
+export interface ResolvedSpawnConfig {
+  identity: SpawnIdentity;
+  execution: SpawnExecution;
+  presentation: SpawnPresentation;
+}
+```
+
+### Consumer interaction pattern
+
+```typescript
+// agent-tool.ts — uses execution for routing, presentation for resume
+const config = resolveSpawnConfig(params, registry, modelInfo, settings);
+if ("error" in config) return textResult(config.error);
+const snapshot = buildSnapshot(config.execution.inheritContext);
+if (config.execution.runInBackground) { /* ... */ }
+return buildDetails(config.presentation.detailBase, record);
+
+// foreground-runner.ts — destructures what it needs
+const { identity, execution, presentation } = params.config;
+record = await manager.spawnAndWait(snapshot, identity.subagentType, execution.prompt, { ... });
+const fallbackNote = identity.fellBack ? `Note: Unknown agent type "${identity.rawType}"...` : "";
+```
+
+This follows Tell-Don't-Ask — callers pick the sub-object relevant to their concern rather than reaching through a flat bag.
+The one-level nesting (`config.execution.inheritContext`) is acceptable because it names the domain the field belongs to.
+
+### Test factory migration
+
+Both test files (`foreground-runner.test.ts`, `background-spawner.test.ts`) have `makeConfig()` factories that construct the full 15-field flat object.
+These will be updated to construct the nested structure.
+The `spawn-config.test.ts` assertions will shift from `result.subagentType` to `result.identity.subagentType` etc.
+
+## Module-Level Changes
+
+| File                                    | Change                                                                                                                                                                          |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/tools/spawn-config.ts`             | Add `SpawnIdentity`, `SpawnExecution`, `SpawnPresentation` interfaces. Change `ResolvedSpawnConfig` to nest them. Update `resolveSpawnConfig` return to build nested structure. |
+| `src/tools/agent-tool.ts`               | Update config access: `config.execution.inheritContext`, `config.execution.runInBackground`, `config.presentation.detailBase`.                                                  |
+| `src/tools/foreground-runner.ts`        | Destructure `config` into `identity`, `execution`, `presentation`. Update all field accesses.                                                                                   |
+| `src/tools/background-spawner.ts`       | Destructure `config` into `identity`, `execution`, `presentation`. Update all field accesses.                                                                                   |
+| `test/tools/spawn-config.test.ts`       | Update all assertions to use nested paths (`result.identity.subagentType`, etc.).                                                                                               |
+| `test/tools/foreground-runner.test.ts`  | Update `makeConfig()` factory to build nested structure.                                                                                                                        |
+| `test/tools/background-spawner.test.ts` | Update `makeConfig()` factory to build nested structure.                                                                                                                        |
+
+## Test Impact Analysis
+
+1. No new unit tests are needed — this is a structural refactor, not new behavior.
+2. No existing tests become redundant — all current `spawn-config.test.ts` assertions still verify the same computation.
+3. All existing tests must be updated to match the new nested access paths, but they continue to exercise the same logic.
+
+## TDD Order
+
+1. **Red→Green: introduce sub-interfaces and nest `ResolvedSpawnConfig`** — change `spawn-config.ts` to export the three sub-interfaces and restructure `ResolvedSpawnConfig`.
+   Update `resolveSpawnConfig` to return the nested shape.
+   Update `spawn-config.test.ts` assertions to match.
+   Commit: `refactor(pi-subagents): introduce SpawnIdentity, SpawnExecution, SpawnPresentation`
+
+2. **Green: update `agent-tool.ts`** — migrate the three field accesses (`inheritContext`, `runInBackground`, `detailBase`) to nested paths.
+   Run `pnpm run check` to confirm types pass.
+   Commit: `refactor(pi-subagents): update agent-tool to use nested spawn config`
+
+3. **Green: update `foreground-runner.ts` and its test** — destructure config and update all field accesses.
+   Update `makeConfig()` factory in `foreground-runner.test.ts`.
+   Commit: `refactor(pi-subagents): update foreground-runner to use nested spawn config`
+
+4. **Green: update `background-spawner.ts` and its test** — destructure config and update all field accesses.
+   Update `makeConfig()` factory in `background-spawner.test.ts`.
+   Commit: `refactor(pi-subagents): update background-spawner to use nested spawn config`
+
+5. **Verify: full suite** — run `pnpm vitest run` and `pnpm run check` to confirm no regressions.
+   Commit (if any lint/type cleanup needed): `chore(pi-subagents): post-decomposition cleanup`
+
+## Risks and Mitigations
+
+| Risk                                                           | Mitigation                                                                                                                                                   |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Step 1 breaks type checking for all consumers simultaneously   | Steps 2–4 must land in the same branch before pushing; or use a transitional type alias that spreads the sub-interfaces flat, removing it in the final step. |
+| Test factories diverge from production shape                   | Each step updates the test factory in the same commit as the source change.                                                                                  |
+| `modelName` and `agentTags` on `SpawnPresentation` look unused | They are unused by external consumers today but provide inspection affordance for debugging/logging. Keep them; #166 or later work may consume them.         |
+
+## Open Questions
+
+- None — the issue's proposed shape aligns with actual field usage patterns.
+  The only observation is that `modelName` and `agentTags` are only consumed internally, but exposing them on `SpawnPresentation` is harmless and aids debuggability.

package/docs/retro/0165-decompose-resolved-spawn-config.md

@@ -0,0 +1,40 @@
+---
+issue: 165
+issue_title: "refactor(pi-subagents): decompose ResolvedSpawnConfig (15 fields)"
+---
+
+# Retro: #165 — decompose ResolvedSpawnConfig (15 fields)
+
+## Stage: Planning (2026-05-24T13:41:41Z)
+
+### Session summary
+
+Produced a 5-step TDD plan to decompose the 15-field `ResolvedSpawnConfig` into three nested sub-interfaces (`SpawnIdentity`, `SpawnExecution`, `SpawnPresentation`).
+Also improved skill descriptions for `colgrep` and `markdown-conventions` to signal decision-relevant content rather than tool reference material.
+
+### Observations
+
+- The proposed decomposition in the issue aligns well with actual field usage patterns — no adjustments needed.
+- `modelName` and `agentTags` are never accessed by external consumers; they're intermediate computation exposed on the return type.
+  Keeping them on `SpawnPresentation` is harmless and aids debuggability.
+- Step 1 (interface change + return restructure) will break type checking for all consumers simultaneously.
+  The plan addresses this by landing steps 1–4 in rapid succession on the same branch.
+- Both test files have `makeConfig()` factories that must be updated in lock-step with their respective source files.
+- Issue #164 (directory reorganization) is closed, so import paths are already in their final `#src/<domain>/` form.
+
+## Stage: Implementation — TDD (2026-05-24T14:32:58Z)
+
+### Session summary
+
+Completed all 4 TDD cycles plus full-suite verification in one session.
+The decomposition touched 7 files (4 source, 3 test) and kept the test count flat at 805 — no new tests needed for a pure structural refactor.
+
+### Observations
+
+- The `Partial<ResolvedSpawnConfig>` spread pattern in `makeConfig` factories doesn't deep-merge into nested sub-objects.
+  Two tests (`foreground-runner.test.ts` and `background-spawner.test.ts`) used flat field overrides (`{ fellBack: true }`, `{ description: "my task" }`) that silently stopped working after nesting.
+  Fixed by writing out the full nested sub-object at the override call site.
+  Future factories for nested config types should either deep-merge or avoid the `Partial<T>` spread pattern — see the `testing` skill's warning about this.
+- Step 1 breaking all consumers simultaneously was handled smoothly by completing all steps before pushing, as planned.
+  No transitional alias was needed.
+- The `background-spawner.test.ts` description-override test was the only unexpected friction point — the flat spread issue wasn't caught by the plan.

package/package.json

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

package/src/tools/agent-tool.ts

@@ -301,7 +301,7 @@ Guidelines:
       if ("error" in config) return textResult(config.error);
 
       // ---- Boundary extraction (after config so inheritContext is resolved) ----
-      const snapshot = buildSnapshot(config.inheritContext);
+      const snapshot = buildSnapshot(config.execution.inheritContext);
       const { parentSessionFile, parentSessionId } = getSessionInfo();
 
       // ---- Resume existing agent ----
@@ -327,12 +327,12 @@ Guidelines:
         }
         return textResult(
           record.result?.trim() ?? record.error?.trim() ?? "No output.",
-          buildDetails(config.detailBase, record),
+          buildDetails(config.presentation.detailBase, record),
         );
       }
 
       // ---- Background execution ----
-      if (config.runInBackground) {
+      if (config.execution.runInBackground) {
         return spawnBackground(
           manager,
           widget,

package/src/tools/background-spawner.ts

@@ -40,23 +40,23 @@ export function spawnBackground(
   agentActivity: AgentActivityAccess,
   params: BackgroundParams,
 ) {
-  const { config } = params;
-  const bgState = new AgentActivityTracker(config.effectiveMaxTurns);
+  const { identity, execution, presentation } = params.config;
+  const bgState = new AgentActivityTracker(execution.effectiveMaxTurns);
 
   let id: string;
   try {
-    id = manager.spawn(params.snapshot, config.subagentType, config.prompt, {
+    id = manager.spawn(params.snapshot, identity.subagentType, execution.prompt, {
       parentSessionFile: params.parentSessionFile,
       parentSessionId: params.parentSessionId,
-      description: config.description,
-      model: config.model,
-      maxTurns: config.effectiveMaxTurns,
-      isolated: config.isolated,
-      inheritContext: config.inheritContext,
-      thinkingLevel: config.thinking,
+      description: execution.description,
+      model: execution.model,
+      maxTurns: execution.effectiveMaxTurns,
+      isolated: execution.isolated,
+      inheritContext: execution.inheritContext,
+      thinkingLevel: execution.thinking,
       isBackground: true,
-      isolation: config.isolation,
-      invocation: config.agentInvocation,
+      isolation: execution.isolation,
+      invocation: execution.agentInvocation,
       toolCallId: params.toolCallId,
       onSessionCreated: (session) => {
         bgState.setSession(session);
@@ -77,8 +77,8 @@ export function spawnBackground(
   return textResult(
     `Agent ${isQueued ? "queued" : "started"} in background.\n` +
       `Agent ID: ${id}\n` +
-      `Type: ${config.displayName}\n` +
-      `Description: ${config.description}\n` +
+      `Type: ${identity.displayName}\n` +
+      `Description: ${execution.description}\n` +
       (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
       (isQueued
         ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n`
@@ -87,7 +87,7 @@ export function spawnBackground(
       `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +
       `Do not duplicate this agent's work.`,
     {
-      ...config.detailBase,
+      ...presentation.detailBase,
       toolUses: 0,
       tokens: "",
       durationMs: 0,

package/src/tools/foreground-runner.ts

@@ -56,19 +56,19 @@ export async function runForeground(
   signal: AbortSignal | undefined,
   onUpdate: ((update: AgentToolResult<any>) => void) | undefined,
 ) {
-  const { config } = params;
+  const { identity, execution, presentation } = params.config;
   let spinnerFrame = 0;
   const startedAt = Date.now();
   let fgId: string | undefined;
 
-  const fgState = new AgentActivityTracker(config.effectiveMaxTurns);
+  const fgState = new AgentActivityTracker(execution.effectiveMaxTurns);
   let unsubUI: (() => void) | undefined;
   let recordRef: AgentRecord | undefined;
 
   const streamUpdate = () => {
     const toolUses = recordRef?.toolUses ?? 0;
     const details: AgentDetails = {
-      ...config.detailBase,
+      ...presentation.detailBase,
       toolUses,
       tokens: recordRef ? formatLifetimeTokens(recordRef) : "",
       turnCount: fgState.turnCount,
@@ -97,17 +97,17 @@ export async function runForeground(
   try {
     record = await manager.spawnAndWait(
       params.snapshot,
-      config.subagentType,
-      config.prompt,
+      identity.subagentType,
+      execution.prompt,
       {
-        description: config.description,
-        model: config.model,
-        maxTurns: config.effectiveMaxTurns,
-        isolated: config.isolated,
-        inheritContext: config.inheritContext,
-        thinkingLevel: config.thinking,
-        isolation: config.isolation,
-        invocation: config.agentInvocation,
+        description: execution.description,
+        model: execution.model,
+        maxTurns: execution.effectiveMaxTurns,
+        isolated: execution.isolated,
+        inheritContext: execution.inheritContext,
+        thinkingLevel: execution.thinking,
+        isolation: execution.isolation,
+        invocation: execution.agentInvocation,
         signal,
         parentSessionFile: params.parentSessionFile,
         parentSessionId: params.parentSessionId,
@@ -137,10 +137,10 @@ export async function runForeground(
   }
 
   const tokenText = formatLifetimeTokens(record);
-  const details = buildDetails(config.detailBase, record, fgState, { tokens: tokenText });
+  const details = buildDetails(presentation.detailBase, record, fgState, { tokens: tokenText });
 
-  const fallbackNote = config.fellBack
-    ? `Note: Unknown agent type "${config.rawType}" — using general-purpose.\n\n`
+  const fallbackNote = identity.fellBack
+    ? `Note: Unknown agent type "${identity.rawType}" — using general-purpose.\n\n`
     : "";
 
   if (record.status === "error") {

package/src/tools/spawn-config.ts

@@ -26,12 +26,16 @@ export interface ModelInfo {
   modelRegistry: unknown;
 }
 
-/** Fully resolved config for spawning an agent. */
-export interface ResolvedSpawnConfig {
+/** Identity: who is being spawned. */
+export interface SpawnIdentity {
   subagentType: string;
   rawType: SubagentType;
   fellBack: boolean;
   displayName: string;
+}
+
+/** Execution: how the agent will run. */
+export interface SpawnExecution {
   prompt: string;
   description: string;
   model: Model<any> | undefined;
@@ -41,12 +45,23 @@ export interface ResolvedSpawnConfig {
   runInBackground: boolean;
   isolated: boolean;
   isolation: IsolationMode | undefined;
-  modelName: string | undefined;
   agentInvocation: AgentInvocation;
+}
+
+/** Presentation: display/UI values derived from identity and execution. */
+export interface SpawnPresentation {
+  modelName: string | undefined;
   agentTags: string[];
   detailBase: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">;
 }
 
+/** Fully resolved config for spawning an agent — composed of domain-aligned sub-interfaces. */
+export interface ResolvedSpawnConfig {
+  identity: SpawnIdentity;
+  execution: SpawnExecution;
+  presentation: SpawnPresentation;
+}
+
 /** Error result when model resolution fails. */
 export interface SpawnConfigError {
   error: string;
@@ -126,22 +141,19 @@ export function resolveSpawnConfig(
   };
 
   return {
-    subagentType,
-    rawType,
-    fellBack,
-    displayName,
-    prompt: params.prompt as string,
-    description: params.description as string,
-    model,
-    effectiveMaxTurns,
-    thinking,
-    inheritContext,
-    runInBackground,
-    isolated,
-    isolation,
-    modelName,
-    agentInvocation,
-    agentTags,
-    detailBase,
+    identity: { subagentType, rawType, fellBack, displayName },
+    execution: {
+      prompt: params.prompt as string,
+      description: params.description as string,
+      model,
+      effectiveMaxTurns,
+      thinking,
+      inheritContext,
+      runInBackground,
+      isolated,
+      isolation,
+      agentInvocation,
+    },
+    presentation: { modelName, agentTags, detailBase },
   };
 }