@sigrun/tui 0.4.1 → 0.5.0

package/dist/sse.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The TUI's §5 conversation stream watcher (Task 4; delta frames in core
+ * hardening W3 Task 3, spec §7.3 ruling 11): a Node-side SSE client over
+ * `GET /v1/conversations/:id/stream` carrying `snapshot` and `delta` frames.
+ *
+ * This watcher is the TUI's delta folder: `snapshot` REPLACES the held view
+ * wholesale, `delta` folds into it via the shared `applyDelta`, and every
+ * accepted frame surfaces to the consumer as a FULL immutable
+ * `ConversationViewWire` revision — the consumer replaces, never
+ * accumulates. The server sends a fresh `snapshot` on EVERY connect, so a
+ * reconnect's snapshot SUBSUMES any frame missed while disconnected — no
+ * replay, no stale merge (Review Focus 1).
+ *
+ * Node 22 global fetch + manual frame parsing: `:` lines are comments,
+ * `data:` lines accumulate until a blank line dispatches the frame;
+ * multi-line `data:` joins with `\n`.
+ *
+ * Transport failures close the reader and reconnect with exponential
+ * backoff (base 250ms doubling, capped at 4s, ±30% jitter). Reconnects
+ * give up after 10 consecutive failures with ONE final `onError`; the
+ * counter resets on every successful open and at watch start. Transport
+ * failures (read error, mid-stream close) emit at most one `onError` per
+ * connection (a read failure and the ensuing close are the same failure);
+ * a non-OK status on (re)connect reports per attempt — it never opens a
+ * connection. A 401 on (re)connect is TERMINAL (Task 5): the auth-failure
+ * string surfaces once and the watcher stops — a revoked credential
+ * cannot recover by reconnecting, so no retry ladder fires. A malformed
+ * frame reports
+ * `onError` and the stream STAYS OPEN — one bad frame must never kill the
+ * transport.
+ */
+import { type ConversationViewWire } from "./api.js";
+import type { HostEventWire } from "@sigrun/shared/views";
+export interface WatchHandlers {
+    /** A `snapshot` frame arrived (the full view on connect/re-attach). */
+    readonly onSnapshot?: (view: ConversationViewWire) => void;
+    /**
+     * A full revision arrived — either the connect snapshot or the fold of
+     * every `delta` since it. The view is ALWAYS a full immutable
+     * `ConversationViewWire`: replace, never accumulate.
+     */
+    readonly onView?: (view: ConversationViewWire) => void;
+    /**
+     * A failure: a malformed frame (stream stays open) or a transport
+     * error (a reconnect follows unless `unwatch` ran). Carries a
+     * human-readable description — fail loud, never silent.
+     */
+    readonly onError?: (message: string) => void;
+    /** The underlying connection (re)opened with an OK response. */
+    readonly onOpen?: () => void;
+}
+export interface WatchOptions {
+    /**
+     * The server's origin (e.g. `http://127.0.0.1:PORT`) — required; the
+     * TUI is a remote client.
+     */
+    readonly baseUrl: string;
+    /** `X-Sigrun-User` identity header (Task 2); omitted when absent/empty. */
+    readonly user?: string;
+    /**
+     * The bearer token (Task 7): `authorization: Bearer <token>` on the
+     * stream connect; omitted when absent/empty/whitespace.
+     */
+    readonly token?: string;
+    /** Backoff ladder base in ms (default 250; tests shrink it). */
+    readonly reconnectBaseMs?: number;
+    /** Backoff cap in ms (default 4000). */
+    readonly reconnectMaxMs?: number;
+    /** Injected for tests; defaults to the ambient `fetch`. */
+    readonly fetch?: typeof globalThis.fetch;
+}
+/** The watcher handle: `unwatch()` closes the stream, idempotent. */
+export type Unwatch = () => void;
+/**
+ * Watch one conversation's stream. Returns `unwatch()`. Reconnects on
+ * stream drop; a reconnect's fresh snapshot replaces state wholesale.
+ */
+export declare function watchConversation(conversationId: number, handlers: WatchHandlers, options: WatchOptions): Unwatch;
+/**
+ * The host events reader (core hardening W3 Task 4, spec §7.4): a
+ * Node-side SSE client over `GET /v1/events` carrying `HostEventWire`
+ * frames (`event: <type>` + single-line `data:` JSON). The TUI's launch
+ * wiring subscribes ONCE per process: `conversation.*` events refetch the
+ * conversation list, `interaction.*` kicks the prompter, `ambient.changed`
+ * refetches the ambient chrome — the old list/interaction/ambient poll
+ * timers are gone.
+ *
+ * Same transport discipline as `watchConversation`: backoff ladder
+ * (250ms doubling, 4s cap, ±30% jitter), one `onError` per failed
+ * connection, give up after 10 consecutive failures, malformed frames
+ * report + keep the stream open. There is no replay — a reconnect's
+ * first post-connect frame suffices because the handlers REFETCH (the
+ * list/interaction/ambient GETs), never merge.
+ */
+export interface EventsHandlers {
+    /** A host event arrived (already JSON-parsed). */
+    readonly onEvent: (event: HostEventWire) => void;
+    /**
+     * The hello frame's streamId (UI-blocks U3 Task 4, spec §7.3's W3
+     * amendment): fired on EVERY (re)connect — a reconnect's hello
+     * carries a NEW id, and the channel re-fetches every visible surface
+     * with it (re-registering the watcher entries). Surface fetches send
+     * the current id as `X-Sigrun-Stream`.
+     */
+    readonly onHello?: (streamId: string) => void;
+    /** A failure: malformed frame (stays open) or transport error (reconnects). */
+    readonly onError?: (message: string) => void;
+    /** The underlying connection (re)opened with an OK response. */
+    readonly onOpen?: () => void;
+}
+/** Subscribe to the global events stream. Returns the unsubscribe. */
+export declare function watchEvents(handlers: EventsHandlers, options: WatchOptions): Unwatch;

