@gotgenes/pi-subagents 6.14.0 → 6.15.0

package/src/tools/agent-tool.ts

@@ -1,34 +1,31 @@
-import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import type { AgentSpawnConfig } from "../agent-manager.js";
-import { normalizeMaxTurns } from "../agent-runner.js";
 import { AgentTypeRegistry } from "../agent-types.js";
-import { resolveAgentInvocationConfig } from "../invocation-config.js";
-import { resolveInvocationModel } from "../model-resolver.js";
+import type { ParentSnapshot } from "../parent-snapshot.js";
 
-import type { AgentInvocation, AgentRecord, SubagentType } from "../types.js";
+import type { AgentRecord } from "../types.js";
 import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
 import { type UICtx } from "../ui/agent-widget.js";
 import {
   type AgentDetails,
-  buildInvocationTags,
   formatMs,
   formatTurns,
   getDisplayName,
-  getPromptModeLabel,
   SPINNER,
 } from "../ui/display.js";
 import { spawnBackground } from "./background-spawner.js";
 import { runForeground } from "./foreground-runner.js";
 import { buildDetails, buildTypeListText, textResult } from "./helpers.js";
+import { type ModelInfo, resolveSpawnConfig } from "./spawn-config.js";
 
 // ---- Deps interface ----
 
 /** Narrow manager interface — only the methods the Agent tool calls. */
 export interface AgentToolManager {
-  spawn: (ctx: ExtensionContext, type: string, prompt: string, opts: AgentSpawnConfig) => string;
-  spawnAndWait: (ctx: ExtensionContext, type: string, prompt: string, opts: Omit<AgentSpawnConfig, "isBackground">) => Promise<AgentRecord>;
+  spawn: (snapshot: ParentSnapshot, type: string, prompt: string, opts: AgentSpawnConfig) => string;
+  spawnAndWait: (snapshot: ParentSnapshot, type: string, prompt: string, opts: Omit<AgentSpawnConfig, "isBackground">) => Promise<AgentRecord>;
   resume: (id: string, prompt: string, signal: AbortSignal) => Promise<AgentRecord | undefined>;
   getRecord: (id: string) => AgentRecord | undefined;
   getMaxConcurrent: () => number;
@@ -60,14 +57,30 @@ export interface AgentToolDeps {
   agentDir: string;
   /** Narrow settings accessor — only the default max turns is needed here. */
   settings: { readonly defaultMaxTurns: number | undefined };
+  /** Build a ParentSnapshot from the current session context. */
+  buildSnapshot: (inheritContext: boolean) => ParentSnapshot;
+  /** Model info from the current session context. */
+  getModelInfo: () => ModelInfo;
+  /** Parent session identity from the current session context. */
+  getSessionInfo: () => { parentSessionFile: string; parentSessionId: string };
 }
 
 // ---- Factory ----
 
 /** 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(", ");
+export function createAgentTool({
+  manager,
+  widget,
+  agentActivity,
+  registry,
+  agentDir,
+  settings,
+  buildSnapshot,
+  getModelInfo,
+  getSessionInfo,
+}: AgentToolDeps) {
+  const typeListText = buildTypeListText(registry, agentDir);
+  const availableTypesText = registry.getAvailableTypes().join(", ");
   return {
     name: "Agent" as const,
     label: "Agent",
@@ -101,7 +114,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: ${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 ${agentDir}/agents/<name>.md (global) are also available.`,
       }),
       model: Type.Optional(
         Type.String({
@@ -156,7 +169,7 @@ Guidelines:
 
     renderCall(args: Record<string, unknown>, theme: any) {
       const displayName = args.subagent_type
-        ? getDisplayName(args.subagent_type as string, deps.registry)
+        ? getDisplayName(args.subagent_type as string, registry)
         : "Agent";
       const desc = (args.description as string) ?? "";
       return new Text(
@@ -273,71 +286,27 @@ Guidelines:
       ctx: any,
     ) => {
       // Ensure we have UI context for widget rendering
-      deps.widget.setUICtx(ctx.ui as UICtx);
+      widget.setUICtx(ctx.ui as UICtx);
 
       // Reload custom agents so new .pi/agents/*.md files are picked up without restart
-      deps.registry.reload();
-
-      const rawType = params.subagent_type as SubagentType;
-      const resolved = deps.registry.resolveType(rawType);
-      const subagentType = resolved ?? "general-purpose";
-      const fellBack = resolved === undefined;
-
-      const displayName = getDisplayName(subagentType, deps.registry);
-
-      // Get agent config for invocation resolution
-      const customConfig = deps.registry.resolveAgentConfig(subagentType);
-
-      const resolvedConfig = resolveAgentInvocationConfig(customConfig, params);
-
-      // Resolve model from agent config first; tool-call params only fill gaps.
-      const resolution = resolveInvocationModel(
-        ctx.model,
-        resolvedConfig.modelInput,
-        resolvedConfig.modelFromParams,
-        ctx.modelRegistry,
+      registry.reload();
+
+      // ---- Config resolution (pure) ----
+      const config = resolveSpawnConfig(
+        params,
+        registry,
+        getModelInfo(),
+        settings,
       );
-      if (resolution.error) return textResult(resolution.error);
-      const model = resolution.model;
+      if ("error" in config) return textResult(config.error);
 
-      const thinking = resolvedConfig.thinking;
-      const inheritContext = resolvedConfig.inheritContext;
-      const runInBackground = resolvedConfig.runInBackground;
-      const isolated = resolvedConfig.isolated;
-      const isolation = resolvedConfig.isolation;
-
-      const parentModelId = ctx.model?.id;
-      const effectiveModelId = model?.id;
-      const modelName =
-        effectiveModelId && effectiveModelId !== parentModelId
-          ? (model?.name ?? effectiveModelId).replace(/^Claude\s+/i, "").toLowerCase()
-          : undefined;
-      const effectiveMaxTurns = normalizeMaxTurns(
-        resolvedConfig.maxTurns ?? deps.settings.defaultMaxTurns,
-      );
-      const agentInvocation: AgentInvocation = {
-        modelName,
-        thinking,
-        maxTurns: normalizeMaxTurns(resolvedConfig.maxTurns),
-        isolated,
-        inheritContext,
-        runInBackground,
-        isolation,
-      };
-      const modeLabel = getPromptModeLabel(subagentType, deps.registry);
-      const { tags: invocationTags } = buildInvocationTags(agentInvocation);
-      const agentTags = modeLabel ? [modeLabel, ...invocationTags] : invocationTags;
-      const detailBase = {
-        displayName,
-        description: params.description as string,
-        subagentType,
-        modelName,
-        tags: agentTags.length > 0 ? agentTags : undefined,
-      };
+      // ---- Boundary extraction (after config so inheritContext is resolved) ----
+      const snapshot = buildSnapshot(config.inheritContext);
+      const { parentSessionFile, parentSessionId } = getSessionInfo();
 
-      // Resume existing agent
+      // ---- Resume existing agent ----
       if (params.resume) {
-        const existing = deps.manager.getRecord(params.resume as string);
+        const existing = manager.getRecord(params.resume as string);
         if (!existing) {
           return textResult(
             `Agent not found: "${params.resume}". It may have been cleaned up.`,
@@ -348,7 +317,7 @@ Guidelines:
             `Agent "${params.resume}" has no active session to resume.`,
           );
         }
-        const record = await deps.manager.resume(
+        const record = await manager.resume(
           params.resume as string,
           params.prompt as string,
           signal ?? new AbortController().signal,
@@ -358,52 +327,26 @@ Guidelines:
         }
         return textResult(
           record.result?.trim() || record.error?.trim() || "No output.",
-          buildDetails(detailBase, record),
+          buildDetails(config.detailBase, record),
         );
       }
 
-      // Background execution
-      if (runInBackground) {
+      // ---- Background execution ----
+      if (config.runInBackground) {
         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,
-            effectiveMaxTurns,
-            isolated,
-            inheritContext,
-            thinking,
-            isolation,
-            agentInvocation,
-          },
+          manager,
+          widget,
+          agentActivity,
+          { config, snapshot, parentSessionFile, parentSessionId, toolCallId },
         );
       }
 
-      // Foreground (synchronous) execution — stream progress via onUpdate
+      // ---- Foreground execution — stream progress via onUpdate ----
       return runForeground(
-        { manager: deps.manager, widget: deps.widget, agentActivity: deps.agentActivity },
-        {
-          ctx,
-          subagentType,
-          prompt: params.prompt as string,
-          description: params.description as string,
-          detailBase,
-          rawType,
-          fellBack,
-          model,
-          effectiveMaxTurns,
-          isolated,
-          inheritContext,
-          thinking,
-          isolation,
-          agentInvocation,
-        },
+        manager,
+        widget,
+        agentActivity,
+        { config, snapshot, parentSessionFile, parentSessionId },
         signal,
         onUpdate,
       );

package/src/tools/background-spawner.ts

@@ -1,15 +1,15 @@
-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 type { ParentSnapshot } from "../parent-snapshot.js";
+import type { AgentRecord } from "../types.js";
 import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
-import type { AgentDetails } from "../ui/display.js";
 import { subscribeUIObserver } from "../ui/ui-observer.js";
 import type { AgentActivityAccess } from "./agent-tool.js";
 import { textResult } from "./helpers.js";
+import type { ResolvedSpawnConfig } from "./spawn-config.js";
 
 /** Narrow manager interface for the background spawner. */
 export interface BackgroundManagerDeps {
-  spawn(ctx: any, type: string, prompt: string, opts: AgentSpawnConfig): string;
+  spawn(snapshot: ParentSnapshot, type: string, prompt: string, opts: AgentSpawnConfig): string;
   getRecord(id: string): AgentRecord | undefined;
   getMaxConcurrent(): number;
 }
@@ -20,34 +20,13 @@ export interface BackgroundWidgetDeps {
   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. */
+/** All values the background spawner needs beyond the resolved config. */
 export interface BackgroundParams {
-  ctx: {
-    sessionManager: {
-      getSessionFile(): string;
-      getSessionId(): string;
-    };
-  };
-  subagentType: string;
-  prompt: string;
-  description: string;
-  displayName: string;
+  config: ResolvedSpawnConfig;
+  snapshot: ParentSnapshot;
+  parentSessionFile: string;
+  parentSessionId: 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;
 }
 
 /**
@@ -56,25 +35,28 @@ export interface BackgroundParams {
  * registration, widget update, and launch message formatting.
  */
 export function spawnBackground(
-  deps: BackgroundDeps,
+  manager: BackgroundManagerDeps,
+  widget: BackgroundWidgetDeps,
+  agentActivity: AgentActivityAccess,
   params: BackgroundParams,
 ) {
-  const bgState = new AgentActivityTracker(params.effectiveMaxTurns);
+  const { config } = params;
+  const bgState = new AgentActivityTracker(config.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,
+    id = manager.spawn(params.snapshot, config.subagentType, config.prompt, {
+      parentSessionFile: params.parentSessionFile,
+      parentSessionId: params.parentSessionId,
+      description: config.description,
+      model: config.model,
+      maxTurns: config.effectiveMaxTurns,
+      isolated: config.isolated,
+      inheritContext: config.inheritContext,
+      thinkingLevel: config.thinking,
       isBackground: true,
-      isolation: params.isolation,
-      invocation: params.agentInvocation,
+      isolation: config.isolation,
+      invocation: config.agentInvocation,
       toolCallId: params.toolCallId,
       onSessionCreated: (session) => {
         bgState.setSession(session);
@@ -85,27 +67,27 @@ export function spawnBackground(
     return textResult(err instanceof Error ? err.message : String(err));
   }
 
-  const record = deps.manager.getRecord(id);
+  const record = manager.getRecord(id);
 
-  deps.agentActivity.set(id, bgState);
-  deps.widget.ensureTimer();
-  deps.widget.update();
+  agentActivity.set(id, bgState);
+  widget.ensureTimer();
+  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` +
+      `Type: ${config.displayName}\n` +
+      `Description: ${config.description}\n` +
       (record?.execution?.outputFile ? `Output file: ${record.execution.outputFile}\n` : "") +
       (isQueued
-        ? `Position: queued (max ${deps.manager.getMaxConcurrent()} concurrent)\n`
+        ? `Position: queued (max ${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,
+      ...config.detailBase,
       toolUses: 0,
       tokens: "",
       durationMs: 0,

package/src/tools/foreground-runner.ts

@@ -1,7 +1,7 @@
-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 type { ParentSnapshot } from "../parent-snapshot.js";
+import type { AgentRecord } from "../types.js";
 import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
 import {
   type AgentDetails,
@@ -17,11 +17,12 @@ import {
   getStatusNote,
   textResult,
 } from "./helpers.js";
+import type { ResolvedSpawnConfig } from "./spawn-config.js";
 
 /** Narrow manager interface for the foreground runner. */
 export interface ForegroundManagerDeps {
   spawnAndWait(
-    ctx: any,
+    snapshot: ParentSnapshot,
     type: string,
     prompt: string,
     opts: Omit<AgentSpawnConfig, "isBackground">,
@@ -34,37 +35,12 @@ export interface ForegroundWidgetDeps {
   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. */
+/** All values the foreground runner needs beyond the resolved config. */
 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;
+  config: ResolvedSpawnConfig;
+  snapshot: ParentSnapshot;
+  parentSessionFile: string;
+  parentSessionId: string;
 }
 
 /**
@@ -73,21 +49,24 @@ export interface ForegroundParams {
  * streaming onUpdate callbacks, cleanup, and result formatting.
  */
 export async function runForeground(
-  deps: ForegroundDeps,
+  manager: ForegroundManagerDeps,
+  widget: ForegroundWidgetDeps,
+  agentActivity: AgentActivityAccess,
   params: ForegroundParams,
   signal: AbortSignal | undefined,
   onUpdate: ((update: AgentToolResult<any>) => void) | undefined,
 ) {
+  const { config } = params;
   let spinnerFrame = 0;
   const startedAt = Date.now();
   let fgId: string | undefined;
 
-  const fgState = new AgentActivityTracker(params.effectiveMaxTurns);
+  const fgState = new AgentActivityTracker(config.effectiveMaxTurns);
   let unsubUI: (() => void) | undefined;
 
   const streamUpdate = () => {
     const details: AgentDetails = {
-      ...params.detailBase,
+      ...config.detailBase,
       toolUses: fgState.toolUses,
       tokens: formatLifetimeTokens(fgState),
       turnCount: fgState.turnCount,
@@ -113,28 +92,28 @@ export async function runForeground(
 
   let record: AgentRecord;
   try {
-    record = await deps.manager.spawnAndWait(
-      params.ctx,
-      params.subagentType,
-      params.prompt,
+    record = await manager.spawnAndWait(
+      params.snapshot,
+      config.subagentType,
+      config.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,
+        description: config.description,
+        model: config.model,
+        maxTurns: config.effectiveMaxTurns,
+        isolated: config.isolated,
+        inheritContext: config.inheritContext,
+        thinkingLevel: config.thinking,
+        isolation: config.isolation,
+        invocation: config.agentInvocation,
         signal,
-        parentSessionFile: params.ctx.sessionManager.getSessionFile(),
-        parentSessionId: params.ctx.sessionManager.getSessionId(),
+        parentSessionFile: params.parentSessionFile,
+        parentSessionId: params.parentSessionId,
         onSessionCreated: (session, record) => {
           fgState.setSession(session);
           unsubUI = subscribeUIObserver(session, fgState, streamUpdate);
           fgId = record.id;
-          deps.agentActivity.set(record.id, fgState);
-          deps.widget.ensureTimer();
+          agentActivity.set(record.id, fgState);
+          widget.ensureTimer();
         },
       },
     );
@@ -149,15 +128,15 @@ export async function runForeground(
 
   // Clean up foreground agent from widget
   if (fgId) {
-    deps.agentActivity.delete(fgId);
-    deps.widget.markFinished(fgId);
+    agentActivity.delete(fgId);
+    widget.markFinished(fgId);
   }
 
   const tokenText = formatLifetimeTokens(fgState);
-  const details = buildDetails(params.detailBase, record, fgState, { tokens: tokenText });
+  const details = buildDetails(config.detailBase, record, fgState, { tokens: tokenText });
 
-  const fallbackNote = params.fellBack
-    ? `Note: Unknown agent type "${params.rawType}" \u2014 using general-purpose.\n\n`
+  const fallbackNote = config.fellBack
+    ? `Note: Unknown agent type "${config.rawType}" — using general-purpose.\n\n`
     : "";
 
   if (record.status === "error") {