@animalabs/agent-framework 0.26.0 → 0.26.1

package/src/framework.ts

@@ -116,6 +116,7 @@ import type { WorkspaceModule } from './modules/workspace/index.js';
 import type { ToolResultGuard, WithheldSpill } from './tool-result-guard.js';
 import {
   nonErrorResultText,
+  shownToScript,
   toolResultDataToHistoryString,
   truncateForHistory,
   DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS,
@@ -1239,6 +1240,10 @@ const RETRY_CANCELLED_BY_STOP = 'a retry waiting while the framework was stoppin
  *  revive the earlier lifecycle's turn in the next one. */
 const RETRY_ACROSS_RESTART = 'a retry waiting while the framework was stopped and started again is dropped before it sends anything';
 
+/** The reason on the inference:aborted that ends a turn whose continuation
+ *  was dropped before it started, other than by an abandon or a stop. */
+const CONTINUATION_DROPPED = "a turn's continuation was dropped before it started";
+
 /** One frame's window while it holds a turn with no stream and one of its
  *  checks is ahead (AgentFramework.checkAhead). `abandoned` is an operator's
  *  quiesce abandon that reached the turn there, which the frame's check
@@ -1603,14 +1608,26 @@ export interface HostModeStatus {
   quiesced: boolean;
   reason?: string;
   since?: number;
-  /** True when no turn is alive (activeTurnTokens empty — the token spans
-   * dequeue → settled teardown, strictly wider than activeStreams). */
+  /** True when no turn is alive: no turn token (the token spans dequeue →
+   * settled teardown, strictly wider than activeStreams) and no continuation
+   * of a turn on its way to its start (a budget restart's or a tool-result
+   * guard's retry, queued, held by a provider hold, parked or in a scheduler
+   * pass), and no wake parked on provider admission. It covers the
+   * framework's own turns: a caller of the direct Agent API
+   * (`Agent.runInference`) owns its turns' timing. */
   drained: boolean;
   activeTurns: number;
+  /** The agents with a turn alive, the ones `activeTurns` counts, sorted:
+   * each from its turn's dequeue to its settled teardown, so a turn in its
+   * hooks or compile, one finishing its deliveries, or one whose continuation
+   * is on its way to its start, is listed. These are the agents an abandon or
+   * a stop() made now would find mid-turn. */
+  activeTurnAgents: string[];
   /** Wakes that own provider admission while waiting for an in-flight
    * auxiliary call — no turn token yet, but a turn is one settle away. The
    * admission continuation rechecks quiesce and requeues them; `drained`
-   * is false until it has. */
+   * is false until it has. A parked continuation of a turn is counted here
+   * and, as a turn alive, in `activeTurns` and `activeTurnAgents`. */
   parkedAdmissions: number;
   /** Inference requests parked by the quiesce wake gate (while quiesced), or
    * simply queued (while serving — non-zero right after a resume until the
@@ -1832,6 +1849,9 @@ interface ProviderAccelerationCooldown {
   /** Armed by an auxiliary (compression) failure with no primary involved:
    *  release reopens auxiliary admission without synthesising an inference. */
   auxiliaryOrigin?: boolean;
+  /** Its held requests were taken out by dropContinuations: release reopens
+   *  admission without synthesising an inference in their place. */
+  emptiedByDrop?: boolean;
   /** Set when this hold is a provider wait (a stated retry-after) for the
    *  agent's primary model: it holds primary turns only. Auxiliary calls are
    *  admitted per model by the provider waits themselves, so a compression
@@ -2065,8 +2085,8 @@ const SCRIPT_TEXT_ANSWER_ENVELOPE_BYTES = Buffer.byteLength(
  * memoryMaxBytes. So the figure moves with memoryMaxBytes. What it can't
  * count: a result's `structured` value, which the measure leaves out and the
  * answer carries as JSON beside the content, and that result's blocks past
- * their text, which the answer carries as they are (each further block's
- * keys, an image's data); nesting past 2,000 levels; and a
+ * their text, which the answer carries as the script lane gives them (each
+ * further block's keys, an image's data); nesting past 2,000 levels; and a
  * parse that needs more of the script's memory than is free, as for JSON
  * dense in small objects or a script already holding most of its memory.
  * Such a result, or one past the figure that doesn't fit, reaches the script
@@ -2378,6 +2398,11 @@ type McpRestartClaim = { readonly restarting: string; endedBy?: string };
 /** Why the framework cancelled a stream it owns: the mark it records, by
  *  agent and stream, before the cancel, for the stream's terminal to read. */
 type FrameworkCancelKind = 'turn_ended' | 'budget_restart' | 'quiesce_abandoned' | 'shutdown';
+/** How a turn whose continuation is dropped before it starts ends: an
+ *  operator's quiesce abandon or stop() settles it as a stop ends a turn's
+ *  start; any other drop ends it as a start dropped before it sends anything.
+ *  `why` is said in the line its end logs. */
+type ContinuationDrop = { kind: 'quiesce_abandoned' | 'shutdown' | 'dropped'; why: string };
 
 /** What opened a channel the agent didn't ask to open
  *  (recordChannelAutoOpenNotice). */
@@ -2808,6 +2833,15 @@ export class AgentFramework {
   // and its settle except that turn's own blocks, and, before its checkpoint,
   // the inputs its start writes (flushForStart).
   private activeTurnTokens: Map<string, number> = new Map();
+  /** Each running scheduler pass's requests, which it took from
+   *  pendingRequests: it holds those of the agents it hasn't taken up yet
+   *  while it awaits an earlier agent's start, so a continuation among them
+   *  is still on its way (pendingContinuationAgents). */
+  private passRequests: Set<Map<string, InferenceRequest[]>> = new Set();
+  /** Continuations whose start waits on provider admission behind an
+   *  auxiliary call, in no queue meanwhile. A drop takes one out and gives
+   *  its admission back; the park, woken, then finds it gone. */
+  private parkedContinuations: Set<InferenceRequest> = new Set();
   /** Each turn whose settle has ended it (settleAgent, endDroppedTurn), for
    *  its agent's scripts: its start's teardown can still hold the agent's
    *  token, and a turn that has ended isn't live (liveTurns). A later start
@@ -2951,9 +2985,17 @@ export class AgentFramework {
   // config.codeExecution.enabled: its settings, and every agent's scripts,
   // each in a process of its own on the engine (AgentScripts). Waiters
   // resolve script-inner tool calls dispatched through the normal
-  // dispatchToolCall path.
+  // dispatchToolCall path. A waiter's route is where the dispatch sent its
+  // call: `toServer` is set when it went to a server's own tool (an MCPL or
+  // MCP-only peer's), so the script lane's exit treats every other result as
+  // a module's (scriptResultAnswer), by where the call went rather than by a
+  // name lookup a connect or disconnect can change while it runs. A
+  // framework tool that talks to a server itself, such as a channel tool,
+  // builds its own result, which counts as a module's. A caller of
+  // dispatchScriptToolCall that passes no route gets one left false, the
+  // reading that withholds more.
   private codeExecution: { settings: IsolateSettings; scripts: AgentScripts } | null = null;
-  private scriptToolWaiters: Map<string, (result: ToolResult) => void> = new Map();
+  private scriptToolWaiters: Map<string, { resolve: (result: ToolResult) => void; route: { toServer: boolean } }> = new Map();
   /** Per agent, a round that called code_execution and waits for those calls'
    *  results before its prose is routed (ScriptRound). */
   private scriptRounds: Map<string, ScriptRound> = new Map();
@@ -4005,6 +4047,16 @@ export class AgentFramework {
     // framework must not keep up to the whole ledger budget referenced.
     this.toolImageLedgers.clear();
 
+    // A turn whose continuation is still on its way ends with the stop, as
+    // a turn's start a stop reaches does: the continuation would start only
+    // after a start(), in a lifecycle where its logical turn is gone
+    // (openLogical, below). Before the holds and the parks go, so the
+    // continuation leaves them with its turn.
+    step(() => {
+      for (const agentName of this.pendingContinuationAgents()) {
+        this.dropContinuations(agentName, { kind: 'shutdown', why: 'the framework is stopping' });
+      }
+    });
     // A stopped host must never hang behind its own cooldown.
     step(() => this.cancelProviderAdmission());
     // An open logical turn doesn't survive a stop: a start after a restart
@@ -4660,7 +4712,8 @@ export class AgentFramework {
       // The stated wait (recorded above for agent.model) set this hold's
       // length: an operator release of it returns the hold to AF's own pacing.
       ...(pacing?.stated ? { statedWait: { model: agent.model, ownUntil: now + pacing.ownMs } } : {}),
-      ...(auxiliary && (!existing || existing.auxiliaryOrigin) ? { auxiliaryOrigin: true } : {}) });
+      ...(auxiliary && (!existing || existing.auxiliaryOrigin) ? { auxiliaryOrigin: true } : {}),
+      ...(existing?.emptiedByDrop && held.length === 0 ? { emptiedByDrop: true } : {}) });
     if (auxiliary && !existing) {
       console.error(`[provider-cooldown] agent=${agent.name} host hold (${hostHold!.reason}) from an auxiliary call — ` +
         `holding primary/auxiliary for ${delayMs}ms`);
@@ -4767,9 +4820,12 @@ export class AgentFramework {
           ? `no longer holds primary turns: the primary model is now ${model} (the wait stays recorded)`
           : `primary hold ended after ${Date.now() - cooldown.startedAt}ms`));
     }
