@yefengr/pi-subagents 0.0.0-stage → 0.1.0

package/src/config/custom-agents.ts

@@ -0,0 +1,114 @@
+/**
+ * custom-agents.ts — Load user-defined agents from project (.pi/agents/) and global ($PI_CODING_AGENT_DIR/agents/, default ~/.pi/agent/agents/) locations.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { BUILTIN_TOOL_NAMES } from "#src/config/agent-types";
+import { debugLog } from "#src/debug";
+import type { AgentConfig, ThinkingLevel } from "#src/types";
+
+/**
+ * Scan for custom agent .md files from multiple locations.
+ * Discovery hierarchy (higher priority wins):
+ *   1. Project: <cwd>/.pi/agents/*.md
+ *   2. Global:  $PI_CODING_AGENT_DIR/agents/*.md (default: ~/.pi/agent/agents/*.md)
+ *
+ * Project-level agents override global ones with the same name.
+ * Any name is allowed — names matching defaults (e.g. "Explore") override them.
+ */
+export function loadCustomAgents(cwd: string): Map<string, AgentConfig> {
+  const globalDir = join(getAgentDir(), "agents");
+  const projectDir = join(cwd, ".pi", "agents");
+
+  const agents = new Map<string, AgentConfig>();
+  loadFromDir(globalDir, agents, "global");   // lower priority
+  loadFromDir(projectDir, agents, "project");  // higher priority (overwrites)
+  return agents;
+}
+
+/** Load agent configs from a directory into the map. */
+function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "project" | "global"): void {
+  if (!existsSync(dir)) return;
+
+  let files: string[];
+  try {
+    files = readdirSync(dir).filter(f => f.endsWith(".md"));
+  } catch (err) {
+    debugLog("readdirSync agents dir", err);
+    return;
+  }
+
+  for (const file of files) {
+    const name = basename(file, ".md");
+
+    let content: string;
+    try {
+      content = readFileSync(join(dir, file), "utf-8");
+    } catch (err) {
+      debugLog("readFileSync agent file", err);
+      continue;
+    }
+
+    const { frontmatter: fm, body } = parseFrontmatter(content);
+
+    agents.set(name, {
+      name,
+      displayName: str(fm.display_name),
+      description: str(fm.description) ?? name,
+      toolNames: listField(fm.tools, BUILTIN_TOOL_NAMES),
+      model: str(fm.model),
+      thinking: str(fm.thinking) as ThinkingLevel | undefined,
+      maxTurns: intAtLeast(fm.max_turns, 1),
+      wrapUpTurns: intAtLeast(fm.wrap_up_turns, 0),
+      maxDurationSeconds: intAtLeast(fm.max_duration_seconds, 1),
+      systemPrompt: body.trim(),
+      promptMode: fm.prompt_mode === "replace" ? "replace" : "append",
+      inheritContext: fm.inherit_context != null ? fm.inherit_context === true : undefined,
+      runInBackground: fm.run_in_background != null ? fm.run_in_background === true : undefined,
+      source,
+      filePath: join(dir, file),
+    });
+  }
+}
+
+// ---- Field parsers ----
+// All follow the same convention: omitted → default, "none"/empty → nothing, value → exact.
+
+/** Extract a string or undefined. */
+function str(val: unknown): string | undefined {
+  return typeof val === "string" ? val : undefined;
+}
+
+/** Extract an integer at or above `min`, or undefined. 0 is not a special value. */
+function intAtLeast(val: unknown, min: number): number | undefined {
+  return typeof val === "number" && Number.isInteger(val) && val >= min ? val : undefined;
+}
+
+/**
+ * Parse a raw list field into items, or undefined if absent/empty/"none".
+ *
+ * Frontmatter is YAML, so a list field is written either as a comma-separated
+ * scalar (`tools: read, grep`) or as a sequence (`tools: [read, grep]`). Both
+ * are supported: a sequence keeps its entries intact, while a scalar is split
+ * on commas.
+ */
+function parseListField(val: unknown): string[] | undefined {
+  if (val === undefined || val === null) return undefined;
+  const items = Array.isArray(val)
+    ? val.map(entry => String(entry).trim()).filter(Boolean)
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string -- val is already narrowed past null/undefined; String() is the intended coercion here
+    : String(val).trim().split(",").map(entry => entry.trim()).filter(Boolean);
+  if (items.length === 0) return undefined;
+  return items.length === 1 && items[0] === "none" ? undefined : items;
+}
+
+/**
+ * Parse a list field with defaults.
+ * omitted → defaults; "none"/empty → []; otherwise → listed items.
+ */
+function listField(val: unknown, defaults: string[]): string[] {
+  if (val === undefined || val === null) return defaults;
+  return parseListField(val) ?? [];
+}

