@animalabs/agent-framework 0.6.5 → 0.6.6

package/dist/src/framework.js

@@ -17,6 +17,29 @@ import { ConversationRouter } from './mcpl/conversation-router.js';
 import { safeSlice } from './safe-slice.js';
 import { toolResultDataToHistoryString } from './tool-result-history.js';
 import { splitProseSegments } from './prose-segments.js';
+/**
+ * Tools whose presence suppresses auto-routing of the surrounding prose,
+ * for two distinct reasons:
+ *   - `skip_reply` — the agent EXPLICITLY chose not to reply (the deliberate
+ *     "stay silent" signal).
+ *   - explicit delivery tools (channel_publish / *send_message /
+ *     *reply_message / *send_dm) — already sent the message, so routing the
+ *     prose again would double-post.
+ * `think` is deliberately NOT here: it is silent *reasoning*, but prose
+ * written around a think is the agent's actual voice and must be delivered.
+ *
+ * Scope: mid-turn rounds apply this PER ROUND (a round's prose is suppressed
+ * only by a silencing tool in that same round — live delivery can't be
+ * retracted by a later round's skip_reply); the turn's TRAILING prose keeps
+ * the historical turn-wide rule (any silencing tool anywhere in the turn
+ * suppresses it), preserving the "send_message then 'sent it.' postscript"
+ * double-post guard.
+ */
+const SILENCING_TOOLS = new Set([
+    'skip_reply', 'channel_publish', 'send_message', 'reply_message', 'send_dm',
+]);
+/** Strip the `server--` MCPL prefix from a tool name. */
+const bareToolName = (n) => n.split('--').pop();
 import { CheckpointManager } from './mcpl/checkpoint-manager.js';
 import { isToolAllowed } from './mcpl/tool-policy.js';
 import { EventGate } from './gate/event-gate.js';
