@gotgenes/pi-subagents 6.0.0 → 6.1.0

package/docs/retro/0102-consolidate-test-record-factory.md

@@ -0,0 +1,30 @@
+---
+issue: 102
+issue_title: "Consolidate test AgentRecord construction into a shared factory"
+---
+
+# Retro: #102 — Consolidate test AgentRecord construction into a shared factory
+
+## Final Retrospective (2026-05-20T15:30:00Z)
+
+### Session summary
+
+Planned, implemented, and shipped a shared `createTestRecord()` factory in `test/helpers/make-record.ts`, migrating 7 test files from local factories and inline literals.
+The session completed in three slash-command phases (plan → TDD → ship) with zero rework, zero test failures, and zero deviations from the plan.
+Released as `pi-subagents-v6.0.1`.
+
+### Observations
+
+#### What went well
+
+- The Explore subagent surveyed all 8 test files' factory patterns in parallel, producing a structured comparison table that directly informed the plan's default-value decisions.
+- Before migrating `service-adapter.test.ts`, reading the `toSubagentRecord` source confirmed that `!== undefined` guards make absent-property vs. property-set-to-undefined semantically equivalent — avoiding a subtle test failure.
+- All 4 TDD steps passed on first run, confirming the plan's migration strategy (preserve old defaults via overrides) was sound.
+
+#### What caused friction (agent side)
+
+No friction points — the mechanical nature of the refactoring and the well-specified plan eliminated ambiguity.
+
+#### What caused friction (user side)
+
+No friction points — the three-phase slash-command workflow required no manual intervention.

package/package.json

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

package/src/agent-manager.ts

@@ -9,10 +9,11 @@
 import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { AgentRecord } from "./agent-record.js";
 import type { AgentRunner, ToolActivity } from "./agent-runner.js";
 import { debugLog } from "./debug.js";
 import type { RunConfig } from "./runtime.js";
