@gotgenes/pi-subagents 6.6.0 → 6.8.0

package/src/tools/agent-tool.ts

@@ -7,9 +7,10 @@ import { AgentTypeRegistry } from "../agent-types.js";
 import { resolveAgentInvocationConfig } from "../invocation-config.js";
 import { resolveInvocationModel } from "../model-resolver.js";
 
+import { NotificationState } from "../notification-state.js";
 import type { AgentInvocation, AgentRecord, SubagentType } from "../types.js";
+import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
 import {
-  type AgentActivity,
   type AgentDetails,
   buildInvocationTags,
   describeActivity,
@@ -26,19 +27,6 @@ import { formatLifetimeTokens, textResult } from "./helpers.js";
 
 // ---- Agent-tool-specific helpers ----
 
-/** Create a fresh AgentActivity state for tracking UI progress. */
-function createAgentActivity(maxTurns?: number): AgentActivity {
-  return {
-    activeTools: new Map(),
-    toolUses: 0,
-    turnCount: 1,
-    maxTurns,
-    responseText: "",
-    session: undefined,
-    lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
-  };
-}
-
 /** Parenthetical status note for completed agent result text. */
 export function getStatusNote(status: string): string {
   switch (status) {
@@ -66,7 +54,7 @@ export function buildDetails(
     session?: any;
     lifetimeUsage: LifetimeUsage;
   },
-  activity?: AgentActivity,
+  activity?: AgentActivityTracker,
   overrides?: Partial<AgentDetails>,
 ): AgentDetails {
   return {
@@ -106,7 +94,7 @@ export interface AgentToolWidget {
 export interface AgentToolDeps {
   manager: AgentToolManager;
   widget: AgentToolWidget;
-  agentActivity: Map<string, AgentActivity>;
+  agentActivity: Map<string, AgentActivityTracker>;
   emitEvent: (name: string, data: unknown) => void;
   registry: AgentTypeRegistry;
   typeListText: string;
@@ -394,7 +382,7 @@ Guidelines:
             `Agent not found: "${params.resume}". It may have been cleaned up.`,
           );
         }
-        if (!existing.session) {
+        if (!existing.execution?.session) {
           return textResult(
             `Agent "${params.resume}" has no active session to resume.`,
           );
@@ -415,7 +403,7 @@ Guidelines:
 
       // Background execution
       if (runInBackground) {
-        const bgState = createAgentActivity(effectiveMaxTurns);
+        const bgState = new AgentActivityTracker(effectiveMaxTurns);
 
         let id: string;
 
@@ -433,7 +421,7 @@ Guidelines:
             isolation,
             invocation: agentInvocation,
             onSessionCreated: (session: any) => {
-              bgState.session = session;
+              bgState.setSession(session);
               subscribeUIObserver(session, bgState);
             },
           });
@@ -443,7 +431,8 @@ Guidelines:
 
         const record = deps.manager.getRecord(id);
         if (record) {
-          record.toolCallId = toolCallId;
+          // Born complete: notification-state object owns toolCallId + resultConsumed.
+          record.notification = new NotificationState(toolCallId);
         }
 
         deps.agentActivity.set(id, bgState);
@@ -464,7 +453,7 @@ Guidelines:
             `Agent ID: ${id}\n` +
             `Type: ${displayName}\n` +
             `Description: ${params.description}\n` +
-            (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
+            (record?.execution?.outputFile ? `Output file: ${record.execution.outputFile}\n` : "") +
             (isQueued
               ? `Position: queued (max ${deps.manager.getMaxConcurrent()} concurrent)\n`
               : "") +
@@ -487,7 +476,7 @@ Guidelines:
       const startedAt = Date.now();
       let fgId: string | undefined;
 
-      const fgState = createAgentActivity(effectiveMaxTurns);
+      const fgState = new AgentActivityTracker(effectiveMaxTurns);
       let unsubUI: (() => void) | undefined;
 
       const streamUpdate = () => {
@@ -535,10 +524,10 @@ Guidelines:
             parentSessionFile: ctx.sessionManager.getSessionFile(),
             parentSessionId: ctx.sessionManager.getSessionId(),
             onSessionCreated: (session: any) => {
-              fgState.session = session;
+              fgState.setSession(session);
               unsubUI = subscribeUIObserver(session, fgState, streamUpdate);
               for (const a of deps.manager.listAgents()) {
-                if (a.session === session) {
+                if (a.execution?.session === session) {
                   fgId = a.id;
                   deps.agentActivity.set(a.id, fgState);
                   deps.widget.ensureTimer();

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

@@ -54,7 +54,9 @@ export function createGetResultTool(deps: GetResultDeps) {
       // (attached earlier at spawn time) and always runs before this await resumes.
       // Setting the flag here prevents a redundant follow-up notification.
       if (params.wait && record.status === "running" && record.promise) {
-        record.resultConsumed = true;
+        // Pre-mark consumed BEFORE awaiting — onComplete fires inside .then() and
+        // always runs before this await resumes. Prevents a redundant notification.
+        record.notification?.markConsumed();
         deps.cancelNudge(params.agent_id);
         await record.promise;
       }
@@ -62,7 +64,7 @@ export function createGetResultTool(deps: GetResultDeps) {
       const displayName = getDisplayName(record.type, deps.registry);
       const duration = formatDuration(record.startedAt, record.completedAt);
       const tokens = formatLifetimeTokens(record);
-      const contextPercent = getSessionContextPercent(record.session);
+      const contextPercent = getSessionContextPercent(record.execution?.session);
       const statsParts = [`Tool uses: ${record.toolUses}`];
       if (tokens) statsParts.push(tokens);
       if (contextPercent !== null) statsParts.push(`Context: ${Math.round(contextPercent)}%`);
@@ -84,13 +86,13 @@ export function createGetResultTool(deps: GetResultDeps) {
 
       // Mark result as consumed — suppresses the completion notification
       if (record.status !== "running" && record.status !== "queued") {
-        record.resultConsumed = true;
+        record.notification?.markConsumed();
         deps.cancelNudge(params.agent_id);
       }
 
       // Verbose: include full conversation
-      if (params.verbose && record.session) {
-        const conversation = deps.getConversation(record.session);
+      if (params.verbose && record.execution?.session) {
+        const conversation = deps.getConversation(record.execution.session);
         if (conversation) {
           output += `\n\n--- Agent Conversation ---\n${conversation}`;
         }

package/src/tools/steer-tool.ts

@@ -9,6 +9,8 @@ export interface SteerToolDeps {
   getRecord: (id: string) => AgentRecord | undefined;
   emitEvent: (name: string, data: unknown) => void;
   steerAgent: (session: AgentSession, message: string) => Promise<void>;
+  /** Buffer a steer for an agent whose session isn't ready yet. */
+  queueSteer: (id: string, message: string) => boolean;
 }
 
 /** Create the steer_subagent tool definition (without Pi SDK wrapper). */
@@ -46,10 +48,10 @@ export function createSteerTool(deps: SteerToolDeps) {
           `Agent "${params.agent_id}" is not running (status: ${record.status}). Cannot steer a non-running agent.`,
         );
       }
-      if (!record.session) {
-        // Session not ready yet — queue the steer for delivery once initialized
-        if (!record.pendingSteers) record.pendingSteers = [];
-        record.pendingSteers.push(params.message);
+      const session = record.execution?.session;
+      if (!session) {
+        // Session not ready yet — queue via manager for delivery once initialized
+        deps.queueSteer(record.id, params.message);
         deps.emitEvent("subagents:steered", { id: record.id, message: params.message });
         return textResult(
           `Steering message queued for agent ${record.id}. It will be delivered once the session initializes.`,
@@ -57,10 +59,10 @@ export function createSteerTool(deps: SteerToolDeps) {
       }
 
       try {
-        await deps.steerAgent(record.session, params.message);
+        await deps.steerAgent(session, params.message);
         deps.emitEvent("subagents:steered", { id: record.id, message: params.message });
         const tokens = formatLifetimeTokens(record);
-        const contextPercent = getSessionContextPercent(record.session);
+        const contextPercent = getSessionContextPercent(session);
         const stateParts: string[] = [];
         if (tokens) stateParts.push(tokens);
         stateParts.push(`${record.toolUses} tool ${record.toolUses === 1 ? "use" : "uses"}`);

package/src/ui/agent-activity-tracker.ts

@@ -0,0 +1,108 @@
+/**
+ * agent-activity-tracker.ts — Per-agent live activity state with explicit transition methods.
+ *
+ * Replaces the mutable `AgentActivity` interface that was written via output arguments
+ * in `ui-observer.ts`. Callers use named transition methods; readers use read-only accessors.
+ */
+
+import { addUsage, type LifetimeUsage, type SessionLike } from "../usage.js";
+
+/** Usage delta accepted by onUsageUpdate — matches the LifetimeUsage accumulator shape. */
+export interface UsageDelta {
+	input: number;
+	output: number;
+	cacheWrite: number;
+}
+
+/** Per-agent live activity state with explicit transition methods and read-only accessors. */
+export class AgentActivityTracker {
+	private _activeTools = new Map<string, string>();
+	private _toolKeySeq = 0;
+	private _toolUses = 0;
+	private _responseText = "";
+	private _session: SessionLike | undefined = undefined;
+	private _turnCount = 1;
+	private _lifetimeUsage: LifetimeUsage = { input: 0, output: 0, cacheWrite: 0 };
+
+	constructor(private readonly _maxTurns?: number) {}
+
+	// ── Transition methods (write surface) ──────────────────────────────────
+
+	/** Record that a tool has started executing. */
+	onToolStart(toolName: string): void {
+		this._activeTools.set(toolName + "_" + (++this._toolKeySeq), toolName);
+	}
+
+	/** Record that a tool has finished executing; increments toolUses. No-op when no matching tool is active. */
+	onToolEnd(toolName: string): void {
+		for (const [key, name] of this._activeTools) {
+			if (name === toolName) {
+				this._activeTools.delete(key);
+				this._toolUses++;
+				break;
+			}
+		}
+	}
+
+	/** Reset the current response text (called at the start of each assistant message). */
+	onMessageStart(): void {
+		this._responseText = "";
+	}
+
+	/** Append a text delta to the current response text. */
+	onMessageUpdate(delta: string): void {
+		this._responseText += delta;
+	}
+
+	/** Record that a turn has ended; increments turnCount. */
+	onTurnEnd(): void {
+		this._turnCount++;
+	}
+
+	/** Accumulate a usage delta into the lifetime usage totals. */
+	onUsageUpdate(delta: UsageDelta): void {
+		addUsage(this._lifetimeUsage, delta);
+	}
+
+	/** Bind the session reference (called once when the agent session is created). */
+	setSession(session: SessionLike): void {
+		this._session = session;
+	}
+
+	// ── Read-only accessors ──────────────────────────────────────────────────
+
+	/** Currently-active tools: key → tool name. Multiple entries for concurrent same-name tools. */
+	get activeTools(): ReadonlyMap<string, string> {
+		return this._activeTools;
+	}
+
+	/** Total completed tool invocations. */
+	get toolUses(): number {
+		return this._toolUses;
+	}
+
+	/** The agent's latest partial response text (reset at each message start). */
+	get responseText(): string {
+		return this._responseText;
+	}
+
+	/** The active SDK session, or undefined before the first session is created. */
+	get session(): SessionLike | undefined {
+		return this._session;
+	}
+
+	/** Current turn count (starts at 1). */
+	get turnCount(): number {
+		return this._turnCount;
+	}
+
+	/** Effective max turns for this agent, or undefined for unlimited. */
+	get maxTurns(): number | undefined {
+		return this._maxTurns;
+	}
+
+	/** Accumulated lifetime token usage (survives compaction). */
+	get lifetimeUsage(): Readonly<LifetimeUsage> {
+		return this._lifetimeUsage;
+	}
+}

package/src/ui/agent-menu.ts

@@ -9,7 +9,7 @@ import {
 } from "../agent-types.js";
 import type { ModelRegistry } from "../model-resolver.js";
 import type { AgentConfig, AgentRecord } from "../types.js";
-import type { AgentActivity } from "./agent-widget.js";
+import type { AgentActivityTracker } from "./agent-activity-tracker.js";
 import { formatDuration, getDisplayName } from "./agent-widget.js";
 
 // ---- Deps interface ----
@@ -35,7 +35,7 @@ export interface AgentMenuSettings {
 export interface AgentMenuDeps {
   manager: AgentMenuManager;
   registry: AgentTypeRegistry;
-  agentActivity: Map<string, AgentActivity>;
+  agentActivity: Map<string, AgentActivityTracker>;
   /** Resolve model label for a given agent type + registry. */
   getModelLabel: (type: string, registry?: ModelRegistry) => string;
   /** Settings manager — owns in-memory values and persistence. */
@@ -197,7 +197,8 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
   }
 
   async function viewAgentConversation(ctx: ExtensionContext, record: AgentRecord) {
-    if (!record.session) {
+    const session = record.execution?.session;
+    if (!session) {
       ctx.ui.notify(
         `Agent is ${record.status === "queued" ? "queued" : "expired"} — no session available.`,
         "info",
@@ -208,7 +209,6 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     const { ConversationViewer, VIEWPORT_HEIGHT_PCT } = await import(
       "./conversation-viewer.js"
     );
-    const session = record.session;
     const activity = deps.agentActivity.get(record.id);
 
     await ctx.ui.custom<undefined>(

package/src/ui/agent-widget.ts

@@ -9,7 +9,8 @@ import { truncateToWidth } from "@earendil-works/pi-tui";
 import type { AgentManager } from "../agent-manager.js";
 import { type AgentConfigLookup, AgentTypeRegistry } from "../agent-types.js";
 import type { AgentInvocation, SubagentType } from "../types.js";
-import { getLifetimeTotal, getSessionContextPercent, type LifetimeUsage, type SessionLike } from "../usage.js";
+import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
+import type { AgentActivityTracker } from "./agent-activity-tracker.js";
 
 // ---- Constants ----
 
@@ -49,20 +50,6 @@ export type UICtx = {
   ): void;
 };
 
-/** Per-agent live activity state. */
-export interface AgentActivity {
-  activeTools: Map<string, string>;
-  toolUses: number;
-  responseText: string;
-  session?: SessionLike;
-  /** Current turn count. */
-  turnCount: number;
-  /** Effective max turns for this agent (undefined = unlimited). */
-  maxTurns?: number;
-  /** Lifetime usage breakdown — see LifetimeUsage docs. */
-  lifetimeUsage: LifetimeUsage;
-}
-
 /** Metadata attached to Agent tool results for custom rendering. */
 export interface AgentDetails {
   displayName: string;
@@ -177,7 +164,7 @@ function truncateLine(text: string, len = 60): string {
 }
 
 /** Build a human-readable activity string from currently-running tools or response text. */
-export function describeActivity(activeTools: Map<string, string>, responseText?: string): string {
+export function describeActivity(activeTools: ReadonlyMap<string, string>, responseText?: string): string {
   if (activeTools.size > 0) {
     const groups = new Map<string, number>();
     for (const toolName of activeTools.values()) {
@@ -224,7 +211,7 @@ export class AgentWidget {
 
   constructor(
     private manager: AgentManager,
-    private agentActivity: Map<string, AgentActivity>,
+    private agentActivity: Map<string, AgentActivityTracker>,
     private registry: AgentTypeRegistry,
   ) {}
 

package/src/ui/conversation-viewer.ts

@@ -11,8 +11,8 @@ import type { AgentConfigLookup } from "../agent-types.js";
 import { extractText } from "../context.js";
 import type { AgentRecord } from "../types.js";
 import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
-import type { Theme } from "./agent-widget.js";
-import { type AgentActivity, buildInvocationTags, describeActivity, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel } from "./agent-widget.js";
+import type { AgentActivityTracker } from "./agent-activity-tracker.js";
+import { buildInvocationTags, describeActivity, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel, type Theme } from "./agent-widget.js";
 
 /** Base lines consumed by chrome: top border + header + header sep + footer sep + footer + bottom border. */
 const CHROME_LINES_BASE = 6;
@@ -31,7 +31,7 @@ export class ConversationViewer implements Component {
     private tui: TUI,
     private session: AgentSession,
     private record: AgentRecord,
-    private activity: AgentActivity | undefined,
+    private activity: AgentActivityTracker | undefined,
     private theme: Theme,
     private done: (result: undefined) => void,
     private registry: AgentConfigLookup,

package/src/ui/ui-observer.ts

@@ -1,13 +1,12 @@
 /**
- * ui-observer.ts — Subscribes to session events and updates AgentActivity state.
+ * ui-observer.ts — Subscribes to session events and updates AgentActivityTracker state.
  *
  * Replaces the callback-based createActivityTracker pattern with a direct
  * session subscription for streaming UI state (active tools, response text,
  * turn count, lifetime usage).
  */
 
-import { addUsage } from "../usage.js";
-import type { AgentActivity } from "./agent-widget.js";
+import type { AgentActivityTracker } from "./agent-activity-tracker.js";
 
 /** Narrow session interface — only the subscribe method needed by the observer. */
 interface SubscribableSession {
@@ -15,15 +14,15 @@ interface SubscribableSession {
 }
 
 /**
- * Subscribe to session events and stream UI state into an AgentActivity object.
+ * Subscribe to session events and stream UI state into an AgentActivityTracker.
  *
  * Handles:
- * - `tool_execution_start` → add to `state.activeTools`
- * - `tool_execution_end` → remove from `state.activeTools`, `state.toolUses++`
- * - `message_start` → reset `state.responseText`
- * - `message_update` (text_delta) → append to `state.responseText`
- * - `turn_end` → `state.turnCount++`
- * - `message_end` (assistant, with usage) → `addUsage(state.lifetimeUsage, …)`
+ * - `tool_execution_start` → `tracker.onToolStart(name)`
+ * - `tool_execution_end` → `tracker.onToolEnd(name)`
+ * - `message_start` → `tracker.onMessageStart()`
+ * - `message_update` (text_delta) → `tracker.onMessageUpdate(delta)`
+ * - `turn_end` → `tracker.onTurnEnd()`
+ * - `message_end` (assistant, with usage) → `tracker.onUsageUpdate(usage)`
  *
  * Calls `onUpdate?.()` after each state mutation to trigger re-renders.
  *
@@ -31,47 +30,41 @@ interface SubscribableSession {
  */
 export function subscribeUIObserver(
 	session: SubscribableSession,
-	state: AgentActivity,
+	tracker: AgentActivityTracker,
 	onUpdate?: () => void,
 ): () => void {
 	return session.subscribe((event: any) => {
 		if (event.type === "tool_execution_start") {
-			state.activeTools.set(event.toolName + "_" + Date.now(), event.toolName);
+			tracker.onToolStart(event.toolName);
 			onUpdate?.();
 		}
 
 		if (event.type === "tool_execution_end") {
-			for (const [key, name] of state.activeTools) {
-				if (name === event.toolName) {
-					state.activeTools.delete(key);
-					break;
-				}
-			}
-			state.toolUses++;
+			tracker.onToolEnd(event.toolName);
 			onUpdate?.();
 		}
 
 		if (event.type === "message_start") {
-			state.responseText = "";
+			tracker.onMessageStart();
 		}
 
 		if (
 			event.type === "message_update" &&
 			event.assistantMessageEvent?.type === "text_delta"
 		) {
-			state.responseText += event.assistantMessageEvent.delta;
+			tracker.onMessageUpdate(event.assistantMessageEvent.delta);
 			onUpdate?.();
 		}
 
 		if (event.type === "turn_end") {
-			state.turnCount++;
+			tracker.onTurnEnd();
 			onUpdate?.();
 		}
 
 		if (event.type === "message_end" && event.message?.role === "assistant") {
 			const u = event.message.usage;
 			if (u) {
-				addUsage(state.lifetimeUsage, {
+				tracker.onUsageUpdate({
 					input: u.input ?? 0,
 					output: u.output ?? 0,
 					cacheWrite: u.cacheWrite ?? 0,

package/src/worktree-state.ts

@@ -0,0 +1,35 @@
+/**
+ * worktree-state.ts — WorktreeState: lifecycle-phase object for worktree-isolated agents.
+ *
+ * Constructed once when the worktree is set up (before the run begins).
+ * Only exists for agents with isolation: "worktree".
+ * cleanupResult is recorded once at completion or error — it is not set at construction.
+ */
+
+import type { WorktreeCleanupResult, WorktreeInfo } from "./worktree.js";
+
+export type { WorktreeCleanupResult, WorktreeInfo };
+
+export class WorktreeState {
+	/** Absolute path to the worktree directory. */
+	readonly path: string;
+	/** Branch name created for this worktree. */
+	readonly branch: string;
+
+	private _cleanupResult?: WorktreeCleanupResult;
+
+	constructor(info: WorktreeInfo) {
+		this.path = info.path;
+		this.branch = info.branch;
+	}
+
+	/** Result of the worktree cleanup — undefined until recordCleanup is called. */
+	get cleanupResult(): WorktreeCleanupResult | undefined {
+		return this._cleanupResult;
+	}
+
+	/** Record the cleanup result. Called once on agent completion or error. */
+	recordCleanup(result: WorktreeCleanupResult): void {
+		this._cleanupResult = result;
+	}
+}