wherever-dev 0.22.1 → 0.23.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.
Files changed (49) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/dist/delta-coalescer.d.ts +77 -0
  3. package/dist/delta-coalescer.d.ts.map +1 -0
  4. package/dist/delta-coalescer.js +117 -0
  5. package/dist/delta-coalescer.js.map +1 -0
  6. package/dist/frame-chunks.d.ts +41 -0
  7. package/dist/frame-chunks.d.ts.map +1 -0
  8. package/dist/frame-chunks.js +61 -0
  9. package/dist/frame-chunks.js.map +1 -0
  10. package/dist/history-images.d.ts +33 -0
  11. package/dist/history-images.d.ts.map +1 -0
  12. package/dist/history-images.js +47 -0
  13. package/dist/history-images.js.map +1 -0
  14. package/dist/index.js +116 -6
  15. package/dist/index.js.map +1 -1
  16. package/dist/session-transcript.d.ts +19 -0
  17. package/dist/session-transcript.d.ts.map +1 -1
  18. package/dist/session-transcript.js +67 -0
  19. package/dist/session-transcript.js.map +1 -1
  20. package/dist/session-types.d.ts +21 -2
  21. package/dist/session-types.d.ts.map +1 -1
  22. package/dist/static-compression.d.ts +15 -0
  23. package/dist/static-compression.d.ts.map +1 -0
  24. package/dist/static-compression.js +87 -0
  25. package/dist/static-compression.js.map +1 -0
  26. package/package.json +1 -1
  27. package/public/_app/immutable/chunks/{DEUwJYqt.js → BHw5ar2A.js} +2 -2
  28. package/public/_app/immutable/chunks/{DEUwJYqt.js.map → BHw5ar2A.js.map} +1 -1
  29. package/public/_app/immutable/chunks/{DSPDB3Gw.js → CLKlGLL7.js} +2 -2
  30. package/public/_app/immutable/chunks/{DSPDB3Gw.js.map → CLKlGLL7.js.map} +1 -1
  31. package/public/_app/immutable/chunks/{Cuh9gHb6.js → FePVnZ_7.js} +2 -2
  32. package/public/_app/immutable/chunks/{Cuh9gHb6.js.map → FePVnZ_7.js.map} +1 -1
  33. package/public/_app/immutable/entry/{app.BkV4f8p8.js → app.BJxkSaKZ.js} +3 -3
  34. package/public/_app/immutable/entry/{app.BkV4f8p8.js.map → app.BJxkSaKZ.js.map} +1 -1
  35. package/public/_app/immutable/entry/start.CRP1MCwE.js +2 -0
  36. package/public/_app/immutable/entry/start.CRP1MCwE.js.map +1 -0
  37. package/public/_app/immutable/nodes/{0.DR4K9Ylw.js → 0.DGFJlad5.js} +2 -2
  38. package/public/_app/immutable/nodes/{0.DR4K9Ylw.js.map → 0.DGFJlad5.js.map} +1 -1
  39. package/public/_app/immutable/nodes/{1.DdqkeKC4.js → 1.Cy3IVwDh.js} +2 -2
  40. package/public/_app/immutable/nodes/{1.DdqkeKC4.js.map → 1.Cy3IVwDh.js.map} +1 -1
  41. package/public/_app/immutable/nodes/2.eb9p7ShF.js +123 -0
  42. package/public/_app/immutable/nodes/2.eb9p7ShF.js.map +1 -0
  43. package/public/_app/version.json +1 -1
  44. package/public/index.html +10 -10
  45. package/public/service-worker.js +1 -1
  46. package/public/_app/immutable/entry/start.D5TsAoxn.js +0 -2
  47. package/public/_app/immutable/entry/start.D5TsAoxn.js.map +0 -1
  48. package/public/_app/immutable/nodes/2.n5lfdeec.js +0 -122
  49. package/public/_app/immutable/nodes/2.n5lfdeec.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # wherever-dev
2
2
 
3
+ ## 0.23.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
+
3
15
  ## 0.22.1
4
16
 
5
17
  ### Patch Changes
