@animalabs/agent-framework 0.25.0 → 0.26.1

package/dist/src/framework.js

@@ -45,7 +45,7 @@ import { safeSlice } from './safe-slice.js';
 import { SEND_TOOLS, bareToolName } from './send-tools.js';
 import { boundedErrorMessage, errorMessage } from './error-message.js';
 import { ProviderWaits, EVERY_MODEL, isReleaseModel, withoutControls } from './provider-waits.js';
-import { nonErrorResultText, toolResultDataToHistoryString, truncateForHistory, DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS, } from './tool-result-history.js';
+import { nonErrorResultText, shownToScript, toolResultDataToHistoryString, truncateForHistory, DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS, } from './tool-result-history.js';
 import { TOOL_IMAGE_REF_RE, ToolImageLedger, cutStoredToolResultToFit, formatKeptImageSlots, parseImagePlaceholders, sha256Hex, storedImageSlots, toolResultCutAt, toolResultShare, } from './tool-image-ledger.js';
 import { randomUUID, createHash } from 'node:crypto';
 import { describeCodeExecution, CODE_EXECUTION_TOOL_NAME, isolateSettings, validateCodeExecutionConfig, } from './code-execution/tool-definition.js';
@@ -712,6 +712,9 @@ const RETRY_CANCELLED_BY_STOP = 'a retry waiting while the framework was stoppin
  *  retry a failed compile across a stop() and a start(): the retry would
  *  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";
 function isTurnContinuation(reason) {
     return reason === 'context_budget_restart' || reason === 'tool_results_ready'
         || reason === 'tool_result_guard_retry';
@@ -1221,8 +1224,8 @@ const SCRIPT_TEXT_ANSWER_ENVELOPE_BYTES = Buffer.byteLength(JSON.stringify({ con
  * 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
@@ -1918,6 +1921,15 @@ export class AgentFramework {
     // and its settle except that turn's own blocks, and, before its checkpoint,
     // the inputs its start writes (flushForStart).
     activeTurnTokens = 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). */
+    passRequests = 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. */
+    parkedContinuations = 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
@@ -2050,7 +2062,15 @@ 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.
     codeExecution = null;
     scriptToolWaiters = new Map();
     /** Per agent, a round that called code_execution and waits for those calls'
@@ -3026,6 +3046,16 @@ export class AgentFramework {
         // Retained tool images are per-process by design; a retained stopped
         // 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
@@ -3695,7 +3725,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`);
@@ -3808,9 +3839,13 @@ 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;
         }
@@ -5393,14 +5428,60 @@ 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.
+     */
+    pendingContinuationAgents() {
+        const agents = new Set();
+        const add = (r) => { 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. */
+    turnHolders() {
+        const holders = this.pendingContinuationAgents();
+        for (const name of this.activeTurnTokens.keys())
+            holders.add(name);
+        return holders;
+    }
+    hasTurn(agentName) {
+        return this.activeTurnTokens.has(agentName) || this.pendingContinuationAgents().has(agentName);
+    }
     getHostModeStatus() {
         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,
@@ -5417,8 +5498,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
@@ -5428,7 +5510,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) {
         this.refuseOperatorAfterStop('quiesce');
@@ -5445,13 +5530,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 } : {}),
                 });
@@ -5476,7 +5561,7 @@ export class AgentFramework {
         this.quiescedAt = since;
         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() ?? []) {
             connection.pauseDataPlane();
@@ -5496,7 +5581,7 @@ export class AgentFramework {
         // continuation's quiesce recheck requeues it — wait for that to happen).
         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));
         }
@@ -5517,7 +5602,7 @@ export class AgentFramework {
         }
         let abandoned = false;
         let unabandonable = [];
-        if (this.activeTurnTokens.size > 0 && opts?.abandon) {
+        if (this.turnHolders().size > 0 && opts?.abandon) {
             abandoned = true;
             unabandonable = await this.abandonActiveTurns();
             if (!this.quiesced)
@@ -5547,7 +5632,19 @@ export class AgentFramework {
      *  the already-quiesced escalation path. */
     async abandonActiveTurns() {
         const unabandonable = [];
+        // 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();
+        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;
@@ -7496,6 +7593,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);
         }
     }
     /**
@@ -9104,7 +9204,7 @@ export class AgentFramework {
         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))
+            else if (this.hasTurn(name))
                 busy.push(`${name} is idle+turn-alive`);
         }
         for (const name of this.activeTurnTokens.keys()) {
@@ -10087,7 +10187,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;
             }
             // RFC-007: the call's terminal (completed / failed) — the result
@@ -10513,7 +10613,27 @@ export class AgentFramework {
                         }
                         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 = {
+                            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,
@@ -10521,13 +10641,23 @@ 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) {
+                        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');
+                        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,
@@ -10538,14 +10668,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
@@ -11306,6 +11428,8 @@ export class AgentFramework {
      */
     disposeConversationAgent(agentName) {
         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.
@@ -11780,9 +11904,19 @@ 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.
@@ -11904,6 +12038,9 @@ export class AgentFramework {
         }
         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;
         }
     }
     /** Serialize both lanes' admissions: create, edit and delete of one subject stay ordered. */
@@ -12532,15 +12669,26 @@ export class AgentFramework {
         }
         return undefined;
     }
+    /** One scheduler pass, whose requests stay visible as on their way until
+     *  it takes their agent up (passRequests). */
     async processInferenceRequests() {
         if (this.pendingRequests.length === 0) {
             return;
         }
+        const requestsByAgent = new Map();
+        this.passRequests?.add(requestsByAgent);
+        try {
+            await this.runInferencePass(requestsByAgent);
+        }
+        finally {
+            this.passRequests?.delete(requestsByAgent);
+        }
+    }
+    async runInferencePass(requestsByAgent) {
         const STALE_REQUEST_MS = 30_000;
         const now = Date.now();
         const state = this.createFrameworkState();
         // Group requests by agent
-        const requestsByAgent = new Map();
         for (const req of this.pendingRequests) {
             const existing = requestsByAgent.get(req.agentName) ?? [];
             existing.push(req);
@@ -12551,6 +12699,14 @@ 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.
@@ -12563,6 +12719,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;
             }
             const providerCooldown = this.providerAccelerationCooldowns?.get(agentName);
@@ -12652,7 +12812,10 @@ export class AgentFramework {
                 requests.length = 0;
                 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
@@ -12722,10 +12885,12 @@ export class AgentFramework {
                 // exactly this class of silent drop. One stderr line per drop.
                 console.error(`[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;
             }
@@ -15078,7 +15243,14 @@ 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;
@@ -15243,6 +15415,99 @@ 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.
+     */
+    dropContinuations(agentName, drop) {
+        const isContinuation = (r) => r.agentName === agentName && resumesLogicalTurn(r.reason);
+        let dropped = false;
+        const take = (requests) => {
+            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.
+     */
+    endContinuedTurn(agentName, drop) {
+        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
@@ -15297,7 +15562,7 @@ export class AgentFramework {
      *  continues one (a restart or a retry) may follow rounds already sent,
      *  so the note says it was stopped before it finished. */
     opensTurn) {
-        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,
@@ -15325,7 +15590,7 @@ export class AgentFramework {
             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)
@@ -16019,8 +16284,8 @@ export class AgentFramework {
                 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);
@@ -17933,7 +18198,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();
             }
@@ -18036,7 +18305,7 @@ export class AgentFramework {
         if (this.surgeryHold) {
             throw new Error(`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 — ` +
                 `injecting a turn under an active stream corrupts wire ordering)`);
@@ -18607,7 +18876,7 @@ export class AgentFramework {
         for (const tc of toolResults) {
             const { text, shown, stored } = alone.get(tc.id);
             spilled.set(tc.id, byShare
-                ? await this.spillOrTruncate(text, share.cap, `${dateLabel}-${tc.id}`, shown, share.bound, stored.written)
+                ? await this.spillOrTruncate(text, share.cap, `${dateLabel}-${tc.id}`, shown, share.bound, stored.written, { readCap: maxChars })
                 : stored);
         }
         const blocks = toolResults.map(tc => ({
@@ -18814,7 +19083,12 @@ export class AgentFramework {
     bound = undefined, 
     /** The spill file an earlier cut of this text wrote: reused, not written
      *  again. Undefined when none was cut. */
-    written) {
+    written, 
+    /** Set where `cap` and `bound` are this text's share of one turn's
+     *  bound (buildStoredToolResultContent): `readCap` is the inline cap,
+     *  which a later read of the file comes back under alone in its own turn
+     *  and its paging advice is sized to. */
+    share) {
         if (!cap || content.length <= cap)
             return { text: content, filePath: null };
         // The stored text is the only place save_recent_image discovers tool
@@ -18824,45 +19098,63 @@ export class AgentFramework {
         // newest slots past the cut that the live copy showed are re-appended
         // after the notice. Otherwise the live copy is this text, and nothing
         // past the cut is kept (#403). The stored copy, notice and kept slots
-        // included, fits `bound`, the most a reader's strategy keeps of it, so
-        // no reader's cut takes the notice (cutStoredToolResultToFit), and the
-        // spill notices name the head they kept.
-        const cut = cutStoredToolResultToFit(content, cap, shown, bound);
+        // included, fits `bound`, the most a reader's strategy keeps of it,
+        // where `bound` leaves the notice its room, so no reader's cut takes the
+        // notice (cutStoredToolResultToFit), and the spill notices name the head
+        // they kept. Under a share too small for that, a cut keeps no head and
+        // stores its notice alone, and a text no longer than that notice is
+        // stored whole, with no file written: each result at its least.
+        const readCap = share?.readCap ?? cap;
+        const cut = cutStoredToolResultToFit(content, cap, shown, bound, share ? this.spillNoticeLength(label, content, shown, bound, readCap) : undefined);
+        if (cut.head === content)
+            return { text: content, filePath: null };
         const { head } = cut;
         const kept = formatKeptImageSlots(cut);
         if (written === undefined)
             written = await this.writeToolResultFile(label, content);
+        const notice = this.spillNotice(head.length, content, shown, bound, readCap, written);
+        // The notice was measured as a written file's reads. A write that failed
+        // keeps nothing, and its notice, naming the failure, can be longer: under
+        // a share, a cut that keeps no head and would store no less than the
+        // text is stored as the text itself, where the text holds no image slot.
+        // One that does is stored as it was measured, cut, since save_recent_image
+        // counted it so before the write.
+        if (share && head.length === 0 && notice.length >= content.length && parseImagePlaceholders(content).length === 0) {
+            return { text: content, filePath: null, written };
+        }
+        return { text: head + notice + kept, filePath: written && written.error === undefined ? written.path : null, written };
+    }
+    /**
+     * The notice a cut copy carries after its head (spillOrTruncate): the file
+     * holding the whole result and how to read it back, or why there is none.
+     */
+    spillNotice(headLength, content, shown, bound, readCap, written) {
         if (written && written.error === undefined) {
-            const path = written.path;
-            return {
-                text: head
-                    + `\n\n[truncated — showing ${head.length} of ${content.length} chars; full content: workspace file ${path}`
-                    + `. ${this.spillPageAdvice(path, cap, bound === undefined || cutStoredToolResultToFit(content, bound, shown, bound).head.length > head.length)}]`
-                    + kept,
-                filePath: path,
-                written,
-            };
+            const canRaise = bound === undefined || cutStoredToolResultToFit(content, bound, shown, bound).head.length > headLength;
+            return `\n\n[truncated — showing ${headLength} of ${content.length} chars; full content: workspace file ${written.path}`
+                + `. ${this.spillPageAdvice(written.path, readCap, canRaise)}]`;
         }
         if (written) {
             // A workspace was there and the write FAILED — say that, loudly and
             // distinctly. Telling the agent "no writable workspace" would teach
             // them their residence lacks a capability it actually has.
-            return {
-                text: head
-                    + `\n\n[truncated — showing ${head.length} of ${content.length} chars; spill to workspace file ${written.path} FAILED`
-                    + ` (${written.error}); content over the cap was not retained]`
-                    + kept,
-                filePath: null,
-                written,
-            };
+            return `\n\n[truncated — showing ${headLength} of ${content.length} chars; spill to workspace file ${written.path} FAILED`
+                + ` (${written.error}); content over the cap was not retained]`;
         }
-        return {
-            text: head
-                + '\n\n[truncated — original was ' + content.length + ' chars; no writable workspace mount without an include, full content not retained]'
-                + kept,
-            filePath: null,
-            written,
-        };
+        return '\n\n[truncated — original was ' + content.length + ' chars; no writable workspace mount without an include, full content not retained]';
+    }
+    /**
+     * The length of the notice a cut of `content` that keeps no head would
+     * carry, before any file is written, as it reads once its file is
+     * (toolResultFilePlace, where any earlier cut of the text wrote it too), so
+     * the cut and save_recent_image's count of the result before it measure
+     * alike. For keeping whole, under a share, a text no longer than its notice
+     * (cutStoredToolResultToFit). A write that fails carries a notice naming
+     * the failure instead (spillOrTruncate).
+     */
+    spillNoticeLength(label, content, shown, bound, readCap) {
+        const place = this.toolResultFilePlace(label);
+        return this.spillNotice(0, content, shown, bound, readCap, place ? { path: place.path } : null).length;
     }
     /**
      * The bridge: one of a script's calls, as its agent's, through the ordinary
@@ -18911,7 +19203,8 @@ export class AgentFramework {
         }
         if (refusal !== undefined)
             return refused(refusal);
-        const result = await this.dispatchScriptToolCall(agentName, toolName, input, context.origin, context.watch?.turnId);
+        const route = { toServer: false };
+        const result = await this.dispatchScriptToolCall(agentName, toolName, input, context.origin, 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
         // the script still runs and wedge the tool round. A call a left script
@@ -18923,7 +19216,7 @@ export class AgentFramework {
             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;
     }
     /**
@@ -18931,14 +19224,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.
      */
-    async scriptResultAnswer(result, toolName) {
+    async scriptResultAnswer(result, toolName, toServer) {
         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
@@ -18955,7 +19252,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);
@@ -18984,6 +19284,21 @@ 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) => shownToScript(value)));
+                }
+                catch (err) {
+                    return failed(err);
+                }
+            }
         }
         else {
             // As in history, a reference is its stub at any depth and inline data
@@ -19022,9 +19337,11 @@ 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.
      */
-    dispatchScriptToolCall(agentName, toolName, args, origin, turnId) {
+    dispatchScriptToolCall(agentName, toolName, args, origin, turnId, route = { toServer: false }) {
         return new Promise((resolve) => {
             const callId = `pytc-${randomUUID()}`;
             // Host-side leak guard: the script's runner already gives the script a
@@ -19050,9 +19367,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 };
             if (origin)
@@ -19583,6 +19903,11 @@ 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;
         }
@@ -24592,7 +24917,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, mcpl) => {
             if (!forScript || !Object.prototype.hasOwnProperty.call(result, 'structuredContent')) {
@@ -25692,11 +26019,15 @@ export class AgentFramework {
                     // the round's calls, finished or not.
                     const { cap, bound } = this.resolveToolResultInlineCap(agent);
                     const share = toolResultShare(cap, bound, state.pending.size + state.completed.length);
+                    const dateLabel = new Date().toISOString().slice(0, 10);
                     for (let i = state.completed.length - 1; i >= 0 && collecting(); i--) {
                         const tc = state.completed[i];
                         const { text, shown } = this.storedToolResultText(agentName, tc, cap);
                         const alone = storedImageSlots(text, cap, shown, bound);
-                        const byShare = storedImageSlots(text, share.cap, shown, share.bound);
+                        // By its share, with the notice the commit's cut would carry, so a
+                        // result no longer than its notice counts as kept whole, as the
+                        // commit stores it.
+                        const byShare = storedImageSlots(text, share.cap, shown, share.bound, this.spillNoticeLength(`${dateLabel}-${tc.id}`, text, shown, share.bound, cap));
                         if (alone.length !== byShare.length || alone.some((slot, j) => slot.text !== byShare[j].text)) {
                             this.toolRoundsByShare.add(state.completed);
                         }