@jopqior/pi-subagents 1.0.0

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,71 @@
+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;
+  /** Closes the retained selection scope — owner-aware root revoke or child release. */
+  closeSelectionScope(): 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:
+  // 0. Close the selection scope — revoke the root lease (or free this
+  //    child's subtree) before anything else: a pending selection must lose
+  //    its authority now, not whenever a later companion handler runs
+  // 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.runtime.closeSelectionScope();
+    this.unpublishService();
+    this.runtime.clearSessionContext();
+    this.disposeNotifications();
+    this.manager.abortAll();
+    return this.manager.dispose();
+  }
+}

package/src/handlers/widget-events.ts

@@ -0,0 +1,49 @@
+/**
+ * Host-event handlers for the agent widget.
+ *
+ * Extracted from index.ts so each handler can be tested in isolation
+ * with a mocked narrow widget interface.
+ *
+ * The three events are unrelated to each other and none is a tool call.
+ * The widget can draw nothing until it holds a UI context, so the capture
+ * belongs on an event that fires in every session; the linger clock counts
+ * parent turns, so it belongs on the event that marks one; and the widget's
+ * two resources have to be released when the session they belong to ends.
+ */
+
+/** Narrow widget interface — only the methods these handlers call. */
+export interface EventDrivenWidget {
+  setUICtx(ctx: unknown): void;
+  onTurnStart(): void;
+  dispose(): void;
+}
+
+/** Minimal context shape for session_start — only the field the handler reads. */
+interface SessionStartCtx {
+  ui: unknown;
+}
+
+/**
+ * Feeds the widget the three host events it depends on.
+ *
+ * `session_start` supplies the UI context: Pi starts the TUI before it
+ * initializes extensions and binds the UI context before emitting the event,
+ * so `ctx.ui` is live here, and headless binds a no-op context rather than
+ * none. `turn_start` ages finished agents out of the widget's roster.
+ * `session_shutdown` releases the update interval and both UI registrations.
+ */
+export class WidgetEventsHandler {
+  constructor(private readonly widget: EventDrivenWidget) {}
+
+  handleSessionStart(_event: unknown, ctx: SessionStartCtx): void {
+    this.widget.setUICtx(ctx.ui);
+  }
+
+  handleTurnStart(): void {
+    this.widget.onTurnStart();
+  }
+
+  handleSessionShutdown(): void {
+    this.widget.dispose();
+  }
+}

package/src/index.ts

