@gotgenes/pi-subagents 12.1.0 → 13.1.0

package/src/lifecycle/agent-runner.ts

@@ -1,472 +0,0 @@
-/**
- * agent-runner.ts - Core execution engine: creates sessions, runs agents, collects results.
- */
-
-import type { Model } from "@earendil-works/pi-ai";
-import {
-  type AgentSession,
-  type AgentSessionEvent,
-  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 { extractAssistantContent } from "#src/session/content-items";
-import { extractText } from "#src/session/context";
-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"];
-
-/**
- * Filter the session's active tool names: remove recursion-guard tools.
- *
- * Run once after `bindExtensions` so extension-registered tools (added during
- * `bindExtensions`) are also covered by the guard.
- *
- * @param activeTools  Names currently active on the session.
- */
-function filterActiveTools(activeTools: string[]): string[] {
-  return activeTools.filter((t) => !EXCLUDED_TOOL_NAMES.includes(t));
-}
-
-/** 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);
-}
-
-// ── 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 EnvironmentIO/SessionFactoryIO methods. */
-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 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 runner 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 runner 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 runAgent().
- *
- * Backward-compatible intersection of EnvironmentIO and SessionFactoryIO.
- * Callers that previously constructed a RunnerIO object continue to satisfy
- * both sub-interfaces via TypeScript's structural typing.
- */
-export type RunnerIO = EnvironmentIO & SessionFactoryIO;
-
-/**
- * Dependencies owned by the runner — injected at construction time.
- *
- * Groups the IO boundary with the two static domain deps (exec, registry)
- * that every run() call needs but that do not vary per call.
- */
-export interface RunnerDeps {
-  io: RunnerIO;
-  exec: ShellExec;
-  registry: AgentConfigLookup;
-  /** Publishes the child-execution lifecycle so consumers can observe it. */
-  lifecycle: ChildLifecyclePublisher;
-}
-
-// ── Public interfaces ─────────────────────────────────────────────────────────
-
-/**
- * Per-call execution context — fields that vary per spawn.
- *
- * Static dependencies (exec, registry) live on RunnerDeps; this interface
- * carries only the two per-call fields that AgentManager supplies at spawn time.
- */
-export interface RunContext {
-  /** Override working directory (e.g. for worktree isolation). */
-  cwd?: string;
-  /** Parent session identity (file path + session ID). */
-  parentSession?: ParentSessionInfo;
-}
-
-export interface RunOptions {
-  /** Parent execution context - where/who is running. */
-  context: RunContext;
-  model?: Model<any>;
-  maxTurns?: number;
-  signal?: AbortSignal;
-  isolated?: boolean;
-  thinkingLevel?: ThinkingLevel;
-  /** Called once after session creation - session delivery mechanism. */
-  onSessionCreated?: (session: AgentSession) => void;
-  /**
-   * Default max turns from runtime config. Falls back to the module-scope
-   * `defaultMaxTurns` during the lift-and-shift migration; superseded by
-   * per-call `maxTurns` and per-agent `agentConfig.maxTurns`.
-   */
-  defaultMaxTurns?: number;
-  /**
-   * Grace turns after the soft-limit steer message. Falls back to the
-   * module-scope `graceTurns` during migration.
-   */
-  graceTurns?: number;
-}
-
-export interface RunResult {
-  responseText: string;
-  session: AgentSession;
-  /** True if the agent was hard-aborted (max_turns + grace exceeded). */
-  aborted: boolean;
-  /** True if the agent was steered to wrap up (hit soft turn limit) but finished in time. */
-  steered: boolean;
-  /** Path to the persisted session JSONL file, if the session was persisted. */
-  sessionFile?: string;
-}
-
-/** Options for resuming an existing agent session. */
-export interface ResumeOptions {
-  signal?: AbortSignal;
-}
-
-/**
- * Execution boundary: decouples AgentManager (lifecycle management) from the
- * SDK session orchestration in runAgent/resumeAgent.
- */
-export interface AgentRunner {
-  run(snapshot: ParentSnapshot, type: SubagentType, prompt: string, options: RunOptions): Promise<RunResult>;
-  resume(session: AgentSession, prompt: string, options?: ResumeOptions): Promise<string>;
-}
-
-/**
- * Concrete AgentRunner backed by RunnerDeps.
- *
- * Captures IO, exec, and registry at construction time so AgentManager
- * remains unaware of runner-internal dependencies.
- */
-export class ConcreteAgentRunner implements AgentRunner {
-  constructor(private readonly deps: RunnerDeps) {}
-
-  run(snapshot: ParentSnapshot, type: SubagentType, prompt: string, options: RunOptions): Promise<RunResult> {
-    return runAgent(snapshot, type, prompt, options, this.deps);
-  }
-
-  resume(session: AgentSession, prompt: string, options?: ResumeOptions): Promise<string> {
-    return resumeAgent(session, prompt, options);
-  }
-}
-
-
-// ── Private 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);
-}
-
-// ── Public functions ──────────────────────────────────────────────────────────
-
-export async function runAgent(
-  snapshot: ParentSnapshot,
-  type: SubagentType,
-  prompt: string,
-  options: RunOptions,
-  deps: RunnerDeps,
-): Promise<RunResult> {
-  const parentSessionId = options.context.parentSession?.parentSessionId;
-  deps.lifecycle.spawning({ agentName: type, parentSessionId });
-
-  // Resolve working directory upfront - needed for detectEnv before assembly.
-  const effectiveCwd = options.context.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: options.context.cwd,
-      isolated: options.isolated,
-      model: options.model,
-      thinkingLevel: options.thinkingLevel,
-    },
-    env,
-    deps.registry,
-    deps.io.assemblerIO,
-  );
-
-  const agentDir = deps.io.getAgentDir();
-
-  // Load extensions/skills: true → load; false → don't.
-  // Suppress AGENTS.md/CLAUDE.md and APPEND_SYSTEM.md - upstream's
-  // buildSystemPrompt() re-appends both AFTER systemPromptOverride, which
-  // 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 = deps.io.createResourceLoader({
-    cwd: cfg.effectiveCwd,
-    agentDir,
-    noExtensions: !cfg.extensions,
-    noSkills: cfg.noSkills,
-    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(options.context.parentSession?.parentSessionFile, cfg.effectiveCwd);
-  const sessionManager = deps.io.createSessionManager(cfg.effectiveCwd, sessionDir);
-  sessionManager.newSession({ parentSession: options.context.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,
-  });
-
-  // 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. Paired with disposed() in the
-  // finally block below to guarantee cleanup on both success and error paths.
-  deps.lifecycle.sessionCreated({ sessionDir, agentName: type, parentSessionId });
-
-  // Bind extensions so that session_start fires and extensions can initialize
-  // (e.g. loading credentials, setting up state). Placed after tool filtering
-  // so extension-provided skills/prompts from extendResourcesFromExtensions()
-  // respect the active tool set. All ExtensionBindings fields are optional.
-  await session.bindExtensions({});
-
-  // Apply recursion guard: remove our own tools from the child's active set.
-  // Runs after bindExtensions so extension-registered tools are included in the
-  // post-bind active set. Only needed when extensions are loaded (extensions: false
-  // means no extension tools were registered, so the guard is a no-op).
-  if (cfg.extensions) {
-    const filtered = filterActiveTools(session.getActiveToolNames());
-    session.setActiveToolsByName(filtered);
-  }
-
-  options.onSessionCreated?.(session);
-
-  // Track turns for graceful max_turns enforcement
-  let turnCount = 0;
-  const maxTurns = normalizeMaxTurns(
-    options.maxTurns ?? cfg.agentMaxTurns ?? options.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 + (options.graceTurns ?? 5)) {
-          aborted = true;
-          void session.abort();
-        }
-      }
-    }
-  });
-
-  const collector = collectResponseText(session);
-  const cleanupAbort = forwardAbortSignal(session, options.signal);
-
-  // Prepend parent context if it was captured at spawn time
-  let effectivePrompt = prompt;
-  if (snapshot.parentContext) {
-    effectivePrompt = snapshot.parentContext + prompt;
-  }
-
-  try {
-    await session.prompt(effectivePrompt);
-    deps.lifecycle.completed({ sessionDir, agentName: type, aborted, steered: softLimitReached });
-  } finally {
-    unsubTurns();
-    collector.unsubscribe();
-    cleanupAbort();
-    deps.lifecycle.disposed({ sessionDir });
-  }
-
-  const responseText =
-    collector.getText().trim() || getLastAssistantText(session);
-  return {
-    responseText,
-    session,
-    aborted,
-    steered: softLimitReached,
-    sessionFile: sessionManager.getSessionFile(),
-  };
-}
-
-/**
- * Send a new prompt to an existing session (resume).
- */
-export async function resumeAgent(
-  session: AgentSession,
-  prompt: string,
-  options: ResumeOptions = {},
-): Promise<string> {
-  const collector = collectResponseText(session);
-  const cleanupAbort = forwardAbortSignal(session, options.signal);
-
-  try {
-    await session.prompt(prompt);
-  } finally {
-    collector.unsubscribe();
-    cleanupAbort();
-  }
-
-  return collector.getText().trim() || getLastAssistantText(session);
-}
-
-/**
- * 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/lifecycle/execution-state.ts

@@ -1,17 +0,0 @@
-/**
- * execution-state.ts — ExecutionState: execution-phase state for a running agent.
- *
- * Constructed and attached to Agent when onSessionCreated fires inside startAgent().
- * Contains the session and output file — the two fields that become known once the
- * runner creates the session. promise stays as a separate Agent field because
- * it is set at a different moment (after runner.run() returns).
- */
-
-import type { AgentSession } from "@earendil-works/pi-coding-agent";
-
-export interface ExecutionState {
-	/** The active agent session — available from the moment the session is created. */
-	readonly session: AgentSession;
-	/** Path to the agent's session JSONL file, or undefined if not yet available. */
-	readonly outputFile: string | undefined;
-}

