@parcha/pi-browser 0.1.0-beta.17 → 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
@@ -18,8 +18,18 @@ export function cdpCall(url, method, params = {}, timeoutMs = 5_000) {
18
18
  };
19
19
  const timer = setTimeout(() => finish(new Error(`the browser did not answer ${method}`)), timeoutMs);
20
20
  socket.onopen = () => socket.send(JSON.stringify({ id: 1, method, params }));
21
- socket.onmessage = (event) => { const reply = JSON.parse(String(event.data)); if (reply.id === 1)
22
- finish(reply.error ? new Error(String(reply.error.message ?? "refused")) : null, reply.result); };
21
+ // A throw in a socket listener ends the process: a frame that is not JSON is dropped, and the timeout still ends the call.
22
+ socket.onmessage = (event) => {
23
+ let reply;
24
+ try {
25
+ reply = JSON.parse(String(event.data));
26
+ }
27
+ catch {
28
+ return;
29
+ }
30
+ if (reply?.id === 1)
31
+ finish(reply.error ? new Error(String(reply.error.message ?? "refused")) : null, reply.result);
32
+ };
23
33
  socket.onerror = () => finish(new Error(`the CDP socket to ${new URL(url).host} failed`));
24
34
  });
25
35
  }
@@ -154,8 +154,12 @@ export async function copyProfile(from, to, signal) {
154
154
  await copyProfile(source, target, signal);
155
155
  else if (entry.isSymbolicLink())
156
156
  await symlink(await readlink(source), target);
157
- else if (entry.isFile())
158
- await pipeline(createReadStream(source), createWriteStream(target, { mode: (await stat(source)).mode & 0o777 }), signal ? { signal } : {});
157
+ else if (entry.isFile()) {
158
+ // The mode is read before either stream exists: a stream made first and left waiting on this await has nobody listening for its error if the file is gone
159
+ // by then, and a failed open with no listener is an unhandled 'error' event that ends the process. Inside pipeline, a failure of either stream is the pipeline's.
160
+ const mode = (await stat(source)).mode & 0o777;
161
+ await pipeline(createReadStream(source), createWriteStream(target, { mode }), signal ? { signal } : {});
162
+ }
159
163
  }
