@gotgenes/pi-subagents 13.2.0 → 13.2.2

package/src/lifecycle/workspace.ts

@@ -11,7 +11,7 @@
  * synchronously at run-start. The core has no knowledge of git or worktrees.
  */
 
-import type { AgentStatus } from "#src/lifecycle/agent";
+import type { SubagentStatus } from "#src/lifecycle/subagent";
 import type { AgentInvocation, SubagentType } from "#src/types";
 
 /** Context the core hands a provider when a child run starts. */
@@ -24,7 +24,7 @@ export interface WorkspacePrepareContext {
 
 /** Outcome the core reports to a workspace when the run ends. */
 export interface WorkspaceDisposeOutcome {
-  status: AgentStatus;
+  status: SubagentStatus;
   description: string;
 }
 

package/src/observation/notification.ts

@@ -1,6 +1,6 @@
 import { debugLog } from "#src/debug";
 import { getLifetimeTotal } from "#src/lifecycle/usage";
-import type { Agent } from "#src/types";
+import type { Subagent } from "#src/types";
 import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 
 /** Details attached to custom notification messages for visual rendering. */
@@ -42,7 +42,7 @@ export function getStatusLabel(status: string, error?: string): string {
 }
 
 /** Format a structured task notification matching Claude Code's <task-notification> XML. */
-export function formatTaskNotification(record: Agent, resultMaxLen: number): string {
+export function formatTaskNotification(record: Subagent, resultMaxLen: number): string {
   const status = getStatusLabel(record.status, record.error);
   const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
@@ -64,7 +64,7 @@ export function formatTaskNotification(record: Agent, resultMaxLen: number): str
     toolCallId ? `<tool-use-id>${escapeXml(toolCallId)}</tool-use-id>` : null,
     outputFile ? `<output-file>${escapeXml(outputFile)}</output-file>` : null,
     `<status>${escapeXml(status)}</status>`,
-    `<summary>Agent "${escapeXml(record.description)}" ${record.status}</summary>`,
+    `<summary>Subagent "${escapeXml(record.description)}" ${record.status}</summary>`,
     `<result>${escapeXml(resultPreview)}</result>`,
     `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses>${ctxXml}${compactXml}<duration_ms>${durationMs}</duration_ms></usage>`,
     "</task-notification>",
@@ -75,7 +75,7 @@ export function formatTaskNotification(record: Agent, resultMaxLen: number): str
 
 /** Build notification details for the custom message renderer. */
 export function buildNotificationDetails(
-  record: Agent,
+  record: Subagent,
   resultMaxLen: number,
   activity?: AgentActivityTracker,
 ): NotificationDetails {
@@ -100,8 +100,8 @@ export function buildNotificationDetails(
   };
 }
 
-/** Build event data for lifecycle events from an Agent. */
-export function buildEventData(record: Agent) {
+/** Build event data for lifecycle events from a Subagent. */
+export function buildEventData(record: Subagent) {
   const durationMs = record.completedAt ? record.completedAt - record.startedAt : Date.now() - record.startedAt;
   const u = record.lifetimeUsage;
   const total = getLifetimeTotal(u);
@@ -126,7 +126,7 @@ export function buildEventData(record: Agent) {
 
 export interface NotificationSystem {
   cancelNudge: (key: string) => void;
-  sendCompletion: (record: Agent) => void;
+  sendCompletion: (record: Subagent) => void;
   cleanupCompleted: (id: string) => void;
   dispose: () => void;
 }
@@ -154,7 +154,7 @@ export class NotificationManager implements NotificationSystem {
     }
   }
 
-  sendCompletion(record: Agent): void {
+  sendCompletion(record: Subagent): void {
     this.agentActivity.delete(record.id);
     this.markFinished(record.id);
     this.scheduleNudge(record.id, () => this.emitIndividualNudge(record));
@@ -187,7 +187,7 @@ export class NotificationManager implements NotificationSystem {
     );
   }
 
-  private emitIndividualNudge(record: Agent): void {
+  private emitIndividualNudge(record: Subagent): void {
     if (record.notification?.resultConsumed) return;
 
     const notification = formatTaskNotification(record, 500);

package/src/observation/record-observer.ts

@@ -1,19 +1,19 @@
 /**
- * record-observer.ts — Subscribes to session events and updates Agent stats.
+ * record-observer.ts — Subscribes to session events and updates Subagent stats.
  *
- * Replaces the scattered callback-wrapping logic in AgentManager's startAgent()
+ * Replaces the scattered callback-wrapping logic in SubagentManager's startAgent()
  * and resume() with a single direct subscription.
  */
 
-import type { Agent } from "#src/lifecycle/agent";
+import type { Subagent } from "#src/lifecycle/subagent";
 import type { CompactionInfo, SubscribableSession } from "#src/types";
 
-export interface AgentObserverOptions {
-  onCompact?: (record: Agent, info: CompactionInfo) => void;
+export interface SubagentObserverOptions {
+  onCompact?: (record: Subagent, info: CompactionInfo) => void;
 }
 
 /**
- * Subscribe to session events and accumulate stats on the agent record.
+ * Subscribe to session events and accumulate stats on the subagent record.
  *
  * Handles:
  * - `tool_execution_end` → `record.incrementToolUses()`
@@ -22,10 +22,10 @@ export interface AgentObserverOptions {
  *
  * @returns An unsubscribe function.
  */
-export function subscribeAgentObserver(
+export function subscribeSubagentObserver(
   session: SubscribableSession,
-  record: Agent,
-  options?: AgentObserverOptions,
+  record: Subagent,
+  options?: SubagentObserverOptions,
 ): () => void {
   return session.subscribe((event) => {
     if (event.type === "tool_execution_end") {

package/src/runtime.ts

@@ -49,7 +49,7 @@ export class SubagentRuntime {
    */
   readonly agentActivity: Map<string, AgentActivityTracker> = new Map();
   /**
-   * Persistent widget reference. Null until constructed after AgentManager.
+   * Persistent widget reference. Null until constructed after SubagentManager.
    * Delegation methods use optional chaining so callers never need `widget!`.
    */
   widget: WidgetLike | null = null;

package/src/service/service-adapter.ts

@@ -1,5 +1,5 @@
 /**
- * service-adapter.ts — Adapter that wraps AgentManager to satisfy SubagentsService.
+ * service-adapter.ts — Adapter that wraps SubagentManager to satisfy SubagentsService.
  *
  * Handles model resolution at the API boundary, record serialization
  * (stripping non-serializable fields), and session gating.
@@ -9,13 +9,13 @@ import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 import type { SpawnOptions, SubagentRecord, SubagentsService } from "#src/service/service";
 import type { ModelRegistry } from "#src/session/model-resolver";
-import type { Agent, SessionContext } from "#src/types";
+import type { SessionContext, Subagent } from "#src/types";
 
-/** Narrow interface for the AgentManager — avoids coupling to the concrete class. */
-export interface AgentManagerLike {
+/** Narrow interface for the SubagentManager — avoids coupling to the concrete class. */
+export interface SubagentManagerLike {
   spawn(snapshot: ParentSnapshot, type: string, prompt: string, options: unknown): string;
-  getRecord(id: string): Agent | undefined;
-  listAgents(): Agent[];
+  getRecord(id: string): Subagent | undefined;
+  listAgents(): Subagent[];
   abort(id: string): boolean;
   waitForAll(): Promise<void>;
   hasRunning(): boolean;
@@ -31,10 +31,10 @@ export interface ServiceRuntimeLike {
   buildSnapshot(inheritContext: boolean): ParentSnapshot;
 }
 
-/** Adapter that wraps AgentManager to satisfy SubagentsService. */
+/** Adapter that wraps SubagentManager to satisfy SubagentsService. */
 export class SubagentsServiceAdapter implements SubagentsService {
   constructor(
-    private readonly manager: AgentManagerLike,
+    private readonly manager: SubagentManagerLike,
     private readonly resolveModel: (input: string, registry: ModelRegistry) => unknown,
     private readonly runtime: ServiceRuntimeLike,
   ) {}
@@ -108,10 +108,10 @@ export class SubagentsServiceAdapter implements SubagentsService {
 }
 
 /**
- * Convert an internal Agent to a serializable SubagentRecord.
+ * Convert an internal Subagent to a serializable SubagentRecord.
  * Uses an explicit allowlist — new fields must be opted in.
  */
-export function toSubagentRecord(record: Agent): SubagentRecord {
+export function toSubagentRecord(record: Subagent): SubagentRecord {
   const out: SubagentRecord = {
     id: record.id,
     type: record.type,

package/src/service/service.ts

@@ -9,6 +9,7 @@
  *   svc?.spawn("Explore", "Check for stale TODOs");
  */
 
+import type { SubagentStatus } from "#src/lifecycle/subagent";
 import type { LifetimeUsage } from "#src/lifecycle/usage";
 import type {
   Workspace,
@@ -18,6 +19,10 @@ import type {
   WorkspaceProvider,
 } from "#src/lifecycle/workspace";
 
+
+// SubagentStatus is defined in the lifecycle layer (single home) and re-exported
+// here for the public API surface — mirrors the LifetimeUsage / workspace pattern.
+export type { SubagentStatus } from "#src/lifecycle/subagent";
 // Generative extension seam (ADR 0002, Phase 16 Step 2). The provider type
 // and all four collaborator types it references are re-exported by name so
 // consumers can import them directly rather than recovering them via
@@ -31,15 +36,6 @@ export type {
   WorkspaceProvider,
 };
 
-export type SubagentStatus =
-  | "queued"
-  | "running"
-  | "completed"
-  | "steered"
-  | "aborted"
-  | "stopped"
-  | "error";
-
 /** Serializable snapshot of an agent's state — no live session objects. */
 export interface SubagentRecord {
   id: string;

package/src/tools/agent-tool.ts

@@ -4,14 +4,14 @@ import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentTypeRegistry } from "#src/config/agent-types";
-import type { AgentSpawnConfig } from "#src/lifecycle/agent-manager";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { AgentSpawnConfig } from "#src/lifecycle/subagent-manager";
 import { spawnBackground } from "#src/tools/background-spawner";
 import { runForeground } from "#src/tools/foreground-runner";
 import { buildDetails, buildTypeListText, textResult } from "#src/tools/helpers";
 import { renderAgentResult } from "#src/tools/result-renderer";
 import { type ModelInfo, resolveSpawnConfig } from "#src/tools/spawn-config";
-import type { Agent, ParentSessionInfo } from "#src/types";
+import type { ParentSessionInfo, Subagent } from "#src/types";
 import { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import { type UICtx } from "#src/ui/agent-widget";
 import { type AgentDetails, getDisplayName } from "#src/ui/display";
@@ -33,9 +33,9 @@ export interface AgentActivityAccess {
 /** Narrow manager interface — only the methods the Agent tool calls. */
 export interface AgentToolManager {
 	spawn: (snapshot: ParentSnapshot, type: string, prompt: string, opts: AgentSpawnConfig) => string;
-	spawnAndWait: (snapshot: ParentSnapshot, type: string, prompt: string, opts: Omit<AgentSpawnConfig, "isBackground">) => Promise<Agent>;
-	resume: (id: string, prompt: string, signal: AbortSignal) => Promise<Agent | undefined>;
-	getRecord: (id: string) => Agent | undefined;
+	spawnAndWait: (snapshot: ParentSnapshot, type: string, prompt: string, opts: Omit<AgentSpawnConfig, "isBackground">) => Promise<Subagent>;
+	resume: (id: string, prompt: string, signal: AbortSignal) => Promise<Subagent | undefined>;
+	getRecord: (id: string) => Subagent | undefined;
 }
 
 /** Narrow runtime interface — the Agent tool's slice of SubagentRuntime. */

package/src/tools/background-spawner.ts

@@ -1,16 +1,16 @@
-import type { AgentSpawnConfig } from "#src/lifecycle/agent-manager";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { AgentSpawnConfig } from "#src/lifecycle/subagent-manager";
 import type { AgentActivityAccess } from "#src/tools/agent-tool";
 import { textResult } from "#src/tools/helpers";
 import type { ResolvedSpawnConfig } from "#src/tools/spawn-config";
-import type { Agent, ParentSessionInfo } from "#src/types";
+import type { ParentSessionInfo, Subagent } from "#src/types";
 import { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import { subscribeUIObserver } from "#src/ui/ui-observer";
 
 /** Narrow manager interface for the background spawner. */
 export interface BackgroundManagerDeps {
   spawn(snapshot: ParentSnapshot, type: string, prompt: string, opts: AgentSpawnConfig): string;
-  getRecord(id: string): Agent | undefined;
+  getRecord(id: string): Subagent | undefined;
 }
 
 /** Narrow widget interface for the background spawner. */

package/src/tools/foreground-runner.ts

@@ -1,6 +1,6 @@
 import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
-import type { AgentSpawnConfig } from "#src/lifecycle/agent-manager";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { AgentSpawnConfig } from "#src/lifecycle/subagent-manager";
 import type { AgentActivityAccess } from "#src/tools/agent-tool";
 import {
   buildDetails,
@@ -9,7 +9,7 @@ import {
   textResult,
 } from "#src/tools/helpers";
 import type { ResolvedSpawnConfig } from "#src/tools/spawn-config";
-import type { Agent, ParentSessionInfo } from "#src/types";
+import type { ParentSessionInfo, Subagent } from "#src/types";
 import { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import {
   type AgentDetails,
@@ -26,7 +26,7 @@ export interface ForegroundManagerDeps {
     type: string,
     prompt: string,
     opts: Omit<AgentSpawnConfig, "isBackground">,
-  ): Promise<Agent>;
+  ): Promise<Subagent>;
 }
 
 /** Narrow widget interface for the foreground runner. */
@@ -62,7 +62,7 @@ export async function runForeground(
 
   const fgState = new AgentActivityTracker(execution.effectiveMaxTurns);
   let unsubUI: (() => void) | undefined;
-  let recordRef: Agent | undefined;
+  let recordRef: Subagent | undefined;
 
   const streamUpdate = () => {
     const toolUses = recordRef?.toolUses ?? 0;
@@ -92,7 +92,7 @@ export async function runForeground(
 
   streamUpdate();
 
-  let record: Agent;
+  let record: Subagent;
   try {
     record = await manager.spawnAndWait(
       params.snapshot,

package/src/tools/get-result-tool.ts

@@ -2,13 +2,13 @@ import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import type { AgentConfigLookup } from "#src/config/agent-types";
 import { formatLifetimeTokens, textResult } from "#src/tools/helpers";
-import type { Agent } from "#src/types";
+import type { Subagent } from "#src/types";
 import { formatDuration, getDisplayName } from "#src/ui/display";
 
 // ---- Deps interfaces ----
 
 export interface GetResultToolManager {
-	getRecord(id: string): Agent | undefined;
+	getRecord(id: string): Subagent | undefined;
 }
 
 export interface GetResultToolNotifications {

package/src/tools/steer-tool.ts

@@ -1,12 +1,12 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import { formatLifetimeTokens, textResult } from "#src/tools/helpers";
-import type { Agent } from "#src/types";
+import type { Subagent } from "#src/types";
 
 // ---- Deps interfaces ----
 
 export interface SteerToolManager {
-	getRecord(id: string): Agent | undefined;
+	getRecord(id: string): Subagent | undefined;
 }
 
 export interface SteerToolEvents {

package/src/types.ts

@@ -7,7 +7,7 @@ import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
 import type { ModelRegistry } from "#src/session/model-resolver";
 
 
-export { Agent } from "#src/lifecycle/agent";
+export { Subagent } from "#src/lifecycle/subagent";
 export type { AgentSessionEvent, ThinkingLevel };
 
 /**

package/src/ui/agent-creation-wizard.ts

@@ -9,7 +9,7 @@ import { join } from "node:path";
 
 import { BUILTIN_TOOL_NAMES } from "#src/config/agent-types";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
-import type { Agent } from "#src/types";
+import type { Subagent } from "#src/types";
 import type { AgentFileOps } from "#src/ui/agent-file-ops";
 import { writeAgentFile } from "#src/ui/agent-file-writer";
 import type { MenuUI } from "#src/ui/agent-menu";
@@ -23,7 +23,7 @@ export interface WizardManager {
     type: string,
     prompt: string,
     opts: { description: string; maxTurns: number },
-  ) => Promise<Agent>;
+  ) => Promise<Subagent>;
 }
 
 /** Narrow registry interface for reloading after creation. */

package/src/ui/agent-menu.ts

@@ -4,7 +4,7 @@ import { AgentTypeRegistry } from "#src/config/agent-types";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { type ModelRegistry, resolveModel } from "#src/session/model-resolver";
 import { getModelLabelFromConfig } from "#src/tools/helpers";
-import type { Agent, AgentConfig } from "#src/types";
+import type { AgentConfig, Subagent } from "#src/types";
 import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import { AgentConfigEditor } from "#src/ui/agent-config-editor";
 import { AgentCreationWizard } from "#src/ui/agent-creation-wizard";
@@ -15,15 +15,15 @@ import { formatDuration, getDisplayName } from "#src/ui/display";
 
 /** Narrow manager interface for menu operations. */
 export interface AgentMenuManager {
-  listAgents: () => Agent[];
-  getRecord: (id: string) => Agent | undefined;
+  listAgents: () => Subagent[];
+  getRecord: (id: string) => Subagent | undefined;
   /** Used by generate wizard to spawn an agent that writes the .md file. */
   spawnAndWait: (
     parentSnapshot: ParentSnapshot,
     type: string,
     prompt: string,
     opts: { description: string; maxTurns: number },
-  ) => Promise<Agent>;
+  ) => Promise<Subagent>;
 }
 
 /** Narrow settings interface required by the agent menu. */
@@ -251,7 +251,7 @@ export class AgentsMenuHandler {
     await this.showRunningAgents(ui);
   }
 
-  private async viewAgentConversation(ui: MenuUI, record: Agent): Promise<void> {
+  private async viewAgentConversation(ui: MenuUI, record: Subagent): Promise<void> {
     if (!record.isSessionReady()) {
       ui.notify(
         `Agent is ${record.status === "queued" ? "queued" : "expired"} — no session available.`,

package/src/ui/agent-widget.ts

@@ -7,7 +7,7 @@
  */
 
 import { AgentTypeRegistry } from "#src/config/agent-types";
-import type { AgentManager } from "#src/lifecycle/agent-manager";
+import type { SubagentManager } from "#src/lifecycle/subagent-manager";
 import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import { ERROR_STATUSES, type Theme } from "#src/ui/display";
 import { renderWidgetLines } from "#src/ui/widget-renderer";
@@ -78,7 +78,7 @@ export class AgentWidget {
   private lastStatusText: string | undefined;
 
   constructor(
-    private manager: AgentManager,
+    private manager: SubagentManager,
     private agentActivity: Map<string, AgentActivityTracker>,
     private registry: AgentTypeRegistry,
   ) {}

package/src/ui/conversation-viewer.ts

@@ -8,7 +8,7 @@
 import { type Component, matchesKey, type TUI, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { AgentConfigLookup } from "#src/config/agent-types";
 import { getLifetimeTotal } from "#src/lifecycle/usage";
-import type { Agent } from "#src/types";
+import type { Subagent } from "#src/types";
 import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import { buildInvocationTags, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel, type Theme } from "#src/ui/display";
 import { formatMessage, formatStreamingIndicator } from "#src/ui/message-formatters";
@@ -23,7 +23,7 @@ export const VIEWPORT_HEIGHT_PCT = 70;
 
 export interface ConversationViewerOptions {
   tui: TUI;
-  record: Agent;
+  record: Subagent;
   activity: AgentActivityTracker | undefined;
   theme: Theme;
   done: (result: undefined) => void;
@@ -39,7 +39,7 @@ export class ConversationViewer implements Component {
   private closed = false;
 
   private tui: TUI;
-  private record: Agent;
+  private record: Subagent;
   private activity: AgentActivityTracker | undefined;
   private theme: Theme;
   private done: (result: undefined) => void;