@parcha/pi-browser 0.1.0-beta.33 → 0.1.0-beta.34

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 +17 -0
  2. package/NOTICE +30 -0
  3. package/README.md +28 -178
  4. package/dist/core/contract.js +14 -5
  5. package/dist/core/custody.d.ts +6 -0
  6. package/dist/core/custody.js +6 -0
  7. package/dist/core/driving-guard.js +17 -2
  8. package/dist/core/host.d.ts +2 -2
  9. package/dist/core/tools.d.ts +9 -0
  10. package/dist/driver/cdp.d.ts +6 -0
  11. package/dist/driver/cdp.js +245 -0
  12. package/dist/driver/page-driver.js +29 -3
  13. package/dist/durable/store.js +13 -4
  14. package/dist/durable.d.ts +1 -0
  15. package/dist/durable.js +1 -0
  16. package/dist/live-view/provider.d.ts +2 -2
  17. package/dist/live-view/provider.js +2 -2
  18. package/dist/live-view/server.d.ts +1 -1
  19. package/dist/providers/chrome-args.d.ts +3 -0
  20. package/dist/providers/chrome-args.js +13 -2
  21. package/dist/vendor/browser-use-pi/ax.d.ts +106 -0
  22. package/dist/vendor/browser-use-pi/ax.js +642 -0
  23. package/dist/vendor/browser-use-pi/cdp.d.ts +19 -0
  24. package/dist/vendor/browser-use-pi/cdp.js +106 -0
  25. package/dist/vendor/browser-use-pi/page.d.ts +38 -0
  26. package/dist/vendor/browser-use-pi/page.js +112 -0
  27. package/package.json +6 -24
  28. package/src/vendor/browser-use-pi/UPSTREAM.json +25 -0
  29. package/src/vendor/stagehand-facade/UPSTREAM.json +0 -4
  30. package/dist/coding-agent-local.d.ts +0 -12
  31. package/dist/coding-agent-local.js +0 -72
  32. package/dist/coding-agent.d.ts +0 -135
  33. package/dist/coding-agent.js +0 -641
  34. package/dist/providers/assigned.d.ts +0 -18
  35. package/dist/providers/assigned.js +0 -75
  36. package/dist/recorder/credential.d.ts +0 -9
  37. package/dist/recorder/credential.js +0 -49
  38. package/dist/recorder/follow.d.ts +0 -36
  39. package/dist/recorder/follow.js +0 -163
  40. package/dist/recorder/frames.d.ts +0 -87
  41. package/dist/recorder/frames.js +0 -377
  42. package/dist/recorder/index.d.ts +0 -4
  43. package/dist/recorder/index.js +0 -7
  44. package/dist/recorder/jpeg.d.ts +0 -8
  45. package/dist/recorder/jpeg.js +0 -70
  46. package/dist/recorder/track.d.ts +0 -107
  47. package/dist/recorder/track.js +0 -280
  48. package/dist/vendor/stagehand-facade/screenshot-transport.d.ts +0 -15
  49. package/dist/vendor/stagehand-facade/screenshot-transport.js +0 -51
