@parcha/pi-browser 0.1.0-beta.13 → 0.1.0-beta.15

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 (43) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +29 -8
  3. package/dist/coding-agent.d.ts +7 -0
  4. package/dist/coding-agent.js +33 -16
  5. package/dist/core/contract.js +1 -1
  6. package/dist/core/custody.d.ts +16 -3
  7. package/dist/core/custody.js +28 -11
  8. package/dist/core/downloads.d.ts +1 -0
  9. package/dist/core/downloads.js +2 -2
  10. package/dist/core/failures.d.ts +8 -0
  11. package/dist/core/failures.js +18 -9
  12. package/dist/core/guard.d.ts +1 -1
  13. package/dist/core/guard.js +2 -1
  14. package/dist/core/host.d.ts +60 -2
  15. package/dist/core/sites.js +2 -1
  16. package/dist/core/tools.d.ts +37 -2
  17. package/dist/core/tools.js +84 -54
  18. package/dist/core/usage.d.ts +1 -20
  19. package/dist/driver/extension-worker.d.ts +7 -0
  20. package/dist/driver/extension-worker.js +148 -0
  21. package/dist/driver/new-document.d.ts +26 -0
  22. package/dist/driver/new-document.js +40 -0
  23. package/dist/driver/stagehand.js +9 -61
  24. package/dist/durable.d.ts +14 -3
  25. package/dist/durable.js +507 -369
  26. package/dist/index.d.ts +1 -0
  27. package/dist/index.js +1 -0
  28. package/dist/providers/browserbase.d.ts +17 -0
  29. package/dist/providers/browserbase.js +49 -8
  30. package/dist/providers/cdp.d.ts +14 -0
  31. package/dist/providers/cdp.js +270 -66
  32. package/dist/providers/kernel.js +40 -6
  33. package/dist/providers/profiles.d.ts +19 -0
  34. package/dist/providers/profiles.js +124 -0
  35. package/dist/providers/shared.d.ts +1 -1
  36. package/dist/recorder/index.d.ts +1 -0
  37. package/dist/recorder/index.js +1 -0
  38. package/dist/recorder/jpeg.d.ts +3 -0
  39. package/dist/recorder/jpeg.js +36 -0
  40. package/dist/recorder/track.d.ts +107 -0
  41. package/dist/recorder/track.js +280 -0
  42. package/dist/testing/backend.js +2 -2
  43. package/package.json +3 -3
@@ -0,0 +1,40 @@
1
+ /** Chrome's answer to an evaluate sent with a document's context id after a navigation replaced it. Stagehand's extension
2
+ * relays it as a JSON-RPC error with this text, and the facade's code runs rebuild it as a plain Error with the same
3
+ * text and no cause. Matched by identity. */
4
+ export const CONTEXT_GONE = "-32000 Cannot find context with specified id";
5
+ const contextGone = (error) => {
6
+ if (!(error instanceof Error))
7
+ return false;
8
+ const cause = error.cause;
9
+ if (cause && typeof cause === "object")
10
+ return typeof cause.code === "number" && cause.message === CONTEXT_GONE;
11
+ return error.message === CONTEXT_GONE;
12
+ };
13
+ /** A read that lands in a document a navigation has just replaced waits for the new one, then reads once more. The
14
+ * wait's own failure is not the read's: the second read's answer, or its error, is what comes back. */
15
+ export async function readOnNewDocument(read, waitForDocument) {
16
+ try {
17
+ return await read();
18
+ }
19
+ catch (error) {
20
+ if (!contextGone(error))
21
+ throw error;
22
+ await waitForDocument().catch(() => undefined);
23
+ return await read();
24
+ }
25
+ }
26
+ // A page's address is its document's (location.href): page.url() names a goto's target once Chrome starts it, so a
27
+ // receipt could cite a page it does not hold. One evaluate reads all four, so they are one document's.
28
+ const PAGE_CODE = `return await page.evaluate(() => ({
29
+ url: location.href,
30
+ title: document.title,
31
+ text: document.body ? document.body.innerText : "",
32
+ html: document.documentElement ? document.documentElement.outerHTML : "",
33
+ }));`;
34
+ /** The driver's snapshot and page reads, each read once more on the new document when a navigation replaced its own. */
35
+ export function documentReads(facade, waitForDocument) {
36
+ return {
37
+ snapshot: (options) => readOnNewDocument(() => facade.snapshot(options), waitForDocument),
38
+ page: async () => await readOnNewDocument(() => facade.run(PAGE_CODE), waitForDocument),
39
+ };
40
+ }
@@ -1,4 +1,6 @@
1
1
  import { StagehandFacadeTools } from "../vendor/stagehand-facade/tools.js";
2
+ import { installedExtension } from "./extension-worker.js";
3
+ import { documentReads } from "./new-document.js";
2
4
  /** A closed loopback port, so no span leaves the host: Stagehand 4.1.0 cannot turn its trace exporter off. */
3
5
  export const STAGEHAND_TELEMETRY = { traces: { endpoint: "http://127.0.0.1:9/v1/traces" } };
