@animalabs/agent-framework 0.24.0 → 0.24.1

package/dist/src/framework.js

@@ -46,7 +46,7 @@ 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 { TOOL_IMAGE_REF_RE, ToolImageLedger, cutStoredToolResult, formatKeptImageSlots, parseImagePlaceholders, sha256Hex, storedImageSlots, toolResultCutAt, } from './tool-image-ledger.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';
 import { AgentScripts, endingWakes, ScriptRefusal, } from './code-execution/isolate/scripts.js';
@@ -294,9 +294,12 @@ function malformedResponseContent(response) {
  * mid-turn message's text at chars/4 and its other blocks about as
  * context-manager's store prices them (injectedBlockTokens), and a small
  * per-block envelope allowance. On membrane's native tool path a mid-turn
- * message rides into the next round with its stored content as it is
- * (provideToolResults' injectedMessages); its XML tool path drops injected
- * messages, so there the estimate errs high. Deliberately a
+ * message rides into the next round as the boundary injects it, which is as
+ * the strategy renders it for the next compile, cut and with its images
+ * limited (renderForInjection), or its stored content where the strategy
+ * can't say (provideToolResults' injectedMessages). Its XML tool path declares that it
+ * can't carry injected messages, so the tool boundary injects none there and
+ * that term is zero. Deliberately a
  * ceiling-ish heuristic, but for a mid-turn message's media at the store's
  * flat prices — the cost of overestimating is one early recompile;
  * the cost of underestimating is the 400 this projection exists to prevent.
@@ -533,6 +536,7 @@ import { MALFORMED_CONTENT_NOTICE, normalizeStandardToolResult } from './mcpl/to
 import { boundedForLog, describeCause } from './mcpl/errors.js';
 import { assertServerConfigBooleans, buildWebSocketUrl, isWebSocketTransport } from './mcpl/transport.js';
 import { formatZonedDateTime, resolveTimeZone } from './timezone.js';
+import { CLOCK_ROW_KIND, clockStampOf, planClock, takesClockBefore } from './clock-rows.js';
 import { firstFreeBranchName } from './branch-names.js';
 import { DEFAULT_DISCORD_AWARENESS_EMOJI, DiscordAwarenessOutbox, DiscordAwarenessRefusal, defaultDiscordAwarenessOutboxPath, extractDiscordAwarenessRefs, selectDiscordAwarenessRefs, checkedDiscordAwarenessMarks, boundDiscordAwarenessText, discordChannelOf, isPermanentDiscordReactionFailure, unsyncedWriteText, } from './recovery/discord-awareness-outbox.js';
 import { OperatorActionError, OperatorLog, capIds, defaultOperatorLogPath, } from './operator-log.js';
@@ -572,6 +576,25 @@ function asCompiled(landed) {
     const text = blocks.filter((b) => b.type === 'text').map((b) => b.text).join('');
     return [...blocks.filter((b) => b.type !== 'text'), { type: 'text', text }];
 }
+/** A message's size as a notice gives it: its text's characters and its
+ *  images, each left out when there are none, so empty when it has
+ *  neither. */
+function contentSize(content) {
+    let chars = 0;
+    let images = 0;
+    for (const b of content) {
+        if (b.type === 'text')
+            chars += b.text.length;
+        else if (b.type === 'image' || b.type === 'generated_image')
+            images++;
+    }
+    const parts = [];
+    if (chars > 0)
+        parts.push(`${chars.toLocaleString('en-US')} character${chars === 1 ? '' : 's'}`);
+    if (images > 0)
+        parts.push(`${images} image${images === 1 ? '' : 's'}`);
+    return parts.join(' and ');
+}
 const storedCopy = (m) => ({ id: m.id, content: m.content, ...(m.bodyGroupId !== undefined ? { bodyGroupId: m.bodyGroupId } : {}) });
 /** Stamp a deferred write's durable id into the metadata it is stored with
  *  (boot recovery dedups replays by it). Idempotent for an already-stamped
@@ -1983,6 +2006,10 @@ export class AgentFramework {
      * ephemeral agents have isolated slots and are their own only readers.
      */
     sharedSlotAgents = new Set();
+    /** Rounds of tool calls, by their results array, that a save_recent_image
+     *  in the round counted by their share of the bound: such a round is
+     *  stored by its share whether or not it fits (buildStoredToolResultContent). */
+    toolRoundsByShare = new WeakSet();
     /** The windows of forks and runs deregistered while the host was quiesced,
      *  by agent name (releaseWindowNowOrAfterResume); resume() releases them
      *  (runReleasesAfterResume), or stop() passes on what they left, unread or
@@ -2630,6 +2657,9 @@ export class AgentFramework {
             });
             framework.tuneOutCoordinator.resumeActiveEpochs();
         }
+        else {
+            framework.endTuneOutsWithoutCoordinator();
+        }
         // Modules, agents, MCPL servers and the tune-out tool are all in place:
         // the first point at which "matches no tool" can be judged. Later tool
         // refreshes re-check patterns still undecided.
@@ -9969,6 +9999,10 @@ export class AgentFramework {
             // Speech happens only via speak_in_channel (its own marked voice).
             proseRouting: 'explicit',
             allowedTools: [...SUBCONSCIOUS_TOOL_NAMES, 'think', 'skip_reply', 'end_turn'],
+            // No clock rows of its own: its merged view carries the residents'
+            // clocks, and clocks it planned from its own rows alone would read the
+            // time a second time beside them, or disagree with them.
+            clock: undefined,
         };
         const agent = new Agent(agentConfig, contextManager, this.membrane);
         this.adoptToolResultGuard(agent);
@@ -10115,14 +10149,14 @@ export class AgentFramework {
                 if (currentState.status === 'ready') {
                     // Effective inline cap: agent_settings override → durable config →
                     // house default, clamped to the strategy bound (see resolver).
-                    const maxChars = this.resolveToolResultInlineCap(agent).cap;
+                    const { cap: maxChars, bound } = this.resolveToolResultInlineCap(agent);
                     // Oversized results — successes AND errors — spill to a workspace
                     // file (truncated preview + file reference) instead of being
                     // blind-truncated. Computed ONCE per call and reused for both the
                     // history copy and the live wire copy below — the two must stay
                     // byte-matched (the window stores what the membrane sends;
                     // divergence breaks the compile prefix).
-                    const { blocks: toolResultContent, spilled } = await this.buildStoredToolResultContent(agent.name, currentState.toolResults, maxChars);
+                    const { blocks: toolResultContent, spilled, keptCap } = await this.buildStoredToolResultContent(agent.name, currentState.toolResults, maxChars, bound);
                     // A spill writes to the workspace, and the turn can be stopped
                     // meanwhile. A host's cancelStream, stop() and abortInference cancel
                     // the round's stream at `ready` and leave the agent idle, and an
@@ -10172,7 +10206,7 @@ export class AgentFramework {
                         this.pendingAssistantBlocks.delete(agent.name);
                     }
                     const membraneResults = currentState.toolResults.map(tc => this.toMembraneToolResult(tc.id, tc.result, maxChars, spilled.get(tc.id)));
-                    agent.toolResultGuard.storeResults(toolResultContent, membraneResults, currentState.toolResults, turnRowMetadata, maxChars);
+                    agent.toolResultGuard.storeResults(toolResultContent, membraneResults, currentState.toolResults, turnRowMetadata, keptCap);
                     // Flush any messages that were deferred while this turn was in
                     // flight: this agent's own entries, those addressed to it and, for
                     // the primary, those addressed to no one (module messages, push
@@ -10184,14 +10218,21 @@ export class AgentFramework {
                     // live turn sees them instead of the agent staying deaf until the
                     // turn ends. The window stores them here, right after the
                     // tool_result message, which is exactly where the membrane appends
-                    // them in the live conversation — same participant, same content
-                    // blocks, and neither carries the row's metadata — and compile()
-                    // emits recent messages verbatim, so the next turn's compiled prefix
-                    // byte-matches the live request (prompt-cache safe). A write that
-                    // threw after it was stored, whose landing couldn't be read, is the
-                    // exception: it's carried at the flush that finds it, after what was
-                    // stored since, so there the store and the live request differ
-                    // (writeDrainedInOrder).
+                    // them in the live conversation — same participant, and neither
+                    // carries the row's metadata — and each goes in as the next compile
+                    // will send it, which the strategy renders (renderForInjection): cut
+                    // by the per-message cap, a sharded body joined, and its images as
+                    // the image limits leave them at the newest position. So the next
+                    // turn's compiled prefix matches the live request (prompt-cache
+                    // safe), up to what came after them: a later message can still
+                    // take an earlier one past an image limit, as for any message, and
+                    // the next compile then strips that image where the live rounds
+                    // carried it. One the next compile won't send among its newest
+                    // isn't injected; a notice after the batch tells the agent of it
+                    // (recordLeftOutNotice). A write that threw after it was stored, whose landing
+                    // couldn't be read, is the exception: it's carried at the flush
+                    // that finds it, after what was stored since, so there the store and
+                    // the live request differ (writeDrainedInOrder).
                     //
                     // The queue is drained ONLY at the target agent's own boundary:
                     // draining at another agent's boundary would store the messages
@@ -10226,21 +10267,29 @@ export class AgentFramework {
                     // a held message does, rather than sitting in the window between
                     // rounds the stream never showed it.
                     const midTurnInjections = [];
-                    // The injected messages' ids, for a boundary that leaves them to the
-                    // turn's next start as arrivals.
-                    const injectedIds = new Map();
+                    // What this boundary stored for the agent to hear, in store order,
+                    // injected or left out, for a boundary that leaves it to the turn's
+                    // next start as arrivals: that start's compile sends it.
+                    const heard = [];
                     if (currentState.supportsInjectedMessages !== false) {
+                        // A clock row due (storeDueClock) goes right after the round's
+                        // results, ahead of what is drained below, and joins the stream
+                        // the same way. A boundary that passed during the round can't
+                        // stand between a tool's call and its results, so this clock
+                        // reads the time it's written (clock-rows.ts).
+                        const clock = this.storeDueClock(agent, 'tool-boundary');
                         const deferred = this.drainDeferredFor(agent.name, (msg) => !isInjectableMidTurn(msg, agent.name));
                         // Stored in queue order, cut at the first that can't be stored: it
                         // and what follows wait for the turn's end, and only what was
                         // stored is injected (the round's results go on either way). One
                         // the store refuses as malformed is dropped instead, and what
-                        // follows goes on. A sharded body read back from its store is
-                        // injected as later compiles render it, its shards joined, and a
-                        // write that threw after storing, which counts as stored, as what
-                        // landed of it (writeDrainedInOrder).
+                        // follows goes on. What was stored is injected as the next compile
+                        // will send it (renderForInjection). Where the strategy can't say,
+                        // a sharded body read back from its store is injected as later
+                        // compiles join it, and a write that threw after storing, which
+                        // counts as stored, as what landed of it (writeDrainedInOrder).
                         const stored = this.writeDrainedInOrder(deferred, `tool boundary for ${agent.name}`, (msg) => agent.getContextManager().addMessage(msg.participant, msg.content, withDeferredWriteId(msg.metadata, msg.id)));
-                        for (const [msg, { id, content }] of stored) {
+                        for (const [msg, { id, content, parts }] of stored) {
                             // Every other resident reads what this boundary stores; for its
                             // own agent, the boundary weighs what it injects below.
                             this.noteForOtherResidents(agent, msg.metadata, id);
@@ -10250,13 +10299,49 @@ export class AgentFramework {
                             // what the next compile hides (#232 gap 5).
                             if (msg.metadata?.tuneOut)
                                 continue;
-                            const injection = {
-                                participant: msg.participant,
-                                content,
-                                ...(msg.metadata ? { metadata: msg.metadata } : {}),
-                            };
-                            midTurnInjections.push(injection);
-                            injectedIds.set(injection, id);
+                            heard.push({ msg, id, content, parts });
+                        }
+                        // Rendered in one call: a render prepares as a compile does, so
+                        // the batch shares one preparation. The image limits count from
+                        // the batch's oldest message to the newest, as a compile does.
+                        // The clock, stored ahead of them, renders first in the same batch
+                        // and is injected first, as the next compile sends it.
+                        const rendered = this.renderForInjection(agent, [...(clock ? [clock.id] : []), ...heard.map((h) => h.id)]);
+                        const first = clock ? 1 : 0;
+                        if (clock) {
+                            const sent = rendered ? rendered[0] : clock.content;
+                            if (sent !== null) {
+                                midTurnInjections.push({ participant: 'user', content: sent, metadata: clock.metadata });
+                            }
+                            else {
+                                console.error(`[clock] ${agent.name}: clock ${clock.id} left out of the live round, since the next compile won't send it among its newest`);
+                            }
+                        }
+                        const leftOut = [];
+                        heard.forEach((h, i) => {
+                            const sent = rendered ? rendered[i + first] : h.content;
+                            // The next compile won't send it among its newest: injected, it
+                            // would put in the live turn what that compile sends elsewhere,
+                            // or not at all. It's under any consumed mark the boundary sets
+                            // (below), as anything stored here is.
+                            if (sent === null) {
+                                leftOut.push(h);
+                                return;
+                            }
+                            midTurnInjections.push({
+                                participant: h.msg.participant,
+                                content: sent,
+                                ...(h.msg.metadata ? { metadata: h.msg.metadata } : {}),
+                            });
+                        });
+                        if (leftOut.length > 0) {
+                            console.error(`[injection] ${agent.name}: left out of the live round, since the next compile won't send them among its newest: ${leftOut.map((h) => h.id).join(', ')}`);
+                            // The agent is told what it didn't hear, after the batch, as
+                            // the routing notice is: stored, so the next compile sends it
+                            // where the live round heard it.
+                            const notice = this.recordLeftOutNotice(agent, leftOut);
+                            if (notice)
+                                midTurnInjections.push(notice);
                         }
                     }
                     // Deferred writes handed to the store above: sync, then drop them
@@ -10391,11 +10476,12 @@ export class AgentFramework {
                     }
                     else if (routesLocus && !shouldEndTurn) {
                         // A boundary that can't re-pin now (over budget, or no live
-                        // stream to tell) leaves its injections to the turn's next start,
-                        // as arrivals: a budget restart, or a re-inference on these tool
-                        // results.
-                        for (const inj of midTurnInjections)
-                            this.noteArrival(agent.name, inj.metadata, injectedIds.get(inj));
+                        // stream to tell) leaves what it stored for the agent to the
+                        // turn's next start, as arrivals: a budget restart, or a
+                        // re-inference on these tool results. That includes a message
+                        // left out of the injection, since that start compiles anew.
+                        for (const { msg, id } of heard)
+                            this.noteArrival(agent.name, msg.metadata, id);
                     }
                     if (shouldEndTurn) {
                         // endTurn: what this boundary stored stays; cancel stream, reset to idle.
@@ -10496,6 +10582,18 @@ export class AgentFramework {
                         // Under context-manager#160 such a write already gives the
                         // replies stored after it stamps their requests didn't carry,
                         // whatever the mark says; deferring those writers is the fix.
+                        // The mark also covers a message the boundary stored and left out
+                        // of the injection, since the next compile won't send it among its
+                        // newest: the notice telling the agent of it is injected, so a
+                        // boundary that leaves one out injects something, unless that
+                        // notice couldn't be stored. The message then counts as read
+                        // though no request carried it: a coalesced render's wake to read
+                        // it drops, and a release doesn't pass it to the primary. The
+                        // notice has told the agent it came, from whom, and how to read
+                        // it. Where the view leaves it out, no request will carry it.
+                        // Where the memory strategy places it before its recent window, a
+                        // batch bigger than that window, the next compile carries it, in
+                        // whatever turn something else starts.
                         if (midTurnInjections.length > 0) {
                             // Possibly shown, whatever the stream declares: the first-view
                             // mark (CoalescerHost.isUnshown) counts a doubt as shown.
@@ -10774,6 +10872,11 @@ export class AgentFramework {
                 return undefined;
             if (this.conversationRouter && this.conversationAgentHomes.has(target.name)) {
                 metadata.triggered = event.triggerInference ?? false;
+                // A fork's channel messages are stored past its deferral; a clock goes
+                // ahead of one only while the fork has no turn alive (storeDueClock).
+                if (!this.turnAlive(target) && takesClockBefore('user', event.content, metadata, target.name)) {
+                    this.storeDueClock(target, 'event');
+                }
                 const id = target.getContextManager().addMessage('user', event.content, AgentFramework.withStoredDigest(metadata, event.content));
                 // A correction may target an older engagement. Refresh only the
                 // binding whose agent actually received the message.
@@ -10933,6 +11036,10 @@ export class AgentFramework {
         // on top of the router's own trigger policy.
         const trigger = decision.trigger && event.triggerInference !== false;
         messageMetadata.triggered = trigger;
+        // As for a correction above: a clock ahead only while no turn is alive.
+        if (!this.turnAlive(agent) && takesClockBefore('user', event.content, messageMetadata, agent.name)) {
+            this.storeDueClock(agent, 'event');
+        }
         const id = agent.getContextManager().addMessage('user', event.content, AgentFramework.withStoredDigest(messageMetadata, event.content));
         router.touch(event.channelId);
         this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:channel-incoming' });
@@ -13671,6 +13778,101 @@ export class AgentFramework {
             return m.channelId;
         return routing.engaged.has(m.channelId) ? m.channelId : undefined;
     }
+    /** Whether `agent` has a turn alive: starting, streaming or waiting on its tools. */
+    turnAlive(agent) {
+        return this.activeTurnTokens.has(agent.name)
+            || this.pendingAssistantBlocks.has(agent.name)
+            || this.activeStreams.has(agent.name);
+    }
+    /**
+     * Store the clock row due in `agent`'s window (clock-rows.ts), if the agent
+     * has clock rows and a boundary has passed since the window's last clock,
+     * or the window holds no clock row yet (planClock), and return it. The
+     * caller places it, by calling this right before what the clock precedes
+     * is written: an incoming event while no turn of the agent's is alive (or
+     * one is assembling before its compile), a fresh turn's inputs before its
+     * compile, or, mid-turn, the messages a tool boundary injects, where the
+     * caller injects the clock first. Each is a place where a row is either in
+     * the request that follows or before every request still to come, so the
+     * window and the live stream keep matching.
+     *
+     * None while the host is quiesced (the window is frozen for surgery), and
+     * none in the residents' shared slot while another of its readers (the
+     * subconscious among them, through its merged view) has a turn alive: the
+     * row would sit inside that turn without joining its stream. A clock that
+     * can't be planned or stored is logged and skipped: it never holds up what
+     * it would have preceded. One whose write threw after it landed is the
+     * window's all the same, so it's returned, and a tool boundary injects it.
+     */
+    storeDueClock(agent, occasion) {
+        const config = agent.clock;
+        if (!config || this.quiesced)
+            return undefined;
+        if (this.sharedSlotAgents.has(agent)) {
+            for (const reader of this.sharedSlotAgents) {
+                if (reader !== agent && this.turnAlive(reader))
+                    return undefined;
+            }
+        }
+        let planned;
+        try {
+            planned = planClock({ now: Date.now(), ...this.lastClockOf(agent.getContextManager()), config, zone: this.timeZone });
+        }
+        catch (err) {
+            console.error(`[clock] ${agent.name}: no clock row at ${occasion}:`, err);
+            return undefined;
+        }
+        if (!planned)
+            return undefined;
+        const metadata = { system: true, kind: CLOCK_ROW_KIND, clock: planned.stamp };
+        const before = this.storedCountOf(agent);
+        let id;
+        try {
+            id = agent.getContextManager().addMessage('user', planned.content, metadata);
+        }
+        catch (err) {
+            // A write can throw after its row landed, as when context-manager's own
+            // propagation of it fails: what landed is read back from where the
+            // store stood before, as writeDrainedInOrder reads a drained write's.
+            const at = planned.stamp.at;
+            const landed = before === undefined
+                ? undefined
+                : this.storedSince(agent, before, (m) => clockStampOf(m.metadata)?.at === at, 'clock', 'the clock write');
+            if (!landed || landed.length === 0) {
+                console.error(`[clock] ${agent.name}: no clock row at ${occasion}${landed ? '' : ' (whether it landed is unknown)'}:`, err);
+                return undefined;
+            }
+            console.error(`[clock] ${agent.name}: the clock row at ${occasion} landed though its write threw:`, err);
+            id = landed[0].id;
+        }
+        this.emitTrace({ type: 'message:added', messageId: id, source: `clock:${occasion}` });
+        return { id, content: planned.content, metadata };
+    }
+    /** Rows a window's last-clock scan reads at a time. */
+    static CLOCK_SCAN_ROWS = 256;
+    /** What the next clock is planned from: the window's newest row's time and
+     *  the time its last clock row reads, found by reading back from the
+     *  newest row, CLOCK_SCAN_ROWS at a time, until a clock row comes, however
+     *  far back it is. In the steady state the newest chunk holds it, unless
+     *  more rows than that have come since the last clock; a window with no
+     *  clock row is read whole once, and then takes one (planClock). */
+    lastClockOf(cm) {
+        let newestRowAt;
+        for (let end = cm.getMessageCount(); end > 0;) {
+            const span = Math.min(end, AgentFramework.CLOCK_SCAN_ROWS);
+            const { messages } = cm.getMessageWindow(end - span, span, { resolveBlobs: false });
+            if (newestRowAt === undefined && messages.length > 0) {
+                newestRowAt = new Date(messages[messages.length - 1].timestamp).getTime();
+            }
+            for (let i = messages.length - 1; i >= 0; i--) {
+                const stamp = clockStampOf(messages[i].metadata);
+                if (stamp)
+                    return { newestRowAt, lastClockAt: stamp.at };
+            }
+            end -= span;
+        }
+        return { newestRowAt, lastClockAt: undefined };
+    }
     /**
      * Weigh a message that no tool boundary of the agent's open logical turn
      * will weigh: one that would re-pin the locus becomes one of the turn's
@@ -15133,6 +15335,17 @@ export class AgentFramework {
         // turn, and flushing there would insert messages between its rounds.
         // Before recordTurnCheckpoint: these are the turn's inputs, not its
         // products — undoing the turn must not destroy them.
+        // A clock row due (storeDueClock) goes ahead of the turn's inputs, so a
+        // turn starts with a current clock, a silent heartbeat's tick (which
+        // stores no row of its own) included, unless storeDueClock writes none:
+        // while the host is quiesced, while another reader of the residents'
+        // shared slot has a turn alive, or when its write fails without landing.
+        // Then a later event, turn start or tool boundary takes it. Fresh turns
+        // only, as the flush below: a turn that resumes continues its logical
+        // turn, which took its clock at its start or at a tool boundary that
+        // could carry one.
+        if (attempt === 0 && !resumesTurn)
+            this.storeDueClock(agent, 'turn-start');
         if (attempt === 0 &&
             !resumesTurn &&
             this.deferredMessages.length > 0) {
@@ -16614,9 +16827,9 @@ export class AgentFramework {
                             // one door a giant blob still walks through).
                             const readyState = agent.state;
                             if (readyState.status === 'ready') {
-                                const cap = this.resolveToolResultInlineCap(agent).cap;
-                                const { blocks: toolResultContent, spilled } = await this.buildStoredToolResultContent(agent.name, readyState.toolResults, cap);
-                                agent.toolResultGuard.storeResults(toolResultContent, readyState.toolResults.map((tc) => this.toMembraneToolResult(tc.id, tc.result, cap, spilled.get(tc.id))), readyState.toolResults, this.silentTurnRowMetadata(agent.name), cap);
+                                const { cap, bound } = this.resolveToolResultInlineCap(agent);
+                                const { blocks: toolResultContent, spilled, keptCap } = await this.buildStoredToolResultContent(agent.name, readyState.toolResults, cap, bound);
+                                agent.toolResultGuard.storeResults(toolResultContent, readyState.toolResults.map((tc) => this.toMembraneToolResult(tc.id, tc.result, cap, spilled.get(tc.id))), readyState.toolResults, this.silentTurnRowMetadata(agent.name), keptCap);
                                 // The response is already complete: this batch is never
                                 // submitted in this turn, so it cannot be refused. Admit it.
                                 agent.toolResultGuard.settleTurnEnded();
@@ -17852,7 +18065,8 @@ export class AgentFramework {
             // token (as during a real tool call) and lands AFTER the pair, never
             // between tool_use and its tool_result. The two addMessage calls
             // below are synchronous and adjacent — nothing can interleave.
-            const { blocks } = await this.buildStoredToolResultContent(agentName, [{ id: toolUseId, name: toolName, input, result, durationMs }], call.resultMaxChars);
+            const { bound } = this.resolveToolResultInlineCap(agent);
+            const { blocks } = await this.buildStoredToolResultContent(agentName, [{ id: toolUseId, name: toolName, input, result, durationMs }], call.resultMaxChars, bound);
             const toolUse = [
                 { type: 'tool_use', id: toolUseId, name: toolName, input },
             ];
@@ -18294,10 +18508,12 @@ export class AgentFramework {
         if (!this.noticeTargetFor(agentName, `script ${scriptId} wake`))
             throw new Error(`agent ${agentName} has no context to wake`);
         const agent = this.agents.get(agentName);
-        const maxChars = agent
-            ? this.resolveToolResultInlineCap(agent).cap
-            : DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS;
-        const { text: shown } = await this.spillOrTruncate(text, maxChars, `script-${label}`);
+        // A reader's strategy cuts the wake's whole message, so its spill fits the
+        // readers' bound with its notice.
+        const { cap: maxChars, bound } = agent
+            ? this.resolveToolResultInlineCap(agent)
+            : { cap: DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS, bound: undefined };
+        const { text: shown } = await this.spillOrTruncate(text, maxChars, `script-${label}`, null, bound);
         // The spill can take a while: the agent may have gone since, or the host begun to stop.
         if (this.stopHasBegun())
             throw new Error('this host is stopping');
@@ -18345,12 +18561,32 @@ export class AgentFramework {
      * #89). Returns the stored blocks plus the per-call spill outcomes so the
      * live wire copy can reuse the identical strings.
      */
-    async buildStoredToolResultContent(agentName, toolResults, maxChars) {
+    async buildStoredToolResultContent(agentName, toolResults, maxChars, 
+    /** The readers' smallest per-message bound (resolveToolResultInlineCap). */
+    bound = undefined) {
         const spilled = new Map();
         const dateLabel = new Date().toISOString().slice(0, 10);
+        // The results are stored as one message, whose bound a reader's
+        // strategy spends across them in order. Each is stored as it would be
+        // alone, unless together they pass the bound, or a save in the round
+        // counted the round by its share (toolRoundsByShare): then each is
+        // stored under its share (toolResultShare). A result carrying an image
+        // keeps its live copy cut at the cap; any other's live copy is its stored
+        // text.
+        const alone = new Map();
         for (const tc of toolResults) {
             const { text, shown } = this.storedToolResultText(agentName, tc, maxChars);
-            spilled.set(tc.id, await this.spillOrTruncate(text, maxChars, `${dateLabel}-${tc.id}`, shown));
+            alone.set(tc.id, { text, shown, stored: await this.spillOrTruncate(text, maxChars, `${dateLabel}-${tc.id}`, shown, bound) });
+        }
+        const share = maxChars === undefined ? undefined : toolResultShare(maxChars, bound, toolResults.length);
+        const total = [...alone.values()].reduce((sum, { stored }) => sum + stored.text.length, 0);
+        const byShare = share?.bound !== undefined && toolResults.length > 1
+            && (this.toolRoundsByShare.has(toolResults) || total > bound);
+        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)
+                : stored);
         }
         const blocks = toolResults.map(tc => ({
             type: 'tool_result',
@@ -18361,7 +18597,10 @@ export class AgentFramework {
             content: spilled.get(tc.id).text,
             isError: tc.result.isError,
         }));
-        return { blocks, spilled };
+        // A withheld round's stubs carry the guard's notice and place beside the
+        // fields they keep, so under a bound their fields are cut within the
+        // share, whether or not the round's results were stored by it.
+        return { blocks, spilled, keptCap: share?.keptCap ?? maxChars };
     }
     /**
      * A tool result's text as its stored copy is written before any cut, and
@@ -18530,21 +18769,30 @@ export class AgentFramework {
         return { path, error: failure };
     }
     /** How to read a tool result's file back a page at a time, with each page
-     *  sized to come back within `cap`. */
-    spillPageAdvice(path, cap) {
+     *  sized to come back within `cap`, and, where `canRaise`, that raising
+     *  the inline cap would show more: where a cap at the readers' bound would
+     *  keep a longer head, or the whole result. */
+    spillPageAdvice(path, cap, canRaise) {
         // JSON serialization can expand each read-back code unit to six
         // chars (\\u0000). Leave room for the page's metadata and a possible
         // extra code unit at a surrogate-pair boundary.
         const pageOverhead = JSON.stringify(path).length + 256;
         const readLimit = Math.max(1, Math.min(2000, Math.floor((cap - pageOverhead) / 6) - 1));
         return `Page with workspace--read ${JSON.stringify({ path, offsetChars: 0, limitChars: readLimit })}; `
-            + 'use nextOffsetChars as offsetChars until null, keeping limitChars. Or raise the inline cap via '
-            + 'agent_settings update tool_result_inline_max_chars.';
+            + 'use nextOffsetChars as offsetChars until null, keeping limitChars.'
+            + (canRaise ? ' Or raise the inline cap via agent_settings update tool_result_inline_max_chars.' : '');
     }
     async spillOrTruncate(content, cap, label, 
     /** What the live copy showed beside this text (storedToolResultText);
      *  null when the live copy was this text. */
-    shown = null) {
+    shown = null, 
+    /** The most a reader's strategy keeps of this copy: the readers'
+     *  smallest per-message bound, or the result's share of it
+     *  (buildStoredToolResultContent). */
+    bound = undefined, 
+    /** The spill file an earlier cut of this text wrote: reused, not written
+     *  again. Undefined when none was cut. */
+    written) {
         if (!cap || content.length <= cap)
             return { text: content, filePath: null };
         // The stored text is the only place save_recent_image discovers tool
@@ -18553,19 +18801,24 @@ export class AgentFramework {
         // saw that the index would silently slide past (issue #104), so the
         // 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).
-        const cut = cutStoredToolResult(content, cap, shown);
+        // 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);
         const { head } = cut;
         const kept = formatKeptImageSlots(cut);
-        const written = await this.writeToolResultFile(label, content);
+        if (written === undefined)
+            written = await this.writeToolResultFile(label, content);
         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)}]`
+                    + `. ${this.spillPageAdvice(path, cap, bound === undefined || cutStoredToolResultToFit(content, bound, shown, bound).head.length > head.length)}]`
                     + kept,
                 filePath: path,
+                written,
             };
         }
         if (written) {
@@ -18578,6 +18831,7 @@ export class AgentFramework {
                     + ` (${written.error}); content over the cap was not retained]`
                     + kept,
                 filePath: null,
+                written,
             };
         }
         return {
@@ -18585,6 +18839,7 @@ export class AgentFramework {
                 + '\n\n[truncated — original was ' + content.length + ' chars; no writable workspace mount without an include, full content not retained]'
                 + kept,
             filePath: null,
+            written,
         };
     }
     /**
@@ -18870,8 +19125,10 @@ export class AgentFramework {
      * the array is text-only (let JSON path handle it; saves a code path).
      * `maxChars`, when provided, caps each accompanying text block so an image
      * inlined alongside an enormous text payload can't blow the context. A
-     * block is cut as the stored copy is (toolResultCutAt), never inside a
-     * slot, so the stored copy can keep exactly the slots this showed (#403).
+     * block is cut at the cap as the stored copy's cut at that cap is
+     * (toolResultCutAt), never inside a slot, so the stored copy can keep
+     * exactly the slots this showed (#403); under a readers' bound the stored
+     * copy's cut can come earlier (cutStoredToolResultToFit).
      */
     tryNativeToolResultContent(data, maxChars, 
     /** Spill file written by the history path — referenced from truncation
@@ -18949,6 +19206,10 @@ export class AgentFramework {
      * (Sol's #94 ruling: a durable preference must not be a durable path for
      * one tool result to exceed maxMessageTokens; the way to see the whole
      * result is the spill file, not an over-bound blob in live context).
+     * An ordinary resident's results land in the shared slot, which each of
+     * its readers compiles under its own strategy, so the bound is the
+     * smallest of theirs, as the tune-out dump's is (residentMessageChars); a
+     * fork's or an ephemeral agent's store has itself as its only reader.
      */
     resolveToolResultInlineCap(agent) {
         const override = this.toolResultInlineMaxCharsOverride.get(agent.name);
@@ -18957,12 +19218,25 @@ export class AgentFramework {
         const source = override !== undefined
             ? 'agent-settings-override'
             : configured !== null ? 'framework-config' : 'default';
-        const strategyBound = this.strategyDerivedToolResultChars(agent);
-        const clamped = strategyBound !== undefined && strategyBound < desired;
+        let bound = this.strategyDerivedToolResultChars(agent);
+        let byReader = false;
+        if (this.isOrdinaryResident(agent)) {
+            for (const reader of this.sharedSlotAgents) {
+                if (reader === agent)
+                    continue;
+                const readerBound = this.strategyDerivedToolResultChars(reader);
+                if (readerBound !== undefined && (bound === undefined || readerBound < bound)) {
+                    bound = readerBound;
+                    byReader = true;
+                }
+            }
+        }
+        const clamped = bound !== undefined && bound < desired;
         return {
-            cap: clamped ? strategyBound : desired,
+            cap: clamped ? bound : desired,
             source,
-            clampedBy: clamped ? 'strategy-bound' : null,
+            clampedBy: clamped ? (byReader ? 'reader-bound' : 'strategy-bound') : null,
+            bound,
         };
     }
     /**
@@ -18970,8 +19244,9 @@ export class AgentFramework {
      * its caller whole. A call from a running script resolves to the script,
      * which takes any result that fits its memory (scriptResultMaxChars). Any
      * other call's result is stored in its agent's context under the agent's
-     * inline cap, and a call for an agent the framework doesn't hold gets the
-     * house default.
+     * inline cap, unless its round's results together pass the readers' bound,
+     * when each takes its share (buildStoredToolResultContent), and a call for
+     * an agent the framework doesn't hold gets the house default.
      */
     resultMaxCharsFor(agentName, callId) {
         const ce = this.codeExecution;
@@ -19544,8 +19819,9 @@ export class AgentFramework {
         // messages flush at the next turn's START (before its compile — riding
         // their own wake), at the agent's next tool boundary (where they are
         // ALSO injected into the live stream — hear-while-acting — all but a
-        // message a tune-out holds from the residents), or in driveStream's
-        // finally when the turn ends.
+        // message a tune-out holds from the residents, and one the next compile
+        // won't send among its newest), or in driveStream's finally when the
+        // turn ends.
         // Quiesce (issue #122): the window exists to run compression/refold
         // against a FROZEN context — module events and api message.send must not
         // append mid-surgery. Deferred here, flushed by resume(). tool_result
@@ -19614,6 +19890,13 @@ export class AgentFramework {
             }
             return ''; // Deferred — flushed at the target's next boundary
         }
+        // A clock row due goes first (storeDueClock). A write that gets here is a
+        // tool result (which takes none), or no turn of the agent's is alive, or
+        // its turn is assembling before its compile, or it comes from stop()'s
+        // drain, once every stream it could join has settled: the clock is in
+        // whatever request comes next.
+        if (takesClockBefore(participant, content, metadata, agent.name))
+            this.storeDueClock(agent, 'event');
         const stored = agent.getContextManager().addMessage(participant, content, opts?.fromQueue ? withDeferredWriteId(metadata, opts.fromQueue.id) : metadata);
         if (opts?.placement) {
             opts.placement.agent = agent.name;
@@ -19696,6 +19979,72 @@ export class AgentFramework {
         if (this.quiesced || this.deferredWritesPersisted)
             this.persistDeferredWrites();
     }
+    /**
+     * What the next compile sends for each of `ids`, messages a tool boundary
+     * has just stored, as the agent's strategy renders them as the newest of
+     * its window (ContextManager.renderAsNewest): cut by the per-message cap,
+     * a sharded body joined, and the image limits applied over the batch, so
+     * the live stream hears what the next compile sends. An id comes back as
+     * null where that compile won't send the message among its newest.
+     * Undefined where the strategy has no such hook, or the render threw,
+     * which is logged: the boundary then injects what it stored, as it did
+     * before strategies could say.
+     */
+    renderForInjection(agent, ids) {
+        if (ids.length === 0)
+            return undefined;
+        try {
+            return agent.getContextManager().renderAsNewest(ids);
+        }
+        catch (error) {
+            console.error(`[injection] ${agent.name}: couldn't render the messages a tool boundary stored as the next compile sends them, so they're injected as stored:`, error);
+            return undefined;
+        }
+    }
+    /**
+     * Tell the agent of the messages a tool boundary stored and left out of
+     * its injection, since the next compile won't send them among its newest:
+     * who sent each and its size, and how to read it, `history--extract`
+     * around it where the agent is shown that tool, else its id. None of a
+     * message's words: the line stands in for a message the live round
+     * doesn't carry. A system line, so it's no conversation: it neither
+     * re-pins the turn nor clears its send suppression. It names the agent
+     * it's for, since every resident sharing the slot reads it too. Returns
+     * the notice as stored, for the boundary to inject after the batch, or
+     * undefined when it couldn't be stored, which is logged.
+     */
+    recordLeftOutNotice(agent, leftOut) {
+        const canExtract = this.advertisedToolsForAgent(agent.name).some((t) => t.name === 'history--extract');
+        const one = leftOut.length === 1;
+        const lines = leftOut.map(({ msg, id, content, parts }) => {
+            const size = contentSize(content);
+            // A sharded body is that many store messages, consecutive from its
+            // first, which extract reads around it one by one. (Its "after" stops
+            // at 100, so a body of more parts, over 300,000 tokens at the memory
+            // strategy's default shard size, is read only that far.)
+            const read = canExtract
+                ? `history--extract with aroundId "${id}", before 0 and after ${parts - 1} reads it` +
+                    `${parts > 1 ? `, stored as ${parts} parts` : ''}.`
+                : `Its id is ${id}${parts > 1 ? `, the first of the ${parts} parts it's stored as` : ''}.`;
+            return `- From ${msg.participant}${size ? `, ${size}` : ''}. ${read}`;
+        });
+        const content = [{
+                type: 'text',
+                text: `[not shown] For ${agent.name}: ${one ? 'A message' : `${leftOut.length} messages`} arrived during your turn that ` +
+                    `${one ? "isn't" : "aren't"} shown here, since your context doesn't keep ${one ? 'it' : 'them'} among ` +
+                    `your newest messages:\n${lines.join('\n')}`,
+            }];
+        const metadata = { system: true, kind: 'left-out-notice' };
+        try {
+            const id = agent.getContextManager().addMessage('user', content, metadata);
+            this.emitTrace({ type: 'message:added', messageId: id, source: 'left-out-notice' });
+            return { participant: 'user', content, metadata };
+        }
+        catch (err) {
+            console.error(`[injection] ${agent.name}: couldn't store the notice of messages left out of the live round:`, err);
+            return undefined;
+        }
+    }
     /**
      * Write drained entries in queue (seq) order, whatever their targets:
      * residents share one message slot, so the order entries arrived in is the
@@ -19814,7 +20163,7 @@ export class AgentFramework {
                     continue;
                 }
                 if (found.length > 0) {
-                    written.set(msg, { id: found[0].id, content: asCompiled(found) });
+                    written.set(msg, { id: found[0].id, content: asCompiled(found), parts: found.length });
                     this.logDeferredWriteError(msg, where, undefined, { count: found.length, sharded: found[0].bodyGroupId !== undefined, foundLater: true });
                     onLanded?.(msg, found[0].id);
                     continue;
@@ -19831,7 +20180,7 @@ export class AgentFramework {
                 const copies = agent && before !== undefined && (this.storedCountOf(agent) ?? before) - before > 1
                     ? this.storedCopiesOf(agent, before, msg.id) ?? []
                     : [];
-                written.set(msg, { id, content: copies.length > 1 ? asCompiled(copies) : msg.content });
+                written.set(msg, { id, content: copies.length > 1 ? asCompiled(copies) : msg.content, parts: Math.max(1, copies.length) });
             }
             catch (error) {
                 // What landed, read back from where the store stood before the
@@ -19839,7 +20188,7 @@ export class AgentFramework {
                 // after it. With no agent there's no store it could have landed in.
                 const landed = !agent ? [] : before === undefined ? undefined : this.storedCopiesOf(agent, before, msg.id);
                 if (landed && landed.length > 0) {
-                    written.set(msg, { id: landed[0].id, content: asCompiled(landed) });
+                    written.set(msg, { id: landed[0].id, content: asCompiled(landed), parts: landed.length });
                     this.logDeferredWriteError(msg, where, error, { count: landed.length, sharded: landed[0].bodyGroupId !== undefined });
                     onLanded?.(msg, landed[0].id);
                     continue;
@@ -19880,14 +20229,19 @@ export class AgentFramework {
      *  `bodyGroupId`. Undefined when the store can't be read back, which is
      *  logged: not the same as nothing found. */
     storedCopiesOf(agent, from, deferredWriteId) {
+        return this.storedSince(agent, from, (m) => m.metadata?.deferredWriteId === deferredWriteId, 'deferral', `deferred write ${deferredWriteId}`);
+    }
+    /** The messages `match` picks among those the agent's store gained from
+     *  position `from` on, in store order, with their blobs resolved. Undefined
+     *  when the store can't be read back, which is logged under `tag`, naming
+     *  `what` was written: not the same as nothing found. */
+    storedSince(agent, from, match, tag, what) {
         try {
             const cm = agent.getContextManager();
-            return cm.getMessageWindow(from, Math.max(0, cm.getMessageCount() - from)).messages
-                .filter((m) => m.metadata?.deferredWriteId === deferredWriteId)
-                .map(storedCopy);
+            return cm.getMessageWindow(from, Math.max(0, cm.getMessageCount() - from)).messages.filter(match).map(storedCopy);
         }
         catch (error) {
-            console.error(`[deferral] could not read back what deferred write ${deferredWriteId} stored in ${agent.name}'s store:`, error);
+            console.error(`[${tag}] could not read back what ${what} stored in ${agent.name}'s store:`, error);
             return undefined;
         }
     }
