@jopqior/pi-subagents 1.0.0

package/src/config/agent-types.ts

@@ -0,0 +1,135 @@
+/**
+ * agent-types.ts — Unified agent type registry.
+ *
+ * Merges embedded default agents with user-defined agents from .pi/agents/*.md.
+ * User agents override defaults with the same name. Disabled agents are kept but excluded from spawning.
+ */
+
+import { DEFAULT_AGENTS } from "#src/config/default-agents";
+import type { AgentConfig } from "#src/types";
+
+// ── AgentConfigLookup interface ──────────────────────────────────────────────
+
+/**
+ * Narrow registry interface for consumers that only need config resolution.
+ * Prefer this over the full `AgentTypeRegistry` in function signatures (ISP).
+ */
+export interface AgentConfigLookup {
+  resolveAgentConfig(type: string): AgentConfig;
+  getToolNamesForType(type: string): string[];
+}
+
+// ── AgentTypeRegistry class ──────────────────────────────────────────────────
+
+/**
+ * Injectable registry of all agent configurations (defaults + user-defined).
+ *
+ * Replaces the module-scoped `agents` Map and its companion free functions.
+ * The constructor accepts a `loadUserAgents` callback to defer disk I/O to the
+ * call site, keeping this class side-effect-free and easy to test.
+ */
+export class AgentTypeRegistry implements AgentConfigLookup {
+  private agents = new Map<string, AgentConfig>();
+
+  /** The three embedded default agent names. */
+  static readonly DEFAULT_AGENT_NAMES = ["general-purpose", "Explore", "Plan"] as const;
+
+  constructor(private loadUserAgents: () => Map<string, AgentConfig>) {
+    this.reload();
+  }
+
+  /**
+   * Re-scan user agents and rebuild the registry.
+   * Starts with DEFAULT_AGENTS, then overlays whatever `loadUserAgents()` returns.
+   */
+  reload(): void {
+    this.agents.clear();
+    for (const [name, config] of DEFAULT_AGENTS) {
+      this.agents.set(name, config);
+    }
+    for (const [name, config] of this.loadUserAgents()) {
+      this.agents.set(name, config);
+    }
+  }
+
+  /** Resolve a type name case-insensitively. Returns the canonical key or undefined. */
+  resolveType(name: string): string | undefined {
+    return this.resolveKey(name);
+  }
+
+  /** Get all enabled type names (for spawning and tool descriptions). */
+  getAvailableTypes(): string[] {
+    return [...this.agents.entries()]
+      .filter(([_, config]) => config.enabled !== false)
+      .map(([name]) => name);
+  }
+
+  /** Get all type names including disabled (for UI listing). */
+  getAllTypes(): string[] {
+    return [...this.agents.keys()];
+  }
+
+  /** Get names of default agents currently in the registry. */
+  getDefaultAgentNames(): string[] {
+    return [...this.agents.entries()]
+      .filter(([_, config]) => config.isDefault === true)
+      .map(([name]) => name);
+  }
+
+  /** Get names of user-defined agents (non-defaults) currently in the registry. */
+  getUserAgentNames(): string[] {
+    return [...this.agents.entries()]
+      .filter(([_, config]) => config.isDefault !== true)
+      .map(([name]) => name);
+  }
+
+  /** Check if a type is valid and enabled (case-insensitive). */
+  isValidType(type: string): boolean {
+    const key = this.resolveKey(type);
+    if (!key) return false;
+    return this.agents.get(key)?.enabled !== false;
+  }
+
+  /**
+   * Get the capability tool names for a type (case-insensitive).
+   *
+   * An agent that declares no `tools:` key gets the built-ins; one that declares
+   * `tools: none` gets nothing. Resolution goes through `resolveAgentConfig` so
+   * the two cannot disagree about which config a type names.
+   */
+  getToolNamesForType(type: string): string[] {
+    return this.resolveAgentConfig(type).toolNames ?? [...BUILTIN_TOOL_NAMES];
+  }
+
+  /** Resolve agent config with guaranteed non-null return. Falls back: unknown → general-purpose → absolute fallback. */
+  resolveAgentConfig(type: string): AgentConfig {
+    const key = this.resolveKey(type);
+    const config = key ? this.agents.get(key) : undefined;
+    if (config) return config;
+
+    const gp = this.agents.get("general-purpose");
+    if (gp) return gp;
+
+    // Absolute fallback (should never happen in practice)
+    return {
+      name: type,
+      displayName: "Agent",
+      description: "General-purpose agent for complex, multi-step tasks",
+      toolNames: BUILTIN_TOOL_NAMES,
+      systemPrompt: "",
+      promptMode: "append",
+    };
+  }
+
+  private resolveKey(name: string): string | undefined {
+    if (this.agents.has(name)) return name;
+    const lower = name.toLowerCase();
+    for (const key of this.agents.keys()) {
+      if (key.toLowerCase() === lower) return key;
+    }
+    return undefined;
+  }
+}
+
+/** All known built-in tool names. */
+export const BUILTIN_TOOL_NAMES: string[] = ["read", "bash", "edit", "write", "grep", "find", "ls"];

