@hainiva/agent-sdk 0.0.0-stage → 0.2.0

package/dist/cjs/session.d.cts

@@ -0,0 +1,101 @@
+import { TypedEmitter } from "./emitter.cjs";
+import { type Logger } from "./log.cjs";
+import { Redactor } from "./redact.cjs";
+/**
+ * Where the session is kept between launches. Same shape as @hainiva/app-sdk's.
+ * The default is in memory (nothing persisted). On the web, `localStorageStore`
+ * (`@hainiva/agent-sdk/web`) is opt-in; in React Native use
+ * `secureStoreSessionStore` (`@hainiva/agent-sdk/react-native`) — the refresh
+ * token then lives only in the Keychain / Android Keystore.
+ */
+export interface SessionStore {
+    get(): Promise<string | null> | string | null;
+    set(value: string): Promise<void> | void;
+    remove(): Promise<void> | void;
+}
+/** Keeps the session for the life of the page / JS context only. The default. */
+export declare function memoryStore(): SessionStore;
+/** A staff session. Fields beyond these are kept as the server sent them. */
+export interface AgentSession {
+    accessToken: string;
+    /** ISO time. */
+    accessExpiresAt: string;
+    refreshToken: string;
+    /** ISO time. */
+    refreshExpiresAt: string;
+    [field: string]: unknown;
+}
+/**
+ * Ask YOUR backend for a fresh staff assertion (a short-lived JWT it signs with
+ * the agent app's private key). Called every time a new session is needed —
+ * the SDK never caches or stores an assertion, and you must not either: each
+ * one carries a single-use `jti` and expires in minutes.
+ */
+export type GetAssertion = () => Promise<string>;
+/**
+ * How sessions are created and refreshed — bound by the REST client.
+ * TODO(S3b): implemented against `/agent/v1/sessions` once the S2 contract is final.
+ */
+export interface SessionTransport<S extends AgentSession = AgentSession> {
+    /** Exchange an assertion for a session (POST /agent/v1/sessions). */
+    exchange(assertion: string): Promise<S>;
+    /** Rotate: a new access token and (rotating) refresh token. */
+    refresh(refreshToken: string): Promise<Pick<S, "accessToken" | "accessExpiresAt"> & Partial<S>>;
+    /** End the session on the server (best effort). */
+    revoke?(session: S): Promise<void>;
+}
+export interface SessionManagerOptions<S extends AgentSession> {
+    getAssertion: GetAssertion;
+    transport: SessionTransport<S>;
+    /** Default: memoryStore(). */
+    store?: SessionStore;
+    /** Refresh this long before the access token expires. Default 60 s. */
+    refreshSkewMs?: number;
+    now?: () => number;
+    redactor?: Redactor;
+    log?: Logger;
+}
+export interface SessionEvents<S extends AgentSession> {
+    /** A new access token (after sign-in or refresh): e.g. send it on the socket. */
+    token: string;
+    session: S | null;
+}
+/**
+ * The staff session: sign in with a fresh assertion, keep it in the store,
+ * refresh before expiry (single flight — one refresh however many callers),
+ * sign in again with a NEW assertion when the refresh is refused.
+ */
+export declare class SessionManager<S extends AgentSession = AgentSession> {
+    private readonly o;
+    readonly events: TypedEmitter<SessionEvents<S>>;
+    private session;
+    private readonly store;
+    private readonly skew;
+    private readonly now;
+    readonly redactor: Redactor;
+    private readonly log;
+    private readonly refreshOnce;
+    private forceNext;
+    constructor(o: SessionManagerOptions<S>);
+    get current(): S | null;
+    /** Restore the stored session if it can still be refreshed, else sign in afresh. */
+    signIn(): Promise<S>;
+    /** A valid access token, refreshing first when it is about to expire. */
+    accessToken(): Promise<string>;
+    /**
+     * The server refused the access token (401 / socket 4001): the next
+     * accessToken() refreshes. Pass the token that was refused: a refusal of an
+     * OLDER token (a request that was in flight while another caller already
+     * refreshed) is ignored, so ten parallel 401s cause one refresh, not ten.
+     */
+    invalidate(refused?: string): void;
+    /** Forget the session here only (the server already ended it): no revoke call. */
+    clear(): Promise<void>;
+    /** End the session here and (best effort) on the server. */
+    signOut(): Promise<void>;
+    private fresh;
+    private doRefresh;
+    private readonly freshSignIn;
+    private keep;
+    private adopt;
+}

