@gotgenes/pi-subagents 6.10.0 → 6.12.0

package/src/agent-runner.ts

@@ -6,26 +6,35 @@ import type { Model } from "@earendil-works/pi-ai";
 import {
   type AgentSession,
   type AgentSessionEvent,
-  createAgentSession,
-  DefaultResourceLoader,
-  getAgentDir,
-  SessionManager,
-  SettingsManager,
+  type SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import type { AgentConfigLookup } from "./agent-types.js";
 import { extractText } from "./context.js";
-import { detectEnv } from "./env.js";
-import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
+import type { EnvInfo } from "./env.js";
 import type { ParentSnapshot } from "./parent-snapshot.js";
-import { buildAgentPrompt } from "./prompts.js";
 import { type AssemblerIO, assembleSessionConfig } from "./session-config.js";
-import { deriveSubagentSessionDir } from "./session-dir.js";
-import { preloadSkills } from "./skill-loader.js";
 import type { ShellExec, SubagentType, ThinkingLevel } from "./types.js";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
 const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
 
+// ── Local message-shape types ───────────────────────────────────────────────
+// The Pi SDK does not export a narrow type for tool-call content variants.
+
+/** Tool-call content item — SDK exposes this variant at runtime but doesn’t export the narrow type. */
+interface ToolCallContent {
+  type: "toolCall";
+  name?: string;
+  toolName?: string;
+}
+
+/** Extracts the display name from a tool-call content item. */
+function getToolCallName(c: { type: string }): string {
+  if (c.type !== "toolCall") return "unknown";
+  const tc = c as ToolCallContent;
+  return tc.name ?? tc.toolName ?? "unknown";
+}
+
 /**
  * Filter the session's active tool names according to extension/denylist rules.
  *
@@ -68,6 +77,64 @@ export function normalizeMaxTurns(n: number | undefined): number | undefined {
   return Math.max(1, n);
 }
 
+// ── IO boundary ───────────────────────────────────────────────────────────────
+
+/** Minimal resource-loader contract used by the runner. */
+export interface ResourceLoaderLike {
+  reload(): Promise<void>;
+}
+
+/** Minimal session-manager contract used by the runner. */
+export interface SessionManagerLike {
+  newSession(opts: { parentSession?: string }): void;
+  getSessionFile(): string | undefined;
+}
+
+/** Options passed to RunnerIO.createResourceLoader. */
+export interface ResourceLoaderOptions {
+  cwd: string;
+  agentDir: string;
+  noExtensions?: boolean;
+  noSkills?: boolean;
+  noPromptTemplates?: boolean;
+  noThemes?: boolean;
+  noContextFiles?: boolean;
+  systemPromptOverride?: () => string;
+  /** Override the append system prompt. Receives the current base value; return the replacement. */
+  appendSystemPromptOverride?: (base: string[]) => string[];
+}
+
+/** Options passed to RunnerIO.createSession. */
+export interface CreateSessionOptions {
+  cwd: string;
+  agentDir: string;
+  sessionManager: SessionManagerLike;
+  settingsManager: SettingsManager;
+  modelRegistry: unknown;
+  model?: unknown;
+  tools: string[];
+  resourceLoader: ResourceLoaderLike;
+  thinkingLevel?: ThinkingLevel;
+}
+
+/**
+ * IO boundary injected into runAgent().
+ *
+ * Decouples the runner from direct Pi SDK imports and sibling-module IO,
+ * making it testable via plain stub objects without vi.mock().
+ */
+export interface RunnerIO {
+  detectEnv: (exec: ShellExec, cwd: string) => Promise<EnvInfo>;
+  getAgentDir: () => string;
+  createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoaderLike;
+  deriveSessionDir: (parentSessionFile: string | undefined, effectiveCwd: string) => string;
+  createSessionManager: (cwd: string, sessionDir: string) => SessionManagerLike;
+  createSettingsManager: (cwd: string, agentDir: string) => SettingsManager;
+  createSession: (opts: CreateSessionOptions) => Promise<{ session: AgentSession }>;
+  assemblerIO: AssemblerIO;
+}
+
+// ── Public interfaces ─────────────────────────────────────────────────────────
 
 export interface RunOptions {
   /** Shell-exec callback for detectEnv — injected from pi.exec(). */
@@ -125,6 +192,20 @@ export interface AgentRunner {
   resume(session: AgentSession, prompt: string, options?: ResumeOptions): Promise<string>;
 }
 
+/**
+ * Create an AgentRunner backed by the given IO boundary.
+ *
+ * Captures io at construction time so AgentManager remains IO-unaware.
+ */
+export function createAgentRunner(io: RunnerIO): AgentRunner {
+  return {
+    run: (snapshot, type, prompt, options) => runAgent(snapshot, type, prompt, options, io),
+    resume: resumeAgent,
+  };
+}
+
+// ── Private helpers ───────────────────────────────────────────────────────────
+
 /**
  * Subscribe to a session and collect the last assistant message text.
  * Returns an object with a `getText()` getter and an `unsubscribe` function.
@@ -170,23 +251,20 @@ function forwardAbortSignal(
   return () => signal.removeEventListener("abort", onAbort);
 }
 
+// ── Public functions ──────────────────────────────────────────────────────────
+
 export async function runAgent(
   snapshot: ParentSnapshot,
   type: SubagentType,
   prompt: string,
   options: RunOptions,
+  io: RunnerIO,
 ): Promise<RunResult> {
   // Resolve working directory upfront — needed for detectEnv before assembly.
   const effectiveCwd = options.cwd ?? snapshot.cwd;
-  const env = await detectEnv(options.exec, effectiveCwd);
+  const env = await io.detectEnv(options.exec, effectiveCwd);
 
   // Assemble session configuration (synchronous, no SDK objects).
-  const io: AssemblerIO = {
-    preloadSkills,
-    buildMemoryBlock,
-    buildReadOnlyMemoryBlock,
-    buildAgentPrompt,
-  };
   const cfg = assembleSessionConfig(
     type,
     {
@@ -203,10 +281,10 @@ export async function runAgent(
     },
     env,
     options.registry,
-    io,
+    io.assemblerIO,
   );
 
-  const agentDir = getAgentDir();
+  const agentDir = io.getAgentDir();
 
   // Load extensions/skills: true or string[] → load; false → don't.
   // Suppress AGENTS.md/CLAUDE.md and APPEND_SYSTEM.md — upstream's
@@ -214,7 +292,7 @@ export async function runAgent(
   // would defeat prompt_mode: replace and isolated: true. Parent context, if
   // wanted, reaches the subagent via prompt_mode: append (parentSystemPrompt
   // is embedded in systemPromptOverride) or inherit_context (conversation).
-  const loader = new DefaultResourceLoader({
+  const loader = io.createResourceLoader({
     cwd: cfg.effectiveCwd,
     agentDir,
     noExtensions: cfg.extensions === false,
@@ -230,25 +308,21 @@ export async function runAgent(
   // Create a persisted SessionManager so transcripts are written in Pi's
   // official JSONL format. Falls back to a temp directory when the parent
   // session is not persisted (e.g. headless/API mode).
-  const sessionDir = deriveSubagentSessionDir(options.parentSessionFile, cfg.effectiveCwd);
-  const sessionManager = SessionManager.create(cfg.effectiveCwd, sessionDir);
+  const sessionDir = io.deriveSessionDir(options.parentSessionFile, cfg.effectiveCwd);
+  const sessionManager = io.createSessionManager(cfg.effectiveCwd, sessionDir);
   sessionManager.newSession({ parentSession: options.parentSessionId });
 
-  const sessionOpts: Parameters<typeof createAgentSession>[0] = {
+  const { session } = await io.createSession({
     cwd: cfg.effectiveCwd,
     agentDir,
     sessionManager,
-    settingsManager: SettingsManager.create(cfg.effectiveCwd, agentDir),
-    modelRegistry: snapshot.modelRegistry as any,
-    model: cfg.model as Model<any> | undefined,
+    settingsManager: io.createSettingsManager(cfg.effectiveCwd, agentDir),
+    modelRegistry: snapshot.modelRegistry,
+    model: cfg.model,
     tools: cfg.toolNames,
     resourceLoader: loader,
-  };
-  if (cfg.thinkingLevel) {
-    sessionOpts.thinkingLevel = cfg.thinkingLevel;
-  }
-
-  const { session } = await createAgentSession(sessionOpts);
+    thinkingLevel: cfg.thinkingLevel,
+  });
 
   // Filter active tools: remove our own tools to prevent nesting,
   // apply extension allowlist if specified, and apply disallowedTools denylist.
@@ -391,9 +465,7 @@ export function getAgentConversation(session: AgentSession): string {
       for (const c of msg.content) {
         if (c.type === "text" && c.text) textParts.push(c.text);
         else if (c.type === "toolCall")
-          toolCalls.push(
-            `  Tool: ${(c as any).name ?? (c as any).toolName ?? "unknown"}`,
-          );
+          toolCalls.push(`  Tool: ${getToolCallName(c)}`);
       }
       if (textParts.length > 0)
         parts.push(`[Assistant]: ${textParts.join("\n")}`);

package/src/index.ts

@@ -11,19 +11,32 @@
  */
 
 import { join } from "node:path";
-import { defineTool, type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  defineTool,
+  type ExtensionAPI,
+  getAgentDir,
+  SettingsManager as SdkSettingsManager,
+  SessionManager,
+} from "@earendil-works/pi-coding-agent";
 import { AgentManager, type AgentManagerObserver } from "./agent-manager.js";
-import { getAgentConversation, resumeAgent, runAgent, steerAgent } from "./agent-runner.js";
+import { createAgentRunner, getAgentConversation, type RunnerIO, steerAgent } from "./agent-runner.js";
 import { AgentTypeRegistry } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
+import { detectEnv } from "./env.js";
 import { SessionLifecycleHandler, ToolStartHandler } from "./handlers/index.js";
+import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
 import { buildEventData, type NotificationDetails, NotificationManager } from "./notification.js";
+import { buildAgentPrompt } from "./prompts.js";
 import { createNotificationRenderer } from "./renderer.js";
 import { createSubagentRuntime } from "./runtime.js";
 import { publishSubagentsService, unpublishSubagentsService } from "./service.js";
 import { createSubagentsService } from "./service-adapter.js";
+import { deriveSubagentSessionDir } from "./session-dir.js";
 import { SettingsManager } from "./settings.js";
+import { preloadSkills } from "./skill-loader.js";
 import { createAgentTool } from "./tools/agent-tool.js";
 import { createGetResultTool } from "./tools/get-result-tool.js";
 import { getModelLabelFromConfig } from "./tools/helpers.js";
@@ -120,8 +133,24 @@ export default function (pi: ExtensionAPI) {
     },
   };
 
+  const runnerIO: RunnerIO = {
+    detectEnv,
+    getAgentDir,
+    createResourceLoader: (opts) => new DefaultResourceLoader(opts),
+    deriveSessionDir: deriveSubagentSessionDir,
+    createSessionManager: (cwd, dir) => SessionManager.create(cwd, dir),
+    createSettingsManager: (cwd, dir) => SdkSettingsManager.create(cwd, dir),
+    createSession: (opts) => createAgentSession(opts as any),
+    assemblerIO: {
+      preloadSkills,
+      buildMemoryBlock,
+      buildReadOnlyMemoryBlock,
+      buildAgentPrompt,
+    },
+  };
+
   const manager = new AgentManager({
-    runner: { run: runAgent, resume: resumeAgent },
+    runner: createAgentRunner(runnerIO),
     worktrees: new GitWorktreeManager(process.cwd()),
     exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
     registry,

package/src/runtime.ts

@@ -7,7 +7,19 @@
  */
 
 import type { AgentActivityTracker } from "./ui/agent-activity-tracker.js";
-import type { AgentWidget, UICtx } from "./ui/agent-widget.js";
+import type { UICtx } from "./ui/agent-widget.js";
+
+/**
+ * Narrow widget interface consumed by SubagentRuntime delegation methods.
+ * AgentWidget satisfies this structurally; tests use plain stubs.
+ */
+export interface WidgetLike {
+  setUICtx(ctx: UICtx): void;
+  onTurnStart(): void;
+  markFinished(id: string): void;
+  update(): void;
+  ensureTimer(): void;
+}
 
 /**
  * Narrow config subset read by AgentManager when constructing RunOptions.
@@ -37,7 +49,7 @@ export class SubagentRuntime {
    * Persistent widget reference. Null until constructed after AgentManager.
    * Delegation methods use optional chaining so callers never need `widget!`.
    */
-  widget: AgentWidget | null = null;
+  widget: WidgetLike | null = null;
 
   // ── Session-context methods ──────────────────────────────────────────────
 

package/src/tools/agent-tool.ts

@@ -21,7 +21,7 @@ import {
 } from "../ui/agent-widget.js";
 import { spawnBackground } from "./background-spawner.js";
 import { runForeground } from "./foreground-runner.js";
-import { buildDetails, buildTypeListText, formatLifetimeTokens, getStatusNote, textResult } from "./helpers.js";
+import { buildDetails, buildTypeListText, textResult } from "./helpers.js";
 
 // ---- Deps interface ----
 

package/src/tools/helpers.ts

@@ -48,7 +48,7 @@ export function buildDetails(
 
 /** Tool execute return value for a text response. */
 export function textResult(msg: string, details?: unknown) {
-  return { content: [{ type: "text" as const, text: msg }], details: details as any };
+  return { content: [{ type: "text" as const, text: msg }], details };
 }
 
 /** Format an agent's lifetime token total, or "" when zero. */

package/src/ui/conversation-viewer.ts

@@ -14,6 +14,37 @@ import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
 import type { AgentActivityTracker } from "./agent-activity-tracker.js";
 import { buildInvocationTags, describeActivity, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel, type Theme } from "./agent-widget.js";
 
+// ── Local message-shape types ───────────────────────────────────────────────
+// The Pi SDK does not export narrow types for all message content variants.
+// These file-local types document the runtime shapes this module handles.
+
+/** Tool-call content item — SDK exposes this variant at runtime but doesn't export the narrow type. */
+interface ToolCallContent {
+  type: "toolCall";
+  name?: string;
+  toolName?: string;
+}
+
+/** Extracts the tool name from a content item, falling back to 'unknown'. */
+function getToolCallName(c: { type: string }): string {
+  if (c.type !== "toolCall") return "unknown";
+  const tc = c as ToolCallContent;
+  return tc.name ?? tc.toolName ?? "unknown";
+}
+
+/** Bash execution message — 'bashExecution' role is not in the SDK's AgentSession message role union. */
+interface BashExecutionMessage {
+  role: "bashExecution";
+  command: string;
+  output?: string;
+}
+
+function isBashExecution(msg: { role: string }): msg is BashExecutionMessage {
+  return msg.role === "bashExecution";
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
 /** Base lines consumed by chrome: top border + header + header sep + footer sep + footer + bottom border. */
 const CHROME_LINES_BASE = 6;
 const MIN_VIEWPORT = 3;
@@ -228,7 +259,7 @@ export class ConversationViewer implements Component {
         for (const c of msg.content) {
           if (c.type === "text" && c.text) textParts.push(c.text);
           else if (c.type === "toolCall") {
-            toolCalls.push((c as any).name ?? (c as any).toolName ?? "unknown");
+            toolCalls.push(getToolCallName(c));
           }
         }
         if (needsSeparator) lines.push(th.fg("dim", "───"));
@@ -250,14 +281,13 @@ export class ConversationViewer implements Component {
         for (const line of wrapTextWithAnsi(truncated.trim(), width)) {
           lines.push(th.fg("dim", line));
         }
-      } else if ((msg as any).role === "bashExecution") {
-        const bash = msg as any;
+      } else if (isBashExecution(msg)) {
         if (needsSeparator) lines.push(th.fg("dim", "───"));
-        lines.push(truncateToWidth(th.fg("muted", `  $ ${bash.command}`), width));
-        if (bash.output?.trim()) {
-          const out = bash.output.length > 500
-            ? bash.output.slice(0, 500) + "... (truncated)"
-            : bash.output;
+        lines.push(truncateToWidth(th.fg("muted", `  $ ${msg.command}`), width));
+        if (msg.output?.trim()) {
+          const out = msg.output.length > 500
+            ? msg.output.slice(0, 500) + "... (truncated)"
+            : msg.output;
           for (const line of wrapTextWithAnsi(out.trim(), width)) {
             lines.push(th.fg("dim", line));
           }