@animalabs/agent-framework 0.5.7 → 0.6.2

package/src/mcpl/transport.ts

@@ -0,0 +1,307 @@
+/**
+ * McplTransport — the byte-level seam under McplServerConnection.
+ *
+ * An MCPL connection is newline-delimited JSON-RPC over a duplex stream. The
+ * only things the connection needs from its underlying transport are: write a
+ * line, receive lines, surface diagnostics/errors, and know when it closed. By
+ * abstracting exactly that, the handshake, message routing, and every send path
+ * stay transport-agnostic and run IDENTICALLY over a spawned stdio child or a
+ * WebSocket — which is the whole point of network MCPL.
+ *
+ * Two implementations:
+ *  - StdioTransport      — spawns `config.command` and speaks over stdin/stdout;
+ *                          child stderr is surfaced as 'stderr' lines.
+ *  - WebSocketTransport  — dials `config.url` (ws:// or wss://) with the `ws`
+ *                          library, appending `?token=` when `config.token` is
+ *                          set; each WS text frame is one JSON-RPC line.
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import { createInterface, type Interface as ReadlineInterface } from 'node:readline';
+import { EventEmitter } from 'node:events';
+import WebSocket from 'ws';
+
+import type { McplServerConfig } from './types.js';
+
+/** Why/how a transport closed. `code`/`signal` are populated for stdio child
+ *  exits; `reason` carries a WebSocket close reason or an error message. */
+export interface TransportCloseInfo {
+  code?: number | null;
+  signal?: NodeJS.Signals | null;
+  reason?: string;
+}
+
+/**
+ * A line-oriented duplex transport to an MCPL server.
+ *
+ * Events:
+ *  - `'line'`   `(line: string)`            one inbound NDJSON line (no newline)
+ *  - `'stderr'` `(line: string)`            diagnostic line (stdio child stderr; never WS)
+ *  - `'error'`  `(err: Error)`              transport-level error
+ *  - `'close'`  `(info: TransportCloseInfo)` transport closed (once)
+ *
+ * Inbound `'line'`/`'stderr'` events are buffered until the first matching
+ * listener attaches (and re-buffered whenever there are none), so no message is
+ * lost across the handshake→routing handoff regardless of attach timing.
+ */
+export abstract class McplTransport extends EventEmitter {
+  abstract readonly kind: 'stdio' | 'websocket';
+
+  private _closed = false;
+  private lineBuffer: string[] = [];
+  private stderrBuffer: string[] = [];
+
+  protected constructor() {
+    super();
+    // Flush buffered inbound lines the moment a consumer subscribes.
+    this.on('newListener', (event) => {
+      if (event === 'line' && this.lineBuffer.length > 0) {
+        const pending = this.lineBuffer;
+        this.lineBuffer = [];
+        queueMicrotask(() => { for (const l of pending) this.emit('line', l); });
+      } else if (event === 'stderr' && this.stderrBuffer.length > 0) {
+        const pending = this.stderrBuffer;
+        this.stderrBuffer = [];
+        queueMicrotask(() => { for (const l of pending) this.emit('stderr', l); });
+      }
+    });
+  }
+
+  get closed(): boolean {
+    return this._closed;
+  }
+
+  /** Deliver an inbound line, buffering it if nobody is listening yet. */
+  protected pushLine(line: string): void {
+    if (this.listenerCount('line') > 0) this.emit('line', line);
+    else this.lineBuffer.push(line);
+  }
+
+  /** Deliver a diagnostic line, buffering it if nobody is listening yet. */
+  protected pushStderr(line: string): void {
+    if (this.listenerCount('stderr') > 0) this.emit('stderr', line);
+    else this.stderrBuffer.push(line);
+  }
+
+  /** Emit 'close' exactly once. */
+  protected markClosed(info: TransportCloseInfo): void {
+    if (this._closed) return;
+    this._closed = true;
+    this.emit('close', info);
+  }
+
+  /** Write one JSON-RPC message as an NDJSON line. */
+  abstract writeLine(json: string): void;
+
+  /** Close the transport and release resources. Resolves once fully closed. */
+  abstract close(): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// stdio
+// ---------------------------------------------------------------------------
+
+export class StdioTransport extends McplTransport {
+  readonly kind = 'stdio' as const;
+
+  private constructor(
+    private readonly child: ChildProcess,
+    private readonly rl: ReadlineInterface,
+  ) {
+    super();
+
+    this.rl.on('line', (line: string) => this.pushLine(line));
+
+    // Stitch stderr chunks into whole lines (a chunk can split a line).
+    let carry = '';
+    this.child.stderr?.on('data', (chunk: Buffer) => {
+      const text = carry + chunk.toString('utf8');
+      const lines = text.split('\n');
+      carry = lines.pop() ?? '';
+      for (const l of lines) if (l.length > 0) this.pushStderr(l);
+    });
+
+    this.child.on('error', (err) => this.emit('error', err));
+    this.child.on('exit', (code, signal) =>
+      this.markClosed({ code, signal, reason: 'child process exited' }),
+    );
+  }
+
+  /**
+   * Spawn `config.command` and return a ready stdio transport. Rejects if the
+   * command is missing (a config bug) or the process fails to spawn.
+   */
+  static spawn(config: McplServerConfig): StdioTransport {
+    if (!config.command) {
+      throw new Error(
+        `MCPL server "${config.id}": stdio transport requires "command" (none provided)`,
+      );
+    }
+    const child = spawn(config.command, config.args ?? [], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, ...config.env },
+    });
+    const rl = createInterface({ input: child.stdout! });
+    return new StdioTransport(child, rl);
+  }
+
+  writeLine(json: string): void {
+    // stdin may be gone if the child died between the closed-check and here.
+    this.child.stdin?.write(json + '\n');
+  }
+
+  async close(): Promise<void> {
+    this.markClosed({ reason: 'closed by host' });
+    this.rl.close();
+    if (this.child && !this.child.killed) {
+      this.child.kill();
+    }
+    await new Promise<void>((resolve) => {
+      if (!this.child || this.child.exitCode !== null || this.child.killed) {
+        resolve();
+      } else {
+        this.child.once('exit', () => resolve());
+      }
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// WebSocket
+// ---------------------------------------------------------------------------
+
+/** Timeout for the WebSocket to reach OPEN before we give up (ms). */
+const WS_OPEN_TIMEOUT_MS = 15_000;
+
+export class WebSocketTransport extends McplTransport {
+  readonly kind = 'websocket' as const;
+
+  private constructor(private readonly ws: WebSocket) {
+    super();
+
+    this.ws.on('message', (data: WebSocket.RawData, isBinary: boolean) => {
+      // MCPL frames are UTF-8 JSON text. A frame MAY contain multiple
+      // newline-delimited messages or a trailing newline; split defensively.
+      const text = isBinary ? (data as Buffer).toString('utf8') : String(data);
+      for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length > 0) this.pushLine(trimmed);
+      }
+    });
+
+    this.ws.on('error', (err: Error) => this.emit('error', err));
+    this.ws.on('close', (code: number, reason: Buffer) =>
+      this.markClosed({ code, reason: reason?.toString('utf8') || 'websocket closed' }),
+    );
+  }
+
+  /**
+   * Dial `config.url` and resolve once the socket is OPEN. Appends `?token=`
+   * when `config.token` is set. Rejects on connect error / timeout (and tears
+   * the socket down) so a failed dial never leaks an open handle.
+   */
+  static open(config: McplServerConfig): Promise<WebSocketTransport> {
+    const url = buildWebSocketUrl(config);
+    const ws = new WebSocket(url);
+
+    return new Promise<WebSocketTransport>((resolve, reject) => {
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        ws.removeAllListeners();
+        try { ws.terminate(); } catch { /* already gone */ }
+        reject(new Error(`MCPL server "${config.id}" WebSocket connect timed out after ${WS_OPEN_TIMEOUT_MS}ms (${url})`));
+      }, WS_OPEN_TIMEOUT_MS);
+
+      ws.once('open', () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        ws.removeAllListeners('error'); // the instance re-attaches its own handlers
+        resolve(new WebSocketTransport(ws));
+      });
+
+      ws.once('error', (err: Error) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        ws.removeAllListeners();
+        try { ws.terminate(); } catch { /* already gone */ }
+        reject(new Error(`MCPL server "${config.id}" WebSocket connect failed: ${err.message} (${url})`));
+      });
+    });
+  }
+
+  writeLine(json: string): void {
+    if (this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(json);
+    }
+  }
+
+  async close(): Promise<void> {
+    this.markClosed({ reason: 'closed by host' });
+    await new Promise<void>((resolve) => {
+      if (this.ws.readyState === WebSocket.CLOSED) {
+        resolve();
+        return;
+      }
+      this.ws.once('close', () => resolve());
+      try {
+        this.ws.close();
+      } catch {
+        try { this.ws.terminate(); } catch { /* already gone */ }
+        resolve();
+      }
+    });
+  }
+}
+
+/**
+ * Build the dial URL: validate it's a ws(s):// URL and append the auth token as
+ * a `token` query param when provided (preserving any existing query).
+ */
+export function buildWebSocketUrl(config: McplServerConfig): string {
+  if (!config.url) {
+    throw new Error(`MCPL server "${config.id}": websocket transport requires "url" (none provided)`);
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(config.url);
+  } catch {
+    throw new Error(`MCPL server "${config.id}": invalid WebSocket url "${config.url}"`);
+  }
+  if (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') {
+    throw new Error(
+      `MCPL server "${config.id}": websocket url must be ws:// or wss://, got "${parsed.protocol}"`,
+    );
+  }
+  if (config.token) {
+    parsed.searchParams.set('token', config.token);
+  }
+  return parsed.toString();
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/** True when the config selects the WebSocket transport (explicit `transport`,
+ *  or a `url` with no `command`). */
+export function isWebSocketTransport(config: McplServerConfig): boolean {
+  if (config.transport === 'websocket') return true;
+  if (config.transport === 'stdio') return false;
+  return Boolean(config.url) && !config.command;
+}
+
+/**
+ * Open the transport selected by `config` (WebSocket when `transport` is
+ * 'websocket' or a bare `url` is given; stdio otherwise). The returned transport
+ * is connected at the byte level but has NOT performed the MCPL handshake.
+ */
+export async function openTransport(config: McplServerConfig): Promise<McplTransport> {
+  if (isWebSocketTransport(config)) {
+    return WebSocketTransport.open(config);
+  }
+  return StdioTransport.spawn(config);
+}

package/src/mcpl/types.ts

@@ -165,8 +165,12 @@ export interface McplServerConfig {
   /** Unique server identifier */
   id: string;
 
-  /** Command to spawn the server process (stdio transport) */
-  command: string;
+  /**
+   * Command to spawn the server process (stdio transport). Mutually exclusive
+   * with `url`. Required for the stdio transport; omit it (and set `url`) for
+   * the WebSocket transport.
+   */
+  command?: string;
 
   /** Arguments for the command */
   args?: string[];
@@ -174,6 +178,26 @@ export interface McplServerConfig {
   /** Environment variables for the child process */
   env?: Record<string, string>;
 
+  /**
+   * WebSocket URL for the network transport (`ws://` or `wss://`). Mutually
+   * exclusive with `command`. When set (or `transport: 'websocket'`), the host
+   * dials this endpoint instead of spawning a process — newline-delimited
+   * JSON-RPC MCPL runs over the socket identically to stdio.
+   */
+  url?: string;
+
+  /**
+   * Transport selector. Defaults to `'websocket'` when a bare `url` is given
+   * (no `command`), `'stdio'` otherwise. Set explicitly to disambiguate.
+   */
+  transport?: 'stdio' | 'websocket';
+
+  /**
+   * Bearer token for WebSocket auth. Appended to `url` as a `token` query
+   * parameter (`?token=…`) on connect. Ignored by the stdio transport.
+   */
+  token?: string;
+
   /** Feature sets to enable on connect */
   enabledFeatureSets?: string[];
 
@@ -210,11 +234,29 @@ export interface McplServerConfig {
   reconnect?: boolean;
 
   /**
-   * Interval between reconnection attempts in milliseconds.
+   * Base interval between reconnection attempts in milliseconds.
+   * The actual delay doubles with each consecutive failure (with ±25% jitter)
+   * up to `reconnectMaxIntervalMs`, and resets after a successful handshake.
    * Default: 5000 (5 seconds).
    */
   reconnectIntervalMs?: number;
 
+  /**
+   * Ceiling for the exponential reconnect backoff in milliseconds.
+   * Default: 300000 (5 minutes).
+   */
+  reconnectMaxIntervalMs?: number;
+
+  /**
+   * Per-request timeout in milliseconds for outbound JSON-RPC requests
+   * (tools/call, tools/list, channels/*, hooks). A live-but-stuck server that
+   * accepts a request and never responds would otherwise freeze the awaiting
+   * agent turn forever; with the timeout the pending request rejects with a
+   * descriptive error, which the framework surfaces as a normal isError
+   * tool_result. Set 0 to disable. Default: 60000 (60 seconds).
+   */
+  requestTimeoutMs?: number;
+
   /**
    * Optional callback to filter which incoming channel messages should trigger
    * agent inference. Receives the text content and message metadata.
@@ -291,6 +333,16 @@ export interface FeatureSetDeclaration {
 
   /** Whether host manages state persistence for this feature set (Section 8.1) */
   hostState?: boolean;
+
+  /** Optional, open-world tag ontology for this feature set's events
+   *  (MCPL RFC-001 §5). A hint catalog — hosts tolerate undeclared tags. */
+  tagOntology?: {
+    coreTags?: string[];
+    tags?: Record<string, unknown>;
+    keyed?: Record<string, unknown>;
+    defaultTreatment?: unknown[];
+    open?: boolean;
+  };
 }
 
 /**
@@ -390,6 +442,13 @@ export interface StateCheckpoint {
   /** Parent checkpoint (null for root) */
   parent: string | null;
 
+  /**
+   * Owning feature set, when the server tags it. Authoritative signal for
+   * attributing this checkpoint — lets the host record it to the right set
+   * instead of guessing when a server has more than one stateful feature set.
+   */
+  featureSet?: string;
+
   /**
    * Full state data (for host-managed state).
    * Mutually exclusive with `patch`.
@@ -461,6 +520,9 @@ export interface PushEventParams {
   /** Provenance metadata (server-defined) */
   origin?: Record<string, unknown>;
 
+  /** Semantic classification the host may route on (MCPL RFC-001). */
+  tags?: string[];
+
   /** Event payload */
   payload: {
     /** Content for the model to interpret */
@@ -897,6 +959,9 @@ export interface ChannelIncomingMessage {
 
   /** Platform-specific metadata */
   metadata?: Record<string, unknown>;
+
+  /** Semantic classification the host may route on (MCPL RFC-001). */
+  tags?: string[];
 }
 
 /**

package/src/module-registry.ts

@@ -27,6 +27,25 @@ import type { Agent } from './agent.js';
 
 const MODULE_STATE_PREFIX = 'modules/';
 
+/**
+ * True when a registerState failure means "this state id already exists" —
+ * the one failure that is safe to swallow on an idempotent re-registration.
+ * Anything else (closed store, IO error) must propagate: swallowing it defers
+ * the real error to a later write with far worse context.
+ */
+export function isStateExistsError(err: unknown): boolean {
+  return err instanceof Error && err.message.includes('State already exists');
+}
+
+/**
+ * Hard ceiling for a single module's gatherContext budget, regardless of the
+ * `contextTimeoutMs` it declares. gatherContext runs on the critical path of
+ * every inference turn, so an unbounded self-declared budget would let one
+ * wedged module stall every agent. 30s is generous for legitimate work (e.g. a
+ * retrieval module's sequential LLM calls) while keeping the worst case bounded.
+ */
+const MAX_CONTEXT_TIMEOUT_MS = 30_000;
+
 /**
  * Registered speech handler.
  */
@@ -55,6 +74,7 @@ export class ModuleRegistry {
 
   private pushEventFn: (event: ProcessEvent) => void;
   private onTraceFn: (listener: TraceEventListener) => () => void;
+  private callToolFn: (call: ToolCall) => Promise<ToolResult>;
 
   constructor(
     store: JsStore,
@@ -68,6 +88,7 @@ export class ModuleRegistry {
       queryMessages: (filter: MessageQuery) => MessageQueryResult;
       pushEvent: (event: ProcessEvent) => void;
       onTrace: (listener: TraceEventListener) => () => void;
+      callTool: (call: ToolCall) => Promise<ToolResult>;
     }
   ) {
     this.store = store;
@@ -80,6 +101,7 @@ export class ModuleRegistry {
     this.queryMessagesFn = options.queryMessages;
     this.pushEventFn = options.pushEvent;
     this.onTraceFn = options.onTrace;
+    this.callToolFn = options.callTool;
   }
 
   /**
@@ -120,7 +142,8 @@ export class ModuleRegistry {
       this.getMessageFn,
       this.queryMessagesFn,
       this.pushEventFn,
-      this.onTraceFn
+      this.onTraceFn,
+      this.callToolFn
     );
 
     this.modules.set(module.name, module);
@@ -298,20 +321,44 @@ export class ModuleRegistry {
   /**
    * Gather context injections from all modules before inference.
    * Calls each module's gatherContext() in parallel with a per-module timeout.
-   * Fail-open: timed-out or erroring modules are skipped silently.
+   * Fail-open: timed-out or erroring modules are skipped (with a stderr line).
+   *
+   * The per-module budget is `module.contextTimeoutMs` when declared, else the
+   * `timeoutMs` default (15s). Modules whose gatherContext does real work —
+   * e.g. a retrieval module making sequential LLM calls with backoff — should
+   * declare a larger `contextTimeoutMs` rather than silently losing their
+   * injection every turn to the shared default. The declared value is clamped
+   * to MAX_CONTEXT_TIMEOUT_MS so no single module can hold every turn hostage.
    * Adapted from Anarchid/agent-framework@mcpl-module-proto.
    */
-  async gatherContext(agentName: string, timeoutMs = 5000): Promise<ContextInjection[]> {
+  async gatherContext(agentName: string, timeoutMs = 15_000): Promise<ContextInjection[]> {
     const injections: ContextInjection[] = [];
     const promises: Promise<void>[] = [];
 
     for (const module of this.modules.values()) {
       if (!module.gatherContext) continue;
 
+      // Clamp the per-module budget. A module declaring `contextTimeoutMs`
+      // legitimately needs more than the shared default (e.g. a retrieval
+      // module doing sequential LLM calls), but it must not be able to hold
+      // EVERY inference turn of EVERY agent hostage: the fail-open contract is
+      // "a wedged module never blocks inference for long", so cap the wait.
+      const budgetMs = Math.min(
+        module.contextTimeoutMs ?? timeoutMs,
+        MAX_CONTEXT_TIMEOUT_MS,
+      );
+      let timer: ReturnType<typeof setTimeout> | undefined;
       const promise = Promise.race([
         module.gatherContext(agentName).then(r => injections.push(...r)),
-        new Promise<void>((_, rej) => setTimeout(() => rej(new Error('timeout')), timeoutMs)),
-      ]).catch(err => console.error(`[${module.name}] gatherContext:`, err));
+        new Promise<void>((_, rej) => {
+          timer = setTimeout(
+            () => rej(new Error(`gatherContext timed out after ${budgetMs}ms`)),
+            budgetMs,
+          );
+        }),
+      ])
+        .catch(err => console.error(`[${module.name}] gatherContext:`, err))
+        .finally(() => clearTimeout(timer));
 
       promises.push(promise as Promise<void>);
     }
@@ -372,6 +419,7 @@ class ModuleContextImpl implements ModuleContext {
   private queryMessagesFn: (filter: MessageQuery) => MessageQueryResult;
   private pushEventFn: (event: ProcessEvent) => void;
   private onTraceFn: (listener: TraceEventListener) => () => void;
+  private callToolFn: (call: ToolCall) => Promise<ToolResult>;
 
   // External ID mapping stored in module state
   private externalIdMap: Map<string, MessageId> = new Map();
@@ -390,7 +438,8 @@ class ModuleContextImpl implements ModuleContext {
     getMessage: (id: MessageId) => StoredMessage | null,
     queryMessages: (filter: MessageQuery) => MessageQueryResult,
     pushEvent: (event: ProcessEvent) => void,
-    onTrace: (listener: TraceEventListener) => () => void
+    onTrace: (listener: TraceEventListener) => () => void,
+    callTool: (call: ToolCall) => Promise<ToolResult>
   ) {
     this.moduleName = moduleName;
     this.store = store;
@@ -406,6 +455,7 @@ class ModuleContextImpl implements ModuleContext {
     this.queryMessagesFn = queryMessages;
     this.pushEventFn = pushEvent;
     this.onTraceFn = onTrace;
+    this.callToolFn = callTool;
 
     // Load external ID map from state if exists
     const state = this.getState<{ externalIdMap?: Record<string, string> }>();
@@ -428,6 +478,72 @@ class ModuleContextImpl implements ModuleContext {
     this.store.setStateJson(this.stateId, fullState);
   }
 
+  /** Log-state names this context has registered (registerLogState is
+   *  contract-required in start(), so this is populated before any use). */
+  private registeredLogStates = new Set<string>();
+
+  private logStateId(name: string): string {
+    if (!name || name === 'state' || name.includes('/')) {
+      throw new Error(
+        `Invalid module log state name '${name}': must be non-empty, not 'state', and contain no '/'`
+      );
+    }
+    return `${MODULE_STATE_PREFIX}${this.moduleName}/${name}`;
+  }
+
+  /**
+   * Like logStateId, but only for names that went through registerLogState.
+   * Chronicle happily appends to an unregistered state — it just never gets a
+   * snapshot strategy, so every reconstruction replays the full op chain from
+   * record one. A forgotten registration or a typo'd name in one call site
+   * must be an immediate, attributable error, not a silent O(n²)-read trap.
+   */
+  private registeredLogStateId(name: string): string {
+    if (!this.registeredLogStates.has(name)) {
+      throw new Error(
+        `Module log state '${name}' is not registered for module '${this.moduleName}' — ` +
+        `call registerLogState('${name}') in start() before using it`
+      );
+    }
+    return this.logStateId(name);
+  }
+
+  registerLogState(
+    name: string,
+    opts?: { deltaSnapshotEvery?: number; fullSnapshotEvery?: number }
+  ): void {
+    const id = this.logStateId(name);
+    try {
+      this.store.registerState({
+        id,
+        strategy: 'append_log',
+        deltaSnapshotEvery: opts?.deltaSnapshotEvery ?? 100,
+        fullSnapshotEvery: opts?.fullSnapshotEvery ?? 20,
+      });
+    } catch (err) {
+      if (!isStateExistsError(err)) throw err;
+      // Already registered (previous run) — idempotent path.
+    }
+    this.registeredLogStates.add(name);
+  }
+
+  appendToLog<T>(name: string, item: T): void {
+    this.store.appendToStateJson(this.registeredLogStateId(name), item);
+  }
+
+  editLogItem<T>(name: string, index: number, item: T): void {
+    this.store.editStateItem(this.registeredLogStateId(name), index, Buffer.from(JSON.stringify(item)));
+  }
+
+  getLog<T>(name: string): T[] {
+    const data = this.store.getStateJson(this.registeredLogStateId(name));
+    return Array.isArray(data) ? (data as T[]) : [];
+  }
+
+  getLogLength(name: string): number {
+    return this.store.getStateLen(this.registeredLogStateId(name)) ?? 0;
+  }
+
   getModule<T extends Module>(name: string): T | null {
     return this.registry.getModule<T>(name);
   }
@@ -436,6 +552,10 @@ class ModuleContextImpl implements ModuleContext {
     return this.onTraceFn(listener);
   }
 
+  callTool(call: ToolCall): Promise<ToolResult> {
+    return this.callToolFn(call);
+  }
+
   addMessage(
     participant: string,
     content: ContentBlock[],

package/src/prose-segments.ts

@@ -0,0 +1,42 @@
+/**
+ * Split an assistant turn's content blocks into ordered prose segments.
+ *
+ * A single turn can interleave prose and tool calls — "msgA → [tool] → msgB →
+ * [tool] → msgC". The membrane accumulates the WHOLE turn (all tool rounds) into
+ * one `response.content` array in provider order, so a left-to-right walk that
+ * breaks at each tool boundary reconstructs the emission order.
+ *
+ * Host output routing used to join every text block into a single trailing post,
+ * collapsing those distinct messages into one (item 4). This helper instead
+ * yields each contiguous run of text — the segments a surface should deliver as
+ * separate, ordered messages. Contiguous text blocks merge into one segment;
+ * `tool_use` / `tool_result` blocks are segment boundaries; empty or
+ * whitespace-only runs are dropped.
+ */
+
+import type { ContentBlock } from '@animalabs/membrane';
+
+export function splitProseSegments(content: readonly ContentBlock[]): string[] {
+  const segments: string[] = [];
+  let buf: string[] = [];
+
+  const flush = (): void => {
+    const s = buf.join('\n').trim();
+    if (s) segments.push(s);
+    buf = [];
+  };
+
+  for (const block of content) {
+    if (block.type === 'text') {
+      buf.push((block as ContentBlock & { type: 'text' }).text);
+    } else if (block.type === 'tool_use' || block.type === 'tool_result') {
+      flush();
+    }
+    // Other block types (thinking, redacted_thinking, image, …) are neither
+    // prose nor boundaries: they don't reach a channel and don't separate two
+    // prose messages, so they're skipped without flushing.
+  }
+  flush();
+
+  return segments;
+}