@animalabs/agent-framework 0.6.10 → 0.7.2

package/dist/src/framework.js

@@ -11,11 +11,16 @@ import { FeatureSetManager } from './mcpl/feature-set-manager.js';
 import { ScopeManager } from './mcpl/scope-manager.js';
 import { HookOrchestrator } from './mcpl/hook-orchestrator.js';
 import { PushHandler } from './mcpl/push-handler.js';
+import { parseProsePrefix } from './mcpl/prose-grammar.js';
+import { ProseStreamRouter } from './mcpl/prose-stream-router.js';
 import { InferenceRouter } from './mcpl/inference-router.js';
 import { ChannelRegistry } from './mcpl/channel-registry.js';
 import { ConversationRouter } from './mcpl/conversation-router.js';
 import { safeSlice } from './safe-slice.js';
 import { toolResultDataToHistoryString } from './tool-result-history.js';
+import { randomUUID } from 'node:crypto';
+import { PyRunner, buildInjectedTools } from './code-execution/py-runner.js';
+import { buildCodeExecutionToolDefinition, CODE_EXECUTION_TOOL_NAME, } from './code-execution/tool-definition.js';
 import { splitProseSegments } from './prose-segments.js';
 /** Detect a supported image media type from magic bytes (the model API
  *  rejects mislabeled media types, so trust bytes over extensions).
@@ -57,6 +62,99 @@ function sniffImageMediaType(data) {
 const SILENCING_TOOLS = new Set([
     'skip_reply', 'channel_publish', 'send_message', 'reply_message', 'send_dm',
 ]);
+/**
+ * True when an injected message is real conversational input — something the
+ * agent might actually be replying to — rather than ambient machinery.
+ * System markers (`system: true` — send-failed notices, routing notices) and
+ * reactions (`chat:reaction` tag, MCPL RFC-001) don't count: they must not
+ * clear explicit-send suppression, and they never influence routing.
+ */
+const isConversationalInjection = (metadata) => {
+    if (!metadata)
+        return true;
+    const m = metadata;
+    if (m.system === true)
+        return false;
+    if (Array.isArray(m.tags) && m.tags.includes('chat:reaction'))
+        return false;
+    return true;
+};
+/**
+ * Explicit delivery tools whose successful use into a closed channel OPENS
+ * it (send implies engagement — see openIfClosedForSend). Bare tool names,
+ * matched after stripping the MCPL server prefix.
+ */
+const SEND_ENGAGEMENT_TOOLS = new Set([
+    'send_message', 'reply_message', 'send_dm', 'send_file', 'send_files',
+]);
+/**
+ * Best-effort extraction of the delivered channel id from an MCPL send-tool
+ * result (the discord-mcpl send tools return JSON like
+ * `{"messageId":"…","channelId":"…"}` as a text block). Returns undefined on
+ * any shape mismatch — the caller falls back to the tool's input args.
+ */
+function extractChannelIdFromToolResult(content) {
+    const text = content?.find((c) => c.type === 'text' && c.text)?.text;
+    if (!text)
+        return undefined;
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed.channelId === 'string' && parsed.channelId.length > 0
+            ? parsed.channelId
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * True when an incoming channel message explicitly addressed the agent.
+ * Primary signal is the MCPL RFC-001 `chat:addressed` tag (mention / reply /
+ * DM, as classified by the server); the metadata booleans are the fallback
+ * for servers that predate tags. Addressed messages outrank ambient chatter
+ * when picking a turn's frozen speech locus.
+ */
+const isAddressedMessage = (tags, _metadata) => Array.isArray(tags) && tags.includes('chat:addressed');
+// parseProsePrefix moved to ./mcpl/prose-grammar.ts — ONE grammar shared with
+// the outgoing-stream router (Spec 14.3), so streamed chunks and delivered
+// envelopes can never disagree on what is a prefix.
+/** One-time primer appended when an agent's proseRouting mode changes. */
+function proseModePrimer(mode) {
+    if (mode === 'locus') {
+        return '[prose-routing] Mode change: your plain text auto-routes to the ' +
+            'conversational locus again. `>>` destination prefixes are no longer needed.';
+    }
+    // Deliberately terse: a short event-style notice is classifier-safe from
+    // the user role (ablation D, 2026-07-24), while the full grammar as a user
+    // message drew a deterministic reasoning_extraction refusal (ablation A/B).
+    // The grammar is TAUGHT BY BOUNCE: the first undelivered text produces a
+    // notice with the exact resend syntax, and the full reference is available
+    // on demand via the prose_help tool (a tool RESULT is model-requested
+    // content — the safest role there is). Nothing is injected into the system
+    // prompt: those bytes belong to the recipe, and the deepest KV prefix must
+    // not vary with framework code.
+    return ('[prose-routing] Output mode changed: plain text is delivered only with a ' +
+        'destination prefix line, e.g. ">>#channel-name your text". ' +
+        'The prose_help tool shows the full syntax.');
+}
+/** Full `>>` routing reference, served as the prose_help TOOL RESULT (never
+ *  injected ambiently — see proseModePrimer note). */
+const PROSE_ROUTING_HELP = 'Plain-text output routing (explicit mode):\n' +
+    '  >>#channel-name …    or    >>@person …  (DM)    or    >>service:guild:id …\n' +
+    '  One message may hold several sections: each line starting with ">>" begins\n' +
+    '  a new envelope, routed to its own destination independently.\n' +
+    '  The first destination in a turn applies to the rest of that turn.\n' +
+    '  Append " !" after the destination (e.g. ">>#ops !") to start your next turn\n' +
+    '  immediately when this one ends, instead of pausing until the next event.\n' +
+    '  >>skip_reply — text stays in your context only, like the skip_reply tool.\n' +
+    'Text without a destination is not delivered: it is retained, and a notice will\n' +
+    'prompt you to resend — reply e.g. ">>#channel {{unsent}}" to deliver the retained\n' +
+    'text unchanged. Send tools (send_message, send_dm, …) are unaffected.';
+const PROSE_HELP_TOOL = {
+    name: 'prose_help',
+    description: 'Show the plain-text output routing syntax (destination prefixes, resend token, skip).',
+    inputSchema: { type: 'object', properties: {} },
+};
 /** Strip the `server--` MCPL prefix from a tool name. */
 const bareToolName = (n) => n.split('--').pop();
 import { CheckpointManager } from './mcpl/checkpoint-manager.js';
@@ -209,20 +307,37 @@ 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. A mid-turn
-     *  injected channel message replaces the pin for the next conversational
-     *  round; otherwise it remains stable. Cleared at the start of every
-     *  non-restart turn. */
+    /** Per-agent output locus FROZEN for the CURRENT logical turn. Resolved
+     *  eagerly in startAgentStream (home → addressed trigger → global default)
+     *  and never moved until the next turn: mid-turn injected messages — ambient
+     *  chatter, reactions, system markers — must not hijack where the agent's
+     *  plain prose lands (2026-07-21 Cairn lounge misroute). 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 or
+     *  re-set at the start of every non-restart turn. */
     turnLocusPins = new Map();
-    /** A tool boundary injected fresh external input into the live stream.
-     *  Presence (including a null value) tells driveStream to clear sticky
-     *  explicit-send suppression before handling the next model round. A
-     *  string also moves that round's reply locus to the newest injected
-     *  channel. */
-    midTurnRoutingResets = new Map();
+    /** A tool boundary injected fresh CONVERSATIONAL input (a real message —
+     *  not a reaction or a system marker) into the live stream. Tells
+     *  driveStream to clear sticky explicit-send suppression before handling
+     *  the next model round. Never affects routing: the turn locus is frozen. */
+    midTurnInputSignals = new Set();
+    /** Last outbound locus announced to each agent as a durable `[routing]`
+     *  window message. Announce-on-change only: steady state emits nothing
+     *  (KV-safe, no per-turn chatter). In-memory — after a process restart the
+     *  first turn's locus is announced once to re-establish the baseline. */
+    lastAnnouncedLocus = new Map();
+    // ---- Explicit prose routing (docs/explicit-prose-routing.md) ----------
+    /** Latest bounced (undelivered) prose per agent — the `{{unsent}}` source. */
+    proseClipboards = new Map();
+    /** Sticky per-TURN delivery target set by the turn's first `>>` prefix.
+     *  Cleared at every non-restart turn start; survives context restarts. */
+    proseTargetPins = new Map();
+    /** Agents whose current turn requested `!` continuation — re-woken when the
+     *  turn completes instead of pausing until the next external event. */
+    proseContinuations = new Set();
+    /** Consecutive bounce-wakes per agent; capped so an agent that keeps
+     *  emitting unprefixed prose can't wake-loop (notices still append). */
+    proseBounceStreaks = new Map();
     pendingAssistantBlocks = new Map();
     /** Streams the FRAMEWORK cancelled for non-terminal reasons, keyed
      *  `${agentName}:${streamId}`: an endTurn tool result or a context-budget
@@ -312,6 +427,17 @@ export class AgentFramework {
     /** Forks whose TTL closure turn has been queued — disposed (removed from
      * agents/agentConfigs/conversationAgentHomes) when their stream ends. */
     closingConversationAgents = new Set();
+    // Client-side programmatic tool calling (`code_execution`). Null unless
+    // config.codeExecution.enabled. One PyRunner per agent (interpreter state
+    // is per-agent, like a per-agent container); waiters resolve script-inner
+    // tool calls dispatched through the normal dispatchToolCall path.
+    codeExecutionConfig = null;
+    codeExecutionRunners = new Map();
+    scriptToolWaiters = new Map();
+    /** Agents whose running script hit an endTurn-carrying inner result —
+     *  deferred and applied to the final code_execution result instead of
+     *  cancelling the stream mid-script (which would wedge the turn). */
+    scriptDeferredEndTurn = new Set();
     mcplTools = [];
     mcplToolRefreshInFlight = false;
     mcplToolRefreshPending = false;
@@ -529,6 +655,9 @@ export class AgentFramework {
         // Stored for lazy MCPL initialization (connectMcplServer on a framework
         // that started with zero configured servers).
         framework.mcplInferenceRoutingConfig = config.inferenceRouting ?? null;
+        // Client-side programmatic tool calling (code_execution). Config is only
+        // retained when enabled — everything downstream gates on the field.
+        framework.codeExecutionConfig = config.codeExecution?.enabled ? config.codeExecution : null;
         // Initialize MCPL subsystems if configured
         if (config.mcplServers && config.mcplServers.length > 0) {
             // Validate tool prefixes: no collisions with module names or between servers
@@ -609,6 +738,13 @@ export class AgentFramework {
     async stop() {
         this.running = false;
         this.queue.close();
+        // Kill running code_execution scripts before cancelling streams: a
+        // zombie script must not keep firing side-effectful tool calls into a
+        // framework that is shutting down.
+        for (const runner of this.codeExecutionRunners.values()) {
+            runner.dispose();
+        }
+        this.codeExecutionRunners.clear();
         // Cancel all active streams
         for (const agent of this.agents.values()) {
             if (agent.state.status === 'streaming' ||
@@ -874,6 +1010,9 @@ export class AgentFramework {
             ...(this.getWorkspaceModule()
                 ? [AgentFramework.SAVE_IMAGE_TOOL, AgentFramework.READ_IMAGE_TOOL]
                 : []),
+            ...(this.codeExecutionConfig
+                ? [buildCodeExecutionToolDefinition(this.codeExecutionConfig)]
+                : []),
         ];
     }
     /** The registered workspace module, if any (used by save_image). */
@@ -988,20 +1127,48 @@ export class AgentFramework {
             throw new Error(`Unknown agent: ${agentName}`);
         return agent.getRuntimeSettings();
     }
-    updateAgentRuntimeSettings(agentName, patch) {
+    /**
+     * Apply runtime settings.
+     *
+     * `opts.persist: false` makes the change EPHEMERAL: it takes effect live but
+     * is not written to the `framework/state` slot, so a restart reverts it. That
+     * is the mode for operator experiments ("change it, watch, revert") — the
+     * default persists, because a durable operational change should survive a
+     * bounce like every other override.
+     *
+     * Nothing here notifies the agent. Discovery is deliberately PULL: the agent
+     * can read current settings any time via the `agent_settings` tool's `get`
+     * action, which costs no context perturbation. Pushing a notice injects text
+     * into the very context being tuned — it invalidates the KV prefix and can
+     * itself trip a classifier — so callers opt into that explicitly rather than
+     * getting it by default.
+     *
+     * KNOWN LIMITATION of `persist: false`: the change still lands in the agent's
+     * in-memory override map, and `persistAgentRuntimeSettings` writes that whole
+     * map. So a LATER persisting call promotes any still-live ephemeral change to
+     * durable as a side effect. Ephemeral means "not written by THIS call", not
+     * "can never be written". Reset the ephemeral key before persisting something
+     * else if that matters. Making it airtight needs per-key ephemeral tracking
+     * inside Agent.
+     */
+    updateAgentRuntimeSettings(agentName, patch, opts) {
         const agent = this.agents.get(agentName);
         if (!agent)
             throw new Error(`Unknown agent: ${agentName}`);
         const result = agent.updateRuntimeSettings(patch);
-        this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+        if (opts?.persist !== false) {
+            this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+        }
         return result;
     }
-    resetAgentRuntimeSettings(agentName, keys) {
+    resetAgentRuntimeSettings(agentName, keys, opts) {
         const agent = this.agents.get(agentName);
         if (!agent)
             throw new Error(`Unknown agent: ${agentName}`);
         const result = agent.resetRuntimeSettings(keys);
-        this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+        if (opts?.persist !== false) {
+            this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+        }
         return result;
     }
     cancelAgentRuntimeSettingsTransition(agentName) {
@@ -1064,10 +1231,14 @@ export class AgentFramework {
             throw new Error(`Agent not found: ${agentName}`);
         }
         const tools = this.getToolsForAgent(agentName).filter((t) => agent.canUseTool(t.name));
+        // An explicit budget compiles against a HYPOTHETICAL window instead of the
+        // agent's live one. That also suppresses transition-settling in
+        // compileWithInjections (which only settles when no budget is passed), so
+        // previewing a smaller window cannot advance a converging descent.
         // Default: no dynamic injection gathering → fully transparent (no
         // inference, no Chronicle writes, no external RPC). Opt in explicitly.
         if (!opts?.injections) {
-            return agent.buildActivationRequest(tools, undefined);
+            return agent.buildActivationRequest(tools, undefined, opts?.budget);
         }
         // Full-fidelity path: mirrors startAgentStream's injection gathering.
         // NOT transparent — see the doc comment above.
@@ -1097,7 +1268,33 @@ export class AgentFramework {
                 console.error('beforeInference hook error (preview):', error);
             }
         }
-        return agent.buildActivationRequest(tools, injections);
+        return agent.buildActivationRequest(tools, injections, opts?.budget);
+    }
+    /**
+     * Non-committing preview of the FOLD PLAN at a hypothetical budget and/or
+     * context settings — the numbers behind an operator's "what happens if I set
+     * the budget to X" before they apply it.
+     *
+     * Unlike `previewActivation` (which renders a request), this returns the
+     * picker's plan: resulting tokens, whether it fits, how many summaries would
+     * have to be produced first, and the per-chunk fold levels. Commits nothing:
+     * no resolution persistence, no compression enqueue, no transition
+     * bookkeeping — see `AutobiographicalStrategy.previewContext`.
+     *
+     * Returns null when the agent's strategy has no fold plan (non-adaptive).
+     */
+    previewContextSettings(agentName, budgetTokens, overrides, opts) {
+        const agent = this.agents.get(agentName);
+        if (!agent)
+            throw new Error(`Unknown agent: ${agentName}`);
+        const cm = agent.getContextManager();
+        if (typeof cm.previewContext !== 'function')
+            return null;
+        // reserveForResponse mirrors the live compile so the previewed middle is
+        // comparable to what the agent actually gets. `opts.render` additionally
+        // returns the rendered entries — opt-in, since they are megabytes on a
+        // large store, and older context-manager builds ignore the argument.
+        return cm.previewContext({ maxTokens: budgetTokens, reserveForResponse: agent.maxTokens }, overrides, opts);
     }
     /**
      * Check if process logging is enabled.
@@ -2599,6 +2796,18 @@ export class AgentFramework {
         // Anthropic API.  If we let modules or MCPL handlers run first they may add
         // messages between tool_use and tool_result, causing a 400 error.
         if (event.type === 'tool-result') {
+            // Script-inner tool calls (client-side programmatic tool calling):
+            // resolve the waiter and stop. These calls belong to a RUNNING
+            // code_execution script, not to the agent's pending tool round — they
+            // must not touch agent state (and must resolve even for ephemeral
+            // agents that aren't in this.agents, or after the agent's own round
+            // has already settled).
+            const scriptWaiter = this.scriptToolWaiters.get(event.callId);
+            if (scriptWaiter) {
+                this.scriptToolWaiters.delete(event.callId);
+                scriptWaiter(event.result);
+                return;
+            }
             const agent = this.agents.get(event.agentName);
             if (agent) {
                 this.touchEphemeralRun(event.agentName, true);
@@ -2691,20 +2900,17 @@ export class AgentFramework {
                             }
                         }
                     }
-                    // A newly injected message begins a new conversational round inside
-                    // the same provider inference. Remember that boundary for
-                    // driveStream: an explicit send in the preceding round must not
-                    // silence the reply, and the newest channel-bearing injection is
-                    // now the reply locus. Map presence matters even without a channel
-                    // (CLI/module input): it still clears the prior send suppression.
-                    if (midTurnInjections.length > 0) {
-                        const injectedChannelId = midTurnInjections.reduce((latest, injection) => {
-                            const candidate = injection.metadata?.channelId;
-                            return typeof candidate === 'string' && candidate.length > 0
-                                ? candidate
-                                : latest;
-                        }, null);
-                        this.midTurnRoutingResets.set(agent.name, injectedChannelId);
+                    // A newly injected CONVERSATIONAL message begins a new
+                    // conversational round inside the same provider inference. Remember
+                    // that boundary for driveStream: an explicit send in the preceding
+                    // round must not silence the reply. Routing is deliberately NOT
+                    // affected — the turn locus is frozen at turn start, so ambient
+                    // chatter, reactions, and system markers injected mid-turn can no
+                    // longer hijack where the agent's prose lands. Non-conversational
+                    // injections (reactions, `system: true` markers) don't even clear
+                    // the send suppression: nothing new was said to the agent.
+                    if (midTurnInjections.some((inj) => isConversationalInjection(inj.metadata))) {
+                        this.midTurnInputSignals.add(agent.name);
                     }
                     // Check if any tool result requested endTurn
                     const shouldEndTurn = currentState.toolResults.some(tc => tc.result.endTurn);
@@ -2890,6 +3096,8 @@ export class AgentFramework {
         };
         if (event.threadId)
             metadata.threadId = event.threadId;
+        if (event.tags)
+            metadata.tags = event.tags;
         // Per-channel conversation routing: messages go to the channel's fork
         // agent (spawned from the template on first qualifying message), never
         // to the primary conversation.
@@ -2900,6 +3108,7 @@ export class AgentFramework {
         const id = this.addMessage('user', event.content, metadata);
         this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:channel-incoming' });
         if (event.triggerInference) {
+            const addressed = isAddressedMessage(event.tags, event.metadata);
             for (const agentName of this.agents.keys()) {
                 this.pendingRequests.push({
                     agentName,
@@ -2909,6 +3118,9 @@ export class AgentFramework {
                     // Route this turn's auto-published speech back to THIS channel, not
                     // the global most-recent-inbound locus (item-3 redux, trunk agents).
                     channelId: event.channelId,
+                    // Addressed messages outrank ambient chatter when a batched wake
+                    // picks the turn's frozen speech locus.
+                    addressed,
                 });
             }
         }
@@ -2990,6 +3202,7 @@ export class AgentFramework {
                 // A fork's home channel wins in routeSpeech regardless, but carry the
                 // triggering channel too so the trunk/active path stays consistent.
                 channelId: event.channelId,
+                addressed: isAddressedMessage(event.tags, event.metadata),
             });
         }
     }
@@ -3145,7 +3358,7 @@ export class AgentFramework {
     handleMcplPushEvent(event) {
         const triggerChannel = this.derivePushEventChannel(event.origin);
         if (triggerChannel && this.channelRegistry) {
-            this.channelRegistry.ensureChannelRegistered(event.serverId, triggerChannel.channelId, triggerChannel.label);
+            this.channelRegistry.ensureChannelRegistered(event.serverId, triggerChannel.channelId, triggerChannel.label, triggerChannel.metadata);
         }
         const metadata = {
             ...event.origin,
@@ -3153,7 +3366,17 @@ export class AgentFramework {
             featureSet: event.featureSet,
             eventId: event.eventId,
             triggered: event.triggerInference ?? false,
+            ...(event.tags ? { tags: event.tags } : {}),
         };
+        // `origin.channelId` is the server-internal raw id (a bare Discord
+        // snowflake) — unroutable as a locus and unresolvable by the agent. Store
+        // the composite MCPL id instead wherever we can derive it, so anything
+        // downstream that reads `metadata.channelId` (routing, provenance, the
+        // agent itself) sees the qualified form. The raw value stays available on
+        // servers that also send `rawChannelId`-style origin fields.
+        if (triggerChannel) {
+            metadata.channelId = triggerChannel.channelId;
+        }
         const content = [...event.content];
         const addressedWhileClosed = triggerChannel &&
             event.tags?.includes('chat:addressed') &&
@@ -3207,6 +3430,10 @@ export class AgentFramework {
                     source: event.serverId,
                     timestamp: Date.now(),
                     channelId: triggerChannel?.channelId,
+                    // DMs and addressed-while-closed messages arrive as push events;
+                    // they must outrank ambient chatter in a batched wake's locus
+                    // selection just like their channels/incoming counterparts.
+                    addressed: isAddressedMessage(event.tags, event.origin),
                 });
             }
         }
@@ -3230,16 +3457,35 @@ export class AgentFramework {
     derivePushEventChannel(origin) {
         if (!origin)
             return undefined;
-        const label = typeof origin.channelName === 'string' ? origin.channelName : undefined;
+        let label = typeof origin.channelName === 'string' && origin.channelName ? origin.channelName : undefined;
+        let metadata;
+        // A DM has no channelName — label it by the PERSON and carry their
+        // identity, so DM registrations are people-first (`DM: antra`, matchable
+        // by `>>@name` / `<@id>` mention tokens) instead of bare snowflakes.
+        const isDM = origin.isDM === true || origin.guildId === null;
+        if (isDM && typeof origin.authorName === 'string' && origin.authorName) {
+            label = label ?? `DM: ${origin.authorName}`;
+            metadata = {
+                channelType: 'dm',
+                recipientName: origin.authorName,
+                ...(typeof origin.authorId === 'string' && origin.authorId
+                    ? { recipientId: origin.authorId }
+                    : {}),
+            };
+        }
         const explicit = origin.mcplChannelId;
         if (typeof explicit === 'string' && explicit) {
-            return { channelId: explicit, label };
+            return { channelId: explicit, ...(label ? { label } : {}), ...(metadata ? { metadata } : {}) };
         }
         // Discord fallback: reconstruct the composite from origin parts. `guildId`
         // is null for a DM (→ 'dm'); a real guild id for a non-open guild channel.
         if (origin.source === 'discord' && typeof origin.channelId === 'string' && origin.channelId) {
             const guild = typeof origin.guildId === 'string' && origin.guildId ? origin.guildId : 'dm';
-            return { channelId: `discord:${guild}:${origin.channelId}`, label };
+            return {
+                channelId: `discord:${guild}:${origin.channelId}`,
+                ...(label ? { label } : {}),
+                ...(metadata ? { metadata } : {}),
+            };
         }
         return undefined;
     }
@@ -3312,14 +3558,287 @@ export class AgentFramework {
             const trigger = requests[0];
             // Route this turn's auto-published speech to the channel that triggered
             // it (item-3 redux). A batched wake may carry several triggering channels
-            // (messages arrived in >1 channel while the agent was busy/idle) — reply
-            // in the MOST-RECENT one: it matches the legacy last-inbound semantics and
-            // is the message the agent is most likely answering. The common case is
-            // 1 message → 1 channel (unambiguous). Non-channel wakes carry no
-            // channelId, leaving the field undefined → global fallback. `reduce`
-            // keeps the last defined channelId across the (FIFO-ordered) batch.
-            const triggerChannel = requests.reduce((acc, r) => r.channelId ?? acc, undefined);
-            await this.startAgentStream(agent, { ...trigger, channelId: triggerChannel });
+            // (messages arrived in >1 channel while the agent was busy/idle):
+            //   1. the most recent ADDRESSED channel wins (mention / reply / DM —
+            //      someone explicitly spoke TO the agent);
+            //   2. else the most recent channel-bearing request (ambient message in
+            //      an open channel — legacy last-inbound semantics).
+            // Ambient chatter must not outrank an addressed message just by being
+            // newest (2026-07-21 Cairn lounge misroute, turn-start variant).
+            // Non-channel wakes (heartbeats, module events, reactions — which never
+            // carry channelId) leave both undefined → global fallback.
+            let ambientChannel;
+            let addressedChannel;
+            for (const r of requests) {
+                if (!r.channelId)
+                    continue;
+                ambientChannel = r.channelId;
+                if (r.addressed)
+                    addressedChannel = r.channelId;
+            }
+            const triggerChannel = addressedChannel ?? ambientChannel;
+            const triggerAddressed = addressedChannel !== undefined;
+            await this.startAgentStream(agent, {
+                ...trigger,
+                channelId: triggerChannel,
+                addressed: triggerAddressed,
+            });
+        }
+    }
+    /**
+     * Announce-on-change locus notice (turn-frozen routing). Appends a durable
+     * `[routing]` window message when the turn's effective outbound locus
+     * differs from the last one announced — the agent must never have to guess
+     * where its plain prose lands. Durable append (never retracted) keeps the
+     * KV prefix stable; change-only keeps it out of steady-state turns. The
+     * first resolution after boot announces only a non-null locus ("prose has
+     * no destination" is the unremarkable boot default). Never triggers
+     * inference; never locus-eligible itself (system + no channel metadata).
+     */
+    announceLocusIfChanged(agentName, locus) {
+        const hasBaseline = this.lastAnnouncedLocus.has(agentName);
+        const prev = this.lastAnnouncedLocus.get(agentName) ?? null;
+        if (hasBaseline ? prev === locus : locus === null) {
+            if (!hasBaseline)
+                this.lastAnnouncedLocus.set(agentName, locus);
+            return;
+        }
+        this.lastAnnouncedLocus.set(agentName, locus);
+        const agent = this.agents.get(agentName);
+        if (!agent)
+            return;
+        let text;
+        if (locus === null) {
+            text =
+                '[routing] Your plain speech currently has no channel — it stays in ' +
+                    'your archive. Use an explicit send tool to reach a channel.';
+        }
+        else {
+            const label = this.channelRegistry?.getDescriptor(locus)?.label;
+            const shown = label && label !== locus
+                ? `${label.startsWith('#') ? label : `#${label}`} (${locus})`
+                : locus;
+            text =
+                `[routing] Your plain speech now lands in ${shown}. ` +
+                    'Other channels need an explicit send tool.';
+        }
+        try {
+            const id = agent.getContextManager().addMessage('user', [{ type: 'text', text }], { system: true, kind: 'routing-notice' });
+            this.emitTrace({ type: 'message:added', messageId: id, source: 'routing-notice' });
+            console.error(`[routing] ${agentName}: locus ${prev ?? '(none)'} -> ${locus ?? '(none)'} (announced in window)`);
+        }
+        catch (err) {
+            console.error('announceLocusIfChanged: failed to record routing notice:', err);
+        }
+    }
+    /**
+     * Durable window notice for a channel the agent did not ask to open —
+     * subscription-policy admission, or an open forced by the agent's own
+     * delivery into a closed channel. The agent must always learn that new
+     * traffic will start flowing, and that `channel_close` opts out (their
+     * decision outranks policy). System message: never triggers inference,
+     * never conversational, never locus-eligible.
+     */
+    recordChannelAutoOpenNotice(agentName, channels, cause) {
+        if (channels.length === 0)
+            return;
+        const shown = channels
+            .map((c) => (c.label && c.label !== c.channelId ? `${c.label} (${c.channelId})` : c.channelId))
+            .join(', ');
+        const plural = channels.length > 1;
+        const causeText = cause === 'subscription-policy'
+            ? 'your subscription policy just admitted ' + (plural ? 'them' : 'it')
+            : 'your own message into the closed channel engaged it';
+        const text = `[channels] Now open: ${shown} — ${causeText}. Ongoing traffic from ` +
+            (plural ? 'these channels' : 'this channel') +
+            ` will reach you. If you don't want ${plural ? 'one of them' : 'it'}, use channel_close — ` +
+            'your choice sticks; neither policy nor a later send will silently reopen it.';
+        try {
+            // Through framework.addMessage for mid-turn safety (deferral +
+            // hear-while-acting injection) — a delivery-forced open happens inside
+            // a live turn, and a direct context-manager append there would store
+            // the notice out of order. Targets the primary agent; connectome-host
+            // runs trunk-only, so this is the delivering agent in practice.
+            this.addMessage('user', [{ type: 'text', text }], { system: true, kind: 'channel-notice' });
+            console.error(`[channel] auto-open notice (${cause}) -> ${agentName ?? 'primary'}: ${shown}`);
+        }
+        catch (err) {
+            console.error('recordChannelAutoOpenNotice failed:', err);
+        }
+    }
+    /**
+     * Explicit-prose-routing delivery gateway (docs/explicit-prose-routing.md).
+     * Every prose segment of an `explicit`-mode agent flows through here:
+     * parse the `>>` prefix, resolve the target, deliver — or bounce to the
+     * clipboard with a resend notice. Misdelivery is structurally impossible:
+     * nothing is ever sent to a destination the model did not name (directly
+     * or via the turn's sticky target).
+     */
+    async deliverProse(agent, rawText) {
+        // Multi-envelope: a single prose block may address SEVERAL destinations —
+        // every line beginning with `>>` opens a new envelope, routed
+        // independently (first live use: Tilde 2026-07-24, one block carrying a
+        // letter to #tilde-mythos AND a `>>#tilde` aside; the single-envelope
+        // parser delivered the aside literally into the first destination —
+        // exactly the leak class this mode exists to kill). Text before the
+        // first `>>` is its own unprefixed envelope (sticky/bounce as usual).
+        const lines = rawText.split('\n');
+        const envelopes = [];
+        let current = [];
+        for (const line of lines) {
+            // Only a REAL prefix line opens an envelope: `>>` immediately followed
+            // by a target token. A quoted `>> arrow` (space after) stays body text.
+            if (/^>>\S/.test(line.trimStart()) && current.length > 0) {
+                envelopes.push(current.join('\n'));
+                current = [];
+            }
+            current.push(line);
+        }
+        if (current.length > 0)
+            envelopes.push(current.join('\n'));
+        for (const envelope of envelopes) {
+            if (!envelope.trim())
+                continue;
+            await this.deliverProseEnvelope(agent, envelope.replace(/^\s+(?=>>)/, ''));
+        }
+    }
+    async deliverProseEnvelope(agent, rawText) {
+        const name = agent.name;
+        const parsed = parseProsePrefix(rawText);
+        if (parsed.continueTurn)
+            this.proseContinuations.add(name);
+        if (parsed.kind === 'private') {
+            // The text already lives in the assistant message (window/chronicle);
+            // "delivery" is deliberately a no-op. Consumes the retained text if the
+            // segment embedded it.
+            if (parsed.body.includes('{{unsent}}'))
+                this.proseClipboards.delete(name);
+            console.error(`[prose] ${name}: >>skip_reply — ${parsed.body.length} chars kept in context (not sent)`);
+            return;
+        }
+        let targetChannel;
+        let body;
+        if (parsed.kind === 'target') {
+            const res = this.channelRegistry.resolveProseTarget(parsed.target);
+            if ('error' in res) {
+                this.bounceProse(agent, parsed.body, res.error, res.candidates);
+                return;
+            }
+            targetChannel = res.channelId;
+            // Sticky within the turn: later unprefixed segments follow this target.
+            this.proseTargetPins.set(name, targetChannel);
+            body = parsed.body;
+        }
+        else {
+            const sticky = this.proseTargetPins.get(name);
+            if (!sticky) {
+                this.bounceProse(agent, rawText, 'no destination prefix and no destination set yet this turn');
+                return;
+            }
+            targetChannel = sticky;
+            body = rawText;
+        }
+        const usedClipboard = body.includes('{{unsent}}');
+        if (usedClipboard) {
+            body = body.replaceAll('{{unsent}}', this.proseClipboards.get(name) ?? '');
+        }
+        if (!body.trim()) {
+            console.error(`[prose] ${name}: empty body after prefix/substitution — nothing to send`);
+            return;
+        }
+        try {
+            const result = await this.channelRegistry.routeSpeech(name, body, targetChannel);
+            if (result?.delivered) {
+                this.proseBounceStreaks.delete(name);
+                if (usedClipboard)
+                    this.proseClipboards.delete(name);
+            }
+        }
+        catch (err) {
+            console.error(`[prose] ${name}: delivery to ${targetChannel} failed:`, err);
+        }
+    }
+    /** Cap on consecutive bounce-triggered wakes (notices still append after). */
+    static PROSE_BOUNCE_WAKE_CAP = 2;
+    bounceProse(agent, text, reason, candidates) {
+        const name = agent.name;
+        this.proseClipboards.set(name, text);
+        const streak = (this.proseBounceStreaks.get(name) ?? 0) + 1;
+        this.proseBounceStreaks.set(name, streak);
+        const cand = candidates?.length ? ` Known channels it could mean: ${candidates.join(', ')}.` : '';
+        const notice = `[prose-routing] Your text (${text.length} chars) was not delivered — ${reason}.${cand} ` +
+            'The text is retained; nothing is lost. To deliver it unchanged, reply with a ' +
+            'destination plus the token {{unsent}}, e.g. ">>#channel {{unsent}}" or ">>@person {{unsent}}". ' +
+            '">>skip_reply {{unsent}}" keeps it in context only. The prose_help tool shows the full syntax.';
+        try {
+            // Through framework.addMessage, NOT the context manager directly: while
+            // the turn is still streaming this defers the notice to the next tool
+            // boundary, where it is BOTH stored in order and injected into the live
+            // stream (hear-while-acting) — the model sees the error and can correct
+            // the prefix within the same turn. A direct append here would land the
+            // notice before the turn's assistant blocks (cache bust, invisible
+            // until the next compile).
+            const id = this.addMessage('user', [{ type: 'text', text: notice }], { system: true, kind: 'prose-bounce' });
+            if (id)
+                this.emitTrace({ type: 'message:added', messageId: id, source: 'prose-bounce' });
+            else
+                this.emitTrace({ type: 'message:added', messageId: 'deferred', source: 'prose-bounce' });
+        }
+        catch (err) {
+            console.error('bounceProse: failed to record bounce notice:', err);
+        }
+        const capped = streak > AgentFramework.PROSE_BOUNCE_WAKE_CAP;
+        console.error(`[prose] ${name}: BOUNCED ${text.length} chars — ${reason}` +
+            (capped ? ' (bounce-wake cap reached; notice appended without wake)' : ''));
+        if (!capped) {
+            // Wake so the resend can happen immediately — an unsent DM reply must
+            // not sit invisible until the next unrelated event.
+            this.pendingRequests.push({
+                agentName: name,
+                reason: 'prose-bounce',
+                source: 'framework',
+                timestamp: Date.now(),
+            });
+        }
+    }
+    /**
+     * One-time mode primer (docs/explicit-prose-routing.md): when an agent's
+     * configured proseRouting differs from the last mode we primed them for,
+     * append the teaching notice and persist the new mode. A brand-new agent
+     * in default locus mode is recorded silently — no primer for the status quo.
+     */
+    maybePrimeProseMode(agent) {
+        const mode = agent.proseRouting;
+        try {
+            const data = this.store.getStateJson(FRAMEWORK_STATE_ID);
+            const state = (data && typeof data === 'object' ? data : {});
+            const primed = { ...(state.proseRoutingPrimed ?? {}) };
+            const stored = primed[agent.name];
+            if (stored === mode)
+                return;
+            // Absence means "always default (locus)": a locus-mode agent that was
+            // never explicit needs no entry and no primer — and skipping the write
+            // keeps framework/state from growing a record per agent (scaling gate).
+            if (mode === 'locus' && stored === undefined)
+                return;
+            if (mode === 'locus')
+                delete primed[agent.name];
+            else
+                primed[agent.name] = mode;
+            state.proseRoutingPrimed = primed;
+            this.store.setStateJson(FRAMEWORK_STATE_ID, state);
+        }
+        catch (err) {
+            console.error('maybePrimeProseMode: state read/write failed:', err);
+            return;
+        }
+        try {
+            const id = agent.getContextManager().addMessage('user', [{ type: 'text', text: proseModePrimer(mode) }], { system: true, kind: 'prose-routing-primer' });
+            this.emitTrace({ type: 'message:added', messageId: id, source: 'prose-routing-primer' });
+            console.error(`[prose] ${agent.name}: mode primer appended (${mode})`);
+        }
+        catch (err) {
+            console.error('maybePrimeProseMode: failed to append primer:', err);
         }
     }
     async startAgentStream(agent, trigger, attempt = 0) {
@@ -3334,20 +3853,74 @@ export class AgentFramework {
         // instead falls back to the global default. A given agent runs one turn at a
         // time, so a set here is only read during THIS turn's routeSpeech /
         // buildChannelContext; retries re-run with the same trigger, re-setting it.
-        if (trigger?.channelId) {
-            this.activeTriggerChannels.set(agent.name, trigger.channelId);
+        // A context-budget restart continues the SAME logical turn in a fresh
+        // stream — its trigger carries no channelId, and deleting the trigger
+        // channel here mid-logical-turn is exactly the hole that sent Sol's DM
+        // reply to a stale guild channel (2026-07-22): any live locus resolution
+        // after the restart fell through to the hours-old defaultPublishChannel.
+        // Keep the turn's trigger channel across restarts; only real new turns
+        // reset it.
+        if (trigger?.reason !== 'context_budget_restart') {
+            if (trigger?.channelId) {
+                this.activeTriggerChannels.set(agent.name, trigger.channelId);
+            }
+            else {
+                this.activeTriggerChannels.delete(agent.name);
+            }
         }
-        else {
-            this.activeTriggerChannels.delete(agent.name);
+        // FREEZE this turn's outbound locus now (turn-frozen routing). Resolved
+        // once — home channel for forks, else the triggering channel, else the
+        // global default — and never moved for the rest of the turn: mid-turn
+        // injections must not redirect the agent's plain prose (ambient chatter /
+        // reactions hijacked it before, 2026-07-21). A context-budget restart
+        // continues the same logical turn, so it keeps the existing pin. The
+        // eager snapshot also protects heartbeat turns from a moving
+        // defaultPublishChannel mid-turn. If the effective locus differs from the
+        // last one announced, drop a durable `[routing]` notice into the window
+        // BEFORE this turn compiles, so the agent always knows where its voice
+        // goes (announce-on-change only — no per-turn chatter, append-only for
+        // KV stability).
+        if (trigger?.reason !== 'context_budget_restart') {
+            if (attempt === 0)
+                this.maybePrimeProseMode(agent);
+            if (agent.proseRouting === 'explicit') {
+                // Explicit prose routing: there is no locus. The model names every
+                // destination in-band (`>>` prefixes); the only turn state is the
+                // sticky target, reset for each fresh turn. No freeze, no announce.
+                this.proseTargetPins.delete(agent.name);
+                this.proseContinuations.delete(agent.name);
+                this.midTurnInputSignals.delete(agent.name);
+                this.turnLocusPins.delete(agent.name);
+            }
+            else {
+                const locus = this.channelRegistry?.resolveLocus(agent.name) ?? null;
+                if (locus !== null)
+                    this.turnLocusPins.set(agent.name, locus);
+                else
+                    this.turnLocusPins.delete(agent.name);
+                this.midTurnInputSignals.delete(agent.name);
+                if (attempt === 0)
+                    this.announceLocusIfChanged(agent.name, locus);
+            }
         }
         this.touchEphemeralRun(agent.name, true);
-        this.emitTrace({ type: 'inference:started', agentName: agent.name });
+        this.emitTrace({
+            type: 'inference:started',
+            agentName: agent.name,
+            // The turn-frozen locus was pinned just above (kept across a
+            // context-budget restart, which skips the re-pin but re-emits this).
+            channelId: this.turnLocusPins.get(agent.name),
+        });
         this.eventGate?.onInferenceStarted(agent.name);
         this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), startedAt: Date.now() });
         try {
             const requestSnapshot = this.captureInferenceToolSnapshot(agent);
             const allTools = this.getToolsForAgent(agent.name, requestSnapshot);
             const tools = allTools.filter((t) => agent.canUseTool(t.name));
+            // Explicit-mode agents get the on-demand routing reference (teach-by-
+            // bounce: the grammar is never injected, only served when asked).
+            if (agent.proseRouting === 'explicit')
+                tools.push(PROSE_HELP_TOOL);
             // Gather context from modules (pull-based) and MCPL hooks (push-based)
             // Both produce ContextInjection[] that get merged before inference.
             let injections;
@@ -3428,25 +4001,14 @@ export class AgentFramework {
         const myStreamId = agent.streamId;
         let hadToolCalls = false;
         // ---- Present-while-acting turn state ---------------------------------
-        // Output locus for the current CONVERSATIONAL ROUND: resolved lazily and
-        // kept stable across tool-only rounds. A channel message injected at a
-        // tool boundary replaces the pin before the next model round, because a
-        // single provider inference can now contain several conversations. The
-        // pin lives in `turnLocusPins` so it survives a context-budget restart. A
-        // null resolution is not pinned.
-        if (trigger?.reason !== 'context_budget_restart') {
-            this.turnLocusPins.delete(agent.name);
-            this.midTurnRoutingResets.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;
-        };
+        // Output locus for the WHOLE logical turn: frozen in startAgentStream
+        // (home → addressed trigger → global default) before this stream began,
+        // and never moved until the next turn. Mid-turn injections do not touch
+        // it — an ambient message or a reaction arriving at a tool boundary must
+        // not redirect the agent's task narration (2026-07-21 Cairn misroute).
+        // The pin lives in `turnLocusPins` so a context-budget restart (same
+        // logical turn, fresh driveStream) keeps it.
+        const resolveTurnLocus = () => this.turnLocusPins.get(agent.name) ?? null;
         // 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
@@ -3475,32 +4037,52 @@ export class AgentFramework {
         // 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.
-        let typingChannel = this.channelRegistry
-            ? trigger?.channelId ?? this.channelRegistry.getDefaultPublishChannel()
-            : null;
+        // Typing indicator: show "<agent> is typing…" 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. Never moves mid-turn.
+        //   - locus mode: the frozen routing pin (where bare prose will land).
+        //   - explicit mode: there is no locus — indicate on the TRIGGER channel
+        //     (where the wake came from). Typing is presence, not delivery, so
+        //     this doesn't violate never-guess: it says "attending to what you
+        //     sent here", which is true regardless of where the reply goes.
+        //     Heartbeat/no-trigger explicit turns show no indicator.
+        const typingChannel = agent.proseRouting === 'explicit'
+            ? trigger?.channelId ?? null
+            : resolveTurnLocus();
         if (typingChannel)
             this.channelRegistry.startTyping(typingChannel);
+        // MCPL Spec 14.3 outgoing streaming: route text deltas to their
+        // destination server AS THEY GENERATE (voice synthesis, live message
+        // rendering). Pure observer surface — suppression is fail-closed (nothing
+        // streams that delivery would refuse), emission is capability-gated in
+        // the registry (`channels.streaming`), and delivery via deliverProse
+        // remains the sole authoritative send.
+        const outgoingInferenceId = `inf_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+        let outgoingIndex = 0;
+        const proseStream = this.channelRegistry
+            ? new ProseStreamRouter({
+                mode: agent.proseRouting === 'explicit' ? 'explicit' : 'locus',
+                initialTarget: typingChannel,
+                resolve: (spec) => {
+                    const r = this.channelRegistry.resolveProseTarget(spec);
+                    return 'channelId' in r ? r.channelId : null;
+                },
+            })
+            : null;
+        const emitOutgoing = (deltas) => {
+            for (const rd of deltas) {
+                this.channelRegistry.sendOutgoingChunk(rd.channelId, agent.name, outgoingInferenceId, outgoingIndex++, rd.delta);
+            }
+        };
         const adoptInjectedRound = () => {
-            if (!this.midTurnRoutingResets.has(agent.name))
+            if (!this.midTurnInputSignals.has(agent.name))
                 return;
-            const nextLocus = this.midTurnRoutingResets.get(agent.name) ?? null;
-            this.midTurnRoutingResets.delete(agent.name);
-            // A new human/agent message, not merely a tool result, means any earlier
-            // explicit delivery has completed its conversational job.
+            this.midTurnInputSignals.delete(agent.name);
+            // A new conversational message, not merely a tool result, means any
+            // earlier explicit delivery has completed its conversational job.
+            // Routing is NOT touched: the turn locus stays frozen.
             turnSilenced = false;
-            if (nextLocus) {
-                this.turnLocusPins.set(agent.name, nextLocus);
-                if (typingChannel !== nextLocus) {
-                    if (typingChannel)
-                        this.channelRegistry?.stopTyping(typingChannel);
-                    typingChannel = nextLocus;
-                    this.channelRegistry?.startTyping(nextLocus);
-                }
-            }
         };
         try {
             for await (const event of stream) {
@@ -3513,7 +4095,14 @@ export class AgentFramework {
                             content: event.content,
                             blockType: event.meta.type,
                             blockIndex: event.meta.blockIndex,
+                            // Turn-frozen locus (same value as the typing indicator above):
+                            // lets trace consumers tag every chunk with the channel this
+                            // turn's prose is bound for, without re-deriving routing.
+                            channelId: typingChannel ?? undefined,
                         });
+                        if (proseStream && event.meta.type === 'text') {
+                            emitOutgoing(proseStream.feed(event.content));
+                        }
                         break;
                     case 'block': {
                         const { event: phase, index, block } = event.event;
@@ -3523,6 +4112,7 @@ export class AgentFramework {
                             phase,
                             blockType: block.type,
                             blockIndex: index,
+                            channelId: typingChannel ?? undefined,
                         });
                         break;
                     }
@@ -3547,13 +4137,30 @@ export class AgentFramework {
                             assistantBlocks = roundContent.filter((b) => b.type !== 'tool_result');
                         }
                         else {
-                            // Fallback (older membrane / XML tool mode): preamble + calls
+                            // Fallback (older membrane / XML tool mode): preamble + calls.
+                            // XML mode: persist the verbatim generation on each tool_use
+                            // (membrane#36 round-trip fidelity). context.rawText is the
+                            // parser's fullMatch — the exact <function_calls> block the
+                            // model wrote (plus the harness-appended close tag), shared by
+                            // every call in the round; the anthropic-xml formatter replays
+                            // it byte-identically instead of reconstructing. Guarded by
+                            // shape so a native-path fallback can never attach non-XML.
+                            const rawText = event.context.rawText;
+                            const rawXml = rawText && /^<(antml:)?function_calls>/.test(rawText)
+                                ? rawText
+                                : undefined;
                             assistantBlocks = [];
                             if (event.context.preamble) {
                                 assistantBlocks.push({ type: 'text', text: event.context.preamble });
                             }
                             for (const c of event.calls) {
-                                assistantBlocks.push({ type: 'tool_use', id: c.id, name: c.name, input: c.input });
+                                assistantBlocks.push({
+                                    type: 'tool_use',
+                                    id: c.id,
+                                    name: c.name,
+                                    input: c.input,
+                                    ...(rawXml ? { rawXml } : {}),
+                                });
                             }
                         }
                         this.pendingAssistantBlocks.set(agent.name, assistantBlocks);
@@ -3588,7 +4195,20 @@ export class AgentFramework {
                                 liveProseRouting = true;
                                 const roundSegments = splitProseSegments(assistantBlocks);
                                 if (roundSegments.length > 0) {
-                                    if (turnSilenced) {
+                                    if (agent.proseRouting === 'explicit') {
+                                        // Explicit mode: every segment through the prose gateway.
+                                        // Silencing does not apply — unprefixed prose bounces and
+                                        // prefixed prose is deliberate; think-privacy still holds.
+                                        if (!hasSameRoundPrivateThink) {
+                                            console.error(`[prose] ${agent.name}: mid-turn round [${roundToolNames.join(', ')}] -> ${roundSegments.length} segment(s) via prose gateway`);
+                                            for (const seg of roundSegments) {
+                                                turnSpeechChain = turnSpeechChain
+                                                    .then(() => this.deliverProse(agent, seg))
+                                                    .catch((err) => console.error('mid-turn prose delivery failed:', err));
+                                            }
+                                        }
+                                    }
+                                    else if (turnSilenced) {
                                         console.error(`[routing] ${agent.name}: mid-turn round [${roundToolNames.join(', ')}] -> prose NOT routed (turn silenced)`);
                                     }
                                     else if (hasSameRoundPrivateThink) {
@@ -3867,11 +4487,30 @@ export class AgentFramework {
                                 .join('\n')
                                 .trim();
                             if (speechText) {
-                                try {
-                                    await this.channelRegistry.routeSpeech(agent.name, speechText);
+                                if (agent.proseRouting === 'explicit') {
+                                    console.error(`[prose] ${agent.name}: text-only turn -> prose gateway`);
+                                    try {
+                                        await this.deliverProse(agent, speechText);
+                                    }
+                                    catch (err) {
+                                        console.error('text-only prose delivery failed:', err);
+                                    }
                                 }
-                                catch (err) {
-                                    console.error('speech routing failed:', err);
+                                else {
+                                    // Route to the TURN-FROZEN locus, like every other speech
+                                    // path. This dispatch runs AFTER the agent is idle, so a live
+                                    // resolution here can read the NEXT turn's trigger state (or
+                                    // a post-restart cleared one) and land the reply in a stale
+                                    // channel — the 2026-07-22 Sol DM-to-guild misroute. The
+                                    // frozen pin is immune to both races.
+                                    const locus = resolveTurnLocus();
+                                    console.error(`[routing] ${agent.name}: text-only turn -> routing speech -> ${locus ?? '(none)'}`);
+                                    try {
+                                        await this.channelRegistry.routeSpeech(agent.name, speechText, locus);
+                                    }
+                                    catch (err) {
+                                        console.error('speech routing failed:', err);
+                                    }
                                 }
                             }
                         }
@@ -3902,7 +4541,20 @@ export class AgentFramework {
                             // 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) {
+                            if (agent.proseRouting === 'explicit') {
+                                if (segments.length > 0) {
+                                    console.error(`[prose] ${agent.name}: tool-call turn [${toolNames.join(', ')}] -> ${segments.length} trailing segment(s) via prose gateway`);
+                                    for (const seg of segments) {
+                                        try {
+                                            await this.deliverProse(agent, seg);
+                                        }
+                                        catch (err) {
+                                            console.error('trailing prose delivery failed:', err);
+                                        }
+                                    }
+                                }
+                            }
+                            else if (silenced || segments.length === 0) {
                                 console.error(`[routing] ${agent.name}: tool-call turn [${toolNames.join(', ') || 'none'}] -> trailing prose NOT routed ` +
                                     `(${silenced ? 'silencing tool / explicit send' : 'no trailing prose'})`);
                             }
@@ -3930,6 +4582,20 @@ export class AgentFramework {
                         // NOTE: agent.reset() + onInferenceEnded() already ran above,
                         // BEFORE dispatchSpeech. Locus routing is speech dispatch and
                         // doesn't depend on the status field, so it correctly runs after.
+                        // Explicit-prose `!` continuation: a prose segment this turn asked
+                        // to keep going (`>>#x !` / `>>private !`) — start another turn
+                        // now instead of pausing until the next external event. This gives
+                        // prose the same continuation ability tool rounds have (wanted for
+                        // robotics-style loops where an end-of-turn pause is harmful).
+                        if (this.proseContinuations.delete(agent.name)) {
+                            console.error(`[prose] ${agent.name}: '!' continuation — requesting immediate next turn`);
+                            this.pendingRequests.push({
+                                agentName: agent.name,
+                                reason: 'prose-continuation',
+                                source: 'framework',
+                                timestamp: Date.now(),
+                            });
+                        }
                         break;
                     }
                     case 'error': {
@@ -3953,6 +4619,7 @@ export class AgentFramework {
                         // Only reset + retry if this is still the active stream
                         if (agent.streamId !== myStreamId)
                             break;
+                        this.abortAgentScript(agent.name, 'stream error');
                         agent.reset();
                         const action = this.errorPolicy.onInferenceError(err, agent.name, attempt);
                         if (action.retry) {
@@ -3999,6 +4666,7 @@ export class AgentFramework {
                         // may have already started a new stream, bumping streamId)
                         if (agent.streamId === myStreamId) {
                             const durationMs = Date.now() - startTime;
+                            this.abortAgentScript(agent.name, `stream aborted (${reason})`);
                             agent.reset();
                             this.settleAgent(agent.name, {
                                 stopReason: 'exhausted',
@@ -4097,6 +4765,7 @@ export class AgentFramework {
                 request: compiledRequest ?? { note: 'streaming request threw' },
                 durationMs,
             });
+            this.abortAgentScript(agent.name, 'stream threw');
             agent.reset();
             this.eventGate?.onInferenceEnded(agent.name);
         }
@@ -4113,6 +4782,15 @@ export class AgentFramework {
             // Stop the typing indicator on every exit path (complete, error,
             // exhausted, abort) so it never sticks after the turn ends.
             this.channelRegistry?.stopTyping();
+            // Spec 14.3: flush any held line-start text, then close each streamed
+            // channel with its final moderated content — the consumer's signal to
+            // finalize (end the TTS utterance, settle the rendered message).
+            if (proseStream) {
+                emitOutgoing(proseStream.finish());
+                for (const [channelId, text] of proseStream.byChannel()) {
+                    this.channelRegistry.sendOutgoingComplete(channelId, agent.name, outgoingInferenceId, text);
+                }
+            }
             this.frameworkCancelledStreams.delete(`${agent.name}:${myStreamId}`);
             this.activeStreams.delete(agent.name);
             this.pendingAssistantBlocks.delete(agent.name);
@@ -4136,6 +4814,12 @@ export class AgentFramework {
      * Used by SubagentModule to dispatch tool calls for ephemeral agents.
      */
     async executeToolCall(call) {
+        // Client-side programmatic tool calling for promise-based callers
+        // (SubagentModule ephemerals). Keyed by callerAgentName so each ephemeral
+        // gets its own interpreter state.
+        if (call.name === CODE_EXECUTION_TOOL_NAME && this.codeExecutionConfig) {
+            return this.runCodeExecution(call.callerAgentName ?? '__ephemeral__', call);
+        }
         // MCPL tools are dispatched via the MCPL subsystem
         if (this.mcplServerRegistry) {
             // Check if this is an MCPL-prefixed tool
@@ -4183,6 +4867,180 @@ export class AgentFramework {
             };
         }
     }
+    // ---------------------------------------------------------------------------
+    // Client-side programmatic tool calling (code_execution)
+    // ---------------------------------------------------------------------------
+    /** Event-pushing wrapper for the model-driven dispatch path. */
+    dispatchCodeExecutionToolCall(agentName, call) {
+        this.emitTrace({
+            type: 'tool:started',
+            module: 'code_execution',
+            tool: call.name,
+            callId: call.id,
+            input: call.input,
+        });
+        const startTime = Date.now();
+        this.runCodeExecution(agentName, call)
+            .catch((error) => {
+            // runCodeExecution is designed not to reject; this is the last-resort
+            // guard so a bug here can never strand the agent in waiting_for_tools.
+            const err = error instanceof Error ? error : new Error(String(error));
+            return { success: false, error: `code_execution failed: ${err.message}`, isError: true };
+        })
+            .then((result) => {
+            if (result.isError) {
+                this.emitTrace({
+                    type: 'tool:failed',
+                    module: 'code_execution',
+                    tool: call.name,
+                    callId: call.id,
+                    error: result.error ?? 'unknown error',
+                });
+            }
+            else {
+                this.emitTrace({
+                    type: 'tool:completed',
+                    module: 'code_execution',
+                    tool: call.name,
+                    callId: call.id,
+                    durationMs: Date.now() - startTime,
+                });
+            }
+            this.pushEvent({
+                type: 'tool-result',
+                callId: call.id,
+                agentName,
+                moduleName: 'code_execution',
+                result,
+            });
+        });
+    }
+    /**
+     * Run one code_execution script for an agent. Never rejects.
+     *
+     * The script runs in the agent's persistent python interpreter with every
+     * tool on the agent's CURRENT surface injected (minus code_execution
+     * itself). Inner tool calls are dispatched through dispatchToolCall — the
+     * exact model path, including MCPL state/checkpoint handling, channel
+     * routing, and traces — and resolved via scriptToolWaiters, so their
+     * results reach the running script and never the model context.
+     */
+    async runCodeExecution(agentName, call) {
+        const input = (call.input ?? {});
+        if (typeof input.code !== 'string' || input.code.trim() === '') {
+            return {
+                success: false,
+                error: 'code_execution requires a non-empty `code` string',
+                isError: true,
+            };
+        }
+        const agent = this.agents.get(agentName);
+        const surface = agent
+            ? this.getToolsForAgent(agentName).filter((t) => agent.canUseTool(t.name))
+            : this.getAllTools(); // ephemeral agents: full surface, matching executeToolCall
+        const injected = buildInjectedTools(surface.map((t) => t.name).filter((name) => name !== CODE_EXECUTION_TOOL_NAME));
+        const runner = this.getOrCreateScriptRunner(agentName);
+        this.scriptDeferredEndTurn.delete(agentName);
+        const exec = await runner.exec(input.code, injected);
+        const endTurn = this.scriptDeferredEndTurn.delete(agentName);
+        return {
+            success: true,
+            data: { stdout: exec.stdout, stderr: exec.stderr, return_code: exec.returnCode },
+            isError: false,
+            ...(endTurn ? { endTurn: true } : {}),
+        };
+    }
+    getOrCreateScriptRunner(agentName) {
+        let runner = this.codeExecutionRunners.get(agentName);
+        if (!runner) {
+            const cfg = this.codeExecutionConfig;
+            runner = new PyRunner({
+                pythonPath: cfg?.pythonPath,
+                toolCallTimeoutMs: cfg?.toolCallTimeoutMs,
+                scriptTimeoutMs: cfg?.scriptTimeoutMs,
+                idleReclaimMs: cfg?.idleReclaimMs,
+                label: agentName,
+                onToolCall: (toolName, args) => this.handleScriptToolCall(agentName, toolName, args),
+            });
+            this.codeExecutionRunners.set(agentName, runner);
+        }
+        return runner;
+    }
+    /**
+     * Resolve one script-inner tool call to the string the script's tool
+     * function returns. Never rejects — errors become "Error: ..." strings,
+     * matching the managed PTC runtime ("Claude's code receives this error").
+     *
+     * Results are serialized with the HISTORY serializer (images become
+     * placeholders): programmatic tool results are text-only by contract, and
+     * a script variable holding megabytes of base64 helps nobody.
+     */
+    async handleScriptToolCall(agentName, toolName, args) {
+        if (toolName === CODE_EXECUTION_TOOL_NAME) {
+            return 'Error: code_execution cannot be called from within a script';
+        }
+        const result = await this.dispatchScriptToolCall(agentName, toolName, args);
+        if (result.endTurn) {
+            // Deferred: applied to the final code_execution result (see
+            // scriptDeferredEndTurn) — ending the turn mid-script would cancel the
+            // stream while the script still runs and wedge the tool round.
+            this.scriptDeferredEndTurn.add(agentName);
+        }
+        if (result.isError) {
+            return `Error: ${result.error ?? 'tool call failed'}`;
+        }
+        if (result.data === undefined)
+            return '';
+        const agent = this.agents.get(agentName);
+        const maxChars = agent ? this.getMaxToolResultChars(agent) : undefined;
+        return toolResultDataToHistoryString(result.data, maxChars);
+    }
+    /**
+     * Dispatch a script-inner tool call through the NORMAL dispatch path and
+     * resolve with its result. The waiter intercept in handleProcessEvent
+     * (keyed by the pytc- call ID) routes the tool-result event here instead
+     * of into the agent's pending tool round.
+     */
+    dispatchScriptToolCall(agentName, toolName, args) {
+        return new Promise((resolve) => {
+            const callId = `pytc-${randomUUID()}`;
+            // Host-side leak guard: the python runtime already raises TimeoutError
+            // at toolCallTimeoutMs; this only reclaims the waiter if a dispatch path
+            // loses the result entirely (so the map cannot grow unboundedly).
+            const safetyMs = (this.codeExecutionConfig?.toolCallTimeoutMs ?? 270_000) + 30_000;
+            const safety = setTimeout(() => {
+                if (this.scriptToolWaiters.delete(callId)) {
+                    resolve({
+                        success: false,
+                        error: `tool '${toolName}' produced no result within ${Math.round(safetyMs / 1000)}s`,
+                        isError: true,
+                    });
+                }
+            }, safetyMs);
+            safety.unref?.();
+            this.scriptToolWaiters.set(callId, (result) => {
+                clearTimeout(safety);
+                resolve(result);
+            });
+            try {
+                this.dispatchToolCall(agentName, { id: callId, name: toolName, input: args });
+            }
+            catch (error) {
+                if (this.scriptToolWaiters.delete(callId)) {
+                    clearTimeout(safety);
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    resolve({ success: false, error: err.message, isError: true });
+                }
+            }
+        });
+    }
+    /** Abort a running script when the agent's turn dies underneath it. */
+    abortAgentScript(agentName, reason) {
+        const runner = this.codeExecutionRunners.get(agentName);
+        if (runner?.busy) {
+            runner.abort(reason);
+        }
+    }
     toMembraneToolResult(callId, afResult, maxChars) {
         if (afResult.isError) {
             return { toolUseId: callId, content: afResult.error ?? 'Unknown error', isError: true };
@@ -4401,6 +5259,27 @@ export class AgentFramework {
             this.dispatchChannelToolCall(agentName, enrichedCall);
             return;
         }
+        // Client-side programmatic tool calling: run a python script that calls
+        // the agent's other tools in-process (script-inner calls come back through
+        // this very dispatcher with waiter-tracked call IDs).
+        if (enrichedCall.name === CODE_EXECUTION_TOOL_NAME && this.codeExecutionConfig) {
+            this.dispatchCodeExecutionToolCall(agentName, enrichedCall);
+            return;
+        }
+        // prose_help: on-demand routing reference for explicit-prose agents.
+        // Answered inline — the grammar is a tool RESULT (model-requested), never
+        // ambient context (see PROSE_ROUTING_HELP / teach-by-bounce).
+        if (enrichedCall.name === 'prose_help') {
+            this.emitTrace({ type: 'tool:completed', module: 'framework', tool: 'prose_help', callId: enrichedCall.id, durationMs: 0 });
+            this.pushEvent({
+                type: 'tool-result',
+                callId: enrichedCall.id,
+                agentName,
+                moduleName: 'framework',
+                result: { success: true, data: PROSE_ROUTING_HELP },
+            });
+            return;
+        }
         const sepIndex = enrichedCall.name.indexOf('--');
         const moduleName = sepIndex >= 0 ? enrichedCall.name.substring(0, sepIndex) : 'unknown';
         const toolName = sepIndex >= 0 ? call.name.substring(sepIndex + 2) : call.name;
@@ -4723,6 +5602,13 @@ export class AgentFramework {
         if (err.name === 'OverBudgetError') {
             return { errorType: 'over_budget' };
         }
+        // context-manager's fatal coverage invariant (fix/coverage-invariant-fatal,
+        // 2026-07-26): a compile REFUSES rather than shipping a context with
+        // silently-dropped messages. Recovery is identical to over_budget — kick
+        // the compression drain so summaries cover the un-represented span.
+        if (err.name === 'UncoveredDropError') {
+            return { errorType: 'context_refusal' };
+        }
         return {};
     }
     /**
@@ -4777,7 +5663,19 @@ export class AgentFramework {
         // (e.g. a reason string that crossed a serialization boundary). It matches
         // CM's current OverBudgetError wording and MAY rot if CM rewords it — the
         // errorType gate is the one that's load-bearing.
-        const overBudget = errorType === 'over_budget' || /exceed hard budget/i.test(reason);
+        const overBudget = errorType === 'over_budget' ||
+            errorType === 'context_refusal' ||
+            /exceed hard budget|no summary covers/i.test(reason);
+        // Observability: a refused compile means the agent cannot think AT ALL
+        // this turn — surface it on the ops-alert pipeline (ops:alert trace +
+        // webhook → fleet-watch) immediately, not only at the hard-down streak.
+        // The per-(agent,kind) cooldown throttles repeats; failures.log already
+        // has the per-exhaustion record from logFailure above.
+        if (overBudget) {
+            this.opsAlert('context-refusal', agentName, `compile refused (${errorType ?? 'unclassified'}): ${reason.slice(0, 300)} — ` +
+                `drain breaker ${agent ? 'kicking' : 'unavailable (no agent handle)'}; ` +
+                `if this persists, raise contextBudgetTokens or overBudgetGraceRatio.`, { skipLog: true });
+        }
         if (agent && overBudget && !this.overBudgetDrainInFlight.has(agentName)) {
             this.overBudgetDrainInFlight.add(agentName);
             void (async () => {
@@ -4924,15 +5822,35 @@ export class AgentFramework {
             // yes, wake no).
             onRouteFailure: ({ channelId, reason, textLen }) => {
                 try {
+                    // Render a human-readable channel name when we can — a bare
+                    // snowflake in the marker is unresolvable for the agent (the
+                    // 2026-07-21 incident read as "a stale artifact", not a live
+                    // failure). The marker is `system: true`, so it is never
+                    // conversational and never influences routing.
+                    const label = channelId
+                        ? this.channelRegistry?.getDescriptor(channelId)?.label
+                        : undefined;
+                    const where = channelId
+                        ? label && label !== channelId
+                            ? `${label.startsWith('#') ? label : `#${label}`} (${channelId})`
+                            : channelId
+                        : 'the channel';
                     this.addMessage('user', [{
                             type: 'text',
-                            text: `[discord-send-failed] Your previous reply (${textLen} chars) could not be delivered to ${channelId ?? 'the channel'} (${reason}). It was saved to your archive but the human did not receive it.`,
+                            text: `[discord-send-failed] Your previous reply (${textLen} chars) could not be delivered to ${where} (${reason}). It was saved to your archive but the human did not receive it.`,
                         }], { system: true, kind: 'discord-send-failed', channelId: channelId ?? '', reason });
                 }
                 catch (err) {
                     console.error('onRouteFailure: failed to record send-failure marker:', err);
                 }
             },
+            // A channel opened without the agent asking (policy admission or an
+            // open forced by delivery) must be announced in the window, with the
+            // opt-out named. Routed here so registry-driven opens and framework-
+            // driven opens produce the same durable notice.
+            onChannelAutoOpened: ({ conversationId, source, channels }) => {
+                this.recordChannelAutoOpenNotice(conversationId, channels, source);
+            },
         });
         // Host capabilities advertised during the MCP handshake — stored so
         // servers can also be connected later at runtime (connectMcplServer).
@@ -5785,6 +6703,33 @@ export class AgentFramework {
                     this.checkpointManager.recordCheckpoint(serverId, fs, result.state);
                 }
             }
+            // INVARIANT: engaging a channel opens it. A successful explicit send
+            // into a channel the registry knows as closed drives the same open
+            // flow as channel_open (durable desired state, server subscribe), so
+            // there is no such thing as posting into a channel that stays
+            // half-alive (no typing, no reactions, no inbound forwarding).
+            // Fire-and-forget: the send already succeeded; the open must not
+            // delay or fail the tool result.
+            if (this.channelRegistry &&
+                SEND_ENGAGEMENT_TOOLS.has(toolName) &&
+                result.isError !== true) {
+                const target = extractChannelIdFromToolResult(result.content) ??
+                    (typeof args.channelId === 'string' ? args.channelId : undefined);
+                if (target) {
+                    this.channelRegistry
+                        .openIfClosedForSend(target, serverId)
+                        .then(({ status, channelId, label }) => {
+                        if (status === 'opened') {
+                            console.error(`[channel] ${agentName}: explicit ${toolName} into closed channel ${target} — opened (send implies engagement)`);
+                            this.recordChannelAutoOpenNotice(agentName, [{ channelId: channelId ?? target, label }], 'opened-by-reply');
+                        }
+                        else if (status === 'open-failed') {
+                            console.error(`[channel] ${agentName}: ${toolName} delivered to ${target} but the open-on-send failed — channel remains half-alive, will reconcile`);
+                        }
+                    })
+                        .catch((err) => console.error('[channel] open-on-send error:', err));
+                }
+            }
             // Convert MCP tool result to framework ToolResult.
             // When the result contains non-text blocks (e.g. images from an MCP
             // tool like zulip-mcp's fetch_attachment), pass the full content array
@@ -6014,12 +6959,31 @@ export class AgentFramework {
         const human = seconds >= 3600 ? `${(seconds / 3600).toFixed(1)}h`
             : seconds >= 60 ? `${Math.round(seconds / 60)}m`
                 : `${Math.round(seconds)}s`;
-        // Announce in the sticky channel (best-effort; never blocks the result).
+        // Announce in the TURN's frozen locus (best-effort; never blocks the
+        // result). The sleep tool runs mid-turn, so the pin is live — same
+        // authority as every other speech path, no live re-resolution.
         if (announce && this.channelRegistry) {
             const text = input.message ?? `💤 Going quiet for ${human}. I'll still see messages, but won't respond until I wake.`;
-            this.channelRegistry.routeSpeech(agentName, text).catch((err) => {
-                console.error('[sleep] announce failed:', err instanceof Error ? err.message : err);
-            });
+            const agent = this.agents.get(agentName);
+            if (agent?.proseRouting === 'explicit') {
+                // Explicit mode: announce to the turn's sticky prose target if the
+                // model has set one; otherwise stay quiet — never guess a channel.
+                const target = this.proseTargetPins.get(agentName);
+                if (target) {
+                    this.channelRegistry.routeSpeech(agentName, text, target).catch((err) => {
+                        console.error('[sleep] announce failed:', err instanceof Error ? err.message : err);
+                    });
+                }
+                else {
+                    console.error(`[sleep] ${agentName}: no prose target this turn — sleep announcement not posted (explicit mode never guesses)`);
+                }
+            }
+            else {
+                const locus = this.turnLocusPins.get(agentName) ?? null;
+                this.channelRegistry.routeSpeech(agentName, text, locus).catch((err) => {
+                    console.error('[sleep] announce failed:', err instanceof Error ? err.message : err);
+                });
+            }
         }
         console.error(`[sleep] agent=${agentName} seconds=${seconds} announce=${announce} until=${new Date(until).toISOString()}`);
         // endTurn: the agent stops here and goes idle for the duration.