@@ -0,0 +1,292 @@
+/**
+ * pi-agents — A pi extension providing focused, in-process autonomous sub-agents.
+ *
+ * Tools:
+ *   Agent             — LLM-callable: spawn a sub-agent
+ *   get_subagent_result  — LLM-callable: check background agent status/result
+ *   steer_subagent       — LLM-callable: send a steering message to a running agent
+ *
+ * Commands:
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  type ExtensionAPI,
+  getAgentDir,
+  ModelRuntime,
+  type ResourceLoader,
+  ModelRegistry as SdkModelRegistry,
+  SettingsManager as SdkSettingsManager,
+  SessionManager,
+} from "@earendil-works/pi-coding-agent";
+import { AgentTypeRegistry } from "#src/config/agent-types";
+import { loadCustomAgents } from "#src/config/custom-agents";
+import { InterruptHandler, SessionLifecycleHandler, WidgetEventsHandler } from "#src/handlers/index";
+import { createChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
+import { ConcurrencyLimiter } from "#src/lifecycle/concurrency-limiter";
+import { createSubagentSession, type SubagentSessionDeps } from "#src/lifecycle/create-subagent-session";
+import { captureInheritedSelectionScope } from "#src/lifecycle/selection-scope";
+import { SpawnSelectionScope } from "#src/lifecycle/spawn-selection";
+import { SubagentManager } from "#src/lifecycle/subagent-manager";
+import { CompositeSubagentObserver } from "#src/observation/composite-subagent-observer";
+import {
+  type NotificationDetails,
+  NotificationManager,
+  type UpdateDetails,
+  type WorkspaceNoticeDetails,
+} from "#src/observation/notification";
+import {
+  createNotificationRenderer,
+  createUpdateRenderer,
+  createWorkspaceNoticeRenderer,
+} from "#src/observation/renderer";
+import { SubagentEventsObserver } from "#src/observation/subagent-events-observer";
+import { createSubagentRuntime } from "#src/runtime";
+import { publishSubagentsService, unpublishSubagentsService } from "#src/service/service";
+import { SubagentsServiceAdapter } from "#src/service/service-adapter";
+import { detectEnv } from "#src/session/env";
+
+import { resolveModel } from "#src/session/model-resolver";
+import { createExcludedPackagesStorage } from "#src/session/package-exclusions";
+import { buildAgentPrompt } from "#src/session/prompts";
+import { inheritRegisteredProviders } from "#src/session/provider-inheritance";
+import { deriveSubagentSessionDir } from "#src/session/session-dir";
+import { SettingsManager } from "#src/settings";
+import { AgentTool } from "#src/tools/agent-tool";
+import { GetResultTool } from "#src/tools/get-result-tool";
+import { SteerTool } from "#src/tools/steer-tool";
+import { AgentWidget } from "#src/ui/agent-widget";
+import { SessionNavigatorHandler } from "#src/ui/session-navigator";
+import { SubagentsSettingsHandler } from "#src/ui/subagents-settings";
+
+export default function (pi: ExtensionAPI) {
+  // ---- Register custom notification renderer ----
+  pi.registerMessageRenderer<NotificationDetails>("subagent-notification", createNotificationRenderer());
+  pi.registerMessageRenderer<UpdateDetails>("subagent-update", createUpdateRenderer());
+  pi.registerMessageRenderer<WorkspaceNoticeDetails>(
+    "subagent-workspace-notice",
+    createWorkspaceNoticeRenderer(),
+  );
+
+  const registry = new AgentTypeRegistry(() => loadCustomAgents(process.cwd()));
+
+  // ---- Runtime: all mutable extension state in one place ----
+  // Selection scope first: capture the inherited handle while the construction
+  // context is still ambient (this factory runs inside the parent's constructChild
+  // wrapper), or create this session's own root lease. A root never gets here
+  // with a context; a child core never gets here without one.
+  const selectionScope = captureInheritedSelectionScope() ?? new SpawnSelectionScope();
+  const runtime = createSubagentRuntime(selectionScope);
+
+  // ---- Notification system ----
+  // Owns completion nudges and live-activity cleanup. The widget detects finished
+  // agents itself (AgentWidget.update self-seeds), so NotificationManager has no
+  // widget dependency — keeping the construction graph a cycle-free DAG.
+  const notifications = new NotificationManager(
+    (msg, opts) => pi.sendMessage(msg, opts),
+  );
+
+  // Gate nudge delivery on the parent's agent run. agent_settled fires exactly
+  // once per run (from a finally block, so it also covers error and abort),
+  // whereas agent_end fires once per run segment — retries, auto-compaction and
+  // followUp continuations each emit one.
+  pi.on("agent_start", () => notifications.onParentAgentStart());
+  pi.on("agent_settled", () => notifications.onParentAgentSettled());
+
+  // Settings: owns all three in-memory values and handles load/save/emit.
+  // onMaxConcurrentChanged is wired to the limiter directly (closure captures by reference).
+  const settings = new SettingsManager({
+    emit: (event, payload) => pi.events.emit(event, payload),
+    cwd: process.cwd(),
+    agentDir: getAgentDir(),
+    onMaxConcurrentChanged: () => limiter.recheck(),
+  });
+  settings.load();
+
+  // Observer: receives agent lifecycle notifications and dispatches events/notifications.
+  const eventsObserver = new SubagentEventsObserver({
+    emit: (channel, data) => pi.events.emit(channel, data),
+    appendEntry: (customType, data) => pi.appendEntry(customType, data),
+    notifications,
+  });
+
+  // Fan-out observer: lets the widget subscribe as a second lifecycle consumer
+  // while the manager keeps its single-observer contract. The widget is added
+  // after construction (it needs the manager); the manager consults the observer
+  // only at spawn time, so registering late is safe.
+  const observer = new CompositeSubagentObserver([eventsObserver]);
+
+  const subagentSessionDeps: SubagentSessionDeps = {
+    io: {
+      detectEnv,
+      getAgentDir,
+      createResourceLoader: (opts) => new DefaultResourceLoader(opts),
+      deriveSessionDir: deriveSubagentSessionDir,
+      createSessionManager: (cwd, dir) => SessionManager.create(cwd, dir),
+      createSettingsManager: (cwd, dir) => SdkSettingsManager.create(cwd, dir),
+      // The exclusion policy is resolved here, at the composition root, so the
+      // assembly factory stays free of it and gets a ready-made settings view.
+      createLoaderSettingsManager: (parent) => {
+        const excluded = new Set(settings.excludedExtensionPackages);
+        if (excluded.size === 0) return parent;
+        return SdkSettingsManager.fromStorage(createExcludedPackagesStorage(parent, excluded), {
+          projectTrusted: parent.isProjectTrusted(),
+        });
+      },
+      // The factory states its collaborators as narrow structural contracts so
+      // it can be tested with plain stubs. Here at the composition root the
+      // values really are the SDK objects, so widen those three and let every
+      // other option type-check against the SDK signature.
+      createSession: async ({ sessionManager, resourceLoader, modelRegistry, ...rest }) => {
+        // Pi builds the child a fresh ModelRuntime whenever it is not given
+        // one, and runtime registrations live on the instance rather than in
+        // models.json or auth.json — so the child would lose every provider the
+        // parent registered via pi.registerProvider. Build the runtime here
+        // instead and replay those registrations onto it. The child keeps its
+        // own pool, so a child-loaded extension cannot mutate the parent's
+        // (Refs #812). The path derivation mirrors the SDK's own.
+        const childRuntime = await ModelRuntime.create({
+          authPath: join(rest.agentDir, "auth.json"),
+          modelsPath: join(rest.agentDir, "models.json"),
+        });
+        const childRegistry = new SdkModelRegistry(childRuntime);
+        inheritRegisteredProviders(modelRegistry as SdkModelRegistry, {
+          registerNative: (provider) => {
+            childRegistry.registerProvider(provider);
+          },
+          registerConfigured: (id, config) => {
+            childRegistry.registerProvider(id, config);
+          },
+        });
+        return createAgentSession({
+          ...rest,
+          sessionManager: sessionManager as SessionManager,
+          resourceLoader: resourceLoader as ResourceLoader,
+          modelRuntime: childRuntime,
+        });
+      },
+      assemblerIO: {
+        buildAgentPrompt,
+      },
+    },
+    exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
+    registry,
+    lifecycle: createChildLifecyclePublisher((channel, data) => pi.events.emit(channel, data)),
+    // Resolved here, at the composition root, so the assembly factory stays
+    // free of the policy and gets a ready-made settings view — the same shape
+    // the extension-exclusion policy reaches it in. It is a resolver rather
+    // than a value because only the assembler knows the child's provider.
+    resolvePromptInheritance: (provider) => settings.promptInheritanceFor(provider),
+  };
+
+  // ConcurrencyLimiter: schedules background run thunks FIFO against the limit.
+  // It knows nothing about agents or the manager — dependency direction is strictly manager → limiter.
+  const limiter = new ConcurrencyLimiter(() => settings.maxConcurrent);
+
+  const manager = new SubagentManager({
+    // The complete child factory call — loader reload, session creation, and
+    // extension binding — runs inside the construction wrapper, so a child
+    // core factory initializing during loader.reload() captures the inherited
+    // selection handle whether or not a provider is ever configured here.
+    createSubagentSession: (params) =>
+      selectionScope.constructChild(() => createSubagentSession(params, subagentSessionDeps)),
+    baseCwd: process.cwd(),
+    observer,
+    limiter,
+    getRunConfig: () => settings,
+    getRetentionPolicy: () => settings,
+    registry,
+    // The same retained scope: an admitted run consults the tree's active
+    // provider before creating its child session.
+    selectionScope,
+  });
+
+  // Typed service published via Symbol.for() for cross-extension access.
+  // Consumers: const { getSubagentsService } = await import("@jopqior/pi-subagents");
+  const service = new SubagentsServiceAdapter(manager, resolveModel, runtime);
+  publishSubagentsService(service);
+
+  const lifecycle = new SessionLifecycleHandler(
+    runtime,
+    manager,
+    () => notifications.dispose(),
+    unpublishSubagentsService,
+  );
+
+  // Live widget: constructed after the manager (it polls listAgents()) and
+  // registered as a lifecycle observer so it self-drives its update timer.
+  const widget = new AgentWidget(manager, registry);
+  observer.add(widget);
+
+  // Give the widget its UI context and its turn ticks. Pi fans an event out to
+  // every handler an extension registers for it, so these take their own
+  // registrations rather than sharing a lambda with an unrelated concern.
+  const widgetEvents = new WidgetEventsHandler(widget);
+
+  pi.on("session_start", (event, ctx) => lifecycle.handleSessionStart(event, ctx));
+  pi.on("session_start", (event, ctx) => widgetEvents.handleSessionStart(event, ctx));
+  pi.on("session_before_switch", () => lifecycle.handleSessionBeforeSwitch());
+  pi.on("session_shutdown", () => lifecycle.handleSessionShutdown());
+  // Registered after the lifecycle handler on purpose. Pi awaits an extension's
+  // handlers for an event in registration order, so the widget is torn down once
+  // `abortAll()` and the awaited `manager.dispose()` have finished — no terminal
+  // transition is left to drive an `update()` at a half-disposed widget.
+  pi.on("session_shutdown", () => widgetEvents.handleSessionShutdown());
+
+  // Capture the prompt parts Pi assembled for the parent's turn. This is the
+  // only event carrying them — `getSystemPromptOptions()` is attached to a
+  // command context, not to the session context the runtime holds — and a spawn
+  // renders the parent's portable identity from the latest capture.
+  pi.on("before_agent_start", (event) => {
+    runtime.setSystemPromptOptions(event.systemPromptOptions);
+  });
+
+  // Abort all subagents when the parent agent loop is interrupted (ESC), unless
+  // the user has turned that policy off. The predicate is read at abort time.
+  const interrupt = new InterruptHandler(manager, () => settings.abortAllOnInterrupt);
+  pi.on("turn_start", (_event, ctx) => interrupt.handleTurnStart(ctx));
+  pi.on("turn_start", () => widgetEvents.handleTurnStart());
+
+  // ---- Agent tool ----
+
+  pi.registerTool(new AgentTool(manager, runtime, settings, registry, getAgentDir()).toToolDefinition());
+
+  // ---- get_subagent_result tool ----
+
+  pi.registerTool(new GetResultTool(manager, registry).toToolDefinition());
+
+  // ---- steer_subagent tool ----
+
+  pi.registerTool(new SteerTool(manager, pi.events).toToolDefinition());
+
+  // ---- /subagents:settings command ----
+
+  const subagentsSettings = new SubagentsSettingsHandler(settings);
+
+  pi.registerCommand("subagents:settings", {
+    description: "Configure subagent settings (concurrency, turn limits, retention, interrupt policy)",
+    handler: async (_args, ctx) => {
+      await subagentsSettings.handle({ ui: ctx.ui });
+    },
+  });
+
+  // ---- /subagents:sessions command ----
+
+  const sessionNavigator = new SessionNavigatorHandler();
+
+  pi.registerCommand("subagents:sessions", {
+    description: "View a subagent's session transcript (read-only)",
+    handler: async (_args, ctx) => {
+      await sessionNavigator.handle({
+        ui: ctx.ui,
+        agents: manager.listAgents(),
+        registry,
+        cwd: ctx.cwd,
+        readFile: (path) => readFileSync(path, "utf8"),
+      });
+    },
+  });
+}

package/src/layered-settings.ts

@@ -0,0 +1,105 @@
+/**
+ * Generic layered settings loader for `@gotgenes/pi-*` extensions.
+ *
+ * Extensions that store configuration in JSON files under a global agent
+ * directory and a per-project `.pi/` folder share the same three-step idiom:
+ *
+ *   1. Read the global file (`<agentDir>/<filename>`).
+ *   2. Read the project file (`<cwd>/.pi/<filename>`).
+ *   3. Merge them — project wins on conflicts — and return the result.
+ *
+ * Both layers are optional: a missing file is silent (`{}`), and a file that
+ * cannot be parsed warns to stderr and is treated as absent so startup
+ * proceeds normally.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { loadLayeredSettings, type LayeredSettingsSource } from "@jopqior/pi-subagents/settings";
+ *
+ * interface MyConfig { enabled?: boolean; limit?: number }
+ *
+ * function sanitize(raw: unknown): Partial<MyConfig> {
+ *   if (!raw || typeof raw !== "object") return {};
+ *   const r = raw as Record<string, unknown>;
+ *   const out: Partial<MyConfig> = {};
+ *   if (typeof r.enabled === "boolean") out.enabled = r.enabled;
+ *   if (typeof r.limit === "number") out.limit = r.limit;
+ *   return out;
+ * }
+ *
+ * const config = loadLayeredSettings<MyConfig>({
+ *   agentDir,     // e.g. from the Pi runtime env — the agent home directory
+ *   cwd,          // project root — project file is at <cwd>/.pi/<filename>
+ *   filename: "my-extension.json",
+ *   sanitize,
+ *   warnLabel: "my-extension",
+ * });
+ * ```
+ *
+ * @public
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Parameters for one layered settings load: describes where the files live,
+ * how to validate their contents, and what label to use in warnings.
+ *
+ * @public
+ */
+export interface LayeredSettingsSource<T> {
+  /** Directory holding the global settings file (typically the Pi agent dir). */
+  agentDir: string;
+  /** Project root; the project file lives at `<cwd>/.pi/<filename>`. */
+  cwd: string;
+  /** Base filename for both layers, e.g. `"subagents.json"`. */
+  filename: string;
+  /**
+   * Validate and coerce parsed JSON into a partial settings object.
+   * Unknown or invalid fields should be silently dropped — return `{}` for
+   * unrecognised shapes. Never throw.
+   */
+  sanitize: (raw: unknown) => Partial<T>;
+  /**
+   * Short label used in the malformed-file warning prefix,
+   * e.g. `"pi-subagents"` → `"[pi-subagents] Ignoring malformed settings at …"`.
+   */
+  warnLabel: string;
+}
+
+/**
+ * Load merged layered settings: global provides defaults, project overrides.
+ *
+ * - A missing file is silent — returns `{}` for that layer.
+ * - A file that exists but cannot be parsed warns to stderr and returns `{}` for
+ *   that layer, so startup proceeds normally.
+ * - The two layers are merged with a shallow spread; project keys win.
+ *
+ * Throws nothing. All error conditions produce a warning and fall back to `{}`.
+ *
+ * @public
+ */
+export function loadLayeredSettings<T>(source: LayeredSettingsSource<T>): Partial<T> {
+  const { agentDir, cwd, filename, sanitize, warnLabel } = source;
+  const global = readLayer(join(agentDir, filename), sanitize, warnLabel);
+  const project = readLayer(join(cwd, ".pi", filename), sanitize, warnLabel);
+  return { ...global, ...project };
+}
+
+// ── Private helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Read one settings file. Missing → `{}` (silent). Malformed → `{}` + warn.
+ */
+function readLayer<T>(path: string, sanitize: (raw: unknown) => Partial<T>, warnLabel: string): Partial<T> {
+  if (!existsSync(path)) return {};
+  try {
+    return sanitize(JSON.parse(readFileSync(path, "utf-8")));
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    console.warn(`[${warnLabel}] Ignoring malformed settings at ${path}: ${reason}`);
+    return {};
+  }
+}