@linxin666/dsh-remote-web-ui 0.1.6 → 0.1.8

package/lib/types/mobile/mux.d.ts

@@ -7,13 +7,40 @@
  * opens — no subscription handshake is needed. Frames arrive as
  * server-request envelopes whose payload is the mux frame; unknown frame
  * types are dropped so a newer host never breaks this client.
- * EventSource reconnects automatically.
+ *
+ * EventSource reconnects automatically — but only over a tunnel that
+ * actually forwards frames. Public quick tunnels (Cloudflare quick tunnel /
+ * Tailscale Serve) do not transparently pass Server-Sent Events: ordinary
+ * HTTP works, yet the SSE connection stays open or reconnects with zero
+ * bytes, so no live frame ever arrives. That is a transport-layer limit of
+ * the tunnel, not something the host can fix. This client therefore
+ * degrades gracefully: once the SSE channel has silently stalled (no frame
+ * for {@link MuxClientOptions.stallThresholdMs}, or the EventSource reports
+ * an error), it starts polling the open session's history over plain HTTP
+ * (the `/m/api/session.history` RPC — unaffected by the SSE limitation),
+ * and re-emits freshly appended events as `session/event` frames through
+ * the same subscriber contract, so listeners (and the message fold) behave
+ * exactly as if the frames had arrived over SSE. When the SSE channel
+ * delivers again, fallback polling stops and the live stream takes over.
  */
 import type { MuxFrame } from '@deepseek-ai/dsh-host-apiproxy/api/events';
