@wherever-dev/client 0.8.2 → 0.9.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.
package/dist/types.d.ts CHANGED
@@ -1,6 +1,18 @@
1
+ /**
2
+ * A tool image. Live (`tool_end`) images always carry base64 `data`. In
3
+ * `message_history` a large image may come BY REFERENCE (this client asks for
4
+ * that with `imageRefs=1`): no `data`; instead its decoded size (`bytes`) and
5
+ * its address (`toolCallId`, `entryId`, `index`), fetched from
6
+ * `GET /session/tool-image?sessionId&toolCallId&entryId&index`.
7
+ */
1
8
  export interface ToolImage {
2
9
  mimeType: string;
3
- data: string;
10
+ data?: string;
11
+ bytes?: number;
12
+ toolCallId?: string;
13
+ /** The transcript entry holding the image (sent alongside `toolCallId`). */
14
+ entryId?: string;
15
+ index?: number;
4
16
  }
5
17
  export interface ChatMessage {
6
18
  id: string;
package/dist/types.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA2VA,8EAA8E;AAC9E,oEAAoE;AACpE,EAAE;AACF,0EAA0E;AAC1E,iEAAiE;AACjE,oCAAoC;AACpC,8EAA8E;AAC9E,4CAA4C;AAC5C,oFAAoF;AACpF,8EAA8E;AAC9E,+EAA+E;AAC/E,4EAA4E;AAC5E,iCAAiC;AACjC,MAAM,UAAU,oBAAoB,CACnC,OAAe;IAEf,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IACpC,gDAAgD;IAChD,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;IAC7D,IAAI,IAAI,EAAE,CAAC;QACV,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAC7C,IAAI,QAAQ,KAAK,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QACjC,OAAO;YACN,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;YAClB,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE;SACxD,CAAC;IACH,CAAC;IACD,yEAAyE;IACzE,IAAI,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,SAAS,GAAG,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QACnE,IAAI,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC;QAC5B,MAAM,IAAI,GAAG,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACpE,OAAO,EAAC,SAAS,EAAE,IAAI,EAAC,CAAC;IAC1B,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED,iFAAiF;AACjF,iFAAiF;AACjF,kEAAkE;AAClE,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACtD,MAAM,MAAM,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,OAAO,SAAS,MAAM,CAAC,SAAS,SAAS,MAAM,CAAC,IAAI,EAAE,CAAC;AACxD,CAAC"}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAuWA,8EAA8E;AAC9E,oEAAoE;AACpE,EAAE;AACF,0EAA0E;AAC1E,iEAAiE;AACjE,oCAAoC;AACpC,8EAA8E;AAC9E,4CAA4C;AAC5C,oFAAoF;AACpF,8EAA8E;AAC9E,+EAA+E;AAC/E,4EAA4E;AAC5E,iCAAiC;AACjC,MAAM,UAAU,oBAAoB,CACnC,OAAe;IAEf,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IACpC,gDAAgD;IAChD,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;IAC7D,IAAI,IAAI,EAAE,CAAC;QACV,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAC7C,IAAI,QAAQ,KAAK,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QACjC,OAAO;YACN,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;YAClB,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE;SACxD,CAAC;IACH,CAAC;IACD,yEAAyE;IACzE,IAAI,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,SAAS,GAAG,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QACnE,IAAI,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC;QAC5B,MAAM,IAAI,GAAG,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACpE,OAAO,EAAC,SAAS,EAAE,IAAI,EAAC,CAAC;IAC1B,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED,iFAAiF;AACjF,iFAAiF;AACjF,kEAAkE;AAClE,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACtD,MAAM,MAAM,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,OAAO,SAAS,MAAM,CAAC,SAAS,SAAS,MAAM,CAAC,IAAI,EAAE,CAAC;AACxD,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wherever-dev/client",
3
- "version": "0.8.2",
3
+ "version": "0.9.1",
4
4
  "description": "Framework-agnostic TypeScript client (browser and Node.js) for the Wherever server's pi coding agent WebSocket API",
5
5
  "keywords": [
6
6
  "wherever",
package/src/client.ts CHANGED
@@ -11,6 +11,7 @@ import {
11
11
  type WhereverState,
12
12
  skillInvocationIdentity,
13
13
  } from "./types.js";
14
+ import { FrameReassembler, FRAME_CHUNK_PARAM, FRAME_CHUNK_VERSION } from "./frame-chunks.js";
14
15
 
15
16
  /**
16
17
  * Per-send options for a user message.
@@ -50,6 +51,11 @@ export interface WhereverClientConfig {
50
51
  // wherever `clientKey` came from, so the collision is resolved for good rather
51
52
  // than re-created on the next reconnect.
52
53
  onClientKeyChange?: (key: string) => void;
54
+ // Ask for large `message_history` tool images BY REFERENCE (`imageRefs=1`):
55
+ // they then arrive without `data`, and the app must load them from
56
+ // `GET /session/tool-image` (see ToolImage). Off by default, so a consumer
57
+ // that renders `img.data` keeps getting it; the web app turns it on.
58
+ imageRefs?: boolean;
53
59
  }
54
60
 
55
61
  // Per-instance fallback identity: stable for the lifetime of this client object,
@@ -386,6 +392,29 @@ export class WhereverClient {
386
392
  // null means "accept any" (e.g. session_new, whose target file is not known
387
393
  // until the reply). The latest tap always wins.
388
394
  private pendingLoadFile: string | null = null;
395
+ // A session request (load or create) the user made while the socket was not
396
+ // open, so its frame could not be sent. It is the user's newest intent and so
397
+ // supersedes the automatic rejoin: onOpen replays it INSTEAD of rejoining the
398
+ // previously-active session. Without this, switching away from a session that
399
+ // was still reconnecting (PWA brought back to the foreground) lost the switch
400
+ // and the rejoin pulled the user back to the old session. Cleared by a leave,
401
+ // a full disconnect, a server-key wipe, the request's watchdog expiring
402
+ // while still armed, or the replay itself. A socket that closes before
403
+ // opening disarms that watchdog without dropping the request, so it is then
404
+ // replayed on a later socket: it is still the user's latest intent.
405
+ private queuedSessionRequest:
406
+ | {type: 'load'; sessionFile: string; cwd?: string; model?: string}
407
+ | {type: 'create'; frame: Record<string, unknown>}
408
+ | null = null;
409
+ // Session files and ids of loads the user moved away from while their reply
410
+ // was still on the wire on THIS socket (a rejoin, a slow load). Their late
411
+ // session_created / message_history are dropped even when nothing else would
412
+ // reject them: a session_new in flight accepts any session_created (its file
413
+ // is unknown until the reply), so a late rejoin reply used to be taken for the
414
+ // new session's and switch the view back. Reset on every new socket (the old
415
+ // socket's replies can no longer arrive), and an entry is removed when the
416
+ // user loads that session again.
417
+ private abandonedSessions = new Set<string>();
389
418
  // serverKey(config) of the socket currently open (captured by connect() next
390
419
  // to the socket it opens). session_created stamps it on the store, so the
391
420
  // stamp names the server that actually DELIVERED the session even if the
@@ -490,6 +519,7 @@ export class WhereverClient {
490
519
  this.resumeModel = undefined;
491
520
  this.pendingLoadFile = null;
492
521
  this.hydratedFile = null;
522
+ this.queuedSessionRequest = null;
493
523
  }
494
524
  this.socketServerKey = key;
495
525
 
@@ -514,6 +544,14 @@ export class WhereverClient {
514
544
  const params: string[] = [];
515
545
  if (this.config.token) params.push(`token=${encodeURIComponent(this.config.token)}`);
516
546
  params.push(`clientKey=${encodeURIComponent(this.clientKey)}`);
547
+ // Ask the server to split large frames (frame-chunks.ts): a multi-MB history
548
+ // arriving as ONE frame over a slow link looked like a dead socket to the
549
+ // liveness watchdog, which tore it down and looped forever.
550
+ params.push(`${FRAME_CHUNK_PARAM}=${FRAME_CHUNK_VERSION}`);
551
+ // History tool images by reference (fetched lazily, cached by the browser)
552
+ // rather than as base64 re-sent on every load and reconnect. Opt-in: the
553
+ // caller must then render images that have no `data`.
554
+ if (this.config.imageRefs) params.push('imageRefs=1');
517
555
  const wsUrl = `${protocol}://${host}:${this.config.port}/ws?${params.join('&')}`;
518
556
 
519
557
  const WebSocketImpl = this.config.WebSocketCtor || (typeof globalThis !== 'undefined' ? (globalThis as any).WebSocket : null);
@@ -544,6 +582,10 @@ export class WhereverClient {
544
582
  }
545
583
 
546
584
  const currentWs = this.ws;
585
+ const reassembler = new FrameReassembler();
586
+ // One warning per run of bad chunks: after one, every remaining chunk of
587
+ // that message is invalid too.
588
+ let inBadChunkRun = false;
547
589
 
548
590
  const onOpen = () => {
549
591
  if (this.ws !== currentWs) return;
@@ -554,6 +596,8 @@ export class WhereverClient {
554
596
  this.reconnectAttempts = 0;
555
597
  this.reconnectDelay = WhereverClient.MIN_RECONNECT_DELAY;
556
598
  this.isInitialConnect = false;
599
+ // Replies to loads issued on an earlier socket can no longer arrive.
600
+ this.abandonedSessions.clear();
557
601
  this.startLivenessWatchdog();
558
602
  this.stateStore.update(s => ({
559
603
  ...s,
@@ -578,6 +622,50 @@ export class WhereverClient {
578
622
  // 2. the store's activeSessionFile -> an UNSOLICITED drop (network
579
623
  // blip, tab switch, laptop sleep, half-open reap) where suspend()
580
624
  // never ran. This is the case that used to silently freeze.
625
+ //
626
+ // A session request the user made while the socket was down (a switch or
627
+ // a create, see queuedSessionRequest) is newer than any rejoin, so it is
628
+ // sent instead and nothing is rejoined.
629
+ let queued = this.queuedSessionRequest;
630
+ this.queuedSessionRequest = null;
631
+ // A queued load of the session we would rejoin anyway (reloadSession()
632
+ // while disconnected) IS the rejoin: take that path, which keeps held
633
+ // uploads and the resyncing affordance.
634
+ if (
635
+ queued?.type === 'load' &&
636
+ queued.sessionFile === (this.resumeSessionFile ?? get(this.stateStore).activeSessionFile)
637
+ ) {
638
+ queued = null;
639
+ }
640
+ if (queued) {
641
+ this.resumeSessionFile = null;
642
+ this.resumeCwd = undefined;
643
+ this.resumeModel = undefined;
644
+ this.uploadsHeldForRejoin = false;
645
+ this.rejectPendingUploads('The session changed before the upload could be sent');
646
+ if (queued.type === 'load') {
647
+ this.stateStore.update(s => ({...s, loadingSession: true, resyncing: false}));
648
+ this.pendingLoadFile = queued.sessionFile;
649
+ this.send({
650
+ type: 'session_load',
651
+ sessionFile: queued.sessionFile,
652
+ cwd: queued.cwd,
653
+ model: queued.model,
654
+ });
655
+ this.armLoadWatchdog();
656
+ } else {
657
+ this.stateStore.update(s => ({
658
+ ...s,
659
+ creatingSession: true,
660
+ loadingSession: false,
661
+ resyncing: false,
662
+ }));
663
+ this.pendingLoadFile = null;
664
+ this.send(queued.frame);
665
+ this.armCreateWatchdog();
666
+ }
667
+ return;
668
+ }
581
669
  const cached = get(this.stateStore);
582
670
  const rejoinFile = this.resumeSessionFile ?? cached.activeSessionFile;
583
671
  const rejoinCwd =
@@ -629,7 +717,20 @@ export class WhereverClient {
629
717
  this.cancelLivenessProbe();
630
718
  try {
631
719
  const rawData = typeof event.data === 'string' ? event.data : event.data.toString();
632
- const msg = JSON.parse(rawData);
720
+ const piece = reassembler.push(rawData);
721
+ if (piece.kind !== 'invalid') inBadChunkRun = false;
722
+ if (piece.kind === 'partial') {
723
+ // A large frame is still arriving: the load it answers is making
724
+ // progress, so it must not time out meanwhile.
725
+ if (this.loadWatchdog) this.armLoadWatchdog();
726
+ return;
727
+ }
728
+ if (piece.kind === 'invalid') {
729
+ if (!inBadChunkRun) console.warn('[wherever] dropped a malformed or incomplete chunked frame');
730
+ inBadChunkRun = true;
731
+ return;
732
+ }
733
+ const msg = JSON.parse(piece.text);
633
734
  this.handleMessage(msg);
634
735
  } catch (err) {
635
736
  console.error("Failed to parse WebSocket message:", err);
@@ -740,6 +841,8 @@ export class WhereverClient {
740
841
  this.rejectPendingUploads('Disconnected before the upload completed');
741
842
  this.uploadsHeldForRejoin = false;
742
843
  this.hydratedFile = null;
844
+ this.queuedSessionRequest = null;
845
+ this.abandonedSessions.clear();
743
846
  this.stateStore.set({
744
847
  ...defaultState,
745
848
  hideThinking: !!this.config.hideThinking,
@@ -1024,6 +1127,7 @@ export class WhereverClient {
1024
1127
  this.loadWatchdog = setTimeout(() => {
1025
1128
  this.loadWatchdog = null;
1026
1129
  const s = get(this.stateStore);
1130
+ if (this.queuedSessionRequest?.type === 'load') this.queuedSessionRequest = null;
1027
1131
  if (!s.loadingSession && !s.resyncing) return;
1028
1132
  console.warn('[wherever] session load timed out; clearing loading state');
1029
1133
  this.failHeldUploads('Could not rejoin the session, so the upload was not sent');
@@ -1056,6 +1160,8 @@ export class WhereverClient {
1056
1160
  this.createWatchdog = setTimeout(() => {
1057
1161
  this.createWatchdog = null;
1058
1162
  const s = get(this.stateStore);
1163
+ // The user was told it failed: a later reconnect must not create it anyway.
1164
+ if (this.queuedSessionRequest?.type === 'create') this.queuedSessionRequest = null;
1059
1165
  if (!s.creatingSession) return;
1060
1166
  console.warn('[wherever] session create timed out; clearing creating state');
1061
1167
  this.stateStore.update(st => ({
@@ -1159,6 +1265,7 @@ export class WhereverClient {
1159
1265
  // initial load has no sessionId yet, so its history still resolves.
1160
1266
  const active = get(this.stateStore).sessionId;
1161
1267
  if (active && msg.sessionId && msg.sessionId !== active) break;
1268
+ if (msg.sessionId && this.abandonedSessions.has(msg.sessionId)) break;
1162
1269
  this.clearLoadWatchdog();
1163
1270
  break;
1164
1271
  }
@@ -1716,10 +1823,22 @@ export class WhereverClient {
1716
1823
  msg.sessionId === this.pendingLoadFile);
1717
1824
  const isRequestedCreate =
1718
1825
  this.pendingLoadFile === null && st.creatingSession;
1719
- if (!matchesPendingLoad && !isRequestedCreate) {
1826
+ // A load the user moved away from (e.g. the rejoin still in flight
1827
+ // when they created a new session) is never the create's reply.
1828
+ const abandoned =
1829
+ this.abandonedSessions.has(msg.sessionFile) ||
1830
+ this.abandonedSessions.has(msg.sessionId);
1831
+ if (!matchesPendingLoad && (!isRequestedCreate || abandoned)) {
1832
+ // Its message_history follows: drop that too, unless it is the
1833
+ // session already on screen.
1834
+ if (msg.sessionId && msg.sessionId !== st.sessionId) {
1835
+ this.abandonedSessions.add(msg.sessionId);
1836
+ }
1720
1837
  break;
1721
1838
  }
1722
1839
  }
1840
+ this.abandonedSessions.delete(msg.sessionFile);
1841
+ this.abandonedSessions.delete(msg.sessionId);
1723
1842
  // This reply matches the load we were waiting on (or the create we
1724
1843
  // requested): the load is resolved, so stop guarding against it.
1725
1844
  this.pendingLoadFile = null;
@@ -2134,6 +2253,11 @@ export class WhereverClient {
2134
2253
  if (active && msg.sessionId && msg.sessionId !== active) {
2135
2254
  break;
2136
2255
  }
2256
+ // Or for a load the user abandoned, arriving before the new target's
2257
+ // own session_created (so no active sessionId guards it yet).
2258
+ if (msg.sessionId && this.abandonedSessions.has(msg.sessionId)) {
2259
+ break;
2260
+ }
2137
2261
  }
2138
2262
  // The server transcript is authoritative for what was actually persisted.
2139
2263
  // Reconcile it against any unconfirmed outbound messages: keep the ones
@@ -2990,11 +3114,48 @@ export class WhereverClient {
2990
3114
  loadingSession: true,
2991
3115
  agentPending: false,
2992
3116
  }));
3117
+ this.abandonPendingLoad(sessionFile);
2993
3118
  this.pendingLoadFile = sessionFile;
2994
- this.send({type: 'session_load', sessionFile, cwd, model});
3119
+ this.sendSessionLoad(sessionFile, cwd, model);
2995
3120
  this.armLoadWatchdog();
2996
3121
  }
2997
3122
 
3123
+ // The in-flight load (if any) is being superseded by a new request: remember
3124
+ // it so its late reply is dropped (see abandonedSessions). `next` is the load
3125
+ // replacing it, which must not be dropped even if it was abandoned before.
3126
+ private abandonPendingLoad(next?: string, {keepShownSession = false} = {}) {
3127
+ if (this.pendingLoadFile && this.pendingLoadFile !== next) {
3128
+ this.abandonedSessions.add(this.pendingLoadFile);
3129
+ }
3130
+ // A load whose session_created was accepted but whose message_history is
3131
+ // still arriving (a rejoin's multi-MB history can take seconds, exactly
3132
+ // while the user is most likely to tap away): pendingLoadFile is already
3133
+ // null, so remember its sessionId instead, or its history would paint over
3134
+ // the next target and disarm that target's watchdog.
3135
+ // keepShownSession: a bare create (composer `/new`) keeps showing the
3136
+ // current session until the new one's session_created, after which the
3137
+ // active-id guard drops its history anyway; abandoning it here would only
3138
+ // blank it if the create then failed.
3139
+ const s = get(this.stateStore);
3140
+ if (
3141
+ !keepShownSession &&
3142
+ s.sessionId &&
3143
+ !s.historyAuthoritative &&
3144
+ s.activeSessionFile !== next &&
3145
+ s.sessionId !== next
3146
+ ) {
3147
+ this.abandonedSessions.add(s.sessionId);
3148
+ }
3149
+ if (next) this.abandonedSessions.delete(next);
3150
+ }
3151
+
3152
+ // Send a user-requested session_load, or queue it for the next open socket
3153
+ // when there is none (see queuedSessionRequest).
3154
+ private sendSessionLoad(sessionFile: string, cwd?: string, model?: string) {
3155
+ const sent = this.send({type: 'session_load', sessionFile, cwd, model});
3156
+ this.queuedSessionRequest = sent ? null : {type: 'load', sessionFile, cwd, model};
3157
+ }
3158
+
2998
3159
  // Switch from the currently-active session (if any) straight to another one in
2999
3160
  // a single, atomic step. Leaving + loading used to be done by the UI as two
3000
3161
  // calls separated by a 100ms setTimeout; that gap could strand the loading
@@ -3014,6 +3175,8 @@ export class WhereverClient {
3014
3175
  if (s.sessionId) {
3015
3176
  this.send({type: 'session_leave', sessionId: s.sessionId});
3016
3177
  }
3178
+ // Before the reset below, which forgets the session being left.
3179
+ this.abandonPendingLoad(sessionFile);
3017
3180
  // Reset to a clean loading state for the target session in one update so the
3018
3181
  // old conversation clears immediately and the spinner reflects the new load.
3019
3182
  this.stateStore.update((st: WhereverState) => ({
@@ -3046,7 +3209,7 @@ export class WhereverClient {
3046
3209
  // later fire against the newly loaded session.
3047
3210
  this.clearCreateWatchdog();
3048
3211
  this.pendingLoadFile = sessionFile;
3049
- this.send({type: 'session_load', sessionFile, cwd, model});
3212
+ this.sendSessionLoad(sessionFile, cwd, model);
3050
3213
  this.armLoadWatchdog();
3051
3214
  }
3052
3215
 
@@ -3084,9 +3247,14 @@ export class WhereverClient {
3084
3247
  // A new session supersedes any in-flight load: its session_created must not
3085
3248
  // be rejected by a stale pendingLoadFile, and a late load reply for the old
3086
3249
  // target must not clobber the new session.
3250
+ this.abandonPendingLoad(undefined, {keepShownSession: true});
3087
3251
  this.pendingLoadFile = null;
3088
3252
  this.hydratedFile = null;
3089
- this.send({
3253
+ // A create supersedes any rejoin the next socket would otherwise make.
3254
+ this.resumeSessionFile = null;
3255
+ this.resumeCwd = undefined;
3256
+ this.resumeModel = undefined;
3257
+ const frame = {
3090
3258
  type: 'session_new',
3091
3259
  cwd,
3092
3260
  model,
@@ -3094,7 +3262,8 @@ export class WhereverClient {
3094
3262
  createRemote,
3095
3263
  repoVisibility,
3096
3264
  cloneRemote,
3097
- });
3265
+ };
3266
+ this.queuedSessionRequest = this.send(frame) ? null : {type: 'create', frame};
3098
3267
  // Never let the blocking "Creating session..." overlay hang if the reply is
3099
3268
  // lost. Symmetrical with armLoadWatchdog for session_load.
3100
3269
  this.armCreateWatchdog();
@@ -3106,7 +3275,14 @@ export class WhereverClient {
3106
3275
  // Leaving abandons any in-flight create too, so disarm its watchdog even when
3107
3276
  // there is no sessionId yet (a create that has not resolved).
3108
3277
  this.clearCreateWatchdog();
3109
- if (!s.sessionId) {
3278
+ // Leaving cancels whatever would otherwise (re)attach a session later: a
3279
+ // request queued while the socket was down, the rejoin of the session being
3280
+ // left, and the reply of a load still in flight. Done even with no
3281
+ // sessionId yet (a load or rejoin that has not resolved), since that is
3282
+ // exactly when a late reply would pull the user back.
3283
+ this.queuedSessionRequest = null;
3284
+ this.abandonPendingLoad();
3285
+ if (!s.sessionId && !s.activeSessionFile && this.pendingLoadFile === null && !this.resumeSessionFile) {
3110
3286
  if (s.creatingSession) {
3111
3287
  this.stateStore.update((st: WhereverState) => ({
3112
3288
  ...st,
@@ -3115,7 +3291,7 @@ export class WhereverClient {
3115
3291
  }
3116
3292
  return;
3117
3293
  }
3118
- this.send({type: 'session_leave', sessionId: s.sessionId});
3294
+ if (s.sessionId) this.send({type: 'session_leave', sessionId: s.sessionId});
3119
3295
  this.stateStore.update((s: WhereverState) => ({
3120
3296
  ...s,
3121
3297
  messages: [],
@@ -0,0 +1,77 @@
1
+ /**
2
+ * Client half of frame chunking (`frames=chunk.v1`); the server half and the
3
+ * rationale are in `server/src/frame-chunks.ts` (kept in sync by hand).
4
+ *
5
+ * The client asks for chunks with `frames=chunk.v1` on the socket URL. A large
6
+ * server frame then arrives as several text frames, each
7
+ * `\u0001<id> <seq> <count>\n<data>`; concatenating the data in order gives back
8
+ * the original JSON. Every chunk is an inbound frame, which is what keeps the
9
+ * liveness watchdog from condemning a socket that is busy delivering a
10
+ * multi-MB history over a slow link.
11
+ */
12
+
13
+ export const FRAME_CHUNK_PARAM = 'frames';
14
+ export const FRAME_CHUNK_VERSION = 'chunk.v1';
15
+ const MARK = 1; // U+0001: never the first character of a JSON document
16
+
17
+ export type ChunkResult =
18
+ | {kind: 'frame'; text: string}
19
+ | {kind: 'partial'; received: number; count: number}
20
+ | {kind: 'invalid'};
21
+
22
+ /**
23
+ * Reassembles chunked frames for ONE socket (make a new one per socket: a
24
+ * message whose chunks were cut short by a drop is never completed on another).
25
+ * Chunks of one message are sent back to back, so only one message is ever in
26
+ * progress; a new id simply replaces an unfinished one.
27
+ */
28
+ export class FrameReassembler {
29
+ private id: string | null = null;
30
+ private count = 0;
31
+ private parts: string[] = [];
32
+
33
+ /** True when `text` is a chunk rather than an ordinary frame. */
34
+ static isChunk(text: string): boolean {
35
+ return text.charCodeAt(0) === MARK;
36
+ }
37
+
38
+ /** Feed one text frame. A non-chunk frame is passed straight through. */
39
+ push(text: string): ChunkResult {
40
+ if (!FrameReassembler.isChunk(text)) return {kind: 'frame', text};
41
+ const nl = text.indexOf('\n');
42
+ if (nl < 0) return {kind: 'invalid'};
43
+ const [id, seqRaw, countRaw] = text.slice(1, nl).split(' ');
44
+ const seq = Number(seqRaw);
45
+ const count = Number(countRaw);
46
+ if (!id || !Number.isInteger(seq) || !Number.isInteger(count) || count < 1 || seq < 0 || seq >= count) {
47
+ return {kind: 'invalid'};
48
+ }
49
+ if (seq === 0 || id !== this.id) {
50
+ if (seq !== 0) {
51
+ // The start of this message was never seen: drop it.
52
+ this.reset();
53
+ return {kind: 'invalid'};
54
+ }
55
+ this.id = id;
56
+ this.count = count;
57
+ this.parts = [];
58
+ }
59
+ if (seq !== this.parts.length || count !== this.count) {
60
+ this.reset();
61
+ return {kind: 'invalid'};
62
+ }
63
+ this.parts.push(text.slice(nl + 1));
64
+ if (this.parts.length < this.count) {
65
+ return {kind: 'partial', received: this.parts.length, count: this.count};
66
+ }
67
+ const full = this.parts.join('');
68
+ this.reset();
69
+ return {kind: 'frame', text: full};
70
+ }
71
+
72
+ reset() {
73
+ this.id = null;
74
+ this.count = 0;
75
+ this.parts = [];
76
+ }
77
+ }
package/src/types.ts CHANGED
@@ -1,6 +1,18 @@
1
+ /**
2
+ * A tool image. Live (`tool_end`) images always carry base64 `data`. In
3
+ * `message_history` a large image may come BY REFERENCE (this client asks for
4
+ * that with `imageRefs=1`): no `data`; instead its decoded size (`bytes`) and
5
+ * its address (`toolCallId`, `entryId`, `index`), fetched from
6
+ * `GET /session/tool-image?sessionId&toolCallId&entryId&index`.
7
+ */
1
8
  export interface ToolImage {
2
9
  mimeType: string;
3
- data: string;
10
+ data?: string;
11
+ bytes?: number;
12
+ toolCallId?: string;
13
+ /** The transcript entry holding the image (sent alongside `toolCallId`). */
14
+ entryId?: string;
15
+ index?: number;
4
16
  }
5
17
 
6
18
  export interface ChatMessage {