160
164
  catch (error) {
161
165
  if (error.code !== "ENOENT" || signal?.aborted)
@@ -205,10 +209,14 @@ async function prepareProfile(root, dir, profile, tag, owner, signal, remove) {
205
209
  * made on Windows, where Chrome's temp directory is not TMPDIR. */
206
210
  const TMP_MARKER = ".pib-tmpdir";
207
211
  const TMP_OWNER = ".pib-owner";
212
+ /** A saved lease's own record of its private TMPDIR, `<profileRoot>/.profiles/.leases/<tag>` (no profile name starts with a dot): the profile's marker is
213
+ * shared by every lease that runs on the saved profile (a replacement for a crashed browser overwrites it) and a restarted provider has no map, so this is
214
+ * the one place a later release finds it. A copied profile is the lease's own, and its marker is not shared. */
215
+ const leaseRecord = (root, tag) => path.join(root, ".profiles", ".leases", tag);
208
216
  const TMP_NAME = /^pib-[A-Za-z0-9]{6}$/;
209
217
  const SOCKET_PATH_MAX = 107;
210
218
  const SOCKET_PATH_TAIL = "/.org.chromium.Chromium.XXXXXX/SingletonSocket".length;
211
- async function makePrivateTmp(tag, profile, remove) {
219
+ async function makePrivateTmp(tag, profile, record, remove) {
212
220
  if (process.platform === "win32")
213
221
  return null;
214
222
  const base = os.tmpdir();
@@ -218,8 +226,14 @@ async function makePrivateTmp(tag, profile, remove) {
218
226
  try {
219
227
  await writeFile(path.join(dir, TMP_OWNER), tag);
220
228
  await writeFile(path.join(profile, TMP_MARKER), dir);
229
+ if (record) {
230
+ await mkdir(path.dirname(record), { recursive: true });
231
+ await writeFile(record, dir);
232
+ }
221
233
  }
222
234
  catch (error) {
235
+ if (record)
236
+ await rm(record, { force: true }).catch(() => undefined);
223
237
  // The directory is not recorded anywhere yet, so a setup that fails here removes it, and names it if it cannot.
224
238
  const left = await removeTree(dir, remove);
225
239
  throw left ? new ProfileNotRemovedError([dir], left.error, error) : error;
@@ -228,7 +242,13 @@ async function makePrivateTmp(tag, profile, remove) {
228
242
  }
229
243
  /** The private directory the profile names, when it is one this provider made for this tag. */
230
244
  async function ownedTmp(profile, tag) {
231
- const named = (await readFile(path.join(profile, TMP_MARKER), "utf8").catch(() => "")).trim();
245
+ return ownedBy((await readFile(path.join(profile, TMP_MARKER), "utf8").catch(() => "")).trim(), tag);
246
+ }
247
+ /** The private directory this lease's own record names, when it is one this provider made for this tag. */
248
+ async function recordedTmp(root, tag) {
249
+ return ownedBy((await readFile(leaseRecord(root, tag), "utf8").catch(() => "")).trim(), tag);
250
+ }
251
+ async function ownedBy(named, tag) {
232
252
  if (!named || !path.isAbsolute(named) || !TMP_NAME.test(path.basename(named)))
233
253
  return null;
234
254
  return (await readFile(path.join(named, TMP_OWNER), "utf8").catch(() => null)) === tag ? named : null;
@@ -319,6 +339,11 @@ export function cdpProvider(options, internals = {}) {
319
339
  /** The private TMPDIR of each lease this provider started, by tag: the profile's marker is the only record a restarted process has, and a profile
320
340
  * that something else removed first takes it along. */
321
341
  const privateTmps = new Map();
342
+ /** A lease whose private TMPDIR is gone (or never made) keeps neither its map entry nor its record. */
343
+ const forgetTmp = async (root, tag) => {
344
+ privateTmps.delete(tag);
345
+ await rm(leaseRecord(root, tag), { force: true }).catch(() => undefined);
346
+ };
322
347
  /** A spawned Chrome whose handle we hold is ours (a handle cannot name a recycled pid); after a restart, only while
323
348
  * the browser on the recorded port reports that pid. */
324
349
  const isOurs = async ({ pid, port }) => {
@@ -329,7 +354,7 @@ export function cdpProvider(options, internals = {}) {
329
354
  };
330
355
  return {
331
356
  name: "cdp",
332
- caps: { ...CAPS, profiles: "chrome" in options },
357
+ caps: { ...CAPS, profiles: "chrome" in options, ...("endpoint" in options ? { sharedBrowser: true } : {}) },
333
358
  ...(downloads ? { downloads } : {}),
334
359
  async create(spec, signal) {
335
360
  if ("endpoint" in options)
@@ -364,7 +389,7 @@ export function cdpProvider(options, internals = {}) {
364
389
  await writeFile(prefsFile, JSON.stringify({ ...prefs, ...keeping, download: { ...prefs.download, default_directory: downloadsDir(profileRoot, spec.tag), prompt_for_download: false }, savefile: { ...prefs.savefile, default_directory: downloadsDir(profileRoot, spec.tag) } }));
365
390
  // A file left by an earlier Chrome on this profile names a browser that is not this one.
366
391
  await rm(path.join(dir, "DevToolsActivePort"), { force: true });
367
- const tmp = await makePrivateTmp(spec.tag, dir, remove);
392
+ const tmp = await makePrivateTmp(spec.tag, dir, spec.profile?.save ? leaseRecord(profileRoot, spec.tag) : null, remove);
368
393
  if (tmp)
369
394
  privateTmps.set(spec.tag, tmp);
370
395
  const child = spawn(executablePath, [
@@ -384,7 +409,7 @@ export function cdpProvider(options, internals = {}) {
384
409
  if (child.pid === undefined) {
385
410
  await sleep(0);
386
411
  const left = await removeAll([dir, downloadsDir(profileRoot, spec.tag), ...(tmp ? [tmp] : [])], remove);
387
- privateTmps.delete(spec.tag);
412
+ await forgetTmp(profileRoot, spec.tag);
388
413
  const why = failed ?? new Error("Chrome could not be started");
389
414
  throw left ? new ProfileNotRemovedError(left.dirs, left.error, why) : why;
390
415
  }
@@ -468,10 +493,11 @@ export function cdpProvider(options, internals = {}) {
468
493
  // A saved lease's directory is a link to the profile the live browser runs on, so that browser is another lease's (a replacement
469
494
  // for a crashed one): this lease's own link and private TMPDIR are still its to remove, and nothing the browser holds is.
470
495
  freeWriter(local.tag);
471
- const mine = privateTmps.get(local.tag);
496
+ // Not the profile's marker, which the replacement has overwritten: the lease's own record names its directory, also after a restart.
497
+ const mine = privateTmps.get(local.tag) ?? await recordedTmp(options.chrome.profileRoot, local.tag);
472
498
  const left = await removeAll([dir, ...(mine ? [mine] : [])], remove);
473
499
  if (!mine || !left?.dirs.includes(mine))
474
- privateTmps.delete(local.tag);
500
+ await forgetTmp(options.chrome.profileRoot, local.tag);
475
501
  if (left)
476
502
  throw new ProfileNotRemovedError(left.dirs, left.error);
477
503
  return;
@@ -501,7 +527,7 @@ export function cdpProvider(options, internals = {}) {
501
527
  if (!("endpoint" in options) && SAFE_TAG.test(local.tag)) {
502
528
  const dir = profileDir(options.chrome.profileRoot, local.tag);
503
529
  const socketDir = await singletonDir(dir);
504
- const tmp = privateTmps.get(local.tag) ?? await ownedTmp(dir, local.tag);
530
+ const tmp = privateTmps.get(local.tag) ?? await recordedTmp(options.chrome.profileRoot, local.tag) ?? await ownedTmp(dir, local.tag);
505
531
  // All are always tried, the profile first named: the profile's link and marker are the only places the other directories' names are read, so
506
532
  // they are reported here with the profile's, not left for a later release to miss.
507
533
  const extras = [...new Set([...(socketDir ? [socketDir] : []), ...(tmp ? [tmp] : []), ...(extrasLeft.get(local.tag) ?? [])])];
@@ -512,7 +538,7 @@ export function cdpProvider(options, internals = {}) {
512
538
  else
513
539
  extrasLeft.delete(local.tag);
514
540
  if (!tmp || !stuck.includes(tmp))
515
- privateTmps.delete(local.tag);
541
+ await forgetTmp(options.chrome.profileRoot, local.tag);
516
542
  if (left)
517
543
  throw new ProfileNotRemovedError(left.dirs, left.error);
518
544
  }
@@ -13,6 +13,16 @@ export type FollowHandlers = {
13
13
  export type Follower = {
14
14
  /** Runs an expression in the followed page and gives its value; rejects when there is no page, the page errors or nothing answers in `ms`. */
15
15
  evaluate(expression: string, ms?: number): Promise<unknown>;
16
+ /** One screenshot of the followed page as it is now, sized like a screencast frame (JPEG, at most the options' width and height), with the page's own CSS size; rejects when there is no page, the browser refuses, nothing answers
17
+ * in `ms`, or the capture moved to another page meanwhile. For a page that does not repaint, so the screencast sends nothing. */
18
+ capture(ms?: number): Promise<{
19
+ bytes: Buffer;
20
+ page: {
21
+ deviceWidth: number;
22
+ deviceHeight: number;
23
+ epoch: number;
24
+ };
25
+ }>;
16
26
  /** Which page, at which moment of its life, the capture is on: it changes when the capture moves to another page and at every main-frame
17
27
  * navigation, so a frame held across a change can be told from one of the page now shown. */
18
28
  epoch(): number;
@@ -53,10 +53,10 @@ export function followPage(url, handlers, options) {
53
53
  clearTimeout(entry.timer);
54
54
  if (message.error)
55
55
  entry.reject(new Error(message.error.message ?? "the browser refused"));
56
- else if (message.result?.exceptionDetails)
56
+ else if (!entry.raw && message.result?.exceptionDetails)
57
57
  entry.reject(new Error("the page threw"));
58
58
  else
59
- entry.resolve(message.result?.result?.value);
59
+ entry.resolve(entry.raw ? message.result : message.result?.result?.value);
60
60
  return;
61
61
  }
62
62
  const { method, params, sessionId } = message;
@@ -126,6 +126,31 @@ export function followPage(url, handlers, options) {
126
126
  waiting.set(id, { resolve, reject, timer });
127
127
  });
128
128
  },
129
+ capture(ms = 4_000) {
130
+ const sessionId = current?.sessionId;
131
+ if (!sessionId || socket.readyState !== 1)
132
+ return Promise.reject(new Error("no page to capture"));
133
+ const at = epoch;
134
+ const ask = (method, params) => new Promise((resolve, reject) => {
135
+ const id = send(method, params, sessionId);
136
+ const timer = setTimeout(() => { waiting.delete(id); reject(new Error("the page did not answer")); }, ms);
137
+ timer.unref?.();
138
+ waiting.set(id, { resolve, reject, timer, raw: true });
139
+ });
140
+ return (async () => {
141
+ const view = (await ask("Page.getLayoutMetrics", {}))?.cssVisualViewport;
142
+ const w = Number(view?.clientWidth) || 0;
143
+ const h = Number(view?.clientHeight) || 0;
144
+ if (!(w > 0 && h > 0))
145
+ throw new Error("the page has no size");
146
+ const shot = await ask("Page.captureScreenshot", { format: "jpeg", quality: options.quality, clip: { x: Number(view.pageX) || 0, y: Number(view.pageY) || 0, width: w, height: h, scale: Math.min(1, options.maxWidth / w, options.maxHeight / h) } });
147
+ if (typeof shot?.data !== "string")
148
+ throw new Error("the browser sent no capture");
149
+ if (epoch !== at || current?.sessionId !== sessionId)
150
+ throw new Error("the capture moved to another page");
151
+ return { bytes: Buffer.from(shot.data, "base64"), page: { deviceWidth: w, deviceHeight: h, epoch: at } };
152
+ })();
153
+ },
129
154
  epoch: () => epoch,
130
155
  close() { closing = true; for (const entry of waiting.values()) {
131
156
  clearTimeout(entry.timer);
@@ -1,4 +1,5 @@
1
1
  import type { BrowserProvider } from "../core/host.js";
2
+ import type { LeaseRef } from "../core/lease.js";
2
3
  export type FrameData = {
3
4
  session: string;
4
5
  provider: string;
@@ -55,6 +56,12 @@ export type FrameRecorderOptions = {
55
56
  probeClock?: ProbeClock;
56
57
  /** Called with the probe clock's time as each check of the page is sent. */
57
58
  onProbe?: (at: number) => void;
59
+ /** Asked wherever the capture asks whether it is paused: true while the host does not want the session recorded (a person is driving it through a live view).
60
+ * While it is true no frame is stored and one `frame.gap` line (`credential_on_page`, detail `host`) marks the span, not one per skipped frame; when it turns false
61
+ * frames resume. It is read when a frame arrives (the frame is dropped, and the page is not checked) and again at the sink, the last step before a frame's write, so a frame
62
+ * queued behind another session's slow write is still held back (the guarantee: no frame is stored while the hold is true at its write). A span that begins and ends
63
+ * between two reads is not seen. A hold that throws counts as true; any answer but `true` as false. */
64
+ hold?: (ref: LeaseRef) => boolean;
58
65
  };
59
66
  export type ProbeClock = {
60
67
  now(): number;
@@ -7,6 +7,8 @@ const MAX_QUEUED_LINES = 32;
7
7
  const tagConversation = (tag) => { const m = /-(\d+)-\d+$/.exec(tag); return m ? Number(m[1]) : null; };
8
8
  /** One session asks its page at most 1000 / PROBE_GAP_MS = 20 times a second: arrival checks and delivery checks share one pace, each sent at least this far after the last. */
9
9
  const PROBE_GAP_MS = 50;
10
+ /** While the host holds a session, the hold is asked again this often (nothing else asks when the page does not repaint), so its lifting is seen. */
11
+ const HOLD_POLL_MS = 500;
10
12
  export function frameRecorder(options) {
11
13
  const maxFps = Math.max(1, Math.min(10, options.maxFps ?? 10));
12
14
  const maxWidth = Math.min(800, options.maxWidth ?? 800);
@@ -27,7 +29,7 @@ export function frameRecorder(options) {
27
29
  /** The timers of lines waiting or being written: unreferenced while the process lives on its own, referenced once `close` waits on them. */
28
30
  const sinkTimers = new Set();
29
31
  /** `make` builds the line when its turn comes (a gap reads the last frame that was saved by then). */
30
- const emit = (make) => {
32
+ const emit = (make, withhold) => {
31
33
  if (queued >= MAX_QUEUED_LINES) {
32
34
  counts.dropped += 1;
33
35
  return Promise.resolve(false);
@@ -36,8 +38,8 @@ export function frameRecorder(options) {
36
38
  let abandoned = false;
37
39
  let answered = false;
38
40
  let answer = () => { };
39
- const result = new Promise((resolve) => { answer = (ok) => { if (answered)
40
- return; answered = true; if (!ok)
41
+ const result = new Promise((resolve) => { answer = (ok, counted = true) => { if (answered)
42
+ return; answered = true; if (!ok && counted)
41
43
  counts.dropped += 1; resolve(ok); }; });
42
44
  const timer = setTimeout(() => { abandoned = true; answer(false); }, sinkTimeoutMs);
43
45
  sinkTimers.add(timer);
@@ -49,6 +51,11 @@ export function frameRecorder(options) {
49
51
  try {
50
52
  if (abandoned)
51
53
  return;
54
+ // The last step before the write: a frame that waited behind another session's slow write is judged by the hold as it is now, not as it was when it was queued.
55
+ if (withhold?.()) {
56
+ answer(false, false);
57
+ return;
58
+ }
52
59
  const [line, blobs] = make();
53
60
  await options.sink(line, blobs);
54
61
  answer(true); // too late to count when the timeout already answered
@@ -80,6 +87,63 @@ export function frameRecorder(options) {
80
87
  c.navigated = false;
81
88
  void gap(c, "credential_on_page", undefined, why ?? "field");
82
89
  };
90
+ /** The host's hold, read now. A hold that throws is a hold (a host that cannot say is not asked twice); anything but `true` is none. The first read of a span writes its one gap;
91
+ * the read that finds it over ends it. */
92
+ const held = (c) => {
93
+ if (!options.hold)
94
+ return false;
95
+ let on;
96
+ try {
97
+ on = options.hold(c.ref) === true;
98
+ }
99
+ catch {
100
+ on = true;
101
+ }
102
+ if (!on) {
103
+ if (c.hostHeld) {
104
+ c.hostHeld = false;
105
+ lifted(c);
106
+ }
107
+ return false;
108
+ }
109
+ if (!c.hostHeld) {
110
+ c.hostHeld = true;
111
+ if (!c.stopped) {
112
+ void gap(c, "credential_on_page", undefined, "host");
113
+ watchHold(c);
114
+ }
115
+ }
116
+ return true;
117
+ };
118
+ const watchHold = (c) => {
119
+ if (c.holdTimer)
120
+ return;
121
+ c.holdTimer = setInterval(() => { if (c.stopped || closed)
122
+ stopWatching(c);
123
+ else
124
+ held(c); }, HOLD_POLL_MS);
125
+ c.holdTimer.unref?.();
126
+ };
127
+ const stopWatching = (c) => { if (c.holdTimer)
128
+ clearInterval(c.holdTimer); c.holdTimer = null; };
129
+ /** The hold was true and is not: the screencast sends a frame only when the page repaints, and a person's login has often already left the page, so the replay would end at the hold. One frame of the page as it is
130
+ * now is asked for and judged like any other (a field still holding a value makes it the credential gap, not a frame). A failed capture costs this frame: the next screencast frame covers it. */
131
+ const lifted = (c) => { stopWatching(c); void captureNow(c); };
132
+ const captureNow = async (c) => {
133
+ const follower = c.follower;
134
+ if (!follower || c.stopped)
135
+ return;
136
+ try {
137
+ const seen = c.frameSeq;
138
+ const frame = await follower.capture();
139
+ // A screencast frame that came while the capture was in flight is a newer picture of the page: the late capture is dropped, so the replay never jumps back.
140
+ if (c.stopped || c.follower !== follower || c.frameSeq !== seen)
141
+ return;
142
+ c.waiting = frame;
143
+ judge(c);
144
+ }
145
+ catch { /* no capture this time */ }
146
+ };
83
147
  const check = async (c) => {
84
148
  try {
85
149
  options.onProbe?.(pclock.now());
@@ -174,7 +238,7 @@ export function frameRecorder(options) {
174
238
  return;
175
239
  const hash = createHash("sha256").update(frame.bytes).digest("hex");
176
240
  const t = options.clock();
177
- const saved = await emit(() => [{ ...base(c, t), kind: "frame", data: { session: c.ref.id, provider: c.provider, w: size.w, h: size.h, mime: "image/jpeg" }, blobs: [hash] }, { [hash]: new Uint8Array(frame.bytes) }]);
241
+ const saved = await emit(() => [{ ...base(c, t), kind: "frame", data: { session: c.ref.id, provider: c.provider, w: size.w, h: size.h, mime: "image/jpeg" }, blobs: [hash] }, { [hash]: new Uint8Array(frame.bytes) }], () => held(c));
178
242
  if (saved) {
179
243
  counts.frames += 1;
180
244
  c.lastFrameT = t;
@@ -191,7 +255,10 @@ export function frameRecorder(options) {
191
255
  frame(bytes, page) {
192
256
  if (c.stopped)
193
257
  return;
258
+ c.frameSeq += 1;
194
259
  // The newest frame wins: an older one still held is not worth keeping.
260
+ if (held(c))
261
+ return;
195
262
  c.waiting = { bytes, page };
196
263
  judge(c);
197
264
  },
@@ -214,7 +281,7 @@ export function frameRecorder(options) {
214
281
  return;
215
282
  if (captures.get(ref.id))
216
283
  return;
217
- const c = { ref, conv: owner, provider: provider.name, follower: null, lastFrameT: null, paused: false, navigated: false, ready: null, waiting: null, probing: false, lastProbeAt: -Infinity, pacing: Promise.resolve(), busy: false, timer: null, lastEmitMs: 0, stopped: false, reconnect: null };
284
+ const c = { ref, conv: owner, provider: provider.name, follower: null, lastFrameT: null, paused: false, navigated: false, hostHeld: false, holdTimer: null, frameSeq: 0, ready: null, waiting: null, probing: false, lastProbeAt: -Infinity, pacing: Promise.resolve(), busy: false, timer: null, lastEmitMs: 0, stopped: false, reconnect: null };
218
285
  captures.set(ref.id, c);
219
286
  // A session first seen in this process that an earlier process already framed: the frames stopped when that process was killed.
220
287
  if (!made.has(ref.id)) {
@@ -232,6 +299,7 @@ export function frameRecorder(options) {
232
299
  clearTimeout(c.timer);
233
300
  if (c.reconnect)
234
301
  clearTimeout(c.reconnect);
302
+ stopWatching(c);
235
303
  c.timer = null;
236
304
  c.reconnect = null;
237
305
  c.ready = null;
package/dist/store.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import type { Context } from "@earendil-works/chord";
2
- import { type ConversationDocToken, type ConversationId, type DocumentReader, type Harness, type Tx } from "@earendil-works/pi-durable";
3
- import type { BrowserConfig, BrowserProvider, InventoryRow, ReconcileReport, ReleaseReason, SessionChange, SessionRecord, SessionsState } from "./core/host.js";
2
+ import { type ConversationDocToken, type ConversationId, type DocumentReader, type Harness, type TaskId, type Tx } from "@earendil-works/pi-durable";
3
+ import type { BrowserConfig, BrowserProvider, HandoffOutcome, HandoffPort, InventoryRow, ReconcileReport, ReleaseReason, SessionChange, SessionRecord, SessionsState } from "./core/host.js";
4
4
  import type { LeaseRef, LeaseState } from "./core/lease.js";
5
5
  export declare const now: () => string;
6
6
  /** Release attempts before custody is given up as `lost`, and status polls before a release is sent again. */
@@ -12,6 +12,7 @@ type Move = {
12
12
  reason?: ReleaseReason;
13
13
  at: string;
14
14
  notice?: "kept" | "lost";
15
+ handoff?: string;
15
16
  };
16
17
  type ReleaseInput = {
17
18
  row: InventoryRow;
@@ -26,6 +27,15 @@ type ReleaseState = {
26
27
  ids: string[];
27
28
  polls: number;
28
29
  };
30
+ export type HandoffInput = {
31
+ row: InventoryRow;
32
+ requestId: string;
33
+ interactionId: string;
34
+ completionCondition: string;
35
+ };
36
+ type HandoffResult = {
37
+ outcome: HandoffOutcome;
38
+ };
29
39
  export type StoreDeps = {
30
40
  name: string;
31
41
  Config: ConversationDocToken<BrowserConfig>;
@@ -37,8 +47,11 @@ export type StoreDeps = {
37
47
  };
38
48
  scrubbed(error: unknown): Error;
39
49
  createDeadlineMs: number;
50
+ handoff?: HandoffPort;
51
+ /** A handoff's session came back under `fence`. */
52
+ handedBack?(tag: string, fence: number): void;
40
53
  };
41
- export declare function custodyStore({ name, Config, Sessions, providerOf, emit, meter, scrubbed, createDeadlineMs }: StoreDeps): {
54
+ export declare function custodyStore({ name, Config, Sessions, providerOf, emit, meter, scrubbed, createDeadlineMs, handoff, handedBack }: StoreDeps): {
42
55
  Inventory: import("@earendil-works/pi-durable").SessionDocToken<{
43
56
  rows: Record<string, InventoryRow>;
44
57
  }>;
@@ -51,6 +64,12 @@ export declare function custodyStore({ name, Config, Sessions, providerOf, emit,
51
64
  ReleaseTask: import("@earendil-works/pi-durable").Task<ReleaseInput, ReleaseState, {
52
65
  released: number;
53
66
  }, object>;
67
+ HandoffTask: import("@earendil-works/pi-durable").Task<HandoffInput, {
68
+ phase: "poll";
69
+ attempt: number;
70
+ }, HandoffResult, object>;
71
+ waitForHandoff: (tx: Tx, input: HandoffInput) => Promise<TaskId<HandoffResult>>;
72
+ findHandoff: (tx: Tx, cid: ConversationId, requestId: string) => Promise<TaskId<HandoffResult> | undefined>;
54
73
  reconcileAll: (harness: Harness, isActive: (conversationId: ConversationId) => boolean, context: Context) => Promise<ReconcileReport>;
55
74
  };
56
75
  export {};
package/dist/store.js CHANGED
@@ -1,13 +1,12 @@
1
1
  import { defineDoc, defineTask } from "@earendil-works/pi-durable";
2
- import { moveRecord, notices } from "./core/custody.js";
2
+ import { backoffMs, moveRecord, notices } from "./core/custody.js";
3
3
  export const now = () => new Date().toISOString();
4
4
  const iso = (ms) => new Date(ms).toISOString();
5
5
  const cidOf = (row) => row.conversationId;
6
6
  /** Release attempts before custody is given up as `lost`, and status polls before a release is sent again. */
7
7
  export const RELEASE_ATTEMPTS = 6;
8
8
  export const CONFIRM_POLLS = 5;
9
- const backoffMs = (n) => Math.min(30_000, 500 * 2 ** n);
10
- export function custodyStore({ name, Config, Sessions, providerOf, emit, meter, scrubbed, createDeadlineMs }) {
9
+ export function custodyStore({ name, Config, Sessions, providerOf, emit, meter, scrubbed, createDeadlineMs, handoff, handedBack }) {
11
10
  const Inventory = defineDoc({ kind: `${name}.inventory`, version: 1, scope: "session", initial: () => ({ rows: {} }) });
12
11
  /** One state change: the record and the open-session inventory move in the same commit. */
13
12
  async function move(tx, row, next) {
@@ -149,6 +148,76 @@ export function custodyStore({ name, Config, Sessions, providerOf, emit, meter,
149
148
  }, context);
150
149
  },
151
150
  });
151
+ /** Polls the port until it answers, then gives the session back with the outcome's notice, if it is still held for
152
+ * this request. */
153
+ const HandoffTask = defineTask({
154
+ name: `${name}.handoff`,
155
+ version: 1,
156
+ initial: () => ({ phase: "poll", attempt: 0 }),
157
+ phases: {
158
+ poll: async (task, runtime, context) => {
159
+ const { row, requestId, interactionId, completionCondition } = task.input;
160
+ const { attempt } = task.state.checkpoint;
161
+ // A session no longer held for this request (the provider stopped it and a reconcile released it, or it was
162
+ // given back) leaves nothing to wait for: the wait ends at once, and the call says the handoff ended.
163
+ let over = false;
164
+ await runtime.commit(async (tx) => {
165
+ const record = (await tx.doc(Sessions, cidOf(row))).sessions.find((r) => r.tag === row.tag);
166
+ if (record?.state === "held" && record.handoff === requestId)
167
+ return undefined;
168
+ over = true;
169
+ return { status: "terminal", outcome: { status: "failed", error: { code: "handoff_ended", message: `${row.tag}: no longer held for ${requestId}` } } };
170
+ }, context);
171
+ if (over)
172
+ return;
173
+ let answer = "pending";
174
+ try {
175
+ if (handoff)
176
+ answer = await handoff.outcome(interactionId, runtime.signal);
177
+ }
178
+ catch (error) {
179
+ if (runtime.signal.aborted)
180
+ throw error;
181
+ runtime.report(scrubbed(error));
182
+ }
183
+ if (answer === "pending") {
184
+ await runtime.sleep(runtime.now() + backoffMs(attempt), context);
185
+ await runtime.commit(() => ({ status: "running", checkpoint: { phase: "poll", attempt: attempt + 1 } }), context);
186
+ return;
187
+ }
188
+ const outcome = answer;
189
+ await runtime.commit(async (tx) => {
190
+ const state = await tx.doc(Sessions, cidOf(row));
191
+ const record = state.sessions.find((r) => r.tag === row.tag);
192
+ if (record?.state === "held" && record.handoff === requestId) {
193
+ await move(tx, row, { state: "live", at: iso(runtime.now()) });
194
+ addNotice(state, notices.handedBack(outcome, completionCondition));
195
+ handedBack?.(row.tag, record.fence ?? 0);
196
+ }
197
+ return { status: "terminal", outcome: { status: "completed", result: { outcome } } };
198
+ }, context);
199
+ },
200
+ },
201
+ abort: async (task, runtime, context) => {
202
+ await runtime.commit(async (tx) => {
203
+ await waitForHandoff(tx, task.input);
204
+ return { status: "terminal", outcome: { status: "aborted", reason: "the wait was handed to a successor task" } };
205
+ }, context);
206
+ },
207
+ });
208
+ const waitForHandoff = (tx, input) => tx.createTask(HandoffTask, input, { ownership: { kind: "conversation" }, conversationId: cidOf(input.row), background: true });
209
+ /** A request's newest wait: a successor is newer than the task it replaced. */
210
+ async function findHandoff(tx, cid, requestId) {
211
+ let cursor;
212
+ do {
213
+ const page = await tx.scanTasks({ conversationId: cid, kind: `${name}.handoff`, order: "descending" }, 50, cursor);
214
+ const found = page.items.find((task) => task.input.requestId === requestId);
215
+ if (found)
216
+ return found.id;
217
+ cursor = page.next;
218
+ } while (cursor);
219
+ return undefined;
220
+ }
152
221
  async function reconcileAll(harness, isActive, context) {
153
222
  const report = { released: [], kept: [], lost: [], unreachable: [] };
154
223
  for (const row of Object.values((await harness.snapshot(Inventory, context))?.rows ?? {})) {
@@ -181,6 +250,8 @@ export function custodyStore({ name, Config, Sessions, providerOf, emit, meter,
181
250
  const status = await provider.status({ id: live.resourceId, tag: live.tag });
182
251
  if (status === "gone" || status === "stopped")
183
252
  await outcome("lost", (tx) => move(tx, live, { state: "released", reason: "ended", at, notice: "lost" }));
253
+ else if (row.state === "held")
254
+ await outcome("kept");
184
255
  else if (isActive(cidOf(row)))
185
256
  await outcome("kept", (tx) => move(tx, live, { state: "live", at, notice: "kept" }));
186
257
  else
@@ -192,5 +263,5 @@ export function custodyStore({ name, Config, Sessions, providerOf, emit, meter,
192
263
  }
193
264
  return report;
194
265
  }
195
- return { Inventory, move, addNotice, begin, requestRelease, bindByTag, emitReleased, ReleaseTask, reconcileAll };
266
+ return { Inventory, move, addNotice, begin, requestRelease, bindByTag, emitReleased, ReleaseTask, HandoffTask, waitForHandoff, findHandoff, reconcileAll };
196
267
  }
@@ -75,14 +75,23 @@ export type FakeBackendOptions = {
75
75
  height: number;
76
76
  };
77
77
  fullPageHeight?: number;
78
+ /** What `locate` finds, by the snapshot ID or the CSS selector a caller gives: one box or several (a selector that matches more than one). Anything else matches nothing. */
79
+ elements?: Record<string, FakeBox | FakeBox[]>;
78
80
  /** Device pixels per CSS pixel; a screenshot is this many times larger unless it asks for `scale: "css"`. */
79
81
  deviceScale?: number;
80
82
  };
83
+ export type FakeBox = {
84
+ x: number;
85
+ y: number;
86
+ width: number;
87
+ height: number;
88
+ };
81
89
  export type FakeScreenshotOptions = {
82
90
  fullPage?: boolean;
83
91
  type?: "png" | "jpeg";
84
92
  quality?: number;
85
93
  scale?: "css" | "device";
94
+ clip?: FakeBox;
86
95
  };
87
96
  /** A PNG or JPEG whose header declares `width` x `height`: enough for a reader that decodes the header, not a picture. */
88
97
  export declare function fakeImage(type: "png" | "jpeg", width: number, height: number): Buffer;
@@ -225,7 +234,24 @@ export declare class FakeDriverFace {
225
234
  width: number;
226
235
  height: number;
227
236
  }>;
237
+ /** No `dispatched` row: where an element is is not a read of the page. */
238
+ locate(id: string, target?: {
239
+ id?: string;
240
+ selector?: string;
241
+ }): Promise<{
242
+ viewport: {
243
+ width: number;
244
+ height: number;
245
+ };
246
+ matches?: number;
247
+ box?: FakeBox | null;
248
+ }>;
228
249
  page(id: string): Promise<FixturePage>;
250
+ setInputFiles(id: string, selector: string, file: {
251
+ name: string;
252
+ mimeType: string;
253
+ buffer: Uint8Array | string;
254
+ }): Promise<void>;
229
255
  close(id: string): Promise<void>;
230
256
  }
231
257
  export {};
@@ -1,3 +1,4 @@
1
+ import { createHash } from "node:crypto";
1
2
  import { EventEmitter } from "node:events";
2
3
  import { crc32 } from "node:zlib";
3
4
  import fs from "node:fs";
@@ -358,7 +359,8 @@ export class FakeDriverFace {
358
359
  }
359
360
  pageOf(id) {
360
361
  const url = this.session(id).url;
361
- return this.b.pages[url] ?? fixturePage(url, "");
362
+ // A page no test registered: about:blank is empty, as a real browser's is; any other URL is a bare fixture.
363
+ return this.b.pages[url] ?? (url === "about:blank" ? { url, title: "", text: "", html: "" } : fixturePage(url, ""));
362
364
  }
363
365
  async call(id, op, knob, detail = {}) {
364
366
  await this.b.before(`driver.${knob}`);
@@ -396,18 +398,34 @@ export class FakeDriverFace {
396
398
  await this.call(id, "screenshot", "screenshot", { options });
397
399
  const { viewport = { width: 1288, height: 711 }, fullPageHeight = 8319, deviceScale = 1 } = this.b.opts;
398
400
  const factor = options.scale === "css" ? 1 : deviceScale;
399
- const width = viewport.width * factor;
400
- const height = (options.fullPage ? fullPageHeight : viewport.height) * factor;
401
+ const width = (options.clip ? options.clip.width : viewport.width) * factor;
402
+ const height = (options.clip ? options.clip.height : options.fullPage ? fullPageHeight : viewport.height) * factor;
401
403
  const type = options.type ?? "jpeg";
402
404
  await this.b.after("driver.screenshot");
403
405
  return { data: fakeImage(type, width, height).toString("base64"), mimeType: `image/${type}`, width, height };
404
406
  }
407
+ /** No `dispatched` row: where an element is is not a read of the page. */
408
+ async locate(id, target) {
409
+ await this.b.before("driver.locate");
410
+ this.session(id);
411
+ const viewport = this.b.opts.viewport ?? { width: 1288, height: 711 };
412
+ if (!target)
413
+ return { viewport };
414
+ const found = this.b.opts.elements?.[target.id ?? target.selector ?? ""];
415
+ const boxes = found === undefined ? [] : Array.isArray(found) ? found : [found];
416
+ return { viewport, matches: boxes.length, box: boxes.length === 1 ? boxes[0] : null };
417
+ }
405
418
  async page(id) {
406
419
  await this.call(id, "read", "page");
407
420
  const out = { ...this.pageOf(id) };
408
421
  await this.b.after("driver.page");
409
422
  return out;
410
423
  }
424
+ async setInputFiles(id, selector, file) {
425
+ const bytes = typeof file.buffer === "string" ? Buffer.from(file.buffer, "base64") : Buffer.from(file.buffer);
426
+ await this.call(id, "setInputFiles", "setInputFiles", { selector, name: file.name, mimeType: file.mimeType, bytes: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") });
427
+ await this.b.after("driver.setInputFiles");
428
+ }
411
429
  async close(id) {
412
430
  this.b.dispatched.push({ op: "close", session: id, url: null });
413
431
  }