@vibefield/rosetta-protocol 0.0.0-stage → 0.1.0

package/dist/client.js

@@ -0,0 +1,981 @@
+// Hand-written client over the generated protocol types. This is the ONE
+// place the subscribe state machine lives outside Rust: snapshot at a
+// stamp, apply mutations keyed by timeline_id (including patches into
+// earlier rows), obey Resync barriers, and reconnect with a resume stamp.
+// Consumers render; they never re-implement protocol semantics.
+import { utf8Base64UrlEncode } from "./base64url.js";
+import { OrderedCache } from "./ordered-cache.js";
+import { PROTOCOL_VERSION } from "./protocol-version.mjs";
+export { PROTOCOL_VERSION } from "./protocol-version.mjs";
+export const DEFAULT_BASE_URL = "http://127.0.0.1:4640";
+export const AUTH_REFUSALS = [
+    "missing",
+    "bad-token",
+    "malformed",
+    "bad-signature",
+    "expired",
+    "wrong-session",
+    "wrong-scope",
+    "wrong-route",
+    "grants-disabled",
+];
+export const AUTH_REASON_HEADER = "x-rosetta-auth";
+/** The subprotocol a daemon selects for a credentialed WebSocket upgrade. */
+export const AUTH_WS_PROTOCOL = "rosetta";
+/** The `Authorization` value that presents `credential`. */
+export function authorizationHeader(credential) {
+    return credential.kind === "bearer"
+        ? `Bearer ${credential.token}`
+        : `Rosetta-Grant ${credential.grant}`;
+}
+/**
+ * A browser's WebSocket cannot set `Authorization`, so the credential rides
+ * the subprotocol list beside the marker the daemon selects. The daemon
+ * never echoes the credential entry.
+ */
+export function webSocketProtocols(credential) {
+    return [
+        AUTH_WS_PROTOCOL,
+        credential.kind === "bearer"
+            ? `rosetta.bearer.${utf8Base64UrlEncode(credential.token)}`
+            : `rosetta.grant.${credential.grant}`,
+    ];
+}
+export class ApiRequestError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.name = "ApiRequestError";
+        this.status = status;
+        this.code = code;
+    }
+}
+/** The bound watermark no longer matches: refetch from the head. */
+export class CursorExpiredError extends ApiRequestError {
+    constructor(message) {
+        super(410, "cursor_expired", message);
+        this.name = "CursorExpiredError";
+    }
+}
+/** A 401: the daemon wants a credential this client did not present, or
+ * refused the one it did. `reason` is null only from a daemon that named
+ * none. */
+export class UnauthorizedError extends ApiRequestError {
+    reason;
+    constructor(reason, message) {
+        super(401, null, message);
+        this.name = "UnauthorizedError";
+        this.reason = reason;
+    }
+}
+// `RequestInit["headers"]`, not `HeadersInit`: a Node consumer compiled without the DOM lib
+// (VibeField's fieldd, `lib: ["ES2022"]` + `@types/node`) has `RequestInit` as a global but no
+// `HeadersInit`; the indexed type is the same bag under both libs.
+function withAuthorization(init, credential) {
+    const headers = new Headers(init);
+    headers.set("authorization", authorizationHeader(credential));
+    return headers;
+}
+function queryString(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== null && value !== undefined) {
+            search.set(key, String(value));
+        }
+    }
+    const text = search.toString();
+    return text === "" ? "" : `?${text}`;
+}
+/** `RequestInit.signal` is exactly optional: an absent signal omits the key
+ * rather than setting it to `undefined`. */
+function withSignal(signal) {
+    return signal === undefined ? {} : { signal };
+}
+const RECONNECT_BASE_MS = 500;
+const RECONNECT_MAX_MS = 10_000;
+/** Keep additive timeline-meta fields safe across a daemon/client rolling
+ * restart. The protocol handshake still owns incompatible changes; a missing
+ * newly-added collection is the one backwards-compatible case we accept. */
+function normalizeTimelineMeta(meta) {
+    return {
+        tasks: meta.tasks ?? [],
+        workflows: meta.workflows ?? [],
+        plans: meta.plans ?? [],
+        artifacts: meta.artifacts ?? [],
+    };
+}
+/** `run` is a query-time join and therefore absent from row-level mutations.
+ * Keep it only while both canonical actions still identify the same run. A
+ * replacement snapshot starts from an empty map and remains authoritative. */
+function retainHydratedWorkflowRun(current, incoming) {
+    const before = current.action;
+    const after = incoming.action;
+    return before.type === "workflow" &&
+        after.type === "workflow" &&
+        before.run !== null &&
+        after.run === null &&
+        before.run_id !== null &&
+        after.run_id === before.run_id
+        ? { ...incoming, action: { ...after, run: before.run } }
+        : incoming;
+}
+export class RosettaClient {
+    origin;
+    get baseUrl() {
+        return this.origin;
+    }
+    connection = new AbortController();
+    connectionListeners = new Set();
+    subscriptions = new Set();
+    requestTimeoutMs;
+    notificationIntervalMs;
+    fetchFn;
+    WebSocketImpl;
+    credential;
+    constructor(options = {}) {
+        this.origin = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.fetchFn = options.fetchFn ?? fetch.bind(globalThis);
+        this.WebSocketImpl = options.WebSocketImpl ?? WebSocket;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
+        this.notificationIntervalMs = options.notificationIntervalMs ?? 16;
+        this.credential = options.credential ?? null;
+    }
+    /**
+     * Replace the credential (a refreshed grant, a rotated bearer), or drop
+     * it. Later requests and every later (re)connect present it. An open
+     * socket is left alone: the daemon checks a credential at the upgrade, so
+     * a grant that expires under a live subscription ends only with its
+     * socket, and the reconnect then needs a fresh one.
+     */
+    setCredential(credential) {
+        this.credential = credential;
+    }
+    async response(path, init) {
+        const signal = AbortSignal.any([
+            AbortSignal.timeout(this.requestTimeoutMs),
+            this.connection.signal,
+            ...(init?.signal ? [init.signal] : []),
+        ]);
+        const headers = this.credential === null ? init?.headers : withAuthorization(init?.headers, this.credential);
+        const response = await this.fetchFn(`${this.baseUrl}${path}`, {
+            ...init,
+            ...(headers === undefined ? {} : { headers }),
+            signal,
+            redirect: "error",
+        });
+        signal.throwIfAborted();
+        const version = response.headers.get("x-rosetta-protocol-version");
+        if (version !== String(PROTOCOL_VERSION)) {
+            throw new ApiRequestError(response.status, "incompatible_protocol", `Daemon protocol ${version ?? "unknown"} is incompatible with this app (expected ${PROTOCOL_VERSION}). Restart with the matching daemon.`);
+        }
+        if (response.status === 401) {
+            const reason = response.headers.get(AUTH_REASON_HEADER);
+            throw new UnauthorizedError(AUTH_REFUSALS.find((refusal) => refusal === reason) ?? null, `The daemon refused ${path} (${reason ?? "unauthorized"}).`);
+        }
+        if (!response.ok) {
+            let code = null;
+            let message = `${response.status} on ${path}`;
+            try {
+                const body = (await response.json());
+                if (body.error) {
+                    code = body.error.code;
+                    message = body.error.message;
+                }
+            }
+            catch {
+                // Non-JSON error body; keep the status-line message.
+            }
+            if (code === "cursor_expired") {
+                throw new CursorExpiredError(message);
+            }
+            throw new ApiRequestError(response.status, code, message);
+        }
+        return response;
+    }
+    async request(path, init) {
+        return (await (await this.response(path, init)).json());
+    }
+    status(signal) {
+        return this.request("/api/status", withSignal(signal));
+    }
+    /** The roll call's census — what discovery found, content-free. */
+    discoveries(signal) {
+        return this.request("/api/discoveries", withSignal(signal));
+    }
+    /** Consent: enroll the chosen agent kinds. Grantable exactly once, while
+     * the daemon is awaiting consent. */
+    enableRuntimes(kinds, signal) {
+        return this.request("/api/runtimes/enable", {
+            method: "POST",
+            ...withSignal(signal),
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ kinds }),
+        });
+    }
+    /** Attention-directed ingestion: the reader opened a still-queued
+     * session — ask the daemon to read it next. Advisory; safe to fire on
+     * every selection of a pending session. */
+    boost(sessionId, signal) {
+        return this.request("/api/ingest/boost", {
+            method: "POST",
+            ...withSignal(signal),
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ session_id: sessionId }),
+        });
+    }
+    runtimes(signal) {
+        return this.request("/api/runtimes", withSignal(signal));
+    }
+    projects(signal) {
+        return this.request("/api/projects", withSignal(signal));
+    }
+    sessions(options = {}, signal) {
+        return this.request(`/api/sessions${queryString(options)}`, withSignal(signal));
+    }
+    /** Resolve canonical rows for provider-native session ids; children come
+     * back too, and `root_session_id` names the navigable thread. */
+    sessionsByNativeId(nativeSessionIds, signal) {
+        return this.sessions({ native_session_id: nativeSessionIds.join(","), limit: 1000 }, signal);
+    }
+    session(id, signal) {
+        return this.request(`/api/sessions/${encodeURIComponent(id)}`, withSignal(signal));
+    }
+    /**
+     * One backward page. Pass the previous page's `cursor` to continue; a
+     * rewrite underneath throws {@link CursorExpiredError} — refetch from the
+     * head (no cursor).
+     */
+    timeline(sessionId, options = {}, signal) {
+        return this.request(`/api/sessions/${encodeURIComponent(sessionId)}/timeline${queryString(options)}`, withSignal(signal));
+    }
+    /** Complete delivered collaboration history for one team member. The
+     * response deliberately excludes private prose and tool rows. */
+    collaborationTimeline(sessionId, signal) {
+        return this.request(`/api/sessions/${encodeURIComponent(sessionId)}/collaboration`, withSignal(signal));
+    }
+    /** An exact row and the generation it belongs to. */
+    timelineEntryResponse(sessionId, timelineId, signal) {
+        return this.request(`/api/sessions/${encodeURIComponent(sessionId)}/timeline/${encodeURIComponent(timelineId)}`, withSignal(signal));
+    }
+    async timelineEntry(sessionId, timelineId, signal) {
+        return (await this.timelineEntryResponse(sessionId, timelineId, signal)).entry;
+    }
+    reportWork(sessionId, timelineId, signal) {
+        return this.request(`/api/sessions/${encodeURIComponent(sessionId)}/timeline/${encodeURIComponent(timelineId)}/work`, withSignal(signal));
+    }
+    /** Recover one deliberately omitted command body from its raw-ledger
+     * record. Nothing is fetched until the reader opens the disclosure. */
+    command(sessionId, timelineId, signal) {
+        return this.request(`/api/sessions/${encodeURIComponent(sessionId)}/timeline/${encodeURIComponent(timelineId)}/command`, withSignal(signal));
+    }
+    /** Read the live file named by one canonical file-bearing target. The caller
+     * supplies identities and an index, never a path; the daemon resolves the
+     * exact path already stored on that timeline row. */
+    /** Direct image URLs let the browser share compressed and decoded resources.
+     * Recipes are finite, versioned and enforced by the daemon. */
+    imageAssetUrl(asset, variant) {
+        const base = new URL(`${this.baseUrl}/`);
+        const rendition = variant === "full" ? asset : asset.image_variants?.[variant];
+        const url = new URL((rendition ?? asset).url, base);
+        if (url.origin !== base.origin || !["http:", "https:"].includes(url.protocol)) {
+            throw new Error("the stored image has an unsupported address");
+        }
+        // Older projection fixtures have no rendition set. The versioned daemon
+        // route can prepare a legacy member without modifying its immutable URL.
+        if (!rendition) {
+            url.searchParams.set("image", variant);
+            url.searchParams.set("v", "1");
+        }
+        return url.toString();
+    }
+    imageFileTargetUrl(sessionId, timelineId, targetIndex, variant) {
+        if (!Number.isSafeInteger(targetIndex) || targetIndex < 0)
+            throw new Error("invalid image target");
+        return `${this.baseUrl}/api/sessions/${encodeURIComponent(sessionId)}/timeline/${encodeURIComponent(timelineId)}/read/${targetIndex}?image=${variant}&v=1`;
+    }
+    async readFileTarget(sessionId, timelineId, targetIndex, signal) {
+        const response = await this.response(`/api/sessions/${encodeURIComponent(sessionId)}/timeline/${encodeURIComponent(timelineId)}/read/${targetIndex}`, withSignal(signal));
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    /** Resolve a canonical oversized-text member only when its disclosure is
+     * opened. Asset references are daemon-owned and may not redirect this
+     * authenticated/local client to another origin. */
+    async readTextAsset(asset, signal) {
+        const base = new URL(`${this.baseUrl}/`);
+        const url = new URL(asset.url, base);
+        if ((url.protocol !== "http:" && url.protocol !== "https:") || url.origin !== base.origin) {
+            throw new Error("the stored text has an unsupported address");
+        }
+        return (await this.response(`${url.pathname}${url.search}`, withSignal(signal))).text();
+    }
+    async readAsset(asset, signal) {
+        const base = new URL(`${this.baseUrl}/`);
+        const url = new URL(asset.url, base);
+        if (url.origin !== base.origin || !["http:", "https:"].includes(url.protocol)) {
+            throw new Error("the stored asset has an unsupported address");
+        }
+        return new Uint8Array(await (await this.response(`${url.pathname}${url.search}`, withSignal(signal))).arrayBuffer());
+    }
+    /** Read one exact plan document selected from timeline_meta. */
+    async readPlan(sessionId, source, signal) {
+        const path = source.type === "revision"
+            ? `/api/sessions/${encodeURIComponent(sessionId)}/plans/revisions/${source.revision}`
+            : `/api/sessions/${encodeURIComponent(sessionId)}/timeline/${encodeURIComponent(source.timeline_id)}/plan`;
+        const response = await this.response(path, withSignal(signal));
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    search(request, signal) {
+        return this.request(`/api/search${queryString({
+            q: request.q,
+            limit: request.limit,
+            session: request.session,
+            sessions: request.sessions,
+            prefix: request.prefix,
+            runtime: request.runtime,
+            agent: request.agent,
+            project: request.project,
+            kind: request.kind,
+            is_error: request.is_error,
+            after_ts: request.after_ts,
+            before_ts: request.before_ts,
+        })}`, withSignal(signal));
+    }
+    heatmap(projectId, options = {}, signal) {
+        return this.request(`/api/projects/${encodeURIComponent(projectId)}/heatmap${queryString({
+            since_ms: options.sinceMs,
+            offset_minutes: options.offsetMinutes,
+        })}`, withSignal(signal));
+    }
+    contribution(projectId, signal) {
+        return this.request(`/api/projects/${encodeURIComponent(projectId)}/contribution`, withSignal(signal));
+    }
+    /** The heatmap figure's decomposition over the same window: per-model days
+     * (they sum back to the heatmap exactly) plus an hour-of-day profile. */
+    usage(projectId, options = {}, signal) {
+        return this.request(`/api/projects/${encodeURIComponent(projectId)}/usage${queryString({
+            since_ms: options.sinceMs,
+            offset_minutes: options.offsetMinutes,
+        })}`, withSignal(signal));
+    }
+    /** Hourly model tokens for one date, using the heatmap's timezone offset. */
+    dayUsage(projectId, day, offsetMinutes = 0, signal) {
+        return this.request(`/api/projects/${encodeURIComponent(projectId)}/usage/day${queryString({
+            day, offset_minutes: offsetMinutes,
+        })}`, withSignal(signal));
+    }
+    /** Which top-level sessions were active in a window of at most seven days,
+     * newest recorded activity first, each with its tree's turns and the gaps
+     * inside them longer than `gapMs` (15 minutes unless asked). It spans
+     * sessions, so it needs the bearer. */
+    activity(window, signal) {
+        return this.request(`/api/activity${queryString({
+            since_ms: window.sinceMs,
+            until_ms: window.untilMs,
+            sessions: window.sessions === undefined ? undefined : window.sessions.join(","),
+            gap_ms: window.gapMs,
+            limit: window.limit,
+        })}`, withSignal(signal));
+    }
+    /** The price catalog behind every cost figure: its basis (list-price
+     * equivalent), version, sources, and the catalog the projection's rollup
+     * was priced with. */
+    pricing(signal) {
+        return this.request("/api/pricing", withSignal(signal));
+    }
+    /** A restarted app-owned daemon may bind another port. Abort old requests
+     * and reconnect existing consumers without losing the reader's selection. */
+    setBaseUrl(baseUrl) {
+        const origin = baseUrl.replace(/\/$/, "");
+        if (origin === this.origin)
+            return;
+        this.origin = origin;
+        this.connection.abort();
+        this.connection = new AbortController();
+        for (const subscription of this.subscriptions)
+            subscription.restart();
+        for (const listener of this.connectionListeners)
+            listener();
+    }
+    onConnectionChange(listener) {
+        this.connectionListeners.add(listener);
+        return () => {
+            this.connectionListeners.delete(listener);
+        };
+    }
+    transport(path) {
+        return {
+            url: () => `${this.baseUrl.replace(/^http/, "ws")}${path}`,
+            protocols: () => (this.credential === null ? undefined : webSocketProtocols(this.credential)),
+            socket: this.WebSocketImpl,
+            interval: this.notificationIntervalMs,
+            onClose: (sub) => this.subscriptions.delete(sub),
+        };
+    }
+    subscribeSession(sessionId, handlers) {
+        const sub = new SessionSubscription(this.transport(`/ws/sessions/${encodeURIComponent(sessionId)}`), handlers, this, sessionId);
+        this.subscriptions.add(sub);
+        return sub;
+    }
+    subscribeMeta(handlers) {
+        const sub = new MetaSubscription(this.transport("/ws/meta"), handlers);
+        this.subscriptions.add(sub);
+        return sub;
+    }
+    subscribeCollaboration(sessionId, handlers) {
+        const sub = new CollaborationSubscription(this.transport(`/ws/collaboration/${encodeURIComponent(sessionId)}`), handlers);
+        this.subscriptions.add(sub);
+        return sub;
+    }
+}
+class BaseSubscription {
+    stamp = null;
+    closed = false;
+    transport;
+    socket = null;
+    attempts = 0;
+    status = null;
+    reconnectTimer = null;
+    deadline = null;
+    changeTimer = null;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    start() {
+        this.connect();
+    }
+    connect() {
+        if (this.closed)
+            return;
+        this.reconnectTimer = null;
+        const resume = this.stamp === null ? "" : `?epoch=${this.stamp.epoch}&seq=${this.stamp.seq}`;
+        this.setStatus("connecting");
+        let socket;
+        try {
+            const url = `${this.transport.url()}${resume}`;
+            const protocols = this.transport.protocols();
+            socket =
+                protocols === undefined
+                    ? new this.transport.socket(url)
+                    : new this.transport.socket(url, protocols);
+        }
+        catch {
+            this.retry();
+            return;
+        }
+        this.socket = socket;
+        let greeted = false;
+        // Opening TCP is not successful synchronization. Keep backoff until live.
+        this.deadline = setTimeout(() => socket.close(), 15_000);
+        socket.onopen = () => {
+            if (this.socket === socket && !this.closed)
+                this.setStatus("syncing");
+        };
+        socket.onmessage = (event) => {
+            if (this.socket !== socket || this.closed)
+                return;
+            try {
+                const frame = JSON.parse(String(event.data));
+                if (frame.frame === "hello") {
+                    if (frame.protocol_version !== PROTOCOL_VERSION) {
+                        this.onError({
+                            code: "incompatible_protocol",
+                            message: `Daemon protocol ${frame.protocol_version} is incompatible with this app (expected ${PROTOCOL_VERSION}). Restart with the matching daemon.`,
+                        });
+                        this.close();
+                        return;
+                    }
+                    greeted = true;
+                    // Hello advertises a target. It never acknowledges data we received.
+                    return;
+                }
+                if (!greeted)
+                    throw new Error("The daemon sent data before its protocol handshake.");
+                if (frame.frame === "error")
+                    this.onError(frame.error);
+                else
+                    this.handleFrame(frame);
+            }
+            catch (error) {
+                this.onError({
+                    code: "internal",
+                    message: error instanceof Error ? error.message : "Invalid daemon frame",
+                });
+                this.stamp = null;
+                this.invalidate();
+                socket.close();
+            }
+        };
+        socket.onclose = () => {
+            if (this.socket !== socket)
+                return;
+            this.socket = null;
+            this.clearDeadline();
+            if (!this.closed)
+                this.retry();
+        };
+        socket.onerror = () => {
+            /* close owns reconnect */
+        };
+    }
+    retry() {
+        if (this.closed)
+            return;
+        this.setStatus("connecting");
+        const delay = Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** this.attempts++);
+        this.reconnectTimer = setTimeout(() => this.connect(), delay);
+    }
+    clearDeadline() {
+        if (this.deadline !== null)
+            clearTimeout(this.deadline);
+        this.deadline = null;
+    }
+    live() {
+        this.attempts = 0;
+        this.clearDeadline();
+        this.setStatus("live");
+    }
+    setStatus(status) {
+        if (this.status === status)
+            return;
+        this.status = status;
+        if (status === "resyncing" && this.socket !== null) {
+            this.clearDeadline();
+            const socket = this.socket;
+            this.deadline = setTimeout(() => socket.close(), 15_000);
+        }
+        this.onStatus(status);
+    }
+    changed(immediate = false) {
+        if (this.closed)
+            return;
+        if (immediate || this.transport.interval === 0) {
+            this.cancelChange();
+            this.flushChanges();
+        }
+        else if (this.changeTimer === null) {
+            this.changeTimer = setTimeout(() => {
+                this.changeTimer = null;
+                if (!this.closed)
+                    this.flushChanges();
+            }, this.transport.interval);
+        }
+    }
+    cancelChange() {
+        if (this.changeTimer !== null)
+            clearTimeout(this.changeTimer);
+        this.changeTimer = null;
+    }
+    /** Drop a generation and request an authoritative snapshot. */
+    restart() {
+        if (this.closed)
+            return;
+        this.stamp = null;
+        this.invalidate();
+        const socket = this.socket;
+        this.socket = null;
+        this.clearDeadline();
+        if (this.reconnectTimer !== null)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+        socket?.close();
+        this.connect();
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.clearDeadline();
+        this.cancelChange();
+        if (this.reconnectTimer !== null)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+        const socket = this.socket;
+        this.socket = null;
+        socket?.close();
+        this.dispose();
+        this.setStatus("closed");
+        this.transport.onClose(this);
+    }
+    dispose() { }
+}
+const timelineOrder = (a, b) => a.ordinal - b.ordinal || a.timeline_id.localeCompare(b.timeline_id);
+/** Apply the same canonical patch to visible rows, held pages, and anchors. */
+function patchRow(row, mutation) {
+    switch (mutation.type) {
+        case "message": {
+            const { type: _tag, ...incoming } = mutation;
+            return row?.body.type === "tool_use" && incoming.body.type === "tool_use"
+                ? {
+                    ...incoming,
+                    body: {
+                        ...incoming.body,
+                        tool: retainHydratedWorkflowRun(row.body.tool, incoming.body.tool),
+                    },
+                }
+                : incoming;
+        }
+        case "tool_updated":
+            return row?.body.type === "tool_use"
+                ? {
+                    ...row,
+                    body: { ...row.body, tool: retainHydratedWorkflowRun(row.body.tool, mutation.tool) },
+                }
+                : row;
+        case "usage": {
+            if (!row)
+                return row;
+            // The read-time cost belongs to the replaced usage: never keep the old.
+            const { cost: _replaced, ...rest } = row;
+            const next = { ...rest, usage: mutation.tokens, model: mutation.model, at: mutation.ts };
+            return mutation.cost === null ? next : { ...next, cost: mutation.cost };
+        }
+        default:
+            return row;
+    }
+}
+export class SessionSubscription extends BaseSubscription {
+    handlers;
+    client;
+    sessionId;
+    rows = new Map();
+    visible = new OrderedCache((row) => row.timeline_id, timelineOrder);
+    timelineMeta = { tasks: [], workflows: [], plans: [], artifacts: [] };
+    generation = 0;
+    watermark = null;
+    pending = new Set();
+    rowsDirty = false;
+    metaDirty = false;
+    constructor(transport, handlers, client, sessionId) {
+        super(transport);
+        this.handlers = handlers;
+        this.client = client;
+        this.sessionId = sessionId;
+        this.start();
+    }
+    entries() {
+        return this.visible.values();
+    }
+    dispose() {
+        for (const read of this.pending)
+            read.controller.abort();
+        this.pending.clear();
+    }
+    invalidate() {
+        const hadSnapshot = this.watermark !== null;
+        this.cancelChange();
+        this.generation++;
+        this.watermark = null;
+        this.dispose();
+        this.rows.clear();
+        this.visible.replace([]);
+        this.timelineMeta = { tasks: [], workflows: [], plans: [], artifacts: [] };
+        this.rowsDirty = this.metaDirty = false;
+        if (hadSnapshot)
+            this.handlers.onReset?.();
+    }
+    handleFrame(frame) {
+        switch (frame.frame) {
+            case "timeline_snapshot":
+                this.invalidate();
+                this.watermark = frame.watermark;
+                for (const row of frame.entries)
+                    this.rows.set(row.timeline_id, row);
+                this.visible.replace(frame.entries);
+                this.timelineMeta = normalizeTimelineMeta(frame.timeline_meta);
+                this.stamp = frame.stamp;
+                this.handlers.onSnapshot?.({
+                    entries: frame.entries,
+                    cursor: frame.cursor,
+                    watermark: frame.watermark,
+                });
+                this.rowsDirty = this.metaDirty = true;
+                this.live();
+                this.changed(true);
+                break;
+            case "caught_up":
+                // A partial replay leaves stamp unchanged and is replayed again.
+                this.stamp = frame.stamp;
+                this.live();
+                this.changed(true);
+                break;
+            case "timeline_meta_snapshot":
+                this.timelineMeta = normalizeTimelineMeta(frame.timeline_meta);
+                this.metaDirty = true;
+                if (frame.stamp !== null) {
+                    this.stamp = frame.stamp;
+                    this.live();
+                }
+                this.changed();
+                break;
+            case "mutation":
+                if (frame.mutation.type === "session_swept") {
+                    this.restart();
+                    return;
+                }
+                this.apply(frame.mutation);
+                if (frame.stamp !== null) {
+                    this.stamp = frame.stamp;
+                    this.live();
+                }
+                this.changed();
+                break;
+            case "resync":
+                this.stamp = null;
+                this.invalidate();
+                this.setStatus("resyncing");
+                break;
+            default:
+                break;
+        }
+    }
+    apply(mutation) {
+        if (mutation.type !== "message" &&
+            mutation.type !== "tool_updated" &&
+            mutation.type !== "usage")
+            return;
+        for (const read of this.pending) {
+            // An overwhelmed read retries instead of silently dropping a late patch.
+            if (read.mutations.length >= 4096)
+                read.controller.abort();
+            else
+                read.mutations.push(mutation);
+        }
+        const current = this.rows.get(mutation.timeline_id);
+        const row = patchRow(current, mutation);
+        if (row === undefined || row === current)
+            return;
+        this.rows.set(row.timeline_id, row);
+        if (this.visible.get(row.timeline_id) !== undefined ||
+            (current === undefined && mutation.type === "message")) {
+            this.visible.set(row);
+            this.rowsDirty = true;
+        }
+    }
+    /** Hold a page in this cache without displaying it until the reader pulls. */
+    async fetchPage(cursor, limit = 200, signal) {
+        return this.read(async (signal) => this.client.timeline(this.sessionId, { cursor, limit }, signal), false, signal);
+    }
+    /** Reveal cached identities using their latest patched values. */
+    reveal(entries) {
+        for (const entry of entries) {
+            const row = this.rows.get(entry.timeline_id);
+            if (row !== undefined)
+                this.visible.set(row);
+        }
+        this.rowsDirty = true;
+        this.changed(true);
+    }
+    async loadEntry(timelineId, signal) {
+        await this.read(async (signal) => {
+            const result = await this.client.timelineEntryResponse(this.sessionId, timelineId, signal);
+            return { entries: [result.entry], watermark: result.watermark, cursor: null };
+        }, true, signal);
+        return true;
+    }
+    async read(load, show, signal) {
+        if (this.closed || this.watermark === null)
+            throw new DOMException("The session is synchronizing", "AbortError");
+        const generation = this.generation;
+        const read = { controller: new AbortController(), mutations: [] };
+        this.pending.add(read);
+        const combined = AbortSignal.any([read.controller.signal, ...(signal ? [signal] : [])]);
+        try {
+            const page = await load(combined);
+            combined.throwIfAborted();
+            if (generation !== this.generation || this.closed)
+                throw new DOMException("The session changed", "AbortError");
+            if (page.watermark !== this.watermark)
+                throw new CursorExpiredError("The session was rewritten");
+            for (const incoming of page.entries) {
+                let row = incoming;
+                for (const mutation of read.mutations) {
+                    if ((mutation.type === "message" ||
+                        mutation.type === "tool_updated" ||
+                        mutation.type === "usage") &&
+                        mutation.timeline_id === incoming.timeline_id)
+                        row = patchRow(row, mutation);
+                }
+                if (row === undefined)
+                    continue;
+                this.rows.set(row.timeline_id, row);
+                if (show || this.visible.get(row.timeline_id) !== undefined) {
+                    this.visible.set(row);
+                    this.rowsDirty = true;
+                }
+            }
+            this.changed(show);
+            return page;
+        }
+        catch (error) {
+            if (error instanceof CursorExpiredError && generation === this.generation) {
+                this.restart();
+                this.handlers.onError?.({ code: "cursor_expired", message: error.message });
+            }
+            throw error;
+        }
+        finally {
+            this.pending.delete(read);
+        }
+    }
+    flushChanges() {
+        if (this.rowsDirty) {
+            this.rowsDirty = false;
+            this.handlers.onChange?.(this.entries());
+        }
+        if (this.metaDirty) {
+            this.metaDirty = false;
+            this.handlers.onTimelineMetaChange?.(this.timelineMeta);
+        }
+    }
+    onStatus(status) {
+        this.handlers.onStatus?.(status);
+    }
+    onError(error) {
+        this.handlers.onError?.(error);
+    }
+}
+export class MetaSubscription extends BaseSubscription {
+    handlers;
+    runtimes = new OrderedCache((r) => r.id, (a, b) => a.id.localeCompare(b.id));
+    projects = new OrderedCache((r) => r.id, (a, b) => a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
+    sessions = new OrderedCache((r) => r.id, (a, b) => b.updated_at - a.updated_at || a.id.localeCompare(b.id));
+    dirty = false;
+    source = "snapshot";
+    constructor(transport, handlers) {
+        super(transport);
+        this.handlers = handlers;
+        this.start();
+    }
+    state() {
+        return {
+            runtimes: this.runtimes.values(),
+            projects: this.projects.values(),
+            sessions: this.sessions.values(),
+        };
+    }
+    invalidate() {
+        this.cancelChange();
+        this.dirty = false;
+    }
+    handleFrame(frame) {
+        switch (frame.frame) {
+            case "meta_snapshot":
+                this.runtimes.replace(frame.runtimes);
+                this.projects.replace(frame.projects);
+                this.sessions.replace(frame.sessions);
+                this.dirty = true;
+                this.source = "snapshot";
+                this.live();
+                this.changed(true);
+                break;
+            case "mutation": {
+                const mutation = frame.mutation;
+                if (mutation.type === "runtime") {
+                    const { type: _tag, ...row } = mutation;
+                    this.runtimes.set(row);
+                }
+                else if (mutation.type === "project") {
+                    const { type: _tag, ...row } = mutation;
+                    this.projects.set(row);
+                }
+                else if (mutation.type === "session") {
+                    const { type: _tag, ...row } = mutation;
+                    this.sessions.set(row);
+                }
+                else
+                    return;
+                this.dirty = true;
+                this.source = "mutation";
+                this.changed();
+                break;
+            }
+            case "resync":
+                this.invalidate();
+                this.setStatus("resyncing");
+                break;
+            default:
+                break;
+        }
+    }
+    flushChanges() {
+        if (this.dirty) {
+            this.dirty = false;
+            this.handlers.onChange?.(this.state(), this.source);
+        }
+    }
+    onStatus(status) {
+        this.handlers.onStatus?.(status);
+    }
+    onError(error) {
+        this.handlers.onError?.(error);
+    }
+}
+export class CollaborationSubscription extends BaseSubscription {
+    handlers;
+    rows = new OrderedCache((r) => r.timeline_id, timelineOrder);
+    observations = new Map();
+    dirty = false;
+    constructor(transport, handlers) {
+        super(transport);
+        this.handlers = handlers;
+        this.start();
+    }
+    observe(observation) {
+        this.observations.set(JSON.stringify([observation.response_id, observation.model, observation.effort]), observation);
+    }
+    invalidate() {
+        this.cancelChange();
+        this.rows.replace([]);
+        this.observations.clear();
+        this.dirty = false;
+        this.handlers.onReset?.();
+    }
+    handleFrame(frame) {
+        switch (frame.frame) {
+            case "collaboration_snapshot":
+                this.invalidate();
+                this.rows.replace(frame.entries);
+                for (const observation of frame.response_runtimes)
+                    this.observe(observation);
+                this.dirty = true;
+                this.live();
+                this.changed(true);
+                break;
+            case "response_runtime":
+                this.observe(frame.observation);
+                this.dirty = true;
+                this.changed();
+                break;
+            case "mutation":
+                if (frame.mutation.type === "message" && frame.mutation.body.type === "collaboration") {
+                    const { type: _tag, ...row } = frame.mutation;
+                    this.rows.set(row);
+                    this.dirty = true;
+                    this.changed();
+                }
+                break;
+            case "resync":
+                this.invalidate();
+                this.setStatus("resyncing");
+                break;
+            default:
+                break;
+        }
+    }
+    flushChanges() {
+        if (this.dirty) {
+            this.dirty = false;
+            this.handlers.onChange?.({
+                entries: this.rows.values(),
+                response_runtimes: [...this.observations.values()],
+            });
+        }
+    }
+    onStatus(status) {
+        this.handlers.onStatus?.(status);
+    }
+    onError(error) {
+        this.handlers.onError?.(error);
+    }
+}