@parcha/pi-browser 0.1.0-beta.35 → 0.1.0-beta.37

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 (46) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +20 -25
  3. package/dist/core/driving-guard.d.ts +1 -1
  4. package/dist/core/driving-guard.js +1 -1
  5. package/dist/core/host.d.ts +1 -12
  6. package/dist/core/images.d.ts +32 -4
  7. package/dist/core/images.js +81 -16
  8. package/dist/core/page-scan.d.ts +69 -0
  9. package/dist/core/page-scan.js +467 -10
  10. package/dist/core/public-fetch.js +3 -0
  11. package/dist/core/read-page.js +20 -4
  12. package/dist/core/tools.js +4 -1
  13. package/dist/core/vault.d.ts +0 -10
  14. package/dist/core/vault.js +0 -13
  15. package/dist/driver/cdp.js +3 -3
  16. package/dist/driver/page-driver.js +7 -3
  17. package/dist/durable/store.d.ts +1 -1
  18. package/dist/durable.d.ts +6 -1
  19. package/dist/durable.js +24 -5
  20. package/dist/index.d.ts +1 -0
  21. package/dist/index.js +3 -0
  22. package/dist/live-view/index.d.ts +2 -0
  23. package/dist/live-view/index.js +4 -0
  24. package/dist/live-view/server.d.ts +11 -0
  25. package/dist/live-view/server.js +13 -2
  26. package/dist/providers/cdp.js +2 -2
  27. package/dist/providers/profiles.d.ts +1 -15
  28. package/dist/providers/profiles.js +1 -64
  29. package/dist/providers/shared.d.ts +1 -47
  30. package/dist/providers/shared.js +1 -82
  31. package/dist/providers/worker-extension.js +1 -1
  32. package/dist/testing/backend.d.ts +4 -3
  33. package/dist/testing/backend.js +6 -5
  34. package/dist/vault-session.d.ts +4 -7
  35. package/dist/vault-session.js +26 -81
  36. package/dist/vendor/browser-use-pi/page.d.ts +3 -12
  37. package/dist/vendor/browser-use-pi/page.js +6 -19
  38. package/package.json +7 -20
  39. package/dist/providers/browserbase-net.d.ts +0 -12
  40. package/dist/providers/browserbase-net.js +0 -95
  41. package/dist/providers/browserbase.d.ts +0 -138
  42. package/dist/providers/browserbase.js +0 -294
  43. package/dist/providers/kernel.d.ts +0 -58
  44. package/dist/providers/kernel.js +0 -291
  45. /package/dist/{providers → core}/cdp-call.d.ts +0 -0
  46. /package/dist/{providers → core}/cdp-call.js +0 -0
@@ -205,12 +205,16 @@ export function pageDriver(stagehand, deadlines) {
205
205
  selector = target.selector;
206
206
  return await facade.run(locateCode(selector));
207
207
  }),