package/dist/sse.js

@@ -0,0 +1,418 @@
+/**
+ * The TUI's §5 conversation stream watcher (Task 4; delta frames in core
+ * hardening W3 Task 3, spec §7.3 ruling 11): a Node-side SSE client over
+ * `GET /v1/conversations/:id/stream` carrying `snapshot` and `delta` frames.
+ *
+ * This watcher is the TUI's delta folder: `snapshot` REPLACES the held view
+ * wholesale, `delta` folds into it via the shared `applyDelta`, and every
+ * accepted frame surfaces to the consumer as a FULL immutable
+ * `ConversationViewWire` revision — the consumer replaces, never
+ * accumulates. The server sends a fresh `snapshot` on EVERY connect, so a
+ * reconnect's snapshot SUBSUMES any frame missed while disconnected — no
+ * replay, no stale merge (Review Focus 1).
+ *
+ * Node 22 global fetch + manual frame parsing: `:` lines are comments,
+ * `data:` lines accumulate until a blank line dispatches the frame;
+ * multi-line `data:` joins with `\n`.
+ *
+ * Transport failures close the reader and reconnect with exponential
+ * backoff (base 250ms doubling, capped at 4s, ±30% jitter). Reconnects
+ * give up after 10 consecutive failures with ONE final `onError`; the
+ * counter resets on every successful open and at watch start. Transport
+ * failures (read error, mid-stream close) emit at most one `onError` per
+ * connection (a read failure and the ensuing close are the same failure);
+ * a non-OK status on (re)connect reports per attempt — it never opens a
+ * connection. A 401 on (re)connect is TERMINAL (Task 5): the auth-failure
+ * string surfaces once and the watcher stops — a revoked credential
+ * cannot recover by reconnecting, so no retry ladder fires. A malformed
+ * frame reports
+ * `onError` and the stream STAYS OPEN — one bad frame must never kill the
+ * transport.
+ */
+import { AUTH_FAILURE_MESSAGE } from "./api.js";
+import { applyDelta } from "@sigrun/shared/view-delta";
+/** Parse a frame; `undefined` when the payload is not an object. */
+function parseFrame(data) {
+    let parsed;
+    try {
+        parsed = JSON.parse(data);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return undefined;
+    }
+    return parsed;
+}
+/**
+ * An incremental SSE frame parser: feed it chunks; it emits complete
+ * frames (`{event, data}`). `:` lines are comments; `data:` accumulates
+ * until a blank line; the field-name space after `:` is stripped once.
+ */
+function createFrameParser(emit) {
+    let buffer = "";
+    let event = "";
+    let data = [];
+    function dispatchLine(line) {
+        if (line === "") {
+            if (data.length > 0) {
+                emit({ event, data: data.join("\n") });
+            }
+            event = "";
+            data = [];
+            return;
+        }
+        if (line.startsWith(":")) {
+            return; // a comment (the heartbeat `: ping`)
+        }
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" ")) {
+            value = value.slice(1);
+        }
+        if (field === "event") {
+            event = value;
+        }
+        else if (field === "data") {
+            data.push(value);
+        }
+        // `id:` (and unknown fields) are accepted and ignored — every frame
+        // is a full revision, so the revision cursor is never needed.
+    }
+    return (chunk) => {
+        buffer += chunk;
+        for (;;) {
+            const newline = buffer.indexOf("\n");
+            if (newline === -1)
+                return;
+            let line = buffer.slice(0, newline);
+            buffer = buffer.slice(newline + 1);
+            if (line.endsWith("\r")) {
+                line = line.slice(0, -1);
+            }
+            dispatchLine(line);
+        }
+    };
+}
+/**
+ * Watch one conversation's stream. Returns `unwatch()`. Reconnects on
+ * stream drop; a reconnect's fresh snapshot replaces state wholesale.
+ */
+export function watchConversation(conversationId, handlers, options) {
+    const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const baseMs = options.reconnectBaseMs ?? 250;
+    const maxMs = options.reconnectMaxMs ?? 4_000;
+    /** Give up after this many consecutive failed reconnects. */
+    const maxAttempts = 10;
+    const user = options.user?.trim();
+    const token = options.token?.trim();
+    const headers = {
+        accept: "text/event-stream",
+        ...(user === undefined || user === "" ? {} : { "x-sigrun-user": user }),
+        ...(token === undefined || token === ""
+            ? {}
+            : { authorization: `Bearer ${token}` }),
+    };
+    const url = `${options.baseUrl}/v1/conversations/${conversationId}/stream`;
+    let closed = false;
+    let attempts = 0;
+    let timer;
+    let abort;
+    /** Per-attempt onError dedupe (fix wave A10); cleared on open. */
+    let reportedTransportError = false;
+    /**
+     * The held view: the last snapshot, folded with every accepted delta
+     * since. `undefined` before the first snapshot — a delta arriving then
+     * is malformed (there is nothing to fold into).
+     */
+    let currentView;
+    function scheduleReconnect() {
+        attempts += 1;
+        const base = Math.min(baseMs * 2 ** (attempts - 1), maxMs);
+        // ±30% jitter: correlated drops must not reconnect in lockstep.
+        const delay = base * (1 + (Math.random() * 0.6 - 0.3));
+        timer = setTimeout(() => {
+            timer = undefined;
+            void connect();
+        }, delay);
+    }
+    async function connect() {
+        if (closed)
+            return;
+        if (attempts >= maxAttempts) {
+            // Give up (fix wave A3): the 10th consecutive failure was just
+            // reported by its caller; emit ONE final notice and stop — no
+            // 11th fetch fires.
+            handlers.onError?.(`giving up after ${maxAttempts} failed reconnects`);
+            return;
+        }
+        const controller = new AbortController();
+        abort = controller;
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                method: "GET",
+                headers,
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            if (closed)
+                return;
+            handlers.onError?.(`conversation stream connect failed: ${error.message}`);
+            scheduleReconnect();
+            return;
+        }
+        if (!response.ok || response.body === null) {
+            if (closed)
+                return;
+            // A 401 (Task 5) is terminal: a credential cannot recover by
+            // reconnecting — surface the auth-failure string ONCE and stop
+            // (never a silent retry ladder against a revoked token).
+            if (response.status === 401) {
+                handlers.onError?.(AUTH_FAILURE_MESSAGE);
+                return;
+            }
+            handlers.onError?.(`conversation stream responded with status ${response.status}`);
+            scheduleReconnect();
+            return;
+        }
+        attempts = 0;
+        // The open clears the per-attempt dedupe (fix wave A10): the next
+        // failed connection gets its own single onError.
+        reportedTransportError = false;
+        handlers.onOpen?.();
+        const parser = createFrameParser((frame) => {
+            if (closed)
+                return;
+            const parsed = parseFrame(frame.data);
+            if (parsed === undefined) {
+                handlers.onError?.(`malformed ${frame.event === "" ? "message" : frame.event} frame (not a view object)`);
+                return;
+            }
+            if (frame.event === "snapshot") {
+                // A fresh snapshot SUBSUMES anything missed — the fold re-bases
+                // on it wholesale; nothing here merges.
+                currentView = parsed;
+                handlers.onSnapshot?.(currentView);
+            }
+            else if (frame.event === "delta") {
+                if (currentView === undefined) {
+                    handlers.onError?.("malformed delta frame (arrived before any snapshot)");
+                    return;
+                }
+                // Fold, then surface the FULL revision: the consumer's contract
+                // stays "replace, never accumulate".
+                currentView = applyDelta(currentView, parsed);
+                handlers.onView?.(currentView);
+            }
+            else {
+                handlers.onError?.(`unknown stream event "${frame.event}"`);
+            }
+        });
+        const decoder = new TextDecoder();
+        try {
+            const reader = response.body.getReader();
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                parser(decoder.decode(value, { stream: true }));
+            }
+        }
+        catch (error) {
+            if (closed)
+                return;
+            // Dedupe (fix wave A10): a read failure and the close that
+            // follows it are ONE connection failure — one onError.
+            if (!reportedTransportError) {
+                reportedTransportError = true;
+                handlers.onError?.(`conversation stream read failed: ${error.message}`);
+            }
+        }
+        if (!closed) {
+            if (!reportedTransportError) {
+                reportedTransportError = true;
+                handlers.onError?.("conversation stream closed by the server");
+            }
+            scheduleReconnect();
+        }
+    }
+    void connect();
+    return () => {
+        if (closed)
+            return;
+        closed = true;
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        abort?.abort();
+        abort = undefined;
+    };
+}
+/** Loose parse: the launch wiring only branches on `type`. */
+function parseEvent(data) {
+    let parsed;
+    try {
+        parsed = JSON.parse(data);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        Array.isArray(parsed) ||
+        typeof parsed.type !== "string") {
+        return undefined;
+    }
+    return parsed;
+}
+/** Subscribe to the global events stream. Returns the unsubscribe. */
+export function watchEvents(handlers, options) {
+    const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const baseMs = options.reconnectBaseMs ?? 250;
+    const maxMs = options.reconnectMaxMs ?? 4_000;
+    const maxAttempts = 10;
+    const user = options.user?.trim();
+    const token = options.token?.trim();
+    const headers = {
+        accept: "text/event-stream",
+        ...(user === undefined || user === "" ? {} : { "x-sigrun-user": user }),
+        ...(token === undefined || token === ""
+            ? {}
+            : { authorization: `Bearer ${token}` }),
+    };
+    const url = `${options.baseUrl}/v1/events`;
+    let closed = false;
+    let attempts = 0;
+    let timer;
+    let abort;
+    let reportedTransportError = false;
+    function scheduleReconnect() {
+        attempts += 1;
+        const base = Math.min(baseMs * 2 ** (attempts - 1), maxMs);
+        const delay = base * (1 + (Math.random() * 0.6 - 0.3));
+        timer = setTimeout(() => {
+            timer = undefined;
+            void connect();
+        }, delay);
+    }
+    async function connect() {
+        if (closed)
+            return;
+        if (attempts >= maxAttempts) {
+            handlers.onError?.(`events stream: giving up after ${maxAttempts} failed reconnects`);
+            return;
+        }
+        const controller = new AbortController();
+        abort = controller;
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                method: "GET",
+                headers,
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            if (closed)
+                return;
+            handlers.onError?.(`events stream connect failed: ${error.message}`);
+            scheduleReconnect();
+            return;
+        }
+        if (!response.ok || response.body === null) {
+            if (closed)
+                return;
+            // A 401 (Task 5) is terminal — same rule as the conversation
+            // stream: the auth-failure string ONCE, never a retry ladder.
+            if (response.status === 401) {
+                handlers.onError?.(AUTH_FAILURE_MESSAGE);
+                return;
+            }
+            handlers.onError?.(`events stream responded with status ${response.status}`);
+            scheduleReconnect();
+            return;
+        }
+        attempts = 0;
+        reportedTransportError = false;
+        handlers.onOpen?.();
+        const parser = createFrameParser((frame) => {
+            if (closed)
+                return;
+            // The hello frame (U3 Task 4) is connection-local: it names
+            // THIS stream for the watcher registry — surface fetches send
+            // the id as `X-Sigrun-Stream`; a NEW id (reconnect) re-fires
+            // so the channel re-registers. It never reaches onEvent (the
+            // launch wiring's switch would ignore it anyway — event types
+            // are an open set). Parsed loosely: the hello payload carries
+            // `streamId`, not a `type` member.
+            if (frame.event === "hello") {
+                let parsed;
+                try {
+                    parsed = JSON.parse(frame.data);
+                }
+                catch {
+                    handlers.onError?.("malformed hello frame (not JSON)");
+                    return;
+                }
+                // SAFETY: the JSON.parse output is unknown; the read below
+                // narrows `streamId` by typeof before use.
+                const streamId = parsed.streamId;
+                if (typeof streamId === "string") {
+                    handlers.onHello?.(streamId);
+                }
+                else {
+                    handlers.onError?.("malformed hello frame (no streamId)");
+                }
+                return;
+            }
+            const event = parseEvent(frame.data);
+            if (event === undefined) {
+                handlers.onError?.(`malformed ${frame.event === "" ? "message" : frame.event} frame (not an event object)`);
+                return;
+            }
+            handlers.onEvent(event);
+        });
+        const decoder = new TextDecoder();
+        try {
+            const reader = response.body.getReader();
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                parser(decoder.decode(value, { stream: true }));
+            }
+        }
+        catch (error) {
+            if (closed)
+                return;
+            if (!reportedTransportError) {
+                reportedTransportError = true;
+                handlers.onError?.(`events stream read failed: ${error.message}`);
+            }
+        }
+        if (!closed) {
+            if (!reportedTransportError) {
+                reportedTransportError = true;
+                handlers.onError?.("events stream closed by the server");
+            }
+            scheduleReconnect();
+        }
+    }
+    void connect();
+    return () => {
+        if (closed)
+            return;
+        closed = true;
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        abort?.abort();
+        abort = undefined;
+    };
+}