-import type { AgentInvocation, AgentRecord, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
+import type { AgentInvocation, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
 import { addUsage } from "./usage.js";
 import type { WorktreeManager } from "./worktree.js";
 
@@ -133,18 +134,15 @@ export class AgentManager {
   ): string {
     const id = randomUUID().slice(0, 17);
     const abortController = new AbortController();
-    const record: AgentRecord = {
+    const record = new AgentRecord({
       id,
       type,
       description: options.description,
       status: options.isBackground ? "queued" : "running",
-      toolUses: 0,
       startedAt: Date.now(),
       abortController,
-      lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
-      compactionCount: 0,
       invocation: options.invocation,
-    };
+    });
     this.agents.set(id, record);
 
     const args: SpawnArgs = { pi, ctx, type, prompt, options };
@@ -184,8 +182,7 @@ export class AgentManager {
       worktreeCwd = wt.path;
     }
 
-    record.status = "running";
-    record.startedAt = Date.now();
+    record.markRunning(Date.now());
     if (options.isBackground) this.runningBackground++;
     this.onStart?.(record);
 
@@ -244,27 +241,26 @@ export class AgentManager {
       },
     })
       .then(({ responseText, session, aborted, steered, sessionFile }) => {
-        // Don't overwrite status if externally stopped via abort()
-        if (record.status !== "stopped") {
-          record.status = aborted ? "aborted" : steered ? "steered" : "completed";
-        }
-        record.result = responseText;
-        record.session = session;
-        record.completedAt ??= Date.now();
-        if (sessionFile) record.outputFile = sessionFile;
-
         detach();
 
-        // Clean up worktree if used
+        // Clean up worktree before transition so the final result includes branch text
+        let finalResult = responseText;
         if (record.worktree) {
           const wtResult = this.worktrees.cleanup(record.worktree, options.description);
           record.worktreeResult = wtResult;
           if (wtResult.hasChanges && wtResult.branch) {
-            record.result = (record.result ?? "") +
-              `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
+            finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
           }
         }
 
+        // Transition — guards against overwriting externally-stopped status
+        if (aborted) record.markAborted(finalResult);
+        else if (steered) record.markSteered(finalResult);
+        else record.markCompleted(finalResult);
+
+        record.session = session;
+        if (sessionFile) record.outputFile = sessionFile;
+
         if (options.isBackground) {
           this.runningBackground--;
           try { this.onComplete?.(record); } catch (err) { debugLog("onComplete callback", err); }
@@ -273,17 +269,10 @@ export class AgentManager {
         return responseText;
       })
       .catch((err) => {
-        // Don't overwrite status if externally stopped via abort()
-        if (record.status !== "stopped") {
-          record.status = "error";
-        }
-        record.error = err instanceof Error ? err.message : String(err);
-        record.completedAt ??= Date.now();
+        record.markError(err);
 
         detach();
 
-
-
         // Best-effort worktree cleanup on error
         if (record.worktree) {
           try {
@@ -314,9 +303,7 @@ export class AgentManager {
       } catch (err) {
         // Late failure (e.g. strict worktree-isolation) — surface on the record
         // so the user/agent can see it via /agents, then keep draining.
-        record.status = "error";
-        record.error = err instanceof Error ? err.message : String(err);
-        record.completedAt = Date.now();
+        record.markError(err);
         this.onComplete?.(record);
       }
     }
@@ -350,11 +337,7 @@ export class AgentManager {
     const record = this.agents.get(id);
     if (!record?.session) return undefined;
 
-    record.status = "running";
-    record.startedAt = Date.now();
-    record.completedAt = undefined;
-    record.result = undefined;
-    record.error = undefined;
+    record.resetForResume(Date.now());
 
     try {
       const responseText = await this.runner.resume(record.session, prompt, {
@@ -370,13 +353,9 @@ export class AgentManager {
         },
         signal,
       });
-      record.status = "completed";
-      record.result = responseText;
-      record.completedAt = Date.now();
+      record.markCompleted(responseText);
     } catch (err) {
-      record.status = "error";
-      record.error = err instanceof Error ? err.message : String(err);
-      record.completedAt = Date.now();
+      record.markError(err);
     }
 
     return record;
@@ -399,15 +378,13 @@ export class AgentManager {
     // Remove from queue if queued
     if (record.status === "queued") {
       this.queue = this.queue.filter(q => q.id !== id);
-      record.status = "stopped";
-      record.completedAt = Date.now();
+      record.markStopped();
       return true;
     }
 
     if (record.status !== "running") return false;
     record.abortController?.abort();
-    record.status = "stopped";
-    record.completedAt = Date.now();
+    record.markStopped();
     return true;
   }
 
@@ -452,8 +429,7 @@ export class AgentManager {
     for (const queued of this.queue) {
       const record = this.agents.get(queued.id);
       if (record) {
-        record.status = "stopped";
-        record.completedAt = Date.now();
+        record.markStopped();
         count++;
       }
     }
@@ -462,8 +438,7 @@ export class AgentManager {
     for (const record of this.agents.values()) {
       if (record.status === "running") {
         record.abortController?.abort();
-        record.status = "stopped";
-        record.completedAt = Date.now();
+        record.markStopped();
         count++;
       }
     }

package/src/agent-record.ts

@@ -0,0 +1,179 @@
+/**
+ * agent-record.ts — AgentRecord class with encapsulated status-transition logic.
+ *
+ * Status transitions (status, result, error, startedAt, completedAt) are owned
+ * by the class and exposed via transition methods. External code reads these
+ * fields through public properties but cannot write them directly.
+ *
+ * Non-transition state (session, toolUses, lifetimeUsage, etc.) remains public.
+ */
+
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { AgentInvocation, SubagentType } from "./types.js";
+import type { LifetimeUsage } from "./usage.js";
+
+export type AgentRecordStatus =
+	| "queued"
+	| "running"
+	| "completed"
+	| "steered"
+	| "aborted"
+	| "stopped"
+	| "error";
+
+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;
+}
+
+export class AgentRecord {
+	// Identity — set once at construction
+	readonly id: string;
+	readonly type: SubagentType;
+	readonly description: string;
+	readonly invocation?: AgentInvocation;
+
+	// Transition state — encapsulated behind getters, mutated only via transition methods
+	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
+	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) {
+		this.id = init.id;
+		this.type = init.type;
+		this.description = init.description;
+		this.invocation = init.invocation;
+
+		this._status = init.status ?? "queued";
+		this._result = init.result;
+		this._error = init.error;
+		this._startedAt = init.startedAt ?? Date.now();
+		this._completedAt = init.completedAt;
+
+		this.toolUses = init.toolUses ?? 0;
+		this.lifetimeUsage = init.lifetimeUsage ?? { input: 0, output: 0, cacheWrite: 0 };
+		this.compactionCount = init.compactionCount ?? 0;
+		this.abortController = init.abortController;
+		this.session = init.session;
+		this.promise = init.promise;
+		this.resultConsumed = init.resultConsumed;
+		this.pendingSteers = init.pendingSteers;
+		this.worktree = init.worktree;
+		this.worktreeResult = init.worktreeResult;
+		this.toolCallId = init.toolCallId;
+		this.outputFile = init.outputFile;
+	}
+
+	/** Transition to running state. Sets status and startedAt. */
+	markRunning(startedAt: number): void {
+		this._status = "running";
+		this._startedAt = startedAt;
+	}
+
+	/**
+	 * Transition to completed state.
+	 * Always sets result and completedAt (??=). Only changes status if not stopped.
+	 */
+	markCompleted(result: string, completedAt?: number): void {
+		this._result = result;
+		this._completedAt ??= completedAt ?? Date.now();
+		if (this._status !== "stopped") {
+			this._status = "completed";
+		}
+	}
+
+	/**
+	 * Transition to aborted state.
+	 * Always sets result and completedAt (??=). Only changes status if not stopped.
+	 */
+	markAborted(result: string, completedAt?: number): void {
+		this._result = result;
+		this._completedAt ??= completedAt ?? Date.now();
+		if (this._status !== "stopped") {
+			this._status = "aborted";
+		}
+	}
+
+	/**
+	 * Transition to steered state.
+	 * Always sets result and completedAt (??=). Only changes status if not stopped.
+	 */
+	markSteered(result: string, completedAt?: number): void {
+		this._result = result;
+		this._completedAt ??= completedAt ?? Date.now();
+		if (this._status !== "stopped") {
+			this._status = "steered";
+		}
+	}
+
+	/**
+	 * Transition to error state.
+	 * Always sets error (formatted) and completedAt (??=). Only changes status if not stopped.
+	 */
+	markError(error: unknown, completedAt?: number): void {
+		this._error = error instanceof Error ? error.message : String(error);
+		this._completedAt ??= completedAt ?? Date.now();
+		if (this._status !== "stopped") {
+			this._status = "error";
+		}
+	}
+
+	/** Transition to stopped state. Always valid — no guard. */
+	markStopped(completedAt?: number): void {
+		this._status = "stopped";
+		this._completedAt = completedAt ?? Date.now();
+	}
+
+	/** Reset for resume: running status, new startedAt, clear completedAt/result/error. */
+	resetForResume(startedAt: number): void {
+		this._status = "running";
+		this._startedAt = startedAt;
+		this._completedAt = undefined;
+		this._result = undefined;
+		this._error = undefined;
+	}
+}

package/src/types.ts

@@ -3,9 +3,10 @@
  */
 
 import type { ThinkingLevel } from "@earendil-works/pi-ai";
-import type { AgentSession } from "@earendil-works/pi-coding-agent";
-import type { LifetimeUsage } from "./usage.js";
 
+export type { AgentRecordInit, AgentRecordStatus } from "./agent-record.js";
+
+export { AgentRecord } from "./agent-record.js";
 export type { ThinkingLevel };
 
 /** Agent type: any string name (built-in defaults or user-defined). */
@@ -55,43 +56,6 @@ export interface AgentConfig {
   source?: "default" | "project" | "global";
 }
 
-export interface AgentRecord {
-  id: string;
-  type: SubagentType;
-  description: string;
-  status: "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
-  result?: string;
-  error?: string;
-  toolUses: number;
-  startedAt: number;
-  completedAt?: number;
-  session?: AgentSession;
-  abortController?: AbortController;
-  promise?: Promise<string>;
-  /** Set when result was already consumed via get_subagent_result — suppresses completion notification. */
-  resultConsumed?: boolean;
-  /** Steering messages queued before the session was ready. */
-  pendingSteers?: string[];
-  /** Worktree info if the agent is running in an isolated worktree. */
-  worktree?: { path: string; branch: string };
-  /** Worktree cleanup result after agent completion. */
-  worktreeResult?: { hasChanges: boolean; branch?: string };
-  /** The tool_use_id from the original Agent tool call. */
-  toolCallId?: string;
-  /** Path to the persisted session transcript file. */
-  outputFile?: string;
-  /**
-   * Lifetime usage breakdown, accumulated via `message_end` events. Survives
-   * compaction. Total = input + output + cacheWrite (cacheRead deliberately
-   * excluded — see issue #38). Initialized to zeros at spawn.
-   */
-  lifetimeUsage: LifetimeUsage;
-  /** Number of times this agent's session has compacted. Initialized to 0 at spawn. */
-  compactionCount: number;
-  /** Resolved spawn params, captured for UI display. Fixed at spawn time. */
-  invocation?: AgentInvocation;
-}
-
 export interface AgentInvocation {
   /** Short display name, e.g. "haiku" — only set when different from parent. */
   modelName?: string;