@wherever-dev/client 0.8.1 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +18 -0
- package/dist/client.d.ts +6 -0
- package/dist/client.js +131 -45
- package/dist/client.js.map +1 -1
- package/dist/frame-chunks.d.ts +39 -0
- package/dist/frame-chunks.js +70 -0
- package/dist/frame-chunks.js.map +1 -0
- package/dist/types.d.ts +13 -1
- package/dist/types.js.map +1 -1
- package/package.json +1 -1
- package/src/client.ts +135 -50
- package/src/frame-chunks.ts +77 -0
- package/src/types.ts +13 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,23 @@
|
|
|
1
1
|
# @wherever-dev/client
|
|
2
2
|
|
|
3
|
+
## 0.9.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 016c887: Wherever is now usable on a slow connection. Before, opening or reconnecting to a session whose recent history held a large tool image (a `read` on a screenshot) could loop forever on a weak link: the history was one multi-MB WebSocket frame, the browser only delivers a frame once it has fully arrived, and the client's liveness watchdog took the long silence for a dead socket, reconnected and asked for the same history again. Measured at 30 KB/s with a 3 MB image: the history never painted; now it paints in about 2 s.
|
|
8
|
+
- Large server frames are split into small chunks for clients that ask (`frames=chunk.v1`), so a big transfer keeps proving the socket alive and no longer times out the session load.
|
|
9
|
+
- History tool images larger than 16 KB are sent by reference for clients that ask (`imageRefs=1`; `WhereverClient` gains an `imageRefs` option, off by default, which the web app turns on) and loaded lazily from the new `GET /session/tool-image`, which the browser caches for good. A reconnect now re-sends text only, and the on-device conversation cache keeps those images.
|
|
10
|
+
- WebSocket frames are compressed (`permessage-deflate`), and the web app's JS/CSS/HTML are served with brotli or gzip.
|
|
11
|
+
- Streamed reply, thinking and tool-output deltas are merged into about one frame per 50 ms instead of one frame per token (order unchanged, nothing dropped), and a client that falls behind catches up in a few large frames instead of thousands of tiny ones.
|
|
12
|
+
|
|
13
|
+
Chunking and images by reference are opt-in per connection, so an older cached web build or client keeps the previous behaviour; delta merging is transparent to every client.
|
|
14
|
+
|
|
15
|
+
## 0.8.2
|
|
16
|
+
|
|
17
|
+
### Patch Changes
|
|
18
|
+
|
|
19
|
+
- 6f0725a: Coming back to the PWA no longer reconnects slower than a page reload. When the page becomes visible again, the client probes the existing socket with a 2 s grace (was 5 s), replaces a dead socket at once instead of after the reconnect backoff, resets a backoff that grew while the app was in the background, and restarts a handshake still pending after 8 s. A dead socket on return used to cost 7 to 20 s of "Reconnecting...".
|
|
20
|
+
|
|
3
21
|
## 0.8.1
|
|
4
22
|
|
|
5
23
|
### Patch Changes
|
package/dist/client.d.ts
CHANGED
|
@@ -22,6 +22,7 @@ export interface WhereverClientConfig {
|
|
|
22
22
|
hideTools?: boolean;
|
|
23
23
|
clientKey?: string;
|
|
24
24
|
onClientKeyChange?: (key: string) => void;
|
|
25
|
+
imageRefs?: boolean;
|
|
25
26
|
}
|
|
26
27
|
/** The capability a server advertises in `connected` for chunked uploads. */
|
|
27
28
|
export declare const UPLOAD_CAPABILITY = "upload.v1";
|
|
@@ -52,7 +53,9 @@ export declare class WhereverClient {
|
|
|
52
53
|
private createWatchdog;
|
|
53
54
|
private static readonly CREATE_WATCHDOG_MS;
|
|
54
55
|
private reconnectAttempts;
|
|
56
|
+
private static readonly MIN_RECONNECT_DELAY;
|
|
55
57
|
private reconnectDelay;
|
|
58
|
+
private socketStartedAt;
|
|
56
59
|
private maxReconnectDelay;
|
|
57
60
|
private hasEverConnected;
|
|
58
61
|
private static readonly HANDSHAKE_FAIL_HINT_AFTER;
|
|
@@ -63,6 +66,8 @@ export declare class WhereverClient {
|
|
|
63
66
|
private static readonly TURN_STALL_MS;
|
|
64
67
|
private static readonly HEARTBEAT_MS;
|
|
65
68
|
private static readonly PROBE_GRACE_MS;
|
|
69
|
+
private static readonly VISIBLE_PROBE_GRACE_MS;
|
|
70
|
+
private static readonly STALLED_HANDSHAKE_MS;
|
|
66
71
|
private probeTimer;
|
|
67
72
|
private lastLivenessTickAt;
|
|
68
73
|
private isInitialConnect;
|
|
@@ -102,6 +107,7 @@ export declare class WhereverClient {
|
|
|
102
107
|
private armCreateWatchdog;
|
|
103
108
|
private clearCreateWatchdog;
|
|
104
109
|
private scheduleReconnect;
|
|
110
|
+
private reconnectNow;
|
|
105
111
|
private handleMessage;
|
|
106
112
|
/**
|
|
107
113
|
* True when an errored tool result is the product of a USER ABORT (e.g. the
|
package/dist/client.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { writable, get } from "sveltore";
|
|
2
2
|
import { skillInvocationIdentity, } from "./types.js";
|
|
3
|
+
import { FrameReassembler, FRAME_CHUNK_PARAM, FRAME_CHUNK_VERSION } from "./frame-chunks.js";
|
|
3
4
|
// Per-instance fallback identity: stable for the lifetime of this client object,
|
|
4
5
|
// which is exactly the lifetime across which reconnects happen.
|
|
5
6
|
function generateClientKey() {
|
|
@@ -187,7 +188,11 @@ export class WhereverClient {
|
|
|
187
188
|
createWatchdog = null;
|
|
188
189
|
static CREATE_WATCHDOG_MS = 25_000;
|
|
189
190
|
reconnectAttempts = 0;
|
|
190
|
-
|
|
191
|
+
static MIN_RECONNECT_DELAY = 2000;
|
|
192
|
+
reconnectDelay = WhereverClient.MIN_RECONNECT_DELAY;
|
|
193
|
+
// Wall-clock time the current socket was created, so a return to the page can
|
|
194
|
+
// tell a handshake that has hung across a freeze from one just started.
|
|
195
|
+
socketStartedAt = 0;
|
|
191
196
|
maxReconnectDelay = 15000;
|
|
192
197
|
// Whether the socket has EVER opened successfully since construction. Repeated
|
|
193
198
|
// closes with zero successful opens almost always mean a rejected handshake
|
|
@@ -223,6 +228,20 @@ export class WhereverClient {
|
|
|
223
228
|
// the timers fire BEFORE the frames queued during the freeze are dispatched,
|
|
224
229
|
// so the raw silence verdict is routinely false on a phone.
|
|
225
230
|
static PROBE_GRACE_MS = 5_000;
|
|
231
|
+
// The probe a return to the page starts (noteVisible) uses a shorter grace.
|
|
232
|
+
// The long grace above exists because timers that came due DURING a freeze
|
|
233
|
+
// fire before the frames queued during it; a probe started from the
|
|
234
|
+
// visibility event is a fresh timer, so the queued frames (and a healthy
|
|
235
|
+
// socket's pong, one round trip later) are dispatched well before it fires.
|
|
236
|
+
// Waiting the full 5 s there, then the reconnect backoff on top, is what made
|
|
237
|
+
// coming back to the PWA slower than a reload.
|
|
238
|
+
static VISIBLE_PROBE_GRACE_MS = 2_000;
|
|
239
|
+
// A socket still CONNECTING this long when the page becomes visible is
|
|
240
|
+
// treated as a handshake that hung (typically started before a freeze,
|
|
241
|
+
// against a network that was gone) and restarted. Well above an honest slow
|
|
242
|
+
// mobile TLS handshake, so a return never throws away one that is about to
|
|
243
|
+
// complete.
|
|
244
|
+
static STALLED_HANDSHAKE_MS = 8_000;
|
|
226
245
|
// The pending probe's grace timer, and the socket it was started on. Cleared
|
|
227
246
|
// by any inbound frame, by stopLivenessWatchdog (every socket change), and
|
|
228
247
|
// ignored if the socket it belongs to is no longer current.
|
|
@@ -371,6 +390,15 @@ export class WhereverClient {
|
|
|
371
390
|
if (this.config.token)
|
|
372
391
|
params.push(`token=${encodeURIComponent(this.config.token)}`);
|
|
373
392
|
params.push(`clientKey=${encodeURIComponent(this.clientKey)}`);
|
|
393
|
+
// Ask the server to split large frames (frame-chunks.ts): a multi-MB history
|
|
394
|
+
// arriving as ONE frame over a slow link looked like a dead socket to the
|
|
395
|
+
// liveness watchdog, which tore it down and looped forever.
|
|
396
|
+
params.push(`${FRAME_CHUNK_PARAM}=${FRAME_CHUNK_VERSION}`);
|
|
397
|
+
// History tool images by reference (fetched lazily, cached by the browser)
|
|
398
|
+
// rather than as base64 re-sent on every load and reconnect. Opt-in: the
|
|
399
|
+
// caller must then render images that have no `data`.
|
|
400
|
+
if (this.config.imageRefs)
|
|
401
|
+
params.push('imageRefs=1');
|
|
374
402
|
const wsUrl = `${protocol}://${host}:${this.config.port}/ws?${params.join('&')}`;
|
|
375
403
|
const WebSocketImpl = this.config.WebSocketCtor || (typeof globalThis !== 'undefined' ? globalThis.WebSocket : null);
|
|
376
404
|
if (!WebSocketImpl) {
|
|
@@ -383,6 +411,7 @@ export class WhereverClient {
|
|
|
383
411
|
}
|
|
384
412
|
// A new socket: its capabilities are unknown until its `connected` frame.
|
|
385
413
|
this.socketCapabilities = null;
|
|
414
|
+
this.socketStartedAt = Date.now();
|
|
386
415
|
try {
|
|
387
416
|
const wsOptions = this.config.secure && this.config.WebSocketCtor ? { rejectUnauthorized: false } : undefined;
|
|
388
417
|
this.ws = wsOptions ? new WebSocketImpl(wsUrl, wsOptions) : new WebSocketImpl(wsUrl);
|
|
@@ -397,6 +426,10 @@ export class WhereverClient {
|
|
|
397
426
|
return;
|
|
398
427
|
}
|
|
399
428
|
const currentWs = this.ws;
|
|
429
|
+
const reassembler = new FrameReassembler();
|
|
430
|
+
// One warning per run of bad chunks: after one, every remaining chunk of
|
|
431
|
+
// that message is invalid too.
|
|
432
|
+
let inBadChunkRun = false;
|
|
400
433
|
const onOpen = () => {
|
|
401
434
|
if (this.ws !== currentWs)
|
|
402
435
|
return;
|
|
@@ -405,7 +438,7 @@ export class WhereverClient {
|
|
|
405
438
|
}
|
|
406
439
|
this.hasEverConnected = true;
|
|
407
440
|
this.reconnectAttempts = 0;
|
|
408
|
-
this.reconnectDelay =
|
|
441
|
+
this.reconnectDelay = WhereverClient.MIN_RECONNECT_DELAY;
|
|
409
442
|
this.isInitialConnect = false;
|
|
410
443
|
this.startLivenessWatchdog();
|
|
411
444
|
this.stateStore.update(s => ({
|
|
@@ -479,7 +512,23 @@ export class WhereverClient {
|
|
|
479
512
|
this.cancelLivenessProbe();
|
|
480
513
|
try {
|
|
481
514
|
const rawData = typeof event.data === 'string' ? event.data : event.data.toString();
|
|
482
|
-
const
|
|
515
|
+
const piece = reassembler.push(rawData);
|
|
516
|
+
if (piece.kind !== 'invalid')
|
|
517
|
+
inBadChunkRun = false;
|
|
518
|
+
if (piece.kind === 'partial') {
|
|
519
|
+
// A large frame is still arriving: the load it answers is making
|
|
520
|
+
// progress, so it must not time out meanwhile.
|
|
521
|
+
if (this.loadWatchdog)
|
|
522
|
+
this.armLoadWatchdog();
|
|
523
|
+
return;
|
|
524
|
+
}
|
|
525
|
+
if (piece.kind === 'invalid') {
|
|
526
|
+
if (!inBadChunkRun)
|
|
527
|
+
console.warn('[wherever] dropped a malformed or incomplete chunked frame');
|
|
528
|
+
inBadChunkRun = true;
|
|
529
|
+
return;
|
|
530
|
+
}
|
|
531
|
+
const msg = JSON.parse(piece.text);
|
|
483
532
|
this.handleMessage(msg);
|
|
484
533
|
}
|
|
485
534
|
catch (err) {
|
|
@@ -736,20 +785,41 @@ export class WhereverClient {
|
|
|
736
785
|
// socket is OPEN and watched, probe it right away instead of waiting for the
|
|
737
786
|
// next tick, and reset the stale baseline so the time the page spent frozen is
|
|
738
787
|
// not counted as silence (the probe decides whether the socket is alive).
|
|
739
|
-
//
|
|
740
|
-
//
|
|
788
|
+
//
|
|
789
|
+
// The user is looking at the page, so a return must never pay the slow paths
|
|
790
|
+
// meant for an unattended client: the probe uses the short
|
|
791
|
+
// VISIBLE_PROBE_GRACE_MS, a socket it condemns is replaced at once instead of
|
|
792
|
+
// after the reconnect backoff, and the backoff grown while hidden is reset.
|
|
793
|
+
// A socket still CONNECTING after STALLED_HANDSHAKE_MS is restarted.
|
|
794
|
+
// With no socket at all this only resets the backoff: the page follows up
|
|
795
|
+
// with resume() / connect(), which connect at once.
|
|
741
796
|
noteVisible() {
|
|
797
|
+
this.reconnectDelay = WhereverClient.MIN_RECONNECT_DELAY;
|
|
742
798
|
const ws = this.ws;
|
|
743
|
-
if (!ws
|
|
799
|
+
if (!ws)
|
|
800
|
+
return;
|
|
801
|
+
if (ws.readyState === 0 /* CONNECTING */) {
|
|
802
|
+
if (Date.now() - this.socketStartedAt > WhereverClient.STALLED_HANDSHAKE_MS) {
|
|
803
|
+
console.info('[wherever] handshake stalled; restarting it');
|
|
804
|
+
this.reconnectNow();
|
|
805
|
+
}
|
|
806
|
+
return;
|
|
807
|
+
}
|
|
808
|
+
if (ws.readyState !== 1 /* OPEN */ || !this.livenessTimer)
|
|
744
809
|
return;
|
|
745
810
|
this.lastInboundAt = Date.now();
|
|
746
811
|
this.lastLivenessTickAt = this.lastInboundAt;
|
|
747
812
|
// Restart any pending probe: its grace may have been eaten by the freeze.
|
|
748
813
|
this.cancelLivenessProbe();
|
|
749
|
-
this.startLivenessProbe('page became visible');
|
|
814
|
+
this.startLivenessProbe('page became visible', true);
|
|
750
815
|
}
|
|
751
816
|
// Send a ping and arm the grace check. Idempotent while a probe is pending.
|
|
752
|
-
|
|
817
|
+
// `onReturn` marks the probe a return to the page started: short grace, and
|
|
818
|
+
// an immediate reconnect if it goes unanswered.
|
|
819
|
+
startLivenessProbe(reason, onReturn = false) {
|
|
820
|
+
const grace = onReturn
|
|
821
|
+
? WhereverClient.VISIBLE_PROBE_GRACE_MS
|
|
822
|
+
: WhereverClient.PROBE_GRACE_MS;
|
|
753
823
|
if (this.probeTimer || !this.ws || typeof setTimeout !== 'function')
|
|
754
824
|
return;
|
|
755
825
|
const probedWs = this.ws;
|
|
@@ -769,15 +839,17 @@ export class WhereverClient {
|
|
|
769
839
|
// background timer throttling (timers batched to ~1/min in a long-hidden
|
|
770
840
|
// tab) every grace check is late, so the verdict on a dead socket is
|
|
771
841
|
// deferred until the page is visible again, where noteVisible() restarts
|
|
772
|
-
// an unthrottled probe and a dead socket goes ~
|
|
842
|
+
// an unthrottled probe and a dead socket goes ~2 s later. Accepted: a
|
|
773
843
|
// hidden page has no viewer, and a capped retry would reintroduce the
|
|
774
844
|
// false teardown on thaw this probe exists to prevent.
|
|
775
|
-
|
|
845
|
+
// A return probe whose check ran late means the page froze again, so
|
|
846
|
+
// nobody is waiting on it any more: re-probe as an ordinary probe.
|
|
847
|
+
if (Date.now() - sentAt > 2 * grace) {
|
|
776
848
|
this.startLivenessProbe(reason);
|
|
777
849
|
return;
|
|
778
850
|
}
|
|
779
|
-
this.tearDownStaleSocket(reason);
|
|
780
|
-
},
|
|
851
|
+
this.tearDownStaleSocket(reason, grace, onReturn);
|
|
852
|
+
}, grace);
|
|
781
853
|
if (this.probeTimer && typeof this.probeTimer.unref === 'function') {
|
|
782
854
|
this.probeTimer.unref();
|
|
783
855
|
}
|
|
@@ -791,12 +863,12 @@ export class WhereverClient {
|
|
|
791
863
|
// The probe went unanswered: treat the socket as dead. Tearing it down
|
|
792
864
|
// forcibly is what makes a half-open connection recover, since the OS never
|
|
793
865
|
// produced a FIN/RST to trigger the normal close path.
|
|
794
|
-
tearDownStaleSocket(reason) {
|
|
866
|
+
tearDownStaleSocket(reason, graceMs, immediate) {
|
|
795
867
|
if (!this.ws)
|
|
796
868
|
return;
|
|
797
869
|
const streaming = get(this.stateStore).isStreaming;
|
|
798
870
|
console.warn(`[wherever] relay connection stale: ${reason}; probe unanswered for ` +
|
|
799
|
-
`${
|
|
871
|
+
`${graceMs}ms; tearing down dead socket and reconnecting`);
|
|
800
872
|
this.stopLivenessWatchdog();
|
|
801
873
|
const deadWs = this.ws;
|
|
802
874
|
this.ws = null;
|
|
@@ -825,7 +897,12 @@ export class WhereverClient {
|
|
|
825
897
|
: s.sessionError,
|
|
826
898
|
isStreaming: false,
|
|
827
899
|
}));
|
|
828
|
-
|
|
900
|
+
// A probe started by a return to the page has a user waiting on it: no
|
|
901
|
+
// backoff, the dead socket is replaced now.
|
|
902
|
+
if (immediate)
|
|
903
|
+
this.reconnectNow();
|
|
904
|
+
else
|
|
905
|
+
this.scheduleReconnect();
|
|
829
906
|
}
|
|
830
907
|
stopLivenessWatchdog() {
|
|
831
908
|
this.cancelLivenessProbe();
|
|
@@ -902,39 +979,48 @@ export class WhereverClient {
|
|
|
902
979
|
this.reconnectTimer = setTimeout(() => {
|
|
903
980
|
this.reconnectTimer = null;
|
|
904
981
|
this.reconnectDelay = Math.min(this.reconnectDelay * 1.5, this.maxReconnectDelay);
|
|
905
|
-
|
|
906
|
-
|
|
907
|
-
|
|
908
|
-
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
920
|
-
|
|
921
|
-
|
|
922
|
-
|
|
923
|
-
|
|
924
|
-
|
|
925
|
-
// activeSessionFile BEFORE onOpen could re-attach to it -- that is what
|
|
926
|
-
// silently detached the frontend from a still-running session (frozen
|
|
927
|
-
// conversation, no re-follow, not even a "connecting"/"loading" hint).
|
|
928
|
-
// Preserving the store keeps the conversation on screen and lets onOpen
|
|
929
|
-
// re-issue session_load from activeSessionFile.
|
|
930
|
-
const preserve = !!get(this.stateStore).activeSessionFile;
|
|
982
|
+
this.reconnectNow();
|
|
983
|
+
}, this.reconnectDelay);
|
|
984
|
+
}
|
|
985
|
+
// Reconnect right away (the body of a backoff timer firing), preserving the
|
|
986
|
+
// store when a session is active so onOpen rejoins it in place.
|
|
987
|
+
reconnectNow() {
|
|
988
|
+
if (this.reconnectTimer) {
|
|
989
|
+
clearTimeout(this.reconnectTimer);
|
|
990
|
+
this.reconnectTimer = null;
|
|
991
|
+
}
|
|
992
|
+
console.info(`[wherever] reconnecting to relay (attempt ${++this.reconnectAttempts})`);
|
|
993
|
+
// If we have retried a few times and NEVER once opened the socket, this is
|
|
994
|
+
// almost certainly a rejected handshake, not a flaky network. Surface a
|
|
995
|
+
// concrete, actionable error (the server rejects a bad/missing token with
|
|
996
|
+
// HTTP 401 during the WS upgrade, which the browser reports only as an
|
|
997
|
+
// opaque 1006 close). Keep retrying, but stop looking like a mere network
|
|
998
|
+
// hiccup.
|
|
999
|
+
if (!this.hasEverConnected &&
|
|
1000
|
+
this.reconnectAttempts >= WhereverClient.HANDSHAKE_FAIL_HINT_AFTER) {
|
|
1001
|
+
const scheme = this.config.secure ? 'wss' : 'ws';
|
|
931
1002
|
this.stateStore.update(s => ({
|
|
932
1003
|
...s,
|
|
933
|
-
|
|
934
|
-
|
|
1004
|
+
error: 'Cannot connect to the wherever server: the connection is being rejected. ' +
|
|
1005
|
+
'This usually means a missing or wrong token, or a wrong host/port/scheme ' +
|
|
1006
|
+
`(currently ${scheme}://${this.config.host}:${this.config.port}). ` +
|
|
1007
|
+
'Check the auth token and connection settings.',
|
|
935
1008
|
}));
|
|
936
|
-
|
|
937
|
-
|
|
1009
|
+
}
|
|
1010
|
+
// If we still hold an active session, PRESERVE the cached store across the
|
|
1011
|
+
// reconnect. A default connect() resets to a blank store, which wiped
|
|
1012
|
+
// activeSessionFile BEFORE onOpen could re-attach to it -- that is what
|
|
1013
|
+
// silently detached the frontend from a still-running session (frozen
|
|
1014
|
+
// conversation, no re-follow, not even a "connecting"/"loading" hint).
|
|
1015
|
+
// Preserving the store keeps the conversation on screen and lets onOpen
|
|
1016
|
+
// re-issue session_load from activeSessionFile.
|
|
1017
|
+
const preserve = !!get(this.stateStore).activeSessionFile;
|
|
1018
|
+
this.stateStore.update(s => ({
|
|
1019
|
+
...s,
|
|
1020
|
+
connecting: true,
|
|
1021
|
+
error: 'Reconnecting...',
|
|
1022
|
+
}));
|
|
1023
|
+
this.connect(undefined, preserve);
|
|
938
1024
|
}
|
|
939
1025
|
handleMessage(msg) {
|
|
940
1026
|
for (const listener of this.listeners) {
|