@gotgenes/pi-subagents 6.8.3 → 6.9.1

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 { 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. */
@@ -91,14 +42,21 @@ export interface AgentToolWidget {
   markFinished: (id: string) => void;
 }
 
+/**
+ * Narrow read/write interface for the agent-tool's agentActivity access.
+ * The full Map satisfies this structurally — no wrapper needed.
+ */
+export interface AgentActivityAccess {
+  get(id: string): AgentActivityTracker | undefined;
+  set(id: string, tracker: AgentActivityTracker): void;
+  delete(id: string): void;
+}
+
 export interface AgentToolDeps {
   manager: AgentToolManager;
   widget: AgentToolWidget;
-  agentActivity: Map<string, AgentActivityTracker>;
-  emitEvent: (name: string, data: unknown) => void;
+  agentActivity: AgentActivityAccess;
   registry: AgentTypeRegistry;
-  typeListText: string;
-  availableTypesText: string;
   agentDir: string;
   /** Narrow settings accessor — only the default max turns is needed here. */
   settings: { readonly defaultMaxTurns: number | undefined };
@@ -108,6 +66,8 @@ export interface AgentToolDeps {
 
 /** Create the Agent tool definition (without Pi SDK wrapper). */
 export function createAgentTool(deps: AgentToolDeps) {
+  const typeListText = buildTypeListText(deps.registry, deps.agentDir);
+  const availableTypesText = deps.registry.getAvailableTypes().join(", ");
   return {
     name: "Agent" as const,
     label: "Agent",
@@ -116,7 +76,7 @@ export function createAgentTool(deps: AgentToolDeps) {
 The Agent tool launches specialized agents that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
 
 Available agent types:
-${deps.typeListText}
+${typeListText}
 
 Guidelines:
 - For parallel work, use run_in_background: true on each agent. Foreground calls run sequentially — only one executes at a time.
@@ -140,7 +100,7 @@ Guidelines:
         description: "A short (3-5 word) description of the task (shown in UI).",
       }),
       subagent_type: Type.String({
-        description: `The type of specialized agent to use. Available types: ${deps.availableTypesText}. Custom agents from .pi/agents/<name>.md (project) or ${deps.agentDir}/agents/<name>.md (global) are also available.`,
+        description: `The type of specialized agent to use. Available types: ${availableTypesText}. Custom agents from .pi/agents/<name>.md (project) or ${deps.agentDir}/agents/<name>.md (global) are also available.`,
       }),
       model: Type.Optional(
         Type.String({
@@ -403,175 +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();
-
-        // Emit created event
-        deps.emitEvent("subagents:created", {
-          id,
-          type: subagentType,
-          description: params.description,
-          isBackground: true,
-        });
-
-        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,
+    },
+  );
+}

package/src/tools/foreground-runner.ts

@@ -0,0 +1,175 @@
+import type { Model } from "@earendil-works/pi-ai";
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+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,
+  describeActivity,
+  formatMs,
+  SPINNER,
+} from "../ui/agent-widget.js";
+import { subscribeUIObserver } from "../ui/ui-observer.js";
+import type { AgentActivityAccess } from "./agent-tool.js";
+import {
+  buildDetails,
+  formatLifetimeTokens,
+  getStatusNote,
+  textResult,
+} from "./helpers.js";
+
+/** Narrow manager interface for the foreground runner. */
+export interface ForegroundManagerDeps {
+  spawnAndWait(
+    ctx: any,
+    type: string,
+    prompt: string,
+    opts: Omit<AgentSpawnConfig, "isBackground">,
+  ): Promise<AgentRecord>;
+}
+
+/** Narrow widget interface for the foreground runner. */
+export interface ForegroundWidgetDeps {
+  ensureTimer(): void;
+  markFinished(id: string): void;
+}
+
+/** Injected collaborators for runForeground. */
+export interface ForegroundDeps {
+  manager: ForegroundManagerDeps;
+  widget: ForegroundWidgetDeps;
+  agentActivity: AgentActivityAccess;
+}
+
+/** All values the foreground runner needs, bundled from shared execute setup. */
+export interface ForegroundParams {
+  ctx: {
+    sessionManager: {
+      getSessionFile(): string;
+      getSessionId(): string;
+    };
+  };
+  subagentType: string;
+  prompt: string;
+  description: string;
+  detailBase: Pick<
+    AgentDetails,
+    "displayName" | "description" | "subagentType" | "modelName" | "tags"
+  >;
+  rawType: string;
+  fellBack: boolean;
+  model: Model<any> | undefined;
+  effectiveMaxTurns: number | undefined;
+  isolated: boolean | undefined;
+  inheritContext: boolean | undefined;
+  thinking: ThinkingLevel | undefined;
+  isolation: IsolationMode | undefined;
+  agentInvocation: AgentInvocation;
+}
+
+/**
+ * Run an agent synchronously in the foreground, streaming spinner updates.
+ * Owns: spinner interval, AgentActivityTracker creation, UI observer subscription,
+ * streaming onUpdate callbacks, cleanup, and result formatting.
+ */
+export async function runForeground(
+  deps: ForegroundDeps,
+  params: ForegroundParams,
+  signal: AbortSignal | undefined,
+  onUpdate: ((update: AgentToolResult<any>) => void) | undefined,
+) {
+  let spinnerFrame = 0;
+  const startedAt = Date.now();
+  let fgId: string | undefined;
+
+  const fgState = new AgentActivityTracker(params.effectiveMaxTurns);
+  let unsubUI: (() => void) | undefined;
+
+  const streamUpdate = () => {
+    const details: AgentDetails = {
+      ...params.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(
+      params.ctx,
+      params.subagentType,
+      params.prompt,
+      {
+        description: params.description,
+        model: params.model,
+        maxTurns: params.effectiveMaxTurns,
+        isolated: params.isolated,
+        inheritContext: params.inheritContext,
+        thinkingLevel: params.thinking,
+        isolation: params.isolation,
+        invocation: params.agentInvocation,
+        signal,
+        parentSessionFile: params.ctx.sessionManager.getSessionFile(),
+        parentSessionId: params.ctx.sessionManager.getSessionId(),
+        onSessionCreated: (session, record) => {
+          fgState.setSession(session);
+          unsubUI = subscribeUIObserver(session, fgState, streamUpdate);
+          fgId = record.id;
+          deps.agentActivity.set(record.id, fgState);
+          deps.widget.ensureTimer();
+        },
+      },
+    );
+  } 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);
+  }
+
+  const tokenText = formatLifetimeTokens(fgState);
+  const details = buildDetails(params.detailBase, record, fgState, { tokens: tokenText });
+
+  const fallbackNote = params.fellBack
+    ? `Note: Unknown agent type "${params.rawType}" \u2014 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,
+  );
+}