package/dist/cjs/singleFlight.cjs

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.singleFlight = singleFlight;
+exports.createTokenRefresher = createTokenRefresher;
+/**
+ * Calls `fn` at most once at a time: callers that arrive while it runs share its
+ * result (or its error). The next call after it settles runs `fn` again.
+ */
+function singleFlight(fn) {
+    let inFlight = null;
+    return () => {
+        inFlight ?? (inFlight = (async () => {
+            try {
+                return await fn();
+            }
+            finally {
+                inFlight = null;
+            }
+        })());
+        return inFlight;
+    };
+}
+/**
+ * Single-flight token refresh with a pluggable refresh function. Ten requests that
+ * find the token expired cause one refresh, not ten — which also keeps a
+ * rotating refresh token from being spent twice (reuse detection would then
+ * revoke the whole session family).
+ */
+function createTokenRefresher(o) {
+    const skew = o.skewMs ?? 60000;
+    const now = o.now ?? Date.now;
+    let current = null;
+    const run = singleFlight(async () => {
+        const t = await o.refresh();
+        if (!t || typeof t.token !== "string" || !t.token)
+            throw new Error("refresh returned no token");
+        current = t;
+        return t.token;
+    });
+    return {
+        get valid() { return current !== null && current.expiresAt - now() > skew; },
+        async get() {
+            if (current && current.expiresAt - now() > skew)
+                return current.token;
+            return run();
+        },
+        invalidate() { current = null; },
+    };
+}

package/dist/cjs/singleFlight.d.cts

@@ -0,0 +1,32 @@
+/**
+ * Calls `fn` at most once at a time: callers that arrive while it runs share its
+ * result (or its error). The next call after it settles runs `fn` again.
+ */
+export declare function singleFlight<T>(fn: () => Promise<T>): () => Promise<T>;
+export interface RefreshedToken {
+    token: string;
+    /** Epoch ms. */
+    expiresAt: number;
+}
+export interface TokenRefresherOptions {
+    /** Fetch a new token. Called once however many callers wait for it. */
+    refresh: () => Promise<RefreshedToken>;
+    /** Refresh this long before expiry. Default 60 s. */
+    skewMs?: number;
+    now?: () => number;
+}
+export interface TokenRefresher {
+    /** A token valid for at least `skewMs`, refreshing (once, shared) when needed. */
+    get(): Promise<string>;
+    /** Forget the current token (the server refused it): the next get() refreshes. */
+    invalidate(): void;
+    /** Whether a token is held that is still valid beyond the skew. */
+    readonly valid: boolean;
+}
+/**
+ * Single-flight token refresh with a pluggable refresh function. Ten requests that
+ * find the token expired cause one refresh, not ten — which also keeps a
+ * rotating refresh token from being spent twice (reuse detection would then
+ * revoke the whole session family).
+ */
+export declare function createTokenRefresher(o: TokenRefresherOptions): TokenRefresher;