package/src/config/default-agents.ts

@@ -0,0 +1,120 @@
+/**
+ * default-agents.ts — Embedded default agent configurations.
+ *
+ * These are always available but can be overridden by user .md files with the same name.
+ */
+
+import type { AgentConfig } from "#src/types";
+
+const READ_ONLY_TOOLS = ["read", "bash", "grep", "find", "ls"];
+
+export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
+  [
+    "general-purpose",
+    {
+      name: "general-purpose",
+      displayName: "Agent",
+      description: "General-purpose agent for complex, multi-step tasks",
+      toolGuideline: "- Use general-purpose for complex tasks that need file editing.",
+      // toolNames omitted — means "all available tools" (resolved at lookup time)
+      // inheritContext / runInBackground omitted — strategy fields, callers decide per-call.
+      // Setting them to false would lock callsite intent (see resolveAgentInvocationConfig in invocation-config.ts).
+      systemPrompt: "",
+      promptMode: "append",
+      isDefault: true,
+    },
+  ],
+  [
+    "Explore",
+    {
+      name: "Explore",
+      displayName: "Explore",
+      description: "Fast codebase exploration agent (read-only)",
+      toolGuideline: "- Use Explore for codebase searches and code understanding.",
+      toolNames: READ_ONLY_TOOLS,
+      model: "anthropic/claude-haiku-4-5-20251001",
+      systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
+You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools.
+
+You are STRICTLY PROHIBITED from:
+- Creating new files
+- Modifying existing files
+- Deleting files
+- Moving or copying files
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Use Bash ONLY for read-only operations: ls, git status, git log, git diff, find, cat, head, tail.
+
+# Tool Usage
+- Use the find tool for file pattern matching (NOT the bash find command)
+- Use the grep tool for content search (NOT bash grep/rg command)
+- Use the read tool for reading files (NOT bash cat/head/tail)
+- Use Bash ONLY for read-only operations
+- Make independent tool calls in parallel for efficiency
+- Adapt search approach based on thoroughness level specified
+
+# Output
+- Use absolute file paths in all references
+- Report findings as regular messages
+- Do not use emojis
+- Be thorough and precise`,
+      promptMode: "replace",
+      isDefault: true,
+    },
+  ],
+  [
+    "Plan",
+    {
+      name: "Plan",
+      displayName: "Plan",
+      description: "Software architect for implementation planning (read-only)",
+      toolGuideline: "- Use Plan for architecture and implementation planning.",
+      toolNames: READ_ONLY_TOOLS,
+      systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
+You are a software architect and planning specialist.
+Your role is EXCLUSIVELY to explore the codebase and design implementation plans.
+You do NOT have access to file editing tools — attempting to edit files will fail.
+
+You are STRICTLY PROHIBITED from:
+- Creating new files
+- Modifying existing files
+- Deleting files
+- Moving or copying files
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+# Planning Process
+1. Understand requirements
+2. Explore thoroughly (read files, find patterns, understand architecture)
+3. Design solution based on your assigned perspective
+4. Detail the plan with step-by-step implementation strategy
+
+# Requirements
+- Consider trade-offs and architectural decisions
+- Identify dependencies and sequencing
+- Anticipate potential challenges
+- Follow existing patterns where appropriate
+
+# Tool Usage
+- Use the find tool for file pattern matching (NOT the bash find command)
+- Use the grep tool for content search (NOT bash grep/rg command)
+- Use the read tool for reading files (NOT bash cat/head/tail)
+- Use Bash ONLY for read-only operations
+
+# Output Format
+- Use absolute file paths
+- Do not use emojis
+- End your response with:
+
+### Critical Files for Implementation
+List 3-5 files most critical for implementing this plan:
+- /absolute/path/to/file.ts - [Brief reason]`,
+      promptMode: "replace",
+      isDefault: true,
+    },
+  ],
+]);

package/src/config/invocation-config.ts