@@ -22799,6 +23153,9 @@ export class AgentFramework {
         // configured servers can still deploy its first one at runtime.
         if (!this.mcplServerRegistry || !this.mcplHostCapabilities) {
             await this.initializeMcpl([], this.mcplInferenceRoutingConfig ?? undefined);
+            // The lifecycle log's replay restored any tune-out on record, and no
+            // coordinator is made here to carry one.
+            this.endTuneOutsWithoutCoordinator();
         }
         const collision = this.mcplPrefixCollision(config, undefined, claim);
         if (collision)
@@ -24468,6 +24825,47 @@ export class AgentFramework {
             ...structured,
         };
     }
+    /**
+     * A tune-out on record where this host has no tune-out coordinator: a
+     * start with no subconscious makes none, and neither does a channel
+     * subsystem brought up after start by connectMcplServer. Nothing then
+     * diverts the channel's traffic or ever cancels its tune-out, tune_out
+     * isn't offered, and channel_open, channel_close and channel_decline
+     * refuse a tuned-out channel, so the channel would stay held by a decision
+     * nothing here can change. Each one ends here instead, its channel decided
+     * open again as a cancel leaves it, under the tune-out's own source, so an
+     * agent's tune-out keeps the agent's provenance (the housekeeping guard
+     * reads it). A log line names the channel and says how many of the
+     * messages it diverted are held here, stored or still queued to be
+     * written, which nothing will now deliver as its backlog.
+     */
+    endTuneOutsWithoutCoordinator() {
+        const registry = this.channelRegistry;
+        if (!registry || this.tuneOutCoordinator)
+            return;
+        const primary = this.primaryAgentName ? this.agents.get(this.primaryAgentName) : undefined;
+        const ofEpoch = (epochId) => (m) => m.metadata?.tuneOut?.epochId === epochId;
+        for (const { serverId, channelId, params, source } of registry.tuneOutsOnRecord()) {
+            const diverted = typeof params.epochId !== 'string' ? 0
+                : (primary?.getContextManager().getAllMessages() ?? []).filter(ofEpoch(params.epochId)).length +
+                    this.deferredMessages.filter((m) => (m.forAgent ?? this.primaryAgentName) === this.primaryAgentName)
+                        .filter(ofEpoch(params.epochId)).length;
+            const held = diverted === 0 ? ''
+                : diverted === 1 ? ' The 1 message it diverted stays here, and nothing will deliver it as its backlog.'
+                    : ` The ${diverted} messages it diverted stay here, and nothing will deliver them as its backlog.`;
+            try {
+                registry.cancelTuneOut(serverId, channelId, 'open', source);
+            }
+            catch (err) {
+                console.error(`[tune-out] "${channelId}" on the "${serverId}" server is tuned out, and nothing on this host watches ` +
+                    `or cancels tune-outs, but ending this one failed, so it stays recorded until a start that can end it: ` +
+                    `${err instanceof Error ? err.message : String(err)}.${held}`);
+                continue;
+            }
+            console.error(`[tune-out] "${channelId}" on the "${serverId}" server was tuned out, and nothing on this host watches ` +
+                `or cancels tune-outs, so the tune-out ends here and the channel is decided open again.${held}`);
+        }
+    }
     /**
      * Build BeforeInferenceParams from agent state and trigger context.
      */