package/dist/cjs/url.cjs

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertSafeUrl = assertSafeUrl;
+const errors_js_1 = require("./errors.cjs");
+const LOCAL = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+/** Query parameter names that would carry a credential. */
+const CREDENTIAL_PARAM = /token|assertion|secret|password|passw|key|auth|jwt|session|signature|ticket/i;
+/**
+ * A base / socket / media URL a partner configured, checked before use: TLS only,
+ * no user:password@, and no credential in the query string. Tokens travel in
+ * headers or in the socket's first frame — never in a URL, which ends up in
+ * access logs, proxies and browser history.
+ */
+function assertSafeUrl(raw, rules) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new errors_js_1.HainivaAgentError(0, "invalid_url", { kind: rules.kind });
+    }
+    const secure = rules.kind === "http" ? "https:" : "wss:";
+    const insecure = rules.kind === "http" ? "http:" : "ws:";
+    const local = LOCAL.has(u.hostname);
+    if (u.protocol !== secure && !(u.protocol === insecure && local && rules.allowInsecureLocalhost)) {
+        throw new errors_js_1.HainivaAgentError(0, "insecure_url", { expected: secure, got: u.protocol, host: u.host });
+    }
+    if (u.username || u.password)
+        throw new errors_js_1.HainivaAgentError(0, "credentials_in_url", { host: u.host });
+    let param = null;
+    u.searchParams.forEach((_v, name) => { if (!param && CREDENTIAL_PARAM.test(name))
+        param = name; });
+    if (param)
+        throw new errors_js_1.HainivaAgentError(0, "credentials_in_url", { host: u.host, param });
+    if (/eyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}/.test(u.search + u.hash + u.pathname)) {
+        throw new errors_js_1.HainivaAgentError(0, "credentials_in_url", { host: u.host });
+    }
+    return u;
+}

package/dist/cjs/url.d.cts

@@ -0,0 +1,13 @@
+export interface UrlRules {
+    /** "http" for REST (https required), "ws" for sockets (wss required). */
+    kind: "http" | "ws";
+    /** Allow http:// / ws:// to localhost (local development only). Default false. */
+    allowInsecureLocalhost?: boolean;
+}
+/**
+ * A base / socket / media URL a partner configured, checked before use: TLS only,
+ * no user:password@, and no credential in the query string. Tokens travel in
+ * headers or in the socket's first frame — never in a URL, which ends up in
+ * access logs, proxies and browser history.
+ */
+export declare function assertSafeUrl(raw: string, rules: UrlRules): URL;

package/dist/cjs/web.cjs

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.joinCallRoom = exports.memoryStore = void 0;
+exports.localStorageStore = localStorageStore;
+var session_js_1 = require("./session.cjs");
+Object.defineProperty(exports, "memoryStore", { enumerable: true, get: function () { return session_js_1.memoryStore; } });
+var livekit_js_1 = require("./livekit.cjs");
+Object.defineProperty(exports, "joinCallRoom", { enumerable: true, get: function () { return livekit_js_1.joinCallRoom; } });
+/**
+ * OPT-IN: keep the session in localStorage so a reload stays signed in.
+ *
+ * ⚠ Any script running on your origin (an XSS, a compromised third-party script)
+ * can read localStorage — including the 30-day refresh token. Use it only with a
+ * strict Content-Security-Policy and no third-party scripts on the page. The
+ * default (memoryStore) keeps nothing: a reload signs in again with a fresh
+ * assertion from your backend, which is the safer choice.
+ */
+function localStorageStore(o = {}) {
+    const key = o.key ?? "hainiva.agent.session";
+    const storage = o.storage ?? globalThis.localStorage;
+    if (!storage)
+        throw new Error("localStorage is not available here; use memoryStore()");
+    return {
+        get: () => storage.getItem(key),
+        set: (v) => storage.setItem(key, v),
+        remove: () => storage.removeItem(key),
+    };
+}

package/dist/cjs/web.d.cts