package/src/session/safe-fs.ts

@@ -1,45 +0,0 @@
-/**
- * safe-fs.ts — Filesystem safety utilities for reading untrusted paths.
- *
- * Used by skill-loader.ts to reject symlinks and path-traversal names
- * before reading skill files from disk.
- */
-
-import { existsSync, lstatSync, readFileSync } from "node:fs";
-import { debugLog } from "#src/debug";
-
-/**
- * Returns true if a name contains characters not allowed in agent/skill names.
- * Uses a whitelist: only alphanumeric, hyphens, underscores, and dots (no leading dot).
- */
-export function isUnsafeName(name: string): boolean {
-  if (!name || name.length > 128) return true;
-  return !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name);
-}
-
-/**
- * Returns true if the given path is a symlink (defense against symlink attacks).
- */
-export function isSymlink(filePath: string): boolean {
-  try {
-    return lstatSync(filePath).isSymbolicLink();
-  } catch (err) {
-    debugLog("lstatSync", err);
-    return false;
-  }
-}
-
-/**
- * Safely read a file, rejecting symlinks.
- * Returns undefined if the file doesn't exist, is a symlink, or can't be read.
- */
-export function safeReadFile(filePath: string): string | undefined {
-  if (!existsSync(filePath)) return undefined;
-  if (isSymlink(filePath)) return undefined;
-  try {
-    return readFileSync(filePath, "utf-8");
-  } catch (err) {
-    debugLog("readFileSync", err);
-    return undefined;
-  }
-}