@@ -0,0 +1,77 @@
1
+ /**
2
+ * Coalesce streamed deltas into fewer WebSocket frames, per socket.
3
+ *
4
+ * Every streamed token used to be its own frame: a ~4-character `text_delta`
5
+ * wrapped in ~60 bytes of JSON (type + a 36-character session id), below the
6
+ * permessage-deflate threshold and so uncompressed, then TLS/TCP framing on top.
7
+ * On a slow phone link that was over an order of magnitude more bytes than the
8
+ * text itself, plus one client re-render per token.
9
+ *
10
+ * Rules (the reason this is safe for every client, old or new):
11
+ * - Only APPEND-ONLY deltas are held: `message_update`, `thinking_update` (keyed
12
+ * by session) and `tool_update` (keyed by session + tool name). For each, the
13
+ * client appends `delta` to the streaming message, so one frame carrying
14
+ * `d1 + d2` renders exactly like `d1` then `d2`.
15
+ * - ORDER IS NEVER CHANGED: any other frame (and a delta with another key)
16
+ * flushes the held delta first, then goes out. So `message_end`, `tool_end`,
17
+ * `agent_end` etc. always follow every delta that preceded them.
18
+ * - A held delta goes out after `windowMs` (default 50 ms, imperceptible), or at
19
+ * once when it reaches `maxChars` (keeps frames well under the chunking size).
20
+ * - Backpressure: while the socket still has unsent data (`isBackedUp`), the
21
+ * held delta keeps growing instead of queueing yet another frame behind it, up
22
+ * to `maxHoldMs`. A client that fell behind thus catches up in a few large
23
+ * frames instead of thousands of tiny ones. Nothing is ever dropped.
24
+ */
25
+ export type DeltaMessage = {
26
+ type: 'message_update';
27
+ sessionId: string;
28
+ delta: string;
29
+ } | {
30
+ type: 'thinking_update';
31
+ sessionId: string;
32
+ delta: string;
33
+ } | {
34
+ type: 'tool_update';
35
+ sessionId: string;
36
+ toolName: string;
37
+ delta: string;
38
+ };
39
+ export interface DeltaCoalescerOptions {
40
+ windowMs?: number;
41
+ maxChars?: number;
42
+ maxHoldMs?: number;
43
+ /** True while the transport still has unsent data queued. */
44
+ isBackedUp?: () => boolean;
45
+ /** Injected for tests. */
46
+ setTimer?: (fn: () => void, ms: number) => unknown;
47
+ clearTimer?: (t: unknown) => void;
48
+ now?: () => number;
49
+ }
50
+ export declare const DELTA_WINDOW_MS = 50;
51
+ export declare const DELTA_MAX_CHARS: number;
52
+ export declare const DELTA_MAX_HOLD_MS = 1000;
53
+ export declare class DeltaCoalescer<M extends {
54
+ type: string;
55
+ }> {
56
+ private readonly write;
57
+ private held;
58
+ private heldKey;
59
+ private heldSince;
60
+ private timer;
61
+ private readonly windowMs;
62
+ private readonly maxChars;
63
+ private readonly maxHoldMs;
64
+ private readonly isBackedUp;
65
+ private readonly setTimer;
66
+ private readonly clearTimer;
67
+ private readonly now;
68
+ constructor(write: (msg: M) => void, opts?: DeltaCoalescerOptions);
69
+ /** Send `msg`, holding it briefly if it is a delta that can be merged. */
70
+ send(msg: M): void;
71
+ /** Send the held delta now, if any. */
72
+ flush(): void;
73
+ /** Forget the held delta without sending it (the socket is gone). */
74
+ dispose(): void;
75
+ private arm;
76
+ }
77
+ //# sourceMappingURL=delta-coalescer.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"delta-coalescer.d.ts","sourceRoot":"","sources":["../src/delta-coalescer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;IAC3B,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACnD,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAClC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,eAAO,MAAM,eAAe,QAAY,CAAC;AACzC,eAAO,MAAM,iBAAiB,OAAQ,CAAC;AAUvC,qBAAa,cAAc,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;IAclD,OAAO,CAAC,QAAQ,CAAC,KAAK;IAbxB,OAAO,CAAC,IAAI,CAA6B;IACzC,OAAO,CAAC,OAAO,CAAM;IACrB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgB;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAClD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAGhB,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,EACxC,IAAI,GAAE,qBAA0B;IAiBlC,0EAA0E;IAC1E,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;IAmBlB,uCAAuC;IACvC,KAAK,IAAI,IAAI;IAWb,qEAAqE;IACrE,OAAO,IAAI,IAAI;IAOf,OAAO,CAAC,GAAG;CAWZ"}
@@ -0,0 +1,117 @@
1
+ /**
2
+ * Coalesce streamed deltas into fewer WebSocket frames, per socket.
3
+ *
4
+ * Every streamed token used to be its own frame: a ~4-character `text_delta`
5
+ * wrapped in ~60 bytes of JSON (type + a 36-character session id), below the
6
+ * permessage-deflate threshold and so uncompressed, then TLS/TCP framing on top.
7
+ * On a slow phone link that was over an order of magnitude more bytes than the
8
+ * text itself, plus one client re-render per token.
9
+ *
10
+ * Rules (the reason this is safe for every client, old or new):
11
+ * - Only APPEND-ONLY deltas are held: `message_update`, `thinking_update` (keyed
12
+ * by session) and `tool_update` (keyed by session + tool name). For each, the
13
+ * client appends `delta` to the streaming message, so one frame carrying
14
+ * `d1 + d2` renders exactly like `d1` then `d2`.
15
+ * - ORDER IS NEVER CHANGED: any other frame (and a delta with another key)
16
+ * flushes the held delta first, then goes out. So `message_end`, `tool_end`,
17
+ * `agent_end` etc. always follow every delta that preceded them.
18
+ * - A held delta goes out after `windowMs` (default 50 ms, imperceptible), or at
19
+ * once when it reaches `maxChars` (keeps frames well under the chunking size).
20
+ * - Backpressure: while the socket still has unsent data (`isBackedUp`), the
21
+ * held delta keeps growing instead of queueing yet another frame behind it, up
22
+ * to `maxHoldMs`. A client that fell behind thus catches up in a few large
23
+ * frames instead of thousands of tiny ones. Nothing is ever dropped.
24
+ */
25
+ export const DELTA_WINDOW_MS = 50;
26
+ export const DELTA_MAX_CHARS = 16 * 1024;
27
+ export const DELTA_MAX_HOLD_MS = 1_000;
28
+ function isDelta(msg) {
29
+ return msg.type === 'message_update' || msg.type === 'thinking_update' || msg.type === 'tool_update';
30
+ }
31
+ function keyOf(msg) {
32
+ return msg.type === 'tool_update' ? `${msg.type}\0${msg.sessionId}\0${msg.toolName}` : `${msg.type}\0${msg.sessionId}`;
33
+ }
34
+ export class DeltaCoalescer {
35
+ write;
36
+ held = null;
37
+ heldKey = '';
38
+ heldSince = 0;
39
+ timer = null;
40
+ windowMs;
41
+ maxChars;
42
+ maxHoldMs;
43
+ isBackedUp;
44
+ setTimer;
45
+ clearTimer;
46
+ now;
47
+ constructor(write, opts = {}) {
48
+ this.write = write;
49
+ this.windowMs = opts.windowMs ?? DELTA_WINDOW_MS;
50
+ this.maxChars = opts.maxChars ?? DELTA_MAX_CHARS;
51
+ this.maxHoldMs = opts.maxHoldMs ?? DELTA_MAX_HOLD_MS;
52
+ this.isBackedUp = opts.isBackedUp ?? (() => false);
53
+ this.setTimer =
54
+ opts.setTimer ??
55
+ ((fn, ms) => {
56
+ const t = setTimeout(fn, ms);
57
+ t.unref?.();
58
+ return t;
59
+ });
60
+ this.clearTimer = opts.clearTimer ?? ((t) => clearTimeout(t));
61
+ this.now = opts.now ?? Date.now;
62
+ }
63
+ /** Send `msg`, holding it briefly if it is a delta that can be merged. */
64
+ send(msg) {
65
+ if (!isDelta(msg)) {
66
+ this.flush();
67
+ this.write(msg);
68
+ return;
69
+ }
70
+ const key = keyOf(msg);
71
+ if (this.held && this.heldKey === key) {
72
+ this.held = { ...this.held, delta: this.held.delta + msg.delta };
73
+ }
74
+ else {
75
+ this.flush();
76
+ this.held = { ...msg };
77
+ this.heldKey = key;
78
+ this.heldSince = this.now();
79
+ this.arm();
80
+ }
81
+ if (this.held.delta.length >= this.maxChars)
82
+ this.flush();
83
+ }
84
+ /** Send the held delta now, if any. */
85
+ flush() {
86
+ if (this.timer !== null) {
87
+ this.clearTimer(this.timer);
88
+ this.timer = null;
89
+ }
90
+ const held = this.held;
91
+ this.held = null;
92
+ this.heldKey = '';
93
+ if (held)
94
+ this.write(held);
95
+ }
96
+ /** Forget the held delta without sending it (the socket is gone). */
97
+ dispose() {
98
+ if (this.timer !== null)
99
+ this.clearTimer(this.timer);
100
+ this.timer = null;
101
+ this.held = null;
102
+ this.heldKey = '';
103
+ }
104
+ arm() {
105
+ this.timer = this.setTimer(() => {
106
+ this.timer = null;
107
+ if (!this.held)
108
+ return;
109
+ if (this.isBackedUp() && this.now() - this.heldSince < this.maxHoldMs) {
110
+ this.arm();
111
+ return;
112
+ }
113
+ this.flush();
114
+ }, this.windowMs);
115
+ }
116
+ }
117
+ //# sourceMappingURL=delta-coalescer.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"delta-coalescer.js","sourceRoot":"","sources":["../src/delta-coalescer.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,41 @@
1
+ /**
2
+ * Frame chunking (`frames=chunk.v1`): split one large server -> client JSON frame
3
+ * into several small TEXT frames that the client reassembles.
4
+ *
5
+ * Why: a browser hands a WebSocket message to the page only once ALL of it has
6
+ * arrived. Over a slow link (a phone on a weak cell) a multi-MB frame, typically
7
+ * a `message_history` carrying base64 tool images, takes longer to arrive than
8
+ * the client's liveness watchdog tolerates silence (`STALE_SOCKET_MS`), so the
9
+ * client tore down a healthy socket mid-transfer, reconnected, asked for the
10
+ * same history and looped forever without ever painting it. Small frames make
11
+ * every piece an inbound frame, which is the watchdog's proof of life.
12
+ *
13
+ * Opt-in per connection: the client says it understands chunks with the
14
+ * `frames=chunk.v1` query parameter on the socket URL, so an older cached web
15
+ * build (or the CLI bridge socket, which never asks) never receives a frame it cannot parse.
16
+ *
17
+ * Wire format of one chunk (a text frame): `\u0001<id> <seq> <count>\n<data>`.
18
+ * The leading U+0001 can never start a JSON document, so a chunk is told apart
19
+ * from an ordinary frame by its first character. `id` names the message, `seq`
20
+ * is 0-based, `count` is the number of chunks; concatenating every chunk's data
21
+ * in order gives back the original JSON text. The chunks of one message are sent
22
+ * back to back, so frame ORDER on the socket is unchanged.
23
+ *
24
+ * The client half lives in `client/src/frame-chunks.ts` (kept in sync by hand:
25
+ * the server does not depend on the client package).
26
+ */
27
+ export declare const FRAME_CHUNK_PARAM = "frames";
28
+ export declare const FRAME_CHUNK_VERSION = "chunk.v1";
29
+ export declare const FRAME_CHUNK_MARK = "\u0001";
30
+ /** Chunk payload size in UTF-16 code units. ~32 KB keeps each piece a few
31
+ * seconds long even on a ~10 KB/s link. */
32
+ export declare const FRAME_CHUNK_CHARS: number;
33
+ /**
34
+ * Split `json` into chunk frames, or return `[json]` unchanged when it fits in
35
+ * one. Never splits a surrogate pair: a lone surrogate would be replaced by
36
+ * U+FFFD when the frame is UTF-8 encoded, corrupting the text.
37
+ */
38
+ export declare function splitFrame(json: string, id: number, maxChars?: number): string[];
39
+ /** True when the socket URL's query string asks for chunked frames. */
40
+ export declare function wantsFrameChunks(searchParams: URLSearchParams): boolean;
41
+ //# sourceMappingURL=frame-chunks.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"frame-chunks.d.ts","sourceRoot":"","sources":["../src/frame-chunks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAC1C,eAAO,MAAM,mBAAmB,aAAa,CAAC;AAC9C,eAAO,MAAM,gBAAgB,WAAW,CAAC;AACzC;4CAC4C;AAC5C,eAAO,MAAM,iBAAiB,QAAY,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,SAAoB,GAAG,MAAM,EAAE,CAgB3F;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,eAAe,GAAG,OAAO,CAEvE"}
@@ -0,0 +1,61 @@
1
+ /**
2
+ * Frame chunking (`frames=chunk.v1`): split one large server -> client JSON frame
3
+ * into several small TEXT frames that the client reassembles.
4
+ *
5
+ * Why: a browser hands a WebSocket message to the page only once ALL of it has
6
+ * arrived. Over a slow link (a phone on a weak cell) a multi-MB frame, typically
7
+ * a `message_history` carrying base64 tool images, takes longer to arrive than
8
+ * the client's liveness watchdog tolerates silence (`STALE_SOCKET_MS`), so the
9
+ * client tore down a healthy socket mid-transfer, reconnected, asked for the
10
+ * same history and looped forever without ever painting it. Small frames make
11
+ * every piece an inbound frame, which is the watchdog's proof of life.
12
+ *
13
+ * Opt-in per connection: the client says it understands chunks with the
14
+ * `frames=chunk.v1` query parameter on the socket URL, so an older cached web
15
+ * build (or the CLI bridge socket, which never asks) never receives a frame it cannot parse.
16
+ *
17
+ * Wire format of one chunk (a text frame): `\u0001<id> <seq> <count>\n<data>`.
18
+ * The leading U+0001 can never start a JSON document, so a chunk is told apart
19
+ * from an ordinary frame by its first character. `id` names the message, `seq`
20
+ * is 0-based, `count` is the number of chunks; concatenating every chunk's data
21
+ * in order gives back the original JSON text. The chunks of one message are sent
22
+ * back to back, so frame ORDER on the socket is unchanged.
23
+ *
24
+ * The client half lives in `client/src/frame-chunks.ts` (kept in sync by hand:
25
+ * the server does not depend on the client package).
26
+ */
27
+ export const FRAME_CHUNK_PARAM = 'frames';
28
+ export const FRAME_CHUNK_VERSION = 'chunk.v1';
29
+ export const FRAME_CHUNK_MARK = '\u0001';
30
+ /** Chunk payload size in UTF-16 code units. ~32 KB keeps each piece a few
31
+ * seconds long even on a ~10 KB/s link. */
32
+ export const FRAME_CHUNK_CHARS = 32 * 1024;
33
+ /**
34
+ * Split `json` into chunk frames, or return `[json]` unchanged when it fits in
35
+ * one. Never splits a surrogate pair: a lone surrogate would be replaced by
36
+ * U+FFFD when the frame is UTF-8 encoded, corrupting the text.
37
+ */
38
+ export function splitFrame(json, id, maxChars = FRAME_CHUNK_CHARS) {
39
+ if (json.length <= maxChars)
40
+ return [json];
41
+ const pieces = [];
42
+ let at = 0;
43
+ while (at < json.length) {
44
+ let end = Math.min(at + maxChars, json.length);
45
+ if (end < json.length) {
46
+ const c = json.charCodeAt(end - 1);
47
+ // Back off one so the pair stays whole; with a 1-char budget that would
48
+ // make no progress, so take the whole pair instead.
49
+ if (c >= 0xd800 && c <= 0xdbff)
50
+ end = end - 1 > at ? end - 1 : end + 1;
51
+ }
52
+ pieces.push(json.slice(at, end));
53
+ at = end;
54
+ }
55
+ return pieces.map((data, seq) => `${FRAME_CHUNK_MARK}${id} ${seq} ${pieces.length}\n${data}`);
56
+ }
57
+ /** True when the socket URL's query string asks for chunked frames. */
58
+ export function wantsFrameChunks(searchParams) {
59
+ return searchParams.getAll(FRAME_CHUNK_PARAM).includes(FRAME_CHUNK_VERSION);
60
+ }
61
+ //# sourceMappingURL=frame-chunks.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"frame-chunks.js","sourceRoot":"","sources":["../src/frame-chunks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC;AAC1C,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC;AAC9C,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAQ,CAAC;AACzC;4CAC4C;AAC5C,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,GAAG,IAAI,CAAC;AAE3C;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,EAAU,EAAE,QAAQ,GAAG,iBAAiB;IAC/E,IAAI,IAAI,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,EAAE,GAAG,CAAC,CAAC;IACX,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACxB,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAC/C,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACtB,MAAM,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;YACnC,wEAAwE;YACxE,oDAAoD;YACpD,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,IAAI,MAAM;gBAAE,GAAG,GAAG,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;QACjC,EAAE,GAAG,GAAG,CAAC;IACX,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,gBAAgB,GAAG,EAAE,IAAI,GAAG,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC,CAAC;AAChG,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,gBAAgB,CAAC,YAA6B;IAC5D,OAAO,YAAY,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC;AAC9E,CAAC"}
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Tool images by reference in `message_history`.
3
+ *
4
+ * A history window inlines every tool image as base64 (a `read` on a screenshot
5
+ * is often 1-3 MB), and the window is re-sent on every load AND on every
6
+ * reconnect. Over a slow link that made a session with a few screenshots take
7
+ * minutes to resync, every time the phone dropped its socket. A socket that asks
8
+ * for refs (`imageRefs=1` on the socket URL) gets large images WITHOUT their
9
+ * bytes; the web loads each one lazily from `GET /session/tool-image`, which the
10
+ * browser caches (a tool result never changes), so a reconnect costs text only.
11
+ *
12
+ * Opt-in so an older cached web build, which only knows inline `data`, keeps
13
+ * getting it. Only images with a `toolCallId` to address them by are stripped,
14
+ * and small ones stay inline (a fetch costs more than it saves).
15
+ */
16
+ import type { HistoryMessage } from './session-types.js';
17
+ export declare const IMAGE_REFS_PARAM = "imageRefs";
18
+ /** Base64 characters above which an image is sent by reference. */
19
+ export declare const INLINE_IMAGE_MAX_CHARS: number;
20
+ export declare function wantsImageRefs(searchParams: URLSearchParams): boolean;
21
+ /**
22
+ * A copy of `messages` with large tool images replaced by references. Messages
23
+ * without such images are returned as is (same objects), so the common case
24
+ * allocates nothing.
25
+ */
26
+ export declare function stripHistoryImages(messages: HistoryMessage[]): HistoryMessage[];
27
+ /**
28
+ * Raster types the endpoint will serve inline (and so the only ones sent by
29
+ * reference). SVG is excluded on purpose (it can carry script; see
30
+ * dispositionTypeFor in index.ts), as is anything unexpected.
31
+ */
32
+ export declare const SERVABLE_IMAGE_TYPES: Set<string>;
33
+ //# sourceMappingURL=history-images.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"history-images.d.ts","sourceRoot":"","sources":["../src/history-images.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAC5C,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,QAAY,CAAC;AAEhD,wBAAgB,cAAc,CAAC,YAAY,EAAE,eAAe,GAAG,OAAO,CAErE;AAQD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,cAAc,EAAE,CAqB/E;AAMD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,aAA6F,CAAC"}
@@ -0,0 +1,47 @@
1
+ export const IMAGE_REFS_PARAM = 'imageRefs';
2
+ /** Base64 characters above which an image is sent by reference. */
3
+ export const INLINE_IMAGE_MAX_CHARS = 16 * 1024;
4
+ export function wantsImageRefs(searchParams) {
5
+ return searchParams.get(IMAGE_REFS_PARAM) === '1';
6
+ }
7
+ /** Approximate decoded size of a base64 string. */
8
+ function base64Bytes(data) {
9
+ const pad = data.endsWith('==') ? 2 : data.endsWith('=') ? 1 : 0;
10
+ return Math.max(0, Math.floor((data.length * 3) / 4) - pad);
11
+ }
12
+ /**
13
+ * A copy of `messages` with large tool images replaced by references. Messages
14
+ * without such images are returned as is (same objects), so the common case
15
+ * allocates nothing.
16
+ */
17
+ export function stripHistoryImages(messages) {
18
+ let changed = false;
19
+ const out = messages.map((m) => {
20
+ if (!m.toolCallId || !m.images?.some(byRef))
21
+ return m;
22
+ changed = true;
23
+ return {
24
+ ...m,
25
+ images: m.images.map((i, index) => byRef(i)
26
+ ? {
27
+ mimeType: i.mimeType,
28
+ bytes: base64Bytes(i.data),
29
+ toolCallId: m.toolCallId,
30
+ ...(m.entryId ? { entryId: m.entryId } : {}),
31
+ index,
32
+ }
33
+ : i),
34
+ };
35
+ });
36
+ return changed ? out : messages;
37
+ }
38
+ function byRef(i) {
39
+ return typeof i.data === 'string' && i.data.length > INLINE_IMAGE_MAX_CHARS && SERVABLE_IMAGE_TYPES.has(i.mimeType);
40
+ }
41
+ /**
42
+ * Raster types the endpoint will serve inline (and so the only ones sent by
43
+ * reference). SVG is excluded on purpose (it can carry script; see
44
+ * dispositionTypeFor in index.ts), as is anything unexpected.
45
+ */
46
+ export const SERVABLE_IMAGE_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/bmp', 'image/avif']);
47
+ //# sourceMappingURL=history-images.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"history-images.js","sourceRoot":"","sources":["../src/history-images.ts"],"names":[],"mappings":"AAiBA,MAAM,CAAC,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAC5C,mEAAmE;AACnE,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,GAAG,IAAI,CAAC;AAEhD,MAAM,UAAU,cAAc,CAAC,YAA6B;IAC1D,OAAO,YAAY,CAAC,GAAG,CAAC,gBAAgB,CAAC,KAAK,GAAG,CAAC;AACpD,CAAC;AAED,mDAAmD;AACnD,SAAS,WAAW,CAAC,IAAY;IAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACjE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAA0B;IAC3D,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC7B,IAAI,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QACtD,OAAO,GAAG,IAAI,CAAC;QACf,OAAO;YACL,GAAG,CAAC;YACJ,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAChC,KAAK,CAAC,CAAC,CAAC;gBACN,CAAC,CAAC;oBACE,QAAQ,EAAE,CAAC,CAAC,QAAQ;oBACpB,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,IAAK,CAAC;oBAC3B,UAAU,EAAE,CAAC,CAAC,UAAU;oBACxB,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC5C,KAAK;iBACN;gBACH,CAAC,CAAC,CAAC,CACN;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;AAClC,CAAC;AAED,SAAS,KAAK,CAAC,CAAsC;IACnD,OAAO,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,sBAAsB,IAAI,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;AACtH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC"}
package/dist/index.js CHANGED
@@ -26,6 +26,11 @@ import { INITIAL_HISTORY_LIMIT, HISTORY_PAGE_SIZE } from './protocol.js';
26
26
  import { gateUploadFolder, gateUploadWrite, uploadMaxBytes, uploadTooLarge } from './upload-gate.js';
