@animalabs/agent-framework 0.5.4 → 0.5.7

package/dist/src/framework.js

@@ -12,12 +12,15 @@ import { HookOrchestrator } from './mcpl/hook-orchestrator.js';
 import { PushHandler } from './mcpl/push-handler.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 { CheckpointManager } from './mcpl/checkpoint-manager.js';
 import { isToolAllowed } from './mcpl/tool-policy.js';
 import { EventGate } from './gate/event-gate.js';
 import { UsageTracker } from './usage/usage-tracker.js';
 const FRAMEWORK_STATE_ID = 'framework/state';
+const CONVERSATION_ROUTER_STATE_ID = 'framework/conversation-router';
 const INFERENCE_LOG_ID = 'framework/inference-log';
 const PROCESS_LOG_ID = 'framework/process-log';
 const TURN_CHECKPOINTS_ID = 'framework/turn-checkpoints';
@@ -91,9 +94,6 @@ function extractGateFields(event) {
         : undefined;
     return { content, metadata, mount, paths };
 }
-/**
- * The main agent framework.
- */
 export class AgentFramework {
     store;
     ownsStore;
@@ -113,6 +113,12 @@ export class AgentFramework {
     processLoggingBroadcast;
     activeStreams = new Map();
     pendingAssistantBlocks = new Map();
+    /** Per-agent count of consecutive exhausted inferences (reset on any success).
+     *  Drives hard-down escalation — see noteInferenceExhausted. */
+    consecutiveInferenceFailures = new Map();
+    /** N consecutive failed inferences ⇒ the agent is treated as hard-down and
+     *  escalated loudly to stderr. */
+    inferenceFailureEscalationThreshold = 3;
     /** Name of the primary (non-ephemeral) agent for routing framework messages. */
     primaryAgentName = null;
     // Messages deferred while an agent is waiting_for_tools (to preserve
@@ -130,6 +136,21 @@ export class AgentFramework {
     inferenceRouter = null;
     channelRegistry = null;
     checkpointManager = null;
+    /** Per-channel conversation routing (null unless config.conversations set). */
+    conversationRouter = null;
+    /** Agent configs by name — fork agents are built from the template's config. */
+    agentConfigs = new Map();
+    /**
+     * Fork agent → its home channel. Permanent (unlike router bindings, which
+     * expire): publish/injection scoping must survive unbinding so the closure
+     * turn still lands in the right channel.
+     */
+    conversationAgentHomes = new Map();
+    /** Last idle-TTL sweep timestamp. */
+    lastConversationSweep = 0;
+    /** Forks whose TTL closure turn has been queued — disposed (removed from
+     * agents/agentConfigs/conversationAgentHomes) when their stream ends. */
+    closingConversationAgents = new Set();
     mcplTools = [];
     mcplToolRefreshInFlight = false;
     mcplToolRefreshPending = false;
@@ -163,6 +184,7 @@ export class AgentFramework {
             getMessage: (id) => this.getMessage(id),
             queryMessages: (filter) => this.queryMessages(filter),
             pushEvent: (event) => this.pushEvent(event),
+            onTrace: (listener) => this.onTrace(listener),
         });
     }
     /**
@@ -235,6 +257,32 @@ export class AgentFramework {
         for (const module of config.modules) {
             await framework.addModule(module);
         }
+        // Initialize per-channel conversation routing (if configured)
+        if (config.conversations) {
+            if (!framework.agents.has(config.conversations.templateAgent)) {
+                throw new Error(`conversations.templateAgent "${config.conversations.templateAgent}" ` +
+                    `is not a configured agent`);
+            }
+            framework.conversationRouter = new ConversationRouter(config.conversations);
+            // Generation counters persist across restarts — reusing generation 1's
+            // agent name after a restart would reopen (and re-seed) the previous
+            // engagement's Chronicle namespace.
+            try {
+                store.registerState({ id: CONVERSATION_ROUTER_STATE_ID, strategy: 'snapshot' });
+            }
+            catch {
+                // Already registered
+            }
+            try {
+                const data = store.getStateJson(CONVERSATION_ROUTER_STATE_ID);
+                if (data?.generations) {
+                    framework.conversationRouter.hydrateGenerations(data.generations);
+                }
+            }
+            catch {
+                // No persisted state yet
+            }
+        }
         // Initialize EventGate if configured (before MCPL so it can be wired as trigger filter)
         if (config.gate) {
             const configPath = config.gate.configPath
@@ -244,6 +292,7 @@ export class AgentFramework {
             framework.eventGate = new EventGate({
                 configPath,
                 initialConfig: config.gate.config,
+                privilegedUsersPath: config.gate.privilegedUsersPath,
                 emitTrace: (e) => framework.emitTrace(e),
                 addMessage: (p, c, m) => framework.addMessage(p, c, m),
                 requestInference: (agentName, reason, source) => {
@@ -351,6 +400,14 @@ export class AgentFramework {
      */
     onTrace(listener) {
         this.traceListeners.push(listener);
+        // Return an unsubscribe so callers with a bounded lifetime (e.g. modules
+        // that get torn down and recreated on session switch) don't leak
+        // listeners. Existing callers that ignore the return value are unaffected.
+        return () => {
+            const idx = this.traceListeners.indexOf(listener);
+            if (idx >= 0)
+                this.traceListeners.splice(idx, 1);
+        };
     }
     /**
      * Public accessor for the MCPL channel registry.
@@ -396,6 +453,13 @@ export class AgentFramework {
     getAllAgents() {
         return Array.from(this.agents.values());
     }
+    /**
+     * Get the per-channel conversation router (null unless config.conversations
+     * was set). Exposed for modules/UIs that surface active engagements.
+     */
+    getConversationRouter() {
+        return this.conversationRouter;
+    }
     /**
      * Abort an in-flight inference for an agent.
      */
@@ -422,12 +486,79 @@ export class AgentFramework {
     getAllTools() {
         const moduleTools = this.moduleRegistry.getAllTools();
         const channelTools = this.channelRegistry?.getChannelTools() ?? [];
-        const gateTools = this.eventGate ? [this.eventGate.getToolDefinition()] : [];
+        const gateTools = this.eventGate
+            ? [this.eventGate.getToolDefinition(), ...AgentFramework.SLEEP_TOOLS]
+            : [];
         if (this.mcplTools.length === 0 && channelTools.length === 0 && gateTools.length === 0) {
             return moduleTools;
         }
         return [...moduleTools, ...this.mcplTools, ...channelTools, ...gateTools];
     }
+    /**
+     * Build the membrane-normalized request that WOULD be emitted if `agentName`
+     * were activated right now — WITHOUT running inference, opening a stream, or
+     * mutating agent state. Intended for debug/preview tooling.
+     *
+     * Transparency contract (default): the preview is side-effect-free and
+     * leaves no trace on the system. It does only read-only work —
+     * `ContextManager.compile` (which never triggers compression itself;
+     * compression runs in the background out-of-band), tool filtering, and
+     * system-prompt assembly — then delegates to `Agent.buildActivationRequest`.
+     * No tokens are spent, nothing is written to Chronicle, and no external
+     * MCPL server is contacted.
+     *
+     * The trade-off is fidelity: the dynamically-gathered ContextInjection[]
+     * (module `gatherContext` + MCPL `beforeInference` hooks) are NOT included
+     * by default, because gathering them is not transparent —
+     *   - module `gatherContext` can run inference (e.g. RetrievalModule makes
+     *     Haiku calls — real token cost and latency), and
+     *   - MCPL `beforeInference` hooks are arbitrary RPCs to external servers
+     *     with side effects, and a preview never sends the paired
+     *     `afterInference`, which can leave a stateful server half-open.
+     *
+     * Pass `{ injections: true }` to opt into full-fidelity gathering and accept
+     * those side effects (byte-faithful to a real activation's injected context).
+     */
+    async previewActivation(agentName, opts) {
+        const agent = this.agents.get(agentName);
+        if (!agent) {
+            throw new Error(`Agent not found: ${agentName}`);
+        }
+        const tools = this.getAllTools().filter((t) => agent.canUseTool(t.name));
+        // 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);
+        }
+        // Full-fidelity path: mirrors startAgentStream's injection gathering.
+        // NOT transparent — see the doc comment above.
+        let injections;
+        // Module gatherContext (fail-open, matches startAgentStream)
+        try {
+            const moduleInjections = await this.moduleRegistry.gatherContext(agentName);
+            if (moduleInjections.length > 0) {
+                injections = moduleInjections;
+            }
+        }
+        catch (error) {
+            console.error('Module gatherContext error (preview):', error);
+        }
+        // MCPL beforeInference hooks (fail-open). Note: the paired afterInference
+        // is intentionally never sent here — this is a preview, not a real turn.
+        if (this.hookOrchestrator) {
+            try {
+                const hookParams = this.buildBeforeInferenceParams(agent);
+                const hookInjections = await this.hookOrchestrator.beforeInference(hookParams);
+                if (hookInjections.length > 0) {
+                    injections = injections ? [...injections, ...hookInjections] : hookInjections;
+                }
+            }
+            catch (error) {
+                console.error('beforeInference hook error (preview):', error);
+            }
+        }
+        return agent.buildActivationRequest(tools, injections);
+    }
     /**
      * Check if process logging is enabled.
      */
@@ -666,6 +797,268 @@ export class AgentFramework {
      * Query inference logs.
      * Returns entries with summary info (doesn't resolve blobs).
      */
+    /** Synthesized sleep/wake tool definitions (present when a gate is wired). */
+    static SLEEP_TOOLS = [
+        {
+            name: 'sleep',
+            description: 'Go quiet: suppress external pings and wakes for a number of seconds. ' +
+                'Messages still accumulate in your context — you just won’t be woken to ' +
+                'respond to them until the window passes. Your heartbeat still beats: you’ll ' +
+                'briefly rouse on each tick and can keep resting or call `wake` to get up early. ' +
+                'Privileged users can also still reach you. By default announces in your current channel.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    seconds: { type: 'number', description: 'How long to stay asleep, in seconds.' },
+                    announce: {
+                        type: 'boolean',
+                        description: 'Announce the sleep in the current sticky channel (default true).',
+                    },
+                    message: {
+                        type: 'string',
+                        description: 'Optional custom announcement text (overrides the default).',
+                    },
+                },
+                required: ['seconds'],
+            },
+        },
+        {
+            name: 'wake',
+            description: 'End your current sleep early, resuming normal wakes immediately.',
+            inputSchema: { type: 'object' },
+        },
+    ];
+    /** Refusal category → Discord reaction emoji. Unknown categories get 🛑. */
+    static REFUSAL_REACTIONS = {
+        bio: '☣️',
+        chem: '🧪',
+        nuclear: '☢️',
+        cyber: '💻',
+        reasoning_extraction: '🧠',
+    };
+    /**
+     * Mark an inference refusal visibly: react on the message that holds the
+     * conversational locus (the most recent incoming channel message) with a
+     * category-specific emoji. Best-effort — failures are logged, never thrown,
+     * and non-Discord loci are silently skipped.
+     */
+    async reactToRefusal(agentName, category) {
+        try {
+            const incoming = this.channelRegistry?.buildChannelContext()?.incoming;
+            if (!incoming)
+                return;
+            // incoming.channelId is the MCPL composite id ("discord:<guild>:<channel>");
+            // the reaction tool wants the raw Discord channel (or thread) id — the
+            // last segment.
+            const parts = incoming.channelId.split(':');
+            if (parts[0] !== 'discord')
+                return;
+            const channelId = parts[parts.length - 1];
+            const emoji = AgentFramework.REFUSAL_REACTIONS[category] ?? '🛑';
+            // Resolve the MCPL server that owns the locus channel and call
+            // tools/call directly on its connection (bare tool name — no prefix
+            // games), bypassing the agent event queue so no synthetic tool-result
+            // is injected into a turn the agent never took.
+            const serverId = this.channelRegistry?.getChannelServerId(incoming.channelId);
+            const server = serverId ? this.mcplServerRegistry?.getServer(serverId) : null;
+            if (!server) {
+                console.error(`[inference-refusal] reaction skipped: no MCPL server for locus "${incoming.channelId}" (agent=${agentName})`);
+                return;
+            }
+            await server.sendToolsCall('add_reaction', {
+                channelId,
+                messageId: incoming.messageId,
+                emoji,
+            });
+        }
+        catch (err) {
+            console.error('[inference-refusal] reaction failed:', err instanceof Error ? err.message : err);
+        }
+    }
+    /**
+     * Handle a `host/command` request from an MCPL surface server (e.g. a
+     * Discord slash command). Currently supports:
+     *
+     *   undo — revert the last N inference turns (branch-based, see
+     *   `undoLastTurn`). The response includes the last message the agent
+     *   would see in its context after the undo, obtained via the transparent
+     *   `previewActivation` render (no inference, no Chronicle writes).
+     */
+    async handleHostCommand(serverId, params) {
+        if (params.command !== 'undo' && params.command !== 'hide') {
+            return { ok: false, error: `Unknown host command: ${String(params.command)}` };
+        }
+        const agentName = params.agentName ?? [...this.agents.keys()][0];
+        if (!agentName || !this.agents.has(agentName)) {
+            return { ok: false, error: `Unknown agent: ${String(agentName)}` };
+        }
+        // hide: redact a single message (or an inclusive range) from the active
+        // branch, addressed by Discord message id. Unlike undo this is a
+        // removal-in-place (chronicle redact), not a branch rewind.
+        if (params.command === 'hide') {
+            const agent = this.agents.get(agentName);
+            if (agent.state.status !== 'idle') {
+                return { ok: false, error: `Cannot hide while agent is ${agent.state.status}` };
+            }
+            if (!params.fromMessageId) {
+                return { ok: false, error: 'hide: fromMessageId is required' };
+            }
+            const cm = agent.getContextManager();
+            const all = cm.getAllMessages();
+            const byDiscordId = (did) => all.findIndex((m) => String(m.metadata?.messageId) === String(did));
+            // Collect Discord refs of every message in [lo, hi] that carries one,
+            // so the surface can mark them. channelId here is whatever the ingest
+            // path stored (raw id or "discord:guild:channel"); the surface
+            // normalizes it.
+            const refsIn = (lo, hi) => {
+                const refs = [];
+                for (let i = lo; i <= hi; i++) {
+                    const md = all[i].metadata;
+                    if (md?.messageId && md?.channelId) {
+                        refs.push({ channelId: String(md.channelId), messageId: String(md.messageId) });
+                    }
+                }
+                return refs;
+            };
+            const fromIdx = byDiscordId(params.fromMessageId);
+            if (fromIdx < 0) {
+                return {
+                    ok: false,
+                    error: `Message ${params.fromMessageId} is not an addressable message in context (it may only exist inside backscroll text, or predates this session).`,
+                };
+            }
+            try {
+                if (params.toMessageId) {
+                    const toIdx = byDiscordId(params.toMessageId);
+                    if (toIdx < 0) {
+                        return { ok: false, error: `Message ${params.toMessageId} is not an addressable message in context.` };
+                    }
+                    const [lo, hi] = fromIdx <= toIdx ? [fromIdx, toIdx] : [toIdx, fromIdx];
+                    const refs = refsIn(lo, hi);
+                    cm.removeMessages(all[lo].id, all[hi].id);
+                    console.error(`[host-command] hide agent=${agentName} range removed=${hi - lo + 1} ` +
+                        `(${params.fromMessageId}..${params.toMessageId}) by=${params.requesterName ?? params.requesterId ?? 'unknown'} (server=${serverId})`);
+                    return {
+                        ok: true,
+                        hidden: hi - lo + 1,
+                        hiddenRefs: refs,
+                        lastVisible: await this.lastVisiblePreview(agentName),
+                    };
+                }
+                const refs = refsIn(fromIdx, fromIdx);
+                cm.removeMessage(all[fromIdx].id);
+                console.error(`[host-command] hide agent=${agentName} removed=1 (${params.fromMessageId}) ` +
+                    `by=${params.requesterName ?? params.requesterId ?? 'unknown'} (server=${serverId})`);
+                return {
+                    ok: true,
+                    hidden: 1,
+                    hiddenRefs: refs,
+                    lastVisible: await this.lastVisiblePreview(agentName),
+                };
+            }
+            catch (error) {
+                return { ok: false, error: error instanceof Error ? error.message : String(error) };
+            }
+        }
+        // Message-granular mode: branch the chronicle at the message that should
+        // become the new tail (ContextManager.branchAt — origin-sequence-based
+        // time-travel branching; see chronicle's rfc-state-item-origins addendum).
+        // No turn checkpoints involved, so this reaches past turn boundaries.
+        if (typeof params.messages === 'number' && params.messages > 0) {
+            const agent = this.agents.get(agentName);
+            if (agent.state.status !== 'idle') {
+                return { ok: false, error: `Cannot undo while agent is ${agent.state.status}` };
+            }
+            const n = Math.max(1, Math.min(50, Math.floor(params.messages)));
+            const cm = agent.getContextManager();
+            const allMessages = cm.getAllMessages();
+            if (n >= allMessages.length) {
+                return {
+                    ok: false,
+                    error: `Cannot remove ${n} message(s) — history has ${allMessages.length}; at least one must remain.`,
+                };
+            }
+            const target = allMessages[allMessages.length - 1 - n];
+            const branchName = cm.branchAt(target.id, `undo-msgs/${agentName}/${Date.now()}`);
+            await cm.switchBranch(branchName);
+            // Materialize config files from the new branch (fire-and-forget; gate
+            // picks up via mtime) — mirrors undoLastTurn.
+            const wsUndo = this.moduleRegistry.getModule('workspace');
+            if (wsUndo && 'materializeMount' in wsUndo) {
+                wsUndo
+                    .materializeMount('_config')
+                    .catch(() => { });
+            }
+            console.error(`[host-command] undo-messages agent=${agentName} removed=${n} branch=${branchName}` +
+                ` by=${params.requesterName ?? params.requesterId ?? 'unknown'} (server=${serverId})`);
+            return {
+                ok: true,
+                messagesRemoved: n,
+                lastVisible: await this.lastVisiblePreview(agentName),
+            };
+        }
+        const requested = Math.max(1, Math.min(20, Math.floor(params.turns ?? 1)));
+        let undone = 0;
+        try {
+            for (let i = 0; i < requested; i++) {
+                const r = this.undoLastTurn(agentName);
+                if (!r.undone)
+                    break;
+                undone++;
+            }
+        }
+        catch (error) {
+            // e.g. "Cannot undo while agent is streaming" — report what happened,
+            // including any turns already undone before the failure.
+            const msg = error instanceof Error ? error.message : String(error);
+            if (undone === 0)
+                return { ok: false, error: msg };
+            console.error(`[host-command] undo partially failed after ${undone}/${requested}: ${msg}`);
+        }
+        console.error(`[host-command] undo agent=${agentName} requested=${requested} undone=${undone}` +
+            ` by=${params.requesterName ?? params.requesterId ?? 'unknown'} (server=${serverId})`);
+        if (undone === 0) {
+            return { ok: true, undone: 0, requested, lastVisible: null };
+        }
+        return { ok: true, undone, requested, lastVisible: await this.lastVisiblePreview(agentName) };
+    }
+    /**
+     * The last message the agent would see in its context right now, via the
+     * transparent `previewActivation` render (no inference, no Chronicle
+     * writes). Returns null if the preview fails or the context is empty.
+     */
+    async lastVisiblePreview(agentName) {
+        try {
+            const preview = await this.previewActivation(agentName);
+            const messages = preview.messages ?? [];
+            const last = messages[messages.length - 1];
+            if (!last)
+                return null;
+            const blocks = Array.isArray(last.content) ? last.content : [];
+            const text = blocks
+                .map((b) => (b && typeof b === 'object' && 'text' in b ? String(b.text) : ''))
+                .join(' ')
+                .trim();
+            // Surface-injected preambles (<system>…</system>, <backscroll>…
+            // </backscroll>) can dominate the head of a bundled incoming message
+            // and bury the actual conversational line. Strip them for the
+            // preview; fall back to the raw text if nothing else remains.
+            const stripped = text
+                .replace(/<system>[\s\S]*?<\/system>/g, '')
+                .replace(/<backscroll\b[\s\S]*?<\/backscroll>/g, '')
+                .trim();
+            const body = stripped.length > 0 ? stripped : text;
+            return {
+                participant: last.participant,
+                role: last.role,
+                preview: body.length > 400 ? `${body.slice(0, 400)}…` : body,
+            };
+        }
+        catch (error) {
+            console.error('[host-command] post-undo context preview failed:', error instanceof Error ? error.message : error);
+            return null;
+        }
+    }
     queryInferenceLogs(query) {
         const limit = query?.limit ?? 50;
         const offset = query?.offset ?? 0;
@@ -1052,6 +1445,7 @@ export class AgentFramework {
         });
         const agent = new Agent(config, contextManager, this.membrane);
         this.agents.set(config.name, agent);
+        this.agentConfigs.set(config.name, config);
         // First non-ephemeral agent becomes the primary for message routing
         if (!this.primaryAgentName) {
             this.primaryAgentName = config.name;
@@ -1074,6 +1468,8 @@ export class AgentFramework {
         if (event) {
             await this.handleProcessEvent(event);
         }
+        // Close idle conversation forks (no-op unless conversations configured)
+        this.sweepExpiredConversations();
         // Check for inference requests
         await this.processInferenceRequests();
         // Yield to the event loop between iterations.
@@ -1124,26 +1520,18 @@ export class AgentFramework {
                     }
                     // Compute truncation limit from agent's strategy (maxMessageTokens * 4 chars)
                     const maxChars = this.getMaxToolResultChars(agent);
-                    // Store tool results as a user message (tool_result blocks)
-                    const toolResultContent = currentState.toolResults.map(tc => {
-                        let content;
-                        if (tc.result.isError) {
-                            content = tc.result.error ?? 'Unknown error';
-                        }
-                        else {
-                            content = JSON.stringify(tc.result.data);
-                            if (maxChars && content.length > maxChars) {
-                                content = safeSlice(content, 0, maxChars)
-                                    + '\n\n[truncated — original was ' + content.length + ' chars]';
-                            }
-                        }
-                        return {
-                            type: 'tool_result',
-                            toolUseId: tc.id,
-                            content,
-                            isError: tc.result.isError,
-                        };
-                    });
+                    // Store tool results as a user message (tool_result blocks).
+                    // Use the history serializer so MCP image blocks become a short
+                    // `[image: type, size]` placeholder instead of megabytes of base64
+                    // that would corrupt under truncation.
+                    const toolResultContent = currentState.toolResults.map(tc => ({
+                        type: 'tool_result',
+                        toolUseId: tc.id,
+                        content: tc.result.isError
+                            ? tc.result.error ?? 'Unknown error'
+                            : toolResultDataToHistoryString(tc.result.data, maxChars),
+                        isError: tc.result.isError,
+                    }));
                     agent.getContextManager().addMessage('user', toolResultContent);
                     // Flush any messages that were deferred while waiting for tool results.
                     // Route to the PRIMARY agent — deferred messages are framework-level
@@ -1211,7 +1599,7 @@ export class AgentFramework {
         // These events are protocol-level (spec Sections 9 & 14) and always
         // represent content intended for the model's context window.
         if (event.type === 'mcpl:channel-incoming') {
-            this.handleMcplChannelIncoming(event);
+            await this.handleMcplChannelIncoming(event);
         }
         else if (event.type === 'mcpl:push-event') {
             this.handleMcplPushEvent(event);
@@ -1282,8 +1670,10 @@ export class AgentFramework {
                 if (!decision.trigger)
                     return;
             }
+            // Broadcast requests exclude conversation forks — they are driven by
+            // their own channel's messages, not by framework-wide events.
             const targetAgents = response.requestInference === true
-                ? Array.from(this.agents.keys())
+                ? Array.from(this.agents.keys()).filter((n) => !this.conversationAgentHomes.has(n))
                 : response.requestInference;
             for (const agentName of targetAgents) {
                 const agent = this.agents.get(agentName);
@@ -1305,7 +1695,7 @@ export class AgentFramework {
      * Convert an incoming MCPL channel message to a context message.
      * This replaces the old MCPLModule.onProcess() message conversion.
      */
-    handleMcplChannelIncoming(event) {
+    async handleMcplChannelIncoming(event) {
         const metadata = {
             ...event.metadata,
             channelId: event.channelId,
@@ -1316,6 +1706,13 @@ export class AgentFramework {
         };
         if (event.threadId)
             metadata.threadId = event.threadId;
+        // 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.
+        if (this.conversationRouter) {
+            await this.routeConversationIncoming(event, metadata);
+            return;
+        }
         const id = this.addMessage('user', event.content, metadata);
         this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:channel-incoming' });
         if (event.triggerInference) {
@@ -1329,6 +1726,228 @@ export class AgentFramework {
             }
         }
     }
+    /**
+     * Route an incoming channel message through the ConversationRouter:
+     * deliver to the channel's bound fork agent, spawning it from the template
+     * agent first when the bind policy matches. Unrouted messages are dropped —
+     * the template ("trunk") is a dormant warm checkpoint, not a listener.
+     */
+    async routeConversationIncoming(event, messageMetadata) {
+        const router = this.conversationRouter;
+        const descriptor = this.channelRegistry?.getDescriptor(event.channelId);
+        const decision = router.route({
+            channelId: event.channelId,
+            mentioned: event.metadata?.mentioned === true,
+            kind: ConversationRouter.classifyChannel(descriptor, event.metadata),
+        });
+        if (decision.kind === 'unbound') {
+            this.emitTrace({
+                type: 'mcpl:conversation-unrouted',
+                channelId: event.channelId,
+                messageId: event.messageId,
+            });
+            return;
+        }
+        let agent;
+        if (decision.kind === 'spawn') {
+            try {
+                agent = await this.createConversationAgent(decision.agentName, event.channelId);
+                router.bind(event.channelId, decision.agentName, decision.generation);
+                this.persistConversationRouterState();
+                this.emitTrace({
+                    type: 'mcpl:conversation-spawned',
+                    channelId: event.channelId,
+                    agentName: decision.agentName,
+                    generation: decision.generation,
+                    template: router.templateAgent,
+                });
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                console.error(`Failed to spawn conversation agent for ${event.channelId}:`, err);
+                this.emitTrace({
+                    type: 'mcpl:conversation-spawn-failed',
+                    channelId: event.channelId,
+                    agentName: decision.agentName,
+                    error: err.message,
+                });
+                return; // next qualifying message proposes the same spawn again
+            }
+        }
+        else {
+            agent = this.agents.get(decision.agentName);
+            if (!agent) {
+                // Bound agent vanished (e.g. external reset) — unbind so the next
+                // qualifying message respawns a fresh fork.
+                router.unbind(event.channelId);
+                this.emitTrace({
+                    type: 'mcpl:conversation-binding-orphaned',
+                    channelId: event.channelId,
+                    agentName: decision.agentName,
+                });
+                return;
+            }
+        }
+        // Respect an explicit server-config-level veto (shouldTriggerInference)
+        // on top of the router's own trigger policy.
+        const trigger = decision.trigger && event.triggerInference !== false;
+        messageMetadata.triggered = trigger;
+        const id = agent.getContextManager().addMessage('user', event.content, messageMetadata);
+        this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:channel-incoming' });
+        if (trigger) {
+            this.pendingRequests.push({
+                agentName: agent.name,
+                reason: 'mcpl:channel-incoming',
+                source: event.serverId,
+                timestamp: Date.now(),
+            });
+        }
+    }
+    /**
+     * Spawn a persistent per-channel conversation agent ("fork") from the
+     * template agent: own ContextManager under `conversations/{name}`, seeded
+     * with a copy of the template's compiled context (the SubagentModule
+     * wholesale-copy pattern), registered in the event loop like any agent —
+     * but never primary.
+     */
+    async createConversationAgent(name, channelId) {
+        const router = this.conversationRouter;
+        const templateConfig = this.agentConfigs.get(router.templateAgent);
+        const template = this.agents.get(router.templateAgent);
+        if (!template || !templateConfig) {
+            throw new Error(`conversation template agent "${router.templateAgent}" not found`);
+        }
+        const contextManager = await ContextManager.open({
+            store: this.store,
+            namespace: `conversations/${name}`,
+            isolate: true,
+            // Strategy instances are stateful — never share the template's.
+            strategy: router.strategyFactory?.() ?? new PassthroughStrategy(),
+            membrane: this.membrane,
+            debugLogContext: !!process.env.DEBUG_CONTEXT,
+        });
+        // Seed with the template's compiled context, renaming the template
+        // participant so the fork reads its inheritance as its own history.
+        // Guard: only seed a genuinely fresh namespace. Generation counters are
+        // persisted precisely so names aren't reused, but if this namespace has
+        // history anyway (counter state lost, crash between spawn and persist),
+        // seeding again would stack another template copy on top of it.
+        const { messages: existing } = await contextManager.compile();
+        if (existing.length === 0) {
+            const { messages: compiled } = await template.getContextManager().compile();
+            for (const msg of compiled) {
+                const participant = msg.participant === template.name ? name : msg.participant;
+                contextManager.addMessage(participant, msg.content);
+            }
+        }
+        const config = { ...templateConfig, name, strategy: undefined };
+        const agent = new Agent(config, contextManager, this.membrane);
+        this.agents.set(name, agent);
+        this.agentConfigs.set(name, config);
+        this.conversationAgentHomes.set(name, channelId);
+        return agent;
+    }
+    /** Persist the router's generation counters (see hydration in create()). */
+    persistConversationRouterState() {
+        if (!this.conversationRouter)
+            return;
+        try {
+            this.store.setStateJson(CONVERSATION_ROUTER_STATE_ID, {
+                generations: this.conversationRouter.exportGenerations(),
+            });
+        }
+        catch (error) {
+            console.error('Failed to persist conversation router state:', error);
+        }
+    }
+    /**
+     * Remove a closed conversation fork from the framework: its closure turn
+     * has finished, so the home mapping has served its purpose and keeping the
+     * agent registered would just grow every agent scan and broadcast filter
+     * forever. The fork's context stays in Chronicle for investigation.
+     */
+    disposeConversationAgent(agentName) {
+        this.closingConversationAgents.delete(agentName);
+        const channelId = this.conversationAgentHomes.get(agentName);
+        this.agents.delete(agentName);
+        this.agentConfigs.delete(agentName);
+        this.conversationAgentHomes.delete(agentName);
+        this.emitTrace({
+            type: 'mcpl:conversation-disposed',
+            agentName,
+            channelId,
+        });
+    }
+    /**
+     * Scope MCPL context injections for a conversation-bound agent: drop
+     * injections that are another open channel's context (injection namespace
+     * = channelId by adapter convention), keep its own channel and anything
+     * that isn't channel context.
+     */
+    scopeInjectionsForAgent(agentName, injections) {
+        const home = this.conversationAgentHomes.get(agentName);
+        if (!home || !this.channelRegistry || injections.length === 0) {
+            return injections;
+        }
+        const openChannelIds = new Set(this.channelRegistry.getOpenChannels().map((e) => e.descriptor.id));
+        return injections.filter((inj) => {
+            const ns = inj.namespace;
+            if (!ns || !openChannelIds.has(ns))
+                return true;
+            return ns === home;
+        });
+    }
+    /**
+     * Idle-TTL sweep for conversation bindings (runs at most once per minute
+     * from the event loop). Expired forks get a final system-initiated closure
+     * turn — publish scoping still works because the agent's home channel
+     * mapping is permanent — and the channel unbinds immediately, so the next
+     * qualifying message spawns a fresh fork from the current template.
+     */
+    sweepExpiredConversations() {
+        if (!this.conversationRouter)
+            return;
+        const now = Date.now();
+        if (now - this.lastConversationSweep < 60_000)
+            return;
+        this.lastConversationSweep = now;
+        for (const binding of this.conversationRouter.expired(now)) {
+            this.conversationRouter.unbind(binding.channelId);
+            this.emitTrace({
+                type: 'mcpl:conversation-closed',
+                channelId: binding.channelId,
+                agentName: binding.agentName,
+                reason: 'idle-ttl',
+            });
+            const agent = this.agents.get(binding.agentName);
+            if (!agent) {
+                // Agent vanished (external reset) — nothing to close, just make sure
+                // its bookkeeping doesn't linger.
+                this.agentConfigs.delete(binding.agentName);
+                this.conversationAgentHomes.delete(binding.agentName);
+                continue;
+            }
+            agent.getContextManager().addMessage('user', [{ type: 'text', text: this.conversationRouter.closurePrompt }], { channelId: binding.channelId, conversationClosure: true });
+            this.pendingRequests.push({
+                agentName: binding.agentName,
+                reason: 'conversation:closure',
+                source: 'framework',
+                timestamp: now,
+            });
+            // Disposed when the closure stream ends (driveStream finally), with
+            // the reaper below as fallback.
+            this.closingConversationAgents.add(binding.agentName);
+        }
+        // Fallback reaper: a closing fork whose closure inference never ran
+        // (request dropped as stale, inference policy veto) would otherwise stay
+        // registered forever. No active stream + no pending request = done.
+        for (const agentName of [...this.closingConversationAgents]) {
+            if (!this.activeStreams.has(agentName) &&
+                !this.pendingRequests.some((r) => r.agentName === agentName)) {
+                this.disposeConversationAgent(agentName);
+            }
+        }
+    }
     /**
      * Convert an MCPL push event to a context message.
      */
@@ -1343,7 +1962,9 @@ export class AgentFramework {
         const id = this.addMessage('user', event.content, metadata);
         this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:push-event' });
         if (event.triggerInference) {
-            const targetAgents = event.targetAgents ?? [...this.agents.keys()];
+            // Default broadcast excludes conversation forks (channel-driven).
+            const targetAgents = event.targetAgents
+                ?? [...this.agents.keys()].filter((n) => !this.conversationAgentHomes.has(n));
             for (const agentName of targetAgents) {
                 this.pendingRequests.push({
                     agentName,
@@ -1425,6 +2046,11 @@ export class AgentFramework {
             // Both produce ContextInjection[] that get merged before inference.
             let injections;
             // Module gatherContext (fail-open, 5s timeout per module)
+            // NOTE: module injections are NOT channel-scoped — only the MCPL hook
+            // injections below pass through scopeInjectionsForAgent (channel
+            // context arrives via beforeInference hooks by adapter convention). A
+            // module that starts emitting per-channel context must scope it per
+            // agent itself, or conversation forks will see cross-channel content.
             try {
                 const moduleInjections = await this.moduleRegistry.gatherContext(agent.name);
                 if (moduleInjections.length > 0) {
@@ -1438,7 +2064,7 @@ export class AgentFramework {
             if (this.hookOrchestrator) {
                 try {
                     const hookParams = this.buildBeforeInferenceParams(agent, trigger);
-                    const hookInjections = await this.hookOrchestrator.beforeInference(hookParams);
+                    const hookInjections = this.scopeInjectionsForAgent(agent.name, await this.hookOrchestrator.beforeInference(hookParams));
                     if (hookInjections.length > 0) {
                         injections = injections ? [...injections, ...hookInjections] : hookInjections;
                     }
@@ -1483,6 +2109,13 @@ export class AgentFramework {
         const requestId = `${agent.name}-${startTime}-${Math.random().toString(36).slice(2, 8)}`;
         const myStreamId = agent.streamId;
         let hadToolCalls = 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();
+        if (typingChannel)
+            this.channelRegistry.startTyping(typingChannel);
         try {
             for await (const event of stream) {
                 switch (event.type) {
@@ -1491,8 +2124,21 @@ export class AgentFramework {
                             type: 'inference:tokens',
                             agentName: agent.name,
                             content: event.content,
+                            blockType: event.meta.type,
+                            blockIndex: event.meta.blockIndex,
                         });
                         break;
+                    case 'block': {
+                        const { event: phase, index, block } = event.event;
+                        this.emitTrace({
+                            type: 'inference:content_block',
+                            agentName: agent.name,
+                            phase,
+                            blockType: block.type,
+                            blockIndex: index,
+                        });
+                        break;
+                    }
                     case 'tool-calls': {
                         hadToolCalls = true;
                         this.emitTrace({
@@ -1500,13 +2146,26 @@ export class AgentFramework {
                             agentName: agent.name,
                             calls: event.calls.map((c) => ({ id: c.id, name: c.name, input: c.input })),
                         });
-                        // Build assistant content blocks from preamble text + tool_use blocks
-                        const assistantBlocks = [];
-                        if (event.context.preamble) {
-                            assistantBlocks.push({ type: 'text', text: event.context.preamble });
+                        // Build assistant content blocks for this round. Prefer the
+                        // membrane's verbatim round content (membrane ≥0.5.64): it
+                        // preserves native thinking / redacted_thinking blocks with
+                        // their signatures IN ORDER — the API requires signed thinking
+                        // to precede its tool_use in the same assistant turn, so
+                        // rebuilding from preamble + calls would break thinking+tools.
+                        const roundContent = event.context.roundContent;
+                        let assistantBlocks;
+                        if (roundContent && roundContent.length > 0) {
+                            assistantBlocks = roundContent.filter((b) => b.type !== 'tool_result');
                         }
-                        for (const c of event.calls) {
-                            assistantBlocks.push({ type: 'tool_use', id: c.id, name: c.name, input: c.input });
+                        else {
+                            // Fallback (older membrane / XML tool mode): preamble + calls
+                            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 });
+                            }
                         }
                         this.pendingAssistantBlocks.set(agent.name, assistantBlocks);
                         // Note: max_tokens truncation cannot produce tool-calls events here.
@@ -1550,21 +2209,25 @@ export class AgentFramework {
                                 const toolResultContent = readyState.toolResults.map(tc => ({
                                     type: 'tool_result',
                                     toolUseId: tc.id,
-                                    content: tc.result.isError ? (tc.result.error ?? 'Unknown error') : JSON.stringify(tc.result.data),
+                                    content: tc.result.isError
+                                        ? (tc.result.error ?? 'Unknown error')
+                                        : toolResultDataToHistoryString(tc.result.data),
                                     isError: tc.result.isError,
                                 }));
                                 agent.getContextManager().addMessage('user', toolResultContent);
                             }
                         }
                         // Add assistant response to context.
-                        // If we had tool calls, the tool_use blocks were already stored as
-                        // pendingAssistantBlocks and flushed when tool results arrived.
-                        // Only store trailing content (text after the last tool round) to
-                        // avoid double-storing tool_use blocks.
-                        const hadToolCalls = response.content.some((b) => b.type === 'tool_use' || b.type === 'tool_result');
-                        if (hadToolCalls) {
-                            // Filter to only trailing text/thinking blocks (no tool_use — those are already stored)
-                            const trailingContent = response.content.filter((block) => block.type !== 'tool_use' && block.type !== 'tool_result');
+                        // If we had tool calls, each round's blocks (thinking + text +
+                        // tool_use) were already stored as pendingAssistantBlocks and
+                        // flushed when tool results arrived. Only store TRAILING content
+                        // — blocks after the last tool block. A type-based filter would
+                        // double-store earlier rounds' text/thinking AND detach signed
+                        // thinking blocks from their tool_use turn (the API requires
+                        // thinking to precede tool_use in the same assistant turn).
+                        const lastToolIdx = response.content.reduce((last, b, i) => b.type === 'tool_use' || b.type === 'tool_result' ? i : last, -1);
+                        if (lastToolIdx >= 0) {
+                            const trailingContent = response.content.slice(lastToolIdx + 1);
                             if (trailingContent.length > 0) {
                                 agent.addAssistantResponse(trailingContent);
                             }
@@ -1660,6 +2323,19 @@ export class AgentFramework {
                             tokenUsage,
                             stopReason: response.stopReason,
                         });
+                        // Surface refusals instead of going silently mute: stderr line
+                        // (headless inference failures are otherwise under-logged) + an
+                        // emoji reaction on the triggering Discord message, keyed by the
+                        // refusal category from stop_details.
+                        if (response.stopReason === 'refusal') {
+                            // stop_details lives on the raw PROVIDER response
+                            // (response.raw is RawAccess = { request, response, headers }).
+                            const stopDetails = response.raw?.response?.stop_details;
+                            const category = stopDetails?.category ?? 'unknown';
+                            console.error(`[inference-refusal] agent=${agent.name} category=${category}` +
+                                (stopDetails?.explanation ? ` explanation=${stopDetails.explanation}` : ''));
+                            void this.reactToRefusal(agent.name, category);
+                        }
                         // Dispatch speech (and thoughts if any)
                         if (speechContent.length > 0 || thoughts.length > 0) {
                             const speechContext = {
@@ -1673,6 +2349,80 @@ export class AgentFramework {
                             };
                             await this.moduleRegistry.dispatchSpeech(agent.name, speechContent, speechContext);
                         }
+                        // Host-owned output routing (see LOCUS-ROUTING-DESIGN). On a
+                        // text-only turn (no tool calls => speechContent populated),
+                        // publish the agent's speech to the conversational locus — the
+                        // most recent incoming channel, tracked cross-surface in the
+                        // ChannelRegistry. This replaces discord-mcpl's per-surface sticky
+                        // auto-post. Tool-call turns produce `thoughts`, not `speech`, so
+                        // they are never routed here — which is precisely how the `think`
+                        // tool (and any explicit send tool) yields a silent turn.
+                        if (speechContent.length > 0 && this.channelRegistry) {
+                            const speechText = speechContent
+                                .map((b) => b.text)
+                                .join('\n')
+                                .trim();
+                            if (speechText) {
+                                try {
+                                    await this.channelRegistry.routeSpeech(agent.name, speechText);
+                                }
+                                catch (err) {
+                                    console.error('speech routing failed:', err);
+                                }
+                            }
+                        }
+                        else if (this.channelRegistry && hadToolCalls && allText.length > 0) {
+                            // Tool-call turn that also produced prose. Per design, route the
+                            // prose to the locus as a reply UNLESS the turn used an explicit
+                            // send/publish tool (channel_publish, *--send_message,
+                            // *--reply_message, *--send_dm) — already delivered, so routing
+                            // again would double-post. `think` and other non-sending tools
+                            // (shell, workspace, etc.) still let the agent speak in the same
+                            // turn. The global speech/thoughts split is left untouched
+                            // (module/TUI rendering unaffected) — this only governs what
+                            // reaches the channel.
+                            // Tools whose presence suppresses the trailing prose, for two
+                            // distinct reasons:
+                            //   - `skip_reply` — the agent EXPLICITLY chose not to reply this
+                            //     turn (the deliberate "stay silent" signal).
+                            //   - explicit delivery tools (channel_publish / *send_message /
+                            //     *reply_message / *send_dm) — already sent the message, so
+                            //     routing it again would double-post.
+                            // `think` is deliberately NOT here: it is silent *reasoning*, but
+                            // prose written after a think is the agent's actual reply and must
+                            // be delivered. (A think-only turn has no trailing prose and stays
+                            // silent via the `!t` check below.)
+                            const SILENCING = new Set([
+                                'skip_reply', 'channel_publish', 'send_message', 'reply_message', 'send_dm',
+                            ]);
+                            const bare = (n) => (n.includes('--') ? n.split('--').pop() : n);
+                            const toolNames = response.content
+                                .filter((b) => b.type === 'tool_use')
+                                .map((b) => b.name)
+                                .filter((n) => typeof n === 'string');
+                            const silenced = toolNames.some((n) => SILENCING.has(bare(n)));
+                            const t = allText
+                                .map((b) => b.text)
+                                .join('\n')
+                                .trim();
+                            if (silenced || !t) {
+                                console.error(`[routing] ${agent.name}: tool-call turn [${toolNames.join(', ') || 'none'}] -> NOT routed ` +
+                                    `(${silenced ? 'silencing tool / explicit send' : 'no prose'})`);
+                            }
+                            else {
+                                console.error(`[routing] ${agent.name}: tool-call turn [${toolNames.join(', ')}] -> routing trailing prose (${t.length} chars) as reply`);
+                                try {
+                                    await this.channelRegistry.routeSpeech(agent.name, t);
+                                }
+                                catch (err) {
+                                    console.error('speech routing failed:', err);
+                                }
+                            }
+                        }
+                        // NOTE: agent.reset() + onInferenceEnded() already ran above, BEFORE
+                        // dispatchSpeech (main's zombie-subagent fix, PR #32 — sync listeners
+                        // must see status === 'idle'). Locus routing is speech dispatch and
+                        // doesn't depend on the status field, so it correctly runs after.
                         break;
                     }
                     case 'error': {
@@ -1765,8 +2515,16 @@ export class AgentFramework {
             this.eventGate?.onInferenceEnded(agent.name);
         }
         finally {
+            // Stop the typing indicator on every exit path (complete, error,
+            // exhausted, abort) so it never sticks after the turn ends.
+            this.channelRegistry?.stopTyping();
             this.activeStreams.delete(agent.name);
             this.pendingAssistantBlocks.delete(agent.name);
+            // A conversation fork whose TTL closure turn just finished is done for
+            // good — dispose it so the agent map doesn't grow monotonically.
+            if (this.closingConversationAgents.has(agent.name)) {
+                this.disposeConversationAgent(agent.name);
+            }
             // Flush any deferred messages (e.g. if stream failed while tools were pending)
             if (this.deferredMessages.length > 0 && this.pendingAssistantBlocks.size === 0) {
                 const deferred = this.deferredMessages.splice(0);
@@ -1830,18 +2588,60 @@ export class AgentFramework {
         }
     }
     toMembraneToolResult(callId, afResult, maxChars) {
-        let content;
         if (afResult.isError) {
-            content = afResult.error ?? 'Unknown error';
+            return { toolUseId: callId, content: afResult.error ?? 'Unknown error', isError: true };
         }
-        else {
-            content = JSON.stringify(afResult.data);
-            if (maxChars && content.length > maxChars) {
-                content = safeSlice(content, 0, maxChars)
-                    + '\n\n[truncated — original was ' + content.length + ' chars]';
+        // MCPL tool results arrive as `data: McpToolResultContent[]` — preserve image
+        // blocks natively rather than JSON-stringifying them away. Anything else
+        // (objects, scalars) falls through to JSON. The error path was handled
+        // above, so isError is always false on these return paths.
+        const blocks = this.tryNativeToolResultContent(afResult.data, maxChars);
+        if (blocks) {
+            return { toolUseId: callId, content: blocks, isError: false };
+        }
+        let content = JSON.stringify(afResult.data);
+        if (maxChars && content.length > maxChars) {
+            content = safeSlice(content, 0, maxChars)
+                + '\n\n[truncated — original was ' + content.length + ' chars]';
+        }
+        return { toolUseId: callId, content, isError: false };
+    }
+    /**
+     * If `data` is an MCP tool-result content array carrying at least one image,
+     * convert to Membrane's native ToolResultContentBlock[]. Returns null when
+     * the array is text-only (let JSON path handle it; saves a code path).
+     * `maxChars`, when provided, caps each accompanying text block so an image
+     * inlined alongside an enormous text payload can't blow the context.
+     */
+    tryNativeToolResultContent(data, maxChars) {
+        if (!Array.isArray(data))
+            return null;
+        let hasImage = false;
+        const blocks = [];
+        for (const raw of data) {
+            if (!raw || typeof raw !== 'object')
+                return null;
+            const b = raw;
+            if (b.type === 'text' && typeof b.text === 'string') {
+                let text = b.text;
+                if (maxChars && text.length > maxChars) {
+                    text = safeSlice(text, 0, maxChars)
+                        + '\n\n[truncated — original was ' + text.length + ' chars]';
+                }
+                blocks.push({ type: 'text', text });
+            }
+            else if (b.type === 'image' && typeof b.data === 'string' && typeof b.mimeType === 'string') {
+                hasImage = true;
+                blocks.push({
+                    type: 'image',
+                    source: { type: 'base64', data: b.data, mediaType: b.mimeType },
+                });
+            }
+            else {
+                return null; // unknown shape — bail to JSON path
             }
         }
-        return { toolUseId: callId, content, isError: afResult.isError };
+        return hasImage ? blocks : null;
     }
     getMaxToolResultChars(agent) {
         const strategy = agent.getContextManager().getStrategy();
@@ -1921,11 +2721,24 @@ export class AgentFramework {
             this.dispatchChannelToolCall(agentName, enrichedCall);
             return;
         }
-        // Route gate:status tool
-        if (enrichedCall.name === 'gate:status' && this.eventGate) {
+        // Route gate_status tool
+        if (enrichedCall.name === 'gate_status' && this.eventGate) {
             this.dispatchGateToolCall(agentName, enrichedCall);
             return;
         }
+        // Route sleep / wake tools
+        if ((enrichedCall.name === 'sleep' || enrichedCall.name === 'wake') && this.eventGate) {
+            this.dispatchSleepToolCall(agentName, enrichedCall);
+            return;
+        }
+        // Route synthesized 'think' (private reasoning) and 'skip_reply' (deliberate
+        // stay-silent) tools — handled by the channel registry like the other
+        // synthesized channel tools, but they aren't `channel_`-prefixed so they
+        // need an explicit route here.
+        if ((enrichedCall.name === 'think' || enrichedCall.name === 'skip_reply') && this.channelRegistry) {
+            this.dispatchChannelToolCall(agentName, enrichedCall);
+            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;
@@ -2059,6 +2872,24 @@ export class AgentFramework {
         };
     }
     emitTrace(event) {
+        // Centralized inference-health observability. Every terminal failure path
+        // funnels through an `inference:exhausted` trace and every successful model
+        // response through `inference:completed`, so intercepting here is the one
+        // place that reliably sees all outcomes regardless of which code path
+        // produced them. In headless/daemon mode no trace client is attached, so
+        // without this the only durable record of a failed inference is a field in
+        // llm-calls.jsonl — invisible to operator, agent, and monitoring.
+        if (event.type === 'inference:exhausted') {
+            this.noteInferenceExhausted(event.agentName ?? 'unknown', event.error ?? 'unknown error');
+        }
+        else if (event.type === 'inference:completed') {
+            // A successful response — even mid-turn between tool calls — proves the
+            // agent isn't hard-down; clear its consecutive-failure streak.
+            const name = event.agentName;
+            if (name && this.consecutiveInferenceFailures.get(name)) {
+                this.consecutiveInferenceFailures.set(name, 0);
+            }
+        }
         const traceEvent = {
             ...event,
             timestamp: Date.now(),
@@ -2072,6 +2903,49 @@ export class AgentFramework {
             }
         }
     }
+    /**
+     * Handle a fully-exhausted inference (the agent could not produce a response
+     * this turn, after retries). Severity here is high — the agent can't think
+     * at all — yet historically the only durable record was a buried field in
+     * llm-calls.jsonl. This surfaces it three ways:
+     *
+     *   1. stderr  — always, with the underlying API reason. The place an
+     *      operator greps; previously empty in headless mode.
+     *   2. chronicle marker — a `[inference-failed]` message so the agent itself
+     *      learns its turn failed and why (otherwise it's an experiential blank,
+     *      indistinguishable from "not addressed"). addMessage does NOT request
+     *      inference, so this never causes a retry/wake loop.
+     *   3. escalation — after N consecutive failures the agent is hard-down;
+     *      log that loudly (a repeated identical failure is the textbook signal).
+     */
+    noteInferenceExhausted(agentName, reason) {
+        const streak = (this.consecutiveInferenceFailures.get(agentName) ?? 0) + 1;
+        this.consecutiveInferenceFailures.set(agentName, streak);
+        // (1) Durable stderr line — works in headless/daemon mode with no client.
+        console.error(`[inference-failed] agent=${agentName} consecutive=${streak}: ${reason}`);
+        // (2) Agent-facing chronicle marker (no inference triggered → no loop).
+        const agent = this.agents.get(agentName);
+        if (agent) {
+            try {
+                agent.getContextManager().addMessage('user', [{
+                        type: 'text',
+                        text: `[inference-failed] Your previous turn did not complete: the model ` +
+                            `call failed and produced no response, so nothing was sent. Reason: ` +
+                            `${reason}. If this recurs with the same cause, change approach ` +
+                            `rather than retrying identically (e.g. drop an oversized attachment ` +
+                            `or an unsupported setting).`,
+                    }], { system: true, kind: 'inference-failed', reason, consecutive: streak });
+            }
+            catch (err) {
+                console.error(`[inference-failed] could not record chronicle marker for ${agentName}:`, err);
+            }
+        }
+        // (3) Hard-down escalation on repeated identical failure.
+        if (streak >= this.inferenceFailureEscalationThreshold) {
+            console.error(`[inference-hard-down] agent=${agentName} has FAILED ${streak} consecutive ` +
+                `inferences — it cannot complete a turn. Last reason: ${reason}`);
+        }
+    }
     // ==========================================================================
     // MCPL subsystem wiring
     // ==========================================================================
@@ -2112,6 +2986,23 @@ export class AgentFramework {
                 }
             },
             shouldTriggerInference: triggerFilter,
+            // A text-only turn whose speech couldn't be delivered must not vanish
+            // silently: record a `[discord-send-failed]` marker in chronicle so the
+            // agent sees, on her next turn, that her reply never reached the human.
+            // addMessage() alone does not request inference, so this never wakes
+            // her (matching the `discord-send-failed-skip` gate intent: context
+            // yes, wake no).
+            onRouteFailure: ({ channelId, reason, textLen }) => {
+                try {
+                    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.`,
+                        }], { system: true, kind: 'discord-send-failed', channelId: channelId ?? '', reason });
+                }
+                catch (err) {
+                    console.error('onRouteFailure: failed to record send-failure marker:', err);
+                }
+            },
         });
         // Host capabilities advertised during the MCP handshake
         const hostCapabilities = {
@@ -2228,6 +3119,19 @@ export class AgentFramework {
         connection.on('channels-incoming', (params, responder) => {
             this.channelRegistry?.handleIncoming(connection.id, params, responder);
         });
+        // Handle host-level admin commands from a surface (e.g. Discord /undo)
+        connection.on('host-command', async (params, responder) => {
+            if (!responder)
+                return;
+            try {
+                const result = await this.handleHostCommand(connection.id, params ?? {});
+                responder.respond(result);
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                responder.respondError(-32603, err.message);
+            }
+        });
         // Handle dynamic tool list changes (notifications/tools/list_changed)
         connection.on('tools-list-changed', () => {
             this.handleToolsListChanged(connection.id);
@@ -2384,11 +3288,22 @@ export class AgentFramework {
                     this.checkpointManager.recordCheckpoint(serverId, fs, result.state);
                 }
             }
-            // Convert MCP tool result to framework ToolResult
+            // 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
+            // through so toMembraneToolResult can preserve image blocks natively.
+            // Text-only results still collapse to a joined string for backward
+            // compatibility with callers that expect data to be string-ish.
             const textContent = result.content
                 ?.filter((c) => c.type === 'text' && c.text)
                 .map((c) => c.text)
                 .join('\n');
+            const hasNonText = result.content?.some((c) => c.type !== 'text');
+            const data = result.isError
+                ? undefined
+                : hasNonText
+                    ? result.content
+                    : (textContent || undefined);
             this.pushEvent({
                 type: 'tool-result',
                 callId: call.id,
@@ -2396,7 +3311,7 @@ export class AgentFramework {
                 moduleName: `mcpl:${serverId}`,
                 result: {
                     success: !result.isError,
-                    data: result.isError ? undefined : textContent || undefined,
+                    data,
                     error: result.isError ? (textContent || 'Tool call failed') : undefined,
                     isError: result.isError ?? false,
                 },
@@ -2421,6 +3336,42 @@ export class AgentFramework {
      * Dispatch a synthesized channel tool call.
      */
     dispatchChannelToolCall(agentName, call) {
+        // Conversation forks act only on their home channel. channel_publish and
+        // channel_close default a missing channelId to home and reject foreign
+        // ones; channel_open is rejected outright — opening channels mutates
+        // framework-global state (the open-channel set every agent's injections
+        // are scoped against), which is not a fork's call to make.
+        const home = this.conversationAgentHomes.get(agentName);
+        if (home) {
+            const reject = (error) => {
+                this.emitTrace({
+                    type: 'tool:failed', module: 'channels', tool: call.name, callId: call.id,
+                    error: `conversation agent ${agentName}: ${error}`,
+                });
+                this.pushEvent({
+                    type: 'tool-result',
+                    callId: call.id,
+                    agentName,
+                    moduleName: 'channels',
+                    result: { success: false, error, isError: true },
+                });
+            };
+            if (call.name === 'channel_open') {
+                reject(`This conversation is bound to channel ${home}; conversation agents cannot open channels.`);
+                return;
+            }
+            if (call.name === 'channel_publish' || call.name === 'channel_close') {
+                const input = (call.input ?? {});
+                if (!input.channelId) {
+                    call = { ...call, input: { ...input, channelId: home } };
+                }
+                else if (input.channelId !== home) {
+                    const verb = call.name === 'channel_publish' ? 'publishing to' : 'closing';
+                    reject(`This conversation is bound to channel ${home}; ${verb} ${input.channelId} is not allowed.`);
+                    return;
+                }
+            }
+        }
         this.emitTrace({ type: 'tool:started', module: 'channels', tool: call.name, callId: call.id, input: call.input });
         const startTime = Date.now();
         this.channelRegistry.handleChannelToolCall(call.name, call.input)
@@ -2447,6 +3398,45 @@ export class AgentFramework {
             });
         });
     }
+    /**
+     * Handle the synthesized `sleep` / `wake` tools. `sleep` arms the gate's
+     * suppression window, optionally announces in the sticky channel, and ends
+     * the turn (the agent goes idle immediately). `wake` clears sleep.
+     */
+    dispatchSleepToolCall(agentName, call) {
+        this.emitTrace({ type: 'tool:started', module: 'gate', tool: call.name, callId: call.id, input: call.input });
+        const gate = this.eventGate;
+        const input = (call.input ?? {});
+        const finish = (result) => {
+            this.emitTrace({ type: 'tool:completed', module: 'gate', tool: call.name, callId: call.id, durationMs: 0 });
+            this.pushEvent({ type: 'tool-result', callId: call.id, agentName, moduleName: 'gate', result });
+        };
+        if (call.name === 'wake') {
+            const was = gate.clearSleep();
+            finish({ success: true, data: { woke: was } });
+            return;
+        }
+        const seconds = Number(input.seconds);
+        if (!Number.isFinite(seconds) || seconds <= 0) {
+            finish({ success: false, error: 'sleep: `seconds` must be a positive number', isError: true });
+            return;
+        }
+        const { until } = gate.setSleep(seconds, input.message);
+        const announce = input.announce !== false; // default true
+        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).
+        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);
+            });
+        }
+        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.
+        finish({ success: true, data: { sleepingFor: human, until }, endTurn: true });
+    }
     dispatchGateToolCall(agentName, call) {
         this.emitTrace({ type: 'tool:started', module: 'gate', tool: call.name, callId: call.id, input: call.input });
         const startTime = Date.now();