lemon-model 1.2.1 → 1.2.2

package/README.md

@@ -32,6 +32,7 @@ Frontend bundlers use the ESM build. Existing Node `require()` consumers use the
 | `types` | Shared request, identity, storage, and service shapes | Source types |
 | `cores` | Small shared transform helpers | Source tests |
 | `socket` | Peer socket, network contract, WebSocket bridge, JSON chunk transport | `src/socket/README.md` |
+| `buffer` | Provider-neutral GenAI stream buffering and network adapters | `src/buffer/README.md` |
 | `genai` | Gemini-like `generateContent()` adapter over Lemon agents APIs | `src/genai/README.md` |
 | `samples` | Real usage cases and PR-ready sample notes | `samples/README.md` |
 
@@ -68,12 +69,28 @@ flowchart TD
     B -- Yes --> D{Which behavior}
     D -- Data transforms --> E[Use cores]
     D -- Socket or network test --> F[Use socket]
+    D -- GenAI stream batching --> J[Use buffer]
     D -- Agents generateContent --> G[Use genai]
     F --> H[Read src/socket/README.md]
     G --> I[Read src/genai/README.md]
+    J --> K[Read src/buffer/README.md]
 ```
 
-Main branch: type-only, transform helper, socket flow, or GenAI proxy.
+Main branch: type-only, transform helper, socket flow, GenAI stream buffer, or GenAI proxy.
+
+## Buffer
+
+`buffer` provides provider-neutral stream primitives for GenAI responses.
+
+```ts
+import { GenAIStreamBuffer, createGenAIStreamNetworkConsumer } from 'lemon-model';
+```
+
+Use it when a provider emits small stream fragments and the app needs consistent `start`, `chunk`, `progress`, `flush`, `eof`, and `error` events.
+
+The network adapter can send `GenAIStreamEvent` over the shared socket/json-transport layer. Diagnostic helpers live under `lemon-model/buffer/testing`.
+
+Provider probe tools are available under `tools/`, but provider SDKs are not part of the runtime package contract. Install the matching SDK in the workspace where you run a probe.
 
 ## Build Formats
 
@@ -81,12 +98,13 @@ Main branch: type-only, transform helper, socket flow, or GenAI proxy.
 - ESM entry: `dist/esm/index.js`
 - Type declarations: `dist/index.d.ts`
 - Package export: `import { ... } from 'lemon-model'`
-- Test helper exports: `lemon-model/genai/testing`, `lemon-model/socket/testing`
+- Test helper exports: `lemon-model/genai/testing`, `lemon-model/buffer/testing`, `lemon-model/socket/testing`
 
 ## Module Docs
 
 - `src/socket/README.md`: peer socket and network contract
 - `src/socket/JSON_TRANSPORT_SPEC.md`: JSON chunk transport protocol
+- `src/buffer/README.md`: GenAI stream buffering and network adapter contract
 - `src/genai/README.md`: GenAI adapter contract
 - `samples/README.md`: sample case rules
 

package/dist/buffer/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `buffer/index.ts`
+ * - Public exports for token, stream, and network buffering utilities.
+ *
+ * @origin eureka-agents-api / src/lib/buffer/index.ts
+ */
+export * from './token';
+export * from './stream';
+export * from './network';

package/dist/buffer/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `buffer/index.ts`
+ * - Public exports for token, stream, and network buffering utilities.
+ *
+ * @origin eureka-agents-api / src/lib/buffer/index.ts
+ */
+__exportStar(require("./token"), exports);
+__exportStar(require("./stream"), exports);
+__exportStar(require("./network"), exports);
+//# sourceMappingURL=index.js.map

package/dist/buffer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/buffer/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;GAKG;AACH,0CAAwB;AACxB,2CAAyB;AACzB,4CAA0B"}

package/dist/buffer/network.d.ts

@@ -0,0 +1,89 @@
+/**
+ * `buffer/network.ts`
+ * - Network transport adapters and diagnostics for GenAI stream events.
+ *
+ * @origin eureka-agents-api / src/lib/buffer/network.ts
+ *
+ * GenAIStreamConsumer emits typed events, while NetworkSupportable only accepts
+ * raw strings and may enforce a packet-size limit. This adapter keeps those
+ * concerns separate by sending stream events through JSONTransport.
+ */
+import { JSONTransportOptions, JSONTransportSupportable } from '../socket/transport';
+import { NetworkSupportable, SocketErrorHandler, SocketUnsubscribe } from '../socket/types';
+import { GenAIStreamConsumer, GenAIStreamEvent } from './stream';
+export interface GenAIStreamNetworkPacket {
+    /** packet discriminator used after JSONTransport reassembly */
+    type: 'genai:stream';
+    /** compact logical stream/session id for multiplexing over one network */
+    sid?: string;
+    /** monotonically increasing event sequence assigned by the sender */
+    seq: number;
+    /** sender-side timestamp in epoch milliseconds */
+    sentAt: number;
+    /** original or wire-compacted GenAI stream event */
+    event: GenAIStreamEvent;
+    /** optional wire-compaction metadata used by restoreStreamEvent() */
+    compact?: GenAIStreamNetworkCompactMeta;
+}
+export interface GenAIStreamNetworkCompactMeta {
+    /** chunk data was removed because it can be reconstructed from flush.data */
+    flushChunksData?: 'fromFlushData';
+}
+export interface GenAIStreamNetworkOptions {
+    /** optional stream/session id carried with every network packet */
+    streamId?: string;
+    /** known raw network packet limit; used to derive JSONTransport chunkBytes */
+    maxPacketBytes?: number;
+    /** JSONTransport chunking/reassembly options */
+    jsonTransport?: JSONTransportOptions;
+    /** wait for network.ready() before each event send; defaults to true */
+    waitReady?: boolean;
+    /** observe errors thrown by the receiver-side consumer */
+    onConsumerError?: SocketErrorHandler;
+    /** observe every accepted stream network packet before forwarding its event */
+    onPacket?: (packet: GenAIStreamNetworkPacket) => void;
+    /** deliver stream packets by seq order; useful for unordered networks */
+    reorder?: boolean;
+    /** remove duplicated flush chunks[].data on the wire and restore it on receive */
+    compactFlush?: boolean;
+}
+export interface GenAIStreamNetworkConsumerHandle {
+    consumer: GenAIStreamConsumer;
+    transport: JSONTransportSupportable<GenAIStreamNetworkPacket>;
+    detach(): void;
+}
+export interface GenAIStreamNetworkReceiver {
+    transport: JSONTransportSupportable<GenAIStreamNetworkPacket>;
+    detach(): void;
+}
+export declare const asGenAIStreamNetworkTransportOptions: (options?: GenAIStreamNetworkOptions) => JSONTransportOptions | undefined;
+/**
+ * Create a GenAIStreamConsumer that serializes stream events and sends them over
+ * NetworkSupportable via JSONTransport.
+ *
+ * The returned consumer preserves the normal GenAIStreamConsumer contract. The
+ * only network-specific behavior is packet wrapping, optional flush compaction,
+ * and JSONTransport splitting for large string payloads.
+ */
+export declare const createGenAIStreamNetworkConsumer: (network: NetworkSupportable, options?: GenAIStreamNetworkOptions) => GenAIStreamNetworkConsumerHandle;
+/**
+ * Receive GenAI stream event packets from a NetworkSupportable and forward the
+ * rebuilt events to a GenAIStreamConsumer.
+ *
+ * When reorder is enabled, packets are held until their seq number can be
+ * delivered contiguously. This is intentionally stream-local; callers should set
+ * streamId when multiplexing multiple streams over one network. On the wire,
+ * that stream id is carried as the compact `sid` field.
+ */
+export declare const createGenAIStreamNetworkReceiver: (network: NetworkSupportable, consumer: GenAIStreamConsumer, options?: GenAIStreamNetworkOptions) => GenAIStreamNetworkReceiver;
+/** subscribe to JSONTransport/network errors from a stream network handle */
+export declare const onGenAIStreamNetworkError: (handle: GenAIStreamNetworkConsumerHandle | GenAIStreamNetworkReceiver, handler: SocketErrorHandler) => SocketUnsubscribe;
+export declare const compactStreamEvent: (event: GenAIStreamEvent) => {
+    event: GenAIStreamEvent;
+    compact?: GenAIStreamNetworkCompactMeta;
+};
+/**
+ * Restore a network packet into the public GenAIStreamEvent shape expected by
+ * downstream consumers.
+ */
+export declare const restoreStreamEvent: (packet: GenAIStreamNetworkPacket) => GenAIStreamEvent;

package/dist/buffer/network.js

@@ -0,0 +1,172 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.restoreStreamEvent = exports.compactStreamEvent = exports.onGenAIStreamNetworkError = exports.createGenAIStreamNetworkReceiver = exports.createGenAIStreamNetworkConsumer = exports.asGenAIStreamNetworkTransportOptions = void 0;
+/**
+ * `buffer/network.ts`
+ * - Network transport adapters and diagnostics for GenAI stream events.
+ *
+ * @origin eureka-agents-api / src/lib/buffer/network.ts
+ *
+ * GenAIStreamConsumer emits typed events, while NetworkSupportable only accepts
+ * raw strings and may enforce a packet-size limit. This adapter keeps those
+ * concerns separate by sending stream events through JSONTransport.
+ */
+const transport_1 = require("../socket/transport");
+// eslint-disable-next-line prettier/prettier
+const STREAM_EVENT_SPLIT_PATHS = ['/event/data', '/event/chunks/*/data', '/event/error/message', '/event/error/stack'];
+const asGenAIStreamNetworkTransportOptions = (options) => {
+    var _a, _b, _c;
+    const jsonTransport = (_a = options === null || options === void 0 ? void 0 : options.jsonTransport) !== null && _a !== void 0 ? _a : {};
+    const chunkBytes = (_b = jsonTransport.chunkBytes) !== null && _b !== void 0 ? _b : ((options === null || options === void 0 ? void 0 : options.maxPacketBytes)
+        ? (0, transport_1.calculateJSONTransportChunkBytes)(options.maxPacketBytes, jsonTransport.envelopeReserveBytes)
+        : undefined);
+    return Object.assign(Object.assign({}, jsonTransport), { chunkBytes, 
+        // eslint-disable-next-line prettier/prettier
+        preferredSplitPaths: [...STREAM_EVENT_SPLIT_PATHS, ...((_c = jsonTransport.preferredSplitPaths) !== null && _c !== void 0 ? _c : [])] });
+};
+exports.asGenAIStreamNetworkTransportOptions = asGenAIStreamNetworkTransportOptions;
+/**
+ * Create a GenAIStreamConsumer that serializes stream events and sends them over
+ * NetworkSupportable via JSONTransport.
+ *
+ * The returned consumer preserves the normal GenAIStreamConsumer contract. The
+ * only network-specific behavior is packet wrapping, optional flush compaction,
+ * and JSONTransport splitting for large string payloads.
+ */
+const createGenAIStreamNetworkConsumer = (network, options) => {
+    var _a;
+    const transport = (0, transport_1.createJSONTransport)(network, (0, exports.asGenAIStreamNetworkTransportOptions)(options));
+    const waitReady = (_a = options === null || options === void 0 ? void 0 : options.waitReady) !== null && _a !== void 0 ? _a : true;
+    let seq = 0;
+    const consumer = (event) => __awaiter(void 0, void 0, void 0, function* () {
+        if (waitReady && network.ready)
+            yield network.ready();
+        const compacted = (options === null || options === void 0 ? void 0 : options.compactFlush) ? (0, exports.compactStreamEvent)(event) : { event };
+        transport.send(Object.assign({ type: 'genai:stream', sid: options === null || options === void 0 ? void 0 : options.streamId, seq: seq++, sentAt: Date.now() }, compacted));
+    });
+    return {
+        consumer,
+        transport,
+        detach: () => transport.detach(),
+    };
+};
+exports.createGenAIStreamNetworkConsumer = createGenAIStreamNetworkConsumer;
+/**
+ * Receive GenAI stream event packets from a NetworkSupportable and forward the
+ * rebuilt events to a GenAIStreamConsumer.
+ *
+ * When reorder is enabled, packets are held until their seq number can be
+ * delivered contiguously. This is intentionally stream-local; callers should set
+ * streamId when multiplexing multiple streams over one network. On the wire,
+ * that stream id is carried as the compact `sid` field.
+ */
+const createGenAIStreamNetworkReceiver = (network, consumer, options) => {
+    const transport = (0, transport_1.createJSONTransport)(network, (0, exports.asGenAIStreamNetworkTransportOptions)(options));
+    // Reordering is deliberately simple: it waits for contiguous seq numbers
+    // from zero. A higher-level timeout policy should own missing packets.
+    let nextSeq = 0;
+    const pending = new Map();
+    const deliver = (packet) => {
+        const event = (0, exports.restoreStreamEvent)(packet);
+        void Promise.resolve(consumer(event)).catch(error => {
+            var _a;
+            (_a = options === null || options === void 0 ? void 0 : options.onConsumerError) === null || _a === void 0 ? void 0 : _a.call(options, error, { scope: 'genai.stream.consumer', network });
+        });
+    };
+    const accept = (packet) => {
+        var _a;
+        (_a = options === null || options === void 0 ? void 0 : options.onPacket) === null || _a === void 0 ? void 0 : _a.call(options, packet);
+        if (!(options === null || options === void 0 ? void 0 : options.reorder)) {
+            deliver(packet);
+            return;
+        }
+        pending.set(packet.seq, packet);
+        while (pending.has(nextSeq)) {
+            const ordered = pending.get(nextSeq);
+            pending.delete(nextSeq++);
+            deliver(ordered);
+        }
+    };
+    transport.onMessage(packet => {
+        if ((packet === null || packet === void 0 ? void 0 : packet.type) !== 'genai:stream')
+            return;
+        if ((options === null || options === void 0 ? void 0 : options.streamId) && packet.sid !== options.streamId)
+            return;
+        accept(packet);
+    });
+    return {
+        transport,
+        detach: () => transport.detach(),
+    };
+};
+exports.createGenAIStreamNetworkReceiver = createGenAIStreamNetworkReceiver;
+/** subscribe to JSONTransport/network errors from a stream network handle */
+const onGenAIStreamNetworkError = (handle, handler) => handle.transport.onError(handler);
+exports.onGenAIStreamNetworkError = onGenAIStreamNetworkError;
+const compactStreamEvent = (event) => {
+    if (event.type !== 'flush' || !canCompactFlushEvent(event))
+        return { event };
+    return {
+        event: Object.assign(Object.assign({}, event), { chunks: event.chunks.map(chunk => {
+                const { data: _data } = chunk, rest = __rest(chunk, ["data"]);
+                return rest;
+            }) }),
+        compact: { flushChunksData: 'fromFlushData' },
+    };
+};
+exports.compactStreamEvent = compactStreamEvent;
+/**
+ * Restore a network packet into the public GenAIStreamEvent shape expected by
+ * downstream consumers.
+ */
+const restoreStreamEvent = (packet) => {
+    var _a;
+    const event = packet.event;
+    if (event.type !== 'flush' || ((_a = packet.compact) === null || _a === void 0 ? void 0 : _a.flushChunksData) !== 'fromFlushData')
+        return event;
+    let offset = 0;
+    return Object.assign(Object.assign({}, event), { chunks: event.chunks.map(chunk => {
+            var _a;
+            const chars = (_a = chunk.chars) !== null && _a !== void 0 ? _a : 0;
+            const data = event.data.substring(offset, offset + chars);
+            offset += chars;
+            return Object.assign(Object.assign({}, chunk), { data });
+        }) });
+};
+exports.restoreStreamEvent = restoreStreamEvent;
+/**
+ * Flush events normally carry both joined data and per-chunk data. Compacting is
+ * safe only when chunk data is exactly contiguous within flush.data.
+ */
+const canCompactFlushEvent = (event) => {
+    var _a;
+    let offset = 0;
+    for (const chunk of event.chunks) {
+        const chars = (_a = chunk.chars) !== null && _a !== void 0 ? _a : chunk.data.length;
+        if (event.data.substring(offset, offset + chars) !== chunk.data)
+            return false;
+        offset += chars;
+    }
+    return offset === event.data.length;
+};
+//# sourceMappingURL=network.js.map

package/dist/buffer/network.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../../src/buffer/network.ts"],"names":[],"mappings":"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"}

package/dist/buffer/stream.d.ts

@@ -0,0 +1,220 @@
+/**
+ * `buffer/stream.ts`
+ * - Provider-neutral GenAI stream buffering primitives.
+ *
+ * @origin eureka-agents-api / src/lib/buffer/stream.ts
+ *
+ * Common stream buffering primitives for GenAI providers.
+ *
+ * This module is intentionally provider-neutral. Gemini/OpenAI adapters can
+ * convert their native stream chunks into GenAIStreamEvent and let this buffer
+ * handle batching, FIFO ordering, and progress calculation.
+ */
+export declare type GenAIStreamKind = 'text' | 'json' | 'image' | 'binary' | 'unknown';
+export declare type GenAIStreamFlushStrategy = 'size' | 'time' | 'bytes' | 'hybrid';
+export interface GenAIStreamEstimate {
+    /** expected generated character count, if known or estimated */
+    totalChars?: number;
+    /** expected generated byte count, if known or estimated */
+    totalBytes?: number;
+    /** expected generated token count, if known or estimated */
+    totalTokens?: number;
+    /** where the estimate came from, e.g. maxOutputTokens, sample, imageSize */
+    source?: string;
+    /** true when the value is inferred rather than exact */
+    estimated?: boolean;
+    /** optional confidence in [0, 1] */
+    confidence?: number;
+}
+export interface GenAIStreamProgress {
+    loadedChars: number;
+    loadedBytes: number;
+    loadedTokens?: number;
+    totalChars?: number;
+    totalBytes?: number;
+    totalTokens?: number;
+    /** stream-total progress from chars/bytes/tokens estimates, if available */
+    percent?: number;
+    /** buffer-cycle progress, always present while the buffer can estimate it */
+    bufferPercent?: number;
+    /** buffer-cycle progress source */
+    source?: 'chunk' | 'interval' | 'flush' | 'eof' | 'snapshot';
+    pendingChunks?: number;
+    pendingBytes?: number;
+    pendingChars?: number;
+    bufferElapsedMs?: number;
+    bufferTargetChunks?: number;
+    bufferTargetBytes?: number;
+    bufferTargetMs?: number;
+    estimated: boolean;
+}
+export interface GenAIStreamMeta {
+    provider?: string;
+    model?: string;
+    kind?: GenAIStreamKind;
+    estimate?: GenAIStreamEstimate;
+    [key: string]: any;
+}
+export interface GenAIStreamEventBase {
+    id?: string;
+    index?: number;
+    createdAt?: number;
+    meta?: GenAIStreamMeta;
+}
+export interface GenAIStreamStartEvent extends GenAIStreamEventBase {
+    type: 'start';
+    estimate?: GenAIStreamEstimate;
+}
+export interface GenAIStreamChunkEvent extends GenAIStreamEventBase {
+    type: 'chunk';
+    data: string;
+    chars?: number;
+    bytes?: number;
+    tokens?: number;
+    progress?: GenAIStreamProgress;
+}
+export interface GenAIStreamFlushEvent extends GenAIStreamEventBase {
+    type: 'flush';
+    data: string;
+    chunks: GenAIStreamChunkEvent[];
+    count: number;
+    chars: number;
+    bytes: number;
+    progress: GenAIStreamProgress;
+}
+export interface GenAIStreamProgressEvent extends GenAIStreamEventBase {
+    type: 'progress';
+    progress: GenAIStreamProgress;
+}
+export interface GenAIStreamEofEvent extends GenAIStreamEventBase {
+    type: 'eof';
+    progress: GenAIStreamProgress;
+}
+export interface GenAIStreamErrorEvent extends GenAIStreamEventBase {
+    type: 'error';
+    error: any;
+}
+export declare type GenAIStreamEvent = GenAIStreamStartEvent | GenAIStreamChunkEvent | GenAIStreamFlushEvent | GenAIStreamProgressEvent | GenAIStreamEofEvent | GenAIStreamErrorEvent;
+export interface GenAIStreamConsumer {
+    (event: GenAIStreamEvent): Promise<void> | void;
+}
+export interface GenAILegacyTokenConsumer {
+    (token?: string | null): Promise<void> | void;
+}
+export interface GenAIStreamBufferOptions {
+    /** disable buffering and flush every chunk immediately */
+    useBuffer?: boolean;
+    /** size: count, time: timer, bytes: bytes, hybrid: any condition */
+    flushStrategy?: GenAIStreamFlushStrategy;
+    /** chunk count threshold */
+    bufferSize?: number;
+    /** byte threshold */
+    bufferBytes?: number;
+    /** time strategy interval */
+    bufferMs?: number;
+    /** max wait for size/bytes/hybrid strategies */
+    maxWaitMs?: number;
+    /** initial stream metadata */
+    meta?: GenAIStreamMeta;
+    /** emit progress events after each accepted chunk */
+    emitProgress?: boolean;
+    /** emit current buffer progress on this interval while chunks are pending; 0 disables */
+    progressIntervalMs?: number;
+    /** emit an error and close the buffer if the stream stays open longer than this; 0 disables */
+    timeoutMs?: number;
+}
+export interface GenAIStreamBufferSnapshot {
+    pendingChunks: number;
+    pendingChars: number;
+    pendingBytes: number;
+    loadedChars: number;
+    loadedBytes: number;
+    loadedTokens?: number;
+    closed: boolean;
+    progress: GenAIStreamProgress;
+}
+export interface GenAIMockStreamOptions {
+    kind?: GenAIStreamKind;
+    provider?: string;
+    model?: string;
+    chunkSize?: number;
+    intervalMs?: number;
+    estimate?: GenAIStreamEstimate;
+}
+/**
+ * Estimate text output size from common generation hints.
+ */
+export declare const estimateGenAIStreamSize: (hint?: {
+    kind?: GenAIStreamKind;
+    maxOutputTokens?: number;
+    maxTokens?: number;
+    totalChars?: number;
+    totalBytes?: number;
+    totalTokens?: number;
+    imageSize?: '1k' | '2k' | '4k' | string;
+    imageFormat?: 'png' | 'jpeg' | 'jpg' | 'webp' | string;
+}) => GenAIStreamEstimate | undefined;
+/**
+ * FIFO stream buffer. Chunk events are queued and flushed as a single `flush`
+ * event when size/time/byte conditions are met.
+ */
+export declare class GenAIStreamBuffer {
+    private readonly consumer;
+    private readonly options;
+    private readonly meta?;
+    private queue;
+    private timer?;
+    private progressTimer?;
+    private timeoutTimer?;
+    private processing;
+    private closed;
+    private index;
+    private loadedChars;
+    private loadedBytes;
+    private loadedTokens;
+    private estimate?;
+    private cycleStartedAt?;
+    private lastProgress?;
+    constructor(consumer: GenAIStreamConsumer, options?: GenAIStreamBufferOptions);
+    start(meta?: GenAIStreamMeta): Promise<void>;
+    write(data: string, meta?: GenAIStreamMeta & {
+        tokens?: number;
+    }): Promise<void>;
+    push(event: string | GenAIStreamEvent): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    cancel(reason?: any): Promise<void>;
+    snapshot(): GenAIStreamBufferSnapshot;
+    private enqueue;
+    private normalizeEvent;
+    private normalizeChunk;
+    private asChunk;
+    private progress;
+    private bufferProgress;
+    private emitProgress;
+    private shouldFlush;
+    private scheduleFlush;
+    private scheduleProgress;
+    private scheduleTimeout;
+    private clearTimer;
+    private clearProgressTimer;
+    private clearTimeout;
+    private reportError;
+    private ensureOpen;
+}
+/**
+ * Convert a stream-event consumer into the existing token/null consumer shape.
+ */
+export declare const asLegacyTokenConsumer: (consumer: GenAIStreamConsumer) => GenAILegacyTokenConsumer;
+/**
+ * Convert a legacy token consumer into a stream-event consumer.
+ */
+export declare const asStreamConsumer: (consumer: GenAILegacyTokenConsumer) => GenAIStreamConsumer;
+/**
+ * Create provider-like mock stream events from a text payload.
+ */
+export declare function mockGenAIStream(content: string, options?: GenAIMockStreamOptions): AsyncGenerator<GenAIStreamEvent, void, unknown>;
+/**
+ * Run mock stream events through GenAIStreamBuffer.
+ */
+export declare const runMockGenAIStream: (content: string, consumer: GenAIStreamConsumer, bufferOptions?: GenAIStreamBufferOptions, mockOptions?: GenAIMockStreamOptions) => Promise<GenAIStreamBufferSnapshot>;