package/dist/theme.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The TUI theme (Task C1, UI refresh): wraps the shared themes module's
+ * palettes in pi-tui's color pipeline (parseColor → foregroundAnsi /
+ * backgroundAnsi) so components style text through token names instead
+ * of raw SGR sequences. The palette DATA lives in one place
+ * (@sigrun/shared/themes, shared with the webui — zero duplication);
+ * this module owns only the terminal mapping.
+ *
+ * Degradation: `colorMode` threads through foregroundAnsi/backgroundAnsi,
+ * so a 256color terminal gets `38;5;N` (pi-tui's nearest-256 mapping)
+ * instead of truecolor `38;2;r;g;b`. The launcher resolves the mode at
+ * boot via `getTerminalColorMode()`; tests pass it explicitly.
+ *
+ * The `code` token is CSS `rgba(...)` (the shared data's overlay chip):
+ * pi-tui's parseColor takes hex/`rgb()` only, so it is alpha-composited
+ * over the mode's `bg` token here — the same visual the webui gets from
+ * layering the overlay on the background.
+ */
+import { type TerminalColorMode } from "@earendil-works/pi-tui";
+import { type AccentName, type ModeName, type PaletteName, type PaletteTokens } from "@sigrun/shared/themes";
+/** A palette token, the accent colour, or a state colour (warn/bad). */
+export type TuiToken = keyof PaletteTokens | "accent" | "warn" | "bad";
+/**
+ * Terminal styling surface: token-named fg/bg plus the plain attribute
+ * helpers. `fg`/`bg` return string wrappers so call sites compose
+ * (`theme.fg("muted")(text)`) without holding SGR sequences.
+ */
+export interface TuiTheme {
+    fg(token: TuiToken): (s: string) => string;
+    bg(token: TuiToken): (s: string) => string;
+    bold(s: string): string;
+    dim(s: string): string;
+    italic(s: string): string;
+}
+export interface TuiThemeOptions {
+    readonly palette: PaletteName;
+    readonly accent: AccentName;
+    readonly mode: ModeName;
+    readonly colorMode: TerminalColorMode;
+}
+/**
+ * Build the theme. Precomputes each token's fg/bg SGR (pi-tui's cached
+ * sequence idiom — `styleTextWithAnsi` without the dependency) and wraps
+ * it in reset-terminated spans.
+ */
+export declare function createTuiTheme(options: TuiThemeOptions): TuiTheme;
+/**
+ * The no-colour fallback (tests, non-TTY sinks): every method is the
+ * identity — the structure renders identically without SGR sequences.
+ */
+export declare function plainTuiTheme(): TuiTheme;