@@ -146,6 +169,12 @@ export class AgentFramework {
     processLoggingPersist;
     processLoggingBroadcast;
     activeStreams = new Map();
+    /** Per-agent output locus pinned for the CURRENT logical turn (see
+     *  resolveTurnLocus in driveStream). Lives here — not in driveStream
+     *  locals — so the pin survives a context-budget stream restart, which
+     *  continues the same logical turn in a fresh driveStream. Cleared at the
+     *  start of every non-restart turn. */
+    turnLocusPins = new Map();
     pendingAssistantBlocks = new Map();
     /** Streams the FRAMEWORK cancelled for non-terminal reasons, keyed
      *  `${agentName}:${streamId}`: an endTurn tool result or a context-budget
@@ -752,10 +781,43 @@ export class AgentFramework {
                 AgentFramework.EVENT_TAGS_TOOL,
             ]
             : [];
-        if (this.mcplTools.length === 0 && channelTools.length === 0 && gateTools.length === 0) {
-            return moduleTools;
-        }
-        return [...moduleTools, ...this.mcplTools, ...channelTools, ...gateTools];
+        return [
+            ...moduleTools,
+            ...this.mcplTools,
+            ...channelTools,
+            ...gateTools,
+            AgentFramework.AGENT_SETTINGS_TOOL,
+        ];
+    }
+    getAgentRuntimeSettings(agentName) {
+        const agent = this.agents.get(agentName);
+        if (!agent)
+            throw new Error(`Unknown agent: ${agentName}`);
+        return agent.getRuntimeSettings();
+    }
+    updateAgentRuntimeSettings(agentName, patch) {
+        const agent = this.agents.get(agentName);
+        if (!agent)
+            throw new Error(`Unknown agent: ${agentName}`);
+        const result = agent.updateRuntimeSettings(patch);
+        this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+        return result;
+    }
+    resetAgentRuntimeSettings(agentName, keys) {
+        const agent = this.agents.get(agentName);
+        if (!agent)
+            throw new Error(`Unknown agent: ${agentName}`);
+        const result = agent.resetRuntimeSettings(keys);
+        this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+        return result;
+    }
+    cancelAgentRuntimeSettingsTransition(agentName) {
+        const agent = this.agents.get(agentName);
+        if (!agent)
+            throw new Error(`Unknown agent: ${agentName}`);
+        const result = agent.cancelRuntimeSettingsTransition();
+        this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+        return result;
     }
     /** Counts-only context-maintenance diagnostics for authenticated debug UIs. */
     getContextMaintenanceSnapshot() {
@@ -932,6 +994,29 @@ export class AgentFramework {
             // Non-fatal — usage tracking is best-effort
         }
     }
+    readAgentRuntimeSettings(agentName) {
+        try {
+            const data = this.store.getStateJson(FRAMEWORK_STATE_ID);
+            const stored = data?.agentRuntimeSettings?.[agentName];
+            return stored ? { ...stored } : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    persistAgentRuntimeSettings(agentName, overrides) {
+        const data = this.store.getStateJson(FRAMEWORK_STATE_ID);
+        const state = (data && typeof data === 'object' ? data : {});
+        const all = {
+            ...(state.agentRuntimeSettings ?? {}),
+        };
+        if (Object.keys(overrides).length === 0)
+            delete all[agentName];
+        else
+            all[agentName] = { ...overrides };
+        state.agentRuntimeSettings = all;
+        this.store.setStateJson(FRAMEWORK_STATE_ID, state);
+    }
     /**
      * Create an ephemeral agent that is NOT registered in the main event loop.
      *
@@ -1238,6 +1323,29 @@ export class AgentFramework {
             'tagsAll / tagsNone) or in gate.js.',
         inputSchema: { type: 'object' },
     };
+    static AGENT_SETTINGS_TOOL = {
+        name: 'agent_settings',
+        description: 'Read or change your hot runtime settings. This intentionally exposes only ' +
+            'context budget, recent raw tail size, and transition pace; model, prompts, ' +
+            'folding strategy, and other restart-bound configuration are not mutable here. ' +
+            'Lower context budgets converge gradually under the transition pace before ' +
+            'becoming the hard live limit; increases take effect immediately.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['get', 'update', 'reset', 'cancel'] },
+                context_budget_tokens: { type: 'number', description: 'Total input context budget, including the reserved response allowance.' },
+                tail_tokens: { type: 'number', description: 'Recent raw context retained verbatim.' },
+                transition_pace_tokens: { type: 'number', description: 'Maximum ordinary KV re-read/perturbation per compile while converging.' },
+                settings: {
+                    type: 'array',
+                    items: { type: 'string', enum: ['context_budget_tokens', 'tail_tokens', 'transition_pace_tokens'] },
+                    description: 'For reset: settings to restore to recipe values. Omit to reset all.',
+                },
+            },
+            required: ['action'],
+        },
+    };
     /** Reserved chat:* core vocabulary (MCPL RFC-001 §4) — short descriptions so
      *  the agent can author rules without reading the spec. */
     static CHAT_CORE_TAGS = {
@@ -2155,6 +2263,9 @@ export class AgentFramework {
             debugLogContext: !!process.env.DEBUG_CONTEXT,
         });
         const agent = new Agent(config, contextManager, this.membrane);
+        const restoredSettings = this.readAgentRuntimeSettings(config.name);
+        if (restoredSettings)
+            agent.restoreRuntimeSettings(restoredSettings);
         this.agents.set(config.name, agent);
         this.agentConfigs.set(config.name, config);
         // First non-ephemeral agent becomes the primary for message routing
@@ -2247,16 +2358,49 @@ export class AgentFramework {
                         isError: tc.result.isError,
                     }));
                     agent.getContextManager().addMessage('user', toolResultContent);
-                    // Flush any messages that were deferred while waiting for tool results.
-                    // Route to the PRIMARY agent — deferred messages are framework-level
-                    // (e.g. subagent return notifications) meant for the main conversation.
+                    // Flush any messages that were deferred while this turn was in
+                    // flight. Route to the PRIMARY agent — deferred messages are
+                    // framework-level (module messages, push events, subagent return
+                    // notifications) meant for the main conversation.
+                    //
+                    // Hear-while-acting: messages flushed into THIS agent's own window
+                    // are also collected for mid-turn injection — passed to the membrane
+                    // with the tool results below, so the NEXT inference round of the
+                    // 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, same metadata, and compile() emits recent messages
+                    // verbatim, so the next turn's compiled prefix byte-matches the
+                    // live request (prompt-cache safe).
+                    //
+                    // The queue is drained ONLY at the target agent's own boundary:
+                    // draining at another agent's boundary would store the messages
+                    // mid-turn in the target's window without injecting them into the
+                    // target's live stream (deaf agent + window/live divergence). Left
+                    // queued, they flush at the target's own next boundary — with
+                    // injection — or in driveStream's finally when its turn ends.
+                    const midTurnInjections = [];
                     if (this.deferredMessages.length > 0) {
-                        const deferred = this.deferredMessages.splice(0);
-                        const primary = this.primaryAgentName
-                            ? this.agents.get(this.primaryAgentName)
-                            : agent;
-                        for (const msg of deferred) {
-                            (primary ?? agent).getContextManager().addMessage(msg.participant, msg.content, msg.metadata);
+                        const target = (this.primaryAgentName ? this.agents.get(this.primaryAgentName) : undefined) ?? agent;
+                        if (target === agent) {
+                            const deferred = this.deferredMessages.splice(0);
+                            for (const msg of deferred) {
+                                target.getContextManager().addMessage(msg.participant, msg.content, msg.metadata);
+                                // Injection guards: tool blocks would corrupt the tool-cycle
+                                // structure the membrane enforces, and a message named as the
+                                // agent itself would render as an ASSISTANT turn on the wire
+                                // (an unintended prefill the model would continue). Such
+                                // messages stay window-only — visible next turn.
+                                const hasToolBlocks = msg.content.some((b) => b.type === 'tool_use' || b.type === 'tool_result');
+                                if (!hasToolBlocks && msg.participant !== agent.name) {
+                                    midTurnInjections.push({
+                                        participant: msg.participant,
+                                        content: msg.content,
+                                        ...(msg.metadata ? { metadata: msg.metadata } : {}),
+                                    });
+                                }
+                            }
                         }
                     }
                     // Check if any tool result requested endTurn
@@ -2307,11 +2451,18 @@ export class AgentFramework {
                         });
                     }
                     else if (currentState.stream) {
-                        // Streaming path: convert results and resume the stream
+                        // Streaming path: convert results and resume the stream.
+                        // Mid-turn messages collected above ride along as injected user
+                        // messages (membrane ≥0.5.72) — appended after the tool_result
+                        // envelope so the next round of THIS turn hears them.
                         const membraneResults = currentState.toolResults.map(tc => this.toMembraneToolResult(tc.id, tc.result, maxChars));
-                        currentState.stream.provideToolResults(membraneResults);
+                        currentState.stream.provideToolResults(membraneResults, midTurnInjections.length > 0 ? { injectedMessages: midTurnInjections } : undefined);
                         agent.setStreaming(currentState.stream);
-                        this.emitTrace({ type: 'inference:stream_resumed', agentName: agent.name });
+                        this.emitTrace({
+                            type: 'inference:stream_resumed',
+                            agentName: agent.name,
+                            ...(midTurnInjections.length > 0 ? { injectedMessages: midTurnInjections.length } : {}),
+                        });
                     }
                     else {
                         // Non-streaming fallback: schedule re-inference
@@ -2689,6 +2840,10 @@ export class AgentFramework {
      * Convert an MCPL push event to a context message.
      */
     handleMcplPushEvent(event) {
+        const triggerChannel = this.derivePushEventChannel(event.origin);
+        if (triggerChannel && this.channelRegistry) {
+            this.channelRegistry.ensureChannelRegistered(event.serverId, triggerChannel.channelId, triggerChannel.label);
+        }
         const metadata = {
             ...event.origin,
             serverId: event.serverId,
@@ -2696,17 +2851,36 @@ export class AgentFramework {
             eventId: event.eventId,
             triggered: event.triggerInference ?? false,
         };
-        const id = this.addMessage('user', event.content, metadata);
-        this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:push-event' });
-        // Some push events carry a channel of origin (Discord DMs arrive here, not
-        // via channels/incoming, because discord-mcpl forwards them with the channel
-        // closed). Register + open that channel so routeSpeech can resolve it, and
-        // thread it onto the wake request so the reply routes back to it instead of
-        // the global locus (item-3 redux, DM sub-case).
-        const triggerChannel = this.derivePushEventChannel(event.origin);
-        if (triggerChannel && this.channelRegistry) {
-            this.channelRegistry.ensureChannelRegistered(event.serverId, triggerChannel.channelId, triggerChannel.label);
+        const content = [...event.content];
+        const addressedWhileClosed = triggerChannel &&
+            event.tags?.includes('chat:addressed') &&
+            this.channelRegistry &&
+            !this.channelRegistry.isChannelOpen(triggerChannel.channelId);
+        if (addressedWhileClosed) {
+            const descriptor = this.channelRegistry.getDescriptor(triggerChannel.channelId);
+            const messageId = typeof event.origin?.messageId === 'string'
+                ? event.origin.messageId
+                : event.eventId;
+            const maxBackscroll = descriptor?.capabilities?.history?.maxMessages ?? 0;
+            content.push({
+                type: 'text',
+                text: `\n[Channel invitation] You were addressed in closed channel ` +
+                    `"${triggerChannel.label ?? triggerChannel.channelId}" (${triggerChannel.channelId}, server ${event.serverId}). ` +
+                    `You received this one message without subscribing. ` +
+                    (maxBackscroll > 0
+                        ? `To subscribe, call channel_open with channelId, serverId "${event.serverId}", backscroll (0-${maxBackscroll}), and beforeMessageId "${messageId}". `
+                        : `To subscribe, call channel_open with this channelId and serverId "${event.serverId}". `) +
+                    `You may reply once without subscribing. To remain closed, call channel_decline ` +
+                    `with channelId, serverId "${event.serverId}", and messageId "${messageId}"; ` +
+                    `optionally set acknowledge to a surface value such as 👀.`,
+            });
+            metadata.channelInvitation = true;
+            metadata.channelOpen = false;
+            metadata.channelId = triggerChannel.channelId;
+            metadata.invitationMessageId = messageId;
         }
+        const id = this.addMessage('user', content, metadata);
+        this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:push-event' });
         if (event.triggerInference) {
             // Default broadcast excludes conversation forks (channel-driven).
             const targetAgents = event.targetAgents
@@ -2935,11 +3109,64 @@ export class AgentFramework {
         const requestId = `${agent.name}-${startTime}-${Math.random().toString(36).slice(2, 8)}`;
         const myStreamId = agent.streamId;
         let hadToolCalls = false;
+        // ---- Present-while-acting turn state ---------------------------------
+        // Output locus for THIS turn: resolved lazily at the first routed prose
+        // segment and pinned for the rest of the turn (mid-turn rounds AND the
+        // trailing prose at 'complete'), so one turn's voice stays in one channel
+        // even when a queued inbound from another channel overwrites the
+        // per-agent triggering channel between segments (PR #32). The pin lives
+        // in `turnLocusPins` so it survives a context-budget stream restart. A
+        // null resolution is NOT pinned — a turn whose locus is unresolvable
+        // early (e.g. heartbeat-triggered) may still resolve a channel by the
+        // time later prose routes.
+        if (trigger?.reason !== 'context_budget_restart') {
+            this.turnLocusPins.delete(agent.name);
+        }
+        const resolveTurnLocus = () => {
+            let locus = this.turnLocusPins.get(agent.name) ?? null;
+            if (locus === null && this.channelRegistry) {
+                locus = this.channelRegistry.resolveLocus(agent.name);
+                if (locus !== null)
+                    this.turnLocusPins.set(agent.name, locus);
+            }
+            return locus;
+        };
+        // Ordered delivery chain for live-routed prose. Links are enqueued
+        // WITHOUT awaiting in the stream-event loop — an awaited network post
+        // here would stall consumption of the next round's events by
+        // segments × RTT on every prose-bearing round. The 'complete' case
+        // awaits the chain before routing trailing prose, so in-channel ordering
+        // is preserved end-to-end. Each link catches its own error: one failed
+        // post must not silence the rest of the turn.
+        let turnSpeechChain = Promise.resolve();
+        const enqueueSpeech = (text, locus) => {
+            turnSpeechChain = turnSpeechChain
+                .then(async () => {
+                await this.channelRegistry.routeSpeech(agent.name, text, locus);
+            })
+                .catch((err) => console.error('mid-turn speech routing failed:', err));
+        };
+        // Sticky silencing: once any round uses a SILENCING_TOOLS member,
+        // prose from that round ONWARD is suppressed — skip_reply means "stay
+        // silent", an explicit send means "I deliver my own words". Earlier
+        // rounds' prose was already delivered live and cannot be retracted.
+        let turnSilenced = false;
+        // Live routing is only trusted when the membrane provides verbatim
+        // round-scoped blocks (roundContent, native tool mode, membrane ≥0.5.64).
+        // The fallback `preamble` is CUMULATIVE in XML mode (assistant prefill +
+        // all earlier rounds' prose and raw tool/thinking XML) — live-routing it
+        // would repost the transcript and leak thinking every round. When no
+        // round was live-routed, the 'complete' case falls back to the
+        // historical whole-turn routing so fallback-mode prose is still
+        // delivered exactly once, at turn end.
+        let liveProseRouting = false;
         // Typing indicator: show "<agent> is typing…" in the channel she's
         // responding to, for the whole duration of this turn. Started here (paired
         // with the finally below, so it can never leak) and refreshed on a 7s
         // interval by the ChannelRegistry until stopped on any exit path.
-        const typingChannel = this.channelRegistry?.getDefaultPublishChannel();
+        const typingChannel = this.channelRegistry
+            ? trigger?.channelId ?? this.channelRegistry.getDefaultPublishChannel()
+            : null;
         if (typingChannel)
             this.channelRegistry.startTyping(typingChannel);
         try {
@@ -3005,6 +3232,39 @@ export class AgentFramework {
                         for (const call of event.calls) {
                             this.dispatchToolCall(agent.name, call);
                         }
+                        // Speak-while-acting: route THIS round's prose to the locus NOW
+                        // instead of batching every segment to the end of the turn. Long
+                        // tool-using turns (robot control, live sessions) otherwise dump
+                        // the whole narration in one blob when the turn finally settles —
+                        // and, worse, make "talking" and "acting" feel mutually exclusive
+                        // to the agent. Mid-turn prose is speech (delivered live, in
+                        // order, via the turn's speech chain — never awaited here); the
+                        // `think` tool remains the private channel. Silencing is STICKY
+                        // from the round it occurs (see SILENCING_TOOLS). Only rounds
+                        // with verbatim roundContent are live-routed (see liveProseRouting
+                        // note above — the fallback preamble is cumulative in XML mode).
+                        if (this.channelRegistry) {
+                            const roundToolNames = event.calls.map((c) => c.name);
+                            if (roundToolNames.some((n) => SILENCING_TOOLS.has(bareToolName(n)))) {
+                                turnSilenced = true;
+                            }
+                            if (roundContent && roundContent.length > 0) {
+                                liveProseRouting = true;
+                                const roundSegments = splitProseSegments(assistantBlocks);
+                                if (roundSegments.length > 0) {
+                                    if (turnSilenced) {
+                                        console.error(`[routing] ${agent.name}: mid-turn round [${roundToolNames.join(', ')}] -> prose NOT routed (turn silenced)`);
+                                    }
+                                    else {
+                                        const locus = resolveTurnLocus();
+                                        console.error(`[routing] ${agent.name}: mid-turn round [${roundToolNames.join(', ')}] -> routing ${roundSegments.length} prose segment(s) live -> ${locus ?? '(default)'}`);
+                                        for (const seg of roundSegments) {
+                                            enqueueSpeech(seg, locus);
+                                        }
+                                    }
+                                }
+                            }
+                        }
                         // Stream's async iterator blocks on next() until provideToolResults() is called
                         break;
                     }
@@ -3098,10 +3358,13 @@ export class AgentFramework {
                                 console.error('afterInference hook error:', error);
                             }
                         }
-                        // Separate speech from thoughts.
-                        // When tools were used, ALL text is thoughts (the tools themselves are
-                        // the agent's actions — surrounding text is just reasoning).
-                        // When no tools were used, all text is speech.
+                        // Separate speech from thoughts — for MODULE dispatch only
+                        // (dispatchSpeech / TUI rendering below). This split does NOT
+                        // decide what reaches the channel: mid-turn prose is routed live
+                        // per round (see the 'tool-calls' case) and trailing prose is
+                        // routed after this block. On a tool-using turn the module-level
+                        // convention remains "text is thoughts"; on a text-only turn all
+                        // text is speech.
                         const isTextBlock = (block) => block.type === 'text';
                         const allText = response.content.filter(isTextBlock);
                         const speechContent = hadToolCalls ? [] : allText;
@@ -3273,65 +3536,48 @@ export class AgentFramework {
                             }
                         }
                         else if (this.channelRegistry && hadToolCalls && allText.length > 0) {
-                            // Tool-call turn that also produced prose. Per design, route the
-                            // prose to the locus as a reply UNLESS the turn used an explicit
-                            // send/publish tool (channel_publish, *--send_message,
-                            // *--reply_message, *--send_dm) — already delivered, so routing
-                            // again would double-post. `think` and other non-sending tools
-                            // (shell, workspace, etc.) still let the agent speak in the same
-                            // turn. The global speech/thoughts split is left untouched
-                            // (module/TUI rendering unaffected) — this only governs what
-                            // reaches the channel.
-                            // Tools whose presence suppresses the trailing prose, for two
-                            // distinct reasons:
-                            //   - `skip_reply` — the agent EXPLICITLY chose not to reply this
-                            //     turn (the deliberate "stay silent" signal).
-                            //   - explicit delivery tools (channel_publish / *send_message /
-                            //     *reply_message / *send_dm) — already sent the message, so
-                            //     routing it again would double-post.
-                            // `think` is deliberately NOT here: it is silent *reasoning*, but
-                            // prose written after a think is the agent's actual reply and must
-                            // be delivered. (A think-only turn has no trailing prose and stays
-                            // silent via the `!t` check below.)
-                            const SILENCING = new Set([
-                                'skip_reply', 'channel_publish', 'send_message', 'reply_message', 'send_dm',
-                            ]);
-                            const bare = (n) => (n.includes('--') ? n.split('--').pop() : n);
+                            // Tool-call turn that also produced prose. When live routing was
+                            // active (native roundContent), each mid-turn round's prose was
+                            // already delivered when that round yielded — only the TRAILING
+                            // prose (blocks after the last tool round) remains here. On the
+                            // fallback path (XML tool mode / older membrane: no roundContent,
+                            // so nothing was live-routed) the historical behavior applies:
+                            // route the whole turn's parsed segments, once, now. The global
+                            // speech/thoughts split is left untouched (module/TUI rendering
+                            // unaffected) — this only governs what reaches the channel.
+                            //
+                            // Silencing here is the sticky flag ∪ turn-wide scan: the scan
+                            // (over the whole turn's tool_use blocks) covers the fallback
+                            // path and the "send_message then a 'sent it.' postscript"
+                            // double-post guard; the sticky flag is its live-rounds twin.
                             const toolNames = response.content
                                 .filter((b) => b.type === 'tool_use')
                                 .map((b) => b.name)
                                 .filter((n) => typeof n === 'string');
-                            const silenced = toolNames.some((n) => SILENCING.has(bare(n)));
-                            // Split the turn's content into ordered prose segments, broken at
-                            // each tool_use / tool_result boundary. `response.content` holds the
-                            // WHOLE turn's blocks in provider order — earlier tool rounds
-                            // included (see the trailing-slice note above, which slices exactly
-                            // because the full turn is present) — so a left-to-right walk
-                            // reconstructs the emission order. Interleaved prose
-                            // ("msgA → [tool] → msgB → [tool] → msgC") is then delivered as
-                            // separate messages IN ORDER instead of being collapsed into one
-                            // trailing post (item 4). The silencing rule stays turn-wide: an
-                            // explicit send / skip suppresses ALL auto-routed prose this turn,
-                            // preserving the double-post guard.
-                            const segments = splitProseSegments(response.content);
+                            const silenced = turnSilenced || toolNames.some((n) => SILENCING_TOOLS.has(bareToolName(n)));
+                            const segments = splitProseSegments(liveProseRouting ? terminalContent : response.content);
+                            // Preserve in-channel ordering: everything enqueued live must
+                            // land before the trailing prose. Awaited even when silenced —
+                            // the chain may still be flushing earlier rounds' posts.
+                            await turnSpeechChain;
                             if (silenced || segments.length === 0) {
-                                console.error(`[routing] ${agent.name}: tool-call turn [${toolNames.join(', ') || 'none'}] -> NOT routed ` +
-                                    `(${silenced ? 'silencing tool / explicit send' : 'no prose'})`);
+                                console.error(`[routing] ${agent.name}: tool-call turn [${toolNames.join(', ') || 'none'}] -> trailing prose NOT routed ` +
+                                    `(${silenced ? 'silencing tool / explicit send' : 'no trailing prose'})`);
                             }
                             else {
-                                // Snapshot the locus ONCE. This loop dispatches AFTER the agent
-                                // is idle (see PR #32 note below), so a queued inbound from
-                                // another channel can start a NEW turn and overwrite the per-agent
-                                // triggering channel (`activeTriggerChannels`) BETWEEN segments —
-                                // splitting one turn's reply across channels (the residual
-                                // multi-segment race left by 83dedf8's per-agent locus). Pin every
-                                // segment of THIS turn to the channel resolved right now.
-                                const turnLocus = this.channelRegistry.resolveLocus(agent.name);
-                                console.error(`[routing] ${agent.name}: tool-call turn [${toolNames.join(', ')}] -> routing ${segments.length} prose segment(s) in order -> ${turnLocus ?? '(default)'}`);
+                                // Reuse the locus pinned at the turn's first live-routed
+                                // segment (or resolve it now for a turn whose only prose is
+                                // trailing). This dispatch runs AFTER the agent is idle (see
+                                // PR #32 note below), so a queued inbound from another channel
+                                // could otherwise overwrite the per-agent triggering channel
+                                // between segments — and a turn that narrated live into one
+                                // channel must not land its postscript in another.
+                                const locus = resolveTurnLocus();
+                                console.error(`[routing] ${agent.name}: tool-call turn [${toolNames.join(', ')}] -> routing ${segments.length} ${liveProseRouting ? 'trailing ' : ''}prose segment(s) -> ${locus ?? '(default)'}`);
                                 // Deliver sequentially (await each) so the segments land in order.
                                 for (const seg of segments) {
                                     try {
-                                        await this.channelRegistry.routeSpeech(agent.name, seg, turnLocus);
+                                        await this.channelRegistry.routeSpeech(agent.name, seg, locus);
                                     }
                                     catch (err) {
                                         console.error('speech routing failed:', err);
@@ -3729,6 +3975,11 @@ export class AgentFramework {
             this.dispatchChannelToolCall(agentName, enrichedCall);
             return;
         }
+        // Route the agent's typed, allowlisted hot-settings surface.
+        if (enrichedCall.name === 'agent_settings') {
+            this.dispatchAgentSettingsToolCall(agentName, enrichedCall);
+            return;
+        }
         // Route gate_status tool
         if (enrichedCall.name === 'gate_status' && this.eventGate) {
             this.dispatchGateToolCall(agentName, enrichedCall);
@@ -3829,12 +4080,19 @@ export class AgentFramework {
         if (!agent) {
             throw new Error('No agents configured');
         }
-        // If any agent has pending assistant blocks (tool_use not yet flushed),
-        // defer non-tool_result messages to preserve tool_use → tool_result adjacency.
+        // Defer non-tool_result messages while a tool cycle is mid-flight
+        // (pendingAssistantBlocks: preserves tool_use → tool_result adjacency)
+        // OR while the target agent has a live stream at all. A message stored
+        // mid-stream lands BEFORE the turn's assistant blocks in the window even
+        // though the live conversation never saw it — so the next compile
+        // diverges from the live prefix (prompt-cache bust) and the message
+        // misses mid-turn injection. Deferred messages flush at the agent's next
+        // tool boundary (where they are ALSO injected into the live stream —
+        // hear-while-acting) or in driveStream's finally when the turn ends.
         const hasToolResult = content.some(b => b.type === 'tool_result');
-        if (!hasToolResult && this.pendingAssistantBlocks.size > 0) {
+        if (!hasToolResult && (this.pendingAssistantBlocks.size > 0 || this.activeStreams.has(agent.name))) {
             this.deferredMessages.push({ participant, content, metadata });
-            return ''; // Deferred — will be added after tool_result flush
+            return ''; // Deferred — flushed at the next boundary
         }
         return agent.getContextManager().addMessage(participant, content, metadata);
     }
@@ -4222,6 +4480,7 @@ export class AgentFramework {
         this.checkpointManager = new CheckpointManager(this.store, (event) => this.emitTrace(event));
         // Channel registry (Step 7)
         this.channelRegistry = new ChannelRegistry(this.mcplServerRegistry, this.featureSetManager, (event) => this.pushEvent(event), (event) => this.emitTrace(event), {
+            store: this.store,
             sendTypingFn: (serverId, channelId, metadata, op) => {
                 const server = this.mcplServerRegistry.getServer(serverId);
                 if (server) {
@@ -4314,8 +4573,8 @@ export class AgentFramework {
         this.mcplServerConfigs.set(config.id, config);
         // Record per-server channel subscription policy before the server
         // registers channels — handleRegister fires during the handshake.
-        if (config.channelSubscription !== undefined && this.channelRegistry) {
-            this.channelRegistry.setSubscriptionPolicy(config.id, config.channelSubscription);
+        if (this.channelRegistry) {
+            this.channelRegistry.setSubscriptionPolicy(config.id, config.channelSubscription ?? 'manual');
         }
         const connection = await this.mcplServerRegistry.addServer(config, this.mcplHostCapabilities);
         // Wire event listeners then flush any events that arrived during the
@@ -5021,6 +5280,84 @@ export class AgentFramework {
             endTurn: true,
         });
     }
+    dispatchAgentSettingsToolCall(agentName, call) {
+        this.emitTrace({
+            type: 'tool:started',
+            module: 'agent',
+            tool: call.name,
+            callId: call.id,
+            input: call.input,
+        });
+        let result;
+        try {
+            const input = (call.input ?? {});
+            switch (input.action) {
+                case 'get':
+                    result = { success: true, data: this.getAgentRuntimeSettings(agentName) };
+                    break;
+                case 'cancel':
+                    result = { success: true, data: this.cancelAgentRuntimeSettingsTransition(agentName) };
+                    break;
+                case 'update': {
+                    const patch = {};
+                    if (input.context_budget_tokens !== undefined) {
+                        patch.contextBudgetTokens = Number(input.context_budget_tokens);
+                    }
+                    if (input.tail_tokens !== undefined)
+                        patch.tailTokens = Number(input.tail_tokens);
+                    if (input.transition_pace_tokens !== undefined) {
+                        patch.transitionPaceTokens = Number(input.transition_pace_tokens);
+                    }
+                    result = { success: true, data: this.updateAgentRuntimeSettings(agentName, patch) };
+                    break;
+                }
+                case 'reset': {
+                    let keys;
+                    if (input.settings !== undefined) {
+                        if (!Array.isArray(input.settings))
+                            throw new Error('reset `settings` must be an array');
+                        const names = {
+                            context_budget_tokens: 'contextBudgetTokens',
+                            tail_tokens: 'tailTokens',
+                            transition_pace_tokens: 'transitionPaceTokens',
+                        };
+                        keys = input.settings.map((name) => {
+                            if (typeof name !== 'string' || !names[name]) {
+                                throw new Error(`Unknown reset setting: ${String(name)}`);
+                            }
+                            return names[name];
+                        });
+                    }
+                    result = { success: true, data: this.resetAgentRuntimeSettings(agentName, keys) };
+                    break;
+                }
+                default:
+                    throw new Error('agent_settings: action must be get, update, reset, or cancel');
+            }
+        }
+        catch (error) {
+            result = {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+                isError: true,
+            };
+        }
+        this.emitTrace({
+            type: result.isError ? 'tool:failed' : 'tool:completed',
+            module: 'agent',
+            tool: call.name,
+            callId: call.id,
+            durationMs: 0,
+            ...(result.isError ? { error: result.error } : {}),
+        });
+        this.pushEvent({
+            type: 'tool-result',
+            callId: call.id,
+            agentName,
+            moduleName: 'agent',
+            result,
+        });
+    }
     /** Aggregate the event-tag vocabulary: reserved chat:* core + each connected
      *  server's declared tag ontology + gate.js status. */
     buildEventTagsResult() {