@parcha/pi-browser 0.1.0-beta.18 → 0.1.0-beta.19

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 (87) hide show
  1. package/CHANGELOG.md +5 -0
  2. package/README.md +177 -39
  3. package/dist/coding-agent-local.js +2 -1
  4. package/dist/coding-agent.d.ts +42 -2
  5. package/dist/coding-agent.js +159 -21
  6. package/dist/core/clip.d.ts +31 -0
  7. package/dist/core/clip.js +49 -0
  8. package/dist/core/contract.d.ts +4 -1
  9. package/dist/core/contract.js +40 -7
  10. package/dist/core/custody.d.ts +79 -5
  11. package/dist/core/custody.js +66 -5
  12. package/dist/core/decisions.d.ts +4 -0
  13. package/dist/core/dial.d.ts +7 -0
  14. package/dist/core/dial.js +41 -0
  15. package/dist/core/downloads.d.ts +1 -0
  16. package/dist/core/downloads.js +17 -5
  17. package/dist/core/driving-guard.d.ts +13 -0
  18. package/dist/core/driving-guard.js +61 -0
  19. package/dist/core/driving.d.ts +61 -0
  20. package/dist/core/driving.js +156 -0
  21. package/dist/core/effects.js +33 -13
  22. package/dist/core/evidence.d.ts +3 -1
  23. package/dist/core/failures.d.ts +5 -1
  24. package/dist/core/failures.js +20 -4
  25. package/dist/core/files.d.ts +8 -0
  26. package/dist/core/files.js +74 -0
  27. package/dist/core/find.d.ts +3 -1
  28. package/dist/core/find.js +2 -1
  29. package/dist/core/guard.d.ts +9 -1
  30. package/dist/core/guard.js +7 -2
  31. package/dist/core/host.d.ts +49 -1
  32. package/dist/core/images.d.ts +10 -2
  33. package/dist/core/images.js +4 -4
  34. package/dist/core/lease.d.ts +1 -1
  35. package/dist/core/lease.js +2 -1
  36. package/dist/core/session-control.d.ts +2 -0
  37. package/dist/core/session-control.js +5 -0
  38. package/dist/core/tools.d.ts +70 -4
  39. package/dist/core/tools.js +288 -45
  40. package/dist/core/unanswered.d.ts +3 -0
  41. package/dist/core/unanswered.js +17 -0
  42. package/dist/core/usage.d.ts +2 -0
  43. package/dist/core/usage.js +6 -0
  44. package/dist/core/web.d.ts +1 -1
  45. package/dist/core/web.js +9 -7
  46. package/dist/driver/extension-worker.d.ts +4 -2
  47. package/dist/driver/extension-worker.js +16 -10
  48. package/dist/driver/page-driver.d.ts +8 -0
  49. package/dist/driver/page-driver.js +128 -0
  50. package/dist/driver/stagehand.d.ts +3 -1
  51. package/dist/driver/stagehand.js +40 -66
  52. package/dist/durable.d.ts +16 -4
  53. package/dist/durable.js +415 -82
  54. package/dist/index.d.ts +2 -0
  55. package/dist/index.js +2 -0
  56. package/dist/live-view/index.d.ts +4 -0
  57. package/dist/live-view/index.js +4 -0
  58. package/dist/live-view/protocol.d.ts +152 -0
  59. package/dist/live-view/protocol.js +84 -0
  60. package/dist/live-view/provider.d.ts +6 -0
  61. package/dist/live-view/provider.js +23 -0
  62. package/dist/live-view/server.d.ts +50 -0
  63. package/dist/live-view/server.js +342 -0
  64. package/dist/live-view/stream.d.ts +7 -0
  65. package/dist/live-view/stream.js +388 -0
  66. package/dist/live-view/token.d.ts +6 -0
  67. package/dist/live-view/token.js +13 -0
  68. package/dist/live-view/viewer.d.ts +6 -0
  69. package/dist/live-view/viewer.js +350 -0
  70. package/dist/live-view/ws.d.ts +19 -0
  71. package/dist/live-view/ws.js +176 -0
  72. package/dist/providers/assigned.d.ts +18 -0
  73. package/dist/providers/assigned.js +76 -0
  74. package/dist/providers/cdp-call.js +12 -2
  75. package/dist/providers/cdp.js +37 -11
  76. package/dist/recorder/follow.d.ts +10 -0
  77. package/dist/recorder/follow.js +27 -2
  78. package/dist/recorder/frames.d.ts +7 -0
  79. package/dist/recorder/frames.js +73 -5
  80. package/dist/store.d.ts +22 -3
  81. package/dist/store.js +75 -4
  82. package/dist/testing/backend.d.ts +26 -0
  83. package/dist/testing/backend.js +21 -3
  84. package/dist/testing/driver.d.ts +18 -1
  85. package/dist/testing/driver.js +4 -0
  86. package/dist/web.js +2 -2
  87. package/package.json +10 -2
