@gotgenes/pi-subagents 6.5.0 → 6.7.0

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 ----
@@ -20,22 +20,22 @@ export interface AgentMenuManager {
   getRecord: (id: string) => AgentRecord | undefined;
   /** Used by generate wizard to spawn an agent that writes the .md file. */
   spawnAndWait: (ctx: ExtensionContext, type: string, prompt: string, opts: Omit<SpawnOptions, "isBackground">) => Promise<AgentRecord>;
-  /** Drain the concurrency queue after maxConcurrent has been updated on SettingsManager. */
-  notifyConcurrencyChanged: () => void;
 }
 
 /** Narrow settings interface required by the agent menu. */
 export interface AgentMenuSettings {
-  maxConcurrent: number;
-  defaultMaxTurns: number | undefined;
-  graceTurns: number;
-  saveAndNotify(msg: string): { message: string; level: "info" | "warning" };
+  readonly maxConcurrent: number;
+  readonly defaultMaxTurns: number | undefined;
+  readonly graceTurns: number;
+  applyMaxConcurrent(n: number): { message: string; level: "info" | "warning" };
+  applyDefaultMaxTurns(n: number): { message: string; level: "info" | "warning" };
+  applyGraceTurns(n: number): { message: string; level: "info" | "warning" };
 }
 
 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. */
@@ -617,9 +617,8 @@ ${systemPrompt}
       if (val) {
         const n = parseInt(val, 10);
         if (n >= 1) {
-          deps.settings.maxConcurrent = n;
-          deps.manager.notifyConcurrencyChanged();
-          notifyApplied(ctx, `Max concurrency set to ${n}`);
+          const toast = deps.settings.applyMaxConcurrent(n);
+          ctx.ui.notify(toast.message, toast.level);
         } else {
           ctx.ui.notify("Must be a positive integer.", "warning");
         }
@@ -631,12 +630,9 @@ ${systemPrompt}
       );
       if (val) {
         const n = parseInt(val, 10);
-        if (n === 0) {
-          deps.settings.defaultMaxTurns = undefined;
-          notifyApplied(ctx, "Default max turns set to unlimited");
-        } else if (n >= 1) {
-          deps.settings.defaultMaxTurns = n;
-          notifyApplied(ctx, `Default max turns set to ${n}`);
+        if (n >= 0) {
+          const toast = deps.settings.applyDefaultMaxTurns(n);
+          ctx.ui.notify(toast.message, toast.level);
         } else {
           ctx.ui.notify("Must be 0 (unlimited) or a positive integer.", "warning");
         }
@@ -649,8 +645,8 @@ ${systemPrompt}
       if (val) {
         const n = parseInt(val, 10);
         if (n >= 1) {
-          deps.settings.graceTurns = n;
-          notifyApplied(ctx, `Grace turns set to ${n}`);
+          const toast = deps.settings.applyGraceTurns(n);
+          ctx.ui.notify(toast.message, toast.level);
         } else {
           ctx.ui.notify("Must be a positive integer.", "warning");
         }
@@ -658,11 +654,6 @@ ${systemPrompt}
     }
   }
 
-  function notifyApplied(ctx: ExtensionContext, successMsg: string) {
-    const { message, level } = deps.settings.saveAndNotify(successMsg);
-    ctx.ui.notify(message, level as "info" | "warning" | "error");
-  }
-
   // Return the handler function
   return async (ctx: ExtensionContext) => {
     await showAgentsMenu(ctx);

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,