@nredd/pi-subagents 0.22.0-nredd.7 → 0.22.0-nredd.8

package/src/agent-manager.ts

@@ -30,7 +30,10 @@ import { getAgentConfig } from "./agent-types.js";
 import { type Clock, realClock, type TimerHandle } from "./clock.js";
 import { assignHandle, handleBase } from "./mention.js";
 import type { ModelCallEvent } from "./model-call.js";
-import { describeModel, describePhysicalModel, describeVirtualModel, isVirtualModel } from "./model-resolver.js";
+import { describeModel, describePhysicalModel, describeVirtualModel, isVirtualModel, type ModelFallback } from "./model-resolver.js";
+import { admitModelSelection, describeSelection, type ModelSelection, modelSelectionNote, selectModel } from "./model-selection.js";
+import { type TierDisclosure, tierDisclosure } from "./model-tiers.js";
+import { appendModelFallbackEntry, appendModelTierEntry } from "./output-file.js";
 import {
   assertWithinBudgetDepth,
   BUDGET_QUEUE_FULL_ERROR,
@@ -41,6 +44,8 @@ import {
   releaseBudget,
   tryAcquireBudget,
 } from "./process-budget.js";
+import { describeBlock } from "./quota-admission.js";
+import { isStaleCtxError } from "./stale-ctx.js";
 import type { AgentInvocation, AgentRecord, AgentTombstone, IsolationMode, MentionResolution, Pool, SubagentType, ThinkingLevel } from "./types.js";
 import { addUsage, type LifetimeUsage } from "./usage.js";
 import type { CompiledSchema } from "./workflow/json-schema.js";
@@ -59,6 +64,10 @@ function relabelFromResponse(record: AgentRecord, message: AssistantMessageInfo
   if (!physical) return;
   record.invocation ??= {};
   Object.assign(record.invocation, physical);
+  if ((record.modelTier?.kind === "routed" || record.modelTier?.kind === "static") && record.modelTier.answered !== physical.modelId) {
+    record.modelTier = { ...record.modelTier, answered: physical.modelId };
+    if (record.outputFile) appendModelTierEntry(record.outputFile, record.id, record.modelTier);
+  }
 }
 
 export type OnAgentComplete = (record: AgentRecord) => void;
@@ -163,12 +172,17 @@ export interface EvictedNote {
   evictedAfterMin: number;
   /** The `.output` transcript when one was written, else the session file. */
   transcript?: string;
+  /** The run's model fallback, so even an evicted agent's id still discloses it. */
+  modelFallback?: ModelFallback;
+  modelTier?: TierDisclosure;
 }
 
 /** The text a tool returns for an id whose record was evicted. */
 export function describeEvicted(note: EvictedNote): string {
   const where = note.transcript ? `; transcript: ${note.transcript}` : "";
-  return `Agent "${note.id}" (${note.description}) ${note.status}, evicted after ${note.evictedAfterMin} min${where}`;
+  const disclosure = modelSelectionNote(note);
+  const fallback = disclosure ? `\n${disclosure}` : "";
+  return `Agent "${note.id}" (${note.description}) ${note.status}, evicted after ${note.evictedAfterMin} min${where}${fallback}`;
 }
 
 /**
@@ -282,6 +296,8 @@ interface SpawnArgs {
 }
 
 interface SpawnOptions {
+  /** Home inherited by nested callers; the manager's home is the default. */
+  homeDir?: string;
   description: string;
   /**
    * Optional memorable name for this instance, becoming a second handle
@@ -308,7 +324,14 @@ interface SpawnOptions {
    * `spawnTopLevel` strips it from anything a caller sends.
    */
   reclaim?: { handle: string; alias?: string };
-  model?: Model<any>;
+  model?: Model<any> | string;
+  /** Internal preflight outcome, stored on the record without resolving again. */
+  modelSelection?: ModelSelection;
+  /** Historical outcome only, never used to label the continuation. */
+  previousModelTier?: TierDisclosure;
+  /** Historical fallback only, never used to label the continuation. */
+  previousModelFallback?: ModelFallback;
+
   maxTurns?: number;
   isolated?: boolean;
   inheritContext?: boolean;
@@ -472,6 +495,7 @@ const CHILD_SHUTDOWN_TIMEOUT_MS = 3_000;
  * `assertActive()` from a bare timer callback — an uncaughtException that kills pi (#242).
  */
 async function shutdownChildSession(session: AgentSession | undefined): Promise<void> {
+  let deadline: ReturnType<typeof setTimeout> | undefined;
   try {
     const runner = session?.extensionRunner;
     // Optional all the way down: on a pi without the getter, or a stubbed session from a
@@ -482,14 +506,44 @@ async function shutdownChildSession(session: AgentSession | undefined): Promise<
       // already torn down — one hung handler would leave a dead terminal.
       await Promise.race([
         runner.emit({ type: "session_shutdown", reason: "quit" }),
-        new Promise<void>(resolve => setTimeout(resolve, CHILD_SHUTDOWN_TIMEOUT_MS).unref()),
+        new Promise<void>(resolve => {
+          deadline = setTimeout(resolve, CHILD_SHUTDOWN_TIMEOUT_MS);
+          deadline.unref();
+        }),
       ]);
     }
   } catch { /* a partial session must degrade, not take the teardown down with it */ }
+  finally {
+    // Promise.race does not cancel its loser, even when a handler rejects.
+    if (deadline !== undefined) clearTimeout(deadline);
+  }
   // Always, even on timeout: disposal is what this function ultimately exists to do.
   try { session?.dispose?.(); } catch { /* ignore */ }
 }
 
+/**
+ * Wrap an observer the child's own agent loop calls (usage, compaction) so a
+ * throw cannot reach that loop. pi records a throw from a session listener as
+ * the turn's failure, so an observer closed over a replaced session's `pi`
+ * ("This extension ctx is stale ...") used to end a detached child with an
+ * empty error turn and "No output" (#145). That failure is expected after a
+ * reload and dropped silently. Any other throw is a real observer defect: it
+ * is logged once per observer and also kept from killing the run.
+ */
+function guardObserver<A extends unknown[]>(name: string, observer: ((...args: A) => void) | undefined): ((...args: A) => void) | undefined {
+  if (!observer) return undefined;
+  let logged = false;
+  return (...args: A) => {
+    try {
+      observer(...args);
+    } catch (error) {
+      if (isStaleCtxError(error) || logged) return;
+      logged = true;
+      console.error(`pi-subagents: ${name} observer failed; further failures are not logged`, error);
+    }
+  };
+}
+
 export class AgentManager {
   private agents = new Map<string, AgentRecord>();
   private cleanupInterval: TimerHandle;
@@ -561,11 +615,12 @@ export class AgentManager {
     onUsage?: OnAgentUsage,
     onSteered?: OnAgentSteered,
     private readonly clock: Clock = realClock,
+    private readonly homeDir?: string,
   ) {
     this.onComplete = onComplete;
     this.onStart = onStart;
-    this.onCompact = onCompact;
-    this.onUsage = onUsage;
+    this.onCompact = guardObserver("compaction", onCompact);
+    this.onUsage = guardObserver("usage", onUsage);
     this.onSteered = onSteered;
     this.maxConcurrent = maxConcurrent;
     // Sweep finished records past their retention window (see cleanup()).
@@ -645,6 +700,19 @@ export class AgentManager {
     // call, not minutes later at drain. Throw (not warn): programmatic callers
     // can fix and retry; the RPC layer converts throws into error envelopes.
     assertValidSpawnCwd(options.cwd);
+    const selection = options.modelSelection ?? selectModel({
+      homeDir: options.homeDir ?? this.homeDir,
+      agentType: type,
+      definitionModel: getAgentConfig(type)?.model,
+      paramModel: options.model,
+      parentModel: ctx.model,
+      registry: ctx.modelRegistry,
+      cwd: options.configCwd ?? ctx.cwd,
+      agentLabel: getAgentConfig(type)?.displayName,
+    });
+    if (typeof selection === "string") throw new Error(selection);
+    if (selection.scopeWarning && !options.modelSelection) ctx.ui.notify(selection.scopeWarning, "warning");
+    options = { ...options, model: selection.model, modelSelection: selection };
 
     const id = randomUUID().slice(0, 17);
     const abortController = new AbortController();
@@ -684,6 +752,11 @@ export class AgentManager {
       // `options` has stopped being the interesting object.
       blocking: options.blocking,
       invocation: options.invocation,
+      modelFallback: selection.fallback,
+      modelSelection: selection,
+      modelTier: selection.tier ? tierDisclosure(selection.tier) : undefined,
+      previousModelTier: options.previousModelTier,
+      previousModelFallback: options.previousModelFallback,
       depth: options.depth ?? 1,
       parentAgentId: options.parentAgentId,
       workflowId: options.workflowId,
@@ -826,28 +899,29 @@ export class AgentManager {
         release();
         markLeft();
       },
-      cancel: () => {},
+      // enqueueBudget only registers; grant cannot run until the next pump,
+      // after this entry has been initialized and published in the queue.
+      cancel: enqueueBudget({
+        depth: record.depth ?? 1,
+        ready: () => pool === undefined || this.poolHasRoom(pool),
+        grant: (lease) => {
+          this.queue = this.queue.filter(e => e !== entry);
+          if (this.agents.get(id) !== record || record.status !== "queued") {
+            releaseBudget(lease);
+            entry.release();
+            return;
+          }
+          record.budgetLease = lease;
+          // Detached, and never rejects: a late failure (e.g. strict worktree
+          // isolation) lands on the record inside `launch`. The release waits
+          // for that startup to SETTLE: a release at grant time would wake a
+          // blocked `spawnAndWait` while `record.promise` was still undefined,
+          // and it would read a healthy agent as one that never ran.
+          void entry.start().then(() => entry.release(), () => entry.release());
+        },
+      }),
       left,
     };
-    entry.cancel = enqueueBudget({
-      depth: record.depth ?? 1,
-      ready: () => pool === undefined || this.poolHasRoom(pool),
-      grant: (lease) => {
-        this.queue = this.queue.filter(e => e !== entry);
-        if (this.agents.get(id) !== record || record.status !== "queued") {
-          releaseBudget(lease);
-          entry.release();
-          return;
-        }
-        record.budgetLease = lease;
-        // Detached, and never rejects: a late failure (e.g. strict worktree
-        // isolation) lands on the record inside `launch`. The release waits
-        // for that startup to SETTLE: a release at grant time would wake a
-        // blocked `spawnAndWait` while `record.promise` was still undefined,
-        // and it would read a healthy agent as one that never ran.
-        void entry.start().then(() => entry.release(), () => entry.release());
-      },
-    });
     this.queue.push(entry);
   }
 
@@ -954,6 +1028,24 @@ export class AgentManager {
     record.startGate = undefined;
     this.chargePool(record.chargedPool, 1);
 
+    // Hold the pool slot BEFORE awaiting admission, just as for worktree creation.
+    try {
+      if (options.modelSelection?.tierBinding && !options.modelSelection.tierAdmitted) {
+        const block = await admitModelSelection(options.modelSelection, ctx.modelRegistry, pi.events);
+        record.modelTier = options.modelSelection.tier ? tierDisclosure(options.modelSelection.tier) : undefined;
+        record.modelFallback = options.modelSelection.fallback;
+        if (block) throw new Error(`${modelSelectionNote(record)} ${describeBlock(block)} The agent was not started.`);
+        if (record.abortController?.signal.aborted || options.signal?.aborted) throw new Error("Agent aborted during model admission.");
+      }
+      if (record.modelTier) {
+        record.invocation ??= {};
+        Object.assign(record.invocation, describeSelection(options.modelSelection, ctx.modelRegistry));
+      }
+    } catch (error) {
+      this.chargePool(record.chargedPool, -1);
+      throw error;
+    }
+
     // Worktree isolation: try to create a temporary git worktree. Strict —
     // fail loud if not possible (no silent fallback to main tree). Done BEFORE
     // the run is kicked off so a failure doesn't leave a half-running agent.
@@ -1035,8 +1127,10 @@ export class AgentManager {
 
     const promise = runAgent(ctx, type, prompt, {
       pi,
+      homeDir: options.homeDir ?? this.homeDir,
       agentId: id,
-      model: options.model,
+      model: options.modelSelection?.model,
+      modelSelection: record.modelSelection!,
       maxTurns: options.maxTurns,
       isolated: options.isolated,
       inheritContext: options.inheritContext,
@@ -1104,7 +1198,9 @@ export class AgentManager {
           const requested = record.invocation.requestedThinking ?? record.invocation.thinking;
           Object.assign(
             record.invocation,
-            isVirtualModel(session.model) ? describeVirtualModel(session.model) : describeModel(session.model),
+            record.modelTier?.kind === "routed" && record.modelTier.admitted
+              ? describeSelection(options.modelSelection, ctx.modelRegistry)
+              : isVirtualModel(session.model) ? describeVirtualModel(session.model) : describeModel(session.model),
           );
           // Guarded for the reason above: a session that reports no level keeps
           // the request rather than losing it. Overwriting unconditionally would
@@ -1117,6 +1213,9 @@ export class AgentManager {
             }
           }
         }
+        // The transcript says it too: it is what someone opens to find out what ran.
+        if (record.modelFallback && record.outputFile) appendModelFallbackEntry(record.outputFile, record.id, record.modelFallback);
+        if (record.modelTier && record.outputFile) appendModelTierEntry(record.outputFile, record.id, record.modelTier);
         // Flush any steers that arrived before the session was ready
         if (record.pendingSteers?.length) {
           for (const msg of record.pendingSteers) {
@@ -1862,6 +1961,8 @@ export class AgentManager {
       description: record.description,
       sessionFile: record.sessionFile,
       completedAt: record.completedAt ?? this.clock.now(),
+      ...(record.modelTier ? { modelTier: record.modelTier } : {}),
+      ...(record.modelFallback ? { modelFallback: record.modelFallback } : {}),
     });
     // Bound the memory a long session can accumulate. Oldest first, since the
     // agent someone still wants to reach is the one they used most recently.
@@ -1882,6 +1983,8 @@ export class AgentManager {
       status: record.status,
       evictedAfterMin: Math.max(0, Math.round((this.clock.now() - completedAt) / 60_000)),
       transcript: record.outputFile ?? record.sessionFile,
+      ...(record.modelTier ? { modelTier: record.modelTier } : {}),
+      ...(record.modelFallback ? { modelFallback: record.modelFallback } : {}),
     });
     while (this.evictedNotes.size > MAX_EVICTED_NOTES) {
       const oldest = this.evictedNotes.keys().next().value;