package/src/session/skill-loader.ts

@@ -1,104 +0,0 @@
-/**
- * skill-loader.ts — Preload named skills.
- *
- * Roots, in precedence order:
- *   - <cwd>/.pi/skills           (project, Pi's standard)
- *   - <cwd>/.agents/skills       (project, cross-tool Agent Skills spec — https://agentskills.io)
- *   - getAgentDir()/skills       (user, default ~/.pi/agent/skills — Pi's standard)
- *   - ~/.agents/skills           (user, cross-tool Agent Skills spec)
- *   - ~/.pi/skills               (legacy global, pre-Pi)
- *
- * Layout per root:
- *   - <root>/<name>.md            (flat file at the top level)
- *   - <root>/.../<name>/SKILL.md  (directory skill, may be nested — Pi's standard)
- *
- * Recursion skips dotfile entries and node_modules. A directory that itself contains
- * SKILL.md is a skill — we don't descend into it (Pi: skills don't nest).
- *
- * Symlinks are rejected for security (deviation from Pi, which follows them).
- */
-
-import type { Dirent } from "node:fs";
-import { existsSync, readdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { debugLog } from "#src/debug";
-import { isSymlink, isUnsafeName, safeReadFile } from "#src/session/safe-fs";
-
-export interface PreloadedSkill {
-  name: string;
-  content: string;
-}
-
-export function preloadSkills(skillNames: string[], cwd: string): PreloadedSkill[] {
-  return skillNames.map((name) => ({ name, content: loadSkillContent(name, cwd) }));
-}
-
-function loadSkillContent(name: string, cwd: string): string {
-  if (isUnsafeName(name)) {
-    return `(Skill "${name}" skipped: name contains path traversal characters)`;
-  }
-  const roots = [
-    join(cwd, ".pi", "skills"), // project — Pi standard
-    join(cwd, ".agents", "skills"), // project — Agent Skills spec
-    join(getAgentDir(), "skills"), // user — Pi standard
-    join(homedir(), ".agents", "skills"), // user — Agent Skills spec
-    join(homedir(), ".pi", "skills"), // legacy global, pre-Pi
-  ];
-  for (const root of roots) {
-    const content = findInRoot(root, name);
-    if (content !== undefined) return content;
-  }
-  return `(Skill "${name}" not found in .pi/skills/, .agents/skills/, or global skill locations)`;
-}
-
-function findInRoot(root: string, name: string): string | undefined {
-  if (isSymlink(root)) return undefined; // reject symlinked roots entirely
-  const flat = safeReadFile(join(root, `${name}.md`))?.trim();
-  if (flat !== undefined) return flat;
-  return findSkillDirectory(root, name);
-}
-
-/** BFS under `root` for a directory named `name` containing `SKILL.md`. Pi-conforming filters. */
-function findSkillDirectory(root: string, name: string): string | undefined {
-  if (!existsSync(root)) return undefined;
-  const queue: string[] = [root];
-
-  while (queue.length > 0) {
-    const current = queue.shift();
-    if (current === undefined) continue;
-
-    let entries: Dirent[];
-    try {
-      entries = readdirSync(current, { withFileTypes: true });
-    } catch (err) {
-      debugLog("readdirSync skill root", err);
-      continue;
-    }
-
-    // Deterministic byte-order traversal — locale-independent.
-    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
-
-      // Symlinked dirs already filtered by entry.isDirectory() — Dirent uses lstat semantics.
-      const path = join(current, entry.name);
-      const skillMd = join(path, "SKILL.md");
-      const isSkillDir = existsSync(skillMd);
-
-      if (isSkillDir) {
-        if (entry.name === name) {
-          const content = safeReadFile(skillMd)?.trim();
-          if (content !== undefined) return content;
-        }
-        continue; // Pi rule: skills don't nest — don't descend into a skill dir
-      }
-
-      queue.push(path);
-    }
-  }
-  return undefined;
-}