@wherever-dev/client 0.7.0 → 0.8.1

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.
Files changed (35) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +63 -0
  3. package/dist/client.d.ts +93 -2
  4. package/dist/client.js +960 -63
  5. package/dist/client.js.map +1 -1
  6. package/dist/types.d.ts +69 -0
  7. package/dist/types.js.map +1 -1
  8. package/package.json +23 -3
  9. package/src/client.ts +1031 -63
  10. package/src/types.ts +97 -0
  11. package/test/agent-pending.test.ts +0 -107
  12. package/test/conversation-mode-flag.test.ts +0 -111
  13. package/test/creating-session-watchdog.test.ts +0 -82
  14. package/test/folder-conflict-read-only.test.ts +0 -145
  15. package/test/folder-missing-read-only.test.ts +0 -114
  16. package/test/harness.ts +0 -97
  17. package/test/message-delivery-confirmation.test.ts +0 -320
  18. package/test/mid-stream-steer.test.ts +0 -91
  19. package/test/new-session-clone-progress.test.ts +0 -263
  20. package/test/optimistic-force-command.test.ts +0 -127
  21. package/test/queued-steer-restored.test.ts +0 -175
  22. package/test/reconnect-rejoins-session.test.ts +0 -136
  23. package/test/restore-panel.test.ts +0 -324
  24. package/test/resume-keeps-session.test.ts +0 -118
  25. package/test/session-load-by-id.test.ts +0 -100
  26. package/test/session-reload.test.ts +0 -82
  27. package/test/skills-autocomplete.test.ts +0 -113
  28. package/test/steer-queue-cancel.test.ts +0 -130
  29. package/test/superseded-connection-key.test.ts +0 -70
  30. package/test/superseded-session-load.test.ts +0 -180
  31. package/test/tool-aborted-render.test.ts +0 -170
  32. package/test/tool-duration-history.test.ts +0 -93
  33. package/test/tool-duration.test.ts +0 -86
  34. package/test/tool-interrupted-history.test.ts +0 -294
  35. package/tsconfig.json +0 -16