4
6
  export const STAGEHAND_INFERENCE_REFUSED = "Stagehand inference is off in this harness: act, extract and observe are unavailable. Drive the page with run code or snapshot IDs.";
@@ -8,17 +10,9 @@ export const SEALED_STAGEHAND = {
8
10
  model: { generate: async () => { throw new Error(STAGEHAND_INFERENCE_REFUSED); } },
9
11
  telemetry: STAGEHAND_TELEMETRY,
10
12
  };
11
- const STAGEHAND_EXTENSION = "Stagehand Runtime";
12
- const DISCOVERY_MS = 10_000;
13
- // A page's address is its document's (location.href): page.url() names a goto's target once Chrome starts it, so a
14
- // receipt could cite a page it does not hold. One evaluate reads all four, so they are one document's.
15
- const PAGE_CODE = `return await page.evaluate(() => ({
16
- url: location.href,
17
- title: document.title,
18
- text: document.body ? document.body.innerText : "",
19
- html: document.documentElement ? document.documentElement.outerHTML : "",
20
- }));`;
21
13
  const URL_READ_MS = 2_000;
14
+ /** How long a read that landed in a document a navigation replaced waits for the new one's DOMContentLoaded. */
15
+ const NEW_DOCUMENT_MS = 15_000;
22
16
  /** In a batch of its own, which the browser runs after any batch still running, so the read never lands inside a
23
17
  * pending navigation (a page call issued then never returns). Past URL_READ_MS, Stagehand's page.url(). */