208
+ // Stagehand's page.screenshot scales to its device's pixels or to one per CSS pixel, and only a clip: a scale below 1
209
+ // is a clip (the viewport's, when none is asked) at one image pixel per CSS pixel, which is no smaller than that on a
210
+ // display of one device pixel per CSS pixel. A full page it does not scale (captureWithinBudget takes the viewport).
208
211
  screenshot: async ({ type = "png", quality, fullPage, scale, clip }) => {
212
+ const css = scale !== undefined && scale < 1;
209
213
  // A clip is read from the viewport's corner, and the browser's own is from the document's: the scroll offset is added.
210
- const origin = clip ? await facade.run(`return await page.evaluate("({ x: scrollX, y: scrollY })");`) : null;
214
+ const view = clip || (css && !fullPage) ? await facade.run(`return await page.evaluate("({ x: scrollX, y: scrollY, width: innerWidth, height: innerHeight })");`) : null;
215
+ const region = view && (clip ? { ...clip, x: clip.x + view.x, y: clip.y + view.y } : view);
211
216
  const bytes = await (await active()).screenshot({
212
- type, ...(fullPage === undefined ? {} : { fullPage }), ...(scale === undefined ? {} : { scale }),
213
- ...(clip && origin ? { clip: { ...clip, x: clip.x + origin.x, y: clip.y + origin.y } } : {}),
217
+ type, ...(region ? { clip: region } : fullPage === undefined ? {} : { fullPage }), ...(css ? { scale: "css" } : {}),
214
218
  // CDP takes a quality for jpeg only, and only as an integer.
215
219
  ...(type === "jpeg" && quality !== undefined ? { quality: Math.round(quality) } : {}),
216
220
  });
@@ -1,4 +1,4 @@
1
- import type { Context } from "@earendil-works/chord";
1
+ import type { Context } from "@earendil-works/chord/context";
2
2
  import { type ConversationDocToken, type ConversationId, type DocumentReader, type Harness, type TaskId, type Tx } from "@earendil-works/pi-durable";
3
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";
package/dist/durable.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { Context } from "@earendil-works/chord";
1
+ import type { Context } from "@earendil-works/chord/context";
2
2
  import { type Conversation, type ConversationDocToken, type ConversationId, type Extension, type Harness, type SessionDocToken, type ToolRegistration, type Tx } from "@earendil-works/pi-durable";
3
3
  import { type DriverFactory } from "./core/custody.js";
4
4
  import type { Decisions } from "./core/decisions.js";
@@ -107,6 +107,11 @@ export type BrowserExtensionHandle = {
107
107
  close(): Promise<void>;
108
108
  /** How many conversations the extension still holds in-memory state for: a repeat guard, an idle timer or a queued call. */
109
109
  retained(): number;
110
+ /** Keeps session `tag` from its idle release while the run waits for its person's answer (the host bounds that wait):
111
+ * an idle window that ends meanwhile releases nothing. The returned function lets it go, once; when the last keep on
112
+ * the tag goes, its idle window starts again from then. Releases for any other reason (the tool, a close, its end)
113
+ * are not held. */
114
+ keepForPerson(tag: string): () => void;
110
115
  };
111
116
  export { CONFIRM_POLLS, RELEASE_ATTEMPTS } from "./durable/store.js";
112
117
  export { HANDOFF_POLL_MS } from "./core/custody.js";
package/dist/durable.js CHANGED
@@ -238,7 +238,6 @@ async function create(c, scope, overrides, presetTag) {
238
238
  const unsupported = profileRefusal(spec, provider.caps) ?? navigationRefusal(spec, provider);
239
239
  if (unsupported)
240
240
  throw new BrowserFailureError(unsupported);
241
- // The vault may name a context or profile for the provider; the record stored below is made from the spec WITHOUT it, so no context id reaches the store.
242
241
  const plan = await planRestore(c.vault, config.vault, provider, spec);
243
242
  const record = newSessionRecord({ plane: scope.plane, tag, provider: provider.name, spec, at: now(), honours: provider.caps.settings });
244
243
  const row = rowOf(scope.cid, record);
@@ -283,9 +282,6 @@ async function create(c, scope, overrides, presetTag) {
283
282
  const live = { ...record, state: "live", resourceId: ref.id };
284
283
  try {
285
284
  const driver = await connect(c, scope, provider, ref, plan.afterAttach, plan.vaulted, plan.holdBack);
286
- // A context made for this session is given to the vault now, so a restart that loses the provider's memory of it still finds it.
287
- if (plan.fresh)
288
- await c.held.capture(ref.tag);
289
285
  await emit(c, scope.cid, config.label, live, "launched", provider);
290
286
  return { record: live, driver };
291
287
  }
@@ -660,6 +656,10 @@ async function releasePlane(c, conversation, reason, context, still = () => true
660
656
  const record = still() ? currentRecord(state, PLANE) : null;
661
657
  if (!record || !releasable(record, reason))
662
658
  return [];
659
+ // A run waiting for its person's answer keeps the session from an idle release; letting the keep go starts the idle
660
+ // window again (keepForPerson).
661
+ if (reason === "idle" && c.waiting.has(record.tag))
662
+ return [];
663
663
  // A person driving or watching the session through the live view keeps it from an idle release (#1098); it is
664
664
  // released one idle window after they leave.
665
665
  kept.gate = reason === "idle" ? personOn(c.options.gates ?? drivingGates, record.tag) : null;
@@ -834,7 +834,7 @@ export function createBrowserExtension(options) {
834
834
  stopped: (tag) => { c.stops.get(tag)?.stop(); c.stops.delete(tag); },
835
835
  });
836
836
  const c = {
837
- ...readers, name, Sessions, store, bill, held: new Attachments(), vault, fences: new Map(), leaving, serial: keyedSerializer(), guards: new Map(), owned, failed: false, stops: new Map(), ending: null, opened: null, incarnation: randomUUID(),
837
+ ...readers, name, Sessions, store, bill, held: new Attachments(), vault, fences: new Map(), leaving, waiting: new Map(), serial: keyedSerializer(), guards: new Map(), owned, failed: false, stops: new Map(), ending: null, opened: null, incarnation: randomUUID(),
838
838
  idle: idleTracker({ idleMs: DEFAULT_BROWSER_POLICY.idleReleaseS * 1000, onIdle: (cid, fired, idleMs) => void releaseIdle(c, cid, fired, idleMs).catch(() => undefined) }),
839
839
  };
840
840
  // Every browser tool is a model call on its session's driving gate: refused while a person drives the live view, and the viewer's input is held while it runs. The host's own
@@ -884,5 +884,24 @@ export function createBrowserExtension(options) {
884
884
  c.owned.clear();
885
885
  },
886
886
  retained: () => new Set([...c.guards.keys(), ...c.idle.keys(), ...c.serial.keys().map((key) => Number(key.slice(0, key.indexOf(":"))))]).size,
887
+ keepForPerson(tag) {
888
+ c.waiting.set(tag, (c.waiting.get(tag) ?? 0) + 1);
889
+ let kept = true;
890
+ return () => {
891
+ if (!kept)
892
+ return;
893
+ kept = false;
894
+ const left = (c.waiting.get(tag) ?? 1) - 1;
895
+ if (left > 0) {
896
+ c.waiting.set(tag, left);
897
+ return;
898
+ }
899
+ c.waiting.delete(tag);
900
+ // The idle window starts again from now, for a session still owned here.
901
+ const cid = c.owned.get(tag)?.cid;
902
+ if (cid !== undefined && c.idle.keys().includes(cid))
903
+ c.idle.activity(cid, 0);
904
+ };
905
+ },
887
906
  };
888
907
  }
package/dist/index.d.ts CHANGED
@@ -22,3 +22,4 @@ export * from "./core/tools.js";
22
22
  export * from "./core/usage.js";
23
23
  export * from "./core/web.js";
24
24
  export * from "./core/vault.js";
25
+ export { cdpCall, type CdpSession } from "./core/cdp-call.js";
package/dist/index.js CHANGED
@@ -23,3 +23,6 @@ export * from "./core/tools.js";
23
23
  export * from "./core/usage.js";
24
24
  export * from "./core/web.js";
25
25
  export * from "./core/vault.js";
26
+ // One CDP call over its own socket, kept open for a setting that lasts as long as it (Browser.setDownloadBehavior): what a
27
+ // host holding a vendor's browser for the tool needs beside the driver.
28
+ export { cdpCall } from "./core/cdp-call.js";
@@ -3,3 +3,5 @@ export { liveViewProvider } from "./provider.js";
3
3
  export * from "./protocol.js";
4
4
  export { createDrivingGates, drivingGates, personDrivingFailure, PERSON_DRIVING, withModelCall, type DrivingOptions } from "../core/driving.js";
5
5
  export { viewerAssets } from "./viewer.js";
6
+ export { acceptWebSocket, type WsConn, type WsOptions } from "./ws.js";
7
+ export { newToken, newViewerId, tokenMatches } from "./token.js";
@@ -3,3 +3,7 @@ export { liveViewProvider } from "./provider.js";
3
3
  export * from "./protocol.js";
4
4
  export { createDrivingGates, drivingGates, personDrivingFailure, PERSON_DRIVING, withModelCall } from "../core/driving.js";
5
5
  export { viewerAssets } from "./viewer.js";
6
+ // The WebSocket server and the viewer's credentials, for another live view built on this protocol (serve's computer
7
+ // viewer, computer-live.ts): the same handshake, frames and token checks.
8
+ export { acceptWebSocket } from "./ws.js";
9
+ export { newToken, newViewerId, tokenMatches } from "./token.js";
@@ -8,6 +8,17 @@ export type LiveViewOptions = {
8
8
  /** Where the host mounts `handle` and `upgrade`, e.g. `https://host.example/live`. Its origin is the viewer's own origin, which an upgrade's Origin
9
9
  * header must equal. Absent: the live view starts its own server on 127.0.0.1 (never 0.0.0.0), on an ephemeral port, at the first `open`. */
10
10
  baseUrl?: string;
11
+ /** With no `baseUrl`: the address its own server listens on, and the host the viewer's link names, for a host whose
12
+ * viewer is reached from another machine (its own proxy, never a person's browser directly). Absent: loopback for
13
+ * both. A host that listens off loopback gives `admit` too. */
14
+ listen?: {
15
+ readonly bind: string;
16
+ readonly host: string;
17
+ };
18
+ /** Asked of every page request and upgrade before anything else is read of it: false is a 403. The host's own check
19
+ * that the request comes from its own proxy (a signed header, say). Absent: every request is asked only what it is
20
+ * asked today. */
21
+ admit?: (req: IncomingMessage) => boolean;
11
22
  /** The screencast and input (stream.ts); the default is the package's own. A test passes a fake. */
12
23
  stream?: StreamFactory;
13
24
  /** The person/model mutex. Absent, the package's own process-wide registry (`drivingGates`, core/driving.ts), the one the toolset's model calls use, so a
@@ -5,6 +5,8 @@ import { openStream } from "./stream.js";
5
5
  import { newToken, newViewerId, tokenMatches } from "./token.js";
6
6
  import { viewerAssets } from "./viewer.js";
7
7
  import { acceptWebSocket } from "./ws.js";
8
+ /** Where the live view's own server listens with no `listen`: this machine alone. */
9
+ const LOOPBACK_HOST = "127.0.0.1"; // key-gate: loopback-rule the default, this machine alone
8
10
  const ID = /^[A-Za-z0-9_-]{22}$/;
9
11
  /** A viewer that cannot take frames as fast as they come drops them: past this many unsent bytes a frame is acknowledged unsent. */
10
12
  const SLOW_VIEWER_BYTES = 512 * 1024;
@@ -65,6 +67,11 @@ export function createLiveView(options) {
65
67
  const upgradeRoute = /^\/v\/([^/]+)\/ws$/.exec(rel);
66
68
  if (!page && !upgradeRoute && rel !== "/viewer.js" && rel !== "/viewer.css")
67
69
  return false;
70
+ if (options.admit && !options.admit(req)) {
71
+ res.writeHead(403, { ...securityHeaders(), "Content-Length": 0 });
72
+ res.end();
73
+ return true;
74
+ }
68
75
  const reply = (status, type, body) => { res.writeHead(status, { ...securityHeaders(), "Content-Type": type, "Content-Length": Buffer.byteLength(body) }); res.end(req.method === "HEAD" ? undefined : body); return true; };
69
76
  if (req.method !== "GET" && req.method !== "HEAD")
70
77
  return reply(405, "text/plain", "method not allowed");
@@ -90,6 +97,8 @@ export function createLiveView(options) {
90
97
  // A browser always sends its page's origin on a WebSocket; another tab's script cannot forge it. Anything but the viewer's own is refused.
91
98
  if (origin === null || req.headers.origin !== origin)
92
99
  return deny("403 Forbidden");
100
+ if (options.admit && !options.admit(req))
101
+ return deny("403 Forbidden");
93
102
  const entry = ID.test(match[1]) ? byId.get(match[1]) : undefined;
94
103
  if (!entry || entry.released)
95
104
  return deny("404 Not Found");
@@ -377,8 +386,10 @@ export function createLiveView(options) {
377
386
  s.on("upgrade", (req, socket, head) => { if (!upgrade(req, socket, head))
378
387
  socket.destroy(); });
379
388
  s.once("error", reject);
380
- // Loopback only, never 0.0.0.0: the host that wants more mounts the handler on its own server.
381
- s.listen(0, "127.0.0.1", () => { s.unref(); server = s; origin = `http://127.0.0.1:${s.address().port}`; resolve(); });
389
+ // Loopback unless the host names another address (`listen`, with its `admit`): the host that wants more mounts the
390
+ // handler on its own server.
391
+ const at = options.listen ?? { bind: LOOPBACK_HOST, host: LOOPBACK_HOST };
392
+ s.listen(0, at.bind, () => { s.unref(); server = s; origin = `http://${at.host}:${s.address().port}`; resolve(); });
382
393
  });
383
394
  return starting;
384
395
  };
@@ -7,12 +7,12 @@ import path from "node:path";
7
7
  import { BrowserFailureError, PROFILE_NAME, refusedError } from "../core/custody.js";
8
8
  import { DownloadNotSettled } from "../core/downloads.js";
9
9
  import { browserFailure } from "../core/failures.js";
10
- import { cdpCall } from "./cdp-call.js";
10
+ import { cdpCall } from "../core/cdp-call.js";
11
11
  import { chromeTail, openChromeStderr, watchChromeStderr } from "./chrome-stderr.js";
12
12
  import { claimWriter, freeWriter, noteWriter } from "./profiles.js";
13
13
  import { chromeArgs } from "./chrome-args.js";
14
14
  import { COPY, copyExtension, copyId, isLoaded, loadConfined, soleStagehand } from "./worker-extension.js";
15
- const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 86_400, survivesDisconnect: true, releaseIsAsync: false, profiles: false, extension: "loaded-locally", settings: { proxies: false, verified: false, geolocation: false, region: false, context: false } };
15
+ const CAPS = { profiles: false, settings: { proxies: false, verified: false, geolocation: false, region: false, context: false } };
16
16
  const downloadsDir = (profileRoot, tag) => path.join(profileDir(profileRoot, tag) + ".downloads");
17
17
  const READY_MS = 20_000;
18
18
  /** The browser is gone and directories it used are not: a profile left behind holds the session's cookies, so a release that cannot remove
@@ -1,4 +1,4 @@
1
- /** Both vendors keep the last writer's state and neither locks, so within this process one session at a time may save to a
1
+ /** A profile keeps the last writer's state and nothing locks it, so within this process one session at a time may save to a
2
2
  * profile. A holder that is no longer running is replaced; the same owner's successor (a relaunch asks for its replacement
3
3
  * while the old session is still being released) waits for the release; anyone else is refused. */
4
4
  export declare function claimWriter(key: string, name: string, tag: string, owner: string, signal?: AbortSignal): Promise<void>;
@@ -7,17 +7,3 @@ export declare function claimWriter(key: string, name: string, tag: string, owne
7
7
  export declare function noteWriter(tag: string, running: (signal: AbortSignal) => Promise<boolean>, settle?: () => Promise<void>): void;
8
8
  export declare function freeWriter(tag: string): void;
9
9
  export declare function isWriter(tag: string): boolean;
10
- /** Context ids are not secrets, and Browserbase has no way to look a context up by name, so the name to id map is the host's.
11
- * `resolve` returns the name's context, calling `make` only when there is none, and no two callers may both make one. */
12
- export type ProfileStore = {
13
- resolve(key: string, make: (signal: AbortSignal) => Promise<string>): Promise<string>;
14
- /** True when the store writes the ids it holds to a clear file (the default one does). A session vault refuses a provider whose store does. */
15
- readonly clear?: boolean;
16
- };
17
- /** Context ids kept in this process only: for a host that moves them into its own vault, so none lands on disk. */
18
- export declare function memoryProfileStore(): ProfileStore;
19
- /** A JSON file, read, extended and written under one lock, so two processes' first uses of a name make one context; a file that is
20
- * not this format, or cannot be read, is never overwritten. */
21
- export declare function fileProfileStore(file?: string, options?: {
22
- makeLimitMs?: number;
23
- }): ProfileStore;
@@ -1,9 +1,4 @@
1
- import { randomBytes } from "node:crypto";
2
- import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
3
- import os from "node:os";
4
- import path from "node:path";
5
1
  import { refusedError } from "../core/custody.js";
6
- import { withLock } from "../core/downloads.js";
7
2
  import { profileHoldings } from "./shared.js";
8
3
  const writers = profileHoldings.writers;
9
4
  const WAIT_MS = 20_000;
@@ -31,7 +26,7 @@ async function waitFor(work, signal, ms) {
31
26
  signal?.removeEventListener("abort", abort);
32
27
  }
33
28
  }
34
- /** Both vendors keep the last writer's state and neither locks, so within this process one session at a time may save to a
29
+ /** A profile keeps the last writer's state and nothing locks it, so within this process one session at a time may save to a
35
30
  * profile. A holder that is no longer running is replaced; the same owner's successor (a relaunch asks for its replacement
36
31
  * while the old session is still being released) waits for the release; anyone else is refused. */
37
32
  export async function claimWriter(key, name, tag, owner, signal) {
@@ -74,61 +69,3 @@ export function isWriter(tag) {
74
69
  return true;
75
70
  return false;
76
71
  }
77
- /** Context ids kept in this process only: for a host that moves them into its own vault, so none lands on disk. */
78
- export function memoryProfileStore() {
79
- const ids = new Map();
80
- return { clear: false, resolve: (key, make) => { let known = ids.get(key); if (!known) {
81
- known = make(AbortSignal.timeout(20_000));
82
- ids.set(key, known);
83
- known.catch(() => ids.delete(key));
84
- } return known; } };
85
- }
86
- const SCHEMA = "pi-browser.profiles.v1";
87
- const defaultProfilesFile = () => path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "pi-browser", "profiles.json");
88
- const notOurs = (file) => new Error(`the profiles file ${path.basename(file)} is not a pi-browser profiles file, so it was left as it is`);
89
- async function readProfiles(file) {
90
- let text;
91
- try {
92
- text = await readFile(file, "utf8");
93
- }
94
- catch (error) {
95
- if (error.code === "ENOENT")
96
- return { schema: SCHEMA, contexts: {} };
97
- throw error;
98
- }
99
- try {
100
- const parsed = JSON.parse(text);
101
- const contexts = parsed?.contexts;
102
- if (parsed?.schema === SCHEMA && contexts && typeof contexts === "object" && !Array.isArray(contexts) && Object.values(contexts).every((id) => typeof id === "string" && id !== ""))
103
- return parsed;
104
- }
105
- catch { /* not JSON */ }
106
- throw notOurs(file);
107
- }
108
- /** A JSON file, read, extended and written under one lock, so two processes' first uses of a name make one context; a file that is
109
- * not this format, or cannot be read, is never overwritten. */
110
- export function fileProfileStore(file = defaultProfilesFile(), options = {}) {
111
- // The lock is taken over once it is 30 s old (core/downloads.ts's rule), so `make` must end well before: a slower one is cut here, never left
112
- // to run past the lock that protects it.
113
- const makeLimitMs = options.makeLimitMs ?? 20_000;
114
- return {
115
- clear: true,
116
- async resolve(key, make) {
117
- await mkdir(path.dirname(file), { recursive: true });
118
- return withLock(`${file}.lock`, async () => {
119
- const current = await readProfiles(file);
120
- const known = current.contexts[key];
121
- if (known)
122
- return known;
123
- const limit = AbortSignal.timeout(makeLimitMs);
124
- // Listening before `make` does, so the cut's own words are what the caller hears.
125
- const cut = new Promise((_, reject) => limit.addEventListener("abort", () => reject(new Error(`making the profile's context took longer than ${makeLimitMs} ms, so it was cut before the profiles file's lock could be taken over`)), { once: true }));
126
- const id = await Promise.race([make(limit), cut]);
127
- const next = `${file}.${randomBytes(4).toString("hex")}.tmp`;
128
- await writeFile(next, `${JSON.stringify({ schema: SCHEMA, contexts: { ...current.contexts, [key]: id } }, null, 2)}\n`);
129
- await rename(next, file);
130
- return id;
131
- }, "the profiles file");
132
- },
133
- };
134
- }
@@ -1,50 +1,5 @@
1
- import type { ResourceStatus } from "../core/lease.js";
2
- import type { CdpSession } from "./cdp-call.js";
3
1
  export declare const nonEmpty: (v: unknown) => string;
4
- /** Values are `[A-Za-z0-9._:-]`, at most 60 characters; the tag is exact, since a query matches it whole. */
5
- export declare const tagValue: (v: string) => string;
6
- export declare function assertTag(tag: string): void;
7
- export declare function extensionArchive(): string;
8
- export declare const accountKey: (origin: string, apiKey: string) => string;
9
- export declare const defaultSleep: (ms: number) => Promise<void>;
10
- export declare const DEFAULT_CONFIRM: {
11
- polls: number;
12
- intervalMs: number;
13
- };
14
- /** The work itself goes on when `signal` fires: another caller may be waiting for it. */
15
- export declare function untilAborted<T>(work: Promise<T>, signal?: AbortSignal): Promise<T>;
16
- /** One upload per process and account; a failed upload is forgotten so the next create tries again. */
17
- export declare function uploadOnce<T>(uploads: Map<string, Promise<T>>, account: string, upload: () => Promise<T>): Promise<T>;
18
- /** The request is asked twice at most; released means the provider says the session is no longer running, not that the
19
- * request was sent. `request` answers "gone" when the provider no longer knows the session. */
20
- export declare function releaseAndConfirm(o: {
21
- request: () => Promise<"gone" | void>;
22
- status: () => Promise<ResourceStatus>;
23
- forget: () => void | Promise<void>;
24
- confirm: {
25
- polls: number;
26
- intervalMs: number;
27
- };
28
- sleep: (ms: number) => Promise<void>;
29
- stillRunning: string;
30
- }): Promise<void>;
31
- export declare const browserbaseHoldings: {
32
- connectUrls: Map<string, string>;
33
- settings: Map<string, Pick<CdpSession, "close" | "open">>;
34
- opening: Map<string, Promise<void>>;
35
- uploads: Map<string, Promise<string>>;
36
- boundDials: Map<string, string>;
37
- };
38
- export declare const kernelHoldings: {
39
- cdpUrls: Map<string, string>;
40
- liveUrls: Map<string, string>;
41
- uploads: Map<string, Promise<{
42
- id: string;
43
- } | {
44
- name: string;
45
- }>>;
46
- };
47
- /** Which session may save to a named profile now, by profile: claimed by both cloud providers (providers/profiles.ts). */
2
+ /** Which session may save to a named profile now, by profile: claimed by the local Chrome provider (providers/profiles.ts). */
48
3
  export declare const profileHoldings: {
49
4
  writers: Map<string, {
50
5
  tag: string;
@@ -53,4 +8,3 @@ export declare const profileHoldings: {
53
8
  settle?: () => Promise<void>;
54
9
  }>;
55
10
  };
56
- export declare function resetProviderHoldings(): void;
@@ -1,86 +1,5 @@
1
- import { createHash } from "node:crypto";
2
- import path from "node:path";
3
- import { fileURLToPath } from "node:url";
4
1
  export const nonEmpty = (v) => String(v ?? "").trim();
5
- /** Values are `[A-Za-z0-9._:-]`, at most 60 characters; the tag is exact, since a query matches it whole. */
6
- export const tagValue = (v) => String(v || "").replace(/[^A-Za-z0-9._:-]+/g, "_").slice(0, 60) || "unknown";
7
- export function assertTag(tag) {
8
- if (!/^[A-Za-z0-9_.-]+$/.test(tag))
9
- throw new Error("a session tag is [A-Za-z0-9_.-]");
10
- }
11
- export function extensionArchive() {
12
- return nonEmpty(process.env.STAGEHAND_EXTENSION_ARCHIVE_PATH) || path.join(path.dirname(fileURLToPath(import.meta.resolve("@browserbasehq/stagehand"))), "assets", "stagehand-extension.zip");
13
- }
14
- export const accountKey = (origin, apiKey) => `${origin}|${createHash("sha256").update(apiKey).digest("hex").slice(0, 16)}`;
15
- export const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
16
- export const DEFAULT_CONFIRM = { polls: 6, intervalMs: 500 };
17
- /** The work itself goes on when `signal` fires: another caller may be waiting for it. */
18
- export function untilAborted(work, signal) {
19
- if (!signal)
20
- return work;
21
- return new Promise((resolve, reject) => {
22
- const abort = () => reject(signal.reason ?? new DOMException("The operation was aborted.", "AbortError"));
23
- // The outcome is taken first, so a failure after the caller left is handled, never unhandled.
24
- work.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
25
- if (signal.aborted)
26
- return abort();
27
- signal.addEventListener("abort", abort, { once: true });
28
- });
29
- }
30
- /** One upload per process and account; a failed upload is forgotten so the next create tries again. */
31
- export function uploadOnce(uploads, account, upload) {
32
- let up = uploads.get(account);
33
- if (!up) {
34
- up = upload();
35
- uploads.set(account, up);
36
- up.catch(() => uploads.delete(account));
37
- }
38
- return up;
39
- }
40
- /** The request is asked twice at most; released means the provider says the session is no longer running, not that the
41
- * request was sent. `request` answers "gone" when the provider no longer knows the session. */
42
- export async function releaseAndConfirm(o) {
43
- let failure;
44
- for (let attempt = 0; attempt < 2; attempt += 1) {
45
- try {
46
- if ((await o.request()) === "gone")
47
- return o.forget();
48
- failure = undefined;
49
- break;
50
- }
51
- catch (error) {
52
- failure = error;
53
- }
54
- }
55
- for (let poll = 0;; poll += 1) {
56
- const now = await o.status();
57
- if (now !== "running" && now !== "pending")
58
- return o.forget();
59
- if (poll >= o.confirm.polls)
60
- throw failure ?? new Error(o.stillRunning);
61
- await o.sleep(o.confirm.intervalMs);
62
- }
63
- }
64
- // Process-wide on purpose: a provider built later (custody builds one for the release) must still close the attach socket,
65
- // drop the dial binding and reuse the account's upload. The URLs carry tokens and are never written anywhere.
66
- export const browserbaseHoldings = {
67
- connectUrls: new Map(),
68
- settings: new Map(),
69
- opening: new Map(),
70
- uploads: new Map(),
71
- boundDials: new Map(),
72
- };
73
- export const kernelHoldings = {
74
- cdpUrls: new Map(),
75
- liveUrls: new Map(),
76
- uploads: new Map(),
77
- };
78
- /** Which session may save to a named profile now, by profile: claimed by both cloud providers (providers/profiles.ts). */
2
+ /** Which session may save to a named profile now, by profile: claimed by the local Chrome provider (providers/profiles.ts). */
79
3
  export const profileHoldings = {
80
4
  writers: new Map(),
81
5
  };
82
- export function resetProviderHoldings() {
83
- for (const holdings of [browserbaseHoldings, kernelHoldings, profileHoldings])
84
- for (const map of Object.values(holdings))
85
- map.clear();
86
- }
@@ -5,7 +5,7 @@
5
5
  // browser starts, because its path decides the extension's id and so the one Origin the browser's socket is opened to.
6
6
  import { cp, readFile, writeFile } from "node:fs/promises";
7
7
  import path from "node:path";
8
- import { cdpCall } from "./cdp-call.js";
8
+ import { cdpCall } from "../core/cdp-call.js";
9
9
  import { extensionDirectory, extensionOrigin } from "./chrome-args.js";
10
10
  export const COPY = "stagehand-extension";
11
11
  /** The name Stagehand's extension carries, which is how Stagehand finds it in a browser. */
@@ -60,7 +60,7 @@ export type FakeBackendOptions = {
60
60
  fullPageHeight?: number;
61
61
  /** 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. */
62
62
  elements?: Record<string, FakeBox | FakeBox[]>;
63
- /** Device pixels per CSS pixel; a screenshot is this many times larger unless it asks for `scale: "css"`. */
63
+ /** Device pixels per CSS pixel; a screenshot is this many times larger, times the `scale` it asks for. */
64
64
  deviceScale?: number;
65
65
  };
66
66
  export type FakeBox = {
@@ -73,7 +73,7 @@ export type FakeScreenshotOptions = {
73
73
  fullPage?: boolean;
74
74
  type?: "png" | "jpeg";
75
75
  quality?: number;
76
- scale?: "css" | "device";
76
+ scale?: number;
77
77
  clip?: FakeBox;
78
78
  };
79
79
  /** A PNG or JPEG whose header declares `width` x `height`: enough for a reader that decodes the header, not a picture. */
@@ -208,7 +208,8 @@ export declare class FakeDriverFace {
208
208
  }): Promise<unknown>;
209
209
  /** No `dispatched` row: a read of the URL is not a read of the page. */
210
210
  url(id: string): Promise<string>;
211
- /** Header-only image of the viewport (or full page) times the device scale; each capture is a dispatched row. */
211
+ /** Header-only image of the viewport (or full page) times the device scale and the asked scale, rounded as Chrome
212
+ * rounds; each capture is a dispatched row. */
212
213
  screenshot(id: string, options?: FakeScreenshotOptions): Promise<{
213
214
  data: string;
214
215
  mimeType: string;
@@ -35,7 +35,7 @@ export function fakeImage(type, width, height) {
35
35
  ihdr[9] = 2;
36
36
  return Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), chunk("IHDR", ihdr), chunk("IEND", Buffer.alloc(0))]);
37
37
  }
