agent-tempo 1.0.1

package/dist/client/subscribe.d.ts

@@ -0,0 +1,108 @@
+/**
+ * `TempoClient.subscribe` — AsyncIterable wrapper over the daemon's
+ * `/v1/events*` SSE endpoints. PR-3 of #94/#95.
+ *
+ * **Reference**: [`docs/SSE-PROTOCOL.md`](../../docs/SSE-PROTOCOL.md),
+ * [`docs/adr/0010-drop-caller-controllable-event-cursor.md`](../../docs/adr/0010-drop-caller-controllable-event-cursor.md),
+ * and the wire types in [`src/http/event-types.ts`](../http/event-types.ts).
+ *
+ * ## Design
+ *
+ * - **Dual transport** — the wrapper picks the best transport for the
+ *   environment + auth context:
+ *   - **Native `EventSource`** when available AND no bearer token is set
+ *     (loopback browser dashboard). Native auto-reconnect handles
+ *     `Last-Event-ID` for free.
+ *   - **`fetch().body`** otherwise (Node 20+, or any path that needs the
+ *     `Authorization` header). Manual reconnect + backoff + `Last-Event-ID`
+ *     tracking implemented here.
+ *
+ *   Native `EventSource` cannot set custom request headers on initial
+ *   connect, so any path that requires `Authorization: Bearer …` must use
+ *   fetch. The transport choice is hidden from the consumer — the
+ *   `AsyncIterable<TempoEvent>` shape is identical on both paths.
+ *
+ * - **Caller-controllable cursor resume is not supported (ADR 0010).**
+ *   `SubscribeOptions` exposes `signal` and `topics` only. Snapshot-then-
+ *   stream (server emits `event: snapshot` on fresh connect; SSE-PROTOCOL.md
+ *   §7.2) covers every realistic case. In-session reconnects use
+ *   `Last-Event-ID` under the hood — auto-managed by `EventSource`,
+ *   tracked manually by the fetch wrapper.
+ *
+ * - **Transparent reconnect on the fetch path (§7.5).** TCP drops,
+ *   premature stream ends, and 5xx responses are retried with exponential
+ *   backoff (`100 ms × 2^attempt`, cap 30 s, reset on first event of a
+ *   new connection). The most-recently-seen event id is replayed on each
+ *   retry so consumers see seamless replay/`gap` behaviour. Native
+ *   `EventSource` does the equivalent automatically.
+ *
+ * - **Gap events surface to consumer (§7.5/§7.6).** The wrapper does NOT
+ *   re-fetch `/v1/state/:ensemble` on `gap` or `chat.compressed`; those
+ *   are application-level concerns that the consumer (TUI / web dashboard)
+ *   handles. The wrapper just relays events faithfully.
+ *
+ * - **Cancellation contract (§7.4).** Two paths:
+ *   - `subscribe(..., { signal })` — when the external `AbortSignal`
+ *     aborts, the wrapper closes the underlying transport and ends the
+ *     iterator.
+ *   - `for await … break` — the JavaScript runtime invokes the iterator's
+ *     `return()` method, which in turn calls `controller.abort('iterator.return')`
+ *     and tears down the transport. Without this, an idle SSE stream would
+ *     leak the underlying socket.
+ */
+import { type SubscribeOptions, type TempoEvent } from '../http/event-types';
+/**
+ * Dependencies the wrapper needs at construction time. All fields are
+ * optional with sensible Node 20+ defaults; tests override them.
+ */
+export interface SubscribeDeps {
+    /**
+     * Daemon HTTP base URL (e.g. `http://127.0.0.1:8473`). When omitted, the
+     * URL is derived per-call from `~/.agent-tempo/daemon.port` with a
+     * `127.0.0.1:8473` fallback. Re-read on every reconnect so a daemon
+     * restart on a new port heals automatically.
+     */
+    baseUrl?: string;
+    /**
+     * Bearer token for `Authorization`. When omitted, no auth header is
+     * sent — correct for the loopback default path. Bearer mode is required
+     * when bind addr is non-loopback or the request `Origin` is non-loopback
+     * (SSE-PROTOCOL.md §3); supply the token explicitly in those cases.
+     *
+     * **Setting this forces the fetch transport** — native `EventSource`
+     * cannot attach an `Authorization` header on the initial connect.
+     */
+    token?: string;
+    /** Override `fetch` — used by tests to drive the wrapper deterministically. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Override the `EventSource` constructor. When omitted, the global
+     * `EventSource` is used if available (browsers); when neither is
+     * present (Node 20), the wrapper falls back to fetch.
+     */
+    EventSourceImpl?: typeof EventSource;
+    /**
+     * Override sleep — used by tests to fast-forward backoff. Accepts an
+     * `AbortSignal` so the wrapper can wake early on abort.
+     */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * Build the `subscribe` method for a TempoClient instance. Returns a
+ * function with two overloads — per-ensemble (`subscribe(ensemble, opts)`)
+ * and global (`subscribe(opts)`).
+ */
+export declare function createSubscribe(deps?: SubscribeDeps): {
+    (ensemble: string, opts?: SubscribeOptions): AsyncIterable<TempoEvent>;
+    (opts?: SubscribeOptions): AsyncIterable<TempoEvent>;
+};
+/**
+ * Surfaced to the consumer when the daemon returned a permanent HTTP
+ * status (401 unauthorized, 404 ensemble-not-found). Consumers should not
+ * retry on these.
+ */
+export declare class SubscribeHttpError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+}