24
18
  async function documentUrl(stagehand, page) {
@@ -30,55 +24,6 @@ async function documentUrl(stagehand, page) {
30
24
  catch { }
31
25
  return await page.url();
32
26
  }
33
- /** A held extension runtime keeps one Stagehand instance until that instance's close, which a dead process never sent,
34
- * so a new attach would be refused: closing its service worker target (no page target) resets it first. */
35
- async function installedExtension(cdpUrl, signal, known) {
36
- const socket = new WebSocket(cdpUrl);
37
- const timer = setTimeout(() => socket.close(), DISCOVERY_MS);
38
- const stop = () => socket.close();
39
- signal?.addEventListener("abort", stop, { once: true });
40
- // A call the browser never answers settles empty when the socket closes (the deadline, an abort, the browser).
41
- const pending = new Map();
42
- let next = 0;
43
- const call = (method, params = {}) => new Promise((resolve) => { pending.set(++next, resolve); socket.send(JSON.stringify({ id: next, method, params })); });
44
- try {
45
- await new Promise((resolve, reject) => {
46
- socket.onopen = () => resolve();
47
- // A refused connection raises `error` and, on Node 22, never `close`: waiting for `close` alone would hang the
48
- // attach.
49
- socket.onerror = () => reject(new Error("Failed to open CDP WebSocket"));
50
- socket.onclose = () => { for (const settle of pending.values())
51
- settle(undefined); reject(new Error("the CDP socket closed")); };
52
- socket.onmessage = (event) => { const message = JSON.parse(String(event.data)); pending.get(message.id)?.(message.result); };
53
- });
54
- let id = known ?? null;
55
- if (!id) {
56
- const extensions = (await call("Extensions.getExtensions"))?.extensions ?? [];
57
- const enabled = extensions.filter((extension) => extension.name === STAGEHAND_EXTENSION && extension.enabled);
58
- if (enabled.length !== 1)
59
- return null;
60
- id = enabled[0].id;
61
- }
62
- const workers = async () => ((await call("Target.getTargets"))?.targetInfos ?? [])
63
- .filter((target) => target.type === "service_worker" && target.url.startsWith(`chrome-extension://${id}/`))
64
- .map((target) => target.targetId);
65
- const closing = await workers();
66
- for (const targetId of closing)
67
- await call("Target.closeTarget", { targetId });
68
- // A closed worker stays listed for a moment and Stagehand would attach to it: wait until it is gone (best effort).
69
- for (let tries = 0; tries < 40 && (await workers()).some((targetId) => closing.includes(targetId)); tries += 1)
70
- await new Promise((r) => setTimeout(r, 50));
71
- return id;
72
- }
73
- catch {
74
- return known ?? null;
75
- }
76
- finally {
77
- clearTimeout(timer);
78
- signal?.removeEventListener("abort", stop);
79
- socket.close();
80
- }
81
- }
82
27
  /** Batches run under `timeoutMs`, not the facade's fixed 60 s; one failing at or past it is a `TimeoutError`, since
83
28
  * Stagehand's own is a plain Error. */
84
29
  function withBatchTimeout(stagehand, timeoutMs) {
@@ -121,8 +66,11 @@ export function stagehandDriver() {
121
66
  throw new Error("Stagehand has no active page.");
122
67
  return page;
123
68
  };
69
+ // In a batch of its own, which the browser runs once the new document is its page's.
70
+ const newDocument = async () => stagehand.experimentalBatch(async (batch, input) => { await batch.page.waitForLoadState("domcontentloaded", input.ms); }, { ms: NEW_DOCUMENT_MS }, { page: await active(), timeout: NEW_DOCUMENT_MS + 1_000 });
71
+ const reads = documentReads(facade, newDocument);
124
72
  return {
125
- snapshot: (snapshotOptions) => facade.snapshot(snapshotOptions),
73
+ snapshot: (snapshotOptions) => reads.snapshot(snapshotOptions),
126
74
  run: (input) => input.actions !== undefined ? facade.runActions(input.actions) : facade.run(input.code ?? ""),
127
75
  url: async () => documentUrl(stagehand, await active()),
128
76
  screenshot: async ({ type = "png", quality, fullPage, scale }) => {
@@ -133,7 +81,7 @@ export function stagehandDriver() {
133
81
  });
134
82
  return { data: Buffer.from(bytes).toString("base64"), mimeType: type === "jpeg" ? "image/jpeg" : "image/png" };
135
83
  },
136
- page: async () => await facade.run(PAGE_CODE),
84
+ page: () => reads.page(),
137
85
  // Stagehand's own close keeps the browser for another attach; the browser's close would end it.
138
86
  close: () => stagehand.close(),
139
87
  };
package/dist/durable.d.ts CHANGED
@@ -4,9 +4,9 @@ import { type DriverFactory } from "./core/custody.js";
4
4
  import type { Decisions } from "./core/decisions.js";
5
5
  import type { EvidenceSink } from "./core/evidence.js";
6
6
  import { EffectObserver } from "./core/effects.js";
7
- import { type PageDriver, type ToolImpl } from "./core/tools.js";
7
+ import { type BrowserToolImpls, type PageDriver } from "./core/tools.js";
8
8
  import type { BrowserConfig, BrowserProvider, InventoryRow, ObserverRow, PriceTable, ReconcileReport, ReleaseReason, SessionChange, SessionRow, SessionsState, SiteInfo, SiteRunPort } from "./core/host.js";
9
- export type { PageDriver, ToolCall, ToolImpl } from "./core/tools.js";
9
+ export type { BrowserToolArgs, BrowserToolImpls, PageDriver, ToolCall, ToolImpl } from "./core/tools.js";
10
10
  export type { DriverFactory, DriverOptions } from "./core/custody.js";
11
11
  export type BrowserExtensionOptions<D extends PageDriver = PageDriver> = {
12
12
  /** Default "browser"; a second plane installs a second extension under another name. */
@@ -20,7 +20,7 @@ export type BrowserExtensionOptions<D extends PageDriver = PageDriver> = {
20
20
  }) => BrowserProvider | Promise<BrowserProvider>;
21
21
  driver: DriverFactory<D>;
22
22
  /** Implementations by contract name, over the package's own; a contract tool with no implementation is not listed. */
23
- tools?: Partial<Record<string, ToolImpl<D>>>;
23
+ tools?: Partial<BrowserToolImpls<D>>;
24
24
  evidence: EvidenceSink;
25
25
  /** Where `browser_downloads` writes files; absent, the tool is not listed. */
26
26
  workspace?: (conversationId: ConversationId) => string;
@@ -47,7 +47,14 @@ export type BrowserExtensionOptions<D extends PageDriver = PageDriver> = {
47
47
  createDeadlineMs?: number;
48
48
  /** How the request observer attaches (default `EffectObserver.open`); a seam for tests that have no Chrome. */
49
49
  openObserver?: typeof EffectObserver.open;
50
+ /** Called synchronously at two moments of a page action, for a host that kills the process there to test a resume:
51
+ * `browser.between-actions` once a page action's answer is committed, before the next page action dispatches, and
52
+ * `browser.action-returned` once the driver call returned (or threw) and the action's entry is marked finished,
53
+ * before pi commits its answer. A throw, or a rejected promise, is a process warning (`PI_BROWSER_CROSSING`) and
54
+ * never changes the call. */
55
+ crossing?: (point: Crossing) => void;
50
56
  };
57
+ type Crossing = "browser.between-actions" | "browser.action-returned";
51
58
  export type BrowserExtensionHandle = {
52
59
  /** Install once per Harness, before `resume()`; select per conversation. */
53
60
  extension: Extension;
@@ -67,8 +74,12 @@ export type BrowserExtensionHandle = {
67
74
  release(conversation: Conversation, reason: ReleaseReason, context: Context): Promise<void>;
68
75
  /** At run open, after install and before resume: every open lease is reconciled with its provider. */
69
76
  reconcile(harness: Harness, isActive: (conversationId: ConversationId) => boolean, context: Context): Promise<ReconcileReport>;
77
+ /** Shutdown is release, `waitForIdle`, `drain`, close: resolves when none of this extension's release tasks is live. */
78
+ drain(harness: Harness, context: Context, signal?: AbortSignal): Promise<void>;
70
79
  /** Drop in-memory driver attachments and idle timers (process exit); never releases. */
71
80
  close(): Promise<void>;
81
+ /** How many conversations the extension still holds in-memory state for: a repeat guard, an idle timer or a queued call. */
82
+ retained(): number;
72
83
  };
73
84
  export { createWebExtension, type WebExtensionOptions } from "./web.js";
74
85
  export { CONFIRM_POLLS, RELEASE_ATTEMPTS } from "./store.js";