@jopqior/pi-subagents 1.0.0

package/src/lifecycle/subagent-manager.ts

@@ -0,0 +1,546 @@
+/**
+ * subagent-manager.ts - Tracks subagents, background execution, resume support.
+ *
+ * Background agents are subject to a configurable concurrency limit (default: 4).
+ * Excess agents are scheduled on a ConcurrencyLimiter and auto-started as running
+ * agents complete. Foreground agents bypass the limiter (they block the parent anyway).
+ */
+
+import { randomUUID } from "node:crypto";
+import type { Model } from "@earendil-works/pi-ai";
+import { type BackgroundRequest, resolveBackgroundMode } from "#src/config/invocation-config";
+import { debugLog } from "#src/debug";
+import type { ConcurrencyLimiter } from "#src/lifecycle/concurrency-limiter";
+import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent-session";
+import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { SelectionScopeHandle } from "#src/lifecycle/selection-scope";
+import { type ResumeRefusal, Subagent, type SubagentLifecycleObserver } from "#src/lifecycle/subagent";
+import type { SubagentSession } from "#src/lifecycle/subagent-session";
+import { SubagentState } from "#src/lifecycle/subagent-state";
+import type { WorkspaceProvider } from "#src/lifecycle/workspace";
+
+import type { RunConfig } from "#src/runtime";
+import type { AgentConfig, CompactionInfo, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
+
+/**
+ * The agent-registry slice the manager needs to resolve a spawn. Deliberately
+ * narrower than AgentConfigLookup, whose slice serves session assembly (ISP).
+ */
+export interface SpawnTypeResolver {
+  resolveType(name: string): string | undefined;
+  isValidType(type: string): boolean;
+  resolveAgentConfig(type: string): AgentConfig;
+}
+
+/**
+ * Why a resume was refused, across every front door.
+ *
+ * Widens the record's own vocabulary by the one refusal that is not a fact
+ * about a record: an id no record answers to.
+ */
+export type ResumeRefusalReason = ResumeRefusal | "unknown-agent";
+
+/**
+ * What a resume attempt produced: the record whose run was restarted, or the
+ * reason nothing was started.
+ *
+ * A resumed run that *failed* is still `resumed` — the record carries the
+ * error. `refused` means the turn loop never ran.
+ */
+export type ResumeOutcome =
+  | { kind: "resumed"; record: Subagent }
+  | { kind: "refused"; reason: ResumeRefusalReason };
+
+/** Per-call knobs for a resume; both doors pass their own. */
+export interface ResumeCallOptions {
+  /** Cancels the resumed turn loop. A resume does not run under the record's own controller. */
+  signal?: AbortSignal;
+  /**
+   * The caller will deliver this outcome to the parent, so nothing announces
+   * it. Omitted, the resumed outcome is announced like any other completion.
+   */
+  claimOutcome?: boolean;
+}
+
+/** A spawn's resolved identity and mode — the invariants every front door shares. */
+interface ResolvedSpawn {
+  type: SubagentType;
+  isBackground: boolean;
+}
+
+/**
+ * Session-retention windows (minutes). `SettingsManager` satisfies this
+ * structurally; a live getter (`getRetentionPolicy`) lets the sweep read the
+ * current values without a construction-time settings dependency.
+ */
+export interface RetentionPolicy {
+  readonly consumedSessionRetentionMinutes: number;
+  readonly unconsumedSessionRetentionMinutes: number;
+}
+
+const DEFAULT_RETENTION_POLICY: RetentionPolicy = {
+  consumedSessionRetentionMinutes: 10,
+  unconsumedSessionRetentionMinutes: 720,
+};
+
+/**
+ * Only what the retention rule reads. Narrower than `Subagent` so the rule
+ * stays a plain function over four facts, testable without spawning an agent.
+ */
+export interface RetentionCandidate {
+  consumed: boolean;
+  completedAt: number | undefined;
+  consumedAt: number | undefined;
+  pendingQuestion: string | undefined;
+}
+
+/** When a terminal record's session-release window opened, and how long it runs. */
+export interface RetentionWindow {
+  referenceAt: number;
+  windowMinutes: number;
+}
+
+/**
+ * Pick the retention window for one terminal record.
+ *
+ * A collected outcome releases on the short window, measured from the later of
+ * completion and collection, so a late read still gets a full resume window; an
+ * uncollected one holds until the long safety cap.
+ *
+ * A record carrying an unanswered question is not collected, whatever
+ * `consumed` says: the parent has read the question but has not answered it,
+ * and the answer is delivered by resuming the very session the short window
+ * would release.
+ */
+export function resolveRetentionWindow(
+  record: RetentionCandidate,
+  policy: RetentionPolicy,
+): RetentionWindow {
+  if (record.consumed && record.pendingQuestion === undefined) {
+    return {
+      referenceAt: Math.max(record.completedAt ?? 0, record.consumedAt ?? 0),
+      windowMinutes: policy.consumedSessionRetentionMinutes,
+    };
+  }
+  return {
+    referenceAt: record.completedAt ?? 0,
+    windowMinutes: policy.unconsumedSessionRetentionMinutes,
+  };
+}
+
+/** Observer interface for agent lifecycle notifications. */
+export interface SubagentManagerObserver {
+  onSubagentStarted(record: Subagent): void;
+  onSubagentCompleted(record: Subagent): void;
+  /**
+   * Fires when a resume starts, from whichever front door asked for it.
+   * Required: a consumer that tracks the widget's live set has to learn that a
+   * settled record went back to running, and the only alternative is polling.
+   */
+  onSubagentResuming(record: Subagent): void;
+  /** Fires when a resumed run reaches a terminal state (distinct from a fresh completion). */
+  onSubagentResumed(record: Subagent): void;
+  /**
+   * Fires when a running child sends its parent a mid-run message.
+   * Optional: the widget has no use for it, and a hook nobody supplies is a
+   * vacant one.
+   */
+  onSubagentUpdate?(record: Subagent, message: string): void;
+  /**
+   * Fires when a teardown after the record's result was delivered reported
+   * where its work went.
+   * Optional for the same reason as `onSubagentUpdate`: the widget has no use
+   * for it, and a hook nobody supplies is a vacant one.
+   */
+  onSubagentWorkspaceNotice?(record: Subagent, notice: string): void;
+  onSubagentCompacted(record: Subagent, info: CompactionInfo): void;
+  /** Fires synchronously after a background agent record is created (before run). */
+  onSubagentCreated(record: Subagent): void;
+}
+
+export interface SubagentManagerOptions {
+  /** Assembly factory that produces a born-complete SubagentSession per spawn. */
+  createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
+  /** Concurrency limiter — schedules background run thunks FIFO against the limit. */
+  limiter: ConcurrencyLimiter;
+  /** Base working directory handed to a workspace provider (the parent cwd). */
+  baseCwd: string;
+  getRunConfig?: () => RunConfig;
+  /** Live accessor for the session-retention windows; defaults applied when absent. */
+  getRetentionPolicy?: () => RetentionPolicy;
+  observer?: SubagentManagerObserver;
+  /** Agent registry, consulted to canonicalize a spawn's type and resolve its config. */
+  registry: SpawnTypeResolver;
+  /**
+   * The spawning session's retained selection scope, threaded into every
+   * record — queued records included — so an admitted run consults the tree's
+   * active provider before creating its child session.
+   */
+  selectionScope: SelectionScopeHandle;
+}
+
+export interface AgentSpawnConfig {
+  description: string;
+  model?: Model<any>;
+  maxTurns?: number;
+  inheritContext?: boolean;
+  thinkingLevel?: ThinkingLevel;
+  /**
+   * Whether this door has committed to a background mode or is offering a
+   * default the agent's frontmatter may override. Required so a new front door
+   * cannot silently inherit another's policy.
+   */
+  background: BackgroundRequest;
+  /**
+   * Skip the maxConcurrent queue check for this spawn - start immediately even
+   * if the configured concurrency limit would otherwise queue it. Useful for
+   * callers (e.g. cross-extension RPC) that must not be deferred by the queue.
+   */
+  bypassQueue?: boolean;
+  /** Parent abort signal - when aborted, the subagent is also stopped. */
+  signal?: AbortSignal;
+  /** Per-subagent lifecycle observer — replaces onSessionCreated callback. */
+  observer?: SubagentLifecycleObserver;
+  /** Parent session identity - grouped fields that travel together from the tool boundary. */
+  parentSession?: ParentSessionInfo;
+}
+
+export class SubagentManager {
+  private agents = new Map<string, Subagent>();
+  private sweepInterval: ReturnType<typeof setInterval>;
+  private readonly observer?: SubagentManagerObserver;
+  private readonly createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
+  private readonly limiter: ConcurrencyLimiter;
+  private readonly baseCwd: string;
+  private getRunConfig?: () => RunConfig;
+  private getRetentionPolicy?: () => RetentionPolicy;
+  private readonly registry: SpawnTypeResolver;
+  private readonly selectionScope: SelectionScopeHandle;
+  private _workspaceProvider?: WorkspaceProvider;
+
+  /** The registered workspace provider, or undefined when none is registered. */
+  get workspaceProvider(): WorkspaceProvider | undefined {
+    return this._workspaceProvider;
+  }
+
+  constructor(options: SubagentManagerOptions) {
+    this.createSubagentSession = options.createSubagentSession;
+    this.limiter = options.limiter;
+    this.baseCwd = options.baseCwd;
+    this.observer = options.observer;
+    this.getRunConfig = options.getRunConfig;
+    this.getRetentionPolicy = options.getRetentionPolicy;
+    this.registry = options.registry;
+    this.selectionScope = options.selectionScope;
+    // Periodically release the heavy session of terminal agents past their
+    // retention window. The lightweight record (with its result) is kept for the
+    // session lifetime, so get_subagent_result never misses in-session.
+    this.sweepInterval = setInterval(() => this.sweep(), 60_000);
+    this.sweepInterval.unref();
+  }
+
+  /**
+   * Register the single workspace provider. Throws if one is already
+   * registered (chaining is out of scope — see ADR 0002). Returns a disposer
+   * that clears the slot only if this provider is still the active one.
+   */
+  registerWorkspaceProvider(provider: WorkspaceProvider): () => void {
+    if (this._workspaceProvider) {
+      throw new Error(
+        "A WorkspaceProvider is already registered; only one is supported.",
+      );
+    }
+    this._workspaceProvider = provider;
+    return () => {
+      if (this._workspaceProvider === provider) this._workspaceProvider = undefined;
+    };
+  }
+
+  /** Compose a per-agent lifecycle observer from manager and spawn-config concerns. */
+  private buildObserver(options: AgentSpawnConfig): SubagentLifecycleObserver {
+    return {
+      onStarted: (agent) => {
+        this.observer?.onSubagentStarted(agent);
+      },
+      onSessionCreated: options.observer?.onSessionCreated
+        ? (agent) => options.observer!.onSessionCreated!(agent)
+        : undefined,
+      // Terminal transitions are reported for every agent. Whether the parent
+      // needs telling is the notification layer's decision, made from the
+      // carrier claim; suppressing the observer here would also suppress the
+      // lifecycle event and the session-history record, which are facts about
+      // the run rather than announcements.
+      onRunFinished: (agent) => {
+        try { this.observer?.onSubagentCompleted(agent); } catch (err) { debugLog("onSubagentCompleted observer", err); }
+      },
+      onResumeStarted: (agent) => {
+        try { this.observer?.onSubagentResuming(agent); } catch (err) { debugLog("onSubagentResuming observer", err); }
+      },
+      onResumeFinished: (agent) => {
+        try { this.observer?.onSubagentResumed(agent); } catch (err) { debugLog("onSubagentResumed observer", err); }
+      },
+      onUpdateSent: (agent, message) => {
+        this.observer?.onSubagentUpdate?.(agent, message);
+      },
+      onWorkspaceNotice: (agent, notice) => {
+        this.observer?.onSubagentWorkspaceNotice?.(agent, notice);
+      },
+      onCompacted: (agent, info) => {
+        this.observer?.onSubagentCompacted(agent, info);
+      },
+    };
+  }
+
+  /**
+   * Spawn an agent and return its ID immediately (for background use).
+   * If the concurrency limit is reached, the agent is queued.
+   *
+   * Throws when the named agent type is disabled.
+   */
+  spawn(
+    snapshot: ParentSnapshot,
+    type: SubagentType,
+    prompt: string,
+    options: AgentSpawnConfig,
+  ): string {
+    return this.create(snapshot, this.resolveSpawn(type, options.background), prompt, options);
+  }
+
+  /**
+   * Spawn an agent and wait for completion (foreground use).
+   * Foreground agents bypass the concurrency queue.
+   *
+   * The caller holds the result, which is a delivery commitment: the agent must
+   * not be queued and must not be announced, whatever its frontmatter declares.
+   *
+   * Rejects when the named agent type is disabled.
+   */
+  async spawnAndWait(
+    snapshot: ParentSnapshot,
+    type: SubagentType,
+    prompt: string,
+    options: Omit<AgentSpawnConfig, "background">,
+  ): Promise<Subagent> {
+    const foreground: BackgroundRequest = { kind: "explicit", isBackground: false };
+    const id = this.create(snapshot, this.resolveSpawn(type, foreground), prompt, {
+      ...options,
+      background: foreground,
+    });
+    const record = this.agents.get(id)!;
+    // The caller holds the result, so this call is the carrier: claim the outcome
+    // before awaiting it, so nothing announces what is already being delivered.
+    record.claim();
+    await record.promise;
+    return record;
+  }
+
+  /**
+   * Stamp the invariants every front door shares: a canonical agent type, a
+   * rejection for a disabled one, and the effective background mode.
+   */
+  private resolveSpawn(type: string, background: BackgroundRequest): ResolvedSpawn {
+    const canonical = this.registry.resolveType(type);
+    if (canonical !== undefined && !this.registry.isValidType(canonical)) {
+      throw new Error(`Agent type "${canonical}" is disabled`);
+    }
+    const resolvedType = canonical ?? "general-purpose";
+    const agentConfig = this.registry.resolveAgentConfig(resolvedType);
+    return { type: resolvedType, isBackground: resolveBackgroundMode(agentConfig, background) };
+  }
+
+  /** Create, register, and start (or queue) a record for an already-resolved spawn. */
+  private create(
+    snapshot: ParentSnapshot,
+    resolved: ResolvedSpawn,
+    prompt: string,
+    options: AgentSpawnConfig,
+  ): string {
+    const { type, isBackground } = resolved;
+    const id = randomUUID().slice(0, 17);
+    const record = new Subagent({
+      id,
+      type,
+      description: options.description,
+      isBackground,
+      state: new SubagentState({
+        status: isBackground ? "queued" : "running",
+        startedAt: Date.now(),
+      }),
+      execution: {
+        createSubagentSession: this.createSubagentSession,
+        snapshot,
+        prompt,
+        baseCwd: this.baseCwd,
+        observer: this.buildObserver(options),
+        getRunConfig: this.getRunConfig,
+        getWorkspaceProvider: () => this._workspaceProvider,
+        selectionScope: this.selectionScope,
+        model: options.model,
+        maxTurns: options.maxTurns,
+        thinkingLevel: options.thinkingLevel,
+        parentSession: options.parentSession,
+        signal: options.signal,
+      },
+    });
+    this.agents.set(id, record);
+
+    if (isBackground) {
+      this.observer?.onSubagentCreated(record);
+    }
+
+    if (isBackground && !options.bypassQueue) {
+      // Schedule on the limiter — scheduleVia captures the limiter promise
+      // eagerly, so a queued agent is awaitable from spawn; guardedRun guards
+      // against abort-while-queued when the slot frees.
+      record.scheduleVia((thunk) => this.limiter.schedule(thunk));
+      return id;
+    }
+
+    record.start();
+    return id;
+  }
+
+  /**
+   * Resume an existing agent session with a new prompt.
+   *
+   * The refusal policy lives here rather than in a caller, so every front door
+   * declines the same resumes for the same reasons; a door owns only how it
+   * words the answer. Delegates to Subagent.resume(), which owns the observer
+   * subscription lifecycle.
+   */
+  async resume(id: string, prompt: string, options: ResumeCallOptions = {}): Promise<ResumeOutcome> {
+    const agent = this.agents.get(id);
+    if (!agent) return { kind: "refused", reason: "unknown-agent" };
+    const refusal = agent.resumeRefusal;
+    if (refusal) return { kind: "refused", reason: refusal };
+    // Before the resume starts: resetForResume runs synchronously inside
+    // resume(), so a claim taken afterwards would miss the terminal edge.
+    if (options.claimOutcome) agent.claim();
+    await agent.resume(prompt, options.signal);
+    return { kind: "resumed", record: agent };
+  }
+
+  getRecord(id: string): Subagent | undefined {
+    return this.agents.get(id);
+  }
+
+  listAgents(): Subagent[] {
+    return [...this.agents.values()].sort(
+      (a, b) => b.startedAt - a.startedAt,
+    );
+  }
+
+  abort(id: string): boolean {
+    const record = this.agents.get(id);
+    if (!record) return false;
+
+    // A queued agent has not started; stop it through the same terminal funnel
+    // a running agent's stop uses. Its scheduled thunk becomes a no-op (status
+    // guard) when its slot finally opens.
+    if (record.status === "queued") {
+      record.stopQueued();
+      return true;
+    }
+
+    return record.abort();
+  }
+
+  /**
+   * Remove a record from the map and tear its session down.
+   * The map is updated first so the record is unreachable while its child's
+   * extensions shut down.
+   */
+  private removeRecord(id: string, record: Subagent): Promise<void> {
+    this.agents.delete(id);
+    return record.disposeSession();
+  }
+
+  /**
+   * Release the heavy session of any terminal agent past its retention window.
+   * The record (with its result) is retained for the session lifetime; only the
+   * live `AgentSession` is freed. `resolveRetentionWindow` owns which window
+   * applies.
+   */
+  private sweep() {
+    const policy = this.getRetentionPolicy?.() ?? DEFAULT_RETENTION_POLICY;
+    const now = Date.now();
+    for (const record of this.agents.values()) {
+      if (record.isActive()) continue;
+      if (!record.isSessionReady()) continue; // already released, or never had a session
+      const { referenceAt, windowMinutes } = resolveRetentionWindow(record, policy);
+      // Fire-and-forget: the sweep runs on an interval with no one to await it,
+      // and Subagent.releaseSession() already swallows a failing teardown.
+      if (now - referenceAt >= windowMinutes * 60_000) void record.releaseSession();
+    }
+  }
+
+  /**
+   * Remove all completed/stopped/errored records immediately.
+   * Called on session start/switch so tasks from a prior session don't persist.
+   */
+  async clearCompleted(): Promise<void> {
+    const teardowns: Promise<void>[] = [];
+    for (const [id, record] of this.agents) {
+      if (record.isActive()) continue;
+      teardowns.push(this.removeRecord(id, record));
+    }
+    await Promise.all(teardowns);
+  }
+
+  /** Whether any agents are still running or queued. */
+  // fallow-ignore-next-line unused-class-member
+  hasRunning(): boolean {
+    return [...this.agents.values()].some(r => r.isActive());
+  }
+
+  /** Abort all running and queued agents immediately. */
+  abortAll(): number {
+    let count = 0;
+    for (const record of this.agents.values()) {
+      if (record.status === "queued") {
+        record.stopQueued();
+        count++;
+      } else if (record.abort()) {
+        count++;
+      }
+    }
+    // Drop pending thunks (their promises resolve).
+    this.limiter.clear();
+    return count;
+  }
+
+  /** Wait for all running and queued agents to complete (including queued ones). */
+  async waitForAll(): Promise<void> {
+    // Every spawned agent has a settled-on-completion promise (the limiter starts
+    // queued ones as slots free), so a single allSettled covers the queued case.
+    // The loop only catches agents spawned during the wait.
+    let pending = this.pendingPromises();
+    while (pending.length > 0) {
+      await Promise.allSettled(pending);
+      pending = this.pendingPromises();
+    }
+  }
+
+  /** Promises of all running/queued agents that have one. */
+  private pendingPromises(): Promise<void>[] {
+    return [...this.agents.values()]
+      .filter(r => r.isActive())
+      .map(r => r.promise)
+      .filter((p): p is Promise<void> => p != null);
+  }
+
+  /**
+   * Tear down every record, resolving once each child's extensions have shut
+   * down. The registry is emptied before the teardowns are awaited, so nothing
+   * can reach a dying record; `allSettled` keeps one failing child from
+   * abandoning its siblings.
+   */
+  async dispose(): Promise<void> {
+    clearInterval(this.sweepInterval);
+    // Drop pending thunks
+    this.limiter.clear();
+    const teardowns = [...this.agents.values()].map(record => record.disposeSession());
+    this.agents.clear();
+    await Promise.allSettled(teardowns);
+  }
+}