@witqq/agent-sdk 0.6.1 → 0.8.0

package/dist/chat/events.cjs

@@ -0,0 +1,203 @@
+'use strict';
+
+// src/chat/events.ts
+var TypedEventEmitter = class {
+  listeners = /* @__PURE__ */ new Map();
+  /**
+   * Subscribe to an event.
+   * @param event - Event name
+   * @param listener - Callback receiving the event payload
+   * @returns Unsubscribe function
+   */
+  on(event, listener) {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(event, set);
+    }
+    const fn = listener;
+    set.add(fn);
+    return () => {
+      set.delete(fn);
+      if (set.size === 0) {
+        this.listeners.delete(event);
+      }
+    };
+  }
+  /**
+   * Subscribe to an event, firing the listener at most once.
+   * @param event - Event name
+   * @param listener - Callback receiving the event payload
+   * @returns Unsubscribe function
+   */
+  once(event, listener) {
+    const unsub = this.on(event, (payload) => {
+      unsub();
+      listener(payload);
+    });
+    return unsub;
+  }
+  /**
+   * Remove a specific listener from an event.
+   * @param event - Event name
+   * @param listener - The listener to remove
+   */
+  off(event, listener) {
+    const set = this.listeners.get(event);
+    if (!set) return;
+    set.delete(listener);
+    if (set.size === 0) {
+      this.listeners.delete(event);
+    }
+  }
+  /**
+   * Emit an event, calling all registered listeners synchronously.
+   * @param event - Event name
+   * @param payload - Event payload
+   */
+  emit(event, payload) {
+    const set = this.listeners.get(event);
+    if (!set) return;
+    for (const fn of [...set]) {
+      fn(payload);
+    }
+  }
+  /**
+   * Remove all listeners for a specific event, or all events if no event specified.
+   * @param event - Optional event name
+   */
+  removeAllListeners(event) {
+    if (event !== void 0) {
+      this.listeners.delete(event);
+    } else {
+      this.listeners.clear();
+    }
+  }
+  /**
+   * Get the number of listeners for a specific event.
+   * @param event - Event name
+   * @returns Number of listeners
+   */
+  listenerCount(event) {
+    const set = this.listeners.get(event);
+    return set ? set.size : 0;
+  }
+  /**
+   * Get all event names that have at least one listener.
+   * @returns Array of event names
+   */
+  eventNames() {
+    return [...this.listeners.keys()];
+  }
+};
+var ChatEventBus = class extends TypedEventEmitter {
+  middlewares = [];
+  /**
+   * Register a middleware function. Middleware runs in registration order.
+   * @param middleware - Middleware function
+   * @returns Unsubscribe function to remove the middleware
+   */
+  use(middleware) {
+    this.middlewares.push(middleware);
+    return () => {
+      const idx = this.middlewares.indexOf(middleware);
+      if (idx !== -1) {
+        this.middlewares.splice(idx, 1);
+      }
+    };
+  }
+  /**
+   * Emit a chat event through the middleware pipeline, then to listeners.
+   *
+   * @param event - ChatEvent type string
+   * @param payload - The full ChatEvent object
+   */
+  emit(event, payload) {
+    if (this.middlewares.length === 0) {
+      super.emit(event, payload);
+      return;
+    }
+    let suppressed = false;
+    let currentEvent = payload;
+    let index = 0;
+    const runNext = () => {
+      if (suppressed) return;
+      if (index >= this.middlewares.length) {
+        super.emit(
+          currentEvent.type,
+          currentEvent
+        );
+        return;
+      }
+      const mw = this.middlewares[index++];
+      const ctx = {
+        event: currentEvent,
+        next: () => {
+          currentEvent = ctx.event;
+          runNext();
+        },
+        suppress: () => {
+          suppressed = true;
+        }
+      };
+      mw(ctx);
+    };
+    runNext();
+  }
+  /**
+   * Replace the event in the middleware context.
+   * Middleware should mutate ctx.event or create a new MiddlewareContext
+   * to transform events passing through the pipeline.
+   */
+  /**
+   * Remove all middleware functions.
+   */
+  clearMiddleware() {
+    this.middlewares.length = 0;
+  }
+  /**
+   * Get the number of registered middleware functions.
+   * @returns Number of middleware
+   */
+  middlewareCount() {
+    return this.middlewares.length;
+  }
+};
+function eventFilter(...types) {
+  const allowed = new Set(types);
+  return (event) => allowed.has(event.type);
+}
+async function* filterEvents(source, ...types) {
+  const pred = eventFilter(...types);
+  for await (const event of source) {
+    if (pred(event)) {
+      yield event;
+    }
+  }
+}
+async function* mapEvents(source, transform) {
+  for await (const event of source) {
+    const result = transform(event);
+    if (result !== null) {
+      yield result;
+    }
+  }
+}
+async function collectText(source) {
+  const parts = [];
+  for await (const event of source) {
+    if (event.type === "message:delta") {
+      parts.push(event.text);
+    }
+  }
+  return parts.join("");
+}
+
+exports.ChatEventBus = ChatEventBus;
+exports.TypedEventEmitter = TypedEventEmitter;
+exports.collectText = collectText;
+exports.eventFilter = eventFilter;
+exports.filterEvents = filterEvents;
+exports.mapEvents = mapEvents;
+//# sourceMappingURL=events.cjs.map
+//# sourceMappingURL=events.cjs.map

