Streaming and replay

/**
 * Render an `agent.stream()` source as a Vercel-compatible UI message stream.
 *
 * The returned `ReadableStream<Uint8Array>` can be wrapped in a `Response`
 * (web / edge / fetch) or piped to a Node `ServerResponse`.
 */
export declare function agentUIStream(agent: Agent | AgentLike, input: string, options?: AgentUIStreamOptions): ReadableStream<Uint8Array>;

/**
 * Vercel AI SDK UI Message Stream adapter.
 *
 * Converts the chunks emitted by `agent.stream(...)` into the line-delimited
 * JSON protocol consumed by Vercel's `useChat` / `createAgentUIStreamResponse`.
 *
 * Spec: https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol
 */
export interface AgentUIStreamOptions {
    /** sessionId forwarded to `agent.run` / `agent.stream`. */
    sessionId?: string;
    /** userId forwarded to `agent.run` / `agent.stream`. */
    userId?: string;
    /** Optional per-request API key override. */
    apiKey?: string;
    /** Optional abort signal to cancel the run. */
    signal?: AbortSignal;
}

/**
 * Create a `Response` whose body streams Vercel UI messages. Use as the return
 * value of a Web / Edge / Next.js Route Handler.
 *
 * @example
 * ```ts
 * import { createAgentUIStreamResponse } from "@agentium/transport";
 *
 * export async function POST(req: Request) {
 *   const { input, sessionId } = await req.json();
 *   return createAgentUIStreamResponse(agent, input, { sessionId });
 * }
 * ```
 */
export declare function createAgentUIStreamResponse(agent: Agent | AgentLike, input: string, options?: AgentUIStreamOptions): Response;

export declare const defaultEventLog: InMemoryEventLog;

/** Format an `SSEEvent` for the wire. */
export declare function formatSSEEvent(ev: SSEEvent): string;

export declare class InMemoryEventLog implements SSEEventLog {
    constructor(config?: InMemoryEventLogConfig);
    record(runId: string, event: Omit<SSEEvent, "id" | "recordedAt">): SSEEvent;
    since(runId: string, afterId: number): SSEEvent[];
    all(runId: string): SSEEvent[];
    finalize(runId: string): void;
    drop(runId: string): void;
}

export interface InMemoryEventLogConfig {
    /** Max events kept per run. Oldest evicted when exceeded. Default: 1024. */
    maxEventsPerRun?: number;
    /** Milliseconds after finalize before a run's buffer is dropped. Default: 300_000 (5min). */
    ttlMs?: number;
}

/**
 * Pipe a Vercel UI message stream into a Node `ServerResponse` (Express style).
 */
export declare function pipeAgentUIStreamToResponse(agent: Agent | AgentLike, input: string, res: any, options?: AgentUIStreamOptions): Promise<void>;

/**
 * Per-run in-memory ring buffer of SSE events. Each event gets a monotonically
 * increasing numeric `id` so clients can pass `Last-Event-ID` on reconnect and
 * replay missed events.
 *
 * Storage is intentionally in-process; for multi-instance deployments, plug a
 * Redis-backed implementation behind the same interface.
 */
export interface SSEEvent {
    /** Monotonic numeric ID. */
    id: number;
    /** Optional `event:` line value. Default omitted. */
    event?: string;
    /** Payload (will be JSON-stringified into the `data:` field). */
    payload: unknown;
    /** Wall-clock time the event was recorded. */
    recordedAt: number;
}

export interface SSEEventLog {
    /** Record a new event and return its assigned id. */
    record(runId: string, event: Omit<SSEEvent, "id" | "recordedAt">): SSEEvent;
    /** Return events for a run with id greater than `afterId`. */
    since(runId: string, afterId: number): SSEEvent[];
    /** All events for a run. */
    all(runId: string): SSEEvent[];
    /** Mark a run completed (frees buffers after `ttlMs`). */
    finalize(runId: string): void;
    /** Remove a run's buffer immediately. */
    drop(runId: string): void;
}

export interface TextStreamLimits {
    /** Maximum encoded frame and queued response bytes. Default 256 KiB each. */
    maxFrameBytes?: number;
    maxBufferedBytes?: number;
    /** Maximum wait for a writable drain. Default 10 seconds. */
    writeTimeoutMs?: number;
}

interface AgentLike {
    stream(input: string, opts?: {
        sessionId?: string;
        userId?: string;
        apiKey?: string;
        signal?: AbortSignal;
    }): AsyncIterable<AgentLikeChunk>;
}

interface AgentLikeChunk {
    type?: string;
    text?: string;
    delta?: string;
    toolCallId?: string;
    toolName?: string;
    arguments?: unknown;
    args?: unknown;
    input?: unknown;
    output?: unknown;
    result?: unknown;
    finishReason?: string;
    usage?: {
        promptTokens?: number;
        completionTokens?: number;
        totalTokens?: number;
    };
    error?: string | {
        message?: string;
    };
    reasoning?: string;
    thinking?: string;
}