@animalabs/agent-framework 0.6.5 → 0.6.6

package/src/framework.ts

@@ -44,6 +44,9 @@ import type {
   ContextMaintenanceRun,
   ContextMaintenanceAgentRun,
   ContextMaintenanceSnapshot,
+  AgentRuntimeSettingsPatch,
+  AgentRuntimeSettingsOverrides,
+  AgentRuntimeSettingsSnapshot,
 } from './types/index.js';
 import { ProcessQueueImpl } from './queue.js';
 import { Agent } from './agent.js';
@@ -59,6 +62,30 @@ 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: string): string => n.split('--').pop()!;
 import { CheckpointManager } from './mcpl/checkpoint-manager.js';
 import { isToolAllowed } from './mcpl/tool-policy.js';
 import { EventGate } from './gate/event-gate.js';
@@ -292,6 +319,13 @@ export class AgentFramework {
   private processLoggingPersist: boolean;
   private processLoggingBroadcast: boolean;
   private activeStreams: Map<string, Promise<void>> = 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. */
+  private turnLocusPins: Map<string, string> = new Map();
   private pendingAssistantBlocks: Map<string, ContentBlock[]> = new Map();
   /** Streams the FRAMEWORK cancelled for non-terminal reasons, keyed
    *  `${agentName}:${streamId}`: an endTurn tool result or a context-budget
@@ -989,10 +1023,49 @@ 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: string): AgentRuntimeSettingsSnapshot {
+    const agent = this.agents.get(agentName);
+    if (!agent) throw new Error(`Unknown agent: ${agentName}`);
+    return agent.getRuntimeSettings();
+  }
+
+  updateAgentRuntimeSettings(
+    agentName: string,
+    patch: AgentRuntimeSettingsPatch,
+  ): AgentRuntimeSettingsSnapshot {
+    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: string,
+    keys?: Array<keyof AgentRuntimeSettingsPatch>,
+  ): AgentRuntimeSettingsSnapshot {
+    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: string): AgentRuntimeSettingsSnapshot {
+    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. */
@@ -1194,6 +1267,33 @@ export class AgentFramework {
     }
   }
 
+  private readAgentRuntimeSettings(agentName: string): AgentRuntimeSettingsOverrides | null {
+    try {
+      const data = this.store.getStateJson(FRAMEWORK_STATE_ID) as {
+        agentRuntimeSettings?: Record<string, AgentRuntimeSettingsOverrides>;
+      } | null;
+      const stored = data?.agentRuntimeSettings?.[agentName];
+      return stored ? { ...stored } : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private persistAgentRuntimeSettings(
+    agentName: string,
+    overrides: AgentRuntimeSettingsOverrides,
+  ): void {
+    const data = this.store.getStateJson(FRAMEWORK_STATE_ID);
+    const state = (data && typeof data === 'object' ? data : {}) as Record<string, unknown>;
+    const all = {
+      ...((state.agentRuntimeSettings as Record<string, AgentRuntimeSettingsOverrides> | undefined) ?? {}),
+    };
+    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.
    *
@@ -1533,6 +1633,31 @@ export class AgentFramework {
     inputSchema: { type: 'object' },
   };
 
+  private static readonly AGENT_SETTINGS_TOOL: import('./types/index.js').ToolDefinition = {
+    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. */
   private static readonly CHAT_CORE_TAGS: Record<string, string> = {
@@ -2601,6 +2726,8 @@ export class AgentFramework {
     });
 
     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);
 
@@ -2708,16 +2835,51 @@ export class AgentFramework {
           }));
           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: Array<{ participant: string; content: ContentBlock[]; metadata?: MessageMetadata }> = [];
           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 } : {}),
+                  });
+                }
+              }
             }
           }
 
@@ -2769,13 +2931,23 @@ export class AgentFramework {
               timestamp: Date.now(),
             });
           } 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
             this.pendingRequests.push({
@@ -3229,6 +3401,15 @@ export class AgentFramework {
    * Convert an MCPL push event to a context message.
    */
   private handleMcplPushEvent(event: McplPushEvent): void {
+    const triggerChannel = this.derivePushEventChannel(event.origin);
+    if (triggerChannel && this.channelRegistry) {
+      this.channelRegistry.ensureChannelRegistered(
+        event.serverId,
+        triggerChannel.channelId,
+        triggerChannel.label,
+      );
+    }
+
     const metadata: Record<string, unknown> = {
       ...event.origin,
       serverId: event.serverId,
@@ -3237,23 +3418,39 @@ export class AgentFramework {
       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
@@ -3522,11 +3719,67 @@ export class AgentFramework {
     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 = (): string | null => {
+      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<void> = Promise.resolve();
+    const enqueueSpeech = (text: string, locus: string | null): void => {
+      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 {
@@ -3599,6 +3852,43 @@ 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;
           }
@@ -3703,10 +3993,13 @@ export class AgentFramework {
               }
             }
 
-            // 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: ContentBlock): block is ContentBlock & { type: 'text' } =>
               block.type === 'text';
             const allText = response.content.filter(isTextBlock);
@@ -3906,70 +4199,54 @@ 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: string) => (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 as unknown as { name?: string }).name)
                 .filter((n): n is string => 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'})`,
+                  `[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);
+                // 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} prose segment(s) in order -> ${turnLocus ?? '(default)'}`,
+                  `[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);
                   }
@@ -4393,6 +4670,12 @@ export class AgentFramework {
       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);
@@ -4511,12 +4794,19 @@ export class AgentFramework {
       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 '' as MessageId; // Deferred — will be added after tool_result flush
+      return '' as MessageId; // Deferred — flushed at the next boundary
     }
 
     return agent.getContextManager().addMessage(participant, content, metadata);
@@ -5004,6 +5294,7 @@ export class AgentFramework {
       (event) => this.pushEvent(event),
       (event) => this.emitTrace(event as { type: TraceEvent['type']; [key: string]: unknown }),
       {
+        store: this.store,
         sendTypingFn: (serverId, channelId, metadata, op) => {
           const server = this.mcplServerRegistry!.getServer(serverId);
           if (server) {
@@ -5108,8 +5399,11 @@ export class AgentFramework {
 
     // 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);
@@ -5934,6 +6228,88 @@ export class AgentFramework {
     });
   }
 
+  private dispatchAgentSettingsToolCall(agentName: string, call: ToolCall): void {
+    this.emitTrace({
+      type: 'tool:started',
+      module: 'agent',
+      tool: call.name,
+      callId: call.id,
+      input: call.input,
+    });
+    let result: ToolResult;
+    try {
+      const input = (call.input ?? {}) as {
+        action?: unknown;
+        context_budget_tokens?: unknown;
+        tail_tokens?: unknown;
+        transition_pace_tokens?: unknown;
+        settings?: unknown;
+      };
+      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: AgentRuntimeSettingsPatch = {};
+          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: Array<keyof AgentRuntimeSettingsPatch> | undefined;
+          if (input.settings !== undefined) {
+            if (!Array.isArray(input.settings)) throw new Error('reset `settings` must be an array');
+            const names: Record<string, keyof AgentRuntimeSettingsPatch> = {
+              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. */
   private buildEventTagsResult(): Record<string, unknown> {