package/dist/client.js CHANGED
@@ -5,6 +5,119 @@ import { skillInvocationIdentity, } from "./types.js";
5
5
  function generateClientKey() {
6
6
  return `ck-${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;
7
7
  }
8
+ // --- Uploads (docs/adr/0012, frames in docs/USAGE.md) ----------------------
9
+ /** The capability a server advertises in `connected` for chunked uploads. */
10
+ export const UPLOAD_CAPABILITY = 'upload.v1';
11
+ const KiB = 1024;
12
+ /**
13
+ * Chunked-upload pacing. The window is the number of BYTES in flight (sent, not
14
+ * yet acked): about UPLOAD_WINDOW_SECONDS worth at the throughput measured from
15
+ * acks, clamped to [UPLOAD_WINDOW_MIN, UPLOAD_WINDOW_MAX]. Before any ack has
16
+ * been timed it is the minimum, so a slow uplink is never flooded (a queue of
17
+ * bytes ahead of the heartbeat pong is what used to kill the socket). Each chunk
18
+ * is `min(window, UPLOAD_CHUNK_MAX)`, well under the server's 1 MiB cap.
19
+ */
20
+ const UPLOAD_WINDOW_MIN = 64 * KiB;
21
+ const UPLOAD_WINDOW_MAX = 1024 * KiB;
22
+ const UPLOAD_CHUNK_MAX = 256 * KiB;
23
+ const UPLOAD_WINDOW_SECONDS = 2;
24
+ // Weight of the newest throughput sample in the moving average.
25
+ const UPLOAD_RATE_ALPHA = 0.3;
26
+ // Legacy base64 is built from reads of this many bytes: a multiple of 3, so
27
+ // each piece encodes without `=` padding and the pieces simply concatenate.
28
+ const LEGACY_READ_BYTES = 3 * 256 * KiB;
29
+ const NOT_READABLE_MESSAGE = 'The file is no longer readable, pick it again';
30
+ /** `[u8 kind=1][u8 version=1][u8 idLen][uploadId ascii][u64 offset BE][payload]` */
31
+ export function encodeChunkFrame(uploadId, offset, payload) {
32
+ const head = 3 + uploadId.length;
33
+ const frame = new Uint8Array(head + 8 + payload.length);
34
+ frame[0] = 1;
35
+ frame[1] = 1;
36
+ frame[2] = uploadId.length;
37
+ for (let i = 0; i < uploadId.length; i++)
38
+ frame[3 + i] = uploadId.charCodeAt(i);
39
+ const view = new DataView(frame.buffer);
40
+ view.setUint32(head, Math.floor(offset / 2 ** 32));
41
+ view.setUint32(head + 4, offset >>> 0);
42
+ frame.set(payload, head + 8);
43
+ return frame;
44
+ }
45
+ function bytesToBinaryString(bytes) {
46
+ let out = '';
47
+ for (let i = 0; i < bytes.length; i += 0x8000) {
48
+ out += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000));
49
+ }
50
+ return out;
51
+ }
52
+ /**
53
+ * 128 random bits, base64url without padding (22 characters, matching the
54
+ * server's `^[A-Za-z0-9_-]{22,64}$`). The id is what makes a resume
55
+ * unguessable, so it comes from `crypto.getRandomValues`; Math.random is only a
56
+ * last resort for a runtime without Web Crypto.
57
+ */
58
+ function generateUploadId() {
59
+ const bytes = new Uint8Array(16);
60
+ const c = globalThis.crypto;
61
+ if (c && typeof c.getRandomValues === 'function') {
62
+ c.getRandomValues(bytes);
63
+ }
64
+ else {
65
+ for (let i = 0; i < bytes.length; i++)
66
+ bytes[i] = Math.floor(Math.random() * 256);
67
+ }
68
+ return btoa(bytesToBinaryString(bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
69
+ }
70
+ class UploadReadError extends Error {
71
+ code;
72
+ }
73
+ // The error an upload fails with when its byte source cannot be read.
74
+ function uploadReadError(err) {
75
+ if (err instanceof UploadReadError)
76
+ return err;
77
+ if (err && err.name === 'NotReadableError') {
78
+ const e = new UploadReadError(NOT_READABLE_MESSAGE);
79
+ e.code = 'not_readable';
80
+ return e;
81
+ }
82
+ return new UploadReadError(`Failed to read the file: ${(err && err.message) || err}`);
83
+ }
84
+ // A read that returned fewer (or other) bytes than asked: the file changed or
85
+ // was invalidated under us, which to the user is the same as unreadable.
86
+ function shortReadError() {
87
+ const e = new UploadReadError(NOT_READABLE_MESSAGE);
88
+ e.code = 'not_readable';
89
+ return e;
90
+ }
91
+ // The host as it goes on the socket URL: a pasted `http(s)://` prefix is dropped.
92
+ function socketHost(host) {
93
+ return host.startsWith('http') ? host.replace(/^https?:\/\//, '') : host;
94
+ }
95
+ // 32-bit FNV-1a over the UTF-16 code units, as 8 hex digits. NOT a security
96
+ // hash: it only keeps the raw token out of the key (and out of IndexedDB keys)
97
+ // while still telling two tokens apart.
98
+ function fnv1a(input) {
99
+ let h = 0x811c9dc5;
100
+ for (let i = 0; i < input.length; i++) {
101
+ h ^= input.charCodeAt(i);
102
+ h = Math.imul(h, 0x01000193);
103
+ }
104
+ return (h >>> 0).toString(16).padStart(8, '0');
105
+ }
106
+ /**
107
+ * The identity of the server a config points at: `host:port#<fnv1a(token)>`.
108
+ * Two configured servers (or one server with a rotated token) never share a
109
+ * key, so the web's conversation cache can never show one server's
110
+ * conversation for another (ADR 0013).
111
+ *
112
+ * Synchronous and pure on purpose: `connect()` is synchronous and must compare
113
+ * it with the stamp before deciding whether to preserve the store, and
114
+ * `crypto.subtle` is both async and missing on plain-http LAN origins. The
115
+ * scheme (`secure`) is deliberately NOT part of the key: ws vs wss to the same
116
+ * host:port is the same server.
117
+ */
118
+ export function serverKey(config) {
119
+ return `${socketHost(config.host)}:${config.port}#${fnv1a(config.token ?? '')}`;
120
+ }
8
121
  const defaultState = {
9
122
  connected: false,
10
123
  connecting: false,
@@ -19,6 +132,7 @@ const defaultState = {
19
132
  messages: [],
20
133
  clientId: null,
21
134
  serverVersion: null,
135
+ piVersion: null,
22
136
  folderConflict: null,
23
137
  folderMissing: null,
24
138
  restore: null,
@@ -35,6 +149,8 @@ const defaultState = {
35
149
  historyTotalCount: 0,
36
150
  historyOffset: 0,
37
151
  loadingMoreHistory: false,
152
+ historyAuthoritative: false,
153
+ serverKey: null,
38
154
  contextUsage: null,
39
155
  pendingSteering: [],
40
156
  skills: [],
@@ -100,6 +216,22 @@ export class WhereverClient {
100
216
  static TURN_STALL_MS = 45_000;
101
217
  // Send a keepalive well under STALE_SOCKET_MS so the pong refreshes liveness.
102
218
  static HEARTBEAT_MS = 25_000;
219
+ // Probe-before-teardown (docs/adr/0011): silence past the threshold never
220
+ // tears a socket down by itself. The watchdog pings and waits this long; ANY
221
+ // inbound frame in that window (onMessage) cancels the probe, and only a
222
+ // socket still silent when it expires is torn down. Needed because on a thaw
223
+ // the timers fire BEFORE the frames queued during the freeze are dispatched,
224
+ // so the raw silence verdict is routinely false on a phone.
225
+ static PROBE_GRACE_MS = 5_000;
226
+ // The pending probe's grace timer, and the socket it was started on. Cleared
227
+ // by any inbound frame, by stopLivenessWatchdog (every socket change), and
228
+ // ignored if the socket it belongs to is no longer current.
229
+ probeTimer = null;
230
+ // Wall-clock time of the previous watchdog tick. A gap of more than 2x
231
+ // HEARTBEAT_MS means the page was frozen; that is an extra, PROACTIVE probe
232
+ // trigger, never the gate (a 45-50 s freeze gap is not a >2x jump yet still
233
+ // crosses TURN_STALL_MS, which is why the probe itself decides).
234
+ lastLivenessTickAt = 0;
103
235
  isInitialConnect = true;
104
236
  // When set, the next successful (re)connection should rejoin the previously
105
237
  // active session instead of starting blank. Used by resume() so a backgrounded
@@ -116,8 +248,63 @@ export class WhereverClient {
116
248
  // null means "accept any" (e.g. session_new, whose target file is not known
117
249
  // until the reply). The latest tap always wins.
118
250
  pendingLoadFile = null;
251
+ // serverKey(config) of the socket currently open (captured by connect() next
252
+ // to the socket it opens). session_created stamps it on the store, so the
253
+ // stamp names the server that actually DELIVERED the session even if the
254
+ // settings are edited afterwards.
255
+ socketServerKey = null;
256
+ // The sessionFile painted by hydrateCachedSession(), until the server answers
257
+ // its rejoin with a session_created (or the hydration is abandoned). While
258
+ // set, an untagged session_error answering that load (pendingLoadFile ===
259
+ // hydratedFile) means the cached session is dead: see hydration_rejected.
260
+ hydratedFile = null;
119
261
  listeners = new Set();
262
+ // In-flight WebSocket uploads, keyed by uploadId. An upload is NOT bound to
263
+ // the socket it started on. On mobile, picking a file backgrounds the page and
264
+ // the socket is often lost within seconds; the upload then waits for the next
265
+ // connection (it is (re)sent once the rejoin is answered, since a reply owed
266
+ // by a dead socket never arrives). Without a server reply an upload is
267
+ // settled by: a full teardown (disconnect(true)), UPLOAD_TIMEOUT_MS of
268
+ // waiting, MAX_UPLOAD_SENDS attempts each lost with its socket (legacy only),
269
+ // cancellation, or a session change. The one unbounded case is by design: an
270
+ // upload on the wire of a socket that stays open is left to its replies (the
271
+ // server's handlers always answer), so a slow but healthy transfer is never
272
+ // cut off. Two protocols share this machinery (see PendingUpload).
120
273
  pendingUploads = new Map();
274
+ // Progress of every upload this client started, keyed by uploadId: the same
275
+ // value each upload's onProgress receives. Settled entries (done / failed /
276
+ // aborted) stay until forgetUpload(), so a late subscriber still sees how an
277
+ // upload ended.
278
+ uploadsStore = writable({});
279
+ // `connected.capabilities` of the CURRENT socket; null until its `connected`
280
+ // frame arrives. Uploads are HELD while null: sending one as legacy to a
281
+ // server that would have taken it chunked would throw resumability away.
282
+ socketCapabilities = null;
283
+ // An upload whose socket dies under it on every attempt (a frame too large
284
+ // for the server's maxPayload, which closes with 1009; or a slow uplink where
285
+ // the multi-MB frame starves the heartbeat) would otherwise be re-sent
286
+ // forever, kicking the live session into a resync each time. After this many
287
+ // sends lost with their socket, it fails. LEGACY frame only: a chunked upload
288
+ // resumes from the server's offset, so a lost socket costs it nothing.
289
+ static MAX_UPLOAD_SENDS = 3;
290
+ // `ws`'s default maxPayload is 100 MiB per frame; leave room for the JSON
291
+ // envelope. Larger base64 payloads are refused (~72 MB files). A backstop:
292
+ // the legacy path refuses `size > MAX_LEGACY_UPLOAD_BYTES` before reading.
293
+ static MAX_UPLOAD_BASE64_CHARS = 96 * 1024 * 1024;
294
+ // base64 of 72 MiB is exactly 96 MiB, MAX_UPLOAD_BASE64_CHARS.
295
+ static MAX_LEGACY_UPLOAD_BYTES = 72 * 1024 * 1024;
296
+ // Bounds the time an upload spends WAITING to be sent (no socket, or held for
297
+ // a rejoin), not its transmission: the clock is cleared whenever the frame
298
+ // actually goes out on an open socket, and re-armed when that socket closes.
299
+ // So a large, slow-but-healthy upload is never rejected mid-transfer.
300
+ static UPLOAD_TIMEOUT_MS = 10 * 60_000;
301
+ // True between a reconnect's rejoin session_load and its session_created.
302
+ // A fresh server socket starts attached to no session with readOnly=false;
303
+ // the server only sets this client's write verdict (readOnly) when it answers
304
+ // the session_load. Uploads sent in that window would bypass the read-only
305
+ // gate (and a multi-MB frame queued ahead of the rejoin could trip the load
306
+ // watchdog), so they are held until session_created lands.
307
+ uploadsHeldForRejoin = false;
121
308
  // Per-message confirmation watchdogs. A user message committed optimistically
122
309
  // is only proven delivered when the server echoes it back; if no echo lands
123
310
  // within CONFIRM_MS the watchdog flips it to delivery:'failed' so the UI can
@@ -145,6 +332,24 @@ export class WhereverClient {
145
332
  };
146
333
  }
147
334
  this.disconnect(false);
335
+ // A store stamped by ANOTHER server (host/port/token edited in Connection
336
+ // Settings, which saves without reconnecting, then this connect, including
337
+ // the automatic one from scheduleReconnect) must not be preserved or
338
+ // rejoined: it would paint, and the web would re-cache, one server's
339
+ // conversation under another's key, and the rejoin would ask the new
340
+ // server for a session it does not have. Wipe instead (which clears the
341
+ // stamp too), and drop every pending rejoin source.
342
+ const key = serverKey(this.config);
343
+ const stamped = get(this.stateStore).serverKey;
344
+ if (stamped !== null && stamped !== key) {
345
+ preserveState = false;
346
+ this.resumeSessionFile = null;
347
+ this.resumeCwd = undefined;
348
+ this.resumeModel = undefined;
349
+ this.pendingLoadFile = null;
350
+ this.hydratedFile = null;
351
+ }
352
+ this.socketServerKey = key;
148
353
  // preserveState keeps the cached session/messages in the store across a
149
354
  // reconnect (resume path), so the previous conversation stays visible while
150
355
  // we reconnect and resync. The default (fresh connect) clears to a blank
@@ -158,9 +363,7 @@ export class WhereverClient {
158
363
  hideTools: !!this.config.hideTools,
159
364
  });
160
365
  const protocol = this.config.secure ? "wss" : "ws";
161
- const host = this.config.host.startsWith('http')
162
- ? this.config.host.replace(/^https?:\/\//, '')
163
- : this.config.host;
366
+ const host = socketHost(this.config.host);
164
367
  // clientKey rides on the URL (not a post-connect frame) so the server can
165
368
  // evict this viewer's previous connection BEFORE any session traffic is
166
369
  // handled, closing the phantom-viewer window entirely.
@@ -178,6 +381,8 @@ export class WhereverClient {
178
381
  }));
179
382
  return;
180
383
  }
384
+ // A new socket: its capabilities are unknown until its `connected` frame.
385
+ this.socketCapabilities = null;
181
386
  try {
182
387
  const wsOptions = this.config.secure && this.config.WebSocketCtor ? { rejectUnauthorized: false } : undefined;
183
388
  this.ws = wsOptions ? new WebSocketImpl(wsUrl, wsOptions) : new WebSocketImpl(wsUrl);
@@ -237,12 +442,25 @@ export class WhereverClient {
237
442
  this.resumeSessionFile = null;
238
443
  this.resumeCwd = undefined;
239
444
  this.resumeModel = undefined;
445
+ // Uploads that were waiting for a socket (or whose reply died with the old
446
+ // one) go out only AFTER the rejoin has been answered (see
447
+ // uploadsHeldForRejoin): session_load first, uploads on session_created.
448
+ // With no session to rejoin there is no write verdict to wait for, and
449
+ // nothing to attribute the upload to any more, so they fail.
450
+ this.uploadsHeldForRejoin = !!rejoinFile;
451
+ if (!rejoinFile) {
452
+ this.rejectPendingUploads('The session was closed before the upload could be sent');
453
+ }
240
454
  if (rejoinFile) {
241
455
  // Keep the cached conversation on screen but mark it resyncing so the
242
456
  // "Reconnecting and syncing session..." banner shows and sending is
243
457
  // blocked until fresh history lands. resyncing is cleared by
244
458
  // message_history (or an error/conflict) via the reducer.
245
- this.stateStore.update(s => (s.resyncing ? s : { ...s, resyncing: true }));
459
+ // The history in the store (cached, or from the dropped socket) may be
460
+ // stale until this rejoin's message_history lands.
461
+ this.stateStore.update(s => s.resyncing && !s.historyAuthoritative
462
+ ? s
463
+ : { ...s, resyncing: true, historyAuthoritative: false });
246
464
  this.pendingLoadFile = rejoinFile;
247
465
  this.send({ type: 'session_load', sessionFile: rejoinFile, cwd: rejoinCwd, model: rejoinModel });
248
466
  this.armLoadWatchdog();
@@ -257,6 +475,8 @@ export class WhereverClient {
257
475
  // Any inbound frame (including the pong reply to our keepalive) proves the
258
476
  // socket is alive and resets the stale-socket watchdog.
259
477
  this.lastInboundAt = Date.now();
478
+ // ...and answers any pending probe, so it must not tear the socket down.
479
+ this.cancelLivenessProbe();
260
480
  try {
261
481
  const rawData = typeof event.data === 'string' ? event.data : event.data.toString();
262
482
  const msg = JSON.parse(rawData);
@@ -269,6 +489,7 @@ export class WhereverClient {
269
489
  const onClose = () => {
270
490
  if (this.ws !== currentWs)
271
491
  return;
492
+ this.uploadsLostSocket();
272
493
  this.stopLivenessWatchdog();
273
494
  this.clearLoadWatchdog();
274
495
  this.ws = null;
@@ -327,6 +548,8 @@ export class WhereverClient {
327
548
  // state, so cancel them here.
328
549
  this.clearLoadWatchdog();
329
550
  this.clearCreateWatchdog();
551
+ // suspend()/resume() close the socket through here, bypassing onClose.
552
+ this.uploadsLostSocket();
330
553
  if (this.ws) {
331
554
  const dyingWs = this.ws;
332
555
  try {
@@ -364,6 +587,11 @@ export class WhereverClient {
364
587
  for (const t of this.confirmTimers.values())
365
588
  clearTimeout(t);
366
589
  this.confirmTimers.clear();
590
+ // An explicit full disconnect abandons in-flight uploads (they would
591
+ // otherwise be re-sent to whatever server is connected next).
592
+ this.rejectPendingUploads('Disconnected before the upload completed');
593
+ this.uploadsHeldForRejoin = false;
594
+ this.hydratedFile = null;
367
595
  this.stateStore.set({
368
596
  ...defaultState,
369
597
  hideThinking: !!this.config.hideThinking,
@@ -422,12 +650,12 @@ export class WhereverClient {
422
650
  // cached active session from an unsolicited drop. In BOTH cases onOpen
423
651
  // re-issues session_load, so mark resyncing here to show the affordance and
424
652
  // block sending until fresh history lands.
653
+ // No load watchdog is armed here: connect() -> disconnect(false) would clear
654
+ // it at once, and onOpen arms one for the rejoin it actually issues. While
655
+ // the socket never opens (offline boot over a hydrated cache) there is no
656
+ // load in flight to time out, so no "timed out" error must appear.
425
657
  if (this.resumeSessionFile || s.activeSessionFile) {
426
658
  this.stateStore.update(st => ({ ...st, resyncing: true }));
427
- // Arm here too: if the socket never opens, onOpen never runs and the
428
- // resync affordance would otherwise hang. onClose also clears it, but the
429
- // watchdog covers the half-open / never-opens case.
430
- this.armLoadWatchdog();
431
659
  }
432
660
  this.connect(undefined, true);
433
661
  }
@@ -451,6 +679,7 @@ export class WhereverClient {
451
679
  startLivenessWatchdog() {
452
680
  this.stopLivenessWatchdog();
453
681
  this.lastInboundAt = Date.now();
682
+ this.lastLivenessTickAt = this.lastInboundAt;
454
683
  const sendBeat = () => {
455
684
  // Keep a healthy connection warm so the pong refreshes lastInboundAt even
456
685
  // during long, token-less model turns.
@@ -468,7 +697,17 @@ export class WhereverClient {
468
697
  const checkLiveness = () => {
469
698
  if (!this.ws)
470
699
  return;
471
- const silentFor = Date.now() - this.lastInboundAt;
700
+ const now = Date.now();
701
+ const sinceLastTick = now - this.lastLivenessTickAt;
702
+ this.lastLivenessTickAt = now;
703
+ // A wall-clock jump between ticks means the page was frozen: probe now
704
+ // rather than waiting for the silence threshold. Only a trigger; the
705
+ // probe's grace period still decides.
706
+ if (sinceLastTick > 2 * WhereverClient.HEARTBEAT_MS) {
707
+ this.startLivenessProbe('clock jump');
708
+ return;
709
+ }
710
+ const silentFor = now - this.lastInboundAt;
472
711
  const streaming = get(this.stateStore).isStreaming;
473
712
  // Per-turn stall timeout: while a turn is in flight the heartbeat pong (and,
474
713
  // normally, tokens) should keep traffic flowing, so a shorter deadline
@@ -480,38 +719,10 @@ export class WhereverClient {
480
719
  : WhereverClient.STALE_SOCKET_MS;
481
720
  if (silentFor < threshold)
482
721
  return;
483
- // The socket has been silent past the threshold: treat it as dead. Tearing
484
- // it down forcibly is what makes a half-open connection recover, since the
485
- // OS never produced a FIN/RST to trigger the normal close path.
486
- console.warn(`[wherever] relay connection stale: no inbound frame for ${silentFor}ms ` +
487
- `(threshold ${threshold}ms, ${streaming ? 'mid-turn' : 'idle'}); ` +
488
- `tearing down dead socket and reconnecting`);
489
- this.stopLivenessWatchdog();
490
- const deadWs = this.ws;
491
- this.ws = null;
492
- try {
493
- if (typeof deadWs.terminate === 'function') {
494
- deadWs.terminate();
495
- }
496
- else if (typeof deadWs.close === 'function') {
497
- deadWs.close();
498
- }
499
- }
500
- catch { }
501
- this.stateStore.update(s => ({
502
- ...s,
503
- connected: false,
504
- connecting: false,
505
- loadingSession: false,
506
- creatingSession: false,
507
- // If a turn was in flight, surface it as a recoverable error so the UI
508
- // shows "the transport stalled" rather than silently parking mid-stream.
509
- sessionError: streaming
510
- ? 'Connection to relay stalled mid-turn; reconnecting...'
511
- : s.sessionError,
512
- isStreaming: false,
513
- }));
514
- this.scheduleReconnect();
722
+ // Silent past the threshold: SUSPECT, not dead. Probe first (see
723
+ // PROBE_GRACE_MS); the teardown happens only if the probe goes unanswered.
724
+ this.startLivenessProbe(`no inbound frame for ${silentFor}ms ` +
725
+ `(threshold ${threshold}ms, ${streaming ? 'mid-turn' : 'idle'})`);
515
726
  };
516
727
  if (typeof setInterval === 'function') {
517
728
  this.livenessTimer = setInterval(checkLiveness, WhereverClient.HEARTBEAT_MS);
@@ -520,7 +731,104 @@ export class WhereverClient {
520
731
  }
521
732
  }
522
733
  }
734
+ // The page just became visible again (visibilitychange: visible, pageshow).
735
+ // The client has no `document` access, so the page calls this. If the current
736
+ // socket is OPEN and watched, probe it right away instead of waiting for the
737
+ // next tick, and reset the stale baseline so the time the page spent frozen is
738
+ // not counted as silence (the probe decides whether the socket is alive).
739
+ // A no-op otherwise: on a CONNECTING socket the ping would be dropped by
740
+ // send() and the grace check would tear down a socket still handshaking.
741
+ noteVisible() {
742
+ const ws = this.ws;
743
+ if (!ws || ws.readyState !== 1 /* OPEN */ || !this.livenessTimer)
744
+ return;
745
+ this.lastInboundAt = Date.now();
746
+ this.lastLivenessTickAt = this.lastInboundAt;
747
+ // Restart any pending probe: its grace may have been eaten by the freeze.
748
+ this.cancelLivenessProbe();
749
+ this.startLivenessProbe('page became visible');
750
+ }
751
+ // Send a ping and arm the grace check. Idempotent while a probe is pending.
752
+ startLivenessProbe(reason) {
753
+ if (this.probeTimer || !this.ws || typeof setTimeout !== 'function')
754
+ return;
755
+ const probedWs = this.ws;
756
+ try {
757
+ this.ping();
758
+ }
759
+ catch { }
760
+ const sentAt = Date.now();
761
+ this.probeTimer = setTimeout(() => {
762
+ this.probeTimer = null;
763
+ if (this.ws !== probedWs)
764
+ return;
765
+ // The grace check itself ran far too late: the page was frozen during
766
+ // the grace period, so the reply may still be queued behind this timer.
767
+ // Probe again rather than condemn the socket on frozen time.
768
+ // Decision (beyond the task's letter): this has no retry cap. Under heavy
769
+ // background timer throttling (timers batched to ~1/min in a long-hidden
770
+ // tab) every grace check is late, so the verdict on a dead socket is
771
+ // deferred until the page is visible again, where noteVisible() restarts
772
+ // an unthrottled probe and a dead socket goes ~5 s later. Accepted: a
773
+ // hidden page has no viewer, and a capped retry would reintroduce the
774
+ // false teardown on thaw this probe exists to prevent.
775
+ if (Date.now() - sentAt > 2 * WhereverClient.PROBE_GRACE_MS) {
776
+ this.startLivenessProbe(reason);
777
+ return;
778
+ }
779
+ this.tearDownStaleSocket(reason);
780
+ }, WhereverClient.PROBE_GRACE_MS);
781
+ if (this.probeTimer && typeof this.probeTimer.unref === 'function') {
782
+ this.probeTimer.unref();
783
+ }
784
+ }
785
+ cancelLivenessProbe() {
786
+ if (this.probeTimer) {
787
+ clearTimeout(this.probeTimer);
788
+ this.probeTimer = null;
789
+ }
790
+ }
791
+ // The probe went unanswered: treat the socket as dead. Tearing it down
792
+ // forcibly is what makes a half-open connection recover, since the OS never
793
+ // produced a FIN/RST to trigger the normal close path.
794
+ tearDownStaleSocket(reason) {
795
+ if (!this.ws)
796
+ return;
797
+ const streaming = get(this.stateStore).isStreaming;
798
+ console.warn(`[wherever] relay connection stale: ${reason}; probe unanswered for ` +
799
+ `${WhereverClient.PROBE_GRACE_MS}ms; tearing down dead socket and reconnecting`);
800
+ this.stopLivenessWatchdog();
801
+ const deadWs = this.ws;
802
+ this.ws = null;
803
+ // This path bypasses onClose (the socket is no longer current), so the
804
+ // uploads it carried must be marked waiting here.
805
+ this.uploadsLostSocket();
806
+ try {
807
+ if (typeof deadWs.terminate === 'function') {
808
+ deadWs.terminate();
809
+ }
810
+ else if (typeof deadWs.close === 'function') {
811
+ deadWs.close();
812
+ }
813
+ }
814
+ catch { }
815
+ this.stateStore.update(s => ({
816
+ ...s,
817
+ connected: false,
818
+ connecting: false,
819
+ loadingSession: false,
820
+ creatingSession: false,
821
+ // If a turn was in flight, surface it as a recoverable error so the UI
822
+ // shows "the transport stalled" rather than silently parking mid-stream.
823
+ sessionError: streaming
824
+ ? 'Connection to relay stalled mid-turn; reconnecting...'
825
+ : s.sessionError,
826
+ isStreaming: false,
827
+ }));
828
+ this.scheduleReconnect();
829
+ }
523
830
  stopLivenessWatchdog() {
831
+ this.cancelLivenessProbe();
524
832
  if (this.heartbeatTimer) {
525
833
  clearInterval(this.heartbeatTimer);
526
834
  this.heartbeatTimer = null;
@@ -541,6 +849,7 @@ export class WhereverClient {
541
849
  if (!s.loadingSession && !s.resyncing)
542
850
  return;
543
851
  console.warn('[wherever] session load timed out; clearing loading state');
852
+ this.failHeldUploads('Could not rejoin the session, so the upload was not sent');
544
853
  this.stateStore.update(st => ({
545
854
  ...st,
546
855
  loadingSession: false,
@@ -677,8 +986,15 @@ export class WhereverClient {
677
986
  connecting: false,
678
987
  clientId: msg.clientId,
679
988
  serverVersion: msg.serverVersion ?? null,
989
+ piVersion: msg.piVersion ?? null,
680
990
  error: null,
681
991
  }));
992
+ // Uploads held for unknown capabilities can now choose their protocol
993
+ // (still subject to the rejoin hold).
994
+ this.socketCapabilities = Array.isArray(msg.capabilities)
995
+ ? msg.capabilities.filter((c) => typeof c === 'string')
996
+ : [];
997
+ this.resendPendingUploads();
682
998
  break;
683
999
  case 'connection_superseded':
684
1000
  // A newer connection arrived carrying OUR clientKey, so the server is
@@ -695,22 +1011,15 @@ export class WhereverClient {
695
1011
  console.error('onClientKeyChange failed:', err);
696
1012
  }
697
1013
  break;
698
- case 'file_uploaded': {
699
- const pending = this.pendingUploads.get(msg.uploadId);
700
- if (pending) {
701
- pending.resolve({ savedPath: msg.savedPath, filename: msg.filename });
702
- this.pendingUploads.delete(msg.uploadId);
703
- }
1014
+ case 'file_uploaded':
1015
+ this.completeUpload(msg.uploadId, { savedPath: msg.savedPath, filename: msg.filename });
704
1016
  break;
705
- }
706
- case 'file_upload_error': {
707
- const pending = this.pendingUploads.get(msg.uploadId);
708
- if (pending) {
709
- pending.reject(new Error(msg.error));
710
- this.pendingUploads.delete(msg.uploadId);
711
- }
1017
+ case 'file_upload_error':
1018
+ this.failUpload(msg.uploadId, msg.error);
1019
+ break;
1020
+ case 'upload_offset':
1021
+ this.handleUploadOffset(msg);
712
1022
  break;
713
- }
714
1023
  case 'agent_start':
715
1024
  if (this.agentEndTimeout) {
716
1025
  clearTimeout(this.agentEndTimeout);
@@ -1140,6 +1449,21 @@ export class WhereverClient {
1140
1449
  // This reply matches the load we were waiting on (or the create we
1141
1450
  // requested): the load is resolved, so stop guarding against it.
1142
1451
  this.pendingLoadFile = null;
1452
+ // The server accepted the load: whatever follows (folder_missing, a
1453
+ // failed cold build) comes after an authoritative paint and must keep
1454
+ // the readable-but-blocked view, so it can no longer reject a hydration.
1455
+ this.hydratedFile = null;
1456
+ // The server has now applied this client's write verdict for the
1457
+ // session (it sets readOnly before sending session_created), so uploads
1458
+ // held across the reconnect can go out and be gated correctly.
1459
+ if (this.uploadsHeldForRejoin) {
1460
+ this.uploadsHeldForRejoin = false;
1461
+ // Release only uploads aimed at the session we actually rejoined. A
1462
+ // different session here means the user switched mid-hold; sending the
1463
+ // old target's upload now would be gated by THIS session's verdict.
1464
+ this.failUnsentUploads('The session changed before the upload could be sent', msg.sessionId);
1465
+ this.resendPendingUploads();
1466
+ }
1143
1467
  this.stateStore.update((s) => ({
1144
1468
  ...s,
1145
1469
  session: msg.sessionFile,
@@ -1147,6 +1471,11 @@ export class WhereverClient {
1147
1471
  activeSessionFile: msg.sessionFile,
1148
1472
  activeCwd: msg.cwd,
1149
1473
  activeModel: msg.model,
1474
+ // Stamp the server that delivered this session (ADR 0013).
1475
+ serverKey: this.socketServerKey,
1476
+ // Its message_history follows; until then the paging state in the
1477
+ // store is not this session's.
1478
+ historyAuthoritative: false,
1150
1479
  isStreaming: msg.isStreaming ?? false,
1151
1480
  creatingSession: false,
1152
1481
  // The server forces read-only for sessions in a configured
@@ -1273,6 +1602,9 @@ export class WhereverClient {
1273
1602
  });
1274
1603
  break;
1275
1604
  case 'session_destroyed':
1605
+ if (get(this.stateStore).sessionId === msg.sessionId) {
1606
+ this.failHeldUploads('The session ended before the upload could be sent');
1607
+ }
1276
1608
  this.stateStore.update((s) => {
1277
1609
  if (s.sessionId === msg.sessionId) {
1278
1610
  return {
@@ -1294,7 +1626,24 @@ export class WhereverClient {
1294
1626
  return s;
1295
1627
  });
1296
1628
  break;
1297
- case 'session_error':
1629
+ case 'session_error': {
1630
+ // While held, the only request in flight is the rejoin: it failed, so the
1631
+ // held uploads can never be gated and sent. Fail them now rather than
1632
+ // leaving them (and every new upload) parked for the full timeout.
1633
+ // The rejoin's own errors carry no sessionId (a failed session_load or
1634
+ // its exception path); an error tagged with a session belongs to some
1635
+ // other request and must not fail the held uploads.
1636
+ if (!msg.sessionId) {
1637
+ this.failHeldUploads('Could not rejoin the session, so the upload was not sent');
1638
+ }
1639
+ // The server refused the load of a HYDRATED session outright. Only the
1640
+ // reply to the rejoin's own session_load counts: with no session
1641
+ // attached, the server's catch-all sends EVERY handler error untagged,
1642
+ // so the error must arrive while that load is still the pending one and
1643
+ // before any session_created (which clears hydratedFile).
1644
+ const rejectedHydration = !msg.sessionId &&
1645
+ this.hydratedFile !== null &&
1646
+ this.pendingLoadFile === this.hydratedFile;
1298
1647
  this.stateStore.update((s) => ({
1299
1648
  ...s,
1300
1649
  sessionError: msg.error,
@@ -1307,7 +1656,10 @@ export class WhereverClient {
1307
1656
  // is surfaced. This is the degrade-to-read-only path.
1308
1657
  agentPending: false,
1309
1658
  }));
1659
+ if (rejectedHydration)
1660
+ this.rejectHydration();
1310
1661
  break;
1662
+ }
1311
1663
  case 'folder_missing':
1312
1664
  // The server states, authoritatively, that this session's working folder
1313
1665
  // is not usable -- it does not exist on this machine, or a restore is
@@ -1527,6 +1879,7 @@ export class WhereverClient {
1527
1879
  messages: [...mapped, ...undelivered],
1528
1880
  historyTotalCount: totalCount,
1529
1881
  historyOffset: offset,
1882
+ historyAuthoritative: true,
1530
1883
  loadingMoreHistory: false,
1531
1884
  loadingSession: false,
1532
1885
  resyncing: false,
@@ -1782,6 +2135,10 @@ export class WhereverClient {
1782
2135
  const s = get(this.stateStore);
1783
2136
  if (!s.sessionId)
1784
2137
  return;
2138
+ // The offset may come from the cache or a dropped socket: never page from
2139
+ // it until the server's own history has replaced it.
2140
+ if (!s.historyAuthoritative)
2141
+ return;
1785
2142
  if (s.loadingMoreHistory)
1786
2143
  return;
1787
2144
  if (s.historyOffset <= 0)
@@ -2224,6 +2581,79 @@ export class WhereverClient {
2224
2581
  return s;
2225
2582
  return { ...s, restore: mutate(current) };
2226
2583
  }
2584
+ /**
2585
+ * Paint a conversation from the web's on-device cache before the socket is up
2586
+ * (ADR 0013), so a reload after the OS killed the PWA shows it at once. Call
2587
+ * it, then `connect(cfg, true)`: onOpen's normal rejoin issues the
2588
+ * `session_load` and its `message_history` replaces the cached messages.
2589
+ *
2590
+ * A no-op unless the client holds nothing that could be clobbered: no active
2591
+ * session, no load in flight, not connected. The painted session is
2592
+ * `resyncing` (sending blocked) and NOT `historyAuthoritative`. `agentPending`,
2593
+ * `folderConflict`, `sudoPrompt` and `readOnly` stay at their defaults: they
2594
+ * are verdicts the server re-states on the rejoin. `pendingLoadFile` is NOT
2595
+ * set here (the rejoin sets it when it actually sends the load).
2596
+ *
2597
+ * Delivery-tagged user messages in the snapshot are dropped: undelivered
2598
+ * outbound messages are recovered only from localStorage on the history
2599
+ * reply (`loadPersistedPending`), so a cached copy would double-surface them.
2600
+ */
2601
+ hydrateCachedSession(snapshot) {
2602
+ const s = get(this.stateStore);
2603
+ if (s.activeSessionFile || this.pendingLoadFile !== null || s.connected)
2604
+ return;
2605
+ const messages = snapshot.messages.filter((m) => !(m.role === 'user' && m.delivery !== undefined));
2606
+ this.hydratedFile = snapshot.sessionFile;
2607
+ this.stateStore.update((st) => ({
2608
+ ...st,
2609
+ session: snapshot.sessionFile,
2610
+ sessionId: snapshot.sessionId,
2611
+ activeSessionFile: snapshot.sessionFile,
2612
+ activeCwd: snapshot.cwd,
2613
+ activeModel: snapshot.model,
2614
+ messages,
2615
+ historyTotalCount: snapshot.historyTotalCount ?? messages.length,
2616
+ historyOffset: snapshot.historyOffset ?? 0,
2617
+ historyAuthoritative: false,
2618
+ resyncing: true,
2619
+ isStreaming: false,
2620
+ serverKey: snapshot.serverKey ?? serverKey(this.config),
2621
+ }));
2622
+ }
2623
+ // The server refused the hydrated session's load: clear the cached view (the
2624
+ // session_error reducer already surfaced the error) and tell the listeners,
2625
+ // so the web evicts the record and drops the hash. Synthesized locally; it is
2626
+ // never a server frame.
2627
+ rejectHydration() {
2628
+ const sessionId = get(this.stateStore).sessionId;
2629
+ this.hydratedFile = null;
2630
+ this.pendingLoadFile = null;
2631
+ this.stateStore.update((s) => ({
2632
+ ...s,
2633
+ messages: [],
2634
+ session: null,
2635
+ sessionId: null,
2636
+ activeSessionFile: null,
2637
+ activeCwd: null,
2638
+ activeModel: null,
2639
+ historyTotalCount: 0,
2640
+ historyOffset: 0,
2641
+ historyAuthoritative: false,
2642
+ serverKey: null,
2643
+ resyncing: false,
2644
+ }));
2645
+ if (!sessionId)
2646
+ return;
2647
+ const event = { type: 'hydration_rejected', sessionId };
2648
+ for (const listener of this.listeners) {
2649
+ try {
2650
+ listener(event);
2651
+ }
2652
+ catch (err) {
2653
+ console.error("Error in message listener:", err);
2654
+ }
2655
+ }
2656
+ }
2227
2657
  joinSession(sessionFile, cwd, model) {
2228
2658
  this.stateStore.update((s) => ({
2229
2659
  ...s,
@@ -2255,6 +2685,7 @@ export class WhereverClient {
2255
2685
  if (s.activeSessionFile === sessionFile && !s.loadingSession && !s.resyncing) {
2256
2686
  return;
2257
2687
  }
2688
+ this.abandonUnsentUploads();
2258
2689
  if (s.sessionId) {
2259
2690
  this.send({ type: 'session_leave', sessionId: s.sessionId });
2260
2691
  }
@@ -2285,6 +2716,7 @@ export class WhereverClient {
2285
2716
  this.resumeSessionFile = null;
2286
2717
  this.resumeCwd = undefined;
2287
2718
  this.resumeModel = undefined;
2719
+ this.hydratedFile = null;
2288
2720
  // Switching supersedes any in-flight create; disarm its watchdog so it can't
2289
2721
  // later fire against the newly loaded session.
2290
2722
  this.clearCreateWatchdog();
@@ -2304,6 +2736,7 @@ export class WhereverClient {
2304
2736
  return this.send({ type: 'session_fork', sessionId, entryId });
2305
2737
  }
2306
2738
  createSession(cwd, model, gitInit, createRemote, repoVisibility, cloneRemote) {
2739
+ this.abandonUnsentUploads();
2307
2740
  this.stateStore.update((s) => ({
2308
2741
  ...s,
2309
2742
  folderConflict: null,
@@ -2319,6 +2752,7 @@ export class WhereverClient {
2319
2752
  // be rejected by a stale pendingLoadFile, and a late load reply for the old
2320
2753
  // target must not clobber the new session.
2321
2754
  this.pendingLoadFile = null;
2755
+ this.hydratedFile = null;
2322
2756
  this.send({
2323
2757
  type: 'session_new',
2324
2758
  cwd,
@@ -2333,6 +2767,7 @@ export class WhereverClient {
2333
2767
  this.armCreateWatchdog();
2334
2768
  }
2335
2769
  leaveSession() {
2770
+ this.abandonUnsentUploads();
2336
2771
  const s = get(this.stateStore);
2337
2772
  // Leaving abandons any in-flight create too, so disarm its watchdog even when
2338
2773
  // there is no sessionId yet (a create that has not resolved).
@@ -2369,6 +2804,7 @@ export class WhereverClient {
2369
2804
  }));
2370
2805
  this.clearLoadWatchdog();
2371
2806
  this.pendingLoadFile = null;
2807
+ this.hydratedFile = null;
2372
2808
  this.resumeSessionFile = null;
2373
2809
  this.resumeCwd = undefined;
2374
2810
  this.resumeModel = undefined;
@@ -2542,19 +2978,480 @@ export class WhereverClient {
2542
2978
  this.listeners.delete(cb);
2543
2979
  };
2544
2980
  }
2545
- uploadFileViaWebSocket(sessionId, filename, base64Data) {
2981
+ /**
2982
+ * Upload a file over the WebSocket. Resolves with the server's saved path;
2983
+ * rejects on failure (an `Error`, with `code: 'not_readable'` when the byte
2984
+ * source can no longer be read) or with "Upload cancelled" when
2985
+ * `options.signal` aborts. Progress (`{acked, size, state, error?}`) goes to
2986
+ * `options.onProgress` and to `uploadsStore`.
2987
+ *
2988
+ * The protocol is chosen when the upload is SENT, from that socket's
2989
+ * `connected.capabilities`: chunked (`upload.v1`) when advertised, else the
2990
+ * legacy base64 `file_upload` frame (see PendingUpload). The legacy path
2991
+ * refuses files over 72 MiB from `source.size`, before reading anything.
2992
+ */
2993
+ uploadFileViaWebSocket(sessionId, filename, source, options) {
2546
2994
  return new Promise((resolve, reject) => {
2547
- const uploadId = this.generateId();
2548
- this.pendingUploads.set(uploadId, { resolve, reject });
2549
- this.send({
2550
- type: 'file_upload',
2995
+ const signal = options?.signal;
2996
+ if (signal?.aborted) {
2997
+ options?.onProgress?.({ acked: 0, size: source.size, state: 'aborted' });
2998
+ reject(new Error('Upload cancelled'));
2999
+ return;
3000
+ }
3001
+ const uploadId = generateUploadId();
3002
+ const upload = {
2551
3003
  uploadId,
2552
3004
  sessionId,
2553
3005
  filename,
2554
- data: base64Data
2555
- });
3006
+ mime: options?.mime || undefined,
3007
+ source,
3008
+ onProgress: options?.onProgress,
3009
+ resolve,
3010
+ reject,
3011
+ timer: null,
3012
+ sentOn: null,
3013
+ protocol: null,
3014
+ state: 'queued',
3015
+ acked: 0,
3016
+ frame: null,
3017
+ preparing: false,
3018
+ sends: 0,
3019
+ begun: false,
3020
+ awaitingBegin: false,
3021
+ nextOffset: 0,
3022
+ inFlight: [],
3023
+ realigning: false,
3024
+ finishing: false,
3025
+ reading: false,
3026
+ readGen: 0,
3027
+ rate: null,
3028
+ lastAckAt: 0,
3029
+ };
3030
+ this.pendingUploads.set(uploadId, upload);
3031
+ this.reportUpload(upload);
3032
+ // Cancelling (e.g. the chip was removed) settles the promise and drops
3033
+ // the upload so it is not re-sent on the next reconnect. A chunked upload
3034
+ // the server knows about is told to drop its partial; a legacy frame
3035
+ // already handed to the socket cannot be recalled.
3036
+ signal?.addEventListener('abort', () => this.abortUpload(uploadId), { once: true });
3037
+ // Sent now when the socket is OPEN, its capabilities are known and it is
3038
+ // not mid-rejoin. Otherwise the upload waits in pendingUploads and is
3039
+ // sent once those hold.
3040
+ if (!this.trySendUpload(uploadId))
3041
+ this.ensureUploadTimer(uploadId);
2556
3042
  });
2557
3043
  }
3044
+ // Number of uploads still waiting for a server reply (sent or parked).
3045
+ pendingUploadCount() {
3046
+ return this.pendingUploads.size;
3047
+ }
3048
+ /** Drop a SETTLED upload's entry from uploadsStore (in-flight ones stay). */
3049
+ forgetUpload(uploadId) {
3050
+ if (this.pendingUploads.has(uploadId))
3051
+ return;
3052
+ this.uploadsStore.update((all) => {
3053
+ if (!(uploadId in all))
3054
+ return all;
3055
+ const next = { ...all };
3056
+ delete next[uploadId];
3057
+ return next;
3058
+ });
3059
+ }
3060
+ // Hand the upload to the current socket if it can go now. True when it is on
3061
+ // the wire (or settled: nothing left to wait for), false when it waits.
3062
+ trySendUpload(uploadId) {
3063
+ const upload = this.pendingUploads.get(uploadId);
3064
+ if (!upload || this.uploadsHeldForRejoin)
3065
+ return false;
3066
+ if (!this.ws || this.ws.readyState !== 1 /* OPEN */)
3067
+ return false;
3068
+ // Capabilities unknown: HOLD (see socketCapabilities).
3069
+ if (this.socketCapabilities === null)
3070
+ return false;
3071
+ const chunked = this.socketCapabilities.includes(UPLOAD_CAPABILITY);
3072
+ if (upload.protocol === null)
3073
+ upload.protocol = chunked ? 'chunked' : 'legacy';
3074
+ if (upload.protocol === 'chunked') {
3075
+ if (!chunked) {
3076
+ this.failUpload(uploadId, 'The server no longer supports resumable uploads, retry');
3077
+ return true;
3078
+ }
3079
+ return this.beginChunkedUpload(upload);
3080
+ }
3081
+ return this.sendLegacyUpload(upload);
3082
+ }
3083
+ sendLegacyUpload(upload) {
3084
+ if (upload.sends >= WhereverClient.MAX_UPLOAD_SENDS) {
3085
+ // Every previous attempt lost its socket mid-transfer: stop retrying.
3086
+ this.failUpload(upload.uploadId, 'Upload failed: the connection dropped during the transfer each time (the file may be too large or the connection too slow)');
3087
+ return true;
3088
+ }
3089
+ if (!upload.frame) {
3090
+ // Checked from the size BEFORE reading, so a huge video is never loaded
3091
+ // and encoded just to be refused (and never crashes the tab).
3092
+ if (upload.source.size > WhereverClient.MAX_LEGACY_UPLOAD_BYTES) {
3093
+ this.failUpload(upload.uploadId, 'File too large to upload over the WebSocket (max 72 MB)');
3094
+ return true;
3095
+ }
3096
+ if (!upload.preparing) {
3097
+ upload.preparing = true;
3098
+ this.prepareLegacyFrame(upload);
3099
+ }
3100
+ return false;
3101
+ }
3102
+ if (!this.send(upload.frame))
3103
+ return false;
3104
+ upload.sends++;
3105
+ upload.sentOn = this.ws;
3106
+ // On the wire: stop the waiting clock (transmission time is not bounded).
3107
+ this.stopUploadTimer(upload);
3108
+ this.reportUpload(upload, 'sending');
3109
+ return true;
3110
+ }
3111
+ // Read and base64-encode the whole file once, then send it if still wanted.
3112
+ prepareLegacyFrame(upload) {
3113
+ this.readLegacyBase64(upload.source).then((data) => {
3114
+ if (this.pendingUploads.get(upload.uploadId) !== upload)
3115
+ return;
3116
+ upload.preparing = false;
3117
+ upload.frame = {
3118
+ type: 'file_upload',
3119
+ uploadId: upload.uploadId,
3120
+ sessionId: upload.sessionId,
3121
+ filename: upload.filename,
3122
+ data,
3123
+ };
3124
+ if (!this.trySendUpload(upload.uploadId))
3125
+ this.ensureUploadTimer(upload.uploadId);
3126
+ }, (err) => {
3127
+ if (this.pendingUploads.get(upload.uploadId) !== upload)
3128
+ return;
3129
+ const e = err instanceof UploadReadError ? err : uploadReadError(err);
3130
+ this.failUpload(upload.uploadId, e.message, e.code);
3131
+ });
3132
+ }
3133
+ // base64 over reads of LEGACY_READ_BYTES (a multiple of 3, so no padding in
3134
+ // the middle), platform-neutral (btoa). MAX_UPLOAD_BASE64_CHARS is a
3135
+ // backstop for a source that yields more than its size claimed.
3136
+ async readLegacyBase64(source) {
3137
+ const parts = [];
3138
+ let chars = 0;
3139
+ for (let offset = 0; offset < source.size; offset += LEGACY_READ_BYTES) {
3140
+ const length = Math.min(LEGACY_READ_BYTES, source.size - offset);
3141
+ let bytes;
3142
+ try {
3143
+ bytes = await source.read(offset, length);
3144
+ }
3145
+ catch (err) {
3146
+ throw uploadReadError(err);
3147
+ }
3148
+ chars += 4 * Math.ceil(bytes.length / 3);
3149
+ if (chars > WhereverClient.MAX_UPLOAD_BASE64_CHARS) {
3150
+ throw new UploadReadError('File too large to upload over the WebSocket (max 72 MB)');
3151
+ }
3152
+ if (bytes.length !== length)
3153
+ throw shortReadError();
3154
+ parts.push(btoa(bytesToBinaryString(bytes)));
3155
+ }
3156
+ return parts.join('');
3157
+ }
3158
+ // (Re)start a chunked upload on the current socket: the begin's answer says
3159
+ // where to continue (or that it is already done).
3160
+ beginChunkedUpload(upload) {
3161
+ const sent = this.send({
3162
+ type: 'upload_begin',
3163
+ uploadId: upload.uploadId,
3164
+ sessionId: upload.sessionId,
3165
+ filename: upload.filename,
3166
+ size: upload.source.size,
3167
+ ...(upload.mime ? { mime: upload.mime } : {}),
3168
+ });
3169
+ if (!sent)
3170
+ return false;
3171
+ upload.begun = true;
3172
+ upload.sentOn = this.ws;
3173
+ upload.awaitingBegin = true;
3174
+ upload.inFlight = [];
3175
+ upload.realigning = false;
3176
+ upload.finishing = false;
3177
+ upload.readGen++;
3178
+ // Transmitting: the waiting clock stops (it bounds waiting, not sending).
3179
+ this.stopUploadTimer(upload);
3180
+ this.reportUpload(upload, 'sending');
3181
+ return true;
3182
+ }
3183
+ // `upload_offset`: the server's offset for a chunked upload, answering a begin
3184
+ // or a chunk. Progress is ONLY ever this value, never what was sent.
3185
+ handleUploadOffset(msg) {
3186
+ const upload = this.pendingUploads.get(msg.uploadId);
3187
+ if (!upload || upload.protocol !== 'chunked' || !this.isUploadOnWire(upload))
3188
+ return;
3189
+ if (msg.done) {
3190
+ this.completeUpload(upload.uploadId, { savedPath: msg.savedPath, filename: upload.filename });
3191
+ return;
3192
+ }
3193
+ const offset = msg.offset;
3194
+ const size = upload.source.size;
3195
+ if (!Number.isSafeInteger(offset) || offset < 0 || offset > size)
3196
+ return;
3197
+ const now = Date.now();
3198
+ if (upload.awaitingBegin) {
3199
+ upload.awaitingBegin = false;
3200
+ upload.nextOffset = offset;
3201
+ upload.lastAckAt = now;
3202
+ }
3203
+ else {
3204
+ const chunk = upload.inFlight.shift();
3205
+ if (!chunk)
3206
+ return; // nothing of ours is awaiting an answer
3207
+ if (!upload.realigning && offset === chunk.offset + chunk.length) {
3208
+ // Time this chunk from when it could start being serviced: its send, or
3209
+ // the previous ack if it was queued behind that one.
3210
+ const elapsed = Math.max(1, now - Math.max(chunk.sentAt, upload.lastAckAt));
3211
+ const sample = chunk.length / elapsed;
3212
+ upload.rate =
3213
+ upload.rate === null ? sample : upload.rate * (1 - UPLOAD_RATE_ALPHA) + sample * UPLOAD_RATE_ALPHA;
3214
+ upload.lastAckAt = now;
3215
+ }
3216
+ else if (!upload.realigning) {
3217
+ // Out of step with the server: discard any read meant for the old
3218
+ // position and wait for the rest of the in-flight acks.
3219
+ upload.realigning = true;
3220
+ upload.readGen++;
3221
+ }
3222
+ if (upload.realigning && upload.inFlight.length === 0) {
3223
+ upload.realigning = false;
3224
+ upload.nextOffset = offset;
3225
+ upload.lastAckAt = now;
3226
+ }
3227
+ }
3228
+ upload.acked = offset;
3229
+ this.reportUpload(upload);
3230
+ this.pumpUpload(upload);
3231
+ }
3232
+ uploadWindow(upload) {
3233
+ if (upload.rate === null)
3234
+ return UPLOAD_WINDOW_MIN;
3235
+ const bytes = upload.rate * 1000 * UPLOAD_WINDOW_SECONDS;
3236
+ return Math.min(UPLOAD_WINDOW_MAX, Math.max(UPLOAD_WINDOW_MIN, Math.floor(bytes)));
3237
+ }
3238
+ // Send the next chunk if the window allows, or finish once every byte is
3239
+ // acked. One source read at a time; each completed send pumps again.
3240
+ pumpUpload(upload) {
3241
+ if (this.pendingUploads.get(upload.uploadId) !== upload)
3242
+ return;
3243
+ if (upload.reading || upload.awaitingBegin || upload.realigning || upload.finishing)
3244
+ return;
3245
+ if (!this.isUploadOnWire(upload))
3246
+ return;
3247
+ const size = upload.source.size;
3248
+ if (upload.acked === size && upload.inFlight.length === 0) {
3249
+ if (!this.send({ type: 'upload_finish', uploadId: upload.uploadId, sessionId: upload.sessionId }))
3250
+ return;
3251
+ upload.finishing = true;
3252
+ this.reportUpload(upload, 'finishing');
3253
+ return;
3254
+ }
3255
+ if (upload.nextOffset >= size)
3256
+ return;
3257
+ const window = this.uploadWindow(upload);
3258
+ const length = Math.min(window, UPLOAD_CHUNK_MAX, size - upload.nextOffset);
3259
+ const inFlightBytes = upload.inFlight.reduce((n, c) => n + c.length, 0);
3260
+ if (inFlightBytes + length > window)
3261
+ return;
3262
+ const offset = upload.nextOffset;
3263
+ const gen = upload.readGen;
3264
+ const socket = this.ws;
3265
+ upload.reading = true;
3266
+ Promise.resolve()
3267
+ .then(() => upload.source.read(offset, length))
3268
+ .then((bytes) => {
3269
+ if (this.pendingUploads.get(upload.uploadId) !== upload)
3270
+ return;
3271
+ upload.reading = false;
3272
+ // The socket or the alignment changed while reading: drop the bytes.
3273
+ if (gen !== upload.readGen || socket !== this.ws || !this.isUploadOnWire(upload)) {
3274
+ this.pumpUpload(upload);
3275
+ return;
3276
+ }
3277
+ if (bytes.length !== length) {
3278
+ const e = shortReadError();
3279
+ this.failUpload(upload.uploadId, e.message, e.code);
3280
+ return;
3281
+ }
3282
+ // A socket that refuses the frame is closing; its close handler
3283
+ // pauses the upload.
3284
+ if (!this.sendBinary(encodeChunkFrame(upload.uploadId, offset, bytes)))
3285
+ return;
3286
+ upload.inFlight.push({ offset, length, sentAt: Date.now() });
3287
+ upload.nextOffset = offset + length;
3288
+ this.pumpUpload(upload);
3289
+ }, (err) => {
3290
+ if (this.pendingUploads.get(upload.uploadId) !== upload)
3291
+ return;
3292
+ const e = uploadReadError(err);
3293
+ this.failUpload(upload.uploadId, e.message, e.code);
3294
+ });
3295
+ }
3296
+ sendBinary(bytes) {
3297
+ if (this.ws && this.ws.readyState === 1 /* OPEN */) {
3298
+ try {
3299
+ this.ws.send(bytes);
3300
+ return true;
3301
+ }
3302
+ catch {
3303
+ return false;
3304
+ }
3305
+ }
3306
+ return false;
3307
+ }
3308
+ // Record (and announce) an upload's progress. `state` defaults to the current.
3309
+ reportUpload(upload, state, error) {
3310
+ if (state)
3311
+ upload.state = state;
3312
+ const progress = {
3313
+ acked: upload.acked,
3314
+ size: upload.source.size,
3315
+ state: upload.state,
3316
+ ...(error ? { error } : {}),
3317
+ };
3318
+ this.uploadsStore.update((all) => ({ ...all, [upload.uploadId]: progress }));
3319
+ if (upload.onProgress) {
3320
+ try {
3321
+ upload.onProgress({ ...progress });
3322
+ }
3323
+ catch (err) {
3324
+ console.error('Upload onProgress failed:', err);
3325
+ }
3326
+ }
3327
+ }
3328
+ completeUpload(uploadId, result) {
3329
+ const upload = this.takePendingUpload(uploadId);
3330
+ if (!upload)
3331
+ return;
3332
+ upload.acked = upload.source.size;
3333
+ this.reportUpload(upload, 'done');
3334
+ upload.resolve(result);
3335
+ }
3336
+ failUpload(uploadId, message, code) {
3337
+ const upload = this.takePendingUpload(uploadId);
3338
+ if (!upload)
3339
+ return;
3340
+ const err = new Error(message);
3341
+ if (code)
3342
+ err.code = code;
3343
+ this.reportUpload(upload, 'failed', code ? { message, code } : { message });
3344
+ upload.reject(err);
3345
+ }
3346
+ abortUpload(uploadId) {
3347
+ const upload = this.takePendingUpload(uploadId);
3348
+ if (!upload)
3349
+ return;
3350
+ // Best effort: with no open socket the partial is left to the server's GC.
3351
+ if (upload.protocol === 'chunked' && upload.begun) {
3352
+ this.send({ type: 'upload_abort', uploadId, sessionId: upload.sessionId });
3353
+ }
3354
+ this.reportUpload(upload, 'aborted');
3355
+ upload.reject(new Error('Upload cancelled'));
3356
+ }
3357
+ isUploadOnWire(pending) {
3358
+ return pending.sentOn !== null && pending.sentOn === this.ws;
3359
+ }
3360
+ // The socket carrying uploads went away (by close, suspend, or the liveness
3361
+ // teardown, the latter two bypassing onClose). Every upload is waiting again:
3362
+ // forget where it was sent, pause it, and restart its waiting clock, so no
3363
+ // upload can be left without a timer. A chunked upload forgets its in-flight
3364
+ // chunks: the next begin tells it what the server really has.
3365
+ uploadsLostSocket() {
3366
+ for (const [id, upload] of this.pendingUploads) {
3367
+ const wasOnWire = upload.sentOn !== null;
3368
+ upload.sentOn = null;
3369
+ if (upload.protocol === 'chunked') {
3370
+ upload.awaitingBegin = false;
3371
+ upload.inFlight = [];
3372
+ upload.realigning = false;
3373
+ upload.finishing = false;
3374
+ upload.readGen++;
3375
+ }
3376
+ if (wasOnWire && upload.state !== 'paused')
3377
+ this.reportUpload(upload, 'paused');
3378
+ // Arm only a clock that is not already running. Re-arming on every loss
3379
+ // restarted the deadline on each failed reconnect attempt (at most 15 s
3380
+ // apart), so an upload against an unreachable server waited forever.
3381
+ this.ensureUploadTimer(id);
3382
+ }
3383
+ }
3384
+ // Fail uploads that have not reached the current socket (parked or held),
3385
+ // optionally sparing those aimed at `keepSessionId`.
3386
+ failUnsentUploads(reason, keepSessionId) {
3387
+ for (const [id, upload] of [...this.pendingUploads]) {
3388
+ if (this.isUploadOnWire(upload))
3389
+ continue;
3390
+ if (keepSessionId && upload.sessionId === keepSessionId)
3391
+ continue;
3392
+ this.failUpload(id, reason);
3393
+ }
3394
+ }
3395
+ failHeldUploads(reason) {
3396
+ if (!this.uploadsHeldForRejoin)
3397
+ return;
3398
+ this.uploadsHeldForRejoin = false;
3399
+ this.failUnsentUploads(reason);
3400
+ }
3401
+ // Switching / creating / leaving a session: an upload not yet on the wire
3402
+ // would otherwise be released by the NEXT session's session_created and be
3403
+ // gated by the wrong session's verdict. One already on the wire is left to
3404
+ // its reply (the server answers on this socket regardless of attachment).
3405
+ abandonUnsentUploads() {
3406
+ this.uploadsHeldForRejoin = false;
3407
+ this.failUnsentUploads('The session changed before the upload could be sent');
3408
+ }
3409
+ // Start the waiting clock unless one is already running (keeps the deadline).
3410
+ ensureUploadTimer(uploadId) {
3411
+ const pending = this.pendingUploads.get(uploadId);
3412
+ if (pending && !pending.timer)
3413
+ this.armUploadTimer(uploadId);
3414
+ }
3415
+ stopUploadTimer(upload) {
3416
+ if (upload.timer)
3417
+ clearTimeout(upload.timer);
3418
+ upload.timer = null;
3419
+ }
3420
+ armUploadTimer(uploadId) {
3421
+ const pending = this.pendingUploads.get(uploadId);
3422
+ if (!pending || typeof setTimeout !== 'function')
3423
+ return;
3424
+ if (pending.timer)
3425
+ clearTimeout(pending.timer);
3426
+ pending.timer = setTimeout(() => {
3427
+ this.failUpload(uploadId, 'Upload timed out (no connection to the server)');
3428
+ }, WhereverClient.UPLOAD_TIMEOUT_MS);
3429
+ if (pending.timer && typeof pending.timer.unref === 'function') {
3430
+ pending.timer.unref();
3431
+ }
3432
+ }
3433
+ takePendingUpload(uploadId) {
3434
+ const pending = this.pendingUploads.get(uploadId);
3435
+ if (!pending)
3436
+ return undefined;
3437
+ this.pendingUploads.delete(uploadId);
3438
+ if (pending.timer)
3439
+ clearTimeout(pending.timer);
3440
+ return pending;
3441
+ }
3442
+ resendPendingUploads() {
3443
+ for (const [id, pending] of [...this.pendingUploads]) {
3444
+ if (this.isUploadOnWire(pending))
3445
+ continue;
3446
+ if (!this.trySendUpload(id))
3447
+ this.ensureUploadTimer(id);
3448
+ }
3449
+ }
3450
+ rejectPendingUploads(reason) {
3451
+ for (const id of [...this.pendingUploads.keys()]) {
3452
+ this.failUpload(id, reason);
3453
+ }
3454
+ }
2558
3455
  generateId() {
2559
3456
  return Math.random().toString(36).substring(2) + Date.now().toString(36);
2560
3457
  }