-    if (cooldown.auxiliaryOrigin && cooldown.heldRequests.length === 0) {
-      // Nobody asked for an inference while parked: just reopen the gate.
-      console.error(`[provider-cooldown] agent=${agentName} auxiliary hold released after ${Date.now() - cooldown.startedAt}ms`);
+    if ((cooldown.auxiliaryOrigin || cooldown.emptiedByDrop) && cooldown.heldRequests.length === 0) {
+      // Nobody asked for an inference while parked, or what was held was a
+      // continuation since dropped with its turn: just reopen the gate. A
+      // primary the hold left pending won't run, so its recovery ends.
+      console.error(`[provider-cooldown] agent=${agentName} ${cooldown.auxiliaryOrigin ? 'auxiliary hold' : 'hold, its held continuation dropped,'} released after ${Date.now() - cooldown.startedAt}ms`);
+      if (cooldown.emptiedByDrop) this.endPendingPrimary(agentName);
       this.flushAuxiliaryAdmission(agentName);
       return;
     }
@@ -6446,14 +6502,54 @@ export class AgentFramework {
     return n;
   }
 
+  /**
+   * A continuation the framework makes for a turn (a budget restart's, which
+   * it queues, or a tool-result guard's retry, which its frame starts at
+   * once) holds no turn token until its start takes one. Once its turn's
+   * frame has let go of its token, its start can wait in the queue, a
+   * provider hold (a retry too, when a wait holds it), a park on admission
+   * or a scheduler pass's hands. Its turn is alive meanwhile. These are the
+   * agents with one on its way. A
+   * `tool_results_ready` continuation follows a tool round left waiting with
+   * no stream, which only the direct Agent API makes (Agent's
+   * runInferenceWithInjections; the framework's own rounds wait with their
+   * stream, enterWaitingForTools). Its caller owns that turn's timing, so it
+   * isn't counted.
+   */
+  private pendingContinuationAgents(): Set<string> {
+    const agents = new Set<string>();
+    const add = (r: InferenceRequest): void => { if (resumesLogicalTurn(r.reason)) agents.add(r.agentName); };
+    // Read defensively: a framework built from the prototype, as the
+    // operator tests build one, sets none of these.
+    for (const r of this.pendingRequests ?? []) add(r);
+    for (const cooldown of this.providerAccelerationCooldowns?.values() ?? []) for (const r of cooldown.heldRequests) add(r);
+    for (const r of this.parkedContinuations ?? []) add(r);
+    for (const pass of this.passRequests ?? []) for (const requests of pass.values()) for (const r of requests) add(r);
+    return agents;
+  }
+
+  /** The agents with a turn alive: holding a turn token, or with a
+   *  continuation of their turn on its way. */
+  private turnHolders(): Set<string> {
+    const holders = this.pendingContinuationAgents();
+    for (const name of this.activeTurnTokens.keys()) holders.add(name);
+    return holders;
+  }
+
+  private hasTurn(agentName: string): boolean {
+    return this.activeTurnTokens.has(agentName) || this.pendingContinuationAgents().has(agentName);
+  }
+
   getHostModeStatus(): HostModeStatus {
     const parkedAdmissions = this.parkedAdmissionCount();
+    const holders = this.turnHolders();
     return {
       quiesced: this.quiesced,
       ...(this.quiesceReason ? { reason: this.quiesceReason } : {}),
       ...(this.quiescedAt !== undefined ? { since: this.quiescedAt } : {}),
-      drained: this.activeTurnTokens.size === 0 && parkedAdmissions === 0,
-      activeTurns: this.activeTurnTokens.size,
+      drained: holders.size === 0 && parkedAdmissions === 0,
+      activeTurns: holders.size,
+      activeTurnAgents: [...holders].sort(),
       parkedAdmissions,
       gatedRequests: this.pendingRequests.filter((r) => !isTurnContinuation(r.reason)).length,
       backgroundScripts: this.codeExecution?.scripts.leftRunning() ?? 0,
@@ -6472,8 +6568,9 @@ export class AgentFramework {
   /**
    * Enter quiesce mode: write the deferred-write queue, persist the flag,
    * suppress gate deliveries, pause all MCPL data planes, and wait for
-   * in-flight turns to settle (turn-alive is `activeTurnTokens`, which spans
-   * dequeue → settled teardown). Idempotent, but for the queue's write, which
+   * in-flight turns to settle (turn-alive is a turn token, which spans
+   * dequeue → settled teardown, or a continuation of the turn on its way to
+   * its start: turnHolders). Idempotent, but for the queue's write, which
    * every call makes first: when the queue can't reach disk, because its
    * write fails or it's over the cap, the call rejects with a
    * QuiesceBlockedError and the host's mode as it was, unless it has
@@ -6483,7 +6580,10 @@ export class AgentFramework {
    * On drain timeout the host STAYS quiesced (`drained: false` in the
    * result); with `abandon: true` the undrained streams are cancelled via a
    * dedicated cancel kind that settles the turn without feeding the
-   * inference-failure accounting.
+   * inference-failure accounting, and a turn whose continuation hasn't
+   * started ends with the continuation dropped. Drain covers the framework's
+   * own turns: a caller of the direct Agent API (`Agent.runInference`) owns
+   * its turns' timing.
    */
   async quiesce(opts?: {
     reason?: string;
@@ -6509,13 +6609,13 @@ export class AgentFramework {
       // out undrained must be escalatable with a second quiesce({abandon})
       // without resume()+re-quiesce (which would reopen data planes and
       // release parked wakes mid-surgery).
-      if (opts?.abandon && this.activeTurnTokens.size > 0) {
+      if (opts?.abandon && this.turnHolders().size > 0) {
         const unabandonable = await this.abandonActiveTurns();
         this.emitTrace({
           type: 'host:quiesce',
           ...(this.quiesceReason ? { reason: this.quiesceReason } : {}),
-          drained: this.activeTurnTokens.size === 0,
-          activeTurns: this.activeTurnTokens.size,
+          drained: this.turnHolders().size === 0,
+          activeTurns: this.turnHolders().size,
           abandoned: true,
           ...(unabandonable.length > 0 ? { unabandonable } : {}),
         });
@@ -6541,7 +6641,7 @@ export class AgentFramework {
     this.lastUnabandonable = [];
     console.error(
       `[host-mode] quiescing${opts?.reason ? ` (${opts.reason})` : ''}: parking wakes, ` +
-      `pausing MCPL data planes, draining ${this.activeTurnTokens.size} in-flight turn(s)`,
+      `pausing MCPL data planes, draining ${this.turnHolders().size} in-flight turn(s)`,
     );
     this.eventGate?.setQuiesced(true);
     for (const connection of this.mcplServerRegistry?.getAllServers() ?? []) {
@@ -6567,7 +6667,7 @@ export class AgentFramework {
     while (
       this.quiesced &&
       !this.queue?.isClosed &&
-      (this.activeTurnTokens.size > 0 || this.parkedAdmissionCount() > 0) &&
+      (this.turnHolders().size > 0 || this.parkedAdmissionCount() > 0) &&
       Date.now() < deadline
     ) {
       await new Promise((resolve) => setTimeout(resolve, 250));
@@ -6591,7 +6691,7 @@ export class AgentFramework {
 
     let abandoned = false;
     let unabandonable: string[] = [];
-    if (this.activeTurnTokens.size > 0 && opts?.abandon) {
+    if (this.turnHolders().size > 0 && opts?.abandon) {
       abandoned = true;
       unabandonable = await this.abandonActiveTurns();
       if (!this.quiesced) return this.getHostModeStatus();
@@ -6624,7 +6724,18 @@ export class AgentFramework {
    *  the already-quiesced escalation path. */
   private async abandonActiveTurns(): Promise<string[]> {
     const unabandonable: string[] = [];
+    // A turn whose continuation is still on its way ends with the
+    // continuation dropped. Its stream has ended; a frame still letting go of
+    // its token ends on its own, and settles nothing, since it handed the turn
+    // to the continuation.
+    const handedOff = new Set<string>();
+    for (const agentName of this.pendingContinuationAgents()) {
+      console.error(`[host-mode] abandoning ${agentName}'s turn before its continuation starts: the continuation is dropped`);
+      this.dropContinuations(agentName, { kind: 'quiesce_abandoned', why: 'its turn was abandoned' });
+      handedOff.add(agentName);
+    }
     for (const agentName of [...this.activeTurnTokens.keys()]) {
+      if (handedOff.has(agentName)) continue;
       const agent = this.agents.get(agentName);
       const state = agent?.state;
       const stream = state && 'stream' in state ? state.stream : undefined;
@@ -8698,6 +8809,9 @@ export class AgentFramework {
       this.activeTurnTokens.delete(agent.name);
       this.activeTurnTriggers.delete(agent.name);
       this.logicalTurnToolCalls.delete(agent);
+      // A continuation of its turn still on its way goes too: the run, and
+      // with it the turn, has ended above.
+      this.dropContinuations(agent.name, null);
     }
   }
 
@@ -10503,7 +10617,7 @@ export class AgentFramework {
     const busy: string[] = [];
     for (const [name, a] of this.agents) {
       if (a.state.status !== 'idle') busy.push(`${name} is ${a.state.status}`);
-      else if (this.activeTurnTokens.has(name)) busy.push(`${name} is idle+turn-alive`);
+      else if (this.hasTurn(name)) busy.push(`${name} is idle+turn-alive`);
     }
     for (const name of this.activeTurnTokens.keys()) {
       if (!this.agents.has(name)) busy.push(`${name} is turn-alive`);
@@ -11660,7 +11774,7 @@ export class AgentFramework {
         // was killed while the call ran: the result reaches no one, but the
         // call did finish.
         this.toolLifecycleEmitter?.onResult(event.agentName, event.callId, event.result);
-        scriptWaiter(event.result);
+        scriptWaiter.resolve(event.result);
         return;
       }
 
@@ -12105,7 +12219,25 @@ export class AgentFramework {
               this.streamBoundaryEnds.get(currentState.stream)?.('turn_ended');
             }
             this.emitTrace({ type: 'inference:turn_ended', agentName: agent.name });
+          } else if ((overBudget || overPhysical) && this.providerAdmissionClosed) {
+            // A stopping framework starts no continuation: the turn ends with
+            // its stream, as stop() ends a live stream's turn.
+            if (currentState.stream) this.frameworkCancelledStreams.set(`${agent.name}:${agent.streamId}`, 'shutdown');
+            agent.cancelStream();
           } else if (overBudget || overPhysical) {
+            // The continuation is queued, and the stream cancelled, before the
+            // boundary's usage report and the restart's trace, so a listener
+            // that stops or quiesces the host on either finds the turn waiting
+            // for its continuation, with nothing left of the stream to end.
+            const continuation: InferenceRequest = {
+              agentName: agent.name,
+              reason: 'context_budget_restart',
+              source: 'framework',
+              timestamp: Date.now(),
+              suppressProse: this.activeTurnTriggers.get(agent.name)?.suppressProse,
+              silentHeartbeat: this.activeTurnTriggers.get(agent.name)?.silentHeartbeat,
+            };
+            this.pendingRequests.push(continuation);
             // Context budget exceeded: break the stream, let compile() compress.
             // Mark the cancel as framework-initiated BEFORE cancelling: the
             // membrane delivers `aborted` before the restart bumps streamId,
@@ -12113,13 +12245,19 @@ export class AgentFramework {
             // a terminal failure — rejecting an ephemeral's promise mid-run
             // and emitting a spurious inference:exhausted (same race shape as
             // endTurn above).
-            if (currentState.stream) {
-              this.frameworkCancelledStreams.set(`${agent.name}:${agent.streamId}`, 'budget_restart');
-              // Its rounds were billed; the restart opens a fresh stream
-              // with its own usage.
-              this.streamBoundaryEnds.get(currentState.stream)?.(overBudget ? 'context_budget' : 'physical_window');
+            if (currentState.stream) this.frameworkCancelledStreams.set(`${agent.name}:${agent.streamId}`, 'budget_restart');
+            try {
+              agent.cancelStream();
+            } catch (error) {
+              // The cancel failed and the stream is still live, so the turn
+              // has no continuation: take it back out of the queue.
+              this.pendingRequests = this.pendingRequests.filter((r) => r !== continuation);
+              throw error;
+            } finally {
+              // Its rounds were billed, even when the cancel throws; the
+              // restart opens a fresh stream with its own usage.
+              if (currentState.stream) this.streamBoundaryEnds.get(currentState.stream)?.(overBudget ? 'context_budget' : 'physical_window');
             }
-            agent.cancelStream();
             this.emitTrace({
               type: 'inference:stream_restarted',
               agentName: agent.name,
@@ -12130,14 +12268,6 @@ export class AgentFramework {
               inputTokens: overBudget ? agent.lastStreamInputTokens : projectedRealTokens,
               budget: overBudget ? agent.maxStreamTokens : (agent.physicalWindowTokens ?? 0),
             });
-            this.pendingRequests.push({
-              agentName: agent.name,
-              reason: 'context_budget_restart',
-              source: 'framework',
-              timestamp: Date.now(),
-              suppressProse: this.activeTurnTriggers.get(agent.name)?.suppressProse,
-              silentHeartbeat: this.activeTurnTriggers.get(agent.name)?.silentHeartbeat,
-            });
           } else if (currentState.stream) {
             // What this round appends is in the next call's prompt. If that
             // call reports no prompt, the next boundary projects it from the
@@ -12987,6 +13117,8 @@ export class AgentFramework {
    */
   private disposeConversationAgent(agentName: string): void {
     this.closingConversationAgents.delete(agentName);
+    // A continuation of its turn still on its way goes with it.
+    this.dropContinuations(agentName, { kind: 'dropped', why: 'its agent was disposed' });
     const channelId = this.conversationAgentHomes.get(agentName);
     const agent = this.agents.get(agentName);
     // A fork stop() ends can still be running: its stream, its tool round.
@@ -13519,9 +13651,18 @@ export class AgentFramework {
       recordReceipt: (record) => {
         // Written now, not at the throttled flush: an acknowledged acceptance
         // must not lose its receipt, the subject's birth, or (deferred) the
-        // accepted work itself to a crash. A failure here fails the acceptance.
+        // accepted work itself to a crash. A failure here fails the answer:
+        // the coalescer keeps the receipt, and the producer's retry writes it
+        // again, with the subject's state as it is then. So a record whose
+        // write failed leaves the list: a later write would carry it after
+        // the batch it holds had moved on.
         this.coalescingRecentReceipts.push(record);
-        this.store.setStateJson(COALESCING_RECENT_ID, this.coalescingRecentReceipts);
+        try {
+          this.store.setStateJson(COALESCING_RECENT_ID, this.coalescingRecentReceipts);
+        } catch (error) {
+          this.coalescingRecentReceipts.pop();
+          throw error;
+        }
       },
       // The acceptance of coalesced work (deferred included) is observed
       // here, once; its later delivery reuses the frozen envelope.
@@ -13628,6 +13769,9 @@ export class AgentFramework {
       this.store.setStateJson(COALESCING_RECENT_ID, []);
     } catch (err) {
       console.error('[coalescing] could not persist coalescing state:', err);
+      // Still unsaved: the next persist, or the stop's flush, writes it. No
+      // timer of its own, so a store that keeps failing isn't retried here.
+      this.coalescingSnapshotDirty ??= snapshot;
     }
   }
 
@@ -14253,17 +14397,28 @@ export class AgentFramework {
     return undefined;
   }
 
+  /** One scheduler pass, whose requests stay visible as on their way until
+   *  it takes their agent up (passRequests). */
   private async processInferenceRequests(): Promise<void> {
     if (this.pendingRequests.length === 0) {
       return;
     }
+    const requestsByAgent = new Map<string, InferenceRequest[]>();
+    this.passRequests?.add(requestsByAgent);
+    try {
+      await this.runInferencePass(requestsByAgent);
+    } finally {
+      this.passRequests?.delete(requestsByAgent);
+    }
+  }
+
+  private async runInferencePass(requestsByAgent: Map<string, InferenceRequest[]>): Promise<void> {
 
     const STALE_REQUEST_MS = 30_000;
     const now = Date.now();
     const state = this.createFrameworkState();
 
     // Group requests by agent
-    const requestsByAgent = new Map<string, InferenceRequest[]>();
     for (const req of this.pendingRequests) {
       const existing = requestsByAgent.get(req.agentName) ?? [];
       existing.push(req);
@@ -14276,6 +14431,13 @@ export class AgentFramework {
     // Check each agent
     for (const [agentName, groupedRequests] of requestsByAgent) {
       let requests = groupedRequests;
+      // Taken up now: from here to its start's turn token (or its hold or
+      // park) nothing awaits, so the requests leave the pass's map, which
+      // shows only what the pass still holds while it awaits a start.
+      requestsByAgent.delete(agentName);
+      // A drop while this pass awaited an earlier agent's start can have
+      // taken every request of this agent's (dropContinuations).
+      if (requests.length === 0) continue;
       const agent = this.agents.get(agentName);
       if (!agent) {
         // Agent not found — request is orphaned. Emit warning and drop.
@@ -14288,6 +14450,10 @@ export class AgentFramework {
           oldestRequestAge: now - oldest,
         });
         console.error(`[inference-dropped] agent=${agentName} reason=agent_not_found requests=${requests.length}`);
+        // A continuation among them leaves its turn to end here.
+        if (requests.some((r) => resumesLogicalTurn(r.reason))) {
+          this.endContinuedTurn(agentName, { kind: 'dropped', why: 'its agent is gone' });
+        }
         continue;
       }
 
@@ -14377,7 +14543,10 @@ export class AgentFramework {
         requests.push(...passThrough);
       }
 
-      const turnAlive = !budgetRestart && this.activeTurnTokens.has(agentName);
+      // Turn-alive includes a continuation of the agent's turn still on its
+      // way elsewhere (a park, another pass's hands): a fresh wake waits for
+      // it, as for a turn holding its token.
+      const turnAlive = !budgetRestart && this.hasTurn(agentName);
       const providerGate = this.providerGates?.get(agentName);
       // A primary can own provider admission while yielding to an already in-flight
       // auxiliary call. Keep this agent's later wakes queued, but do not block the
@@ -14455,9 +14624,12 @@ export class AgentFramework {
           `[inference-dropped] agent=${agentName} reason=policy-skip ` +
           `requests=${requests.length} triggers=${requests.map((r) => r.reason).join(',')}`,
         );
-        // A context-budget restart inherits the predecessor's EventGate liveness.
-        // If policy drops the queued successor, no driveStream remains to release it.
-        if (budgetRestart) this.eventGate?.onInferenceEnded(agentName);
+        // A continuation inherits its predecessor's EventGate liveness and
+        // logical turn. If policy drops it, no driveStream remains to end them,
+        // so its turn ends here (endContinuedTurn).
+        if (requests.some((r) => resumesLogicalTurn(r.reason))) {
+          this.endContinuedTurn(agentName, { kind: 'dropped', why: 'the inference policy dropped its continuation' });
+        }
         this.endPendingPrimary(agentName);
         continue;
       }
@@ -16912,7 +17084,12 @@ export class AgentFramework {
         // Do not await inside processInferenceRequests: one slow auxiliary call for
         // this resident must not block events or other residents. Admission stays
         // owned and the continuation receives it after the in-flight call settles.
+        const parkedContinuation = trigger !== undefined && resumesLogicalTurn(trigger.reason);
+        if (parkedContinuation) this.parkedContinuations.add(trigger);
         void this.waitForAuxiliaryIdle(agent.name).then(async () => {
+          // A continuation dropped while it was parked left the set then, with
+          // its admission given back.
+          if (parkedContinuation && !this.parkedContinuations.delete(trigger)) return;
           if (this.providerAdmissionClosed) {
             this.releasePrimaryProviderGate(agent.name);
             return;
@@ -17072,6 +17249,93 @@ export class AgentFramework {
     }
   }
 
+  /**
+   * Drop every continuation of `agentName`'s turn still on its way, wherever
+   * it waits: the queue, a provider hold (which, left empty, then releases
+   * with nothing to run), a park on admission (whose admission it gives
+   * back), or a scheduler pass's hands (which then never reach it). If one
+   * was there, the turn ends (endContinuedTurn), unless `drop` is null: the
+   * caller has ended the turn already.
+   */
+  private dropContinuations(agentName: string, drop: ContinuationDrop | null): void {
+    const isContinuation = (r: InferenceRequest): boolean => r.agentName === agentName && resumesLogicalTurn(r.reason);
+    let dropped = false;
+    const take = (requests: InferenceRequest[]): InferenceRequest[] => {
+      const left = requests.filter((r) => !isContinuation(r));
+      if (left.length < requests.length) dropped = true;
+      return left;
+    };
+    this.pendingRequests = take(this.pendingRequests);
+    const hold = this.providerAccelerationCooldowns.get(agentName);
+    if (hold) {
+      const held = hold.heldRequests.length;
+      hold.heldRequests = take(hold.heldRequests);
+      if (held > 0 && hold.heldRequests.length === 0) hold.emptiedByDrop = true;
+    }
+    for (const parked of [...this.parkedContinuations]) {
+      if (!isContinuation(parked)) continue;
+      this.parkedContinuations.delete(parked);
+      this.releasePrimaryProviderGate(agentName);
+      dropped = true;
+    }
+    for (const pass of this.passRequests) {
+      const requests = pass.get(agentName);
+      if (!requests) continue;
+      const left = take(requests);
+      requests.length = 0;
+      requests.push(...left);
+    }
+    if (!dropped || !drop) return;
+    // A primary a provider hold left pending for what it released won't run
+    // now, when nothing else of the agent's waits (endPendingPrimary).
+    if (!this.pendingRequests.some((r) => r.agentName === agentName) && !this.providerAccelerationCooldowns.get(agentName)?.heldRequests.length) {
+      this.endPendingPrimary(agentName);
+    }
+    this.endContinuedTurn(agentName, drop);
+  }
+
+  /**
+   * End a turn whose continuation won't run. The frame that handed the turn
+   * to it kept the turn open for it: its logical turn, the EventGate's
+   * window, the tool-result guard's batch and recovery, its typing. An
+   * abandon or a stop of a registered agent settles the turn as it settles a
+   * turn's start (endStoppedStart: one inference:aborted, the turn settled,
+   * the gate released). Any other drop ends it as a start dropped before it
+   * sends anything ends. That frame, if it hasn't let go of its token yet,
+   * ends on its own and settles nothing. What was deferred for the agent
+   * lands now, or at that frame's end.
+   */
+  private endContinuedTurn(agentName: string, drop: ContinuationDrop): void {
+    console.error(`[turn-continuation] ${agentName}: its turn ends without its continuation: ${drop.why}`);
+    const agent = this.agents.get(agentName);
+    const startedAt = this.lastInferenceAt.get(agentName)?.startedAt ?? Date.now();
+    if (agent && drop.kind !== 'dropped') {
+      const routing = this.openLogical.get(agentName) ?? this.routingOf(agentName);
+      this.endStoppedStart(agent, { kind: drop.kind }, routing, startedAt, undefined, false);
+    } else {
+      const owner = this.activeTurnTokens.get(agentName);
+      this.abortDroppedTurn(agentName, owner ?? -1, drop.kind === 'dropped' ? CONTINUATION_DROPPED : drop.kind, startedAt);
+      this.channelRegistry?.stopTyping();
+      if (agent) {
+        agent.toolResultGuard.recovering = false;
+        if (agent.toolResultGuard.hasPending) {
+          try {
+            agent.toolResultGuard.abandon('aborted');
+          } catch (error) {
+            console.error(`[tool-result-guard] agent=${agentName} failed to record aborted batch:`, error);
+          }
+        }
+      }
+      const routing = this.openLogical.get(agentName) ?? this.turnRouting.get(agentName);
+      if (routing) this.endDroppedTurn(agentName, routing);
+      this.eventGate?.onInferenceEnded(agentName);
+    }
+    if (!this.activeTurnTokens.has(agentName) && this.deferredMessages.length > 0 && !this.pendingAssistantBlocks.has(agentName)) {
+      this.readdDrained(this.drainDeferredFor(agentName), 'continuation-drop flush');
+      this.ackDeferredWrites();
+    }
+  }
+
   /**
    * End a turn that beginAgentTurn drops before it sends anything. The turn
    * emitted inference:started, and listeners that bracket a turn, such as a
@@ -17122,7 +17386,7 @@ export class AgentFramework {
    */
   private endStoppedStart(
     agent: Agent,
-    stop: { kind: 'quiesce_abandoned' } | { kind: 'caller'; reason?: string },
+    stop: { kind: 'quiesce_abandoned' | 'shutdown' } | { kind: 'caller'; reason?: string },
     routing: TurnRouting,
     turnStartedAt: number,
     compiledRequest: NormalizedRequest | undefined,
@@ -17132,7 +17396,7 @@ export class AgentFramework {
      *  so the note says it was stopped before it finished. */
     opensTurn: boolean,
   ): void {
-    console.error(`[turn] ${agent.name}: ${stop.kind === 'caller' ? 'a stop' : 'a quiesce abandon'} reached the turn's start before it ${opensTurn ? 'sent anything' : 'finished'}; it ends there`);
+    console.error(`[turn] ${agent.name}: ${stop.kind === 'caller' ? 'a stop' : stop.kind === 'shutdown' ? "the framework's stop" : 'a quiesce abandon'} reached the turn's start before it ${opensTurn ? 'sent anything' : 'finished'}; it ends there`);
     this.channelRegistry?.stopTyping();
     // A start that continues a turn (a budget or guard restart) follows a
     // frame that kept the turn's tool-result batch, and the guard's recovery,
@@ -17160,7 +17424,7 @@ export class AgentFramework {
     if (stop.kind === 'caller') {
       this.settleDeliberateCancel({ ...common, reason: stop.reason ?? 'user', before: opensTurn ? 'sending' : 'finishing' });
     } else {
-      this.settleFrameworkCancel({ ...common, kind: 'quiesce_abandoned' });
+      this.settleFrameworkCancel({ ...common, kind: stop.kind });
     }
     const last = this.lastInferenceAt.get(agent.name);
     if (last?.startedAt === turnStartedAt) this.lastInferenceAt.set(agent.name, { ...last, endedAt: Date.now() });
@@ -17889,8 +18153,8 @@ export class AgentFramework {
       if (turnEnded) this.recordProviderAccelerationRecovery(agent, compiledRequest, end);
       // The accounting writes to the store, and a write that fails must not
       // skip what the boundary does after this call: the rest of a turn's
-      // end, or a restart's cancel and its request, and then the event's
-      // dispatch to modules.
+      // end, or a restart's trace (its cancel and its request come before
+      // this call), and then the event's dispatch to modules.
       try {
         if (turnEnded) {
           completeTurn(latestUsage, durationMs);
@@ -19891,7 +20155,11 @@ export class AgentFramework {
       // its ids when a successor turn has already taken the agent. A fork or
       // run deregistered while the host is quiesced leaves its queue to its
       // window's release at resume (drainDeferredFor).
-      if (frameReachedTerminal && this.deferredMessages.length > 0 && !this.pendingAssistantBlocks.has(agent.name)) {
+      // A frame that handed its turn to a continuation since dropped
+      // (endContinuedTurn, which couldn't land it while this frame held the
+      // token) lands it too: the turn is over.
+      const handedOffTurnOver = preserveEventGateForSuccessor && !this.hasTurn(agent.name);
+      if ((frameReachedTerminal || handedOffTurnOver) && this.deferredMessages.length > 0 && !this.pendingAssistantBlocks.has(agent.name)) {
         this.readdDrained(this.drainDeferredFor(agent.name), 'turn-end flush');
         this.ackDeferredWrites();
       }
@@ -20007,7 +20275,7 @@ export class AgentFramework {
         `puppet refused: the store is under live ${this.surgeryHold.verb} for ${this.surgeryHold.agentName} — retry when it completes`,
       );
     }
-    if (agent.state.status !== 'idle' || this.activeTurnTokens.has(agentName)) {
+    if (agent.state.status !== 'idle' || this.hasTurn(agentName)) {
       const shown = agent.state.status === 'idle' ? 'idle+turn-alive' : agent.state.status;
       throw new Error(
         `puppet refused: agent ${agentName} is ${shown} (requires idle — ` +
@@ -20958,9 +21226,10 @@ export class AgentFramework {
       if (!roundCalls.some((c) => c.name === counted.name && c.cause === counted.cause && c.refused === counted.refused)) roundCalls.push(counted);
     }
     if (refusal !== undefined) return refused(refusal);
+    const route = { toServer: false };
     const result = await this.dispatchScriptToolCall(
       agentName, toolName, input as Record<string, unknown>,
-      context.origin as ScriptCallOrigin | undefined, context.watch?.turnId,
+      context.origin as ScriptCallOrigin | undefined, context.watch?.turnId, route,
     );
     // Deferred: applied to the result of the code_execution call watching
     // the script — ending the turn mid-script would cancel the stream while
@@ -20971,7 +21240,7 @@ export class AgentFramework {
     const watching = context.watching ? context.watching() : context.watch;
     if (result.endTurn && watching) watching.endTurn = true;
     if (result.refused) return refused(result.error ?? `${toolName} was refused; nothing was done`);
-    const answer = await this.scriptResultAnswer(result, toolName);
+    const answer = await this.scriptResultAnswer(result, toolName, route.toServer);
     return SCRIPT_CALL_NO_RESULT.has(result) ? { ...answer, held: true } : answer;
   }
 
@@ -20980,14 +21249,18 @@ export class AgentFramework {
    * isError }`, one shape for every tool. `content` is
    * what the model would read: a structured result's blocks as the dispatch
    * gave them (the direct reading, with RFC-005's treatment of an MCPL peer's
-   * blocks), and otherwise one text block of the model's text, which for a
-   * failure is its error. `structuredContent` is the tool's own structured
+   * blocks there, bound to the server that sent them), a module's under
+   * history's reading of RFC-005 at every depth (shownToScript), and
+   * otherwise one text block of the model's text, which for a failure is its
+   * error. A module's is any result whose call the dispatch didn't send to
+   * a server (`toServer`, from the call's waiter). `structuredContent` is the
+   * tool's own structured
    * content where it sent one, `false`, `0` and `null` included, else null.
    * A result that can't be converted to JSON (a cyclic object, a BigInt),
    * which the dispatch's own check makes unlikely here, is a failure naming
    * the tool and saying the call itself completed.
    */
-  private async scriptResultAnswer(result: ToolResult, toolName: string): Promise<ToolAnswer> {
+  private async scriptResultAnswer(result: ToolResult, toolName: string, toServer: boolean): Promise<ToolAnswer> {
     const structured = Object.prototype.hasOwnProperty.call(result, 'structured');
     const isError = result.isError === true;
     // RFC-005 "eagerly lazy": a script receiving a result is the strongest
@@ -21004,7 +21277,10 @@ export class AgentFramework {
     // which isn't fetched.
     // Whenever the result's blocks reach the script: a structured failure's
     // included, as a module's error can carry content.
-    if ((!isError || structured) && Array.isArray(result.data) && this.resolveMcplTool(toolName) === null) {
+    // Not a server's result: a module's, whose blocks no dispatch has given
+    // RFC-005's treatment.
+    const fromModule = !toServer;
+    if ((!isError || structured) && Array.isArray(result.data) && fromModule) {
       const fetcher = this.getReferenceFetcher();
       for (const block of result.data) {
         const c = classifyBlock(block);
@@ -21031,6 +21307,20 @@ export class AgentFramework {
     // no blocks reads as its error text.
     if (structured && (!isError || (Array.isArray(result.data) && result.data.length > 0))) {
       content = Array.isArray(result.data) ? result.data : [];
+      // A module's blocks, such as an MCPL peer's it got from ctx.callTool
+      // and returns whole, are read as history reads a module's data: what
+      // RFC-005 governs, at any depth, as the script lane shows it, and
+      // anything else as sent. What a script prints comes back to the model,
+      // so no uri the model's lanes withhold reaches it. What this gives is
+      // a stub, a notice or the value itself, so a module that returns
+      // blocks it already gave has them left as they are.
+      if (fromModule) {
+        try {
+          content = JSON.parse(JSON.stringify(content, (_key, value: unknown) => shownToScript(value))) as unknown[];
+        } catch (err) {
+          return failed(err);
+        }
+      }
     } else {
       // As in history, a reference is its stub at any depth and inline data
       // claiming a uri or a disposition is withheld (RFC-005).
@@ -21067,7 +21357,9 @@ export class AgentFramework {
    * RFC-007: with an `origin`, observers see the call as they see a model
    * call (register, dispatch with its refusal sites, open; the terminal at
    * the waiter intercept), under the inner tool's own name and class.
-   * `turnId` is the turn the call was made in (dispatchToolCall).
+   * `turnId` is the turn the call was made in (dispatchToolCall). `route` is
+   * the waiter's: the dispatch sets `toServer` when it sends the call to a
+   * server.
    */
   private dispatchScriptToolCall(
     agentName: string,
@@ -21075,6 +21367,7 @@ export class AgentFramework {
     args: Record<string, unknown>,
     origin?: ScriptCallOrigin,
     turnId?: number,
+    route: { toServer: boolean } = { toServer: false },
   ): Promise<ToolResult> {
     return new Promise<ToolResult>((resolve) => {
       const callId = `pytc-${randomUUID()}`;
@@ -21102,9 +21395,12 @@ export class AgentFramework {
       }, safetyMs);
       safety.unref?.();
 
-      this.scriptToolWaiters.set(callId, (result) => {
-        clearTimeout(safety);
-        resolve(result);
+      this.scriptToolWaiters.set(callId, {
+        resolve: (result) => {
+          clearTimeout(safety);
+          resolve(result);
+        },
+        route,
       });
 
       const call = { id: callId, name: toolName, input: args };
@@ -21663,6 +21959,10 @@ export class AgentFramework {
     // Route MCPL tool calls to the appropriate server via prefix map
     const mcplMatch = this.resolveMcplTool(enrichedCall.name);
     if (mcplMatch && this.mcplServerRegistry) {
+      // A script's call: its waiter keeps that it went to a server, for the
+      // script lane's exit (scriptToolWaiters).
+      const scriptWaiter = this.scriptToolWaiters.get(enrichedCall.id);
+      if (scriptWaiter) scriptWaiter.route.toServer = true;
       this.dispatchMcplToolCall(agentName, enrichedCall, mcplMatch[0], mcplMatch[1]);
       return;
     }
@@ -27190,7 +27490,9 @@ export class AgentFramework {
     // generated JSON) stands in for what the server sent. An MCPL peer's
     // content blocks are the exception: what a script prints comes back to
     // the model, so each gets the treatment RFC-005 gives it on every lane
-    // the model reads. A standard peer's blocks reach the script as sent.
+    // the model reads, here, where the server that sent them is known. A
+    // module's blocks get it at the script lane's exit (scriptResultAnswer).
+    // A standard peer's blocks reach the script as sent.
     const forScript = this.scriptToolWaiters?.has(call.id) ?? false;
     const reading = async (result: { content?: unknown; isError?: boolean; structuredContent?: unknown }, mcpl: boolean): Promise<ToolResult> => {
       if (!forScript || !Object.prototype.hasOwnProperty.call(result, 'structuredContent')) {