@gotgenes/pi-subagents 6.0.1 → 6.2.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.1.0...pi-subagents-v6.2.0) (2026-05-21)
+
+
+### Features
+
+* add ParentSnapshot type and builder ([#99](https://github.com/gotgenes/pi-packages/issues/99)) ([ee24eb9](https://github.com/gotgenes/pi-packages/commit/ee24eb907eba9f6f917bc166c912e5482eff5bd5))
+
+
+### Documentation
+
+* **pi-subagents:** cross-reference issues in architecture decomposition plan ([2242e45](https://github.com/gotgenes/pi-packages/commit/2242e457b7e1bf8cb44e9a1df6fb4d2fd1ba1116))
+* plan replace live ctx capture with ParentSnapshot ([#99](https://github.com/gotgenes/pi-packages/issues/99)) ([b6b63f8](https://github.com/gotgenes/pi-packages/commit/b6b63f8677231617a00cb1e3d1227667cbae7ecd))
+* **retro:** add retro notes for issue [#98](https://github.com/gotgenes/pi-packages/issues/98) ([ef52aaa](https://github.com/gotgenes/pi-packages/commit/ef52aaa4d8b690b309f2129ff34f90c44368cc57))
+
+## [6.1.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.0.1...pi-subagents-v6.1.0) (2026-05-20)
+
+
+### Features
+
+* create AgentRecord class with transition methods ([#98](https://github.com/gotgenes/pi-packages/issues/98)) ([e5b2170](https://github.com/gotgenes/pi-packages/commit/e5b21704de2d693e4feff8b0c0f80a4f6e3fdabd))
+
+
+### Documentation
+
+* plan AgentRecord state machine extraction ([#98](https://github.com/gotgenes/pi-packages/issues/98)) ([5ca6613](https://github.com/gotgenes/pi-packages/commit/5ca6613ba8e73e042c7f06e2f303ad573048138e))
+* **retro:** add retro notes for issue [#102](https://github.com/gotgenes/pi-packages/issues/102) ([594a61a](https://github.com/gotgenes/pi-packages/commit/594a61a59f04aafba06ab8649c183b5003e95822))
+
 ## [6.0.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.0.0...pi-subagents-v6.0.1) (2026-05-20)
 
 

package/docs/architecture/architecture.md

@@ -489,7 +489,7 @@ The `if (record.status !== "stopped")` guards in `.then()` and `.catch()` become
 The three designs are independent and can land in any order.
 The recommended sequence minimizes intermediate churn.
 
-#### Step 1: Record state machine
+#### Step 1: Record state machine ✓ (done — #98, #102)
 
 Extract status-transition methods onto `AgentRecord` (or a `RecordManager` wrapper).
 Purely mechanical — replace scattered field writes with method calls.
@@ -497,7 +497,9 @@ No interface changes for callers.
 
 This is the lowest-risk change and immediately reduces `startAgent()` line count.
 
-#### Step 2: Parent snapshot
+Issue #102 consolidated test `AgentRecord` construction into a shared factory as follow-up.
+
+#### Step 2: Parent snapshot (#99)
 
 Replace `ctx: ExtensionContext` in `SpawnArgs` with a `ParentSnapshot` data object.
 Capture the snapshot in `spawn()` or at the tool call site.
@@ -506,7 +508,7 @@ Remove `pi: ExtensionAPI` from `SpawnArgs` (it is only used to pass to `runner.r
 
 This change narrows the `AgentRunner` interface and eliminates live-reference capture.
 
-#### Step 3: Session-event observation
+#### Step 3: Session-event observation (#100)
 
 Replace the callback-threading pattern with direct session subscriptions.
 AgentManager subscribes to the session after creation to update the record.

package/docs/plans/0098-extract-agent-record-state-machine.md

@@ -0,0 +1,435 @@
+---
+issue: 98
+issue_title: "Extract AgentRecord state machine from scattered status transitions"
+---
+
+# Extract AgentRecord state machine
+
+## Problem Statement
+
+`AgentRecord` status transitions are scattered across 6 locations in `agent-manager.ts`: `startAgent()` `.then()`, `startAgent()` `.catch()`, `resume()`, `abort()`, `abortAll()`, and `drainQueue()` catch.
+Each site sets `record.status` plus associated fields (`completedAt`, `result`, `error`) in ad-hoc combinations, with repeated guards like `if (record.status !== "stopped")`.
+
+There are 15 direct `record.status = ...` writes and 17 associated field writes (`result`, `error`, `completedAt`, `startedAt`) — ~32 scattered mutation sites total.
+`startAgent()` is ~130 lines partly because it manages these transitions inline.
+
+## Goals
+
+- Convert `AgentRecord` from a plain interface to a class that owns and encapsulates its transition state.
+- Extract status-transition methods that centralize the "don't overwrite stopped" guard.
+- Reduce scattered field writes in `agent-manager.ts` to method calls.
+- Encapsulate transition fields (`status`, `result`, `error`, `startedAt`, `completedAt`) behind private backing fields with getters — external code can read but not write.
+- Use lift-and-shift to migrate incrementally: introduce the class alongside the interface, migrate construction sites, switch the re-export, replace writes, then encapsulate.
+
+## Non-Goals
+
+- Parent snapshot extraction (architecture.md Step 2) — separate issue.
+- Session-event observation / callback threading removal (architecture.md Step 3) — separate issue.
+- Stat accumulation methods (`toolUses++`, `addUsage()`, `compactionCount++`) — these are running counters, not status transitions.
+  They could become methods in a follow-up but are out of scope here.
+- Encapsulating non-transition field writes (`session`, `outputFile`, `worktree`, `worktreeResult`, `promise`, `toolCallId`, `resultConsumed`, `pendingSteers`) — these are data capture, not status transitions.
+
+## Prerequisites
+
+- Issue #102 (shared test record factory) — shipped.
+  All 8 test files construct `AgentRecord` objects through `createTestRecord()` in `test/helpers/make-record.ts`.
+  Converting the interface to a class requires updating only this one factory (plus `agent-manager.ts` construction).
+
+## Background
+
+### Relevant modules
+
+| Module                        | Role                                                                           |
+| ----------------------------- | ------------------------------------------------------------------------------ |
+| `src/types.ts`                | Defines `AgentRecord` interface — 20+ consumers read from it                   |
+| `src/agent-manager.ts`        | Only file that writes status-transition fields                                 |
+| `src/service.ts`              | Defines `SubagentRecord` (serializable snapshot) — unchanged                   |
+| `src/service-adapter.ts`      | Converts `AgentRecord` → `SubagentRecord` via `toSubagentRecord()` — unchanged |
+| `test/helpers/make-record.ts` | Shared test factory — single construction site for all tests (#102)            |
+
+### External writes to `AgentRecord` (not status transitions)
+
+Several files outside `agent-manager.ts` write non-transition fields:
+
+- `tools/get-result-tool.ts` — `record.resultConsumed = true` (2 sites)
+- `tools/steer-tool.ts` / `service-adapter.ts` — `record.pendingSteers` (push messages)
+- `tools/agent-tool.ts` — `record.toolCallId = toolCallId`
+
+These are data-capture writes, not status transitions, and remain public fields.
+
+### Code-style constraints
+
+The code-style skill's "output arguments" rule applies directly: "If a function sets a field on a received object, it is doing work that belongs inside the owning object.
+Encapsulate the mutation behind a method."
+The "scattered resets" rule also applies: "When the same set of fields is reset to the same values in multiple places, extract a single method."
+
+## Design Overview
+
+### `AgentRecord` becomes a class
+
+`AgentRecord` moves from an interface in `types.ts` to a class in a new `src/agent-record.ts` module.
+`types.ts` re-exports the class so existing `import type { AgentRecord } from "./types.js"` across the codebase continues to work with no import-path changes.
+
+The class encapsulates the 5 transition fields behind private backing fields with getters.
+All other fields remain public (identity fields are `readonly`; non-transition mutable fields stay public).
+
+```typescript
+export type AgentRecordStatus =
+  | "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+
+export class AgentRecord {
+  // Identity — readonly, set once at construction
+  readonly id: string;
+  readonly type: SubagentType;
+  readonly description: string;
+  readonly invocation?: AgentInvocation;
+
+  // Transition state — private backing fields, public getters
+  private _status: AgentRecordStatus;
+  get status(): AgentRecordStatus { return this._status; }
+
+  private _result?: string;
+  get result(): string | undefined { return this._result; }
+
+  private _error?: string;
+  get error(): string | undefined { return this._error; }
+
+  private _startedAt: number;
+  get startedAt(): number { return this._startedAt; }
+
+  private _completedAt?: number;
+  get completedAt(): number | undefined { return this._completedAt; }
+
+  // Non-transition mutable state — public fields
+  toolUses: number;
+  lifetimeUsage: LifetimeUsage;
+  compactionCount: number;
+  session?: AgentSession;
+  abortController?: AbortController;
+  promise?: Promise<string>;
+  resultConsumed?: boolean;
+  pendingSteers?: string[];
+  worktree?: { path: string; branch: string };
+  worktreeResult?: { hasChanges: boolean; branch?: string };
+  toolCallId?: string;
+  outputFile?: string;
+
+  constructor(init: AgentRecordInit) { /* ... */ }
+
+  // Transition methods — see below
+}
+```
+
+### Constructor and `AgentRecordInit`
+
+The constructor accepts a wide init bag that covers all fields.
+Required fields: `id`, `type`, `description`.
+All others are optional with sensible defaults (`status` defaults to `"queued"`, `toolUses` to 0, etc.).
+
+This wide init bag serves two purposes:
+
+1. Production use (`agent-manager.ts`): passes the 7 fields it needs at spawn time.
+2. Test use (`createTestRecord`): sets arbitrary state (e.g., `status: "completed"`, `result: "done"`) without going through transition methods.
+
+```typescript
+export interface AgentRecordInit {
+  id: string;
+  type: SubagentType;
+  description: string;
+  status?: AgentRecordStatus;
+  startedAt?: number;
+  completedAt?: number;
+  result?: string;
+  error?: string;
+  toolUses?: number;
+  lifetimeUsage?: LifetimeUsage;
+  compactionCount?: number;
+  abortController?: AbortController;
+  invocation?: AgentInvocation;
+  session?: AgentSession;
+  promise?: Promise<string>;
+  resultConsumed?: boolean;
+  pendingSteers?: string[];
+  worktree?: { path: string; branch: string };
+  worktreeResult?: { hasChanges: boolean; branch?: string };
+  toolCallId?: string;
+  outputFile?: string;
+}
+```
+
+### Transition methods
+
+7 methods covering all 6 transition sites plus the resume-reset:
+
+#### `markRunning(startedAt: number): void`
+
+Sets `status = "running"` and `startedAt`.
+Called in `startAgent()` when transitioning from queued to running.
+
+#### `markCompleted(result: string, completedAt?: number): void`
+
+Always sets `result` and `completedAt` (via `??=`).
+Only changes `status` to `"completed"` if not already `"stopped"`.
+Called in the `.then()` success path and in `resume()` try block.
+
+#### `markAborted(result: string, completedAt?: number): void`
+
+Same guard as `markCompleted` — preserves stopped status.
+Sets `status = "aborted"`.
+Called in `.then()` when runner returns `aborted: true`.
+
+#### `markSteered(result: string, completedAt?: number): void`
+
+Same guard as `markCompleted` — preserves stopped status.
+Sets `status = "steered"`.
+Called in `.then()` when runner returns `steered: true`.
+
+#### `markError(error: unknown, completedAt?: number): void`
+
+Always sets `error` (formatted: `Error` → `.message`, otherwise `String(...)`) and `completedAt` (via `??=`).
+Only changes `status` to `"error"` if not already `"stopped"`.
+Called in `.catch()`, `resume()` catch block, and `drainQueue()` catch.
+
+#### `markStopped(completedAt?: number): void`
+
+Always sets `status = "stopped"` and `completedAt`.
+No guard — stopping is always valid.
+Called in `abort()` (2 sites) and `abortAll()` (2 sites).
+
+#### `resetForResume(startedAt: number): void`
+
+Sets `status = "running"`, `startedAt`.
+Clears `completedAt`, `result`, `error` to `undefined`.
+Called in `resume()` before re-running.
+
+### Guard semantics: preserve current behavior
+
+The current `.then()` and `.catch()` blocks guard only the `status` field but always set `result`/`error` and `completedAt`:
+
+```typescript
+// Current .then() — result and completedAt are set even when stopped
+if (record.status !== "stopped") {
+  record.status = aborted ? "aborted" : steered ? "steered" : "completed";
+}
+record.result = responseText;
+record.completedAt ??= Date.now();
+```
+
+This is intentional — `get-result-tool.ts` reads `record.result` from stopped records.
+The transition methods preserve this behavior: data fields are always set, status is only changed when not stopped.
+The `??=` on `completedAt` preserves the abort timestamp when `markStopped()` fires before `.then()`.
+
+### Worktree result-append: reorder, don't add a method
+
+The `.then()` block currently appends worktree branch text to `record.result` after the transition.
+With encapsulated fields, direct writes to `result` are forbidden.
+
+Instead of adding an `appendToResult()` method, reorder the `.then()` block to compute the final result (including worktree text) before calling the transition method:
+
+```typescript
+.then(({ responseText, session, aborted, steered, sessionFile }) => {
+  // Worktree cleanup first — compute final result
+  let finalResult = responseText;
+  if (record.worktree) {
+    const wtResult = this.worktrees.cleanup(record.worktree, options.description);
+    record.worktreeResult = wtResult;
+    if (wtResult.hasChanges && wtResult.branch) {
+      finalResult += `\n\n---\nChanges saved to branch ...`;
+    }
+  }
+
+  // Transition with complete result
+  if (aborted) record.markAborted(finalResult);
+  else if (steered) record.markSteered(finalResult);
+  else record.markCompleted(finalResult);
+
+  record.session = session;
+  if (sessionFile) record.outputFile = sessionFile;
+
+  detach();
+  // ...
+})
+```
+
+The worktree cleanup reads `record.worktree` (a public field set before the promise) and writes `record.worktreeResult` (a public field).
+It does not depend on `record.status` or `record.result`, so the reorder is safe.
+
+### Correctness improvement in `resume()`
+
+The current `resume()` method lacks the "don't overwrite stopped" guard:
+
+```typescript
+// Current — no guard against abort race
+record.status = "completed";
+record.result = responseText;
+record.completedAt = Date.now();
+```
+
+After migration, `record.markCompleted(responseText)` includes the guard.
+This closes a latent race where `abort()` sets status to `"stopped"` between `resetForResume()` and the runner returning.
+The current code would overwrite `"stopped"` back to `"completed"` — the method call does not.
+
+### Circular import avoidance
+
+`agent-record.ts` imports types from `types.ts` (`SubagentType`, `AgentInvocation`).
+`types.ts` re-exports the class from `agent-record.ts`.
+
+This is safe because `agent-record.ts` uses `import type` for its `types.ts` imports — these are erased at runtime, so no runtime circular dependency exists.
+
+## Module-Level Changes
+
+### New files
+
+1. `src/agent-record.ts` — `AgentRecord` class, `AgentRecordInit` interface, `AgentRecordStatus` type.
+2. `test/agent-record.test.ts` — unit tests for constructor and all 7 transition methods.
+
+### Changed files
+
+1. `src/types.ts` — remove `AgentRecord` interface; add re-export: `export { AgentRecord, type AgentRecordInit, type AgentRecordStatus } from "./agent-record.js"`.
+2. `src/agent-manager.ts` — import `AgentRecord` as a value from `./agent-record.js`; replace object literal construction with `new AgentRecord(...)`; replace ~32 scattered field writes with 11 transition method calls.
+3. `test/helpers/make-record.ts` — import `AgentRecord` from `../../src/agent-record.js`; construct with `new AgentRecord(...)` instead of plain object.
+
+### Unchanged files
+
+All other source and test files — they use `import type { AgentRecord } from "./types.js"` and only read fields.
+The re-export from `types.ts` means zero import-path changes.
+
+## Test Impact Analysis
+
+### New tests enabled by the extraction
+
+The state machine is currently untestable in isolation — transitions are buried inside `agent-manager.ts`.
+After extraction:
+
+- Guard logic tested directly (e.g., `markCompleted` on a stopped record preserves status but sets result).
+- Invalid transition sequences tested without mocking the runner.
+- Error formatting (`Error` vs string) tested in isolation.
+- `resetForResume` field clearing tested without the full resume flow.
+
+### Existing tests that stay as-is
+
+`agent-manager.test.ts` tests verify end-to-end behavior (spawn, complete, abort, resume, queue drain, worktree).
+They remain unchanged — they verify the wiring between `AgentManager` and the `AgentRecord` class.
+
+### No test files need updating (except the shared factory)
+
+Issue #102 consolidated all test record construction into `createTestRecord()`.
+Only that one factory changes.
+All 8 consumer test files are untouched.
+
+## TDD Order
+
+### Cycle 1: AgentRecord class tests
+
+Test surface: `test/agent-record.test.ts` (new file).
+
+Tests cover:
+
+- Constructor: defaults (`status` → `"queued"`, `toolUses` → 0, `lifetimeUsage` → zeros, `compactionCount` → 0), passthrough of init values (including optional transition fields like `result`, `completedAt`).
+- `markRunning`: sets status and startedAt.
+- `markCompleted`: sets status/result/completedAt when not stopped; preserves status but still sets result/completedAt when stopped; `completedAt` uses `??=` semantics (does not overwrite existing value).
+- `markAborted` and `markSteered`: same guard behavior as `markCompleted`.
+- `markError`: sets status/error/completedAt when not stopped; preserves status but still sets error/completedAt when stopped; formats `Error` objects to `.message`, non-Error to `String(...)`.
+- `markStopped`: always sets status and completedAt, no guard.
+- `resetForResume`: sets status to `"running"` and startedAt; clears completedAt, result, error.
+
+Commit: `test: add AgentRecord class tests (#98)`
+
+### Cycle 2: AgentRecord class implementation
+
+Source: `src/agent-record.ts` (new file).
+Exports: `AgentRecord` class, `AgentRecordInit` interface, `AgentRecordStatus` type.
+All fields public initially (encapsulation deferred to cycle 6).
+
+All cycle 1 tests pass.
+
+Commit: `feat: create AgentRecord class with transition methods (#98)`
+
+### Cycle 3: Lift — migrate construction sites
+
+Changed files: `test/helpers/make-record.ts`, `src/agent-manager.ts`.
+
+`createTestRecord`: import `AgentRecord` from `agent-record.ts`; construct with `new AgentRecord(...)`.
+`agent-manager.ts`: import `AgentRecord` from `agent-record.ts` (value import); replace object literal in `spawn()` with `new AgentRecord(...)`.
+
+At this point, both the interface (in `types.ts`) and the class (in `agent-record.ts`) coexist.
+`agent-manager.ts` uses the class; all other consumers use the interface.
+Scattered field writes still work because fields are public.
+
+Run: full test suite + `pnpm run check`.
+
+Commit: `refactor: construct AgentRecord class in agent-manager and test factory (#98)`
+
+### Cycle 4: Shift — switch `types.ts` from interface to re-export
+
+Changed file: `src/types.ts`.
+
+Remove the `AgentRecord` interface definition.
+Add re-exports:
+
+```typescript
+export { AgentRecord } from "./agent-record.js";
+export type { AgentRecordInit, AgentRecordStatus } from "./agent-record.js";
+```
+
+All `import type { AgentRecord } from "./types.js"` across the codebase now resolve to the class.
+No consumer constructs `AgentRecord` as a plain object (construction was migrated in cycle 3).
+
+Run: `pnpm run check` (catches any structural incompatibilities).
+
+Commit: `refactor: replace AgentRecord interface with class re-export in types.ts (#98)`
+
+### Cycle 5: Replace scattered field writes with transition methods
+
+Changed file: `src/agent-manager.ts`.
+
+Replace all 11 transition sites:
+
+| Location               | Before                                                             | After                                                               |
+| ---------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| `startAgent()` running | `record.status = "running"; record.startedAt = ...`                | `record.markRunning(Date.now())`                                    |
+| `.then()` success      | `if (!stopped) status = ...; result = ...; completedAt ??= ...`    | `record.markCompleted(finalResult)` / `markAborted` / `markSteered` |
+| `.catch()` error       | `if (!stopped) status = "error"; error = ...; completedAt ??= ...` | `record.markError(err)`                                             |
+| `resume()` reset       | `status = ...; startedAt = ...; clear 3 fields`                    | `record.resetForResume(Date.now())`                                 |
+| `resume()` try         | `status = "completed"; result = ...; completedAt = ...`            | `record.markCompleted(responseText)`                                |
+| `resume()` catch       | `status = "error"; error = ...; completedAt = ...`                 | `record.markError(err)`                                             |
+| `abort()` queued       | `status = "stopped"; completedAt = ...`                            | `record.markStopped()`                                              |
+| `abort()` running      | `status = "stopped"; completedAt = ...`                            | `record.markStopped()`                                              |
+| `abortAll()` queued    | `status = "stopped"; completedAt = ...`                            | `record.markStopped()`                                              |
+| `abortAll()` running   | `status = "stopped"; completedAt = ...`                            | `record.markStopped()`                                              |
+| `drainQueue()` catch   | `status = "error"; error = ...; completedAt = ...`                 | `record.markError(err)`                                             |
+
+Also reorder the `.then()` block: worktree cleanup moves before the transition call so the final result includes worktree branch text (see Design Overview).
+
+Run: full test suite.
+
+Commit: `refactor: replace scattered status transitions with AgentRecord methods (#98)`
+
+### Cycle 6: Encapsulate transition fields
+
+Changed file: `src/agent-record.ts`.
+
+Make `status`, `result`, `error`, `startedAt`, `completedAt` private (`_status`, `_result`, etc.) with public getters.
+Make `id`, `type`, `description`, `invocation` readonly.
+
+Run: `pnpm run check` — verifies no remaining direct writes to encapsulated fields anywhere in `src/` or `test/`.
+Run: full test suite.
+
+Commit: `refactor: encapsulate AgentRecord transition state (#98)`
+
+## Risks and Mitigations
+
+| Risk                                                                                                                   | Mitigation                                                                                                      |
+| ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Guard semantics drift: transition methods might not exactly match scattered guards                                     | Each method's guard logic has dedicated tests (cycle 1); full agent-manager test suite runs after each cycle    |
+| Data fields on stopped records: `markCompleted` etc. must still set `result`/`completedAt` even when status is guarded | Explicit "stopped guard" test cases verify data fields are set; mirrors current `.then()` / `.catch()` behavior |
+| Worktree result-append after encapsulation: direct `record.result = ...` no longer compiles                            | `.then()` block reordered to compute full result before calling transition method (cycle 5)                     |
+| `types.ts` re-export introduces type-only circular dependency                                                          | `agent-record.ts` → `types.ts` imports are `import type` only (erased at runtime); no runtime cycle             |
+| `resume()` gains a "stopped" guard it didn't have before                                                               | This is a correctness improvement: closes a latent abort race; noted explicitly in design                       |
+
+## Open Questions
+
+- The `markCompleted`/`markAborted`/`markSteered` split is not in the original issue's 5-method list (which only shows `markCompleted`).
+  The split is needed because the `.then()` block dispatches to 3 distinct terminal statuses.
+- Stat accumulation (`toolUses++`, `addUsage(lifetimeUsage, ...)`, `compactionCount++`) is left as direct field writes on public fields.
+  These could become methods in a follow-up if the callback-threading removal (architecture.md Step 3) makes it natural.