+import { type HistoryPage } from './api.ts';
 /** Injectable seams for tests. */
 export interface MuxClientOptions {
     /** EventSource factory (defaults to the browser EventSource). */
     sourceFactory?: (url: string) => EventSourceLike;
+    /**
+     * Fetch one history page (tail) for a session — the polling fallback's
+     * data source. Defaults to the mobile `session.history` RPC, which rides
+     * the ordinary HTTP channel (unaffected by SSE-impairing tunnels).
+     */
+    pollLatest?: (sessionId: string) => Promise<HistoryPage>;
+    /** Poll cadence while SSE is stalled (default 3000 ms). */
+    pollIntervalMs?: number;
+    /** How long SSE must go without a frame before fallback kicks in (default 12000 ms). */
+    stallThresholdMs?: number;
+    /** Clock seam for tests (defaults to Date.now). */
+    now?: () => number;
 }
 /** The EventSource subset this client uses (browser EventSource fits). */
 export interface EventSourceLike {
@@ -26,14 +53,34 @@ export interface EventSourceLike {
 /**
  * Keep one SSE subscription open, fanning validated frames out to
  * subscribers. EventSource owns reconnection (with its own backoff); this
- * class only manages the subscription lifecycle.
+ * class only manages the subscription lifecycle, plus a polling fallback
+ * that keeps the open session live when the SSE channel cannot deliver.
  */
 export declare class MuxClient {
     private readonly sourceFactory;
+    private readonly pollLatest;
+    private readonly pollIntervalMs;
+    private readonly stallThresholdMs;
+    private readonly now;
     private readonly listeners;
     private source;
     private stopped;
     private readonly url;
+    /** The session to keep live via fallback polling (undefined = none). */
+    private observeSessionId;
+    /** Last epoch ms the SSE channel produced a frame (or the stream opened). */
+    private lastDataAt;
+    /**
+     * Whether the SSE channel has ever delivered a frame in this stream (a
+     * delivered frame proves the tunnel forwards SSE; silence alone then means
+     * the agent idle, not a dead channel — only an onerror re-arms fallback).
+     */
+    private sseAlive;
+    /** Per-session highest event seq already emitted, for poll dedup. */
+    private readonly pollWatermark;
+    private stallTimer;
+    private pollTimer;
+    private polling;
     /**
      * @param url - the mobile events endpoint (browser-relative).
      * @param options - seams.
@@ -45,8 +92,25 @@ export declare class MuxClient {
     stop(): void;
     /** Subscribe to validated frames; returns an unsubscribe function. */
     onFrame(listener: (frame: MuxFrame) => void): () => void;
+    /**
+     * Point the fallback at one open session (or `undefined` to stop it).
+     * While the SSE channel is stalled this client polls that session's
+     * history and re-emits new events as `session/event` frames.
+     */
+    observe(sessionId: string | undefined): void;
     private connect;
+    private startStallChecker;
+    private stopStallChecker;
+    private startPolling;
+    private stopPolling;
+    /**
+     * Fetch the latest history page for the observed session and re-emit any
+     * event above the per-session watermark as a `session/event` frame.
+     * Idempotent by seq: listeners (and the fold) never see a duplicate.
+     */
+    private pollTick;
     private handleMessage;
+    private emit;
     private closeSource;
 }
 //# sourceMappingURL=mux.d.ts.map

package/lib/types/mobile/mux.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mux.d.ts","sourceRoot":"","sources":["../../../src/mobile/mux.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2CAA2C,CAAA;AAIzE,kCAAkC;AAClC,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,eAAe,CAAA;CACjD;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAA;IACrD,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAA;IAC1C,KAAK,IAAI,IAAI,CAAA;CACd;AASD;;;;GAIG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkC;IAChE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuC;IACjE,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAE5B;;;OAGG;gBACS,GAAG,SAAsB,EAAE,OAAO,GAAE,gBAAqB;IAKrE,+EAA+E;IAC/E,KAAK,IAAI,IAAI;IAMb,sBAAsB;IACtB,IAAI,IAAI,IAAI;IAKZ,sEAAsE;IACtE,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,MAAM,IAAI;IAKxD,OAAO,CAAC,OAAO;IAaf,OAAO,CAAC,aAAa;IAuBrB,OAAO,CAAC,WAAW;CAapB"}
+{"version":3,"file":"mux.d.ts","sourceRoot":"","sources":["../../../src/mobile/mux.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2CAA2C,CAAA;AAGzE,OAAO,EAA2B,KAAK,WAAW,EAAE,MAAM,UAAU,CAAA;AAEpE,kCAAkC;AAClC,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,eAAe,CAAA;IAChD;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAA;IACxD,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,wFAAwF;IACxF,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAA;IACrD,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAA;IAC1C,KAAK,IAAI,IAAI,CAAA;CACd;AAiBD;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkC;IAChE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6C;IACxE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuC;IACjE,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAE5B,wEAAwE;IACxE,OAAO,CAAC,gBAAgB,CAAoB;IAC5C,6EAA6E;IAC7E,OAAO,CAAC,UAAU,CAAI;IACtB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAQ;IACxB,qEAAqE;IACrE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;IAC1D,OAAO,CAAC,UAAU,CAA4C;IAC9D,OAAO,CAAC,SAAS,CAA4C;IAC7D,OAAO,CAAC,OAAO,CAAQ;IAEvB;;;OAGG;gBACS,GAAG,SAAsB,EAAE,OAAO,GAAE,gBAAqB;IASrE,+EAA+E;IAC/E,KAAK,IAAI,IAAI;IAOb,sBAAsB;IACtB,IAAI,IAAI,IAAI;IAQZ,sEAAsE;IACtE,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,MAAM,IAAI;IAKxD;;;;OAIG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAY5C,OAAO,CAAC,OAAO;IAqBf,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,WAAW;IAQnB;;;;OAIG;YACW,QAAQ;IAsBtB,OAAO,CAAC,aAAa;IAuBrB,OAAO,CAAC,IAAI;IAUZ,OAAO,CAAC,WAAW;CAapB"}

package/lib/types/mobile/mux.js

@@ -7,27 +7,66 @@
  * opens — no subscription handshake is needed. Frames arrive as
  * server-request envelopes whose payload is the mux frame; unknown frame
  * types are dropped so a newer host never breaks this client.
- * EventSource reconnects automatically.
+ *
+ * EventSource reconnects automatically — but only over a tunnel that
+ * actually forwards frames. Public quick tunnels (Cloudflare quick tunnel /
+ * Tailscale Serve) do not transparently pass Server-Sent Events: ordinary
+ * HTTP works, yet the SSE connection stays open or reconnects with zero
+ * bytes, so no live frame ever arrives. That is a transport-layer limit of
+ * the tunnel, not something the host can fix. This client therefore
+ * degrades gracefully: once the SSE channel has silently stalled (no frame
+ * for {@link MuxClientOptions.stallThresholdMs}, or the EventSource reports
+ * an error), it starts polling the open session's history over plain HTTP
+ * (the `/m/api/session.history` RPC — unaffected by the SSE limitation),
+ * and re-emits freshly appended events as `session/event` frames through
+ * the same subscriber contract, so listeners (and the message fold) behave
+ * exactly as if the frames had arrived over SSE. When the SSE channel
+ * delivers again, fallback polling stops and the live stream takes over.
  */
 import { muxFrameSchema } from '@deepseek-ai/dsh-host-apiproxy/api/events.schema';
 import { serverRequestSchema } from '@deepseek-ai/dsh-host-apiproxy/api/rpc.schema';
+import { history as fetchHistory } from "./api.js";
 /** Browser default source factory. */
 function browserSource(url) {
     // The DOM EventSource is structurally compatible; the `this`-typed handler
     // signatures differ, so the narrow face takes it through an adapter cast.
     return new EventSource(url);
 }
+const DEFAULT_POLL_INTERVAL_MS = 3000;
+const DEFAULT_STALL_THRESHOLD_MS = 12000;
+/** Poll window: enough recent events to cover a few seconds of agent output. */
+const DEFAULT_POLL_PAGE_SIZE = 50;
 /**
  * Keep one SSE subscription open, fanning validated frames out to
  * subscribers. EventSource owns reconnection (with its own backoff); this
- * class only manages the subscription lifecycle.
+ * class only manages the subscription lifecycle, plus a polling fallback
+ * that keeps the open session live when the SSE channel cannot deliver.
  */
 export class MuxClient {
     sourceFactory;
+    pollLatest;
+    pollIntervalMs;
+    stallThresholdMs;
+    now;
     listeners = new Set();
     source;
     stopped = false;
     url;
+    /** The session to keep live via fallback polling (undefined = none). */
+    observeSessionId;
+    /** Last epoch ms the SSE channel produced a frame (or the stream opened). */
+    lastDataAt = 0;
+    /**
+     * Whether the SSE channel has ever delivered a frame in this stream (a
+     * delivered frame proves the tunnel forwards SSE; silence alone then means
+     * the agent idle, not a dead channel — only an onerror re-arms fallback).
+     */
+    sseAlive = false;
+    /** Per-session highest event seq already emitted, for poll dedup. */
+    pollWatermark = new Map();
+    stallTimer;
+    pollTimer;
+    polling = false;
     /**
      * @param url - the mobile events endpoint (browser-relative).
      * @param options - seams.
@@ -35,25 +74,51 @@ export class MuxClient {
     constructor(url = '/m/api/events.mux', options = {}) {
         this.url = url;
         this.sourceFactory = options.sourceFactory ?? browserSource;
+        this.pollLatest = options.pollLatest ?? ((sessionId) => fetchHistory(sessionId, undefined, DEFAULT_POLL_PAGE_SIZE));
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.stallThresholdMs = options.stallThresholdMs ?? DEFAULT_STALL_THRESHOLD_MS;
+        this.now = options.now ?? (() => Date.now());
     }
     /** Open the stream (idempotent; EventSource reconnects until {@link stop}). */
     start() {
         this.stopped = false;
-        if (this.source !== undefined)
-            return;
-        this.connect();
+        this.lastDataAt = this.now();
+        if (this.source === undefined)
+            this.connect();
+        this.startStallChecker();
     }
     /** Close for good. */
     stop() {
         this.stopped = true;
+        this.stopStallChecker();
+        this.stopPolling();
         this.closeSource();
+        this.observeSessionId = undefined;
     }
     /** Subscribe to validated frames; returns an unsubscribe function. */
     onFrame(listener) {
         this.listeners.add(listener);
         return () => { this.listeners.delete(listener); };
     }
+    /**
+     * Point the fallback at one open session (or `undefined` to stop it).
+     * While the SSE channel is stalled this client polls that session's
+     * history and re-emits new events as `session/event` frames.
+     */
+    observe(sessionId) {
+        this.observeSessionId = sessionId;
+        if (sessionId === undefined) {
+            this.stopPolling();
+            return;
+        }
+        // If SSE is already stalled for this session, start patching right away.
+        if (!this.polling && !this.stopped && !this.sseAlive && (this.now() - this.lastDataAt) > this.stallThresholdMs) {
+            this.startPolling();
+        }
+    }
     connect() {
+        // A fresh stream starts unknown; only a delivered frame proves it works.
+        this.sseAlive = false;
         const source = this.sourceFactory(this.url);
         this.source = source;
         source.onmessage = (event) => {
@@ -61,11 +126,83 @@ export class MuxClient {
         };
         source.onerror = () => {
             // EventSource reconnects by itself; when we are closing, detach first
-            // so the native reconnect cannot outlive stop().
-            if (this.stopped && this.source === source)
+            // so the native reconnect cannot outlive stop(). Otherwise an error is
+            // a strong signal the transport is not delivering — degrade to polling.
+            if (this.stopped && this.source === source) {
                 this.closeSource();
+                return;
+            }
+            this.sseAlive = false;
+            if (this.observeSessionId !== undefined)
+                this.startPolling();
         };
     }
+    startStallChecker() {
+        this.stopStallChecker();
+        this.stallTimer = setInterval(() => {
+            if (this.stopped)
+                return;
+            if (this.observeSessionId === undefined)
+                return;
+            if (this.polling)
+                return;
+            // A live SSE channel only goes silent while the agent idles; never
+            // poll against it. Fallback arms again only via onerror or a stream
+            // that has never delivered.
+            if (this.sseAlive)
+                return;
+            if ((this.now() - this.lastDataAt) > this.stallThresholdMs)
+                this.startPolling();
+        }, 1000);
+    }
+    stopStallChecker() {
+        if (this.stallTimer !== undefined) {
+            clearInterval(this.stallTimer);
+            this.stallTimer = undefined;
+        }
+    }
+    startPolling() {
+        if (this.polling || this.stopped)
+            return;
+        this.polling = true;
+        void this.pollTick();
+        this.pollTimer = setInterval(() => { void this.pollTick(); }, this.pollIntervalMs);
+    }
+    stopPolling() {
+        this.polling = false;
+        if (this.pollTimer !== undefined) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = undefined;
+        }
+    }
+    /**
+     * Fetch the latest history page for the observed session and re-emit any
+     * event above the per-session watermark as a `session/event` frame.
+     * Idempotent by seq: listeners (and the fold) never see a duplicate.
+     */
+    async pollTick() {
+        const sessionId = this.observeSessionId;
+        if (sessionId === undefined) {
+            this.stopPolling();
+            return;
+        }
+        try {
+            const page = await this.pollLatest(sessionId);
+            let maxSeq = this.pollWatermark.get(sessionId) ?? -1;
+            for (const entry of page.events) {
+                const event = entry.event;
+                const seq = typeof event?.seq === 'number' ? event.seq : -1;
+                if (seq <= maxSeq)
+                    continue;
+                maxSeq = seq;
+                this.emit({ type: 'session/event', sessionId: sessionId, event });
+            }
+            this.pollWatermark.set(sessionId, maxSeq);
+        }
+        catch {
+            // Transient (network, pairing, history paging); the next tick retries.
+        }
+    }
     handleMessage(data) {
         if (typeof data !== 'string' || data === '')
             return;
@@ -84,9 +221,19 @@ export class MuxClient {
         const frame = muxFrameSchema.safeParse(envelope.data.payload);
         if (!frame.success)
             return;
+        // A delivered frame proves the SSE channel is live (the tunnel forwards
+        // it) and delivers again — drop any fallback polling so the live stream
+        // takes over without double delivery.
+        this.sseAlive = true;
+        this.lastDataAt = this.now();
+        if (this.polling)
+            this.stopPolling();
+        this.emit(frame.data);
+    }
+    emit(frame) {
         for (const listener of this.listeners) {
             try {
-                listener(frame.data);
+                listener(frame);
             }
             catch {
                 // A throwing subscriber must not break the emit loop.

package/lib/types/mobile/mux.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mux.test.d.ts.map

package/lib/types/mobile/mux.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mux.test.d.ts","sourceRoot":"","sources":["../../../src/mobile/mux.test.ts"],"names":[],"mappings":""}

package/lib/types/mobile/mux.test.js

@@ -0,0 +1,141 @@
+/** mux: live-event client, SSE delivery + stall-driven polling fallback. */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { MuxClient } from "./mux.js";
+/** Create an EventSource factory that records every opened source. */
+function makeSources() {
+    const sources = [];
+    const factory = (url) => {
+        const source = {
+            url,
+            onmessage: null,
+            onerror: null,
+            closed: false,
+            close: () => { source.closed = true; },
+        };
+        sources.push(source);
+        return source;
+    };
+    return { factory, sources };
+}
+/** One history page whose events carry sequential ids. */
+function pageOf(seqs) {
+    return {
+        hasMore: false,
+        events: seqs.map(seq => ({
+            event: { type: 'user/message', seq, time: seq * 1_000, data: { text: String(seq) } },
+        })),
+    };
+}
+/** A server-request envelope carrying one mux frame (the SSE wire shape). */
+function envelopeWith(payload) {
+    return JSON.stringify({ type: 'server-request', rpcId: 'r1', method: 'events.mux', payload });
+}
+/** Options common to every test: tight clocks, injected data source. */
+function baseOptions(pollLatest, factory) {
+    return { sourceFactory: factory, pollLatest, stallThresholdMs: 800, pollIntervalMs: 400 };
+}
+describe('MuxClient polling fallback', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    it('does not poll while the SSE channel is fresh', async () => {
+        const { factory } = makeSources();
+        const pollLatest = vi.fn(async (_sessionId) => pageOf([0]));
+        const client = new MuxClient('/m/api/events.mux', baseOptions(pollLatest, factory));
+        const frames = [];
+        client.onFrame(frame => { frames.push(frame); });
+        client.start();
+        client.observe('s1');
+        await vi.advanceTimersByTimeAsync(400); // well under the stall threshold
+        expect(pollLatest).not.toHaveBeenCalled();
+        expect(frames).toHaveLength(0);
+        client.stop();
+    });
+    it('starts polling after silence and emits appended events as session/event frames', async () => {
+        const { factory } = makeSources();
+        const pages = [pageOf([0]), pageOf([0, 1])];
+        const pollLatest = vi.fn(async (_sessionId) => pages.shift() ?? pageOf([]));
+        const client = new MuxClient('/m/api/events.mux', baseOptions(pollLatest, factory));
+        const frames = [];
+        client.onFrame(frame => { frames.push(frame); });
+        client.start();
+        client.observe('s1');
+        // Nothing live within a poll interval until the stall window passes.
+        await vi.advanceTimersByTimeAsync(400);
+        expect(pollLatest).not.toHaveBeenCalled();
+        // Past the stall threshold the first poll runs and emits seq 0.
+        await vi.advanceTimersByTimeAsync(700); // 1100ms total -> first stall-checker tick
+        expect(pollLatest).toHaveBeenCalledWith('s1');
+        expect(frames).toHaveLength(1);
+        expect(frames[0]).toMatchObject({ type: 'session/event', sessionId: 's1' });
+        expect(frames[0]?.event).toMatchObject({ seq: 0 });
+        // The next poll emits only the appended event (seq 1), not seq 0 again.
+        await vi.advanceTimersByTimeAsync(400);
+        expect(frames).toHaveLength(2);
+        expect(frames[1]?.event).toMatchObject({ seq: 1 });
+        client.stop();
+    });
+    it('keeps the watermark so a repeated page never re-emits old events', async () => {
+        const { factory } = makeSources();
+        // Two calls return the same page: the second must emit nothing.
+        const pollLatest = vi.fn(async (_sessionId) => pageOf([0, 1, 2]));
+        const client = new MuxClient('/m/api/events.mux', baseOptions(pollLatest, factory));
+        const frames = [];
+        client.onFrame(frame => { frames.push(frame); });
+        client.start();
+        client.observe('s1');
+        await vi.advanceTimersByTimeAsync(1100); // first poll -> 3 events
+        expect(frames).toHaveLength(3);
+        await vi.advanceTimersByTimeAsync(400); // second poll -> same page, nothing new
+        expect(frames).toHaveLength(3);
+        client.stop();
+    });
+    it('stops polling when observe is cleared and keeps it stopped', async () => {
+        const { factory } = makeSources();
+        const pollLatest = vi.fn(async (_sessionId) => pageOf([0]));
+        const client = new MuxClient('/m/api/events.mux', baseOptions(pollLatest, factory));
+        client.start();
+        client.observe('s1');
+        await vi.advanceTimersByTimeAsync(1100);
+        expect(pollLatest).toHaveBeenCalled();
+        client.observe(undefined);
+        const callsAfterClear = pollLatest.mock.calls.length;
+        await vi.advanceTimersByTimeAsync(2000);
+        expect(pollLatest.mock.calls.length).toBe(callsAfterClear);
+        client.stop();
+    });
+    it('stops polling on stop(), closing any live source', async () => {
+        const { factory, sources } = makeSources();
+        const pollLatest = vi.fn(async (_sessionId) => pageOf([0]));
+        const client = new MuxClient('/m/api/events.mux', baseOptions(pollLatest, factory));
+        client.start();
+        client.observe('s1');
+        await vi.advanceTimersByTimeAsync(1100);
+        expect(pollLatest).toHaveBeenCalled();
+        client.stop();
+        const callsAfterStop = pollLatest.mock.calls.length;
+        await vi.advanceTimersByTimeAsync(2000);
+        expect(pollLatest.mock.calls.length).toBe(callsAfterStop);
+        expect(sources[0]?.closed).toBe(true);
+    });
+    it('returns to SSE when a frame arrives, dropping the fallback poller', async () => {
+        const { factory, sources } = makeSources();
+        const pollLatest = vi.fn(async (_sessionId) => pageOf([0]));
+        const client = new MuxClient('/m/api/events.mux', baseOptions(pollLatest, factory));
+        const frames = [];
+        client.onFrame(frame => { frames.push(frame); });
+        client.start();
+        client.observe('s1');
+        // Stall into polling.
+        await vi.advanceTimersByTimeAsync(1100);
+        expect(pollLatest).toHaveBeenCalledTimes(1);
+        // A live mux frame proves SSE delivers again -> fallback stops.
+        sources[0]?.onmessage?.({ data: envelopeWith({ type: 'session/subscribed', sessionId: 's1', lastSeq: 4 }) });
+        await vi.advanceTimersByTimeAsync(2000);
+        expect(pollLatest.mock.calls.length).toBe(1); // polling stopped after the live frame
+        const live = frames.filter(frame => frame?.type === 'session/subscribed');
+        expect(live).toHaveLength(1);
+        expect(live[0]).toMatchObject({ type: 'session/subscribed', sessionId: 's1' });
+        client.stop();
+    });
+});

package/lib/types/mobile/views/App.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"App.d.ts","sourceRoot":"","sources":["../../../../src/mobile/views/App.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAA2B,YAAY,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAazF,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;CACf;AAED,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAA;CACnD,GAAG,WAAW,CAad;AAED,+CAA+C;AAC/C,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CASlD;AAED;;;GAGG;AACH,wBAAgB,GAAG,gCAwClB;AAED,qEAAqE;AACrE,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKhD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIjE;AAED,6FAA6F;AAC7F,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,4CAEhE;AAED,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,EAAE,CAAA"}
+{"version":3,"file":"App.d.ts","sourceRoot":"","sources":["../../../../src/mobile/views/App.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAA2B,YAAY,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAazF,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;CACf;AAED,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAA;CACnD,GAAG,WAAW,CAad;AAED,+CAA+C;AAC/C,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CASlD;AAED;;;GAGG;AACH,wBAAgB,GAAG,gCA+ClB;AAED,qEAAqE;AACrE,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKhD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIjE;AAED,6FAA6F;AAC7F,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,4CAEhE;AAED,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,EAAE,CAAA"}

package/lib/types/mobile/views/App.js

@@ -55,6 +55,12 @@ export function App() {
         mux.start();
         return () => { mux.stop(); };
     }, []);
+    // Keep the live-event client pointed at the session currently on screen so
+    // its polling fallback can keep that chat fresh over SSE-impairing tunnels
+    // (quick tunnel / Tailscale Serve do not forward Server-Sent Events).
+    useEffect(() => {
+        muxRef.current?.observe(route.kind === 'chat' ? route.session.sessionId : undefined);
+    }, [route]);
     const back = useCallback(() => {
         setRoute(previous => {
             if (previous.kind === 'chat')

package/lib/types/mobile/views/ChatView.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChatView.d.ts","sourceRoot":"","sources":["../../../../src/mobile/views/ChatView.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAIjE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAGrC,+BAA+B;AAC/B,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,WAAW,CAAA;IACpB,6EAA6E;IAC7E,GAAG,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IAC3B,MAAM,IAAI,IAAI,CAAA;CACf;AAYD,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,gBAAgB,EAAE,CAAA;IAC3B,YAAY,EAAE,MAAM,CAAA;CACrB;AAqCD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,aAAa,+BA6M/D"}
+{"version":3,"file":"ChatView.d.ts","sourceRoot":"","sources":["../../../../src/mobile/views/ChatView.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAIjE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAGrC,+BAA+B;AAC/B,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,WAAW,CAAA;IACpB,6EAA6E;IAC7E,GAAG,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IAC3B,MAAM,IAAI,IAAI,CAAA;CACf;AAYD,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,gBAAgB,EAAE,CAAA;IAC3B,YAAY,EAAE,MAAM,CAAA;CACrB;AAqCD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,aAAa,+BA2N/D"}

package/lib/types/mobile/views/ChatView.js

@@ -100,7 +100,6 @@ export function ChatView({ session, mux, onBack }) {
             // plugin (augmentation), so the base SDK map is indexed loosely.
             const projections = page.projections?.values;
             setPermissions(parsePermissionSelect(projections?.['permissions']));
-            scrollToBottom();
         }, (reason) => {
             if (cancelled)
                 return;
@@ -134,17 +133,32 @@ export function ChatView({ session, mux, onBack }) {
             }
         });
     }, [mux, session.sessionId]);
-    // Keep the newest content visible while streaming.
-    useEffect(() => {
-        if (messages.some(message => message.pending === true))
-            scrollToBottom();
-    }, [messages]);
     const scrollToBottom = useCallback(() => {
         const el = scrollRef.current;
         if (el === undefined)
             return;
         el.scrollTop = el.scrollHeight;
     }, []);
+    // Track the last message's fold key so scrolling only fires when the
+    // newest message actually changes (seq bump and/or pending flip). Runs
+    // after React has committed the render, so scrollHeight reflects the
+    // freshly appended content.
+    const lastMessageKeyRef = useRef(undefined);
+    // Keep the newest content visible. This covers the initial tail page (the
+    // effect runs after commit, fixing the stale scrollHeight from the old
+    // open-time scrollToBottom), live streaming chunks on the pending message,
+    // and finalized/appended messages. Prepending older pages via loadOlder
+    // leaves the last message untouched, so it never disturbs the scroll position.
+    useEffect(() => {
+        const last = messages[messages.length - 1];
+        if (last === undefined)
+            return;
+        const key = last.seq + ':' + (last.pending === true ? 'p' : 'f');
+        if (key === lastMessageKeyRef.current)
+            return;
+        lastMessageKeyRef.current = key;
+        scrollToBottom();
+    }, [messages, scrollToBottom]);
     /** Load one older page and prepend it. The fold is directional (incremental
      *  tails only), so the older page folds standalone and concatenates ahead —
      *  host page boundaries never cut a message, so the seam is exact. */