@animalabs/agent-framework 0.5.6 → 0.5.7

package/src/mcpl/conversation-router.ts

@@ -0,0 +1,284 @@
+/**
+ * ConversationRouter — routes incoming channel messages to per-channel
+ * conversation agents ("forks") instead of the primary conversation.
+ *
+ * The router is a lookup table plus policy — deliberately no LLM in the
+ * routing path. The framework consults it from handleMcplChannelIncoming:
+ *
+ * - A channel with an active binding routes to its bound agent. Whether the
+ *   message *triggers* inference (vs. just landing in the fork's context) is
+ *   a separate per-channel-kind rule: in a busy channel everything is case
+ *   input but only mentions demand a reply.
+ * - An unbound channel binds (→ the framework spawns a fork from the
+ *   template/trunk agent) when the bind rule matches: by default any message
+ *   in a DM, an explicit bot mention in a channel (`metadata.mentioned`,
+ *   set server-side by the platform adapters).
+ * - Everything else is left unrouted and dropped by the framework — the
+ *   trunk is a dormant template, not a listener.
+ *
+ * Bindings expire after an idle TTL. Expiry runs a final closure turn on the
+ * fork (see framework wiring) and unbinds; the next qualifying message on
+ * that channel spawns a *fresh* fork (generation + 1) from the current
+ * trunk, so handbook/template updates propagate between engagements.
+ *
+ * The binding table is in-memory — bindings are re-established by the next
+ * qualifying message after a restart. The generation counters, by contrast,
+ * are persisted by the framework (exportGenerations/hydrateGenerations):
+ * a restarted host must NOT reuse generation 1's agent name, or it would
+ * reopen the previous engagement's Chronicle namespace and re-seed the
+ * template context on top of the old history.
+ */
+
+import type { ContextStrategy } from '@animalabs/context-manager';
+import type { ChannelDescriptor } from './types.js';
+
+// ============================================================================
+// Config & types
+// ============================================================================
+
+/** When an unbound channel acquires a fork. */
+export type BindRule = 'always' | 'mention' | 'never';
+
+/** When a message on a bound channel triggers inference (it always lands in
+ * the fork's context). */
+export type TriggerRule = 'always' | 'mention';
+
+/** How a channel is classified for bind/trigger rules. Group DMs are their
+ * own kind: the bot was added deliberately (so they bind like DMs) but they
+ * host multi-human chatter (so they trigger like channels by default —
+ * inferring on every message of a four-human group DM is a firehose). */
+export type ChannelKind = 'dm' | 'groupDm' | 'channel';
+
+export interface ConversationRouterConfig {
+  /** Agent whose context seeds new forks (the "trunk"/warm checkpoint). */
+  templateAgent: string;
+
+  /** Bind rules per channel kind.
+   * Defaults: dm 'always', groupDm 'always', channel 'mention'. */
+  bind?: { dm?: BindRule; groupDm?: BindRule; channel?: BindRule };
+
+  /** Trigger rules per channel kind.
+   * Defaults: dm 'always', groupDm 'mention', channel 'mention'. */
+  trigger?: { dm?: TriggerRule; groupDm?: TriggerRule; channel?: TriggerRule };
+
+  /** Idle time before a binding expires and the fork is closed. Default 12h. */
+  idleTtlMs?: number;
+
+  /** Final system-initiated user message sent to a fork on expiry. */
+  closurePrompt?: string;
+
+  /** Prefix for generated fork agent names. Default 'conversation'. */
+  agentPrefix?: string;
+
+  /**
+   * Fresh compression strategy per fork. Strategy instances are stateful and
+   * must not be shared between ContextManagers, so the template agent's own
+   * strategy is never reused — without a factory, forks get passthrough.
+   */
+  strategyFactory?: () => ContextStrategy;
+}
+
+export interface ConversationBinding {
+  channelId: string;
+  agentName: string;
+  /** Engagement counter per channel — fresh forks get a new generation. */
+  generation: number;
+  boundAt: number;
+  lastActivity: number;
+}
+
+/** The facts route() needs about one incoming message, pre-extracted by the
+ * framework so the router stays free of event-shape knowledge. */
+export interface IncomingMessageFacts {
+  channelId: string;
+  /** Personal mention of the bot (metadata.mentioned from the adapter). */
+  mentioned: boolean;
+  /** Channel classification (see classifyChannel). */
+  kind: ChannelKind;
+  /** Clock injection for tests; defaults to Date.now(). */
+  now?: number;
+}
+
+export type RoutingDecision =
+  /** Channel already has a fork — deliver there. */
+  | { kind: 'existing'; agentName: string; trigger: boolean }
+  /** Bind rule matched — framework should spawn this agent, then bind(). */
+  | { kind: 'spawn'; agentName: string; generation: number; trigger: boolean }
+  /** No binding and bind rule didn't match — drop. */
+  | { kind: 'unbound' };
+
+const DEFAULT_IDLE_TTL_MS = 12 * 60 * 60 * 1000;
+
+export const DEFAULT_CLOSURE_PROMPT =
+  '[system] This engagement is closing due to inactivity. Finalize your ' +
+  'work: post any promised results to the channel and record outstanding ' +
+  'threads as unresolved. Do not ask follow-up questions.';
+
+// ============================================================================
+// ConversationRouter
+// ============================================================================
+
+export class ConversationRouter {
+  private config: ConversationRouterConfig;
+
+  /** Active bindings, keyed by channelId. */
+  private bindings = new Map<string, ConversationBinding>();
+
+  /** Engagement counter per channel — survives unbind, so a re-bound channel
+   * gets a distinct fork agent name. */
+  private generations = new Map<string, number>();
+
+  constructor(config: ConversationRouterConfig) {
+    this.config = config;
+  }
+
+  get templateAgent(): string {
+    return this.config.templateAgent;
+  }
+
+  get closurePrompt(): string {
+    return this.config.closurePrompt ?? DEFAULT_CLOSURE_PROMPT;
+  }
+
+  get idleTtlMs(): number {
+    return this.config.idleTtlMs ?? DEFAULT_IDLE_TTL_MS;
+  }
+
+  get strategyFactory(): (() => ContextStrategy) | undefined {
+    return this.config.strategyFactory;
+  }
+
+  /**
+   * Decide where an incoming message goes. Pure read except for refreshing
+   * lastActivity on an existing binding — a 'spawn' decision does NOT create
+   * the binding; the framework calls bind() after the fork agent actually
+   * exists, so a failed spawn doesn't leave a dangling route.
+   */
+  route(facts: IncomingMessageFacts): RoutingDecision {
+    const now = facts.now ?? Date.now();
+    const existing = this.bindings.get(facts.channelId);
+
+    if (existing) {
+      existing.lastActivity = now;
+      return {
+        kind: 'existing',
+        agentName: existing.agentName,
+        trigger: this.shouldTrigger(facts),
+      };
+    }
+
+    const bindRule = this.config.bind?.[facts.kind]
+      ?? (facts.kind === 'channel' ? 'mention' : 'always');
+
+    const binds =
+      bindRule === 'always' || (bindRule === 'mention' && facts.mentioned);
+    if (!binds) {
+      return { kind: 'unbound' };
+    }
+
+    const generation = (this.generations.get(facts.channelId) ?? 0) + 1;
+    return {
+      kind: 'spawn',
+      agentName: this.forkAgentName(facts.channelId, generation),
+      generation,
+      trigger: this.shouldTrigger(facts),
+    };
+  }
+
+  /**
+   * Record a binding after the framework successfully spawned the fork.
+   * Returns the new binding.
+   */
+  bind(channelId: string, agentName: string, generation: number, now = Date.now()): ConversationBinding {
+    this.generations.set(channelId, generation);
+    const binding: ConversationBinding = {
+      channelId,
+      agentName,
+      generation,
+      boundAt: now,
+      lastActivity: now,
+    };
+    this.bindings.set(channelId, binding);
+    return binding;
+  }
+
+  unbind(channelId: string): void {
+    this.bindings.delete(channelId);
+  }
+
+  getBinding(channelId: string): ConversationBinding | undefined {
+    return this.bindings.get(channelId);
+  }
+
+  /** Reverse lookup: the channel an agent is bound to, if any. */
+  channelForAgent(agentName: string): string | undefined {
+    for (const binding of this.bindings.values()) {
+      if (binding.agentName === agentName) return binding.channelId;
+    }
+    return undefined;
+  }
+
+  getBindings(): ConversationBinding[] {
+    return Array.from(this.bindings.values());
+  }
+
+  /** Bindings whose idle TTL has elapsed. Does not unbind — the framework
+   * runs the closure turn first, then calls unbind(). */
+  expired(now = Date.now()): ConversationBinding[] {
+    const ttl = this.idleTtlMs;
+    return this.getBindings().filter((b) => now - b.lastActivity >= ttl);
+  }
+
+  // ==========================================================================
+  // Helpers
+  // ==========================================================================
+
+  /**
+   * Classify a channel from its descriptor and/or message metadata. Slack
+   * marks DMs/group DMs with is_im/is_mpim on the channel descriptor and
+   * channel_type on each message; other platforms can adopt either
+   * convention.
+   */
+  static classifyChannel(
+    descriptor?: ChannelDescriptor,
+    messageMetadata?: Record<string, unknown>,
+  ): ChannelKind {
+    const meta = descriptor?.metadata as Record<string, unknown> | undefined;
+    if (meta?.is_im === true) return 'dm';
+    if (meta?.is_mpim === true) return 'groupDm';
+    const channelType = messageMetadata?.channel_type;
+    if (channelType === 'im') return 'dm';
+    if (channelType === 'mpim') return 'groupDm';
+    return 'channel';
+  }
+
+  /** Export the per-channel engagement counters for persistence — they must
+   * survive restarts, or a re-engaged channel reuses generation 1's name and
+   * reopens (and re-seeds) the previous engagement's Chronicle namespace. */
+  exportGenerations(): Record<string, number> {
+    return Object.fromEntries(this.generations);
+  }
+
+  /** Restore persisted engagement counters (see exportGenerations). */
+  hydrateGenerations(generations: Record<string, number>): void {
+    for (const [channelId, generation] of Object.entries(generations)) {
+      if (typeof generation === 'number' && generation > (this.generations.get(channelId) ?? 0)) {
+        this.generations.set(channelId, generation);
+      }
+    }
+  }
+
+  private shouldTrigger(facts: IncomingMessageFacts): boolean {
+    const rule = this.config.trigger?.[facts.kind]
+      ?? (facts.kind === 'dm' ? 'always' : 'mention');
+    return rule === 'always' || facts.mentioned;
+  }
+
+  /** `conversation-slack-C123-g2` — agent names double as Chronicle
+   * namespace components, so the channel id is sanitized. */
+  private forkAgentName(channelId: string, generation: number): string {
+    const prefix = this.config.agentPrefix ?? 'conversation';
+    const safe = channelId.replace(/[^A-Za-z0-9_-]+/g, '-');
+    return `${prefix}-${safe}-g${generation}`;
+  }
+}