@@ -0,0 +1,23 @@
+/**
+ * @hainiva/agent-sdk/web — browser adapters: an opt-in localStorage session store
+ * and LiveKit call media (peer dependency `livekit-client`).
+ */
+import type { SessionStore } from "./session.cjs";
+export { memoryStore } from "./session.cjs";
+export { joinCallRoom, type JoinOptions, type MediaCall, type MediaJoin } from "./livekit.cjs";
+export interface LocalStorageStoreOptions {
+    /** Default "hainiva.agent.session". */
+    key?: string;
+    /** Default globalThis.localStorage. */
+    storage?: Pick<Storage, "getItem" | "setItem" | "removeItem">;
+}
+/**
+ * OPT-IN: keep the session in localStorage so a reload stays signed in.
+ *
+ * ⚠ Any script running on your origin (an XSS, a compromised third-party script)
+ * can read localStorage — including the 30-day refresh token. Use it only with a
+ * strict Content-Security-Policy and no third-party scripts on the page. The
+ * default (memoryStore) keeps nothing: a reload signs in again with a fresh
+ * assertion from your backend, which is the safer choice.
+ */
+export declare function localStorageStore(o?: LocalStorageStoreOptions): SessionStore;

package/dist/cjs/ws.cjs

@@ -0,0 +1,246 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReconnectingSocket = void 0;
+exports.backoffDelay = backoffDelay;
+const emitter_js_1 = require("./emitter.cjs");
+const errors_js_1 = require("./errors.cjs");
+const log_js_1 = require("./log.cjs");
+const redact_js_1 = require("./redact.cjs");
+const url_js_1 = require("./url.cjs");
+/** Exponential backoff with full jitter: between half and all of min(max, initial·2^attempt). */
+function backoffDelay(attempt, initial = 1000, max = 30000, rnd = Math.random) {
+    const cap = Math.min(max, initial * 2 ** Math.max(0, attempt));
+    return Math.round(cap / 2 + rnd() * (cap / 2));
+}
+const OPEN = 1;
+/**
+ * A WebSocket that stays connected: exponential backoff with jitter, auth in the
+ * first frame (the token is never in the URL), heartbeat with a dead-connection
+ * timeout, and a resume hook carrying the last sequence number seen. Frame shapes
+ * are the caller's: pass `authFrame`, `isReady`, `resume`, `seqOf` for the
+ * protocol (`/agent/v1/ws` bindings: TODO(S3b)).
+ */
+class ReconnectingSocket {
+    constructor(o) {
+        this.o = o;
+        this.ws = null;
+        this.st = "idle";
+        this.want = false;
+        this.authed = false;
+        this.attempt = 0;
+        this.seq = 0;
+        this.lastFrameAt = 0;
+        this.reconnectTimer = null;
+        this.authTimer = null;
+        this.pingTimer = null;
+        this.WS = o.WebSocket ?? globalThis.WebSocket;
+        this.redactor = o.redactor ?? new redact_js_1.Redactor();
+        this.log = (0, log_js_1.safeLogger)(o.log, this.redactor);
+        this.events = new emitter_js_1.TypedEmitter((e) => this.log("listener_error", e));
+        this.expiredCode = o.closeCodes?.tokenExpired ?? 4001;
+        this.revokedCode = o.closeCodes?.revoked ?? 4003;
+    }
+    get state() { return this.st; }
+    /** The highest sequence number received (what `resume` is called with). */
+    get lastSeq() { return this.seq; }
+    /** Restore a sequence number kept from an earlier run. */
+    setLastSeq(n) { if (Number.isFinite(n) && n >= 0)
+        this.seq = n; }
+    connect() {
+        this.want = true;
+        if (this.ws || this.reconnectTimer)
+            return;
+        if (!this.WS) {
+            this.fail(new errors_js_1.HainivaAgentError(0, "no_websocket"));
+            return;
+        }
+        void this.open();
+    }
+    disconnect() {
+        this.want = false;
+        this.clearTimers();
+        const ws = this.ws;
+        this.ws = null;
+        this.authed = false;
+        ws?.close(1000);
+        this.setState("closed");
+    }
+    /** Send a frame on an authenticated socket. False when not open (nothing is queued). */
+    send(frame) {
+        if (!this.ws || !this.authed || this.ws.readyState !== OPEN)
+            return false;
+        this.ws.send(this.encode(frame));
+        return true;
+    }
+    /** Hand a refreshed access token to the open socket (needs `tokenFrame`). */
+    updateToken(token) {
+        this.redactor.add(token);
+        return this.o.tokenFrame ? this.send(this.o.tokenFrame(token)) : false;
+    }
+    encode(f) { return (this.o.encode ?? JSON.stringify)(f); }
+    setState(s) {
+        if (this.st === s)
+            return;
+        this.st = s;
+        this.events.emit("state", s);
+    }
+    fail(e) {
+        this.log("socket_error", { code: e.code });
+        this.events.emit("error", e);
+    }
+    async open() {
+        this.setState(this.attempt ? "reconnecting" : "connecting");
+        let token;
+        let url;
+        try {
+            token = await this.o.getToken();
+            this.redactor.add(token);
+            url = typeof this.o.url === "function" ? await this.o.url() : this.o.url;
+        }
+        catch (e) {
+            this.fail(errors_js_1.HainivaAgentError.from(e, "socket_auth_failed", this.redactor));
+            return this.scheduleReconnect();
+        }
+        if (!this.want)
+            return;
+        try {
+            (0, url_js_1.assertSafeUrl)(url, { kind: "ws", ...(this.o.allowInsecureLocalhost ? { allowInsecureLocalhost: true } : {}) });
+            if (token && url.includes(token))
+                throw new errors_js_1.HainivaAgentError(0, "credentials_in_url");
+        }
+        catch (e) {
+            // A configuration mistake: retrying cannot fix it.
+            this.want = false;
+            this.setState("closed");
+            return this.fail(errors_js_1.HainivaAgentError.from(e, "invalid_url", this.redactor));
+        }
+        let ws;
+        try {
+            ws = new this.WS(url);
+        }
+        catch (e) {
+            this.fail(errors_js_1.HainivaAgentError.from(e, "socket_failed", this.redactor));
+            return this.scheduleReconnect();
+        }
+        this.ws = ws;
+        this.authed = false;
+        ws.onopen = () => {
+            if (this.ws !== ws)
+                return;
+            // First frame: the credential. Nothing else is sent before the server says ready.
+            ws.send(this.encode((this.o.authFrame ?? ((t) => ({ type: "auth", token: t })))(token)));
+            this.authTimer = setTimeout(() => {
+                if (this.ws === ws && !this.authed) {
+                    this.log("auth_timeout");
+                    ws.close(4000, "auth timeout");
+                }
+            }, this.o.authTimeoutMs ?? 10000);
+        };
+        ws.onmessage = (ev) => { if (this.ws === ws)
+            this.onFrame(ws, typeof ev.data === "string" ? ev.data : String(ev.data)); };
+        ws.onerror = () => { };
+        ws.onclose = (ev) => {
+            if (this.ws !== ws)
+                return;
+            this.ws = null;
+            this.authed = false;
+            this.clearTimers();
+            this.log("socket_closed", { code: ev.code });
+            if (!this.want)
+                return this.setState("closed");
+            if (ev.code === this.revokedCode) {
+                this.want = false;
+                this.setState("closed");
+                this.events.emit("revoked", { code: ev.code });
+                return;
+            }
+            if (this.o.closeCodes?.fatal?.includes(ev.code)) {
+                this.want = false;
+                this.setState("closed");
+                return this.fail(new errors_js_1.HainivaAgentError(0, `socket_closed_${ev.code}`, {}, this.redactor));
+            }
+            if (ev.code === this.expiredCode)
+                this.o.onTokenRejected?.();
+            this.scheduleReconnect();
+        };
+    }
+    onFrame(ws, raw) {
+        let f;
+        try {
+            f = (this.o.decode ?? JSON.parse)(raw);
+        }
+        catch {
+            return;
+        }
+        this.lastFrameAt = Date.now();
+        if (!this.authed) {
+            const ready = this.o.isReady ?? ((x) => x?.["type"] === "ready");
+            if (!ready(f))
+                return; // nothing is delivered before the server accepted the credential
+            this.authed = true;
+            this.attempt = 0;
+            if (this.authTimer) {
+                clearTimeout(this.authTimer);
+                this.authTimer = null;
+            }
+            this.startHeartbeat(ws);
+            this.setState("open");
+            const resume = this.seq > 0 ? this.o.resume?.(this.seq) : null;
+            if (resume)
+                ws.send(this.encode(resume));
+            this.events.emit("ready", f);
+            return;
+        }
+        const seqOf = this.o.seqOf ?? ((x) => { const s = x?.["seq"]; return typeof s === "number" ? s : undefined; });
+        const s = seqOf(f);
+        if (s !== undefined) {
+            if (s <= this.seq)
+                return; // a replayed frame already delivered
+            this.seq = s;
+        }
+        this.events.emit("frame", f);
+    }
+    startHeartbeat(ws) {
+        const hb = this.o.heartbeat;
+        if (hb === false)
+            return;
+        const every = hb?.intervalMs ?? 20000;
+        const dead = hb?.timeoutMs ?? 45000;
+        const frame = hb?.frame ?? (() => ({ type: "ping" }));
+        this.pingTimer = setInterval(() => {
+            if (this.ws !== ws)
+                return;
+            if (Date.now() - this.lastFrameAt > dead) {
+                this.log("heartbeat_timeout");
+                ws.close(4000, "heartbeat timeout");
+                return;
+            }
+            if (ws.readyState === OPEN)
+                ws.send(this.encode(frame()));
+        }, every);
+    }
+    scheduleReconnect() {
+        if (!this.want)
+            return;
+        const b = this.o.backoff;
+        const d = backoffDelay(this.attempt++, b?.initialMs, b?.maxMs, b?.random);
+        this.setState("reconnecting");
+        this.reconnectTimer = setTimeout(() => { this.reconnectTimer = null; if (this.want)
+            void this.open(); }, d);
+    }
+    clearTimers() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.authTimer) {
+            clearTimeout(this.authTimer);
+            this.authTimer = null;
+        }
+        if (this.pingTimer) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = null;
+        }
+    }
+}
+exports.ReconnectingSocket = ReconnectingSocket;

