@animalabs/agent-framework 0.5.6 → 0.6.0

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[];
 
@@ -291,6 +315,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 +424,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 +502,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 +941,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

@@ -21,6 +21,7 @@ import type {
   SpeechContext,
   SpeechHandlerOptions,
   ProcessEvent,
+  TraceEventListener,
 } from './types/index.js';
 import type { Agent } from './agent.js';
 
@@ -53,6 +54,8 @@ export class ModuleRegistry {
   private queryMessagesFn: (filter: MessageQuery) => MessageQueryResult;
 
   private pushEventFn: (event: ProcessEvent) => void;
+  private onTraceFn: (listener: TraceEventListener) => () => void;
+  private callToolFn: (call: ToolCall) => Promise<ToolResult>;
 
   constructor(
     store: JsStore,
@@ -65,6 +68,8 @@ export class ModuleRegistry {
       getMessage: (id: MessageId) => StoredMessage | null;
       queryMessages: (filter: MessageQuery) => MessageQueryResult;
       pushEvent: (event: ProcessEvent) => void;
+      onTrace: (listener: TraceEventListener) => () => void;
+      callTool: (call: ToolCall) => Promise<ToolResult>;
     }
   ) {
     this.store = store;
@@ -76,6 +81,8 @@ export class ModuleRegistry {
     this.getMessageFn = options.getMessage;
     this.queryMessagesFn = options.queryMessages;
     this.pushEventFn = options.pushEvent;
+    this.onTraceFn = options.onTrace;
+    this.callToolFn = options.callTool;
   }
 
   /**
@@ -115,7 +122,9 @@ export class ModuleRegistry {
       this.removeMessageFn,
       this.getMessageFn,
       this.queryMessagesFn,
-      this.pushEventFn
+      this.pushEventFn,
+      this.onTraceFn,
+      this.callToolFn
     );
 
     this.modules.set(module.name, module);
@@ -366,6 +375,8 @@ 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;
+  private callToolFn: (call: ToolCall) => Promise<ToolResult>;
 
   // External ID mapping stored in module state
   private externalIdMap: Map<string, MessageId> = new Map();
@@ -383,7 +394,9 @@ 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,
+    callTool: (call: ToolCall) => Promise<ToolResult>
   ) {
     this.moduleName = moduleName;
     this.store = store;
@@ -398,6 +411,8 @@ class ModuleContextImpl implements ModuleContext {
     this.getMessageFn = getMessage;
     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> }>();
@@ -424,6 +439,14 @@ class ModuleContextImpl implements ModuleContext {
     return this.registry.getModule<T>(name);
   }
 
+  onTrace(listener: TraceEventListener): () => void {
+    return this.onTraceFn(listener);
+  }
+
+  callTool(call: ToolCall): Promise<ToolResult> {
+    return this.callToolFn(call);
+  }
+
   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/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;
+}