@@ -0,0 +1,39 @@
+import { minPositive } from "#src/config/resource-limits";
+import type { AgentConfig, ThinkingLevel } from "#src/types";
+
+interface AgentInvocationParams {
+  model?: string;
+  thinking?: string;
+  max_turns?: number;
+  wrap_up_turns?: number;
+  max_duration_seconds?: number;
+  run_in_background?: boolean;
+  inherit_context?: boolean;
+}
+
+export function resolveAgentInvocationConfig(
+  agentConfig: AgentConfig | undefined,
+  params: AgentInvocationParams,
+): {
+  modelInput?: string;
+  modelFromParams: boolean;
+  thinking?: ThinkingLevel;
+  maxTurns?: number;
+  wrapUpTurns?: number;
+  maxDurationSeconds?: number;
+  inheritContext: boolean;
+  runInBackground: boolean;
+} {
+  return {
+    modelInput: agentConfig?.model ?? params.model,
+    modelFromParams: agentConfig?.model == null && params.model != null,
+    thinking: (agentConfig?.thinking ?? params.thinking) as ThinkingLevel | undefined,
+    // Turn and duration budgets may only tighten: when both the profile and the
+    // tool call define one, the smaller value wins rather than the profile value.
+    maxTurns: minPositive(agentConfig?.maxTurns, params.max_turns),
+    wrapUpTurns: params.wrap_up_turns ?? agentConfig?.wrapUpTurns,
+    maxDurationSeconds: minPositive(agentConfig?.maxDurationSeconds, params.max_duration_seconds),
+    inheritContext: agentConfig?.inheritContext ?? params.inherit_context ?? false,
+    runInBackground: agentConfig?.runInBackground ?? params.run_in_background ?? false,
+  };
+}

package/src/config/resource-limits.ts

@@ -0,0 +1,26 @@
+/**
+ * resource-limits.ts — Pure merge helpers for layered runtime budgets.
+ *
+ * maxTurns and maxDurationSeconds may only tighten as they flow from global
+ * settings through the agent profile to the tool call, so the effective value
+ * is the minimum of every defined layer. wrapUpTurns instead follows fixed
+ * precedence (invocation > profile > global) and is then clamped below the
+ * effective turn budget.
+ */
+
+/** Smallest positive candidate; undefined when no candidate is a positive number. */
+export function minPositive(...values: Array<number | undefined>): number | undefined {
+  let min: number | undefined;
+  for (const value of values) {
+    if (value == null || !Number.isFinite(value) || value < 1) continue;
+    if (min === undefined || value < min) min = value;
+  }
+  return min;
+}
+
+/** Clamp a wrap-up turn budget to the [0, maxTurns - 1] window. */
+export function clampWrapUpTurns(wrapUpTurns: number, maxTurns: number): number {
+  const ceiling = Math.max(0, Math.floor(maxTurns) - 1);
+  const floor = Math.max(0, Math.floor(wrapUpTurns));
+  return Math.min(floor, ceiling);
+}

package/src/config/settings-file.ts