package/dist/cjs/ws.d.cts

@@ -0,0 +1,134 @@
+import { TypedEmitter } from "./emitter.cjs";
+import { HainivaAgentError } from "./errors.cjs";
+import { type Logger } from "./log.cjs";
+import { Redactor } from "./redact.cjs";
+export type ConnectionState = "idle" | "connecting" | "open" | "reconnecting" | "closed";
+/** Exponential backoff with full jitter: between half and all of min(max, initial·2^attempt). */
+export declare function backoffDelay(attempt: number, initial?: number, max?: number, rnd?: () => number): number;
+/** The part of the WebSocket API this client uses (browser, React Native, `ws` in Node). */
+export interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((ev: {
+        code: number;
+        reason?: string;
+    }) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+}
+export type WebSocketCtor = new (url: string) => WebSocketLike;
+type AnyFrame = Record<string, unknown>;
+export interface SocketOptions<In = AnyFrame, Out = AnyFrame> {
+    /** wss:// URL, or a function returning it. Never carries a credential (checked). */
+    url: string | (() => string | Promise<string>);
+    /** A valid access token (e.g. `session.accessToken()`); sent in the first frame. */
+    getToken: () => Promise<string>;
+    /** The server refused the token (close code `tokenExpired`): e.g. `session.invalidate()`. */
+    onTokenRejected?: () => void;
+    WebSocket?: WebSocketCtor;
+    /** First frame after open. Default `{ type: "auth", token }`. */
+    authFrame?: (token: string) => Out;
+    /** Whether a frame is the server's "authenticated" answer. Default `type === "ready"`. */
+    isReady?: (frame: In) => boolean;
+    /** Give up on an open socket that is not ready after this long. Default 10 s. */
+    authTimeoutMs?: number;
+    /** Keep-alive. `false` turns it off. */
+    heartbeat?: false | {
+        /** Send `frame()` this often. Default 20 s. */
+        intervalMs?: number;
+        /** Reconnect when nothing at all was received for this long. Default 45 s. */
+        timeoutMs?: number;
+        /** Default `{ type: "ping" }`. */
+        frame?: () => Out;
+    };
+    /** Resume hook: the frame to send after `ready` when frames were seen before. */
+    resume?: (lastSeq: number) => Out | null;
+    /** A frame's sequence number, if it has one. Default: numeric `seq`. */
+    seqOf?: (frame: In) => number | undefined;
+    /** Frame to hand the server a refreshed access token on an open socket. */
+    tokenFrame?: (token: string) => Out;
+    encode?: (frame: Out) => string;
+    decode?: (raw: string) => In;
+    backoff?: {
+        initialMs?: number;
+        maxMs?: number;
+        random?: () => number;
+    };
+    /**
+     * Server close codes. Defaults: tokenExpired 4001 (refresh and reconnect),
+     * revoked 4003 (stop). `fatal`: codes reconnecting cannot fix (stop, emit
+     * `error` with code `socket_closed_<code>`). Default none.
+     */
+    closeCodes?: {
+        tokenExpired?: number;
+        revoked?: number;
+        fatal?: number[];
+    };
+    /** Allow ws://localhost in development. Default false. */
+    allowInsecureLocalhost?: boolean;
+    log?: Logger;
+    redactor?: Redactor;
+}
+export interface SocketEvents<In> {
+    state: ConnectionState;
+    /** Authenticated (after every (re)connect). */
+    ready: In;
+    /** Every frame after `ready`, except ones already seen (seq ≤ lastSeq). */
+    frame: In;
+    /** The server revoked the session: the socket stays closed until connect() is called again. */
+    revoked: {
+        code: number;
+    };
+    error: HainivaAgentError;
+}
+/**
+ * A WebSocket that stays connected: exponential backoff with jitter, auth in the
+ * first frame (the token is never in the URL), heartbeat with a dead-connection
+ * timeout, and a resume hook carrying the last sequence number seen. Frame shapes
+ * are the caller's: pass `authFrame`, `isReady`, `resume`, `seqOf` for the
+ * protocol (`/agent/v1/ws` bindings: TODO(S3b)).
+ */
+export declare class ReconnectingSocket<In = AnyFrame, Out = AnyFrame> {
+    private readonly o;
+    readonly events: TypedEmitter<SocketEvents<In>>;
+    private ws;
+    private st;
+    private want;
+    private authed;
+    private attempt;
+    private seq;
+    private lastFrameAt;
+    private reconnectTimer;
+    private authTimer;
+    private pingTimer;
+    private readonly WS;
+    private readonly redactor;
+    private readonly log;
+    private readonly expiredCode;
+    private readonly revokedCode;
+    constructor(o: SocketOptions<In, Out>);
+    get state(): ConnectionState;
+    /** The highest sequence number received (what `resume` is called with). */
+    get lastSeq(): number;
+    /** Restore a sequence number kept from an earlier run. */
+    setLastSeq(n: number): void;
+    connect(): void;
+    disconnect(): void;
+    /** Send a frame on an authenticated socket. False when not open (nothing is queued). */
+    send(frame: Out): boolean;
+    /** Hand a refreshed access token to the open socket (needs `tokenFrame`). */
+    updateToken(token: string): boolean;
+    private encode;
+    private setState;
+    private fail;
+    private open;
+    private onFrame;
+    private startHeartbeat;
+    private scheduleReconnect;
+    private clearTimers;
+}
+export {};