@@ -0,0 +1,350 @@
1
+ // The live view's viewer page, as three strings the server serves: the page at {base}/v/{id}, and its script and style at {base}/viewer.js and {base}/viewer.css. Three files because the
2
+ // page is served under `default-src 'self'`, which refuses inline script and style. Nothing external: one canvas, the page's own two files and one WebSocket to the page's own origin.
3
+ //
4
+ // The script reads the token from the URL fragment (#t=<token>) and drops the fragment from the address bar at once, opens ws(s)://<this host><this path>/ws, and sends {type:"hello", token} as
5
+ // its first message; nothing else is sent before the server has answered. Frames arrive as binary [u16 w][u16 h][jpeg] and are drawn to the canvas; mouse, wheel, key and paste on the canvas go
6
+ // back as protocol.ts messages in the page's own CSS pixels (the w and h of the latest frame), and the address bar and its back and reload buttons go back as `nav`. It writes no frame to
7
+ // storage: a frame lives in the canvas and in the one decode in flight.
8
+ const html = `<!doctype html>
9
+ <html lang="en">
10
+ <head>
11
+ <meta charset="utf-8">
12
+ <meta name="viewport" content="width=device-width, initial-scale=1">
13
+ <title>Live view</title>
14
+ <link rel="stylesheet" href="../viewer.css">
15
+ </head>
16
+ <body>
17
+ <header id="bar">
18
+ <button id="back" type="button" title="Back" aria-label="Back">&#8592;</button>
19
+ <button id="reload" type="button" title="Reload" aria-label="Reload">&#8635;</button>
20
+ <form id="go" autocomplete="off"><input id="url" type="text" spellcheck="false" aria-label="Address" placeholder="https://"></form>
21
+ <span id="drive" aria-live="polite"></span>
22
+ </header>
23
+ <div id="notice" role="status" hidden></div>
24
+ <div id="still" role="status" hidden>This page is in a background tab or has not drawn yet, so there is no picture until it is shown. Typing and clicking still work.</div>
25
+ <div id="dialog" role="alertdialog" aria-modal="true" hidden>
26
+ <div id="dialog-box">
27
+ <p id="dialog-kind"></p>
28
+ <p id="dialog-message"></p>
29
+ <input id="dialog-prompt" type="text" hidden aria-label="Answer">
30
+ <div id="dialog-buttons"><button id="dialog-accept" type="button">OK</button><button id="dialog-dismiss" type="button">Cancel</button></div>
31
+ </div>
32
+ </div>
33
+ <main id="stage"><canvas id="screen" tabindex="0" aria-label="The browser's page"></canvas><textarea id="sink" rows="1" autocapitalize="off" autocomplete="off" autocorrect="off" spellcheck="false" aria-label="Keyboard input for the page"></textarea></main>
34
+ <script src="../viewer.js"></script>
35
+ </body>
36
+ </html>
37
+ `;
38
+ const css = `* { box-sizing: border-box; }
39
+ html, body { margin: 0; height: 100%; background: #111; color: #eee; font: 14px system-ui, sans-serif; }
40
+ body { display: flex; flex-direction: column; }
41
+ #bar { display: flex; gap: 6px; align-items: center; padding: 6px 8px; background: #222; border-bottom: 1px solid #333; }
42
+ #bar button { background: #333; color: #eee; border: 1px solid #444; border-radius: 4px; padding: 4px 10px; cursor: pointer; }
43
+ #bar button:hover { background: #444; }
44
+ #go { flex: 1; margin: 0; }
45
+ #url { width: 100%; background: #111; color: #eee; border: 1px solid #444; border-radius: 4px; padding: 5px 8px; font: inherit; }
46
+ #drive { min-width: 9em; text-align: right; color: #aaa; }
47
+ #drive.agent { color: #f0b429; }
48
+ #drive.person { color: #6cc070; }
49
+ #notice { padding: 6px 10px; background: #5a3b00; color: #ffe2a8; }
50
+ #notice.fatal { background: #5a1a1a; color: #ffc4c4; }
51
+ #stage { flex: 1; min-height: 0; display: flex; align-items: flex-start; justify-content: center; overflow: auto; }
52
+ #screen { max-width: 100%; max-height: 100%; background: #000; outline: none; cursor: default; }
53
+ #screen:focus, #stage:focus-within #screen { box-shadow: 0 0 0 2px #3b82f6; }
54
+ #still { padding: 6px 12px; background: #3a3a1a; color: #f3e9a8; border-bottom: 1px solid #5a5a2a; }
55
+ #sink { position: fixed; left: 0; bottom: 0; width: 1px; height: 1px; padding: 0; border: 0; opacity: 0; resize: none; overflow: hidden; pointer-events: none; font-size: 16px; }
56
+ #dialog { position: fixed; inset: 0; background: rgba(0, 0, 0, 0.6); display: flex; align-items: center; justify-content: center; }
57
+ #dialog[hidden], #notice[hidden], #dialog-prompt[hidden] { display: none; }
58
+ #dialog-box { background: #222; border: 1px solid #555; border-radius: 6px; padding: 16px; width: min(28em, 90vw); }
59
+ #dialog-kind { margin: 0 0 6px; color: #aaa; text-transform: uppercase; font-size: 12px; }
60
+ #dialog-message { margin: 0 0 12px; white-space: pre-wrap; overflow-wrap: anywhere; }
61
+ #dialog-prompt { width: 100%; margin: 0 0 12px; background: #111; color: #eee; border: 1px solid #444; border-radius: 4px; padding: 5px 8px; font: inherit; }
62
+ #dialog-buttons { display: flex; gap: 8px; justify-content: flex-end; }
63
+ #dialog-buttons button { background: #333; color: #eee; border: 1px solid #444; border-radius: 4px; padding: 5px 14px; cursor: pointer; }
64
+ `;
65
+ const js = `"use strict";
66
+ (function () {
67
+ var params = new URLSearchParams(location.hash.slice(1));
68
+ var token = params.get("t");
69
+ // The fragment never stays in the address bar, the history or a screenshot of it.
70
+ history.replaceState(null, "", location.pathname + location.search);
71
+
72
+ var $ = function (id) { return document.getElementById(id); };
73
+ var canvas = $("screen");
74
+ var sink = $("sink");
75
+ // The page is shown on a canvas, which cannot take text: the keyboard's focus sits on a hidden textarea beside it, so a virtual keyboard and an IME have something to type into.
76
+ function focusScreen() { try { sink.focus({ preventScroll: true }); } catch (e) { canvas.focus(); } }
77
+ var ctx = canvas.getContext("2d");
78
+ var urlBox = $("url");
79
+ var notice = $("notice");
80
+ var drive = $("drive");
81
+ var frame = { w: 0, h: 0 };
82
+ var stillEl = $("still");
83
+ var stillTimer = null;
84
+ var drewSince = false;
85
+ var shownUrl = null;
86
+ // A page that gives no picture (a tab opened in the background, which Chrome does not paint) leaves the canvas as it was: after a while the viewer says so, and input still works.
87
+ function expectPicture() { drewSince = false; stillEl.hidden = true; clearTimeout(stillTimer); stillTimer = setTimeout(function () { if (!drewSince && !fatal) stillEl.hidden = false; }, 2500); }
88
+ function gotPicture() { drewSince = true; clearTimeout(stillTimer); stillEl.hidden = true; }
89
+ var fatal = false;
90
+
91
+ function say(text, isFatal) {
92
+ if (!text) { notice.hidden = true; notice.textContent = ""; return; }
93
+ notice.hidden = false;
94
+ notice.textContent = text;
95
+ notice.className = isFatal ? "fatal" : "";
96
+ }
97
+ function setDrive(state) {
98
+ drive.className = state === "agent" || state === "person" ? state : "";
99
+ drive.textContent = state === "agent" ? "the agent is acting" : state === "person" ? "you are driving" : "";
100
+ }
101
+
102
+ if (!token) { fatal = true; say("This link has no token. Open the live view from the link the host gave you.", true); return; }
103
+ var proto = location.protocol === "https:" ? "wss://" : "ws://";
104
+ var ws = new WebSocket(proto + location.host + location.pathname.replace(/\\/$/, "") + "/ws");
105
+ ws.binaryType = "arraybuffer";
106
+ var ready = false;
107
+ var closed = false;
108
+ var CONNECTING = "Connecting to the browser. Input is not sent until it is ready.";
109
+ var WAITING = "Still connecting: that input was not sent. Try again when this message goes away.";
110
+ say(CONNECTING);
111
+
112
+ // Input before the host's ready is refused out loud and never queued: a keystroke replayed into a page the person has since lost sight of is worse than one that was not sent. A hover is not worth a notice.
113
+ function stillConnecting() { if (ready || fatal || closed) return false; say(WAITING); return true; }
114
+ function send(message) {
115
+ if (!ready) { if (!(message.type === "mouse" && message.action === "move")) stillConnecting(); return; }
116
+ if (ws.readyState === 1) ws.send(JSON.stringify(message));
117
+ }
118
+ ws.onopen = function () { ws.send(JSON.stringify({ type: "hello", token: token })); token = null; };
119
+
120
+ // Frames: the latest only. A decode in flight and one waiting; a newer frame replaces the one waiting.
121
+ var decoding = false;
122
+ var waiting = null;
123
+ function draw(buffer) {
124
+ if (buffer.byteLength <= 4) { decoding = false; return; }
125
+ var view = new DataView(buffer);
126
+ var w = view.getUint16(0);
127
+ var h = view.getUint16(2);
128
+ var blob = new Blob([new Uint8Array(buffer, 4)], { type: "image/jpeg" });
129
+ createImageBitmap(blob).then(function (bitmap) {
130
+ if (canvas.width !== bitmap.width || canvas.height !== bitmap.height) { canvas.width = bitmap.width; canvas.height = bitmap.height; }
131
+ ctx.drawImage(bitmap, 0, 0);
132
+ gotPicture();
133
+ if (bitmap.close) bitmap.close();
134
+ frame = { w: w || bitmap.width, h: h || bitmap.height };
135
+ }, function () {}).then(function () {
136
+ decoding = false;
137
+ if (waiting) { var next = waiting; waiting = null; decoding = true; draw(next); }
138
+ });
139
+ }
140
+
141
+ var dialogEl = $("dialog");
142
+ var promptEl = $("dialog-prompt");
143
+ function showDialog(d) {
144
+ $("dialog-kind").textContent = d.kind;
145
+ $("dialog-message").textContent = d.message;
146
+ promptEl.hidden = d.kind !== "prompt";
147
+ promptEl.value = d.defaultPrompt || "";
148
+ dialogEl.hidden = false;
149
+ (d.kind === "prompt" ? promptEl : $("dialog-accept")).focus();
150
+ }
151
+ function hideDialog() { dialogEl.hidden = true; focusScreen(); }
152
+ function answer(accept) {
153
+ var message = { type: "dialog", accept: accept };
154
+ if (!promptEl.hidden && accept) message.promptText = promptEl.value;
155
+ send(message);
156
+ }
157
+ $("dialog-accept").addEventListener("click", function () { answer(true); });
158
+ $("dialog-dismiss").addEventListener("click", function () { answer(false); });
159
+
160
+ var HELD = { agent_acting: "The agent is acting, so that input was held. Try again in a moment.", no_page: "There is no page to drive yet.", bad_message: "That input was not understood." };
161
+ var REFUSED = { unauthorized: "This link's token was not accepted.", viewer_in_use: "Another viewer already has this session.", released: "This session has been released.", bad_message: "The host did not understand this viewer." };
162
+ ws.onmessage = function (event) {
163
+ if (typeof event.data !== "string") {
164
+ if (decoding) { waiting = event.data; return; }
165
+ decoding = true;
166
+ draw(event.data);
167
+ return;
168
+ }
169
+ var m;
170
+ try { m = JSON.parse(event.data); } catch (e) { return; }
171
+ if (m.type === "ready") { ready = true; setDrive(m.drive); say(""); focusScreen(); expectPicture(); }
172
+ else if (m.type === "status") { setDrive(m.drive); if (m.drive !== "agent") say(""); else say("The agent is acting. Your input is held until it is done."); }
173
+ else if (m.type === "page") { document.title = m.title ? m.title + " - Live view" : "Live view"; if (document.activeElement !== urlBox) urlBox.value = m.url; if (m.url !== shownUrl) { shownUrl = m.url; expectPicture(); } }
174
+ else if (m.type === "dialog") showDialog(m);
175
+ else if (m.type === "dialog_closed") hideDialog();
176
+ else if (m.type === "held") say(HELD[m.reason] || "That input was held.");
177
+ else if (m.type === "refused") { fatal = true; ready = false; stillEl.hidden = true; say(REFUSED[m.reason] || "The host refused this viewer.", true); }
178
+ else if (m.type === "ended") { fatal = true; ready = false; say("This session has ended: the browser was released.", true); }
179
+ };
180
+ ws.onclose = function () { closed = true; ready = false; setDrive(""); if (!fatal) say("Disconnected. Open the live view link again.", true); };
181
+
182
+ // Input: the page's CSS pixels, from the canvas's own box and the latest frame's width and height.
183
+ var lastPoint = null;
184
+ function point(e) {
185
+ var rect = canvas.getBoundingClientRect();
186
+ if (!frame.w || !rect.width) return null;
187
+ var x = Math.round((e.clientX - rect.left) * (frame.w / rect.width));
188
+ var y = Math.round((e.clientY - rect.top) * (frame.h / rect.height));
189
+ // Kept inside the page's own area: a drag that leaves the canvas still names a place on the page.
190
+ lastPoint = { x: Math.max(0, Math.min(frame.w, x)), y: Math.max(0, Math.min(frame.h, y)) };
191
+ return lastPoint;
192
+ }
193
+ function mods(e) { return (e.altKey ? 1 : 0) | (e.ctrlKey ? 2 : 0) | (e.metaKey ? 4 : 0) | (e.shiftKey ? 8 : 0); }
194
+ var BUTTONS = ["left", "middle", "right"];
195
+ var moved = null;
196
+ var scheduled = false;
197
+ var pressing = false;
198
+ // The buttons the page believes are held (MouseEvent.buttons: left 1, right 2, middle 4), so a window that loses focus can release each by its own name.
199
+ var heldButtons = 0;
200
+ // Moves are coalesced to one per animation frame; a button event must not overtake the move before it, so it flushes the pending move first.
201
+ function flushMove() { if (moved) { send(moved); moved = null; } }
202
+ function queueMove(e, p) {
203
+ if (pressing) heldButtons = e.buttons;
204
+ moved = { type: "mouse", action: "move", x: p.x, y: p.y, buttons: e.buttons, modifiers: mods(e) };
205
+ if (!scheduled) { scheduled = true; requestAnimationFrame(function () { scheduled = false; flushMove(); }); }
206
+ }
207
+ function clicks(e) { return Math.max(1, Math.min(3, e.detail || 1)); }
208
+ function release(e, p) {
209
+ flushMove();
210
+ pressing = e.buttons !== 0;
211
+ heldButtons = e.buttons;
212
+ send({ type: "mouse", action: "up", x: p.x, y: p.y, button: BUTTONS[e.button] || "left", buttons: e.buttons, clickCount: clicks(e), modifiers: mods(e) });
213
+ }
214
+ canvas.addEventListener("mousemove", function (e) {
215
+ var p = point(e);
216
+ if (!p) return;
217
+ queueMove(e, p);
218
+ });
219
+ canvas.addEventListener("mousedown", function (e) {
220
+ focusScreen();
221
+ if (stillConnecting()) return;
222
+ var p = point(e);
223
+ if (!p) return;
224
+ e.preventDefault();
225
+ flushMove();
226
+ pressing = true;
227
+ heldButtons = e.buttons;
228
+ send({ type: "mouse", action: "down", x: p.x, y: p.y, button: BUTTONS[e.button] || "left", buttons: e.buttons, clickCount: clicks(e), modifiers: mods(e) });
229
+ });
230
+ canvas.addEventListener("mouseup", function (e) {
231
+ var p = point(e);
232
+ if (!p) return;
233
+ e.preventDefault();
234
+ release(e, p);
235
+ });
236
+ // A drag that leaves the canvas still ends where the person lets go, or the page keeps the button down: while a button is held, moves and the release outside the canvas are sent too, and a window that loses focus releases.
237
+ window.addEventListener("mousemove", function (e) {
238
+ if (!pressing || e.target === canvas) return;
239
+ var p = point(e);
240
+ if (p) queueMove(e, p);
241
+ });
242
+ window.addEventListener("mouseup", function (e) {
243
+ if (!pressing || e.target === canvas) return;
244
+ var p = point(e);
245
+ if (p) release(e, p);
246
+ });
247
+ window.addEventListener("blur", function () {
248
+ if (!pressing || !lastPoint) return;
249
+ flushMove();
250
+ var held = heldButtons || 1;
251
+ pressing = false;
252
+ heldButtons = 0;
253
+ // One release per held button, each by its own name and with the buttons still held after it: a right press is released as the right button, not the left.
254
+ [[4, "middle"], [2, "right"], [1, "left"]].forEach(function (pair) {
255
+ if (!(held & pair[0])) return;
256
+ held = held & ~pair[0];
257
+ send({ type: "mouse", action: "up", x: lastPoint.x, y: lastPoint.y, button: pair[1], buttons: held, clickCount: 1, modifiers: 0 });
258
+ });
259
+ });
260
+ canvas.addEventListener("contextmenu", function (e) { e.preventDefault(); });
261
+ canvas.addEventListener("wheel", function (e) {
262
+ if (stillConnecting()) return;
263
+ var p = point(e);
264
+ if (!p) return;
265
+ e.preventDefault();
266
+ var unit = e.deltaMode === 1 ? 16 : e.deltaMode === 2 ? frame.h : 1;
267
+ send({ type: "wheel", x: p.x, y: p.y, deltaX: Math.round(e.deltaX * unit), deltaY: Math.round(e.deltaY * unit), modifiers: mods(e) });
268
+ }, { passive: false });
269
+
270
+ // A key event can carry no code (a script's CDP keys, a virtual keyboard); the host refuses a message without one, so the viewer names the key: a letter or a digit by its own code, anything else Unidentified.
271
+ function codeOf(e) {
272
+ if (e.code) return e.code;
273
+ var k = e.key;
274
+ if (k.length === 1 && /[a-z]/i.test(k)) return "Key" + k.toUpperCase();
275
+ if (k.length === 1 && /[0-9]/.test(k)) return "Digit" + k;
276
+ return "Unidentified";
277
+ }
278
+ function keyMessage(action, e) {
279
+ var printable = e.key.length === 1 && !e.ctrlKey && !e.metaKey;
280
+ var text = printable ? e.key : e.key === "Enter" ? "\\r" : undefined;
281
+ var message = { type: "key", action: action, key: e.key, code: codeOf(e), windowsVirtualKeyCode: e.keyCode, modifiers: mods(e) };
282
+ if (text !== undefined && action === "down") message.text = text;
283
+ return message;
284
+ }
285
+ // A keydown the browser made for an IME or a virtual keyboard (keyCode 229, isComposing, or key "Unidentified") says nothing about what was typed: the text comes as input and composition events, below.
286
+ function textComesLater(e) { return e.isComposing || e.keyCode === 229 || e.key === "Unidentified"; }
287
+ function onKeyDown(e) {
288
+ if (textComesLater(e)) return;
289
+ // Paste arrives as a paste event with the text; the shortcut itself is not sent as keys.
290
+ if ((e.ctrlKey || e.metaKey) && (e.key === "v" || e.key === "V")) return;
291
+ e.preventDefault();
292
+ send(keyMessage("down", e));
293
+ }
294
+ function onKeyUp(e) {
295
+ if (textComesLater(e)) return;
296
+ if ((e.ctrlKey || e.metaKey) && (e.key === "v" || e.key === "V")) return;
297
+ e.preventDefault();
298
+ send(keyMessage("up", e));
299
+ }
300
+ function onPaste(e) {
301
+ var text = e.clipboardData ? e.clipboardData.getData("text/plain") : "";
302
+ e.preventDefault();
303
+ if (text) send({ type: "text", text: text });
304
+ }
305
+ [canvas, sink].forEach(function (el) {
306
+ el.addEventListener("keydown", onKeyDown);
307
+ el.addEventListener("keyup", onKeyUp);
308
+ el.addEventListener("paste", onPaste);
309
+ });
310
+
311
+ // Text that arrives without usable key events: a virtual keyboard's insertText, an autocorrection, its Enter and Backspace, and an IME's composition, whose text is sent once, when it ends.
312
+ var committed = { text: "", at: 0 };
313
+ function sendText(text) { if (text) send({ type: "text", text: text }); }
314
+ function sendKey(key, code, vk, text) {
315
+ var down = { type: "key", action: "down", key: key, code: code, windowsVirtualKeyCode: vk, modifiers: 0 };
316
+ if (text) down.text = text;
317
+ send(down);
318
+ send({ type: "key", action: "up", key: key, code: code, windowsVirtualKeyCode: vk, modifiers: 0 });
319
+ }
320
+ sink.addEventListener("beforeinput", function (e) {
321
+ if (e.isComposing) return;
322
+ var t = e.inputType;
323
+ if (t === "insertText" || t === "insertReplacementText") {
324
+ var text = e.data || (e.dataTransfer ? e.dataTransfer.getData("text/plain") : "");
325
+ e.preventDefault();
326
+ // Some browsers repeat a composition's text as an insertText right after it ends.
327
+ if (text && !(text === committed.text && Date.now() - committed.at < 100)) sendText(text);
328
+ } else if (t === "insertLineBreak" || t === "insertParagraph") { e.preventDefault(); sendKey("Enter", "Enter", 13, "\\r"); }
329
+ else if (t === "deleteContentBackward") { e.preventDefault(); sendKey("Backspace", "Backspace", 8); }
330
+ else if (t === "deleteContentForward") { e.preventDefault(); sendKey("Delete", "Delete", 46); }
331
+ });
332
+ sink.addEventListener("compositionend", function (e) {
333
+ if (e.data) { committed = { text: e.data, at: Date.now() }; sendText(e.data); }
334
+ sink.value = "";
335
+ });
336
+
337
+ $("back").addEventListener("click", function () { send({ type: "nav", action: "back" }); focusScreen(); });
338
+ $("reload").addEventListener("click", function () { send({ type: "nav", action: "reload" }); focusScreen(); });
339
+ $("go").addEventListener("submit", function (e) {
340
+ e.preventDefault();
341
+ var value = urlBox.value.trim();
342
+ if (!value) return;
343
+ if (!/^[a-z][a-z0-9+.-]*:/i.test(value)) value = "https://" + value;
344
+ send({ type: "nav", action: "url", url: value });
345
+ focusScreen();
346
+ });
347
+ })();
348
+ `;
349
+ /** The viewer page and its two static files, served by the live view's server (never an inline script or style: the page's policy is `default-src 'self'`). */
350
+ export const viewerAssets = Object.freeze({ html, js, css });
@@ -0,0 +1,19 @@
1
+ import type { IncomingMessage } from "node:http";
2
+ import type { Duplex } from "node:stream";
3
+ export type WsConn = {
4
+ /** False when the connection is closed. `done` runs once the bytes were handed to the operating system (or the connection ended). */
5
+ send(data: string | Uint8Array, done?: () => void): boolean;
6
+ /** Sends a close frame and ends the socket. Idempotent. */
7
+ close(code: number, reason?: string): void;
8
+ /** Bytes written and not yet taken by the network: a slow viewer shows here. */
9
+ readonly buffered: number;
10
+ readonly closed: boolean;
11
+ onMessage: (data: string | Buffer, binary: boolean) => void;
12
+ onClose: () => void;
13
+ };
14
+ export type WsOptions = {
15
+ maxPayload?: number;
16
+ };
17
+ /** Completes the handshake on `socket` and returns the connection; null (with the socket destroyed after a 400) when the request is not a valid
18
+ * WebSocket upgrade. The caller has already decided the request may proceed (path, Origin). */
19
+ export declare function acceptWebSocket(req: IncomingMessage, socket: Duplex, head: Buffer, options?: WsOptions): WsConn | null;
@@ -0,0 +1,176 @@
1
+ // A WebSocket server for one upgraded socket (RFC 6455): text and binary messages, fragmentation, ping/pong, close. It is as small as the
2
+ // viewer needs and takes no dependency. Client frames must be masked; a message larger than `maxPayload` ends the connection.
3
+ import { createHash } from "node:crypto";
4
+ const GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
5
+ /** A message of more frames than this is cut off (1009), whatever its bytes: input messages arrive whole or in a few frames. */
6
+ const MAX_FRAGMENTS = 64;
7
+ /** A client that pings and never reads its pongs is cut off past this many queued bytes. */
8
+ const MAX_QUEUED_WRITE = 1 << 20;
9
+ /** Completes the handshake on `socket` and returns the connection; null (with the socket destroyed after a 400) when the request is not a valid
10
+ * WebSocket upgrade. The caller has already decided the request may proceed (path, Origin). */
11
+ export function acceptWebSocket(req, socket, head, options = {}) {
12
+ const key = req.headers["sec-websocket-key"];
13
+ const upgrade = String(req.headers.upgrade ?? "").toLowerCase();
14
+ if (req.method !== "GET" || upgrade !== "websocket" || typeof key !== "string" || req.headers["sec-websocket-version"] !== "13") {
15
+ socket.end("HTTP/1.1 400 Bad Request\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
16
+ return null;
17
+ }
18
+ const maxPayload = options.maxPayload ?? 64 * 1024;
19
+ const accept = createHash("sha1").update(key + GUID).digest("base64");
20
+ socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`);
21
+ let closed = false;
22
+ let sentClose = false;
23
+ let buffer = head.length ? Buffer.from(head) : Buffer.alloc(0);
24
+ let fragments = [];
25
+ let fragmentBytes = 0;
26
+ /** How many frames the message being assembled has had, empty ones included: a message of unlimited empty fragments adds no bytes and would never reach the size cap. */
27
+ let fragmentFrames = 0;
28
+ /** A message is being assembled: its first frame was not final. Kept apart from `fragments`, which holds only frames that carry bytes. */
29
+ let inMessage = false;
30
+ let fragmentBinary = false;
31
+ const conn = {
32
+ send(data, done) {
33
+ if (closed || sentClose)
34
+ return false;
35
+ const payload = typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data.buffer, data.byteOffset, data.byteLength);
36
+ socket.write(frame(typeof data === "string" ? 0x1 : 0x2, payload), () => done?.());
37
+ return true;
38
+ },
39
+ close(code, reason = "") {
40
+ if (!sentClose && !closed) {
41
+ sentClose = true;
42
+ const text = Buffer.from(reason.slice(0, 100), "utf8");
43
+ const payload = Buffer.allocUnsafe(2 + text.length);
44
+ payload.writeUInt16BE(code, 0);
45
+ text.copy(payload, 2);
46
+ try {
47
+ socket.write(frame(0x8, payload));
48
+ }
49
+ catch { /* already gone */ }
50
+ }
51
+ // The socket ends after the close frame is flushed; a peer that never answers is cut off.
52
+ socket.end();
53
+ const timer = setTimeout(() => socket.destroy(), 1_000);
54
+ timer.unref();
55
+ },
56
+ get buffered() { return socket.writableLength; },
57
+ get closed() { return closed || sentClose; },
58
+ onMessage: () => { },
59
+ onClose: () => { },
60
+ };
61
+ const finish = () => { if (closed)
62
+ return; closed = true; conn.onClose(); };
63
+ const fail = (code, reason) => { conn.close(code, reason); };
64
+ const deliver = (binary, payload) => {
65
+ if (binary) {
66
+ conn.onMessage(payload, true);
67
+ return;
68
+ }
69
+ let text;
70
+ try {
71
+ text = new TextDecoder("utf-8", { fatal: true }).decode(payload);
72
+ }
73
+ catch {
74
+ fail(1007, "text is not utf-8");
75
+ return;
76
+ }
77
+ conn.onMessage(text, false);
78
+ };
79
+ const drain = () => {
80
+ while (!closed && !sentClose) {
81
+ if (buffer.length < 2)
82
+ return;
83
+ const first = buffer[0], second = buffer[1];
84
+ const fin = (first & 0x80) !== 0, opcode = first & 0x0f;
85
+ if ((first & 0x70) !== 0)
86
+ return fail(1002, "reserved bits");
87
+ if ((second & 0x80) === 0)
88
+ return fail(1002, "client frames are masked");
89
+ let length = second & 0x7f, offset = 2;
90
+ if (length === 126) {
91
+ if (buffer.length < 4)
92
+ return;
93
+ length = buffer.readUInt16BE(2);
94
+ offset = 4;
95
+ }
96
+ else if (length === 127) {
97
+ if (buffer.length < 10)
98
+ return;
99
+ const big = buffer.readBigUInt64BE(2);
100
+ if (big > BigInt(maxPayload))
101
+ return fail(1009, "message too big");
102
+ length = Number(big);
103
+ offset = 10;
104
+ }
105
+ if (length > maxPayload)
106
+ return fail(1009, "message too big");
107
+ if (buffer.length < offset + 4 + length)
108
+ return;
109
+ const mask = buffer.subarray(offset, offset + 4);
110
+ const payload = Buffer.allocUnsafe(length);
111
+ for (let i = 0; i < length; i += 1)
112
+ payload[i] = buffer[offset + 4 + i] ^ mask[i % 4];
113
+ buffer = buffer.subarray(offset + 4 + length);
114
+ if (opcode >= 0x8) {
115
+ if (!fin || length > 125)
116
+ return fail(1002, "bad control frame");
117
+ if (opcode === 0x8) {
118
+ conn.close(payload.length >= 2 ? payload.readUInt16BE(0) : 1000);
119
+ return;
120
+ }
121
+ if (opcode === 0x9) {
122
+ if (socket.writableLength > MAX_QUEUED_WRITE)
123
+ return fail(1008, "too slow to read");
124
+ if (!closed)
125
+ socket.write(frame(0xa, payload));
126
+ continue;
127
+ }
128
+ if (opcode === 0xa)
129
+ continue;
130
+ return fail(1002, "unknown opcode");
131
+ }
132
+ if (opcode === 0x0) {
133
+ if (!inMessage)
134
+ return fail(1002, "unexpected continuation");
135
+ }
136
+ else if (opcode === 0x1 || opcode === 0x2) {
137
+ if (inMessage)
138
+ return fail(1002, "interleaved message");
139
+ fragmentBinary = opcode === 0x2;
140
+ }
141
+ else
142
+ return fail(1002, "unknown opcode");
143
+ fragmentFrames += 1;
144
+ if (fragmentFrames > MAX_FRAGMENTS)
145
+ return fail(1009, "too many fragments");
146
+ if (payload.length > 0) {
147
+ fragments.push(payload);
148
+ fragmentBytes += payload.length;
149
+ }
150
+ if (fragmentBytes > maxPayload)
151
+ return fail(1009, "message too big");
152
+ inMessage = !fin;
153
+ if (fin) {
154
+ const whole = fragments.length === 1 ? fragments[0] : Buffer.concat(fragments);
155
+ fragments = [];
156
+ fragmentBytes = 0;
157
+ fragmentFrames = 0;
158
+ inMessage = false;
159
+ deliver(fragmentBinary, whole);
160
+ }
161
+ }
162
+ };
163
+ socket.on("data", (chunk) => { buffer = buffer.length ? Buffer.concat([buffer, chunk]) : chunk; drain(); });
164
+ // An HTTP server's sockets allow half-open: a viewer that vanishes sends only a FIN, and without answering it `close` never comes.
165
+ socket.on("end", () => { socket.end(); });
166
+ socket.on("close", finish);
167
+ socket.on("error", () => { socket.destroy(); finish(); });
168
+ if (buffer.length)
169
+ queueMicrotask(drain);
170
+ return conn;
171
+ }
172
+ function frame(opcode, payload) {
173
+ const n = payload.length;
174
+ const head = n < 126 ? Buffer.from([0x80 | opcode, n]) : n < 65536 ? Buffer.from([0x80 | opcode, 126, n >> 8, n & 0xff]) : (() => { const h = Buffer.alloc(10); h[0] = 0x80 | opcode; h[1] = 127; h.writeBigUInt64BE(BigInt(n), 2); return h; })();
175
+ return Buffer.concat([head, payload]);
176
+ }
@@ -0,0 +1,18 @@
1
+ import { type BrowserFailure } from "../core/failures.js";
2
+ import type { AttachTarget, BrowserProvider } from "../core/host.js";
3
+ import type { ResourceStatus } from "../core/lease.js";
4
+ export type AssignedSession = {
5
+ /** The session's id: the same for every attach. */
6
+ readonly id: string;
7
+ /** A fresh target for the driver; it names no secret in `sdkCdpUrl` (a relay or a signed URL goes in `dial`). A failure
8
+ * the model should read is thrown as an error carrying `failure`. */
9
+ attach(signal?: AbortSignal): Promise<AttachTarget>;
10
+ status(signal?: AbortSignal): Promise<ResourceStatus>;
11
+ /** Why the session can no longer be used (the host fenced it, took it back, it ended), or null while it can. */
12
+ failure?(): BrowserFailure | null;
13
+ };
14
+ export declare function assignedSessionProvider(input: {
15
+ name: string;
16
+ session: AssignedSession;
17
+ maxLifetimeS?: number;
18
+ }): BrowserProvider;
@@ -0,0 +1,76 @@
1
+ // A provider over the one session a host assigned to the run (Parcha's site child: the session it reserved for this task).
2
+ // It never creates or ends a browser. create hands that session to one custody at a time, every attach asks the host for a
3
+ // fresh target (a relay's capability rotates), and release lets go of that custody's hold without asking the host: a
4
+ // custody releases at a failed launch, an orphan sweep or a conversation's end, and the session is the task's, not the
5
+ // conversation's. The host takes it back itself, once, when the task's browser closes; after that the session's own
6
+ // failure() answers every create. A second create while another custody holds it is a refusal: the run has one browser.
7
+ import { BrowserFailureError } from "../core/custody.js";
8
+ import { FAILURE_CODES } from "../core/failures.js";
9
+ const refused = (message) => new BrowserFailureError({ ok: false, code: "refused", retryable: false, effect: "none", message });
10
+ /** A host session types a failure the model should read as an error carrying `failure`; the tool loop takes it as is. */
11
+ function typed(error) {
12
+ const failure = error?.failure;
13
+ if (error instanceof BrowserFailureError || !failure || failure.ok !== false || !FAILURE_CODES.includes(failure.code))
14
+ return error;
15
+ return new BrowserFailureError(failure);
16
+ }
17
+ let assignedHolds;
18
+ const assignedHoldOf = (session) => {
19
+ assignedHolds ??= new WeakMap();
20
+ let assignedCustody = assignedHolds.get(session);
21
+ if (!assignedCustody) {
22
+ assignedCustody = { heldBy: null, letGo: new Set() };
23
+ assignedHolds.set(session, assignedCustody);
24
+ }
25
+ return assignedCustody;
26
+ };
27
+ export function assignedSessionProvider(input) {
28
+ const { session } = input;
29
+ const caps = { timeoutModel: "wall-clock", maxLifetimeS: input.maxLifetimeS ?? 21_600, survivesDisconnect: true, releaseIsAsync: false, extension: "preinstalled", fixedSession: true,
30
+ // The host made the session and owns its sign-in: none of the run's session settings is applied, and no saved profile
31
+ // can be loaded into it.
32
+ settings: { proxies: false, verified: false, geolocation: false, region: false, context: false }, profiles: false };
33
+ // A hold its custody let go of is over for that custody; the session goes on for the next one.
34
+ const assignedCustody = assignedHoldOf(session);
35
+ const ours = (ref) => ref.id === session.id;
36
+ return {
37
+ name: input.name,
38
+ caps,
39
+ async create(spec) {
40
+ // A session that can no longer be used says why (a sign-in it needs, the host took it back), never that it is open elsewhere.
41
+ const ended = session.failure?.();
42
+ if (ended)
43
+ throw new BrowserFailureError(ended);
44
+ if (assignedCustody.heldBy !== null && assignedCustody.heldBy !== spec.tag)
45
+ throw refused("This task has one browser, the website session assigned to it, and it is already open; keep using it.");
46
+ assignedCustody.heldBy = spec.tag;
47
+ assignedCustody.letGo.delete(spec.tag);
48
+ return { id: session.id, tag: spec.tag };
49
+ },
50
+ findByTag: async (tag) => (assignedCustody.heldBy === tag ? [{ id: session.id, tag }] : []),
51
+ async status(ref, signal) {
52
+ if (!ours(ref))
53
+ return "gone";
54
+ if (assignedCustody.letGo.has(ref.tag))
55
+ return "stopped";
56
+ return session.status(signal);
57
+ },
58
+ async attach(ref, signal) {
59
+ if (!ours(ref))
60
+ throw new Error("this session is not the one the host assigned to the run");
61
+ try {
62
+ return await session.attach(signal);
63
+ }
64
+ catch (error) {
65
+ throw typed(error);
66
+ }
67
+ },
68
+ async release(ref) {
69
+ if (!ours(ref))
70
+ return;
71
+ if (assignedCustody.heldBy === ref.tag)
72
+ assignedCustody.heldBy = null;
73
+ assignedCustody.letGo.add(ref.tag);
74
+ },
75
+ };
76
+ }