package/dist/chat/events.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/chat/events.ts"],"names":[],"mappings":"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","file":"events.cjs","sourcesContent":["/**\n * @witqq/agent-sdk/chat/events\n *\n * Type-safe event emitter, chat event bus, and middleware pipeline.\n * Generic TypedEventEmitter<EventMap> for arbitrary typed event maps.\n * ChatEventBus specializing TypedEventEmitter for ChatEvent types.\n * Middleware support for event interception, transformation, and suppression.\n * Utility functions for filtering and mapping event streams.\n */\n\nimport type { ChatEvent, ChatEventType } from \"./core.js\";\n\n// ─── EventMap constraint ──────────────────────────────────────\n\n/** Constraint for event maps: keys are strings, values are payloads */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type EventMap = Record<string, any>;\n\n// ─── Listener types ───────────────────────────────────────────\n\n/** Listener callback for a specific event */\nexport type Listener<T> = (payload: T) => void;\n\n/** Unsubscribe function returned by on/once */\nexport type Unsubscribe = () => void;\n\n// ─── TypedEventEmitter ────────────────────────────────────────\n\n/**\n * Generic type-safe event emitter parameterized by an EventMap.\n *\n * @typeParam T - Map of event names to payload types\n *\n * @example\n * ```typescript\n * type MyEvents = {\n *   message: string;\n *   count: number;\n *   done: void;\n * };\n * const emitter = new TypedEventEmitter<MyEvents>();\n * emitter.on(\"message\", (text) => console.log(text));\n * emitter.emit(\"message\", \"hello\");\n * ```\n */\nexport class TypedEventEmitter<T extends EventMap> {\n  private readonly listeners = new Map<keyof T, Set<Listener<unknown>>>();\n\n  /**\n   * Subscribe to an event.\n   * @param event - Event name\n   * @param listener - Callback receiving the event payload\n   * @returns Unsubscribe function\n   */\n  on<K extends keyof T>(event: K, listener: Listener<T[K]>): Unsubscribe {\n    let set = this.listeners.get(event);\n    if (!set) {\n      set = new Set();\n      this.listeners.set(event, set);\n    }\n    const fn = listener as Listener<unknown>;\n    set.add(fn);\n    return () => {\n      set!.delete(fn);\n      if (set!.size === 0) {\n        this.listeners.delete(event);\n      }\n    };\n  }\n\n  /**\n   * Subscribe to an event, firing the listener at most once.\n   * @param event - Event name\n   * @param listener - Callback receiving the event payload\n   * @returns Unsubscribe function\n   */\n  once<K extends keyof T>(event: K, listener: Listener<T[K]>): Unsubscribe {\n    const unsub = this.on(event, (payload) => {\n      unsub();\n      listener(payload);\n    });\n    return unsub;\n  }\n\n  /**\n   * Remove a specific listener from an event.\n   * @param event - Event name\n   * @param listener - The listener to remove\n   */\n  off<K extends keyof T>(event: K, listener: Listener<T[K]>): void {\n    const set = this.listeners.get(event);\n    if (!set) return;\n    set.delete(listener as Listener<unknown>);\n    if (set.size === 0) {\n      this.listeners.delete(event);\n    }\n  }\n\n  /**\n   * Emit an event, calling all registered listeners synchronously.\n   * @param event - Event name\n   * @param payload - Event payload\n   */\n  emit<K extends keyof T>(event: K, payload: T[K]): void {\n    const set = this.listeners.get(event);\n    if (!set) return;\n    for (const fn of [...set]) {\n      fn(payload);\n    }\n  }\n\n  /**\n   * Remove all listeners for a specific event, or all events if no event specified.\n   * @param event - Optional event name\n   */\n  removeAllListeners<K extends keyof T>(event?: K): void {\n    if (event !== undefined) {\n      this.listeners.delete(event);\n    } else {\n      this.listeners.clear();\n    }\n  }\n\n  /**\n   * Get the number of listeners for a specific event.\n   * @param event - Event name\n   * @returns Number of listeners\n   */\n  listenerCount<K extends keyof T>(event: K): number {\n    const set = this.listeners.get(event);\n    return set ? set.size : 0;\n  }\n\n  /**\n   * Get all event names that have at least one listener.\n   * @returns Array of event names\n   */\n  eventNames(): Array<keyof T> {\n    return [...this.listeners.keys()];\n  }\n}\n\n// ─── ChatEventMap ─────────────────────────────────────────────\n\n/**\n * Map of ChatEvent type strings to their corresponding ChatEvent payloads.\n * Used to parameterize TypedEventEmitter for chat events.\n */\nexport type ChatEventMap = {\n  [K in ChatEventType]: Extract<ChatEvent, { type: K }>;\n};\n\n// ─── Middleware ────────────────────────────────────────────────\n\n/**\n * Context passed to middleware functions.\n * Contains the event and control methods for the middleware pipeline.\n */\nexport interface MiddlewareContext {\n  /** The current event (may be transformed by prior middleware) */\n  event: ChatEvent;\n  /** Call the next middleware in the chain, or deliver to listeners if last */\n  next: () => void;\n  /** Suppress the event — do not deliver to listeners or subsequent middleware */\n  suppress: () => void;\n}\n\n/**\n * Middleware function for intercepting, transforming, or suppressing events.\n * EventMiddleware operates at the ChatEventBus level.\n *\n * @param ctx - Middleware context with event, next(), and suppress()\n *\n * @example\n * ```typescript\n * // Logging middleware\n * const logger: EventMiddleware = (ctx) => {\n *   console.log(`Event: ${ctx.event.type}`);\n *   ctx.next();\n * };\n *\n * // Suppressing middleware\n * const filter: EventMiddleware = (ctx) => {\n *   if (ctx.event.type === \"heartbeat\") {\n *     ctx.suppress();\n *   } else {\n *     ctx.next();\n *   }\n * };\n * ```\n */\nexport type EventMiddleware = (ctx: MiddlewareContext) => void;\n\n// ─── ChatEventBus ─────────────────────────────────────────────\n\n/**\n * Chat event bus: a typed event emitter specialized for ChatEvent types\n * with middleware pipeline support.\n *\n * Events pass through the middleware pipeline before reaching listeners.\n * Middleware can inspect, transform, or suppress events.\n *\n * @example\n * ```typescript\n * const bus = new ChatEventBus();\n *\n * // Add middleware\n * bus.use((ctx) => {\n *   console.log(`[${ctx.event.type}]`);\n *   ctx.next();\n * });\n *\n * // Listen for events\n * bus.on(\"message:delta\", (event) => {\n *   console.log(event.text);\n * });\n *\n * // Emit events\n * bus.emit(\"message:delta\", { type: \"message:delta\", messageId: id, text: \"hi\" });\n * ```\n */\nexport class ChatEventBus extends TypedEventEmitter<ChatEventMap> {\n  private readonly middlewares: EventMiddleware[] = [];\n\n  /**\n   * Register a middleware function. Middleware runs in registration order.\n   * @param middleware - Middleware function\n   * @returns Unsubscribe function to remove the middleware\n   */\n  use(middleware: EventMiddleware): Unsubscribe {\n    this.middlewares.push(middleware);\n    return () => {\n      const idx = this.middlewares.indexOf(middleware);\n      if (idx !== -1) {\n        this.middlewares.splice(idx, 1);\n      }\n    };\n  }\n\n  /**\n   * Emit a chat event through the middleware pipeline, then to listeners.\n   *\n   * @param event - ChatEvent type string\n   * @param payload - The full ChatEvent object\n   */\n  override emit<K extends ChatEventType>(\n    event: K,\n    payload: ChatEventMap[K],\n  ): void {\n    if (this.middlewares.length === 0) {\n      super.emit(event, payload);\n      return;\n    }\n\n    let suppressed = false;\n    let currentEvent: ChatEvent = payload;\n    let index = 0;\n\n    const runNext = (): void => {\n      if (suppressed) return;\n\n      if (index >= this.middlewares.length) {\n        super.emit(\n          currentEvent.type as K,\n          currentEvent as ChatEventMap[K],\n        );\n        return;\n      }\n\n      const mw = this.middlewares[index++];\n      const ctx: MiddlewareContext = {\n        event: currentEvent,\n        next: () => {\n          currentEvent = ctx.event;\n          runNext();\n        },\n        suppress: () => {\n          suppressed = true;\n        },\n      };\n      mw(ctx);\n    };\n\n    runNext();\n  }\n\n  /**\n   * Replace the event in the middleware context.\n   * Middleware should mutate ctx.event or create a new MiddlewareContext\n   * to transform events passing through the pipeline.\n   */\n\n  /**\n   * Remove all middleware functions.\n   */\n  clearMiddleware(): void {\n    this.middlewares.length = 0;\n  }\n\n  /**\n   * Get the number of registered middleware functions.\n   * @returns Number of middleware\n   */\n  middlewareCount(): number {\n    return this.middlewares.length;\n  }\n}\n\n// ─── Utility: Event Filtering ─────────────────────────────────\n\n/**\n * Create a filter function that passes only events of specified types.\n *\n * @param types - Event types to allow through\n * @returns Predicate function for filtering ChatEvents\n *\n * @example\n * ```typescript\n * const isTextEvent = eventFilter(\"message:start\", \"message:delta\", \"message:complete\");\n * const textEvents = allEvents.filter(isTextEvent);\n * ```\n */\nexport function eventFilter(\n  ...types: ChatEventType[]\n): (event: ChatEvent) => boolean {\n  const allowed = new Set<string>(types);\n  return (event: ChatEvent) => allowed.has(event.type);\n}\n\n/**\n * Filter an async iterable of ChatEvents to only specified types.\n *\n * @param source - Async iterable of ChatEvents\n * @param types - Event types to keep\n * @returns Async iterable of filtered ChatEvents\n *\n * @example\n * ```typescript\n * for await (const event of filterEvents(stream, \"message:delta\", \"message:complete\")) {\n *   // only message:delta and message:complete events\n * }\n * ```\n */\nexport async function* filterEvents(\n  source: AsyncIterable<ChatEvent>,\n  ...types: ChatEventType[]\n): AsyncIterable<ChatEvent> {\n  const pred = eventFilter(...types);\n  for await (const event of source) {\n    if (pred(event)) {\n      yield event;\n    }\n  }\n}\n\n// ─── Utility: Event Mapping ───────────────────────────────────\n\n/**\n * Map/transform events from an async iterable.\n *\n * @param source - Async iterable of ChatEvents\n * @param transform - Function to transform each event (return null to skip)\n * @returns Async iterable of transformed values\n *\n * @example\n * ```typescript\n * // Extract text from message:delta events\n * const texts = mapEvents(stream, (event) =>\n *   event.type === \"message:delta\" ? event.text : null\n * );\n * ```\n */\nexport async function* mapEvents<R>(\n  source: AsyncIterable<ChatEvent>,\n  transform: (event: ChatEvent) => R | null,\n): AsyncIterable<R> {\n  for await (const event of source) {\n    const result = transform(event);\n    if (result !== null) {\n      yield result;\n    }\n  }\n}\n\n/**\n * Collect text from message:delta events into a single string.\n *\n * @param source - Async iterable of ChatEvents\n * @returns Complete text assembled from message:delta payloads\n *\n * @example\n * ```typescript\n * const fullText = await collectText(stream);\n * ```\n */\nexport async function collectText(\n  source: AsyncIterable<ChatEvent>,\n): Promise<string> {\n  const parts: string[] = [];\n  for await (const event of source) {\n    if (event.type === \"message:delta\") {\n      parts.push(event.text);\n    }\n  }\n  return parts.join(\"\");\n}\n"]}