27
27
  import { readAttachGrants } from './download-grants.js';
28
28
  import { DEFAULT_DOWNLOAD_MAX_BYTES } from './attach-file-tool.js';
29
+ import { splitFrame, wantsFrameChunks, FRAME_CHUNK_CHARS } from './frame-chunks.js';
30
+ import { compressCached, isCompressible, negotiateEncoding } from './static-compression.js';
31
+ import { stripHistoryImages, wantsImageRefs, SERVABLE_IMAGE_TYPES } from './history-images.js';
32
+ import { readToolResultImage } from './session-transcript.js';
33
+ import { DeltaCoalescer } from './delta-coalescer.js';
29
34
  import { UploadStaging, UPLOAD_CAPABILITY, isValidUploadId, parseChunkFrame, CHUNK_FRAME_KIND } from './upload-staging.js';
30
35
  import fs from 'node:fs';
31
36
  import path from 'node:path';
@@ -272,7 +277,7 @@ async function resolveSafeDownloadPath(requested, cwd, roots, grants) {
272
277
  }
273
278
  return null;
274
279
  }
275
- function serveStaticFile(reqPath, res) {
280
+ function serveStaticFile(reqPath, res, acceptEncoding) {
276
281
  let filePath = path.join(staticDir, reqPath === '/' ? 'index.html' : reqPath);
277
282
  if (!filePath.startsWith(staticDir)) {
278
283
  res.writeHead(403);
@@ -313,8 +318,26 @@ function serveStaticFile(reqPath, res) {
313
318
  if (debugEnabled && filePath.endsWith('index.html')) {
314
319
  data = Buffer.from(data.toString().replace(ERUDA_PLUGINS_META_FALSE, ERUDA_PLUGINS_META_TRUE));
315
320
  }
316
- res.writeHead(200, { 'Content-Type': contentType, 'Cache-Control': cacheControl });
317
- res.end(data);
321
+ const encoding = isCompressible(contentType, data.length) ? negotiateEncoding(acceptEncoding) : null;
322
+ if (!encoding) {
323
+ res.writeHead(200, { 'Content-Type': contentType, 'Cache-Control': cacheControl, Vary: 'Accept-Encoding' });
324
+ res.end(data);
325
+ return;
326
+ }
327
+ const body = data;
328
+ compressCached(body, encoding).then((compressed) => {
329
+ res.writeHead(200, {
330
+ 'Content-Type': contentType,
331
+ 'Cache-Control': cacheControl,
332
+ 'Content-Encoding': encoding,
333
+ 'Content-Length': compressed.length,
334
+ Vary: 'Accept-Encoding',
335
+ });
336
+ res.end(compressed);
337
+ }, () => {
338
+ res.writeHead(200, { 'Content-Type': contentType, 'Cache-Control': cacheControl, Vary: 'Accept-Encoding' });
339
+ res.end(body);
340
+ });
318
341
  }
319
342
  });
320
343
  }