@@ -0,0 +1,174 @@
+import { randomUUID } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+const LOCK_STALE_MS = 5 * 60 * 1000;
+
+export type JsonObject = Record<string, unknown>;
+
+/** Read a JSON object from disk. A missing file is reported as undefined. */
+export function readSettingsFile(path: string): JsonObject | undefined {
+  try {
+    return parseJsonObject(readFileSync(path, "utf-8"), path);
+  } catch (error) {
+    if (isMissingFileError(error)) return undefined;
+    throw error;
+  }
+}
+
+/**
+ * Atomically update one JSON settings file while preserving unrelated keys.
+ * The updater runs after acquiring the lock and re-reading the current file.
+ */
+export function updateSettingsFile(path: string, update: (current: JsonObject) => JsonObject): void {
+  mkdirSync(dirname(path), { recursive: true });
+
+  const targetPath = resolveWriteTarget(path);
+  const lockPath = `${targetPath}.lock`;
+  let lockFd: number | undefined;
+  let tempPath: string | undefined;
+
+  try {
+    lockFd = acquireLock(lockPath);
+    const current = readSettingsFile(targetPath) ?? {};
+    const next = update(current);
+    if (!isJsonObject(next)) {
+      throw new TypeError("Settings file updates must produce a JSON object");
+    }
+
+    const mode = existingMode(targetPath);
+    tempPath = join(dirname(targetPath), `.${basename(targetPath)}.tmp-${process.pid}-${randomUUID()}`);
+    writeTempFile(tempPath, `${JSON.stringify(next, null, 2)}\n`, mode);
+    renameSync(tempPath, targetPath);
+    tempPath = undefined;
+  } finally {
+    if (tempPath) rmSync(tempPath, { force: true });
+    if (lockFd !== undefined) {
+      closeSync(lockFd);
+      rmSync(lockPath, { force: true });
+    }
+  }
+}
+
+function acquireLock(lockPath: string): number {
+  try {
+    return createLock(lockPath);
+  } catch (error) {
+    if (!isExistingFileError(error) || !recoverStaleLock(lockPath)) throw error;
+    return createLock(lockPath);
+  }
+}
+
+function createLock(lockPath: string): number {
+  const fd = openSync(lockPath, "wx", 0o600);
+  try {
+    writeFileSync(fd, `${process.pid}\\n`, "utf-8");
+    return fd;
+  } catch (error) {
+    closeSync(fd);
+    rmSync(lockPath, { force: true });
+    throw error;
+  }
+}
+
+function recoverStaleLock(lockPath: string): boolean {
+  let before: ReturnType<typeof statSync>;
+  try {
+    before = statSync(lockPath);
+  } catch {
+    return false;
+  }
+  if (Date.now() - before.mtimeMs < LOCK_STALE_MS) return false;
+
+  const content = readFileSync(lockPath, "utf-8").trim();
+  const pid = Number.parseInt(content, 10);
+  if (Number.isInteger(pid) && pid > 0) {
+    try {
+      process.kill(pid, 0);
+      return false;
+    } catch (error) {
+      if (!isMissingProcessError(error)) return false;
+    }
+  }
+
+  let after: ReturnType<typeof statSync>;
+  try {
+    after = statSync(lockPath);
+  } catch {
+    return false;
+  }
+  if (after.mtimeMs !== before.mtimeMs || after.size !== before.size) return false;
+  rmSync(lockPath);
+  return true;
+}
+
+function isExistingFileError(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
+}
+
+function isMissingProcessError(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ESRCH";
+}
+
+function parseJsonObject(content: string, path: string): JsonObject {
+  const parsed: unknown = JSON.parse(content);
+  if (!isJsonObject(parsed)) {
+    throw new TypeError(`Settings file at ${path} must contain a JSON object`);
+  }
+  return parsed;
+}
+
+function isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isMissingFileError(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+
+function resolveWriteTarget(path: string): string {
+  let entry: ReturnType<typeof lstatSync> | undefined;
+  try {
+    entry = lstatSync(path);
+  } catch (error) {
+    if (!isMissingFileError(error)) throw error;
+  }
+
+  // A dangling symlink is an existing link and must never be replaced.
+  if (entry?.isSymbolicLink()) return realpathSync(path);
+
+  // Canonicalizing the parent also makes aliases through ancestor symlinks
+  // share one lock and ensures a new file is created beside the real parent.
+  return join(realpathSync(dirname(path)), basename(path));
+}
+
+function existingMode(path: string): number {
+  try {
+    return statSync(path).mode & 0o777;
+  } catch (error) {
+    if (isMissingFileError(error)) return 0o600;
+    throw error;
+  }
+}
+
+function writeTempFile(path: string, content: string, mode: number): void {
+  const fd = openSync(path, "wx", mode);
+  try {
+    writeFileSync(fd, content, "utf-8");
+    chmodSync(path, mode);
+  } finally {
+    closeSync(fd);
+  }
+}

package/src/debug.ts

@@ -0,0 +1,14 @@
+/**
+ * debug.ts — Debug logging utility for silenced catch blocks.
+ *
+ * Set PI_SUBAGENTS_DEBUG=1 to reveal silent failures in catch blocks
+ * throughout the package. Production behavior is unchanged when unset.
+ */
+
+export function isDebug(): boolean {
+  return process.env.PI_SUBAGENTS_DEBUG === "1";
+}
+
+export function debugLog(context: string, err: unknown): void {
+  if (isDebug()) console.warn(`[pi-subagents:debug] ${context}:`, err);
+}

package/src/handlers/index.ts

@@ -0,0 +1,3 @@
+export { InterruptHandler } from "#src/handlers/interrupt";
+export { SessionLifecycleHandler } from "#src/handlers/lifecycle";
+export { ToolStartHandler } from "#src/handlers/tool-start";

package/src/handlers/interrupt.ts

@@ -0,0 +1,58 @@
+/**
+ * turn_start event handler that aborts subagents on a parent interrupt (ESC),
+ * subject to the abort-all policy.
+ *
+ * The parent agent loop creates a fresh AbortController per run and only aborts
+ * it on an explicit interrupt — never on normal completion. So latching to the
+ * current run's signal and aborting on its `abort` event fires exactly on ESC.
+ *
+ * `turn_start` carries the live per-run `ctx.signal`, so re-latching each turn
+ * keeps the handler tracking the current signal across runs and tool-less turns.
+ */
+
+/** Narrow manager interface — only the method the interrupt handler calls. */
+export interface InterruptManager {
+  abortAll(): number;
+}
+
+/** Minimal context shape — only the field the handler reads. */
+interface InterruptCtx {
+  signal: AbortSignal | undefined;
+}
+
+/**
+ * Latches the current parent abort signal and aborts all subagents when it fires,
+ * unless `shouldAbortAll` declines.
+ *
+ * The latch dedups by reference: most turns reuse the same signal (no-op); a new
+ * run's signal triggers a detach-and-rewire. The `abort` listener is one-shot.
+ *
+ * `shouldAbortAll` is consulted inside the listener, so a mid-session settings
+ * change applies to the very next interrupt without re-wiring.
+ */
+export class InterruptHandler {
+  private latched?: AbortSignal;
+  private detach?: () => void;
+
+  constructor(
+    private readonly manager: InterruptManager,
+    private readonly shouldAbortAll: () => boolean,
+  ) {}
+
+  handleTurnStart(ctx: InterruptCtx): void {
+    const signal = ctx.signal;
+    if (signal === this.latched) return;
+
+    this.detach?.();
+    this.detach = undefined;
+    this.latched = signal;
+    if (!signal) return;
+
+    const onAbort = (): void => {
+      if (!this.shouldAbortAll()) return;
+      this.manager.abortAll();
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    this.detach = () => signal.removeEventListener("abort", onAbort);
+  }
+}

package/src/handlers/lifecycle.ts

@@ -0,0 +1,65 @@
+import type { SessionContext } from "#src/types";
+
+/**
+ * Session lifecycle event handlers: session_start, session_before_switch, session_shutdown.
+ *
+ * Extracted from index.ts so each handler can be tested in isolation
+ * with mocked narrow interfaces.
+ */
+
+/** Narrow manager interface — only the methods lifecycle handlers call. */
+export interface LifecycleManager {
+  clearCompleted(): Promise<void>;
+  abortAll(): void;
+  dispose(): Promise<void>;
+}
+
+/** Narrow runtime interface — only the methods lifecycle handlers call. */
+export interface LifecycleRuntime {
+  setSessionContext(ctx: SessionContext): void;
+  clearSessionContext(): void;
+}
+
+/**
+ * Handles session lifecycle events.
+ *
+ * Constructor deps:
+ * - `runtime` — owns session context state
+ * - `manager` — manages agent lifecycle (clear, abort, dispose)
+ * - `disposeNotifications` — tears down the notification system on shutdown
+ * - `unpublishService` — unpublishes the SubagentsService symbol on shutdown
+ */
+export class SessionLifecycleHandler {
+  constructor(
+    private readonly runtime: LifecycleRuntime,
+    private readonly manager: LifecycleManager,
+    private readonly disposeNotifications: () => void,
+    private readonly unpublishService: () => void,
+  ) {}
+
+  handleSessionStart(_event: unknown, ctx: unknown): Promise<void> {
+    this.runtime.setSessionContext(ctx as SessionContext);
+    return this.manager.clearCompleted();
+  }
+
+  handleSessionBeforeSwitch(): Promise<void> {
+    return this.manager.clearCompleted();
+  }
+
+  // Cleanup order matters:
+  // 1. Unpublish service — prevent new cross-extension calls
+  // 2. Clear session context — no more session state
+  // 3. Dispose notifications — silence nudges *before* the aborts that would
+  //    raise them: no parent run is active at shutdown, so a terminal
+  //    transition delivers its nudge synchronously and Pi cannot recall it
+  // 4. Abort all agents — stop running and queued work
+  // 5. Dispose manager — final cleanup, awaited so each child's extensions get
+  //    their `session_shutdown` before Pi tears the parent down (#709)
+  handleSessionShutdown(): Promise<void> {
+    this.unpublishService();
+    this.runtime.clearSessionContext();
+    this.disposeNotifications();
+    this.manager.abortAll();
+    return this.manager.dispose();
+  }
+}

package/src/handlers/tool-start.ts

@@ -0,0 +1,32 @@
+/**
+ * tool_execution_start event handler.
+ *
+ * Extracted from index.ts so the handler can be tested in isolation
+ * with a mocked narrow runtime interface.
+ */
+
+/** Narrow widget interface — only the methods the handler calls. */
+export interface ToolStartWidget {
+  setUICtx(ctx: unknown): void;
+  onTurnStart(): void;
+}
+
+/** Minimal context shape for tool_execution_start — only the field the handler reads. */
+interface ToolStartCtx {
+  ui: unknown;
+}
+
+/**
+ * Handles tool_execution_start events.
+ *
+ * Grabs UI context from the first tool execution of each turn
+ * and signals the widget to clear lingering state.
+ */
+export class ToolStartHandler {
+  constructor(private readonly widget: ToolStartWidget) {}
+
+  handleToolExecutionStart(_event: unknown, ctx: ToolStartCtx): void {
+    this.widget.setUICtx(ctx.ui);
+    this.widget.onTurnStart();
+  }
+}