package/dist/chat/events.d.cts

@@ -0,0 +1,245 @@
+import { C as ChatEventType, a as ChatEvent } from '../types-DRgd_9R7.cjs';
+import '../agent-DxY68NZL.cjs';
+import 'zod';
+import '../errors-C-so0M4t.cjs';
+import '../types-4vbcmPTp.cjs';
+import '../errors-CmVvczxZ.cjs';
+
+/**
+ * @witqq/agent-sdk/chat/events
+ *
+ * Type-safe event emitter, chat event bus, and middleware pipeline.
+ * Generic TypedEventEmitter<EventMap> for arbitrary typed event maps.
+ * ChatEventBus specializing TypedEventEmitter for ChatEvent types.
+ * Middleware support for event interception, transformation, and suppression.
+ * Utility functions for filtering and mapping event streams.
+ */
+
+/** Constraint for event maps: keys are strings, values are payloads */
+type EventMap = Record<string, any>;
+/** Listener callback for a specific event */
+type Listener<T> = (payload: T) => void;
+/** Unsubscribe function returned by on/once */
+type Unsubscribe = () => void;
+/**
+ * Generic type-safe event emitter parameterized by an EventMap.
+ *
+ * @typeParam T - Map of event names to payload types
+ *
+ * @example
+ * ```typescript
+ * type MyEvents = {
+ *   message: string;
+ *   count: number;
+ *   done: void;
+ * };
+ * const emitter = new TypedEventEmitter<MyEvents>();
+ * emitter.on("message", (text) => console.log(text));
+ * emitter.emit("message", "hello");
+ * ```
+ */
+declare class TypedEventEmitter<T extends EventMap> {
+    private readonly listeners;
+    /**
+     * Subscribe to an event.
+     * @param event - Event name
+     * @param listener - Callback receiving the event payload
+     * @returns Unsubscribe function
+     */
+    on<K extends keyof T>(event: K, listener: Listener<T[K]>): Unsubscribe;
+    /**
+     * Subscribe to an event, firing the listener at most once.
+     * @param event - Event name
+     * @param listener - Callback receiving the event payload
+     * @returns Unsubscribe function
+     */
+    once<K extends keyof T>(event: K, listener: Listener<T[K]>): Unsubscribe;
+    /**
+     * Remove a specific listener from an event.
+     * @param event - Event name
+     * @param listener - The listener to remove
+     */
+    off<K extends keyof T>(event: K, listener: Listener<T[K]>): void;
+    /**
+     * Emit an event, calling all registered listeners synchronously.
+     * @param event - Event name
+     * @param payload - Event payload
+     */
+    emit<K extends keyof T>(event: K, payload: T[K]): void;
+    /**
+     * Remove all listeners for a specific event, or all events if no event specified.
+     * @param event - Optional event name
+     */
+    removeAllListeners<K extends keyof T>(event?: K): void;
+    /**
+     * Get the number of listeners for a specific event.
+     * @param event - Event name
+     * @returns Number of listeners
+     */
+    listenerCount<K extends keyof T>(event: K): number;
+    /**
+     * Get all event names that have at least one listener.
+     * @returns Array of event names
+     */
+    eventNames(): Array<keyof T>;
+}
+/**
+ * Map of ChatEvent type strings to their corresponding ChatEvent payloads.
+ * Used to parameterize TypedEventEmitter for chat events.
+ */
+type ChatEventMap = {
+    [K in ChatEventType]: Extract<ChatEvent, {
+        type: K;
+    }>;
+};
+/**
+ * Context passed to middleware functions.
+ * Contains the event and control methods for the middleware pipeline.
+ */
+interface MiddlewareContext {
+    /** The current event (may be transformed by prior middleware) */
+    event: ChatEvent;
+    /** Call the next middleware in the chain, or deliver to listeners if last */
+    next: () => void;
+    /** Suppress the event — do not deliver to listeners or subsequent middleware */
+    suppress: () => void;
+}
+/**
+ * Middleware function for intercepting, transforming, or suppressing events.
+ * EventMiddleware operates at the ChatEventBus level.
+ *
+ * @param ctx - Middleware context with event, next(), and suppress()
+ *
+ * @example
+ * ```typescript
+ * // Logging middleware
+ * const logger: EventMiddleware = (ctx) => {
+ *   console.log(`Event: ${ctx.event.type}`);
+ *   ctx.next();
+ * };
+ *
+ * // Suppressing middleware
+ * const filter: EventMiddleware = (ctx) => {
+ *   if (ctx.event.type === "heartbeat") {
+ *     ctx.suppress();
+ *   } else {
+ *     ctx.next();
+ *   }
+ * };
+ * ```
+ */
+type EventMiddleware = (ctx: MiddlewareContext) => void;
+/**
+ * Chat event bus: a typed event emitter specialized for ChatEvent types
+ * with middleware pipeline support.
+ *
+ * Events pass through the middleware pipeline before reaching listeners.
+ * Middleware can inspect, transform, or suppress events.
+ *
+ * @example
+ * ```typescript
+ * const bus = new ChatEventBus();
+ *
+ * // Add middleware
+ * bus.use((ctx) => {
+ *   console.log(`[${ctx.event.type}]`);
+ *   ctx.next();
+ * });
+ *
+ * // Listen for events
+ * bus.on("message:delta", (event) => {
+ *   console.log(event.text);
+ * });
+ *
+ * // Emit events
+ * bus.emit("message:delta", { type: "message:delta", messageId: id, text: "hi" });
+ * ```
+ */
+declare class ChatEventBus extends TypedEventEmitter<ChatEventMap> {
+    private readonly middlewares;
+    /**
+     * Register a middleware function. Middleware runs in registration order.
+     * @param middleware - Middleware function
+     * @returns Unsubscribe function to remove the middleware
+     */
+    use(middleware: EventMiddleware): Unsubscribe;
+    /**
+     * Emit a chat event through the middleware pipeline, then to listeners.
+     *
+     * @param event - ChatEvent type string
+     * @param payload - The full ChatEvent object
+     */
+    emit<K extends ChatEventType>(event: K, payload: ChatEventMap[K]): void;
+    /**
+     * Replace the event in the middleware context.
+     * Middleware should mutate ctx.event or create a new MiddlewareContext
+     * to transform events passing through the pipeline.
+     */
+    /**
+     * Remove all middleware functions.
+     */
+    clearMiddleware(): void;
+    /**
+     * Get the number of registered middleware functions.
+     * @returns Number of middleware
+     */
+    middlewareCount(): number;
+}
+/**
+ * Create a filter function that passes only events of specified types.
+ *
+ * @param types - Event types to allow through
+ * @returns Predicate function for filtering ChatEvents
+ *
+ * @example
+ * ```typescript
+ * const isTextEvent = eventFilter("message:start", "message:delta", "message:complete");
+ * const textEvents = allEvents.filter(isTextEvent);
+ * ```
+ */
+declare function eventFilter(...types: ChatEventType[]): (event: ChatEvent) => boolean;
+/**
+ * Filter an async iterable of ChatEvents to only specified types.
+ *
+ * @param source - Async iterable of ChatEvents
+ * @param types - Event types to keep
+ * @returns Async iterable of filtered ChatEvents
+ *
+ * @example
+ * ```typescript
+ * for await (const event of filterEvents(stream, "message:delta", "message:complete")) {
+ *   // only message:delta and message:complete events
+ * }
+ * ```
+ */
+declare function filterEvents(source: AsyncIterable<ChatEvent>, ...types: ChatEventType[]): AsyncIterable<ChatEvent>;
+/**
+ * Map/transform events from an async iterable.
+ *
+ * @param source - Async iterable of ChatEvents
+ * @param transform - Function to transform each event (return null to skip)
+ * @returns Async iterable of transformed values
+ *
+ * @example
+ * ```typescript
+ * // Extract text from message:delta events
+ * const texts = mapEvents(stream, (event) =>
+ *   event.type === "message:delta" ? event.text : null
+ * );
+ * ```
+ */
+declare function mapEvents<R>(source: AsyncIterable<ChatEvent>, transform: (event: ChatEvent) => R | null): AsyncIterable<R>;
+/**
+ * Collect text from message:delta events into a single string.
+ *
+ * @param source - Async iterable of ChatEvents
+ * @returns Complete text assembled from message:delta payloads
+ *
+ * @example
+ * ```typescript
+ * const fullText = await collectText(stream);
+ * ```
+ */
+declare function collectText(source: AsyncIterable<ChatEvent>): Promise<string>;
+
+export { ChatEventBus, type ChatEventMap, type EventMap, type EventMiddleware, type Listener, type MiddlewareContext, TypedEventEmitter, type Unsubscribe, collectText, eventFilter, filterEvents, mapEvents };