@gotgenes/pi-subagents 13.0.0 → 13.1.0

package/src/lifecycle/create-subagent-session.ts

@@ -0,0 +1,242 @@
+/**
+ * create-subagent-session.ts — Assembly factory for born-complete child sessions (issue #265).
+ *
+ * `createSubagentSession()` does the assembly portion that the old runner's
+ * `runAgent()` did up front: detect the environment, assemble the session config,
+ * create the SDK session, publish `spawning`/`session-created`, bind extensions,
+ * and apply the recursion guard. It returns a fully usable `SubagentSession` —
+ * `Agent` then only coordinates (turn loop, steer, dispose).
+ *
+ * The factory takes a resolved `cwd` value, never the WorkspaceProvider: `cwd`
+ * is a value the factory consumes directly (detectEnv, assembleSessionConfig,
+ * createSession), so threading the provider through here would be a relay smell.
+ */
+
+import type { Model } from "@earendil-works/pi-ai";
+import {
+  type AgentSession,
+  type SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import type { AgentConfigLookup } from "#src/config/agent-types";
+import type { ChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
+import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import { SubagentSession } from "#src/lifecycle/subagent-session";
+import type { EnvInfo } from "#src/session/env";
+import { type AssemblerIO, assembleSessionConfig } from "#src/session/session-config";
+import type { ParentSessionInfo, ShellExec, SubagentType, ThinkingLevel } from "#src/types";
+
+/** Names of tools registered by this extension that subagents must NOT inherit. */
+const EXCLUDED_TOOL_NAMES = ["subagent", "get_subagent_result", "steer_subagent"];
+
+/**
+ * Apply the recursion guard: remove this extension's dispatch tools from the
+ * child's active set. Runs after `bindExtensions` so extension-registered tools
+ * are also covered. Unconditional: children always load the parent's extensions.
+ */
+function applyRecursionGuard(session: AgentSession): void {
+  const filtered = session
+    .getActiveToolNames()
+    .filter((t) => !EXCLUDED_TOOL_NAMES.includes(t));
+  session.setActiveToolsByName(filtered);
+}
+
+// ── IO boundary ───────────────────────────────────────────────────────────────
+
+/** Minimal resource-loader contract used by the factory. */
+export interface ResourceLoaderLike {
+  reload(): Promise<void>;
+}
+
+/** Minimal session-manager contract used by the factory. */
+export interface SessionManagerLike {
+  newSession(opts: { parentSession?: string }): void;
+  getSessionFile(): string | undefined;
+}
+
+/** Options passed to EnvironmentIO/SessionFactoryIO methods. */
+export interface ResourceLoaderOptions {
+  cwd: string;
+  agentDir: string;
+  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 SessionFactoryIO.createSession. */
+export interface CreateSessionOptions {
+  cwd: string;
+  agentDir: string;
+  sessionManager: SessionManagerLike;
+  settingsManager: SettingsManager;
+  modelRegistry: unknown;
+  model?: unknown;
+  tools: string[];
+  resourceLoader: ResourceLoaderLike;
+  thinkingLevel?: ThinkingLevel;
+}
+
+/**
+ * Environment discovery - detect runtime context and resolve directories.
+ *
+ * Decouples the factory from direct process/SDK reads so each can be stubbed
+ * independently in tests.
+ */
+export interface EnvironmentIO {
+  detectEnv: (exec: ShellExec, cwd: string) => Promise<EnvInfo>;
+  getAgentDir: () => string;
+  deriveSessionDir: (parentSessionFile: string | undefined, effectiveCwd: string) => string;
+}
+
+/**
+ * Session factory - create SDK objects for a child agent session.
+ *
+ * Decouples the factory from direct Pi SDK imports and sibling-module IO,
+ * making it testable via plain stub objects without vi.mock().
+ */
+export interface SessionFactoryIO {
+  createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoaderLike;
+  createSessionManager: (cwd: string, sessionDir: string) => SessionManagerLike;
+  createSettingsManager: (cwd: string, agentDir: string) => SettingsManager;
+  createSession: (opts: CreateSessionOptions) => Promise<{ session: AgentSession }>;
+  assemblerIO: AssemblerIO;
+}
+
+/**
+ * IO boundary injected into createSubagentSession().
+ *
+ * Intersection of EnvironmentIO and SessionFactoryIO — callers satisfy both
+ * sub-interfaces via TypeScript's structural typing.
+ */
+export type SubagentSessionIO = EnvironmentIO & SessionFactoryIO;
+
+/**
+ * Dependencies injected at construction time — the IO boundary plus the two
+ * static domain deps (exec, registry) every creation needs.
+ */
+export interface SubagentSessionDeps {
+  io: SubagentSessionIO;
+  exec: ShellExec;
+  registry: AgentConfigLookup;
+  /** Publishes the child-execution lifecycle so consumers can observe it. */
+  lifecycle: ChildLifecyclePublisher;
+}
+
+/** Per-spawn parameters — the fields that vary per child session. */
+export interface CreateSubagentSessionParams {
+  snapshot: ParentSnapshot;
+  type: SubagentType;
+  /** Resolved workspace cwd; undefined → parent cwd. */
+  cwd?: string;
+  /** Parent session identity (file path + session ID). */
+  parentSession?: ParentSessionInfo;
+  model?: Model<any>;
+  thinkingLevel?: ThinkingLevel;
+}
+
+/**
+ * Build a born-complete SubagentSession: assemble config, create the SDK
+ * session, publish lifecycle events, bind extensions, apply the recursion guard.
+ */
+export async function createSubagentSession(
+  params: CreateSubagentSessionParams,
+  deps: SubagentSessionDeps,
+): Promise<SubagentSession> {
+  const { snapshot, type } = params;
+  const parentSessionId = params.parentSession?.parentSessionId;
+  deps.lifecycle.spawning({ agentName: type, parentSessionId });
+
+  // Resolve working directory upfront - needed for detectEnv before assembly.
+  const effectiveCwd = params.cwd ?? snapshot.cwd;
+  const env = await deps.io.detectEnv(deps.exec, effectiveCwd);
+
+  // Assemble session configuration (synchronous, no SDK objects).
+  const cfg = assembleSessionConfig(
+    type,
+    {
+      cwd: snapshot.cwd,
+      parentSystemPrompt: snapshot.systemPrompt,
+      parentModel: snapshot.model,
+      modelRegistry: snapshot.modelRegistry,
+    },
+    {
+      cwd: params.cwd,
+      model: params.model,
+      thinkingLevel: params.thinkingLevel,
+    },
+    env,
+    deps.registry,
+    deps.io.assemblerIO,
+  );
+
+  const agentDir = deps.io.getAgentDir();
+
+  // Children always load the parent's extensions and skills.
+  // Suppress AGENTS.md/CLAUDE.md and APPEND_SYSTEM.md - upstream's
+  // buildSystemPrompt() re-appends both AFTER systemPromptOverride, which
+  // would defeat prompt_mode: replace. Parent context, if wanted, reaches the
+  // subagent via prompt_mode: append (parentSystemPrompt is embedded in
+  // systemPromptOverride) or inherit_context (conversation).
+  const loader = deps.io.createResourceLoader({
+    cwd: cfg.effectiveCwd,
+    agentDir,
+    noPromptTemplates: true,
+    noThemes: true,
+    noContextFiles: true,
+    systemPromptOverride: () => cfg.systemPrompt,
+    appendSystemPromptOverride: () => [],
+  });
+  await loader.reload();
+
+  // 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 = deps.io.deriveSessionDir(params.parentSession?.parentSessionFile, cfg.effectiveCwd);
+  const sessionManager = deps.io.createSessionManager(cfg.effectiveCwd, sessionDir);
+  sessionManager.newSession({ parentSession: params.parentSession?.parentSessionId });
+
+  const { session } = await deps.io.createSession({
+    cwd: cfg.effectiveCwd,
+    agentDir,
+    sessionManager,
+    settingsManager: deps.io.createSettingsManager(cfg.effectiveCwd, agentDir),
+    modelRegistry: snapshot.modelRegistry,
+    model: cfg.model,
+    tools: cfg.toolNames,
+    resourceLoader: loader,
+    thinkingLevel: cfg.thinkingLevel,
+  });
+
+  const subagentSession = new SubagentSession(session, {
+    outputFile: sessionManager.getSessionFile(),
+    sessionDir,
+    agentName: type,
+    agentMaxTurns: cfg.agentMaxTurns,
+    parentContext: snapshot.parentContext,
+    lifecycle: deps.lifecycle,
+  });
+
+  // Publish session-created before bindExtensions() so observers (e.g. the
+  // permission system) can register the child synchronously and have their
+  // entry in place for the first permission check during child extension
+  // initialization. The event bus dispatches synchronously, so a synchronous
+  // subscriber completes before this returns.
+  deps.lifecycle.sessionCreated({ sessionDir, agentName: type, parentSessionId });
+
+  try {
+    // Bind extensions so that session_start fires and extensions can initialize.
+    await session.bindExtensions({});
+    // Apply recursion guard after bindExtensions so extension-registered tools
+    // are included in the post-bind active set.
+    applyRecursionGuard(session);
+  } catch (err) {
+    // Binding failed after session-created — dispose (emit disposed +
+    // session.dispose()) before rethrowing so registration is never leaked.
+    subagentSession.dispose();
+    throw err;
+  }
+
+  return subagentSession;
+}

package/src/lifecycle/subagent-session.ts

@@ -0,0 +1,204 @@
+/**
+ * subagent-session.ts — The born-complete child-session value object (issue #265).
+ *
+ * A SubagentSession wraps one SDK AgentSession plus its turn-driving and teardown.
+ * It is born complete: `createSubagentSession()` returns a fully usable instance
+ * (session created, extensions bound, recursion guard applied), so the only thing
+ * left for `Agent` to do is coordinate — drive the turn loop, steer, dispose.
+ *
+ * Turn driving lives here, on the object that owns the AgentSession, rather than
+ * reaching through `subagentSession.session` from `Agent` (Law of Demeter).
+ */
+
+import {
+  type AgentSession,
+  type AgentSessionEvent,
+} from "@earendil-works/pi-coding-agent";
+import type { ChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
+import { normalizeMaxTurns } from "#src/lifecycle/turn-limits";
+import { extractText } from "#src/session/context";
+
+/** Outcome of one turn loop. */
+export interface TurnLoopResult {
+  responseText: string;
+  /** True if the agent was hard-aborted (max turns + grace exceeded). */
+  aborted: boolean;
+  /** True if the agent was steered to wrap up (soft turn limit) but finished in time. */
+  steered: boolean;
+}
+
+/** Per-call options for the initial run's turn loop. */
+export interface TurnLoopOptions {
+  /** Per-call max-turns override — highest precedence. */
+  maxTurns?: number;
+  /** Runtime-config fallback when neither per-call nor per-agent limit is set. */
+  defaultMaxTurns?: number;
+  /** Grace turns after the soft-limit steer message before a hard abort. */
+  graceTurns?: number;
+  signal?: AbortSignal;
+}
+
+/** Session-level facts known at creation, supplied by the factory. */
+export interface SubagentSessionMeta {
+  /** Path to the persisted session JSONL file, if the session was persisted. */
+  outputFile: string | undefined;
+  /** Child session directory — the registry key carried on lifecycle events. */
+  sessionDir: string;
+  agentName: string;
+  /** Per-agent max-turns from the resolved agent config — middle precedence. */
+  agentMaxTurns: number | undefined;
+  /** Parent context prepended to the run prompt, captured at spawn time. */
+  parentContext: string | undefined;
+  lifecycle: ChildLifecyclePublisher;
+}
+
+/**
+ * One child AgentSession plus its turn-driving and teardown — born complete.
+ */
+export class SubagentSession {
+  constructor(
+    private readonly _session: AgentSession,
+    private readonly meta: SubagentSessionMeta,
+  ) {}
+
+  /** Wrapped session — exposed for observer wiring + consumers; retired by #277. */
+  get session(): AgentSession {
+    return this._session;
+  }
+
+  get outputFile(): string | undefined {
+    return this.meta.outputFile;
+  }
+
+  /** Drive the initial run's turn loop; emits `completed` on success. */
+  async runTurnLoop(prompt: string, opts: TurnLoopOptions): Promise<TurnLoopResult> {
+    const session = this._session;
+
+    // Track turns for graceful max_turns enforcement.
+    let turnCount = 0;
+    const maxTurns = normalizeMaxTurns(
+      opts.maxTurns ?? this.meta.agentMaxTurns ?? opts.defaultMaxTurns,
+    );
+    let softLimitReached = false;
+    let aborted = false;
+
+    const unsubTurns = session.subscribe((event: AgentSessionEvent) => {
+      if (event.type === "turn_end") {
+        turnCount++;
+        if (maxTurns != null) {
+          if (!softLimitReached && turnCount >= maxTurns) {
+            softLimitReached = true;
+            void session.steer(
+              "You have reached your turn limit. Wrap up immediately - provide your final answer now.",
+            );
+          } else if (softLimitReached && turnCount >= maxTurns + (opts.graceTurns ?? 5)) {
+            aborted = true;
+            void session.abort();
+          }
+        }
+      }
+    });
+
+    const collector = collectResponseText(session);
+    const cleanupAbort = forwardAbortSignal(session, opts.signal);
+
+    // Prepend parent context if it was captured at spawn time.
+    const effectivePrompt = this.meta.parentContext
+      ? this.meta.parentContext + prompt
+      : prompt;
+
+    try {
+      await session.prompt(effectivePrompt);
+      this.meta.lifecycle.completed({
+        sessionDir: this.meta.sessionDir,
+        agentName: this.meta.agentName,
+        aborted,
+        steered: softLimitReached,
+      });
+    } finally {
+      unsubTurns();
+      collector.unsubscribe();
+      cleanupAbort();
+    }
+
+    const responseText = collector.getText().trim() || getLastAssistantText(session);
+    return { responseText, aborted, steered: softLimitReached };
+  }
+
+  /** Re-prompt the same session (resume); does not emit `completed`. */
+  async resumeTurnLoop(prompt: string, signal?: AbortSignal): Promise<string> {
+    const session = this._session;
+    const collector = collectResponseText(session);
+    const cleanupAbort = forwardAbortSignal(session, signal);
+
+    try {
+      await session.prompt(prompt);
+    } finally {
+      collector.unsubscribe();
+      cleanupAbort();
+    }
+
+    return collector.getText().trim() || getLastAssistantText(session);
+  }
+
+  /** Deliver a steer to the live session. */
+  async steer(message: string): Promise<void> {
+    await this._session.steer(message);
+  }
+
+  /** Tear down: session.dispose() + emit `disposed` (registry unregister). */
+  dispose(): void {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose may not exist on all session implementations
+    this._session.dispose?.();
+    this.meta.lifecycle.disposed({ sessionDir: this.meta.sessionDir });
+  }
+}
+
+// ── Private turn-loop helpers ───────────────────────────────────────────────────
+
+/**
+ * Subscribe to a session and collect the last assistant message text.
+ * Returns an object with a `getText()` getter and an `unsubscribe` function.
+ */
+function collectResponseText(session: AgentSession) {
+  let text = "";
+  const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+    if (event.type === "message_start") {
+      text = "";
+    }
+    if (
+      event.type === "message_update" &&
+      event.assistantMessageEvent.type === "text_delta"
+    ) {
+      text += event.assistantMessageEvent.delta;
+    }
+  });
+  return { getText: () => text, unsubscribe };
+}
+
+/** Get the last assistant text from the completed session history. */
+function getLastAssistantText(session: AgentSession): string {
+  for (let i = session.messages.length - 1; i >= 0; i--) {
+    const msg = session.messages[i];
+    if (msg.role !== "assistant") continue;
+    const text = extractText(msg.content).trim();
+    if (text) return text;
+  }
+  return "";
+}
+
+/**
+ * Wire an AbortSignal to abort a session.
+ * Returns a cleanup function to remove the listener.
+ */
+function forwardAbortSignal(
+  session: AgentSession,
+  signal?: AbortSignal,
+): () => void {
+  if (!signal) return () => {};
+  const onAbort = (): void => {
+    void session.abort();
+  };
+  signal.addEventListener("abort", onAbort, { once: true });
+  return () => signal.removeEventListener("abort", onAbort);
+}

package/src/lifecycle/turn-limits.ts

@@ -0,0 +1,13 @@
+/**
+ * turn-limits.ts — Pure turn-limit normalization for subagent execution.
+ *
+ * Extracted from agent-runner.ts (issue #265) so the turn-counting policy has a
+ * focused home independent of session assembly. Consumed by the Agent tool's
+ * spawn-config resolution and by the turn loop in SubagentSession.
+ */
+
+/** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
+export function normalizeMaxTurns(n: number | undefined): number | undefined {
+  if (n == null || n === 0) return undefined;
+  return Math.max(1, n);
+}

package/src/runtime.ts

@@ -25,7 +25,7 @@ export interface WidgetLike {
 }
 
 /**
- * Narrow config subset read by AgentManager when constructing RunOptions execution fields.
+ * Narrow config subset read by Agent when driving the turn loop (defaultMaxTurns, graceTurns).
  * Kept separate so callers can satisfy it without depending on the full runtime.
  */
 export interface RunConfig {

package/src/session/conversation.ts

@@ -0,0 +1,49 @@
+/**
+ * conversation.ts — Render a subagent session's messages as formatted text.
+ *
+ * Extracted from agent-runner.ts (issue #265) into the session domain, where the
+ * other message-extraction helpers (content-items, context) live. Consumed by
+ * the get_subagent_result tool's verbose output.
+ */
+
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import { extractAssistantContent } from "#src/session/content-items";
+import { extractText } from "#src/session/context";
+
+/**
+ * Get the subagent's conversation messages as formatted text.
+ */
+export function getAgentConversation(session: AgentSession): string {
+  const parts: string[] = [];
+
+  for (const msg of session.messages) {
+    if (msg.role === "user") {
+      const text =
+        typeof msg.content === "string"
+          ? msg.content
+          : extractText(msg.content);
+      if (text.trim()) parts.push(`[User]: ${text.trim()}`);
+    } else if (msg.role === "assistant") {
+      const { textParts, toolNames } = extractAssistantContent(msg.content);
+      const attribution = formatAttribution(msg);
+      if (textParts.length > 0)
+        parts.push(`[Assistant${attribution}]: ${textParts.join("\n")}`);
+      if (toolNames.length > 0)
+        parts.push(`[Tool Calls]:\n${toolNames.map((n) => `  Tool: ${n}`).join("\n")}`);
+    } else if (msg.role === "toolResult") {
+      const text = extractText(msg.content);
+      const truncated = text.length > 200 ? text.slice(0, 200) + "..." : text;
+      parts.push(`[Tool Result (${msg.toolName})]: ${truncated}`);
+    }
+  }
+
+  return parts.join("\n\n");
+}
+
+/** Build a `(provider/model)` attribution suffix for assistant messages. */
+function formatAttribution(msg: { provider?: string; model?: string }): string {
+  const { provider, model } = msg;
+  if (!provider && !model) return "";
+  if (provider && model) return ` (${provider}/${model})`;
+  return ` (${provider ?? model})`;
+}

package/src/session/session-config.ts

@@ -1,10 +1,10 @@
 /**
  * session-config.ts — Pure configuration assembler for agent sessions.
  *
- * `assembleSessionConfig()` is the pure core extracted from `runAgent()`.
- * It accepts resolved inputs (agent type, narrow context, run options, env info)
- * and returns everything `runAgent()` needs to create the SDK session — without
- * importing or constructing any Pi SDK types.
+ * `assembleSessionConfig()` is the pure assembly core called by
+ * `createSubagentSession()`. It accepts resolved inputs (agent type, narrow
+ * context, run options, env info) and returns everything the factory needs to
+ * create the SDK session — without importing or constructing any Pi SDK types.
  *
  * The only async IO in the assembly phase (`detectEnv`) is handled by the caller
  * before invoking this function, keeping the assembler synchronous.
@@ -22,7 +22,7 @@ import type { AgentPromptConfig, SubagentType, ThinkingLevel } from "#src/types"
  * Bundling the IO-touching (or promptly testable) function into a single
  * interface keeps the assembler free of direct module imports and makes it
  * trivially testable without `vi.mock()` — callers inject real implementations
- * at the edge (`agent-runner.ts`) or stubs in tests.
+ * at the edge (`create-subagent-session.ts`) or stubs in tests.
  */
 export interface AssemblerIO {
   buildAgentPrompt: (
@@ -57,7 +57,7 @@ export interface AssemblerContext {
 }
 
 /**
- * Narrow slice of RunOptions execution fields consumed by the assembler.
+ * Narrow slice of per-spawn execution fields consumed by the assembler.
  * All fields are optional — callers pass only what they have.
  */
 export interface AssemblerOptions {
@@ -70,7 +70,7 @@ export interface AssemblerOptions {
 }
 
 /**
- * Assembled configuration returned to `runAgent()`.
+ * Assembled configuration returned to `createSubagentSession()`.
  * Contains everything needed to create the SDK session and filter tools —
  * with no SDK object references.
  */
@@ -173,7 +173,7 @@ export function assembleSessionConfig(
   // Thinking level: explicit option > agent config > undefined (inherit)
   const thinkingLevel = options.thinkingLevel ?? agentConfig.thinking;
 
-  // Per-agent max turns (combined with options.maxTurns and defaultMaxTurns by runAgent)
+  // Per-agent max turns (combined with per-call maxTurns and defaultMaxTurns by SubagentSession.runTurnLoop)
   const agentMaxTurns = agentConfig.maxTurns;
 
   return {

package/src/settings.ts

@@ -8,7 +8,7 @@ export interface SubagentsSettings {
   maxConcurrent?: number;
   /**
    * 0 = unlimited — the extension's single source of truth for that convention:
-   * `normalizeMaxTurns()` in agent-runner.ts treats 0 → `undefined`, and the
+   * `normalizeMaxTurns()` in turn-limits.ts treats 0 → `undefined`, and the
    * `/agents` → Settings input prompt explicitly says "0 = unlimited".
    */
   defaultMaxTurns?: number;

package/src/tools/get-result-tool.ts

@@ -1,8 +1,8 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import type { AgentConfigLookup } from "#src/config/agent-types";
-import { getAgentConversation } from "#src/lifecycle/agent-runner";
 import { getSessionContextPercent } from "#src/lifecycle/usage";
+import { getAgentConversation } from "#src/session/conversation";
 import { formatLifetimeTokens, textResult } from "#src/tools/helpers";
 import type { Agent } from "#src/types";
 import { formatDuration, getDisplayName } from "#src/ui/display";

package/src/tools/spawn-config.ts

@@ -10,7 +10,7 @@
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentTypeRegistry } from "#src/config/agent-types";
 import { resolveAgentInvocationConfig } from "#src/config/invocation-config";
-import { normalizeMaxTurns } from "#src/lifecycle/agent-runner";
+import { normalizeMaxTurns } from "#src/lifecycle/turn-limits";
 import { resolveInvocationModel } from "#src/session/model-resolver";
 import type { AgentInvocation, SubagentType, ThinkingLevel } from "#src/types";
 import {