@gotgenes/pi-subagents 12.1.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/service/service-adapter.ts

@@ -66,7 +66,6 @@ export class SubagentsServiceAdapter implements SubagentsService {
       model,
       maxTurns: options?.maxTurns,
       thinkingLevel: options?.thinkingLevel,
-      isolated: options?.isolated,
       inheritContext: options?.inheritContext,
       bypassQueue: options?.bypassQueue,
       isBackground,

package/src/service/service.ts

@@ -61,7 +61,6 @@ export interface SpawnOptions {
   model?: string;
   maxTurns?: number;
   thinkingLevel?: string;
-  isolated?: boolean;
   inheritContext?: boolean;
   foreground?: boolean;
   bypassQueue?: boolean;

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/prompts.ts

@@ -5,12 +5,6 @@
 import type { EnvInfo } from "#src/session/env";
 import type { AgentPromptConfig } from "#src/types";
 
-/** Extra sections to inject into the system prompt (skills, etc.). */
-export interface PromptExtras {
-  /** Preloaded skill contents to inject. */
-  skillBlocks?: { name: string; content: string }[];
-}
-
 /**
  * Build the system prompt for an agent from its config.
  *
@@ -25,14 +19,12 @@ export interface PromptExtras {
  * inherited content so the stable prefix is cacheable by the LLM's KV cache.
  *
  * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
- * @param extras  Optional extra sections to inject (memory, preloaded skills).
  */
 export function buildAgentPrompt(
   config: AgentPromptConfig,
   cwd: string,
   env: EnvInfo,
   parentSystemPrompt?: string,
-  extras?: PromptExtras,
 ): string {
   const activeAgentTag = `<active_agent name="${config.name}"/>\n\n`;
 
@@ -41,18 +33,6 @@ Working directory: ${cwd}
 ${env.isGitRepo ? `Git repository: yes\nBranch: ${env.branch}` : "Not a git repository"}
 Platform: ${env.platform}`;
 
-  // Build optional extras suffix
-  const extraSections: string[] = [];
-  if (extras?.skillBlocks?.length) {
-    for (const skill of extras.skillBlocks) {
-      extraSections.push(
-        `\n# Preloaded Skill: ${skill.name}\n${skill.content}`,
-      );
-    }
-  }
-  const extrasSuffix =
-    extraSections.length > 0 ? "\n\n" + extraSections.join("\n") : "";
-
   if (config.promptMode === "append") {
     const identity = parentSystemPrompt ?? genericBase;
 
@@ -85,8 +65,7 @@ You are operating as a sub-agent invoked to handle a specific task.
       "\n\n" +
       activeAgentTag +
       envBlock +
-      customSection +
-      extrasSuffix
+      customSection
     );
   }
 
@@ -97,7 +76,7 @@ You have been invoked to handle a specific task autonomously.
 ${envBlock}`;
 
   return (
-    activeAgentTag + replaceHeader + "\n\n" + config.systemPrompt + extrasSuffix
+    activeAgentTag + replaceHeader + "\n\n" + config.systemPrompt
   );
 }