@yefengr/pi-subagents 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,257 @@
+/**
+ * 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 { AgentEnablementSettings } from "#src/config/agent-enablement";
+import { AgentTypeRegistry } from "#src/config/agent-types";
+import { loadCustomAgents } from "#src/config/custom-agents";
+import { InterruptHandler, SessionLifecycleHandler, ToolStartHandler } 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 { SubagentManager } from "#src/lifecycle/subagent-manager";
+import { CompositeSubagentObserver } from "#src/observation/composite-subagent-observer";
+import { type NotificationDetails, NotificationManager } from "#src/observation/notification";
+import { createNotificationRenderer } 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 { SubagentsAgentsHandler } from "#src/ui/subagents-agents";
+import { SubagentsSettingsHandler } from "#src/ui/subagents-settings";
+
+export default function (pi: ExtensionAPI) {
+  // ---- Register custom notification renderer ----
+  pi.registerMessageRenderer<NotificationDetails>("subagent-notification", createNotificationRenderer());
+
+  const agentEnablement = new AgentEnablementSettings({
+    agentDir: getAgentDir(),
+    cwd: process.cwd(),
+  });
+  const registry = new AgentTypeRegistry(
+    () => loadCustomAgents(process.cwd()),
+    agentEnablement,
+  );
+
+  // ---- Runtime: all mutable extension state in one place ----
+  const runtime = createSubagentRuntime();
+
+  // ---- 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(),
+        });
+      },
+      // Pi 0.85 creates a fresh ModelRuntime for a child session. Runtime
+      // provider registrations live on the parent runtime rather than in
+      // models.json, so replay them onto the child before session creation.
+      createSession: async ({ sessionManager, resourceLoader, modelRegistry, ...rest }) => {
+        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)),
+  };
+
+  // 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({
+    createSubagentSession: (params) => createSubagentSession(params, subagentSessionDeps),
+    baseCwd: process.cwd(),
+    observer,
+    limiter,
+    getRunConfig: () => settings,
+    getRetentionPolicy: () => settings,
+  });
+
+  // Typed service published via Symbol.for() for cross-extension access.
+  // Consumers: const { getSubagentsService } = await import("@yefengr/pi-subagents");
+  const service = new SubagentsServiceAdapter(manager, resolveModel, runtime, registry);
+  publishSubagentsService(service);
+
+  const lifecycle = new SessionLifecycleHandler(
+    runtime,
+    manager,
+    () => notifications.dispose(),
+    unpublishSubagentsService,
+  );
+
+  pi.on("session_start", (event, ctx) => lifecycle.handleSessionStart(event, ctx));
+  pi.on("session_before_switch", () => lifecycle.handleSessionBeforeSwitch());
+  pi.on("session_shutdown", () => lifecycle.handleSessionShutdown());
+
+  // 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);
+
+  // Grab UI context from first tool execution + clear lingering widget on new turn
+  const toolStart = new ToolStartHandler(widget);
+  pi.on("tool_execution_start", (event, ctx) => toolStart.handleToolExecutionStart(event, ctx));
+
+  // 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));
+
+  // ---- 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:agents command ----
+
+  const subagentsAgents = new SubagentsAgentsHandler(
+    registry,
+    agentEnablement,
+    () => registry.reload(),
+  );
+
+  pi.registerCommand("subagents:agents", {
+    description: "List and enable or disable subagent types for the project or globally",
+    handler: async (_args, ctx) => {
+      await subagentsAgents.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 "@yefengr/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 {};
+  }
+}

package/src/lifecycle/child-lifecycle.ts

@@ -0,0 +1,89 @@
+/**
+ * child-lifecycle.ts — Child-execution lifecycle event contract and publisher.
+ *
+ * The core publishes its child-execution lifecycle as ordered events on the Pi
+ * event bus; reactive consumers (permissions, telemetry, UI) subscribe rather
+ * than the core reaching out to them (ADR 0002). This module owns the channel
+ * names, payload shapes, and the publisher that emits them.
+ *
+ * The publisher takes an injected `emit` callback so this module stays free of
+ * Pi SDK imports — `index.ts` wires it to `pi.events.emit`.
+ */
+
+/** Emitted at the start of a child run, before the session is created. */
+export const SUBAGENT_CHILD_SPAWNING = "subagents:child:spawning";
+
+/**
+ * Emitted after the child session is created, immediately before
+ * `bindExtensions()`. Carries the child session id consumers need to register
+ * the session in `SubagentSessionRegistry`. Subscribers must register
+ * synchronously so the entry lands before binding proceeds (see ADR 0002 /
+ * the event-bus synchronous-dispatch guarantee).
+ */
+export const SUBAGENT_CHILD_SESSION_CREATED = "subagents:child:session-created";
+
+/** Emitted after the child's prompt resolves with a classified invocation outcome. */
+export const SUBAGENT_CHILD_COMPLETED = "subagents:child:completed";
+
+/** Emitted in the run's `finally` — always fires, on success and error. */
+export const SUBAGENT_CHILD_DISPOSED = "subagents:child:disposed";
+
+/** Payload for `subagents:child:spawning`. */
+export interface ChildSpawningEvent {
+  agentName: string;
+  parentSessionId?: string;
+}
+
+/** Payload for `subagents:child:session-created`. */
+export interface ChildSessionCreatedEvent {
+  /** Child session id — the registry key. Unique per child; concurrent
+   * siblings of the same parent occupy distinct keys. */
+  sessionId: string;
+  parentSessionId?: string;
+}
+
+/** Payload for `subagents:child:completed`. */
+export interface ChildCompletedEvent {
+  sessionDir: string;
+  agentName: string;
+  outcome: "completed" | "turn_limit" | "timeout" | "cancelled";
+  /** Whether the run received the configured wrap-up instruction. */
+  wrappedUp: boolean;
+}
+
+/** Payload for `subagents:child:disposed`. */
+export interface ChildDisposedEvent {
+  /** Child session id — the registry key. Must match `session-created`. */
+  sessionId: string;
+}
+
+/** Narrow emit seam — injected, never imports the Pi SDK. */
+export type LifecycleEmit = (channel: string, data: unknown) => void;
+
+/** Publishes the child-execution lifecycle on the event bus. */
+export interface ChildLifecyclePublisher {
+  spawning(event: ChildSpawningEvent): void;
+  sessionCreated(event: ChildSessionCreatedEvent): void;
+  completed(event: ChildCompletedEvent): void;
+  disposed(event: ChildDisposedEvent): void;
+}
+
+/** Build a publisher backed by an injected `emit` callback. */
+export function createChildLifecyclePublisher(
+  emit: LifecycleEmit,
+): ChildLifecyclePublisher {
+  return {
+    spawning(event) {
+      emit(SUBAGENT_CHILD_SPAWNING, event);
+    },
+    sessionCreated(event) {
+      emit(SUBAGENT_CHILD_SESSION_CREATED, event);
+    },
+    completed(event) {
+      emit(SUBAGENT_CHILD_COMPLETED, event);
+    },
+    disposed(event) {
+      emit(SUBAGENT_CHILD_DISPOSED, event);
+    },
+  };
+}