@@ -1,75 +0,0 @@
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, refusedError } from "../core/custody.js";
8
- import { FAILURE_CODES } from "../core/failures.js";
9
- /** A host session types a failure the model should read as an error carrying `failure`; the tool loop takes it as is. */
10
- function typed(error) {
11
- const failure = error?.failure;
12
- if (error instanceof BrowserFailureError || !failure || failure.ok !== false || !FAILURE_CODES.includes(failure.code))
13
- return error;
14
- return new BrowserFailureError(failure);
15
- }
16
- let assignedHolds;
17
- const assignedHoldOf = (session) => {
18
- assignedHolds ??= new WeakMap();
19
- let assignedCustody = assignedHolds.get(session);
20
- if (!assignedCustody) {
21
- assignedCustody = { heldBy: null, letGo: new Set() };
22
- assignedHolds.set(session, assignedCustody);
23
- }
24
- return assignedCustody;
25
- };
26
- export function assignedSessionProvider(input) {
27
- const { session } = input;
28
- const caps = { timeoutModel: "wall-clock", maxLifetimeS: input.maxLifetimeS ?? 21_600, survivesDisconnect: true, releaseIsAsync: false, extension: "preinstalled", fixedSession: true,
29
- // The host made the session and owns its sign-in: none of the run's session settings is applied, and no saved profile
30
- // can be loaded into it.
31
- settings: { proxies: false, verified: false, geolocation: false, region: false, context: false }, profiles: false };
32
- // A hold its custody let go of is over for that custody; the session goes on for the next one.
33
- const assignedCustody = assignedHoldOf(session);
34
- const ours = (ref) => ref.id === session.id;
35
- return {
36
- name: input.name,
37
- caps,
38
- async create(spec) {
39
- // 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.
40
- const ended = session.failure?.();
41
- if (ended)
42
- throw new BrowserFailureError(ended);
43
- if (assignedCustody.heldBy !== null && assignedCustody.heldBy !== spec.tag)
44
- throw refusedError("This task has one browser, the website session assigned to it, and it is already open; keep using it.");
45
- assignedCustody.heldBy = spec.tag;
46
- assignedCustody.letGo.delete(spec.tag);
47
- return { id: session.id, tag: spec.tag };
48
- },
49
- findByTag: async (tag) => (assignedCustody.heldBy === tag ? [{ id: session.id, tag }] : []),
50
- async status(ref, signal) {
51
- if (!ours(ref))
52
- return "gone";
53
- if (assignedCustody.letGo.has(ref.tag))
54
- return "stopped";
55
- return session.status(signal);
56
- },
57
- async attach(ref, signal) {
58
- if (!ours(ref))
59
- throw new Error("this session is not the one the host assigned to the run");
60
- try {
61
- return await session.attach(signal);
62
- }
63
- catch (error) {
64
- throw typed(error);
65
- }
66
- },
67
- async release(ref) {
68
- if (!ours(ref))
69
- return;
70
- if (assignedCustody.heldBy === ref.tag)
71
- assignedCustody.heldBy = null;
72
- assignedCustody.letGo.add(ref.tag);
73
- },
74
- };
75
- }
@@ -1,9 +0,0 @@
1
- /** Run in the page: whether any field holding a credential or a one-time code has a value. It looks at password fields, fields that say
2
- * `one-time-code`, and fields whose name, id, label (a `<label>` for it or around it, or `aria-labelledby`), `aria-label` or placeholder names
3
- * a code (otp, totp, 2fa, passcode, ...), in the document, in open shadow roots and in same-origin frames. The answer is `true` when one holds
4
- * a value now (`why: "field"`), or held one since the last check (`why: "typed"`: the page keeps a flag, set by the fields' own `input` events,
5
- * that a check reports once and clears). Anything it cannot read counts as a credential being present: a page that nests deeper than it reads
6
- * (`why: "too_deep"`) and a visible frame whose content it cannot reach, a cross-origin frame such as a payment or sign-in widget
7
- * (`why: "unreadable_frame"`). A frame with no box on the page is not a picture of anything and is not counted. The answer is `{ hold, why }`.
8
- * What it cannot see at all (a closed shadow root, a value set by script with no event) is the host's to pause with `frames.pause`. (Elements are told by tag, not by class: a frame's elements are of its own realm.) */
9
- export declare const CREDENTIAL_PROBE = "(() => {\n const named = /(^|[^a-z])(otp|totp|2fa|mfa|passcode|one[-_ ]?time|verification[-_ ]?code|security[-_ ]?code|auth(entication)?[-_ ]?code)([^a-z]|$)/i;\n const words = (el) => {\n let text = [el.name, el.id, el.getAttribute(\"aria-label\") || \"\", el.placeholder || \"\"].join(\" \");\n try { for (const label of el.labels || []) text += \" \" + label.textContent; } catch (error) { /* no labels */ }\n const ids = el.getAttribute(\"aria-labelledby\");\n if (ids) { const root = el.getRootNode(); for (const id of ids.split(/s+/)) { const node = root.getElementById ? root.getElementById(id) : null; if (node) text += \" \" + node.textContent; } }\n return text;\n };\n const like = (el) => el.localName === \"input\" && (el.type === \"password\" || el.autocomplete === \"one-time-code\" || named.test(words(el)));\n const state = window.__piFramesSecret || (window.__piFramesSecret = { seen: false });\n if (!state.listening) {\n state.listening = true;\n addEventListener(\"input\", (event) => { const el = event.target; if (el && el.localName === \"input\" && el.value !== \"\" && like(el)) state.seen = true; }, true);\n }\n let blind = null;\n const shown = (el) => { const style = getComputedStyle(el); return el.clientWidth >= 2 && el.clientHeight >= 2 && style.display !== \"none\" && style.visibility !== \"hidden\"; };\n const scan = (root, depth) => {\n for (const el of root.querySelectorAll(\"*\")) {\n if (el.localName === \"input\" && el.value !== \"\" && like(el)) return true;\n const shadow = el.shadowRoot;\n const frame = el.localName === \"iframe\";\n if (!shadow && !frame) continue;\n if (depth >= 8) { blind = blind || \"too_deep\"; continue; }\n if (shadow && scan(shadow, depth + 1)) return true;\n if (frame) {\n let inside = null;\n try { inside = el.contentDocument; } catch (error) { inside = null; }\n if (inside) { if (scan(inside, depth + 1)) return true; }\n else if (shown(el)) blind = blind || \"unreadable_frame\";\n }\n }\n return false;\n };\n const found = scan(document, 0);\n const seen = state.seen;\n state.seen = false;\n if (found) return { hold: true, why: \"field\" };\n if (seen) return { hold: true, why: \"typed\" };\n return blind ? { hold: true, why: blind } : { hold: false, why: null };\n})()";
@@ -1,49 +0,0 @@
1
- /** Run in the page: whether any field holding a credential or a one-time code has a value. It looks at password fields, fields that say
2
- * `one-time-code`, and fields whose name, id, label (a `<label>` for it or around it, or `aria-labelledby`), `aria-label` or placeholder names
3
- * a code (otp, totp, 2fa, passcode, ...), in the document, in open shadow roots and in same-origin frames. The answer is `true` when one holds
4
- * a value now (`why: "field"`), or held one since the last check (`why: "typed"`: the page keeps a flag, set by the fields' own `input` events,
5
- * that a check reports once and clears). Anything it cannot read counts as a credential being present: a page that nests deeper than it reads
6
- * (`why: "too_deep"`) and a visible frame whose content it cannot reach, a cross-origin frame such as a payment or sign-in widget
7
- * (`why: "unreadable_frame"`). A frame with no box on the page is not a picture of anything and is not counted. The answer is `{ hold, why }`.
8
- * What it cannot see at all (a closed shadow root, a value set by script with no event) is the host's to pause with `frames.pause`. (Elements are told by tag, not by class: a frame's elements are of its own realm.) */
9
- export const CREDENTIAL_PROBE = `(() => {
10
- const named = /(^|[^a-z])(otp|totp|2fa|mfa|passcode|one[-_ ]?time|verification[-_ ]?code|security[-_ ]?code|auth(entication)?[-_ ]?code)([^a-z]|$)/i;
11
- const words = (el) => {
12
- let text = [el.name, el.id, el.getAttribute("aria-label") || "", el.placeholder || ""].join(" ");
13
- try { for (const label of el.labels || []) text += " " + label.textContent; } catch (error) { /* no labels */ }
14
- const ids = el.getAttribute("aria-labelledby");
15
- if (ids) { const root = el.getRootNode(); for (const id of ids.split(/\s+/)) { const node = root.getElementById ? root.getElementById(id) : null; if (node) text += " " + node.textContent; } }
16
- return text;
17
- };
18
- const like = (el) => el.localName === "input" && (el.type === "password" || el.autocomplete === "one-time-code" || named.test(words(el)));
19
- const state = window.__piFramesSecret || (window.__piFramesSecret = { seen: false });
20
- if (!state.listening) {
21
- state.listening = true;
22
- addEventListener("input", (event) => { const el = event.target; if (el && el.localName === "input" && el.value !== "" && like(el)) state.seen = true; }, true);
23
- }
24
- let blind = null;
25
- const shown = (el) => { const style = getComputedStyle(el); return el.clientWidth >= 2 && el.clientHeight >= 2 && style.display !== "none" && style.visibility !== "hidden"; };
26
- const scan = (root, depth) => {
27
- for (const el of root.querySelectorAll("*")) {
28
- if (el.localName === "input" && el.value !== "" && like(el)) return true;
29
- const shadow = el.shadowRoot;
30
- const frame = el.localName === "iframe";
31
- if (!shadow && !frame) continue;
32
- if (depth >= 8) { blind = blind || "too_deep"; continue; }
33
- if (shadow && scan(shadow, depth + 1)) return true;
34
- if (frame) {
35
- let inside = null;
36
- try { inside = el.contentDocument; } catch (error) { inside = null; }
37
- if (inside) { if (scan(inside, depth + 1)) return true; }
38
- else if (shown(el)) blind = blind || "unreadable_frame";
39
- }
40
- }
41
- return false;
42
- };
43
- const found = scan(document, 0);
44
- const seen = state.seen;
45
- state.seen = false;
46
- if (found) return { hold: true, why: "field" };
47
- if (seen) return { hold: true, why: "typed" };
48
- return blind ? { hold: true, why: blind } : { hold: false, why: null };
49
- })()`;
@@ -1,36 +0,0 @@
1
- export type FollowHandlers = {
2
- /** One screencast frame of the followed page: JPEG bytes and the page's own width and height as the browser reports them. */
3
- frame(bytes: Buffer, page: {
4
- deviceWidth: number;
5
- deviceHeight: number;
6
- epoch: number;
7
- }): void;
8
- /** The followed page's main frame navigated. */
9
- navigated(): void;
10
- /** The socket ended and was not asked to. */
11
- closed(): void;
12
- };
13
- export type Follower = {
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
- 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
- }>;
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
27
- * navigation, so a frame held across a change can be told from one of the page now shown. */
28
- epoch(): number;
29
- close(): void;
30
- };
31
- export type FollowOptions = {
32
- maxWidth: number;
33
- maxHeight: number;
34
- quality: number;
35
- };
36
- export declare function followPage(url: string, handlers: FollowHandlers, options: FollowOptions): Follower;
@@ -1,163 +0,0 @@
1
- // A read-only screencast of the page an agent is using, over a browser's DevTools socket. It attaches beside whatever else is
2
- // connected (the driver, the effect observer); every frame is acknowledged at once, whatever is done with it.
3
- export function followPage(url, handlers, options) {
4
- const socket = new WebSocket(url);
5
- let seq = 0;
6
- let closing = false;
7
- let current = null;
8
- let epoch = 0;
9
- /** Every page the browser has: its address, and when it was last opened or moved (an arrival counter, not a clock). */
10
- const pages = new Map();
11
- let moves = 0;
12
- const waiting = new Map();
13
- const send = (method, params = {}, sessionId) => {
14
- const id = ++seq;
15
- if (socket.readyState === 1)
16
- socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
17
- return id;
18
- };
19
- const follow = (targetId, url) => {
20
- if (current?.targetId === targetId)
21
- return;
22
- epoch += 1;
23
- if (current?.sessionId)
24
- send("Target.detachFromTarget", { sessionId: current.sessionId });
25
- current = { targetId, sessionId: null, url };
26
- send("Target.attachToTarget", { targetId, flatten: true });
27
- };
28
- /** The page in use: the one most recently opened or moved to an address, a blank one only when no other exists. The browser lists its
29
- * pages in no order that says which the agent is on, so arrival is what is read. */
30
- const choose = () => {
31
- let best = null;
32
- for (const [id, page] of pages) {
33
- const blank = page.url === "about:blank" || page.url === "";
34
- const bestBlank = best !== null && (best.url === "about:blank" || best.url === "");
35
- if (best === null || (bestBlank && !blank) || (bestBlank === blank && page.moved > best.moved))
36
- best = { id, url: page.url, moved: page.moved };
37
- }
38
- if (best)
39
- follow(best.id, best.url);
40
- };
41
- socket.onopen = () => { send("Target.setDiscoverTargets", { discover: true }); };
42
- socket.onmessage = (event) => {
43
- let message;
44
- try {
45
- message = JSON.parse(String(event.data));
46
- }
47
- catch {
48
- return;
49
- }
50
- if (message.id !== undefined && waiting.has(message.id)) {
51
- const entry = waiting.get(message.id);
52
- waiting.delete(message.id);
53
- clearTimeout(entry.timer);
54
- if (message.error)
55
- entry.reject(new Error(message.error.message ?? "the browser refused"));
56
- else if (!entry.raw && message.result?.exceptionDetails)
57
- entry.reject(new Error("the page threw"));
58
- else
59
- entry.resolve(entry.raw ? message.result : message.result?.result?.value);
60
- return;
61
- }
62
- const { method, params, sessionId } = message;
63
- if (method === "Target.targetCreated" && params.targetInfo.type === "page") {
64
- pages.set(params.targetInfo.targetId, { url: params.targetInfo.url, moved: (moves += 1) });
65
- choose();
66
- }
67
- else if (method === "Target.targetInfoChanged" && params.targetInfo.type === "page") {
68
- const known = pages.get(params.targetInfo.targetId);
69
- // A page that moved to a new address is the one in use; a new title on the same address is not a move.
70
- if (!known)
71
- pages.set(params.targetInfo.targetId, { url: params.targetInfo.url, moved: (moves += 1) });
72
- else if (known.url !== params.targetInfo.url) {
73
- known.url = params.targetInfo.url;
74
- known.moved = (moves += 1);
75
- }
76
- choose();
77
- }
78
- else if (method === "Target.attachedToTarget") {
79
- const page = current;
80
- if (!page || params.targetInfo.targetId !== page.targetId) {
81
- send("Target.detachFromTarget", { sessionId: params.sessionId });
82
- return;
83
- }
84
- page.sessionId = params.sessionId;
85
- send("Page.enable", {}, params.sessionId);
86
- send("Page.startScreencast", { format: "jpeg", quality: options.quality, maxWidth: options.maxWidth, maxHeight: options.maxHeight }, params.sessionId);
87
- }
88
- else if (method === "Page.screencastFrame") {
89
- send("Page.screencastFrameAck", { sessionId: params.sessionId }, sessionId);
90
- if (sessionId !== current?.sessionId)
91
- return;
92
- handlers.frame(Buffer.from(String(params.data), "base64"), { deviceWidth: Number(params.metadata?.deviceWidth) || 0, deviceHeight: Number(params.metadata?.deviceHeight) || 0, epoch });
93
- }
94
- else if (method === "Page.frameNavigated" && sessionId === current?.sessionId && !params.frame?.parentId) {
95
- epoch += 1;
96
- handlers.navigated();
97
- }
98
- else if (method === "Target.targetDestroyed") {
99
- pages.delete(params.targetId);
100
- if (params.targetId === current?.targetId) {
101
- current = null;
102
- epoch += 1;
103
- }
104
- choose();
105
- }
106
- };
107
- socket.onerror = () => { };
108
- socket.onclose = () => {
109
- for (const entry of waiting.values()) {
110
- clearTimeout(entry.timer);
111
- entry.reject(new Error("the browser's socket closed"));
112
- }
113
- waiting.clear();
114
- if (!closing)
115
- handlers.closed();
116
- };
117
- return {
118
- evaluate(expression, ms = 1_500) {
119
- const sessionId = current?.sessionId;
120
- if (!sessionId || socket.readyState !== 1)
121
- return Promise.reject(new Error("no page to ask"));
122
- return new Promise((resolve, reject) => {
123
- const id = send("Runtime.evaluate", { expression, returnByValue: true }, sessionId);
124
- const timer = setTimeout(() => { waiting.delete(id); reject(new Error("the page did not answer")); }, ms);
125
- timer.unref?.();
126
- waiting.set(id, { resolve, reject, timer });
127
- });
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
- },
154
- epoch: () => epoch,
155
- close() { closing = true; for (const entry of waiting.values()) {
156
- clearTimeout(entry.timer);
157
- entry.reject(new Error("closed"));
158
- } waiting.clear(); try {
159
- socket.close();
160
- }
161
- catch { /* already closed */ } },
162
- };
163
- }
@@ -1,87 +0,0 @@
1
- import type { BrowserProvider } from "../core/host.js";
2
- import type { LeaseRef } from "../core/lease.js";
3
- export type FrameData = {
4
- session: string;
5
- provider: string;
6
- w: number;
7
- h: number;
8
- mime: "image/jpeg";
9
- };
10
- /** `detail`, when present, says why a `credential_on_page` gap was written: `field` (a credential or code field holds a value), `typed` (one held a value
11
- * since the last check), `too_deep` (the page nests deeper than the check reads), `unreadable_frame` (a visible frame whose content cannot be read), `host` (the host paused
12
- * the session). Anything the check cannot read counts as a credential being present. */
13
- export type FrameGapData = {
14
- session: string;
15
- from: number;
16
- reason: "process_killed" | "credential_on_page" | "session_released";
17
- detail?: string;
18
- };
19
- /** One live line of agentrun.recording/1. `seq`, the line's place among the process's live lines, is the writer's to add. */
20
- export type FrameLine = {
21
- channel: "live";
22
- source: "browser";
23
- kind: "frame";
24
- t: number;
25
- gen?: number;
26
- conv: number;
27
- data: FrameData;
28
- blobs: [string];
29
- } | {
30
- channel: "live";
31
- source: "browser";
32
- kind: "frame.gap";
33
- t: number;
34
- gen?: number;
35
- conv: number;
36
- data: FrameGapData;
37
- };
38
- /** `blobs` maps each sha256 a line names to its bytes; the sink keeps them as `blobs/<sha256>.jpg`. A sink that throws or rejects is
39
- * ignored: a recorder never fails a browser call. */
40
- export type FrameSink = (line: FrameLine, blobs?: Record<string, Uint8Array>) => void | Promise<void>;
41
- export type FrameRecorderOptions = {
42
- sink: FrameSink;
43
- /** Milliseconds since the recording started: `t` of every line, and the `from` of a gap, are read from it. */
44
- clock: () => number;
45
- /** This process's generation, set on every line when given. */
46
- gen?: () => number;
47
- /** When a session this process did not create is taken up, the `t` of that session's last frame in an earlier process (the host reads
48
- * it from the recording), so a `process_killed` gap can start where the frames stopped; null: it has none. Absent: no such gap. */
49
- lastFrameAt?: (session: string) => number | null;
50
- maxFps?: number;
51
- maxWidth?: number;
52
- quality?: number;
53
- /** How long one line may wait for the sink before it counts as dropped; default 5 s. */
54
- sinkTimeoutMs?: number;
55
- /** The clock and the waits the page checks are paced by (default: performance.now and timers). A test passes a virtual one. */
56
- probeClock?: ProbeClock;
57
- /** Called with the probe clock's time as each check of the page is sent. */
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;
65
- };
66
- export type ProbeClock = {
67
- now(): number;
68
- sleep(ms: number): Promise<void>;
69
- };
70
- export type FrameRecorder = {
71
- /** The provider, with every session it creates or is reattached to captured, and every release ending that capture with a gap. Its
72
- * own methods are untouched. `conv` is the pi conversation that owns the sessions; without it, it is read from the lease tag
73
- * (`ar-<run>-<conversation>-<n>`), and a session whose conversation cannot be told is not recorded. */
74
- watch(provider: BrowserProvider, conv?: number): BrowserProvider;
75
- /** Pauses a session's capture as if a credential were on its page (a code entered, a setup key shown). It lifts at the next
76
- * navigation of the page, or at `resume`. */
77
- pause(session: string): void;
78
- resume(session: string): void;
79
- stats(): {
80
- frames: number;
81
- gaps: number;
82
- dropped: number;
83
- sessions: number;
84
- };
85
- close(): Promise<void>;
86
- };
87
- export declare function frameRecorder(options: FrameRecorderOptions): FrameRecorder;