@pouchy_ai/companion-sdk 0.33.0 → 0.35.0

package/dist/client.js

@@ -42,6 +42,35 @@ export function pouchyBrandIconUrl(baseUrl, size = 512) {
  *  (so call.ts shares it cycle-free); re-exported here so the public import
  *  path is unchanged. */
 export { CompanionError } from './errors.js';
+// Default outbox persistence: localStorage when the environment has one (and
+// allows it — privacy mode / quota errors fall through), else a module-level
+// Map so the queue at least survives for the page's lifetime.
+const memoryOutbox = new Map();
+const defaultOutboxStore = {
+    load(key) {
+        try {
+            if (typeof window !== 'undefined' && window.localStorage) {
+                return window.localStorage.getItem(key);
+            }
+        }
+        catch {
+            /* storage denied — fall through to the in-memory copy */
+        }
+        return memoryOutbox.get(key) ?? null;
+    },
+    save(key, value) {
+        try {
+            if (typeof window !== 'undefined' && window.localStorage) {
+                window.localStorage.setItem(key, value);
+                return;
+            }
+        }
+        catch {
+            /* quota / privacy mode — keep the in-memory copy below */
+        }
+        memoryOutbox.set(key, value);
+    }
+};
 const SEEN_CAP = 512;
 export class CompanionClient {
     opts;
@@ -68,6 +97,17 @@ export class CompanionClient {
     // Instrumentation sink (0.32.0) — null when `debug` is unset, so the hot
     // paths pay one falsy check.
     debugSink;
+    // Offline send queue (0.34.0) — null until first use, then loaded lazily
+    // from the store so a reloaded tab resumes the queue its predecessor
+    // persisted.
+    outbox = null;
+    outboxHandlers = new Set();
+    // In-flight flush, shared so concurrent triggers run ONE flush at a time.
+    outboxFlush = null;
+    /** Epoch-ms before which flush attempts are skipped — set from a 429's
+     *  Retry-After during replay so the auto-flush on every reconnect doesn't
+     *  re-hammer a server that just told us to back off (0.35.0). */
+    outboxBlockedUntil = 0;
     constructor(opts) {
         if (!opts.baseUrl)
             throw new CompanionError('CompanionClient: baseUrl is required', 0, 'missing_option');
@@ -129,6 +169,10 @@ export class CompanionClient {
                 console.error('[companion-sdk] stream-state handler threw', e);
             }
         }
+        // The stream coming back up is the strongest "server reachable again"
+        // signal there is — drain any sends queued while offline (0.34.0).
+        if (next === 'connected' && this.opts.queueOffline)
+            void this.flushOutbox().catch(() => { });
     }
     /** Swap the bearer token used by every subsequent request and stream
      *  reconnect. Session tokens expire (default 1h) — call this when your
@@ -175,6 +219,38 @@ export class CompanionClient {
         const minor = Number(m[2]);
         return major > 1 || (major === 1 && minor >= 1);
     }
+    /** doFetch raced against the `requestTimeoutMs` HEADERS deadline (0.35.0).
+     *  The deadline only bounds time-to-response-headers: it does NOT swap the
+     *  request's AbortSignal, so a streaming response body stays tied to the
+     *  caller's own signal, and the timer is cleared the moment the race
+     *  settles. On timeout the helper rejects `request_timeout` (status 0) —
+     *  code-bearing, so the offline queue's network-failure predicate correctly
+     *  ignores it (the server may have received the request). The abandoned
+     *  fetch keeps its rejection silenced so a late network error can't surface
+     *  as an unhandled rejection. */
+    async doFetchBounded(url, init) {
+        const budget = this.opts.requestTimeoutMs ?? 30_000;
+        if (!budget)
+            return this.doFetch(url, init);
+        const req = this.doFetch(url, init);
+        let timer;
+        try {
+            return await Promise.race([
+                req,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new CompanionError(`request timed out after ${budget}ms waiting for response headers`, 0, 'request_timeout')), budget);
+                })
+            ]);
+        }
+        catch (e) {
+            req.catch(() => { });
+            throw e;
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
     async fetchAuthed(url, init) {
         const method = init.method ?? 'GET';
         const path = url.startsWith(this.opts.baseUrl) ? url.slice(this.opts.baseUrl.length) : url;
@@ -182,7 +258,7 @@ export class CompanionClient {
         this.dbg({ kind: 'request', at: startedAt, method, path });
         let res;
         try {
-            res = await this.doFetch(url, init);
+            res = await this.doFetchBounded(url, init);
         }
         catch (e) {
             // A caller-supplied AbortSignal makes fetch throw a native AbortError —
@@ -217,7 +293,7 @@ export class CompanionClient {
         const retryAt = Date.now();
         this.dbg({ kind: 'request', at: retryAt, method, path });
         try {
-            const retryRes = await this.doFetch(url, init);
+            const retryRes = await this.doFetchBounded(url, init);
             this.dbg({
                 kind: 'response',
                 at: Date.now(),
@@ -322,6 +398,10 @@ export class CompanionClient {
         }, opts?.signal);
         this._session = json.session;
         this.cursor = json.resumeCursor ?? 0;
+        // A successful handshake proves reachability — replay any sends queued
+        // while offline (0.34.0; no-op when the queue is empty).
+        if (this.opts.queueOffline)
+            void this.flushOutbox().catch(() => { });
         return {
             ...json,
             representative: json.representative ?? false,
@@ -356,6 +436,26 @@ export class CompanionClient {
         // message that happens by (world-state reactions, confirm outcomes).
         const turnId = `turn_${this.randomId()}`;
         const body = { text, turnId, ...(opts?.images?.length ? { images: opts.images } : {}) };
+        if (!this.opts.queueOffline)
+            return this.dispatchText(id, body, opts, turnId);
+        // Offline queue: two triggers only — the browser already knows it's
+        // offline, or fetch itself rejected without an HTTP response. An HTTP
+        // error (4xx/5xx incl. 429) means the server SAW the turn: those keep
+        // the normal throw semantics and are never queued.
+        if (typeof navigator !== 'undefined' && navigator.onLine === false) {
+            return this.queueSend(turnId, text, opts);
+        }
+        try {
+            return await this.dispatchText(id, body, opts, turnId);
+        }
+        catch (e) {
+            if (this.isNetworkSendFailure(e))
+                return this.queueSend(turnId, text, opts);
+            throw e;
+        }
+    }
+    /** The pre-queue dispatch of sendText: awaitReply / streaming / buffered. */
+    async dispatchText(id, body, opts, turnId) {
         if (opts?.awaitReply)
             return this.sendTextAwaitingReply(id, body, opts, turnId);
         const wantStream = opts?.stream ?? this.deltaHandlers.size > 0;
@@ -365,6 +465,32 @@ export class CompanionClient {
         }
         return this.sendTextStreaming(id, body, opts?.signal);
     }
+    /** True only for a send that never reached the server: fetch rejected at
+     *  the network level, which asCompanionError wraps as status 0 with NO
+     *  code. Every code-carrying status-0 error is deliberate — `aborted` is
+     *  the caller cancelling, `reply_timeout`/`needs_event_stream` mean the
+     *  POST was accepted — and any nonzero status is a response the server
+     *  produced. None of those may queue. */
+    isNetworkSendFailure(e) {
+        return e instanceof CompanionError && e.status === 0 && e.code === undefined;
+    }
+    /** Enqueue an offline send. Plain sends resolve `{ seq: null, queued: true,
+     *  turnId }`; awaitReply can't await a reply that won't arrive this
+     *  session, so it rejects with `queued_offline` — the item is queued
+     *  either way. */
+    queueSend(turnId, text, opts) {
+        this.loadOutbox().push({
+            turnId,
+            text,
+            ...(opts?.images?.length ? { images: opts.images } : {}),
+            at: Date.now()
+        });
+        this.commitOutbox();
+        if (opts?.awaitReply) {
+            throw new CompanionError('offline — the text was queued and will send when the connection returns; no reply to await', 0, 'queued_offline');
+        }
+        return { seq: null, queued: true, turnId };
+    }
     /** The awaitReply leg of sendText. Prefers the in-request answer (the
      *  streaming `done` frame's envelope); falls back to the next
      *  `companion.message` off the event stream, bounded by a timeout. The
@@ -372,6 +498,13 @@ export class CompanionClient {
      *  can't slip through the gap. */
     async sendTextAwaitingReply(sessionId, body, opts, turnId) {
         const timeoutMs = opts?.replyTimeoutMs ?? 60_000;
+        // Already-aborted fast-fail comes FIRST (0.35.0): it used to sit after the
+        // companion.message subscription below, whose cleanup lives in the finally
+        // of the try we never entered — every call with a spent signal leaked one
+        // permanent handler (a host reusing one AbortController across turns
+        // accumulated them without bound).
+        if (opts?.signal?.aborted)
+            throw new CompanionError('request aborted', 0, 'aborted');
         let resolveFallback;
         const fallback = new Promise((res) => (resolveFallback = res));
         // Correlate: resolve only on THIS turn's reply (`replyTo === turnId`).
@@ -392,11 +525,9 @@ export class CompanionClient {
         const ac = new AbortController();
         // Link the caller's signal: aborting it tears down the in-flight stream
         // (via ac) AND rejects the whole operation with `aborted`, exactly like
-        // the deadline does. If it is already aborted, fail fast.
+        // the deadline does.
         let onCallerAbort;
         if (opts?.signal) {
-            if (opts.signal.aborted)
-                throw new CompanionError('request aborted', 0, 'aborted');
             onCallerAbort = () => ac.abort();
             opts.signal.addEventListener('abort', onCallerAbort, { once: true });
         }
@@ -567,9 +698,131 @@ export class CompanionClient {
             catch {
                 /* stream already finished */
             }
-            throw e;
+            // Normalize (0.35.0): a mid-stream network drop rejects reader.read()
+            // with a NATIVE TypeError. Rethrowing it raw broke the "every helper
+            // rejects with CompanionError" contract AND slipped past the offline
+            // queue's isNetworkSendFailure (which requires a code-less status-0
+            // CompanionError) — the exact loss queueOffline exists to prevent.
+            // Queueing the replay is safe: it reuses the ORIGINAL turnId and the
+            // server dedupes completed turns, so a turn that did run isn't re-run.
+            throw this.asCompanionError(e);
         }
     }
+    /** The live offline queue, loaded from the store on first use so a reloaded
+     *  tab resumes what its predecessor persisted. Unreadable or foreign store
+     *  content is discarded — a corrupt store must never break sending. */
+    loadOutbox() {
+        if (this.outbox)
+            return this.outbox;
+        let items = [];
+        try {
+            const raw = (this.opts.outboxStore ?? defaultOutboxStore).load(this.outboxKey());
+            const parsed = raw ? JSON.parse(raw) : null;
+            if (Array.isArray(parsed)) {
+                items = parsed.filter((q) => !!q &&
+                    typeof q.turnId === 'string' &&
+                    typeof q.text === 'string');
+            }
+        }
+        catch {
+            /* unreadable store — start empty */
+        }
+        this.outbox = items;
+        return items;
+    }
+    outboxKey() {
+        return `pouchy-outbox:${this.opts.surface ?? 'default'}`;
+    }
+    /** Persist + notify after EVERY queue mutation (enqueue / flushed / drop),
+     *  so the stored copy never lags what a reload would need. Handler
+     *  isolation matches emit(): a throwing consumer must not skip the rest. */
+    commitOutbox() {
+        const items = this.loadOutbox();
+        try {
+            (this.opts.outboxStore ?? defaultOutboxStore).save(this.outboxKey(), JSON.stringify(items));
+        }
+        catch {
+            /* store save failed — the in-memory queue still flushes this page */
+        }
+        const copy = Object.freeze([...items]);
+        for (const h of this.outboxHandlers) {
+            try {
+                h(copy);
+            }
+            catch (e) {
+                console.error('[companion-sdk] outbox handler threw', e);
+            }
+        }
+    }
+    /** The sends queued while offline (oldest first), as a defensive copy —
+     *  see the `queueOffline` option. */
+    pendingOutbox() {
+        return [...this.loadOutbox()];
+    }
+    /** Subscribe to offline-queue changes (enqueue / flushed / dropped) — drive
+     *  a "N pending" badge from `items.length`. Returns an unsubscribe fn. */
+    onOutboxChange(handler) {
+        this.outboxHandlers.add(handler);
+        return () => this.outboxHandlers.delete(handler);
+    }
+    /** Replay the offline queue: FIFO, sequential, each item a normal buffered
+     *  input POST reusing its ORIGINAL `turnId` (the server dedupes completed
+     *  turnIds — see `queueOffline` — so a retry can never double-run a turn).
+     *  Runs automatically after connect() and on every stream reconnect; call
+     *  it yourself for a manual retry affordance. One flush at a time —
+     *  concurrent calls share the in-flight run. Per item: success (or a
+     *  server-side duplicate) → removed; network failure / 5xx / 429 → stop,
+     *  keep this item and the rest for the next flush; any other 4xx → the
+     *  item itself is invalid (the server deliberately rejected it) — drop it,
+     *  console.warn, and keep flushing. */
+    async flushOutbox() {
+        this.requireSession();
+        this.outboxFlush ??= this.runOutboxFlush().finally(() => {
+            this.outboxFlush = null;
+        });
+        return this.outboxFlush;
+    }
+    async runOutboxFlush() {
+        const id = this.requireSession();
+        const items = this.loadOutbox();
+        // Respect the last replay 429's Retry-After (0.35.0): the flush re-arms
+        // on EVERY stream reconnect, so without this gate a rate-limited server
+        // got re-hammered on each reconnect despite naming its own window.
+        if (Date.now() < this.outboxBlockedUntil)
+            return { sent: 0, remaining: items.length };
+        let sent = 0;
+        while (items.length) {
+            const item = items[0];
+            try {
+                await this.postJson(`/api/companion/session/${id}/input`, {
+                    text: item.text,
+                    turnId: item.turnId,
+                    ...(item.images?.length ? { images: item.images } : {})
+                });
+            }
+            catch (e) {
+                const status = e instanceof CompanionError ? e.status : 0;
+                if (status >= 400 && status < 500 && status !== 429) {
+                    // The server saw it and said no — retrying can't fix the item.
+                    console.warn('[companion-sdk] dropping queued send the server rejected', status, e);
+                    items.shift();
+                    this.commitOutbox();
+                    continue;
+                }
+                // A throttle names its own retry window — honor it across flushes.
+                if (status === 429 && e instanceof CompanionError && typeof e.retryAfter === 'number') {
+                    this.outboxBlockedUntil = Date.now() + e.retryAfter * 1000;
+                }
+                // Unreachable again (or throttled / a server-side failure): keep
+                // this item and everything behind it for the next flush.
+                break;
+            }
+            items.shift();
+            sent += 1;
+            this.commitOutbox();
+        }
+        return { sent, remaining: items.length };
+    }
     /** Subscribe to token-streaming deltas of the reply (P1-2). Registering a
      *  subscriber makes sendText stream automatically. Returns an unsubscribe
      *  function. Render chunks as they arrive; on `meta.reset` clear the partial;
@@ -867,7 +1120,10 @@ export class CompanionClient {
      *  arrive as `control.error`. Since 0.30.0 `code` is typed as
      *  `ControlErrorCodeValue` (the CONTROL_ERROR_CODES vocabulary + the
      *  SDK-synthesized stream codes, open for newer servers) so a `switch` on it
-     *  autocompletes. Returns an unsubscribe fn. */
+     *  autocompletes. A malformed frame with no string `code` is delivered with
+     *  the literal fallback `'error'` (not part of the exported vocabulary) —
+     *  give your `switch` a `default:` arm rather than enumerating every code.
+     *  Returns an unsubscribe fn. */
     onError(handler) {
         return this.on('control.error', (env) => {
             const p = env.payload;
@@ -1216,13 +1472,19 @@ export class CompanionClient {
         let backoff = 500;
         while (this.streaming && gen === this.streamGen) {
             let errored = false;
-            const connectedAt = Date.now();
+            // Stamped in onopen (0.35.0) — measuring from before the constructor
+            // counted DNS/TCP/handshake time as "connection lifetime", so a gateway
+            // that took ~2s to accept and then instantly closed read as long-lived
+            // and RESET the backoff (a near-hot reconnect loop). 0 = never opened,
+            // which always backs off.
+            let openedAt = 0;
             try {
                 await new Promise((resolve, reject) => {
                     const ws = new WS(deriveWsStreamUrl(this.opts.baseUrl, id, this.opts.token, this.cursor));
                     let poll;
                     let settled = false;
                     ws.onopen = () => {
+                        openedAt = Date.now();
                         if (this.streaming && gen === this.streamGen)
                             this.setStreamState('connected');
                     };
@@ -1284,7 +1546,7 @@ export class CompanionClient {
             // loop. A connection that lived a while resets the backoff.
             if (this.streaming && gen === this.streamGen)
                 this.setStreamState('reconnecting');
-            if (Date.now() - connectedAt < 2000) {
+            if (openedAt === 0 || Date.now() - openedAt < 2000) {
                 await this.backoffSleep(backoff);
                 backoff = Math.min(backoff * 2, 8000);
             }
@@ -1453,15 +1715,37 @@ export class CompanionClient {
         const reader = body.getReader();
         const decoder = new TextDecoder();
         let buf = '';
-        while (this.streaming && gen === this.streamGen) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            buf += decoder.decode(value, { stream: true });
-            const { events, rest } = parseSse(buf);
-            buf = rest;
-            for (const ev of events)
-                this.handleFrame(ev.event, ev.data);
+        // Liveness watchdog (0.35.0). The server writes a `: ping` comment every
+        // ~1.5s and closes each stream window at 45s — a healthy connection is
+        // NEVER byte-silent for long. On a silent half-open TCP drop (NAT/LB
+        // idle-kill, laptop sleep) no FIN ever arrives: reader.read() blocks for
+        // minutes while streamState still reads 'connected' and every reply is
+        // silently lost. 10× the ping interval without a single byte can only be
+        // a dead connection — cancel the reader so read() returns and the loop
+        // reconnects through its normal backoff + cursor resume (replays dedupe
+        // by envelope id). Only the SSE plane gets this: the WS plane has no
+        // heartbeat contract, so an idle-but-healthy socket can't be told apart.
+        const SSE_STALL_MS = 15_000;
+        let lastByteAt = Date.now();
+        const watchdog = setInterval(() => {
+            if (Date.now() - lastByteAt > SSE_STALL_MS)
+                void reader.cancel().catch(() => { });
+        }, 5_000);
+        try {
+            while (this.streaming && gen === this.streamGen) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                lastByteAt = Date.now();
+                buf += decoder.decode(value, { stream: true });
+                const { events, rest } = parseSse(buf);
+                buf = rest;
+                for (const ev of events)
+                    this.handleFrame(ev.event, ev.data);
+            }
+        }
+        finally {
+            clearInterval(watchdog);
         }
     }
     sleep(ms) {