package/src/config/custom-agents.ts

@@ -0,0 +1,151 @@
+/**
+ * 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 { isLockableField, type LockDeclaration } from "#src/config/invocation-config";
+import { parseThinkingLevel, thinkingLevelError } from "#src/config/thinking-level";
+import { debugLog } from "#src/debug";
+import type { AgentConfig } 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: thinkingLevel(fm.thinking, name),
+      maxTurns: nonNegativeInt(fm.max_turns),
+      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,
+      locked: lockDeclaration(fm.locked, name),
+      enabled: fm.enabled !== false,  // default true; explicitly false disables
+      source,
+    });
+  }
+}
+
+// ---- 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;
+}
+
+/**
+ * Parse the `locked:` key into a lock declaration, or undefined when it claims nothing.
+ *
+ * `true` is the whole-file form; anything else parses as a field list, so both YAML
+ * spellings `tools:` accepts work here too. An entry naming no lockable field is
+ * dropped rather than failing the agent's load.
+ */
+function lockDeclaration(val: unknown, agentName: string): LockDeclaration | undefined {
+  if (typeof val === "boolean") return val ? true : undefined;
+
+  const entries = parseListField(val);
+  if (entries === undefined) return undefined;
+
+  const fields = entries.filter(isLockableField);
+  const unknownEntries = entries.filter((entry) => !isLockableField(entry));
+  if (unknownEntries.length > 0) {
+    debugLog(`agent ${agentName} frontmatter locked`, `unknown fields: ${unknownEntries.join(", ")}`);
+  }
+  return fields.length > 0 ? fields : undefined;
+}
+
+/**
+ * Extract a thinking level, dropping an unrecognized one.
+ *
+ * Passing it through would not surface as an error: Pi clamps a level missing from
+ * its own table down to `off`, silently disabling thinking for an agent whose author
+ * asked for more of it. Inheriting the parent's level is the safer miss (Refs #834).
+ */
+function thinkingLevel(val: unknown, agentName: string): AgentConfig["thinking"] {
+  const level = parseThinkingLevel(val);
+  if (val != null && level === undefined) {
+    debugLog(`agent ${agentName} frontmatter thinking`, thinkingLevelError(val));
+  }
+  return level;
+}
+
+/** Extract a non-negative integer or undefined. 0 means unlimited for max_turns. */
+function nonNegativeInt(val: unknown): number | undefined {
+  return typeof val === "number" && val >= 0 ? 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,121 @@
+/**
+ * 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.
+      // No built-in declares `locked`: Explore's haiku is a cost default, not a
+      // correctness one, so a caller that knows better may override it (#829).
+      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,167 @@
+import type { AgentConfig, ThinkingLevel } from "#src/types";
+
+/**
+ * The fields a `subagent` tool caller may pass, spelled as the frontmatter key an
+ * agent author writes rather than the camelCase `AgentConfig` property.
+ */
+export const LOCKABLE_FIELDS = [
+  "model",
+  "thinking",
+  "max_turns",
+  "inherit_context",
+  "run_in_background",
+] as const;
+
+/** One field an agent file may withhold from its callers. */
+export type LockableField = (typeof LOCKABLE_FIELDS)[number];
+
+/**
+ * An agent file's claim over the fields a caller may not override.
+ *
+ * `true` locks every field the file sets, which is the pre-#829 blanket behavior. A
+ * list locks exactly the fields it names, whether or not the file supplies a value —
+ * so an author can deny an override without pinning one.
+ */
+export type LockDeclaration = true | readonly LockableField[];
+
+/** True when `name` is a field an agent file may lock. */
+export function isLockableField(name: string): name is LockableField {
+  return (LOCKABLE_FIELDS as readonly string[]).includes(name);
+}
+
+/**
+ * A front door's answer to "should this agent run in the background?".
+ *
+ * `explicit` is a commitment the door has already acted on — the foreground
+ * runner holds the result promise, or the tool door merged frontmatter itself
+ * and routed on the answer. `default` is a door with no commitment, so the
+ * agent's own `runInBackground` frontmatter fills it.
+ */
+export type BackgroundRequest =
+	| { kind: "explicit"; isBackground: boolean }
+	| { kind: "default"; isBackground: boolean };
+
+/** Resolve the effective background mode. Explicit answers are honored verbatim. */
+export function resolveBackgroundMode(
+	agentConfig: Pick<AgentConfig, "runInBackground">,
+	request: BackgroundRequest,
+): boolean {
+	return request.kind === "explicit"
+		? request.isBackground
+		: (agentConfig.runInBackground ?? request.isBackground);
+}
+
+interface AgentInvocationParams {
+  model?: string;
+  /** Already validated by the door — see `parseThinkingLevel`. */
+  thinking?: ThinkingLevel;
+  max_turns?: number;
+  run_in_background?: boolean;
+  inherit_context?: boolean;
+}
+
+/** The per-call values the Agent tool door resolved from its caller and the agent file. */
+export interface AgentInvocationConfig {
+  modelInput?: string;
+  /**
+   * True when the winning model string came from the caller.
+   *
+   * Decides whether an unresolvable string surfaces as an error or falls back to the
+   * parent model silently: the caller is present to read an error, an agent file's
+   * author is not.
+   */
+  modelFromParams: boolean;
+  thinking?: ThinkingLevel;
+  maxTurns?: number;
+  inheritContext: boolean;
+  runInBackground: boolean;
+  /**
+   * Locked fields whose caller value was thrown away, in `LOCKABLE_FIELDS` order.
+   *
+   * A caller that passed the agent's own value discarded nothing and is absent here.
+   */
+  discarded: LockableField[];
+}
+
+/**
+ * Merge an agent file's frontmatter with the `subagent` tool call's parameters.
+ *
+ * The caller wins by default and the agent file fills what the caller left unset. The
+ * upstream guard this inverts existed because the *model* guesses harness knobs it does
+ * not understand — an agent author who wants that guard back declares `locked:`, which
+ * is the only case where a caller's value is discarded (Refs #829).
+ */
+export function resolveAgentInvocationConfig(
+  agentConfig: AgentConfig,
+  params: AgentInvocationParams,
+): AgentInvocationConfig {
+  const locked = agentConfig.locked;
+  const model = resolveField("model", agentConfig.model, params.model, locked);
+  const thinking = resolveField("thinking", agentConfig.thinking, params.thinking, locked);
+  const maxTurns = resolveField("max_turns", agentConfig.maxTurns, params.max_turns, locked);
+  const inheritContext = resolveField(
+    "inherit_context",
+    agentConfig.inheritContext,
+    params.inherit_context,
+    locked,
+  );
+  const runInBackground = resolveField(
+    "run_in_background",
+    agentConfig.runInBackground,
+    params.run_in_background,
+    locked,
+  );
+
+  return {
+    modelInput: model.value,
+    modelFromParams: model.source === "caller",
+    thinking: thinking.value,
+    maxTurns: maxTurns.value,
+    inheritContext: inheritContext.value ?? false,
+    runInBackground: runInBackground.value ?? false,
+    discarded: [model, thinking, maxTurns, inheritContext, runInBackground]
+      .filter((resolution) => resolution.discarded)
+      .map((resolution) => resolution.field),
+  };
+}
+
+/** One field's precedence outcome; `source` names the side that supplied the value. */
+interface FieldResolution<T> {
+  field: LockableField;
+  value: T | undefined;
+  source: "caller" | "agent" | "none";
+  /** True when a lock threw away a caller value that differed from the agent's. */
+  discarded: boolean;
+}
+
+/** Apply the precedence rule to a single field. */
+function resolveField<T>(
+  field: LockableField,
+  agentValue: T | undefined,
+  callerValue: T | undefined,
+  locked: LockDeclaration | undefined,
+): FieldResolution<T> {
+  if (!isLocked(field, agentValue, locked) && callerValue !== undefined) {
+    return { field, value: callerValue, source: "caller", discarded: false };
+  }
+  const discarded = callerValue !== undefined && callerValue !== agentValue;
+  return agentValue !== undefined
+    ? { field, value: agentValue, source: "agent", discarded }
+    : { field, value: undefined, source: "none", discarded };
+}
+
+/**
+ * Whether an agent file withholds `field` from its callers.
+ *
+ * The two declaration forms differ deliberately on a field the file leaves unset:
+ * `true` means "what I set is mine", so it locks nothing it did not supply, while a
+ * list names fields outright and denies an override with no value of its own.
+ */
+function isLocked(
+  field: LockableField,
+  agentValue: unknown,
+  locked: LockDeclaration | undefined,
+): boolean {
+  if (locked === undefined) return false;
+  return locked === true ? agentValue !== undefined : locked.includes(field);
+}

package/src/config/thinking-level.ts

@@ -0,0 +1,58 @@
+/**
+ * thinking-level.ts — The thinking-level vocabulary both spawn doors validate against.
+ *
+ * Pi accepts `off` alongside pi-ai's `ThinkingLevel`, but does not export the
+ * combined list: `THINKING_LEVEL_OPTIONS` lives in `@earendil-works/pi-coding-agent`'s
+ * internals and is absent from its public entry, so this package carries its own.
+ *
+ * An unrecognized level is not ignored by the SDK — `clampThinkingLevel` misses it in
+ * the ordered table and falls to the first supported level, which is always `off`. A
+ * typo therefore disables thinking entirely, which is why both doors reject rather
+ * than pass the value through (Refs #834).
+ */
+
+import type { ThinkingLevel as SdkThinkingLevel } from "@earendil-works/pi-ai";
+
+/**
+ * Every level Pi accepts, in ascending order of effort.
+ *
+ * The `satisfies` clause rejects an entry the installed SDK does not declare, and the
+ * parity tests in `test/config/thinking-level.test.ts` check both directions at runtime.
+ * One drift escapes them: a level the SDK adds *and* gates behind a `thinkingLevelMap`
+ * key, the way `xhigh` and `max` are gated, is invisible until a caller names it.
+ */
+export const THINKING_LEVELS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+] as const satisfies readonly (SdkThinkingLevel | "off")[];
+
+/** A thinking level as an agent file or a spawn caller may spell it. */
+export type SubagentThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+/** Narrow an unvalidated value to a thinking level, or undefined when it is not one. */
+export function parseThinkingLevel(value: unknown): SubagentThinkingLevel | undefined {
+  return THINKING_LEVELS.find((level): boolean => level === value);
+}
+
+/** The message a door reports for a value {@link parseThinkingLevel} rejected. */
+export function thinkingLevelError(value: unknown): string {
+  return `Invalid thinking level ${describeRejected(value)}. Valid levels: ${THINKING_LEVELS.join(", ")}.`;
+}
+
+/**
+ * Render a rejected value for an error message.
+ *
+ * The value arrives unvalidated from YAML frontmatter or a tool call, so it may be
+ * any shape at all — anything past a primitive is named by type rather than serialized.
+ */
+function describeRejected(value: unknown): string {
+  if (typeof value === "string") return `"${value}"`;
+  if (value === null) return "null";
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return `of type ${typeof value}`;
+}

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 { WidgetEventsHandler } from "#src/handlers/widget-events";