@@ -25262,11 +25660,24 @@ export class AgentFramework {
                 // carries the same ref.
                 const state = agent.state;
                 if (state.status === 'waiting_for_tools') {
-                    const cap = this.resolveToolResultInlineCap(agent).cap;
+                    // The commit stores a round as each result would be alone, or by
+                    // its share where they pass the bound together, which a sibling
+                    // still running can decide. Where the two ways differ for a result
+                    // counted here, the round is marked to be stored by its share
+                    // (toolRoundsByShare), so the count holds either way: a result
+                    // counted before the mark is the same both ways. The share is of
+                    // the round's calls, finished or not.
+                    const { cap, bound } = this.resolveToolResultInlineCap(agent);
+                    const share = toolResultShare(cap, bound, state.pending.size + state.completed.length);
                     for (let i = state.completed.length - 1; i >= 0 && collecting(); i--) {
                         const tc = state.completed[i];
                         const { text, shown } = this.storedToolResultText(agentName, tc, cap);
-                        considerToolResultImages(tc.id, tc.name, storedImageSlots(text, cap, shown), 0);
+                        const alone = storedImageSlots(text, cap, shown, bound);
+                        const byShare = storedImageSlots(text, share.cap, shown, share.bound);
+                        if (alone.length !== byShare.length || alone.some((slot, j) => slot.text !== byShare[j].text)) {
+                            this.toolRoundsByShare.add(state.completed);
+                        }
+                        considerToolResultImages(tc.id, tc.name, this.toolRoundsByShare.has(state.completed) ? byShare : alone, 0);
                     }
                 }
                 // Walk the message store tail-first in bounded windows, re-inlining