@gotgenes/pi-subagents 6.9.0 → 6.9.2

package/src/notification.ts

@@ -1,8 +1,23 @@
 import { debugLog } from "./debug.js";
-import type { AgentRecord, NotificationDetails } from "./types.js";
+import type { AgentRecord } from "./types.js";
 import type { AgentActivityTracker } from "./ui/agent-activity-tracker.js";
 import { getLifetimeTotal, getSessionContextPercent } from "./usage.js";
 
+/** Details attached to custom notification messages for visual rendering. */
+export interface NotificationDetails {
+  id: string;
+  description: string;
+  status: string;
+  toolUses: number;
+  turnCount: number;
+  maxTurns?: number;
+  totalTokens: number;
+  durationMs: number;
+  outputFile?: string;
+  error?: string;
+  resultPreview: string;
+}
+
 // ---- Pure helpers (exported for unit testing) ----
 
 /** Escape XML special characters to prevent injection in structured notifications. */
@@ -129,23 +144,43 @@ export interface NotificationSystem {
 
 const NUDGE_HOLD_MS = 200;
 
-export function createNotificationSystem(deps: NotificationDeps): NotificationSystem {
-  const pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
+export class NotificationManager implements NotificationSystem {
+  private pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
 
-  function cancelNudge(key: string) {
-    const timer = pendingNudges.get(key);
+  constructor(private deps: NotificationDeps) {}
+
+  cancelNudge(key: string): void {
+    const timer = this.pendingNudges.get(key);
     if (timer != null) {
       clearTimeout(timer);
-      pendingNudges.delete(key);
+      this.pendingNudges.delete(key);
     }
   }
 
-  function scheduleNudge(key: string, send: () => void, delay = NUDGE_HOLD_MS) {
-    cancelNudge(key);
-    pendingNudges.set(
+  sendCompletion(record: AgentRecord): void {
+    this.deps.agentActivity.delete(record.id);
+    this.deps.markFinished(record.id);
+    this.scheduleNudge(record.id, () => this.emitIndividualNudge(record));
+    this.deps.updateWidget();
+  }
+
+  cleanupCompleted(id: string): void {
+    this.deps.agentActivity.delete(id);
+    this.deps.markFinished(id);
+    this.deps.updateWidget();
+  }
+
+  dispose(): void {
+    for (const timer of this.pendingNudges.values()) clearTimeout(timer);
+    this.pendingNudges.clear();
+  }
+
+  private scheduleNudge(key: string, send: () => void, delay = NUDGE_HOLD_MS): void {
+    this.cancelNudge(key);
+    this.pendingNudges.set(
       key,
       setTimeout(() => {
-        pendingNudges.delete(key);
+        this.pendingNudges.delete(key);
         try {
           send();
         } catch (err) {
@@ -155,41 +190,21 @@ export function createNotificationSystem(deps: NotificationDeps): NotificationSy
     );
   }
 
-  function emitIndividualNudge(record: AgentRecord) {
+  private emitIndividualNudge(record: AgentRecord): void {
     if (record.notification?.resultConsumed) return;
 
     const notification = formatTaskNotification(record, 500);
     const outputFile = record.execution?.outputFile;
     const footer = outputFile ? `\nFull transcript available at: ${outputFile}` : "";
 
-    deps.sendMessage(
+    this.deps.sendMessage(
       {
         customType: "subagent-notification",
         content: notification + footer,
         display: true,
-        details: buildNotificationDetails(record, 500, deps.agentActivity.get(record.id)),
+        details: buildNotificationDetails(record, 500, this.deps.agentActivity.get(record.id)),
       },
       { deliverAs: "followUp", triggerTurn: true },
     );
   }
-
-  function sendCompletion(record: AgentRecord) {
-    deps.agentActivity.delete(record.id);
-    deps.markFinished(record.id);
-    scheduleNudge(record.id, () => emitIndividualNudge(record));
-    deps.updateWidget();
-  }
-
-  function cleanupCompleted(id: string) {
-    deps.agentActivity.delete(id);
-    deps.markFinished(id);
-    deps.updateWidget();
-  }
-
-  function dispose() {
-    for (const timer of pendingNudges.values()) clearTimeout(timer);
-    pendingNudges.clear();
-  }
-
-  return { cancelNudge, sendCompletion, cleanupCompleted, dispose };
 }

package/src/parent-snapshot.ts

@@ -4,7 +4,26 @@
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { buildParentContext } from "./context.js";
-import type { ParentSnapshot } from "./types.js";
+
+/**
+ * Plain data snapshot of the parent session state captured at spawn time.
+ * Replaces live `ExtensionContext` references so queued agents don't read stale state.
+ */
+export interface ParentSnapshot {
+  /** Parent working directory. */
+  cwd: string;
+  /** Parent's effective system prompt (for append-mode agents). */
+  systemPrompt: string;
+  /** Parent's current model instance (fallback when agent config has no model). */
+  model: unknown;
+  /** Model registry for resolving config.model strings and creating sessions. */
+  modelRegistry: {
+    find(provider: string, modelId: string): unknown;
+    getAvailable?(): Array<{ provider: string; id: string }>;
+  };
+  /** Pre-built parent conversation text (when inheritContext was requested). */
+  parentContext?: string;
+}
 
 /**
  * Build an immutable snapshot of the parent session state.

package/src/prompts.ts

@@ -2,7 +2,8 @@
  * prompts.ts — System prompt builder for agents.
  */
 
-import type { AgentConfig, EnvInfo } from "./types.js";
+import type { EnvInfo } from "./env.js";
+import type { AgentPromptConfig } from "./types.js";
 
 /** Extra sections to inject into the system prompt (memory, skills, etc.). */
 export interface PromptExtras {
@@ -27,7 +28,7 @@ export interface PromptExtras {
  * @param extras  Optional extra sections to inject (memory, preloaded skills).
  */
 export function buildAgentPrompt(
-  config: AgentConfig,
+  config: AgentPromptConfig,
   cwd: string,
   env: EnvInfo,
   parentSystemPrompt?: string,

package/src/renderer.ts

@@ -1,5 +1,5 @@
 import { Text } from "@earendil-works/pi-tui";
-import type { NotificationDetails } from "./types.js";
+import type { NotificationDetails } from "./notification.js";
 import { formatMs, formatTokens, formatTurns } from "./ui/agent-widget.js";
 
 /** Narrow theme interface — only the methods the renderer actually calls. */

package/src/session-config.ts

@@ -15,10 +15,11 @@ import {
   getMemoryToolNames,
   getReadOnlyMemoryToolNames,
 } from "./agent-types.js";
+import type { EnvInfo } from "./env.js";
 import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
 import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
 import { preloadSkills } from "./skill-loader.js";
-import type { EnvInfo, SubagentType, ThinkingLevel } from "./types.js";
+import type { SubagentType, ThinkingLevel } from "./types.js";
 
 // ── Public interfaces ────────────────────────────────────────────────────────
 

package/src/tools/agent-tool.ts

@@ -7,13 +7,11 @@ 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 AgentDetails,
   buildInvocationTags,
-  describeActivity,
   formatMs,
   formatTurns,
   getDisplayName,
@@ -21,55 +19,9 @@ import {
   SPINNER,
   type UICtx,
 } from "../ui/agent-widget.js";
-import { subscribeUIObserver } from "../ui/ui-observer.js";
-import type { LifetimeUsage } from "../usage.js";
-import { buildTypeListText, formatLifetimeTokens, textResult } from "./helpers.js";
-
-// ---- Agent-tool-specific helpers ----
-
-/** Parenthetical status note for completed agent result text. */
-export function getStatusNote(status: string): string {
-  switch (status) {
-    case "aborted":
-      return " (aborted — max turns exceeded, output may be incomplete)";
-    case "steered":
-      return " (wrapped up — reached turn limit)";
-    case "stopped":
-      return " (stopped by user)";
-    default:
-      return "";
-  }
-}
-
-/** Build AgentDetails from a base + record-specific fields. */
-export function buildDetails(
-  base: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">,
-  record: {
-    toolUses: number;
-    startedAt: number;
-    completedAt?: number;
-    status: string;
-    error?: string;
-    id?: string;
-    session?: any;
-    lifetimeUsage: LifetimeUsage;
-  },
-  activity?: AgentActivityTracker,
-  overrides?: Partial<AgentDetails>,
-): AgentDetails {
-  return {
-    ...base,
-    toolUses: record.toolUses,
-    tokens: formatLifetimeTokens(record),
-    turnCount: activity?.turnCount,
-    maxTurns: activity?.maxTurns,
-    durationMs: (record.completedAt ?? Date.now()) - record.startedAt,
-    status: record.status as AgentDetails["status"],
-    agentId: record.id,
-    error: record.error,
-    ...overrides,
-  };
-}
+import { spawnBackground } from "./background-spawner.js";
+import { runForeground } from "./foreground-runner.js";
+import { buildDetails, buildTypeListText, formatLifetimeTokens, getStatusNote, textResult } from "./helpers.js";
 
 // ---- Deps interface ----
 
@@ -80,7 +32,6 @@ export interface AgentToolManager {
   resume: (id: string, prompt: string, signal: AbortSignal) => Promise<AgentRecord | undefined>;
   getRecord: (id: string) => AgentRecord | undefined;
   getMaxConcurrent: () => number;
-  listAgents: () => AgentRecord[];
 }
 
 /** Narrow widget interface — only the methods the Agent tool calls. */
@@ -412,167 +363,48 @@ Guidelines:
 
       // Background execution
       if (runInBackground) {
-        const bgState = new AgentActivityTracker(effectiveMaxTurns);
-
-        let id: string;
-
-        try {
-          id = deps.manager.spawn(ctx, subagentType, params.prompt as string, {
-            parentSessionFile: ctx.sessionManager.getSessionFile(),
-            parentSessionId: ctx.sessionManager.getSessionId(),
+        return spawnBackground(
+          { manager: deps.manager, widget: deps.widget, agentActivity: deps.agentActivity },
+          {
+            ctx,
+            subagentType,
+            prompt: params.prompt as string,
             description: params.description as string,
+            displayName,
+            toolCallId,
+            detailBase,
             model,
-            maxTurns: effectiveMaxTurns,
+            effectiveMaxTurns,
             isolated,
             inheritContext,
-            thinkingLevel: thinking,
-            isBackground: true,
+            thinking,
             isolation,
-            invocation: agentInvocation,
-            onSessionCreated: (session: any) => {
-              bgState.setSession(session);
-              subscribeUIObserver(session, bgState);
-            },
-          });
-        } catch (err) {
-          return textResult(err instanceof Error ? err.message : String(err));
-        }
-
-        const record = deps.manager.getRecord(id);
-        if (record) {
-          // Born complete: notification-state object owns toolCallId + resultConsumed.
-          record.notification = new NotificationState(toolCallId);
-        }
-
-        deps.agentActivity.set(id, bgState);
-        deps.widget.ensureTimer();
-        deps.widget.update();
-
-        const isQueued = record?.status === "queued";
-        return textResult(
-          `Agent ${isQueued ? "queued" : "started"} in background.\n` +
-            `Agent ID: ${id}\n` +
-            `Type: ${displayName}\n` +
-            `Description: ${params.description}\n` +
-            (record?.execution?.outputFile ? `Output file: ${record.execution.outputFile}\n` : "") +
-            (isQueued
-              ? `Position: queued (max ${deps.manager.getMaxConcurrent()} concurrent)\n`
-              : "") +
-            `\nYou will be notified when this agent completes.\n` +
-            `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +
-            `Do not duplicate this agent's work.`,
-          {
-            ...detailBase,
-            toolUses: 0,
-            tokens: "",
-            durationMs: 0,
-            status: "background" as const,
-            agentId: id,
+            agentInvocation,
           },
         );
       }
 
       // Foreground (synchronous) execution — stream progress via onUpdate
-      let spinnerFrame = 0;
-      const startedAt = Date.now();
-      let fgId: string | undefined;
-
-      const fgState = new AgentActivityTracker(effectiveMaxTurns);
-      let unsubUI: (() => void) | undefined;
-
-      const streamUpdate = () => {
-        const details: AgentDetails = {
-          ...detailBase,
-          toolUses: fgState.toolUses,
-          tokens: formatLifetimeTokens(fgState),
-          turnCount: fgState.turnCount,
-          maxTurns: fgState.maxTurns,
-          durationMs: Date.now() - startedAt,
-          status: "running",
-          activity: describeActivity(fgState.activeTools, fgState.responseText),
-          spinnerFrame: spinnerFrame % SPINNER.length,
-        };
-        onUpdate?.({
-          content: [{ type: "text", text: `${fgState.toolUses} tool uses...` }],
-          details: details as any,
-        });
-      };
-
-      // Animate spinner at ~80ms (smooth rotation through 10 braille frames)
-      const spinnerInterval = setInterval(() => {
-        spinnerFrame++;
-        streamUpdate();
-      }, 80);
-
-      streamUpdate();
-
-      let record: AgentRecord;
-      try {
-        record = await deps.manager.spawnAndWait(
+      return runForeground(
+        { manager: deps.manager, widget: deps.widget, agentActivity: deps.agentActivity },
+        {
           ctx,
           subagentType,
-          params.prompt as string,
-          {
-            description: params.description as string,
-            model,
-            maxTurns: effectiveMaxTurns,
-            isolated,
-            inheritContext,
-            thinkingLevel: thinking,
-            isolation,
-            invocation: agentInvocation,
-            signal,
-            parentSessionFile: ctx.sessionManager.getSessionFile(),
-            parentSessionId: ctx.sessionManager.getSessionId(),
-            onSessionCreated: (session: any) => {
-              fgState.setSession(session);
-              unsubUI = subscribeUIObserver(session, fgState, streamUpdate);
-              for (const a of deps.manager.listAgents()) {
-                if (a.execution?.session === session) {
-                  fgId = a.id;
-                  deps.agentActivity.set(a.id, fgState);
-                  deps.widget.ensureTimer();
-                  break;
-                }
-              }
-            },
-          },
-        );
-      } catch (err) {
-        clearInterval(spinnerInterval);
-        unsubUI?.();
-        return textResult(err instanceof Error ? err.message : String(err));
-      }
-
-      clearInterval(spinnerInterval);
-      unsubUI?.();
-
-      // Clean up foreground agent from widget
-      if (fgId) {
-        deps.agentActivity.delete(fgId);
-        deps.widget.markFinished(fgId);
-      }
-
-      // Get final token count
-      const tokenText = formatLifetimeTokens(fgState);
-
-      const details = buildDetails(detailBase, record, fgState, { tokens: tokenText });
-
-      const fallbackNote = fellBack
-        ? `Note: Unknown agent type "${rawType}" — using general-purpose.\n\n`
-        : "";
-
-      if (record.status === "error") {
-        return textResult(`${fallbackNote}Agent failed: ${record.error}`, details);
-      }
-
-      const durationMs = (record.completedAt ?? Date.now()) - record.startedAt;
-      const statsParts = [`${record.toolUses} tool uses`];
-      if (tokenText) statsParts.push(tokenText);
-      return textResult(
-        `${fallbackNote}Agent completed in ${formatMs(durationMs)} (${statsParts.join(", ")})${getStatusNote(record.status)}.\n\n` +
-          (record.result?.trim() || "No output."),
-        details,
+          prompt: params.prompt as string,
+          description: params.description as string,
+          detailBase,
+          rawType,
+          fellBack,
+          model,
+          effectiveMaxTurns,
+          isolated,
+          inheritContext,
+          thinking,
+          isolation,
+          agentInvocation,
+        },
+        signal,
+        onUpdate,
       );
     },
   };

package/src/tools/background-spawner.ts

@@ -0,0 +1,116 @@
+import type { Model } from "@earendil-works/pi-ai";
+import type { AgentSpawnConfig } from "../agent-manager.js";
+import type { AgentInvocation, AgentRecord, IsolationMode, ThinkingLevel } from "../types.js";
+import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
+import type { AgentDetails } from "../ui/agent-widget.js";
+import { subscribeUIObserver } from "../ui/ui-observer.js";
+import type { AgentActivityAccess } from "./agent-tool.js";
+import { textResult } from "./helpers.js";
+
+/** Narrow manager interface for the background spawner. */
+export interface BackgroundManagerDeps {
+  spawn(ctx: any, type: string, prompt: string, opts: AgentSpawnConfig): string;
+  getRecord(id: string): AgentRecord | undefined;
+  getMaxConcurrent(): number;
+}
+
+/** Narrow widget interface for the background spawner. */
+export interface BackgroundWidgetDeps {
+  ensureTimer(): void;
+  update(): void;
+}
+
+/** Injected collaborators for spawnBackground. */
+export interface BackgroundDeps {
+  manager: BackgroundManagerDeps;
+  widget: BackgroundWidgetDeps;
+  agentActivity: AgentActivityAccess;
+}
+
+/** All values the background spawner needs, bundled from shared execute setup. */
+export interface BackgroundParams {
+  ctx: {
+    sessionManager: {
+      getSessionFile(): string;
+      getSessionId(): string;
+    };
+  };
+  subagentType: string;
+  prompt: string;
+  description: string;
+  displayName: string;
+  toolCallId: string;
+  detailBase: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">;
+  model: Model<any> | undefined;
+  effectiveMaxTurns: number | undefined;
+  isolated: boolean | undefined;
+  inheritContext: boolean | undefined;
+  thinking: ThinkingLevel | undefined;
+  isolation: IsolationMode | undefined;
+  agentInvocation: AgentInvocation;
+}
+
+/**
+ * Spawn a background agent and return the tool result immediately.
+ * Owns: activity tracker creation, UI observer subscription, activity map
+ * registration, widget update, and launch message formatting.
+ */
+export function spawnBackground(
+  deps: BackgroundDeps,
+  params: BackgroundParams,
+) {
+  const bgState = new AgentActivityTracker(params.effectiveMaxTurns);
+
+  let id: string;
+  try {
+    id = deps.manager.spawn(params.ctx, params.subagentType, params.prompt, {
+      parentSessionFile: params.ctx.sessionManager.getSessionFile(),
+      parentSessionId: params.ctx.sessionManager.getSessionId(),
+      description: params.description,
+      model: params.model,
+      maxTurns: params.effectiveMaxTurns,
+      isolated: params.isolated,
+      inheritContext: params.inheritContext,
+      thinkingLevel: params.thinking,
+      isBackground: true,
+      isolation: params.isolation,
+      invocation: params.agentInvocation,
+      toolCallId: params.toolCallId,
+      onSessionCreated: (session) => {
+        bgState.setSession(session);
+        subscribeUIObserver(session, bgState);
+      },
+    });
+  } catch (err) {
+    return textResult(err instanceof Error ? err.message : String(err));
+  }
+
+  const record = deps.manager.getRecord(id);
+
+  deps.agentActivity.set(id, bgState);
+  deps.widget.ensureTimer();
+  deps.widget.update();
+
+  const isQueued = record?.status === "queued";
+  return textResult(
+    `Agent ${isQueued ? "queued" : "started"} in background.\n` +
+      `Agent ID: ${id}\n` +
+      `Type: ${params.displayName}\n` +
+      `Description: ${params.description}\n` +
+      (record?.execution?.outputFile ? `Output file: ${record.execution.outputFile}\n` : "") +
+      (isQueued
+        ? `Position: queued (max ${deps.manager.getMaxConcurrent()} concurrent)\n`
+        : "") +
+      `\nYou will be notified when this agent completes.\n` +
+      `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +
+      `Do not duplicate this agent's work.`,
+    {
+      ...params.detailBase,
+      toolUses: 0,
+      tokens: "",
+      durationMs: 0,
+      status: "background" as const,
+      agentId: id,
+    },
+  );
+}