38
- const DEFAULT_CAPS = { timeoutModel: "inactivity", maxLifetimeS: 3600, survivesDisconnect: false, releaseIsAsync: false, profiles: false, extension: "loaded-locally" };
38
+ const DEFAULT_CAPS = { profiles: false };
39
39
  export class FakeBackend {
40
40
  sentinels;
41
41
  pages;
@@ -369,13 +369,14 @@ export class FakeDriverFace {
369
369
  await this.b.before("driver.url");
370
370
  return this.session(id).url;
371
371
  }
372
- /** Header-only image of the viewport (or full page) times the device scale; each capture is a dispatched row. */
372
+ /** Header-only image of the viewport (or full page) times the device scale and the asked scale, rounded as Chrome
373
+ * rounds; each capture is a dispatched row. */
373
374
  async screenshot(id, options = {}) {
374
375
  await this.call(id, "screenshot", "screenshot", { options });
375
376
  const { viewport = { width: 1288, height: 711 }, fullPageHeight = 8319, deviceScale = 1 } = this.b.opts;
376
- const factor = options.scale === "css" ? 1 : deviceScale;
377
- const width = (options.clip ? options.clip.width : viewport.width) * factor;
378
- const height = (options.clip ? options.clip.height : options.fullPage ? fullPageHeight : viewport.height) * factor;
377
+ const factor = deviceScale * (options.scale ?? 1);
378
+ const width = Math.round((options.clip ? options.clip.width : viewport.width) * factor);
379
+ const height = Math.round((options.clip ? options.clip.height : options.fullPage ? fullPageHeight : viewport.height) * factor);
379
380
  const type = options.type ?? "jpeg";
380
381
  await this.b.after("driver.screenshot");
381
382
  return { data: fakeImage(type, width, height).toString("base64"), mimeType: `image/${type}`, width, height };
@@ -28,23 +28,20 @@ export declare function vaultRuntime(options: VaultOptions, track: (secret: stri
28
28
  }): VaultRuntime | null;
29
29
  /** Waits, up to `ms`, for a person to stop driving a session: a capture reads only once they have handed back. True when the gate is free. */
30
30
  export declare function untilQuiet(gate: DrivingGate | null, ms?: number): Promise<boolean>;
31
- /** `vaulted`: this session was created under the host's vault plan (a context kind asked the provider for a saved context or profile), so it may be captured; a session that
32
- * started with no target cannot be given one later, because its provider holds no context for it. `fresh`: nothing was kept, so a new context was made and its id is
33
- * given to the vault right after the create (a restart then still finds it). */
31
+ /** `vaulted`: this session was created under the host's vault plan, with a target. */
34
32
  export type RestorePlan = {
35
33
  spec: SessionSpec;
36
34
  afterAttach: ((target: AttachTarget) => Promise<void>) | null;
37
35
  vaulted: boolean;
38
- fresh: boolean;
39
36
  /** Set when the vault may hold a saved sign-in this session did not take (the read failed, or what it holds could not be used here): this session is NOT captured, so it
40
37
  * can never replace what is saved. The text is the warning given once at the first capture. */
41
38
  holdBack?: string;
42
39
  };
43
- /** What the create does with the vault: the spec the provider is asked for (a kept context or profile for Browserbase and Kernel) and a step that runs after the
44
- * browser is attached and before the driver is (a local Chrome's cookies and local storage). The record the adapter stores is made from the ORIGINAL spec, never this one. */
40
+ /** What the create does with the vault: a step that runs after the browser is attached and before the driver is (a local Chrome's cookies and local storage).
41
+ * The spec is the one given, and the record the adapter stores is made from it. */
45
42
  export declare function planRestore(rt: VaultRuntime | null, target: VaultTarget | undefined, provider: BrowserProvider, spec: SessionSpec): Promise<RestorePlan>;
46
43
  export type CaptureOptions = {
47
- /** Whether the session was created under the vault plan (RestorePlan.vaulted). A context kind session that was not cannot be captured. */
44
+ /** Whether the session was created under the vault plan (RestorePlan.vaulted). */
48
45
  vaulted: boolean;
49
46
  /** The session's driving gate, read when the capture runs: a person who begins driving while the browser is being read voids that read. */
50
47
  gate?: () => DrivingGate | null;