@@ -866,10 +889,48 @@ function readBody(req, maxLimitBytes = 1e6) {
866
889
  req.on('error', (err) => reject(err));
867
890
  });
868
891
  }
892
+ // Sockets whose client asked for chunked frames (`frames=chunk.v1` on the socket
893
+ // URL, see frame-chunks.ts). Keyed by socket so every sender gets it for free.
894
+ const chunkingSockets = new WeakSet();
895
+ let nextFrameChunkId = 1;
896
+ // Sockets whose client loads large history images by reference (`imageRefs=1`,
897
+ // see history-images.ts) instead of receiving their base64 inline.
898
+ const imageRefSockets = new WeakSet();
899
+ // Per-socket coalescing of streamed deltas (delta-coalescer.ts): fewer, larger
900
+ // frames, frame order unchanged. "Backed up" = more than 64 KB still unsent.
901
+ const deltaCoalescers = new WeakMap();
902
+ const BACKED_UP_BYTES = 64 * 1024;
903
+ function coalescerFor(ws) {
904
+ let c = deltaCoalescers.get(ws);
905
+ if (!c) {
906
+ c = new DeltaCoalescer((m) => writeWS(ws, m), {
907
+ isBackedUp: () => ws.bufferedAmount > BACKED_UP_BYTES,
908
+ });
909
+ deltaCoalescers.set(ws, c);
910
+ ws.once('close', () => c.dispose());
911
+ }
912
+ return c;
913
+ }
869
914
  function sendWS(ws, msg) {
915
+ if (ws.readyState !== WebSocket.OPEN)
916
+ return;
917
+ coalescerFor(ws).send(msg);
918
+ }
919
+ function writeWS(ws, msg) {
870
920
  if (ws.readyState === WebSocket.OPEN) {
871
921
  try {
872
- ws.send(JSON.stringify(msg));
922
+ if ((msg.type === 'message_history' || msg.type === 'message_history_prepend') && imageRefSockets.has(ws)) {
923
+ msg = { ...msg, messages: stripHistoryImages(msg.messages) };
924
+ }
925
+ const json = JSON.stringify(msg);
926
+ if (chunkingSockets.has(ws) && json.length > FRAME_CHUNK_CHARS) {
927
+ // Back to back, so frame order on the socket is unchanged.
928
+ for (const piece of splitFrame(json, nextFrameChunkId++))
929
+ ws.send(piece);
930
+ }
931
+ else {
932
+ ws.send(json);
933
+ }
873
934
  }
874
935
  catch (err) {
875
936
  console.error('Failed to send WS message:', err);
@@ -900,6 +961,8 @@ function sendThenTerminate(ws, msg, flushTimeoutMs = 1_000) {
900
961
  };
901
962
  const timer = setTimeout(kill, flushTimeoutMs);
902
963
  timer.unref?.();
964
+ // Anything still held by the delta coalescer goes out first, in order.
965
+ deltaCoalescers.get(ws)?.flush();
903
966
  if (ws.readyState !== WebSocket.OPEN) {
904
967
  clearTimeout(timer);
905
968
  kill();
@@ -2353,6 +2416,41 @@ async function main() {
2353
2416
  }
2354
2417
  return;
2355
2418
  }
2419
+ // A tool image sent by reference in message_history (history-images.ts).
2420
+ // Same token gate as every /session/ route. A tool result never changes once
2421
+ // written, so the browser may keep the image for good.
2422
+ if (pathname === '/session/tool-image' && req.method === 'GET') {
2423
+ const qSessionId = url.searchParams.get('sessionId') || '';
2424
+ const qToolCallId = url.searchParams.get('toolCallId') || '';
2425
+ const qEntryId = url.searchParams.get('entryId') || undefined;
2426
+ const qIndexRaw = url.searchParams.get('index');
2427
+ const qIndex = qIndexRaw ? Number(qIndexRaw) : NaN;
2428
+ if (!qSessionId || !qToolCallId || !Number.isInteger(qIndex) || qIndex < 0) {
2429
+ sendJSON(res, 400, { error: 'Missing sessionId, toolCallId or index' });
2430
+ return;
2431
+ }
2432
+ const located = await sessionPool.locateSession(qSessionId);
2433
+ const image = located
2434
+ ? await readToolResultImage(located.sessionFile, { toolCallId: qToolCallId, entryId: qEntryId }, qIndex)
2435
+ : null;
2436
+ if (!image) {
2437
+ sendJSON(res, 404, { error: 'Image not found' });
2438
+ return;
2439
+ }
2440
+ if (!SERVABLE_IMAGE_TYPES.has(image.mimeType)) {
2441
+ sendJSON(res, 415, { error: `Unsupported image type ${image.mimeType}` });
2442
+ return;
2443
+ }
2444
+ const bytes = Buffer.from(image.data, 'base64');
2445
+ res.writeHead(200, {
2446
+ 'Content-Type': image.mimeType,
2447
+ 'Content-Length': bytes.length,
2448
+ 'Cache-Control': 'private, max-age=31536000, immutable',
2449
+ 'X-Content-Type-Options': 'nosniff',
2450
+ });
2451
+ res.end(bytes);
2452
+ return;
2453
+ }
2356
2454
  if (pathname === '/session/download' && req.method === 'GET') {
2357
2455
  const config = getWhereverConfig();
2358
2456
  if (config.downloads?.enabled === false) {
@@ -2521,7 +2619,7 @@ async function main() {
2521
2619
  });
2522
2620
  return;
2523
2621
  }
2524
- serveStaticFile(pathname, res);
2622
+ serveStaticFile(pathname, res, req.headers['accept-encoding']);
2525
2623
  };
2526
2624
  let server;
2527
2625
  let httpServer = null;
@@ -2561,7 +2659,15 @@ async function main() {
2561
2659
  else {
2562
2660
  server = createHttpServer(requestHandler);
2563
2661
  }
2564
- const wss = new WebSocketServer({ noServer: true });
2662
+ // permessage-deflate: frames are JSON text (history, tool output, streamed
2663
+ // replies) that compresses several times over, which matters most on the slow
2664
+ // links phones are on. Browsers negotiate it natively; a client that does not
2665
+ // offer the extension simply gets uncompressed frames. Small frames (most
2666
+ // streaming deltas) are left alone: deflating them costs CPU for no gain.
2667
+ const wss = new WebSocketServer({
2668
+ noServer: true,
2669
+ perMessageDeflate: { threshold: 1024 },
2670
+ });
2565
2671
  // Connection-liveness heartbeat. A half-open TCP socket (peer vanished without
2566
2672
  // a clean FIN/RST: process restart, network blip, dropped upstream) stays in
2567
2673
  // ESTAB and fires neither 'close' nor 'error', so the connected agent/session
@@ -2633,6 +2739,10 @@ async function main() {
2633
2739
  else if (raw) {
2634
2740
  clientKey = raw;
2635
2741
  }
2742
+ if (wantsFrameChunks(url.searchParams))
2743
+ chunkingSockets.add(ws);
2744
+ if (wantsImageRefs(url.searchParams))
2745
+ imageRefSockets.add(ws);
2636
2746
  }
2637
2747
  catch { }
2638
2748
  if (clientKey) {