package/src/lifecycle/child-shutdown.ts

@@ -0,0 +1,105 @@
+/**
+ * child-shutdown.ts — Bounded `session_shutdown` emission for a child session (issue #709).
+ *
+ * A child session binds the full extension set, so `session_start` fires and every
+ * inherited extension initializes. Pi's `AgentSession.dispose()` does not emit the
+ * matching `session_shutdown` — only `AgentSessionRuntime` does, and children do not
+ * use that path — so extension-owned subprocesses, timers, and sockets outlive the
+ * child. This module supplies the missing half of the pair.
+ *
+ * Two constraints shape it:
+ *
+ * 1. `AgentSession.dispose()` invalidates the extension runner, and every `ctx`
+ *    accessor throws once invalidated. The emit must therefore be awaited to
+ *    completion *before* disposal, never fired and forgotten alongside it.
+ * 2. Pi's runner catches each handler's errors but does not bound a handler that
+ *    hangs. An unbounded await here would stall the parent's teardown and Pi's exit,
+ *    so the emit races a timeout and teardown proceeds either way.
+ *
+ * Nothing here throws: a child that will not shut down cleanly must still be disposed.
+ */
+
+import { debugLog } from "#src/debug";
+
+/** Upper bound on how long one child's shutdown handlers may take. */
+export const CHILD_SHUTDOWN_TIMEOUT_MS = 5_000;
+
+const SESSION_SHUTDOWN = "session_shutdown";
+
+/** The event a disposed child session dispatches to its extensions. */
+interface ChildSessionShutdownEvent {
+  type: typeof SESSION_SHUTDOWN;
+  reason: "quit";
+}
+
+/**
+ * Narrow session seam — only what child shutdown reads.
+ *
+ * Both members are optional so the emitter stays safe against a Pi build that
+ * predates them; either absence means "nothing to emit."
+ */
+export interface ShutdownCapableSession {
+  hasExtensionHandlers?(eventType: string): boolean;
+  readonly extensionRunner?: {
+    emit(event: ChildSessionShutdownEvent): Promise<unknown>;
+  };
+}
+
+/**
+ * Dispatch one `session_shutdown` to a child's extensions and await it, bounded
+ * by `timeoutMs`. Resolves quietly on every failure mode — no runner, no handlers,
+ * a rejected emit, or a handler that never settles — so disposal always proceeds.
+ */
+export async function emitChildSessionShutdown(
+  session: ShutdownCapableSession,
+  timeoutMs: number = CHILD_SHUTDOWN_TIMEOUT_MS,
+): Promise<void> {
+  const runner = session.extensionRunner;
+  if (!runner || !hasShutdownHandlers(session)) return;
+
+  try {
+    const emitted = runner.emit({ type: SESSION_SHUTDOWN, reason: "quit" });
+    if ((await settleWithinBound(emitted, timeoutMs)) === "timed-out") {
+      debugLog("child session_shutdown exceeded its bound (ms)", timeoutMs);
+    }
+  } catch (err) {
+    debugLog("child session_shutdown emit", err);
+  }
+}
+
+/** Whether the child has anything to hear the event; unknown counts as yes. */
+function hasShutdownHandlers(session: ShutdownCapableSession): boolean {
+  return session.hasExtensionHandlers?.(SESSION_SHUTDOWN) ?? true;
+}
+
+type ShutdownOutcome = "settled" | "timed-out";
+
+/**
+ * Resolve when `emitted` settles or when `timeoutMs` elapses, whichever is first.
+ * A rejection counts as settled (the caller logs it); the timer is always cleared,
+ * so a prompt shutdown leaves nothing holding the event loop.
+ */
+async function settleWithinBound(
+  emitted: Promise<unknown>,
+  timeoutMs: number,
+): Promise<ShutdownOutcome> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const bound = new Promise<ShutdownOutcome>((resolve) => {
+    timer = setTimeout(() => {
+      resolve("timed-out");
+    }, timeoutMs);
+  });
+  const settled = emitted.then(
+    (): ShutdownOutcome => "settled",
+    (err: unknown): ShutdownOutcome => {
+      debugLog("child session_shutdown handler", err);
+      return "settled";
+    },
+  );
+
+  try {
+    return await Promise.race([settled, bound]);
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/lifecycle/concurrency-limiter.ts

@@ -0,0 +1,123 @@
+/**
+ * concurrency-limiter.ts — FIFO admission gate for background work.
+ *
+ * Schedules run closures (thunks) against a dynamic limit, running them in
+ * scheduling order as slots free. The limiter knows nothing about agents, IDs,
+ * or the manager — it owns only the active count and the pending queue.
+ *
+ * Every scheduled promise settles: it follows the task's settlement when the
+ * task runs, resolves early if clear() drops it before it starts, or settles
+ * when its queued-timeout elapses first (resolving, or rejecting if onTimeout
+ * throws).
+ */
+
+/** Optional per-task bounds for schedule(). */
+export interface ScheduleOptions {
+	/** Positive milliseconds the task may sit queued before it is dropped. */
+	timeoutMs?: number;
+	/** Called once when the queued-timeout drops the task; never called by clear(). */
+	onTimeout?: () => void;
+}
+
+interface PendingEntry {
+	/** Start the task: consumes the entry and cancels its queued-timeout timer. */
+	start: () => void;
+	/** Resolve the schedule() promise without running the task. */
+	settle: () => void;
+	/** Cancel the queued-timeout timer if it is still armed. */
+	cancelTimer: () => void;
+	/** Timer armed while the entry waits in the queue. */
+	timeout: ReturnType<typeof setTimeout> | undefined;
+	/** Set once the entry starts or times out, so neither happens twice. */
+	started: boolean;
+}
+
+export class ConcurrencyLimiter {
+	private active = 0;
+	private readonly pending: PendingEntry[] = [];
+
+	constructor(private readonly getLimit: () => number) {}
+
+	/**
+	 * Schedule a task to run FIFO once a slot is free.
+	 * Returns a promise that settles with the task, resolves early if the task
+	 * is dropped by clear(), or settles early when options.timeoutMs elapses
+	 * while the task is still pending. An already-started task ignores its
+	 * timeout.
+	 */
+	schedule(task: () => Promise<void>, options?: ScheduleOptions): Promise<void> {
+		const timeoutMs = options?.timeoutMs;
+		if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+			throw new RangeError(`timeoutMs must be a positive finite number, got ${timeoutMs}`);
+		}
+		const onTimeout = options?.onTimeout;
+
+		const { promise, resolve, reject } = Promise.withResolvers<void>(); // eslint-disable-line @typescript-eslint/no-invalid-void-type -- Promise.withResolvers<void> is valid; rule does not allow void in generic fn call type args
+		const entry: PendingEntry = {
+			timeout: undefined,
+			started: false,
+			settle: resolve,
+			cancelTimer: () => {
+				if (entry.timeout !== undefined) {
+					clearTimeout(entry.timeout);
+					entry.timeout = undefined;
+				}
+			},
+			start: () => {
+				entry.started = true;
+				entry.cancelTimer();
+				this.active++;
+				task()
+					.then(resolve, reject)
+					.finally(() => {
+						this.active--;
+						this.recheck();
+					});
+			},
+		};
+
+		if (timeoutMs !== undefined) {
+			const timer = setTimeout(() => {
+				entry.timeout = undefined;
+				// start() already consumed the entry and cleared us.
+				if (entry.started) return;
+				entry.started = true;
+				// clear() already dropped the entry; a late timer must settle nothing.
+				const index = this.pending.indexOf(entry);
+				if (index === -1) return;
+				this.pending.splice(index, 1);
+				try {
+					onTimeout?.();
+				} catch (error) {
+					reject(error);
+					return;
+				}
+				resolve();
+			}, timeoutMs);
+			timer.unref?.();
+			entry.timeout = timer;
+		}
+
+		this.pending.push(entry);
+		this.recheck();
+		return promise;
+	}
+
+	/** Start pending tasks until the limit is reached. Call when the limit may have grown. */
+	recheck(): void {
+		while (this.active < this.getLimit()) {
+			const next = this.pending.shift();
+			if (!next) break;
+			next.start();
+		}
+	}
+
+	/** Drop all pending tasks, resolving their promises without running them or firing their timeouts. */
+	clear(): void {
+		const dropped = this.pending.splice(0);
+		for (const entry of dropped) {
+			entry.cancelTimer();
+			entry.settle();
+		}
+	}
+}