package/src/mcpl/feature-set-manager.ts

@@ -145,7 +145,20 @@ export class FeatureSetManager {
     capabilities: McplCapabilities,
     config?: { enabledFeatureSets?: string[]; disabledFeatureSets?: string[] }
   ): FeatureSetsUpdateParams {
-    const declared = capabilities.featureSets ?? {};
+    // Cross-package compat: agent-framework's McplCapabilities types
+    // featureSets as Record<string, FeatureSetDeclaration>, but mcpl-core-ts
+    // (used by discord-mcpl and other servers) types it as an array of
+    // {name, ...FeatureSetDeclaration}. Both representations arrive over
+    // the wire. Normalize to Record here so downstream code (resolvePatterns,
+    // validateInbound, etc.) can rely on the keyed shape.
+    const featureSetsRaw = capabilities.featureSets ?? {};
+    const declared: Record<string, FeatureSetDeclaration> = Array.isArray(featureSetsRaw)
+      ? Object.fromEntries(
+          (featureSetsRaw as ReadonlyArray<FeatureSetDeclaration & { name: string }>).map(
+            (d) => [d.name, d],
+          ),
+        )
+      : featureSetsRaw;
 
     const state: ServerState = {
       declared: { ...declared },

package/src/mcpl/index.ts

@@ -130,5 +130,17 @@ export { InferenceRouter } from './inference-router.js';
 // Channel registry (channel lifecycle, incoming messages, synthesized tools)
 export { ChannelRegistry } from './channel-registry.js';
 
+// Per-channel conversation routing (fork-per-channel agents)
+export { ConversationRouter, DEFAULT_CLOSURE_PROMPT } from './conversation-router.js';
+export type {
+  ConversationRouterConfig,
+  ConversationBinding,
+  RoutingDecision,
+  IncomingMessageFacts,
+  BindRule,
+  TriggerRule,
+  ChannelKind,
+} from './conversation-router.js';
+
 // State management (Section 8, checkpoint trees + JSON Patch)
 export { CheckpointManager, applyJsonPatch } from './checkpoint-manager.js';

package/src/mcpl/server-connection.ts

@@ -646,6 +646,10 @@ export class McplServerConnection extends EventEmitter {
     [McplMethod.ChannelsIncoming]: 'channels-incoming',
     [McplMethod.FeatureSetsChanged]: 'feature-sets-changed',
     'notifications/tools/list_changed': 'tools-list-changed',
+    // Host-level admin commands initiated from a surface (e.g. a Discord
+    // slash command). Params: { command, ... }; host responds with a
+    // command-specific result object.
+    'host/command': 'host-command',
   };
 
   /**

package/src/module-registry.ts

@@ -21,6 +21,7 @@ import type {
   SpeechContext,
   SpeechHandlerOptions,
   ProcessEvent,
+  TraceEventListener,
 } from './types/index.js';
 import type { Agent } from './agent.js';
 
@@ -53,6 +54,7 @@ export class ModuleRegistry {
   private queryMessagesFn: (filter: MessageQuery) => MessageQueryResult;
 
   private pushEventFn: (event: ProcessEvent) => void;
+  private onTraceFn: (listener: TraceEventListener) => () => void;
 
   constructor(
     store: JsStore,
@@ -65,6 +67,7 @@ export class ModuleRegistry {
       getMessage: (id: MessageId) => StoredMessage | null;
       queryMessages: (filter: MessageQuery) => MessageQueryResult;
       pushEvent: (event: ProcessEvent) => void;
+      onTrace: (listener: TraceEventListener) => () => void;
     }
   ) {
     this.store = store;
@@ -76,6 +79,7 @@ export class ModuleRegistry {
     this.getMessageFn = options.getMessage;
     this.queryMessagesFn = options.queryMessages;
     this.pushEventFn = options.pushEvent;
+    this.onTraceFn = options.onTrace;
   }
 
   /**
@@ -115,7 +119,8 @@ export class ModuleRegistry {
       this.removeMessageFn,
       this.getMessageFn,
       this.queryMessagesFn,
-      this.pushEventFn
+      this.pushEventFn,
+      this.onTraceFn
     );
 
     this.modules.set(module.name, module);
@@ -366,6 +371,7 @@ class ModuleContextImpl implements ModuleContext {
   private getMessageFn: (id: MessageId) => StoredMessage | null;
   private queryMessagesFn: (filter: MessageQuery) => MessageQueryResult;
   private pushEventFn: (event: ProcessEvent) => void;
+  private onTraceFn: (listener: TraceEventListener) => () => void;
 
   // External ID mapping stored in module state
   private externalIdMap: Map<string, MessageId> = new Map();
@@ -383,7 +389,8 @@ class ModuleContextImpl implements ModuleContext {
     removeMessage: (id: MessageId) => void,
     getMessage: (id: MessageId) => StoredMessage | null,
     queryMessages: (filter: MessageQuery) => MessageQueryResult,
-    pushEvent: (event: ProcessEvent) => void
+    pushEvent: (event: ProcessEvent) => void,
+    onTrace: (listener: TraceEventListener) => () => void
   ) {
     this.moduleName = moduleName;
     this.store = store;
@@ -398,6 +405,7 @@ class ModuleContextImpl implements ModuleContext {
     this.getMessageFn = getMessage;
     this.queryMessagesFn = queryMessages;
     this.pushEventFn = pushEvent;
+    this.onTraceFn = onTrace;
 
     // Load external ID map from state if exists
     const state = this.getState<{ externalIdMap?: Record<string, string> }>();
@@ -424,6 +432,10 @@ class ModuleContextImpl implements ModuleContext {
     return this.registry.getModule<T>(name);
   }
 
+  onTrace(listener: TraceEventListener): () => void {
+    return this.onTraceFn(listener);
+  }
+
   addMessage(
     participant: string,
     content: ContentBlock[],

package/src/modules/discord/index.ts

@@ -18,6 +18,7 @@ import type {
   ToolCall,
   ToolResult,
   SpeechContext,
+  TraceEvent,
 } from '../../types/index.js';
 import type {
   DiscordModuleConfig,
@@ -56,6 +57,24 @@ const DEFAULT_CONFIG: Partial<DiscordModuleConfig> = {
   historyScrollback: 50,
 };
 
+// Re-trigger the Discord typing indicator on this interval. Discord's
+// indicator auto-expires after ~10s, so we refresh comfortably inside that.
+const TYPING_REFRESH_MS = 8_000;
+
+// Absolute safety cap on a single typing keepalive. If a terminal trace event
+// is somehow missed (crash, dropped stream), this guarantees typing can't get
+// stuck on forever.
+const TYPING_MAX_MS = 5 * 60_000;
+
+// Trace event types that terminate an agent's turn — any of these stops the
+// typing keepalive. They fire once per turn, after all tool-call cycles.
+const TURN_TERMINAL_TRACES = new Set([
+  'inference:turn_ended',
+  'inference:aborted',
+  'inference:failed',
+  'inference:exhausted',
+]);
+
 // Image MIME types that Claude can process
 const SUPPORTED_IMAGE_TYPES = [
   'image/jpeg',
@@ -95,6 +114,15 @@ export class DiscordModule implements Module {
   // Last message sent by a tool (for thought-editing)
   private lastSentMessage: { channelId: string; messageId: string } | null = null;
 
+  // Typing keepalive: agentName -> { interval, deadline }. Started on
+  // inference:started, stopped on the turn's terminal trace event. Discord's
+  // typing indicator auto-expires after ~10s, so we re-trigger on an interval
+  // to keep it alive for the whole turn (including tool-call cycles).
+  private typingLoops: Map<string, { interval: ReturnType<typeof setInterval>; deadline: number }> = new Map();
+
+  // Unsubscribe handle for the trace subscription (cleared in stop()).
+  private unsubscribeTrace: (() => void) | null = null;
+
   constructor(client: DiscordClientInterface, config: DiscordModuleConfig) {
     this.client = client;
     this.config = { ...DEFAULT_CONFIG, ...config };
@@ -114,6 +142,22 @@ export class DiscordModule implements Module {
     // Register as speech handler
     ctx.registerSpeechHandler('*');
 
+    // Typing keepalive: bracket the indicator between an agent starting
+    // inference and its turn ending, so it stays alive for the whole turn
+    // (including tool-call cycles) and stops cleanly whether the agent
+    // responds, errors, or decides to stay silent.
+    if (this.config.autoTyping) {
+      this.unsubscribeTrace = ctx.onTrace((event: TraceEvent) => {
+        const agentName = (event as { agentName?: string }).agentName;
+        if (!agentName) return;
+        if (event.type === 'inference:started') {
+          this.startTypingLoop(agentName);
+        } else if (TURN_TERMINAL_TRACES.has(event.type)) {
+          this.stopTypingLoop(agentName);
+        }
+      });
+    }
+
     // Set up Discord event handlers
     this.client.onMessage((message) => this.handleDiscordMessage(message));
     this.client.onMessageEdit((id, content) => this.handleDiscordMessageEdit(id, content));
@@ -146,10 +190,59 @@ export class DiscordModule implements Module {
       this.ctx.setState(this.state);
     }
 
+    // Tear down typing keepalive: drop the trace subscription and clear any
+    // in-flight intervals so nothing leaks across teardown/recreate.
+    this.unsubscribeTrace?.();
+    this.unsubscribeTrace = null;
+    for (const { interval } of this.typingLoops.values()) {
+      clearInterval(interval);
+    }
+    this.typingLoops.clear();
+
     await this.client.disconnect();
     this.ctx = null;
   }
 
+  /**
+   * Start (or refresh) the typing keepalive for an agent's reply channel.
+   * Idempotent: a fresh `inference:started` resets the safety deadline and
+   * restarts the interval. No-op if we can't resolve a channel for the agent.
+   */
+  private startTypingLoop(agentName: string): void {
+    const replyCtx = this.replyContexts.get(agentName) ?? this.replyContexts.get('default');
+    if (!replyCtx) return;
+    const channel = replyCtx.threadId ?? replyCtx.channelId;
+
+    // Restart cleanly if one is already running for this agent.
+    this.stopTypingLoop(agentName);
+
+    const deadline = Date.now() + TYPING_MAX_MS;
+    const fire = () => {
+      if (Date.now() >= deadline) {
+        this.stopTypingLoop(agentName);
+        return;
+      }
+      this.client.sendTyping(channel).catch((err) => {
+        console.warn('Discord: Failed to send typing indicator:', err);
+      });
+    };
+
+    fire(); // immediate feedback, don't wait a full interval
+    const interval = setInterval(fire, TYPING_REFRESH_MS);
+    // Don't keep the process alive solely for a typing indicator.
+    (interval as { unref?: () => void }).unref?.();
+    this.typingLoops.set(agentName, { interval, deadline });
+  }
+
+  /** Stop the typing keepalive for an agent, if one is running. */
+  private stopTypingLoop(agentName: string): void {
+    const loop = this.typingLoops.get(agentName);
+    if (loop) {
+      clearInterval(loop.interval);
+      this.typingLoops.delete(agentName);
+    }
+  }
+
   getTools(): ToolDefinition[] {
     return [
       {

package/src/tool-result-history.ts

@@ -0,0 +1,57 @@
+/**
+ * Convert an AF `ToolResult.data` value into the string form that lives in
+ * the agent's conversation history.
+ *
+ * The live path (`toMembraneToolResult` in framework.ts) preserves MCP image
+ * blocks natively so the model sees the bytes on the current turn. The
+ * *persisted* copy needs to survive recompilation, compression, and
+ * `/restore` — storing megabytes of base64 there gets corrupted on the next
+ * `maxChars` slice and re-introduces, one turn deferred, exactly the silent
+ * hallucination this feature exists to kill.
+ *
+ * For MCP-shaped content arrays, this helper keeps text blocks verbatim and
+ * replaces image blocks with a short `[image: mimeType, ~NKB]` placeholder.
+ * For anything else it falls back to JSON.
+ */
+
+import { safeSlice } from './safe-slice.js';
+
+export function toolResultDataToHistoryString(data: unknown, maxChars?: number): string {
+  const fromArray = tryHistoryStringFromContentArray(data);
+  const str = fromArray ?? JSON.stringify(data);
+  if (maxChars && str.length > maxChars) {
+    return safeSlice(str, 0, maxChars)
+      + '\n\n[truncated — original was ' + str.length + ' chars]';
+  }
+  return str;
+}
+
+/**
+ * If `data` is an MCP content array whose every block has a shape we
+ * recognize, return a history-safe string (images → placeholders). Otherwise
+ * return `null` to defer to the caller's fallback (JSON, usually).
+ */
+function tryHistoryStringFromContentArray(data: unknown): string | null {
+  if (!Array.isArray(data)) return null;
+  const parts: string[] = [];
+  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') {
+      parts.push(b.text);
+    } else if (b.type === 'image' && typeof b.data === 'string' && typeof b.mimeType === 'string') {
+      // Decoded byte estimate from base64 length (3/4 ratio, rounded).
+      const approxBytes = Math.floor(b.data.length * 3 / 4);
+      parts.push(`[image: ${b.mimeType}, ${formatSize(approxBytes)}]`);
+    } else {
+      return null;
+    }
+  }
+  return parts.join('\n');
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `~${Math.round(bytes / 1024)}KB`;
+  return `~${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}

package/src/types/agent.ts

@@ -42,6 +42,9 @@ export interface AgentConfig {
    *  restarts with recompiled (compressed) context. Default: 150000. */
   maxStreamTokens?: number;
 
+  /** Per-agent context compile budget (input tokens). When unset, the
+   *  ContextManager's built-in default (100k) applies. */
+  contextBudgetTokens?: number;
   /**
    * Extended thinking config. When `enabled: true`, the agent runs with
    * Anthropic's native extended thinking; responses include `thinking` blocks
@@ -51,6 +54,14 @@ export interface AgentConfig {
   thinking?: {
     enabled: boolean;
     budgetTokens?: number;
+    /** 'enabled' (explicit budget, default) or 'adaptive' (model-managed) */
+    type?: 'enabled' | 'adaptive';
+    /**
+     * How thinking content is returned: 'summarized' (readable summary) or
+     * 'omitted' (empty thinking field, signature only). Fable 5 / Opus 4.7+
+     * default to 'omitted' — set 'summarized' to receive thinking text.
+     */
+    display?: 'summarized' | 'omitted';
   };
 }
 

package/src/types/framework.ts

@@ -4,6 +4,7 @@ import type { Module, EventResponse } from './module.js';
 import type { AgentConfig, InferenceRequest } from './agent.js';
 import type { ProcessEvent } from './events.js';
 import type { McplServerConfig, InferenceRoutingPolicy } from '../mcpl/types.js';
+import type { ConversationRouterConfig } from '../mcpl/conversation-router.js';
 import type { GateOptions } from '../gate/types.js';
 
 // Re-export trace types
@@ -66,6 +67,14 @@ export interface FrameworkConfig {
 
   /** EventGate config. If omitted, all events trigger inference (unchanged default). */
   gate?: GateOptions;
+
+  /**
+   * Per-channel conversation routing. When set, incoming MCPL channel
+   * messages route to per-channel fork agents spawned from the template
+   * agent instead of the primary conversation. If omitted, behavior is
+   * unchanged (all messages go to the primary agent).
+   */
+  conversations?: ConversationRouterConfig;
 }
 
 /**

package/src/types/module.ts

@@ -6,6 +6,7 @@ import type {
   ContextInjection,
 } from '@animalabs/context-manager';
 import type { ProcessEvent, ToolDefinition, ToolCall, ToolResult } from './events.js';
+import type { TraceEventListener } from './trace.js';
 
 /**
  * Filter criteria for querying messages.
@@ -184,6 +185,21 @@ export interface ModuleContext {
    * Unregister this module as a speech handler.
    */
   unregisterSpeechHandler(): void;
+
+  /**
+   * Subscribe to the framework's trace event stream for observability.
+   *
+   * Modules use this to react to agent lifecycle without polling — e.g. an
+   * adapter that wants to show a "typing" indicator can bracket it between
+   * `inference:started` and the terminal events (`inference:turn_ended`,
+   * `inference:aborted`, `inference:failed`, `inference:exhausted`), all of
+   * which carry `agentName`. The terminal events fire once per turn, after any
+   * tool-call cycles, so a single start/stop bracket spans the whole turn.
+   *
+   * Returns an unsubscribe function. Call it in the module's `stop()` to avoid
+   * leaking listeners across teardown/recreate (e.g. session switch).
+   */
+  onTrace(listener: TraceEventListener): () => void;
 }
 
 /**