@animalabs/agent-framework 0.5.6 → 0.5.7

package/src/framework.ts

@@ -1,6 +1,6 @@
 import { join } from 'node:path';
 import { JsStore } from '@animalabs/chronicle';
-import type { Membrane, ContentBlock, NormalizedRequest, YieldingStream, ToolResult as MembraneToolResult } from '@animalabs/membrane';
+import type { Membrane, ContentBlock, NormalizedRequest, YieldingStream, ToolResult as MembraneToolResult, ToolResultContentBlock } from '@animalabs/membrane';
 import { MembraneError } from '@animalabs/membrane';
 import { ContextManager, PassthroughStrategy } from '@animalabs/context-manager';
 import type {
@@ -50,7 +50,9 @@ import { HookOrchestrator } from './mcpl/hook-orchestrator.js';
 import { PushHandler, type McplPushEvent } 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';
@@ -74,6 +76,7 @@ import type {
 import type { ContextInjection } from '@animalabs/context-manager';
 
 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';
@@ -180,6 +183,24 @@ function extractGateFields(event: ProcessEvent): {
 /**
  * The main agent framework.
  */
+/** Params for a `host/command` request from an MCPL surface server. */
+interface HostCommandParams {
+  command?: string;
+  agentName?: string;
+  turns?: number;
+  /** Message-granular undo: branch the chronicle so the last N messages
+   *  (regardless of participant) are no longer on the active branch.
+   *  Mutually exclusive with `turns`. */
+  messages?: number;
+  /** For the `hide` command: Discord message id of the (first) message to
+   *  remove. With `toMessageId`, removes the inclusive range between them. */
+  fromMessageId?: string;
+  /** For the `hide` command: Discord message id ending an inclusive range. */
+  toMessageId?: string;
+  requesterId?: string;
+  requesterName?: string;
+}
+
 export class AgentFramework {
   private store: JsStore;
   private ownsStore: boolean;
@@ -199,6 +220,12 @@ export class AgentFramework {
   private processLoggingBroadcast: boolean;
   private activeStreams: Map<string, Promise<void>> = new Map();
   private pendingAssistantBlocks: Map<string, ContentBlock[]> = new Map();
+  /** Per-agent count of consecutive exhausted inferences (reset on any success).
+   *  Drives hard-down escalation — see noteInferenceExhausted. */
+  private consecutiveInferenceFailures: Map<string, number> = new Map();
+  /** N consecutive failed inferences ⇒ the agent is treated as hard-down and
+   *  escalated loudly to stderr. */
+  private readonly inferenceFailureEscalationThreshold = 3;
   /** Name of the primary (non-ephemeral) agent for routing framework messages. */
   private primaryAgentName: string | null = null;
 
@@ -219,6 +246,22 @@ export class AgentFramework {
   private inferenceRouter: InferenceRouter | null = null;
   private channelRegistry: ChannelRegistry | null = null;
   private checkpointManager: CheckpointManager | null = null;
+  /** Per-channel conversation routing (null unless config.conversations set). */
+  private conversationRouter: ConversationRouter | null = null;
+  /** Agent configs by name — fork agents are built from the template's config. */
+  private agentConfigs: Map<string, AgentConfig> = 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.
+   */
+  private conversationAgentHomes: Map<string, string> = new Map();
+  /** Last idle-TTL sweep timestamp. */
+  private lastConversationSweep = 0;
+
+  /** Forks whose TTL closure turn has been queued — disposed (removed from
+   * agents/agentConfigs/conversationAgentHomes) when their stream ends. */
+  private closingConversationAgents: Set<string> = new Set();
   private mcplTools: import('./types/index.js').ToolDefinition[] = [];
   private mcplToolRefreshInFlight = false;
   private mcplToolRefreshPending = false;
@@ -265,6 +308,7 @@ export class AgentFramework {
       getMessage: (id) => this.getMessage(id),
       queryMessages: (filter) => this.queryMessages(filter),
       pushEvent: (event) => this.pushEvent(event),
+      onTrace: (listener) => this.onTrace(listener),
     });
   }
 
@@ -352,6 +396,35 @@ export class AgentFramework {
       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) as
+          { generations?: Record<string, number> } | null;
+        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
@@ -361,6 +434,7 @@ export class AgentFramework {
       framework.eventGate = new EventGate({
         configPath,
         initialConfig: config.gate.config,
+        privilegedUsersPath: config.gate.privilegedUsersPath,
         emitTrace: (e) => framework.emitTrace(e as { type: TraceEvent['type']; [key: string]: unknown }),
         addMessage: (p, c, m) => framework.addMessage(p, c, m as MessageMetadata),
         requestInference: (agentName, reason, source) => {
@@ -486,8 +560,15 @@ export class AgentFramework {
   /**
    * Add a trace event listener for observability.
    */
-  onTrace(listener: TraceEventListener): void {
+  onTrace(listener: TraceEventListener): () => void {
     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);
+    };
   }
 
   /**
@@ -540,6 +621,14 @@ export class AgentFramework {
     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(): ConversationRouter | null {
+    return this.conversationRouter;
+  }
+
   /**
    * Abort an in-flight inference for an agent.
    */
@@ -568,13 +657,88 @@ export class AgentFramework {
   getAllTools(): import('./types/index.js').ToolDefinition[] {
     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: string,
+    opts?: { injections?: boolean }
+  ): Promise<NormalizedRequest> {
+    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: ContextInjection[] | undefined;
+
+    // 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.
    */
@@ -840,6 +1004,313 @@ 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). */
+  private static readonly SLEEP_TOOLS: import('./types/index.js').ToolDefinition[] = [
+    {
+      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 🛑. */
+  private static readonly REFUSAL_REACTIONS: Record<string, string> = {
+    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.
+   */
+  private async reactToRefusal(agentName: string, category: string): Promise<void> {
+    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).
+   */
+  private async handleHostCommand(
+    serverId: string,
+    params: HostCommandParams,
+  ): Promise<{
+    ok: boolean;
+    error?: string;
+    undone?: number;
+    requested?: number;
+    messagesRemoved?: number;
+    hidden?: number;
+    /** For `hide`: the Discord (channelId, messageId) of each removed message
+     *  that carried one — so the surface can mark them with a reaction. */
+    hiddenRefs?: Array<{ channelId: string; messageId: string }>;
+    lastVisible?: { participant?: string; role?: string; preview?: string } | null;
+  }> {
+    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: string) =>
+        all.findIndex((m) => String((m.metadata as { messageId?: unknown } | undefined)?.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: number, hi: number) => {
+        const refs: Array<{ channelId: string; messageId: string }> = [];
+        for (let i = lo; i <= hi; i++) {
+          const md = all[i].metadata as { messageId?: unknown; channelId?: unknown } | undefined;
+          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 as { materializeMount: (m: string) => Promise<void> })
+          .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.
+   */
+  private async lastVisiblePreview(
+    agentName: string,
+  ): Promise<{ participant?: string; role?: string; preview?: string } | null> {
+    try {
+      const preview = await this.previewActivation(agentName);
+      const messages = (preview as { messages?: unknown[] }).messages ?? [];
+      const last = messages[messages.length - 1] as
+        | { role?: string; participant?: string; content?: unknown }
+        | undefined;
+      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 as { text: unknown }).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?: InferenceLogQuery): InferenceLogQueryResult {
     const limit = query?.limit ?? 50;
     const offset = query?.offset ?? 0;
@@ -1307,6 +1778,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) {
@@ -1334,6 +1806,9 @@ export class AgentFramework {
       await this.handleProcessEvent(event);
     }
 
+    // Close idle conversation forks (no-op unless conversations configured)
+    this.sweepExpiredConversations();
+
     // Check for inference requests
     await this.processInferenceRequests();
 
@@ -1392,25 +1867,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: ContentBlock[] = currentState.toolResults.map(tc => {
-            let content: string;
-            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' as const,
-              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: ContentBlock[] = currentState.toolResults.map(tc => ({
+            type: 'tool_result' as const,
+            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.
@@ -1482,7 +1950,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 as unknown as {
+      await this.handleMcplChannelIncoming(event as unknown as {
         type: 'mcpl:channel-incoming';
         serverId: string;
         channelId: string;
@@ -1578,9 +2046,11 @@ 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) {
@@ -1605,7 +2075,7 @@ export class AgentFramework {
    * Convert an incoming MCPL channel message to a context message.
    * This replaces the old MCPLModule.onProcess() message conversion.
    */
-  private handleMcplChannelIncoming(event: {
+  private async handleMcplChannelIncoming(event: {
     type: 'mcpl:channel-incoming';
     serverId: string;
     channelId: string;
@@ -1616,7 +2086,7 @@ export class AgentFramework {
     timestamp: string;
     metadata?: Record<string, unknown>;
     triggerInference?: boolean;
-  }): void {
+  }): Promise<void> {
     const metadata: Record<string, unknown> = {
       ...event.metadata,
       channelId: event.channelId,
@@ -1627,6 +2097,14 @@ 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' });
 
@@ -1642,6 +2120,261 @@ 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.
+   */
+  private async routeConversationIncoming(
+    event: {
+      serverId: string;
+      channelId: string;
+      messageId: string;
+      author: { id: string; name: string };
+      content: ContentBlock[];
+      metadata?: Record<string, unknown>;
+      triggerInference?: boolean;
+    },
+    messageMetadata: Record<string, unknown>,
+  ): Promise<void> {
+    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: Agent | undefined;
+    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.
+   */
+  private async createConversationAgent(name: string, channelId: string): Promise<Agent> {
+    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: AgentConfig = { ...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()). */
+  private persistConversationRouterState(): void {
+    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.
+   */
+  private disposeConversationAgent(agentName: string): void {
+    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.
+   */
+  private scopeInjectionsForAgent(
+    agentName: string,
+    injections: ContextInjection[],
+  ): ContextInjection[] {
+    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.
+   */
+  private sweepExpiredConversations(): void {
+    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.
    */
@@ -1658,7 +2391,9 @@ export class AgentFramework {
     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,
@@ -1753,6 +2488,11 @@ export class AgentFramework {
       let injections: ContextInjection[] | undefined;
 
       // 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) {
@@ -1766,7 +2506,10 @@ 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;
           }
@@ -1819,6 +2562,13 @@ export class AgentFramework {
     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) {
@@ -1852,13 +2602,27 @@ export class AgentFramework {
               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: ContentBlock[] = [];
-            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 as Record<string, unknown> });
+            // 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 as { roundContent?: ContentBlock[] }).roundContent;
+            let assistantBlocks: ContentBlock[];
+            if (roundContent && roundContent.length > 0) {
+              assistantBlocks = roundContent.filter(
+                (b) => b.type !== 'tool_result'
+              );
+            } 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 as Record<string, unknown> });
+              }
             }
             this.pendingAssistantBlocks.set(agent.name, assistantBlocks);
 
@@ -1909,7 +2673,9 @@ export class AgentFramework {
                 const toolResultContent: ContentBlock[] = readyState.toolResults.map(tc => ({
                   type: 'tool_result' as const,
                   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);
@@ -1917,18 +2683,20 @@ export class AgentFramework {
             }
 
             // 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: ContentBlock) => b.type === 'tool_use' || b.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: number, b: ContentBlock, i: number) =>
+                b.type === 'tool_use' || b.type === 'tool_result' ? i : last,
+              -1
             );
-            if (hadToolCalls) {
-              // Filter to only trailing text/thinking blocks (no tool_use — those are already stored)
-              const trailingContent = response.content.filter(
-                (block: ContentBlock) => block.type !== 'tool_use' && block.type !== 'tool_result'
-              );
+            if (lastToolIdx >= 0) {
+              const trailingContent = response.content.slice(lastToolIdx + 1);
               if (trailingContent.length > 0) {
                 agent.addAssistantResponse(trailingContent);
               }
@@ -2034,6 +2802,24 @@ export class AgentFramework {
               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 as {
+                stop_details?: { category?: string; explanation?: string };
+              } | undefined)?.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: SpeechContext = {
@@ -2052,6 +2838,81 @@ export class AgentFramework {
               );
             }
 
+            // 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 as ContentBlock & { type: 'text' }).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: string) => (n.includes('--') ? n.split('--').pop()! : n);
+              const toolNames = response.content
+                .filter((b) => b.type === 'tool_use')
+                .map((b) => (b as unknown as { name?: string }).name)
+                .filter((n): n is string => typeof n === 'string');
+              const silenced = toolNames.some((n) => SILENCING.has(bare(n)));
+              const t = allText
+                .map((b) => (b as ContentBlock & { type: 'text' }).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;
           }
 
@@ -2147,9 +3008,18 @@ export class AgentFramework {
       agent.reset();
       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);
@@ -2216,17 +3086,57 @@ export class AgentFramework {
   }
 
   private toMembraneToolResult(callId: string, afResult: ToolResult, maxChars?: number): MembraneToolResult {
-    let content: string;
     if (afResult.isError) {
-      content = afResult.error ?? 'Unknown error';
-    } else {
-      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: afResult.error ?? 'Unknown error', isError: true };
+    }
+    // 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.
+   */
+  private tryNativeToolResultContent(data: unknown, maxChars?: number): ToolResultContentBlock[] | null {
+    if (!Array.isArray(data)) return null;
+    let hasImage = false;
+    const blocks: ToolResultContentBlock[] = [];
+    for (const raw of data) {
+      if (!raw || typeof raw !== 'object') return null;
+      const b = raw as { type?: unknown; text?: unknown; data?: unknown; mimeType?: unknown };
+      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;
   }
 
   private getMaxToolResultChars(agent: Agent): number | undefined {
@@ -2320,12 +3230,27 @@ export class AgentFramework {
       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;
@@ -2479,6 +3404,27 @@ export class AgentFramework {
   }
 
   private emitTrace(event: { type: TraceEvent['type']; [key: string]: unknown }): void {
+    // 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 as string) ?? 'unknown',
+        (event.error as string) ?? '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 as string | undefined;
+      if (name && this.consecutiveInferenceFailures.get(name)) {
+        this.consecutiveInferenceFailures.set(name, 0);
+      }
+    }
+
     const traceEvent = {
       ...event,
       timestamp: Date.now(),
@@ -2493,6 +3439,59 @@ 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).
+   */
+  private noteInferenceExhausted(agentName: string, reason: string): void {
+    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
   // ==========================================================================
@@ -2563,6 +3562,26 @@ 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);
+          }
+        },
       },
     );
 
@@ -2716,6 +3735,21 @@ export class AgentFramework {
       this.channelRegistry?.handleIncoming(connection.id, params, responder as never);
     });
 
+    // Handle host-level admin commands from a surface (e.g. Discord /undo)
+    connection.on('host-command', async (
+      params: HostCommandParams,
+      responder?: { respond: (result: unknown) => void; respondError: (code: number, message: string) => void },
+    ) => {
+      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);
@@ -2887,11 +3921,22 @@ export class AgentFramework {
           }
         }
 
-        // 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',
@@ -2900,7 +3945,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,
           },
@@ -2927,6 +3972,43 @@ export class AgentFramework {
    * Dispatch a synthesized channel tool call.
    */
   private dispatchChannelToolCall(agentName: string, call: ToolCall): void {
+    // 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: string): void => {
+        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 ?? {}) as { channelId?: string };
+        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();
 
@@ -2955,6 +4037,53 @@ 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.
+   */
+  private dispatchSleepToolCall(agentName: string, call: ToolCall): void {
+    this.emitTrace({ type: 'tool:started', module: 'gate', tool: call.name, callId: call.id, input: call.input });
+    const gate = this.eventGate!;
+    const input = (call.input ?? {}) as { seconds?: number; announce?: boolean; message?: string };
+
+    const finish = (result: ToolResult) => {
+      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 });
+  }
+
   private dispatchGateToolCall(agentName: string, call: ToolCall): void {
     this.emitTrace({ type: 'tool:started', module: 'gate', tool: call.name, callId: call.id, input: call.input });
     const startTime = Date.now();