@aexhq/sdk 0.46.4-canary → 0.50.0

package/dist/_contracts/event-envelope.js

@@ -1,501 +0,0 @@
-/**
- * The unified aex event envelope.
- *
- * One versioned, self-describing record that every subscriber sees, derived
- * from the unified {@link RunnerEvent}. Managed runtime adapters emit
- * byte-identical envelopes for the same logical event by construction. This is
- * the shape the coordinator (Phase 2) appends, broadcasts, and archives.
- *
- *   - **CloudEvents-shaped** self-describing envelope: a stable `id`, the
- *     coarse `source`, the AG-UI-aligned `type`, the `subject` (session), a
- *     `time`, the `sequence` cursor, and the typed `data`.
- *   - **AG-UI vocabulary** for `type` where it maps; aex-specific events
- *     ride AG-UI's reserved `CUSTOM` carrier under an `aex.*` name, so an
- *     off-the-shelf AG-UI client reads an aex start with no glue.
- *   - Two aex extensions: a coarse `source` (filter first by origin) and
- *     an optional human `message` (log / CLI / dashboard rendering).
- *
- * Unified observability spine:
- * the envelope additionally carries four ordering attributes so BOTH the typed
- * event stream and the high-volume hosted-platform log stream ride one per-session
- * coordinator:
- *   - `channel`   — "event" (the typed AG-UI stream) or "log" (a verbose log
- *                   line). The single axis a consumer splits the unified stream
- *                   on.
- *   - `sourceSeq` — a per-SOURCE monotonic counter assigned AT the source. The
- *                   DO's hard guarantee is that records of the same source are
- *                   never reordered relative to their `sourceSeq`.
- *   - `emittedAt` — source wall-clock ms at emit. Carried, never trusted for
- *                   cross-source ordering (clocks are independent; the coordinator gives
- *                   no synchronized clock). A client may re-sort by it for a
- *                   best-effort time view.
- * The coordinator remains the single serial ordering authority: it assigns the global
- * `sequence` on arrival, which is the canonical stream order. `sourceSeq` /
- * `emittedAt` are CARRIED through broadcast + archive, not used to reorder.
- *
- * This module is a pure projection plus honest guards and a strict AG-UI
- * projection for consumers.
- */
-import { SESSION_TERMINAL_OUTCOMES } from "./status.js";
-import { AEX_FAILURE_CLASSES, isAexFailureClass } from "./failure-class.js";
-import { parseProviderFault } from "./provider-fault.js";
-/** CloudEvents `specversion` the envelope conforms to. */
-export const AEX_EVENT_SPECVERSION = "1.0";
-/**
- * Mapping version. Bump when the RunnerEvent → envelope projection changes
- * shape (new `source`/`type`, renamed data field). Independent of
- * {@link AEX_EVENT_SPECVERSION} (the CloudEvents version) and of
- * `RUNNER_EVENT_VERSION` (the upstream wire version).
- */
-export const AEX_EVENT_MAP_VERSION = 2;
-/**
- * Coarse origin classifier — the first axis a consumer filters on.
- *   - `agent`   — the model: text, reasoning, builtin tool calls/results.
- *   - `api`     — the hosted aex API path.
- *   - `runtime` — the execution runtime: lifecycle, diagnostics, non-fatal
- *                 stream errors.
- *   - `mcp`     — an MCP server (a tool call/result routed through MCP).
- *   - `aex` — the platform: skills, files, and other aex-native events.
- *   - `workflow`— the orchestration layer.
- *   - `host`    — the managed host the runtime executes on; distinct from the
- *                 runtime process itself.
- */
-export const AEX_EVENT_SOURCES = ["agent", "api", "runtime", "mcp", "aex", "workflow", "host"];
-/**
- * The channel a record rides on the unified per-session stream:
- *   - `event` — the typed, low-volume, fully-replayed AG-UI event stream.
- *   - `log`   — a high-volume verbose log line (level + message + fields). The
- *               coordinator prunes flushed log rows after evidence archival
- *               (logs are append-only, events are kept). Absent on the wire ⇒
- *               `event`.
- */
-export const AEX_EVENT_CHANNELS = ["event", "log"];
-/**
- * Log severity carried by a `channel: "log"` record (the `LOG` event type).
- * NOTE: the platform owner's canonical term for the middle level is "warning";
- * we keep "warn" for consistency with the existing in-code vocabulary — the
- * mapping is `warning ≡ warn`.
- */
-export const AEX_LOG_LEVELS = ["info", "warn", "error"];
-/**
- * The AG-UI-aligned `type` vocabulary the envelope emits. A subset of the
- * full AG-UI protocol — the events aex actually produces today — plus
- * `CUSTOM`, AG-UI's reserved carrier for aex-native events.
- */
-export const AEX_EVENT_TYPES = [
-    "RUN_STARTED",
-    "RUN_FINISHED",
-    "RUN_ERROR",
-    "TEXT_MESSAGE_CONTENT",
-    "TOOL_CALL_START",
-    "TOOL_CALL_RESULT",
-    "CUSTOM",
-    // The carrier type for a `channel: "log"` record. Kept out of the AG-UI
-    // typed-event vocabulary on purpose: a `LOG` is never a session-lifecycle signal,
-    // so terminal detection (RUN_FINISHED/RUN_ERROR) is unaffected and an
-    // off-the-shelf AG-UI client filters logs out by `channel`.
-    "LOG"
-];
-/** Explicit failure thrown when a malformed known event is projected. */
-export class MalformedAexEventError extends Error {
-    code = "malformed_known_event";
-    issue;
-    constructor(issue) {
-        super(`Malformed ${issue.type} event: ${issue.path} must be ${issue.expected}`);
-        this.name = "MalformedAexEventError";
-        this.issue = issue;
-    }
-}
-/** True only for a provisional frame outside the durable replay sequence. */
-export function isAexLiveEvent(event) {
-    return event.replayable === false;
-}
-/** True only for a durable event carrying a replay cursor. */
-export function isReplayableEvent(event) {
-    return event.replayable !== false && typeof event.sequence === "number";
-}
-/** Compatibility spelling used by the hosted platform. */
-export const isReplayableAexEvent = isReplayableEvent;
-/**
- * Project a {@link RunnerEvent} onto the unified public envelope. Internal
- * runtime completion has no public projection: only the platform-authored
- * RUN_FINISHED/RUN_ERROR event is a completion boundary.
- */
-export function runnerEventToAexEvent(evt, ctx) {
-    const projection = project(evt);
-    if (projection === null)
-        return null;
-    const event = {
-        specversion: AEX_EVENT_SPECVERSION,
-        id: `${ctx.sessionId}:${evt.seq}`,
-        source: projection.source,
-        type: projection.type,
-        subject: ctx.sessionId,
-        threadId: ctx.sessionId,
-        runId: ctx.runId,
-        time: new Date(ctx.baseMs + evt.tMs).toISOString(),
-        sequence: evt.seq,
-        ...(evt.sourceSeq !== undefined ? { sourceSeq: evt.sourceSeq } : {}),
-        ...(evt.emittedAt !== undefined ? { emittedAt: evt.emittedAt } : {}),
-        ...(projection.message !== undefined ? { message: projection.message } : {}),
-        data: Object.freeze(projection.data)
-    };
-    const classified = classifyAexEvent(event);
-    if (classified.kind === "malformed_known") {
-        throw new MalformedAexEventError(classified.issue);
-    }
-    return event;
-}
-function project(evt) {
-    const data = evt.data;
-    switch (evt.kind) {
-        case "runtime_started":
-            return { type: "RUN_STARTED", source: "runtime", message: "turn started", data: { ...data } };
-        case "assistant_text": {
-            const text = typeof data.text === "string" ? data.text : undefined;
-            return {
-                type: "TEXT_MESSAGE_CONTENT",
-                source: "agent",
-                ...(text ? { message: clip(text) } : {}),
-                data: { ...data }
-            };
-        }
-        case "tool_request": {
-            const name = typeof data.name === "string" ? data.name : undefined;
-            return {
-                type: "TOOL_CALL_START",
-                source: data.extension ? "mcp" : "agent",
-                ...(name ? { message: `tool ${name}` } : {}),
-                data: { ...data }
-            };
-        }
-        case "tool_response":
-            return {
-                type: "TOOL_CALL_RESULT",
-                source: data.extension ? "mcp" : "agent",
-                data: { ...data }
-            };
-        case "skill_loaded":
-            return custom("aex.skill_loaded", "aex", data, "skill loaded");
-        case "file_uploaded":
-            return custom("aex.file_uploaded", "aex", data, "file uploaded");
-        case "notification":
-            return custom("aex.notification", "runtime", data, typeof data.reason === "string" && data.reason.length > 0 ? data.reason : undefined);
-        case "stream_error":
-            return custom("aex.stream_error", "runtime", data, typeof data.message === "string" && data.message.length > 0 ? data.message : "stream error");
-        case "runtime_terminal":
-            return null;
-    }
-}
-/**
- * Project a log line onto an inbound coordinator envelope. The coordinator
- * stamps `specversion`/`id`/`subject`/`sequence` on ingest (it is the ordering
- * authority); everything else — `channel`, `source`, `sourceSeq`, `emittedAt`,
- * and the `LOG` payload — is supplied here.
- */
-export function logToInbound(source, line) {
-    return {
-        source,
-        type: "LOG",
-        channel: "log",
-        sourceSeq: line.sourceSeq,
-        emittedAt: line.emittedAt,
-        // First-class severity on the envelope (not only inside `data`). `data.level`
-        // is kept too so an existing `data`-reading consumer still works.
-        level: line.level,
-        time: new Date(line.emittedAt).toISOString(),
-        message: line.message,
-        data: {
-            level: line.level,
-            message: line.message,
-            ...(line.fields ? { fields: { ...line.fields } } : {})
-        }
-    };
-}
-function custom(name, source, value, message) {
-    return {
-        type: "CUSTOM",
-        source,
-        ...(message !== undefined ? { message } : {}),
-        data: { name, value: { ...value } }
-    };
-}
-// --- Known/unknown classification and honest guards ---------------------------
-const TERMINAL_OUTCOMES = new Set(SESSION_TERMINAL_OUTCOMES);
-const LOG_LEVELS = new Set(AEX_LOG_LEVELS);
-function malformed(type, path, expected) {
-    return { code: "malformed_known_event", type, path, expected };
-}
-function optionalString(data, key) {
-    return data[key] === undefined || typeof data[key] === "string";
-}
-function optionalBoolean(data, key) {
-    return data[key] === undefined || typeof data[key] === "boolean";
-}
-function isJsonObjectShape(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function knownIssue(e) {
-    const d = e.data;
-    switch (e.type) {
-        case "RUN_STARTED":
-            for (const key of ["source", "mode", "provider", "model"]) {
-                if (!optionalString(d, key)) {
-                    return malformed("RUN_STARTED", `data.${key}`, "a string when present");
-                }
-            }
-            return d.turnSeq === undefined || (typeof d.turnSeq === "number" && Number.isInteger(d.turnSeq) && d.turnSeq >= 0)
-                ? undefined
-                : malformed("RUN_STARTED", "data.turnSeq", "a non-negative integer when present");
-        case "RUN_FINISHED":
-            return typeof d.outcome === "string" && TERMINAL_OUTCOMES.has(d.outcome)
-                ? undefined
-                : malformed("RUN_FINISHED", "data.outcome", `one of ${SESSION_TERMINAL_OUTCOMES.join(", ")}`);
-        case "RUN_ERROR":
-            if (typeof d.outcome !== "string" || !TERMINAL_OUTCOMES.has(d.outcome)) {
-                return malformed("RUN_ERROR", "data.outcome", `one of ${SESSION_TERMINAL_OUTCOMES.join(", ")}`);
-            }
-            if (!isAexFailureClass(d.failureClass))
-                return malformed("RUN_ERROR", "data.failureClass", `one of ${AEX_FAILURE_CLASSES.join(", ")}`);
-            if (typeof d.failureMessage !== "string" || d.failureMessage.length === 0) {
-                return malformed("RUN_ERROR", "data.failureMessage", "a non-empty string");
-            }
-            if (Object.hasOwn(d, "providerFault")) {
-                try {
-                    parseProviderFault(d.providerFault);
-                }
-                catch {
-                    return malformed("RUN_ERROR", "data.providerFault", "a canonical ProviderFault object when present");
-                }
-            }
-            return undefined;
-        case "TEXT_MESSAGE_CONTENT":
-            if (typeof d.text !== "string") {
-                return malformed("TEXT_MESSAGE_CONTENT", "data.text", "a string");
-            }
-            if (!optionalString(d, "messageId")) {
-                return malformed("TEXT_MESSAGE_CONTENT", "data.messageId", "a string when present");
-            }
-            if (!optionalString(d, "eventId")) {
-                return malformed("TEXT_MESSAGE_CONTENT", "data.eventId", "a string when present");
-            }
-            if (!optionalBoolean(d, "delta"))
-                return malformed("TEXT_MESSAGE_CONTENT", "data.delta", "a boolean when present");
-            return optionalBoolean(d, "truncated")
-                ? undefined
-                : malformed("TEXT_MESSAGE_CONTENT", "data.truncated", "a boolean when present");
-        case "TOOL_CALL_START":
-            if (typeof d.id !== "string" || d.id.length === 0) {
-                return malformed("TOOL_CALL_START", "data.id", "a non-empty string");
-            }
-            if (typeof d.name !== "string" || d.name.length === 0) {
-                return malformed("TOOL_CALL_START", "data.name", "a non-empty string");
-            }
-            if (d.arguments !== undefined && !isJsonObjectShape(d.arguments)) {
-                return malformed("TOOL_CALL_START", "data.arguments", "a JSON object when present");
-            }
-            return optionalString(d, "messageId")
-                ? undefined
-                : malformed("TOOL_CALL_START", "data.messageId", "a string when present");
-        case "TOOL_CALL_RESULT":
-            if (typeof d.id !== "string" || d.id.length === 0) {
-                return malformed("TOOL_CALL_RESULT", "data.id", "a non-empty string");
-            }
-            if (!Object.hasOwn(d, "content")) {
-                return malformed("TOOL_CALL_RESULT", "data.content", "present JSON data");
-            }
-            if (!optionalBoolean(d, "isError")) {
-                return malformed("TOOL_CALL_RESULT", "data.isError", "a boolean when present");
-            }
-            if (!optionalString(d, "messageId"))
-                return malformed("TOOL_CALL_RESULT", "data.messageId", "a string when present");
-            return optionalBoolean(d, "truncated") ? undefined : malformed("TOOL_CALL_RESULT", "data.truncated", "a boolean when present");
-        case "CUSTOM":
-            if (typeof d.name !== "string" || d.name.length === 0) {
-                return malformed("CUSTOM", "data.name", "a non-empty string");
-            }
-            return Object.hasOwn(d, "value")
-                ? undefined
-                : malformed("CUSTOM", "data.value", "present JSON data");
-        case "LOG":
-            if (e.channel !== "log")
-                return malformed("LOG", "channel", '"log"');
-            if (typeof e.level !== "string" || !LOG_LEVELS.has(e.level)) {
-                return malformed("LOG", "level", `one of ${AEX_LOG_LEVELS.join(", ")}`);
-            }
-            if (d.level !== e.level)
-                return malformed("LOG", "data.level", "the first-class event level");
-            if (typeof d.message !== "string")
-                return malformed("LOG", "data.message", "a string");
-            if (d.fields !== undefined && !isJsonObjectShape(d.fields))
-                return malformed("LOG", "data.fields", "a JSON object when present");
-            return optionalBoolean(d, "truncated") ? undefined : malformed("LOG", "data.truncated", "a boolean when present");
-        default:
-            return null;
-    }
-}
-/** Classify an open event without cloning or rewriting it. */
-export function classifyAexEvent(event) {
-    const issue = knownIssue(event);
-    if (issue === null)
-        return { kind: "unknown", event };
-    if (issue !== undefined)
-        return { kind: "malformed_known", event, issue };
-    return { kind: "known", event: event };
-}
-/** True only for a currently understood event with a valid payload. */
-export function isKnownAexEvent(e) {
-    return knownIssue(e) === undefined;
-}
-export function isRunStarted(e) {
-    return e.type === "RUN_STARTED" && knownIssue(e) === undefined;
-}
-export function isRunFinished(e) {
-    return e.type === "RUN_FINISHED" && knownIssue(e) === undefined;
-}
-export function isRunError(e) {
-    return e.type === "RUN_ERROR" && knownIssue(e) === undefined;
-}
-/** A valid terminal event of either flavour (finished or error). */
-export function isRunTerminal(e) {
-    return (e.type === "RUN_FINISHED" || e.type === "RUN_ERROR") && knownIssue(e) === undefined;
-}
-export function isTextMessage(e) {
-    return e.type === "TEXT_MESSAGE_CONTENT" && knownIssue(e) === undefined;
-}
-export function isToolCallStart(e) {
-    return e.type === "TOOL_CALL_START" && knownIssue(e) === undefined;
-}
-export function isToolCallResult(e) {
-    return e.type === "TOOL_CALL_RESULT" && knownIssue(e) === undefined;
-}
-export function isCustom(e) {
-    return e.type === "CUSTOM" && knownIssue(e) === undefined;
-}
-/** The `aex.*` name of a valid CUSTOM event, or null otherwise. */
-export function customName(e) {
-    return isCustom(e) ? e.data.name : null;
-}
-/**
- * The CUSTOM `data.name` of the HITL write-gate park: the session has reached the
- * `awaiting_approval` state before a gated action and is holding for an
- * `approve()`/`deny()`. Structural (independent of model prose).
- */
-export const AEX_SESSION_AWAITING_APPROVAL_NAME = "aex.session.awaiting_approval";
-/** The CUSTOM `data.name` carrying a schema-decoded value (`{ value }`). */
-export const AEX_RESULT_DECODED_NAME = "aex.result.decoded";
-/** The CUSTOM `data.name` carrying a typed decode refusal (`{ reason, detail? }`). */
-export const AEX_RESULT_REFUSED_NAME = "aex.result.refused";
-/** True for the HITL `awaiting_approval` gate event. */
-export function isAwaitingApproval(e) {
-    return isCustom(e) && e.data.name === AEX_SESSION_AWAITING_APPROVAL_NAME;
-}
-/** True for a schema-decoded terminal result event. */
-export function isResultDecoded(e) {
-    return isCustom(e) && e.data.name === AEX_RESULT_DECODED_NAME;
-}
-/** True for a typed decode-refusal terminal result event. */
-export function isResultRefused(e) {
-    return isCustom(e) && e.data.name === AEX_RESULT_REFUSED_NAME;
-}
-export function isFromSource(e, source) {
-    return e.source === source;
-}
-/** The channel a record rides, defaulting an absent value to `"event"`. */
-export function channelOf(e) {
-    return e.channel ?? "event";
-}
-/** True when a record is a valid log line (the `log` channel / `LOG` type). */
-export function isLog(e) {
-    return e.type === "LOG" && knownIssue(e) === undefined;
-}
-/** True when a record is a typed AG-UI event (the `event` channel). */
-export function isEventChannel(e) {
-    return channelOf(e) === "event";
-}
-// --- Oversized-payload rule (2 MB SQLite row cap) -----------------------------
-/**
- * The coordinator's embedded store caps a
- * single row at 2 MB. Events whose serialized form exceeds the budget must be
- * split before insert (the coordinator's responsibility); the archive uses the
- * same bound. A conservative margin under the hard 2 MiB leaves room for row
- * overhead and column framing.
- */
-export const EVENT_ROW_MAX_BYTES = 2_000_000;
-/** Serialized UTF-8 byte length of an event (the size the row must hold). */
-export function serializedEventBytes(e) {
-    return new TextEncoder().encode(JSON.stringify(e)).byteLength;
-}
-/** True when an event's serialized form exceeds the row budget and must be split. */
-export function exceedsRowBudget(e, max = EVENT_ROW_MAX_BYTES) {
-    return serializedEventBytes(e) > max;
-}
-/**
- * Project an aex envelope to a strict AG-UI event so an off-the-shelf
- * AG-UI client can consume an aex start with no glue. This is the
- * client-side projection the SDK exposes.
- */
-export function toAGUI(e) {
-    const timestamp = Date.parse(e.time);
-    const classified = classifyAexEvent(e);
-    if (classified.kind === "malformed_known") {
-        throw new MalformedAexEventError(classified.issue);
-    }
-    if (classified.kind === "unknown") {
-        return { type: "CUSTOM", timestamp, name: e.type, value: { ...e.data } };
-    }
-    const known = classified.event;
-    switch (known.type) {
-        case "RUN_STARTED":
-            return { type: "RUN_STARTED", timestamp, threadId: known.threadId, runId: known.runId };
-        case "RUN_FINISHED": {
-            const result = known.data.result;
-            return {
-                type: "RUN_FINISHED",
-                timestamp,
-                threadId: known.threadId,
-                runId: known.runId,
-                ...(result !== undefined ? { result } : {})
-            };
-        }
-        case "RUN_ERROR":
-            return {
-                type: "RUN_ERROR",
-                timestamp,
-                message: known.data.failureMessage,
-                code: known.data.failureClass
-            };
-        case "TEXT_MESSAGE_CONTENT":
-            return {
-                type: "TEXT_MESSAGE_CONTENT",
-                timestamp,
-                messageId: known.data.messageId ?? known.data.eventId ?? known.id,
-                delta: known.data.text
-            };
-        case "TOOL_CALL_START":
-            return {
-                type: "TOOL_CALL_START",
-                timestamp,
-                toolCallId: known.data.id,
-                toolCallName: known.data.name
-            };
-        case "TOOL_CALL_RESULT":
-            return {
-                type: "TOOL_CALL_RESULT",
-                timestamp,
-                messageId: known.data.messageId ?? known.id,
-                toolCallId: known.data.id,
-                content: known.data.content
-            };
-        case "CUSTOM":
-            return { type: "CUSTOM", timestamp, name: known.data.name, value: known.data.value };
-        case "LOG":
-            // Logs ride the `log` channel and are normally filtered out before
-            // projection. If a consumer projects one anyway, carry it under AG-UI's
-            // reserved CUSTOM so the client still receives a valid record.
-            return { type: "CUSTOM", timestamp, name: "aex.log", value: { ...known.data } };
-    }
-}
-function clip(s, max = 200) {
-    return s.length <= max ? s : `${s.slice(0, max - 1)}…`;
-}

package/dist/_contracts/event-stream-client.d.ts

@@ -1,122 +0,0 @@
-/**
- * Client-side consumer of the event coordinator's WebSocket stream.
- *
- * One mechanism for catch-up + resume + live: subscribe = read-from-cursor +
- * tail. The consumer opens a WS to the coordinator with a connection ticket,
- * replays from its cursor, and yields {@link AexStreamEvent}s as they arrive.
- * On a transport drop it reconnects with backoff and resumes from the last
- * durable sequence it saw — `from = lastSeq + 1`. Provisional
- * {@link AexLiveEvent}s are deduplicated by stable `id` but never advance that
- * replay cursor. It stops on a durable terminal event, on abort,
- * or when the caller breaks the iterator.
- *
- * A silently half-open socket (no close/error, no frames) is the dangerous
- * case: the read loop would block forever and MISS a terminal that was already
- * persisted server-side. So the client sends a post-open replay trigger plus a
- * tiny keep-alive ping the coordinator answers with a matching pong, and uses an idle
- * watchdog: if no frame arrives within {@link CoordinatorStreamOptions.idleTimeoutMs},
- * the socket is treated as dead and reconnected — resume-from-cursor then
- * replays the terminal.
- *
- * Filtering and projection are the client's concern (the wire carries the
- * whole session): compose {@link filterStream} with the envelope guards, and
- * {@link mapStream} with {@link toAGUI}, on top of this stream.
- *
- * The WebSocket is injectable so the SDK/CLI use the global `WebSocket`
- * (Bun and Node 22+ ship it; no dependency) and tests drive a fake. The timers
- * are injectable the same way ({@link TimerPort}) so the watchdog/backoff
- * clocks are deterministic under test.
- */
-import { type AexEvent, type AexEventBase, type AexRunErrorEvent, type AexRunFinishedEvent, type AexStreamEvent } from "./event-envelope.js";
-/** The slice of the WHATWG WebSocket this client depends on. */
-export interface WebSocketLike {
-    close(code?: number, reason?: string): void;
-    addEventListener(type: "open" | "message" | "close" | "error", listener: (ev: {
-        data?: unknown;
-    }) => void): void;
-    /** Send a keep-alive ping. Optional: a transport without it just relies on real events to reset the watchdog. */
-    send?(data: string): void;
-}
-export type WebSocketFactory = (url: string) => WebSocketLike;
-/**
- * The four host timer functions the stream client schedules on. Injectable so
- * tests drive the watchdog/ping/backoff timers deterministically without
- * swapping globals; defaults to the host's own timers. Handles are opaque:
- * whatever `setTimeout`/`setInterval` return is what the matching clear
- * receives.
- */
-export interface TimerPort {
-    setTimeout(callback: () => void, delayMs: number): unknown;
-    clearTimeout(handle: unknown): void;
-    setInterval(callback: () => void, delayMs: number): unknown;
-    clearInterval(handle: unknown): void;
-}
-export interface CoordinatorStreamOptions {
-    /** Base subscribe URL, e.g. `wss://coordinator/sessions/<id>/subscribe`. */
-    readonly wsUrl: string;
-    /** Starting cursor: events with `sequence >= from` are delivered. Default 0 (from start). */
-    readonly from?: number;
-    /** Mint/refresh a short-lived connection ticket (called before each connect). */
-    readonly fetchTicket: () => Promise<string>;
-    readonly signal?: AbortSignal;
-    /** Injected WebSocket constructor; defaults to the global `WebSocket`. */
-    readonly webSocketFactory?: WebSocketFactory;
-    /** Reconnect ceiling (default: unlimited until terminal/abort). */
-    readonly maxReconnects?: number;
-    /** Backoff between reconnect attempts (default 500 ms). */
-    readonly reconnectDelayMs?: number;
-    /**
-     * Predicate that decides which event ENDS the stream. Default: the AG-UI
-     * terminal events (RUN_FINISHED / RUN_ERROR). A terminal is emitted only
-     * after the run's checkpoint, accounting, and session state are committed.
-     */
-    readonly isTerminal?: (event: AexEvent) => boolean;
-    /**
-     * Half-open watchdog window. If no frame (a real event OR a keep-alive pong)
-     * arrives within this many ms, the socket is treated as dead and reconnected
-     * (resume from cursor). Default 45s. Set 0 to disable.
-     */
-    readonly idleTimeoutMs?: number;
-    /**
-     * Client keep-alive ping cadence. The client sends {@link COORDINATOR_PING},
-     * which the coordinator answers with a matching pong, so
-     * a legitimately quiet session keeps the socket measurably alive and does not trip
-     * the watchdog. Default 15s. Set 0 to disable (then only real events reset the
-     * watchdog → quiet sessions may reconnect).
-     */
-    readonly pingIntervalMs?: number;
-    /**
-     * Event-quiet recheck window. A pong proves the SOCKET is alive, not the
-     * delivery pipeline behind it — a server-side subscription that died (reaped
-     * connection row, wedged fan-out) keeps answering pings while never delivering
-     * another event, so the idle watchdog alone would hang one frame short of the
-     * terminal forever. If no REAL event frame arrives within this many ms the
-     * client silently reconnects (resume from cursor) — the replay-on-connect path
-     * reads the event store directly, so a dead subscription self-heals. Default
-     * 90s. Set 0 to disable.
-     */
-    readonly eventQuietRecheckMs?: number;
-    /**
-     * Injected timer functions for the idle watchdog, event-quiet recheck,
-     * keep-alive ping, and reconnect backoff. Default: the host's own timers.
-     */
-    readonly timers?: TimerPort;
-}
-/** An open event narrowed only to a run-terminal discriminant, not a validated payload. */
-export type RunTerminalTypeEvent<T extends AexEventBase = AexEventBase> = T & {
-    readonly type: AexRunFinishedEvent["type"] | AexRunErrorEvent["type"];
-};
-/**
- * True for either run-terminal discriminant, including a malformed payload.
- *
- * Streaming uses this weaker boundary so a malformed terminal still ends the
- * read loop and reaches the canonical payload validation/error path. Consumers
- * that need validated terminal data must use `isRunTerminal` instead.
- * Internal-only: intentionally omitted from the public contracts barrel.
- */
-export declare function hasRunTerminalType<T extends AexEventBase>(event: T): event is RunTerminalTypeEvent<T>;
-export declare function streamCoordinatorEvents(opts: CoordinatorStreamOptions): AsyncGenerator<AexStreamEvent, void, void>;
-/** Async-iterable filter — keep only events matching the predicate. */
-export declare function filterStream<T>(stream: AsyncIterable<T>, predicate: (event: T) => boolean): AsyncGenerator<T, void, void>;
-/** Async-iterable map — project each event (e.g. with `toAGUI`). */
-export declare function mapStream<T, U>(stream: AsyncIterable<T>, project: (event: T) => U): AsyncGenerator<U, void, void>;