@parcha/pi-browser 0.0.0-stage → 0.1.0-beta.13

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 (104) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +33 -0
  4. package/README.md +329 -2
  5. package/dist/coding-agent-local.d.ts +16 -0
  6. package/dist/coding-agent-local.js +138 -0
  7. package/dist/coding-agent.d.ts +78 -0
  8. package/dist/coding-agent.js +446 -0
  9. package/dist/core/contract.d.ts +26 -0
  10. package/dist/core/contract.js +154 -0
  11. package/dist/core/custody.d.ts +111 -0
  12. package/dist/core/custody.js +122 -0
  13. package/dist/core/decisions.d.ts +43 -0
  14. package/dist/core/decisions.js +4 -0
  15. package/dist/core/downloads.d.ts +35 -0
  16. package/dist/core/downloads.js +131 -0
  17. package/dist/core/effects.d.ts +63 -0
  18. package/dist/core/effects.js +256 -0
  19. package/dist/core/evidence.d.ts +43 -0
  20. package/dist/core/evidence.js +6 -0
  21. package/dist/core/failures.d.ts +28 -0
  22. package/dist/core/failures.js +59 -0
  23. package/dist/core/find.d.ts +32 -0
  24. package/dist/core/find.js +179 -0
  25. package/dist/core/guard.d.ts +6 -0
  26. package/dist/core/guard.js +24 -0
  27. package/dist/core/host.d.ts +279 -0
  28. package/dist/core/host.js +2 -0
  29. package/dist/core/images.d.ts +37 -0
  30. package/dist/core/images.js +60 -0
  31. package/dist/core/lease.d.ts +16 -0
  32. package/dist/core/lease.js +30 -0
  33. package/dist/core/receipts.d.ts +19 -0
  34. package/dist/core/receipts.js +22 -0
  35. package/dist/core/redact.d.ts +13 -0
  36. package/dist/core/redact.js +83 -0
  37. package/dist/core/session-control.d.ts +25 -0
  38. package/dist/core/session-control.js +75 -0
  39. package/dist/core/sites.d.ts +33 -0
  40. package/dist/core/sites.js +102 -0
  41. package/dist/core/tools.d.ts +37 -0
  42. package/dist/core/tools.js +170 -0
  43. package/dist/core/uri.d.ts +11 -0
  44. package/dist/core/uri.js +37 -0
  45. package/dist/core/usage.d.ts +38 -0
  46. package/dist/core/usage.js +44 -0
  47. package/dist/core/web.d.ts +98 -0
  48. package/dist/core/web.js +327 -0
  49. package/dist/driver/stagehand.d.ts +25 -0
  50. package/dist/driver/stagehand.js +141 -0
  51. package/dist/durable-result.d.ts +6 -0
  52. package/dist/durable-result.js +2 -0
  53. package/dist/durable.d.ts +75 -0
  54. package/dist/durable.js +484 -0
  55. package/dist/index.d.ts +18 -0
  56. package/dist/index.js +19 -0
  57. package/dist/providers/browserbase-net.d.ts +13 -0
  58. package/dist/providers/browserbase-net.js +96 -0
  59. package/dist/providers/browserbase.d.ts +152 -0
  60. package/dist/providers/browserbase.js +262 -0
  61. package/dist/providers/cdp-call.d.ts +6 -0
  62. package/dist/providers/cdp-call.js +25 -0
  63. package/dist/providers/cdp.d.ts +48 -0
  64. package/dist/providers/cdp.js +353 -0
  65. package/dist/providers/http.d.ts +2 -0
  66. package/dist/providers/http.js +21 -0
  67. package/dist/providers/kernel.d.ts +49 -0
  68. package/dist/providers/kernel.js +246 -0
  69. package/dist/providers/shared.d.ts +47 -0
  70. package/dist/providers/shared.js +82 -0
  71. package/dist/recorder/credential.d.ts +9 -0
  72. package/dist/recorder/credential.js +49 -0
  73. package/dist/recorder/follow.d.ts +26 -0
  74. package/dist/recorder/follow.js +138 -0
  75. package/dist/recorder/frames.d.ts +80 -0
  76. package/dist/recorder/frames.js +309 -0
  77. package/dist/recorder/index.d.ts +3 -0
  78. package/dist/recorder/index.js +6 -0
  79. package/dist/recorder/jpeg.d.ts +5 -0
  80. package/dist/recorder/jpeg.js +34 -0
  81. package/dist/store.d.ts +56 -0
  82. package/dist/store.js +196 -0
  83. package/dist/testing/backend.d.ts +231 -0
  84. package/dist/testing/backend.js +414 -0
  85. package/dist/testing/driver.d.ts +28 -0
  86. package/dist/testing/driver.js +32 -0
  87. package/dist/testing/index.d.ts +4 -0
  88. package/dist/testing/index.js +4 -0
  89. package/dist/testing/pages.d.ts +3 -0
  90. package/dist/testing/pages.js +10 -0
  91. package/dist/testing/sentinels.d.ts +29 -0
  92. package/dist/testing/sentinels.js +38 -0
  93. package/dist/vendor/stagehand-facade/contract.d.ts +348 -0
  94. package/dist/vendor/stagehand-facade/contract.js +155 -0
  95. package/dist/vendor/stagehand-facade/runtime.d.ts +90 -0
  96. package/dist/vendor/stagehand-facade/runtime.js +1640 -0
  97. package/dist/vendor/stagehand-facade/screenshot-transport.d.ts +15 -0
  98. package/dist/vendor/stagehand-facade/screenshot-transport.js +51 -0
  99. package/dist/vendor/stagehand-facade/tools.d.ts +31 -0
  100. package/dist/vendor/stagehand-facade/tools.js +139 -0
  101. package/dist/web.d.ts +41 -0
  102. package/dist/web.js +38 -0
  103. package/package.json +123 -4
  104. package/src/vendor/stagehand-facade/UPSTREAM.json +24 -0
@@ -0,0 +1,141 @@
1
+ import { StagehandFacadeTools } from "../vendor/stagehand-facade/tools.js";
2
+ /** A closed loopback port, so no span leaves the host: Stagehand 4.1.0 cannot turn its trace exporter off. */
3
+ export const STAGEHAND_TELEMETRY = { traces: { endpoint: "http://127.0.0.1:9/v1/traces" } };
4
+ 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.";
5
+ export const SEALED_STAGEHAND = {
6
+ logging: { level: "off" },
7
+ cache: false,
8
+ model: { generate: async () => { throw new Error(STAGEHAND_INFERENCE_REFUSED); } },
9
+ telemetry: STAGEHAND_TELEMETRY,
10
+ };
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
+ const URL_READ_MS = 2_000;
22
+ /** In a batch of its own, which the browser runs after any batch still running, so the read never lands inside a
23
+ * pending navigation (a page call issued then never returns). Past URL_READ_MS, Stagehand's page.url(). */
24
+ async function documentUrl(stagehand, page) {
25
+ try {
26
+ const href = await stagehand.experimentalBatch(async (batch) => await batch.page.evaluate("location.href"), {}, { page, timeout: URL_READ_MS });
27
+ if (typeof href === "string" && href)
28
+ return href;
29
+ }
30
+ catch { }
31
+ return await page.url();
32
+ }
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
+ /** Batches run under `timeoutMs`, not the facade's fixed 60 s; one failing at or past it is a `TimeoutError`, since
83
+ * Stagehand's own is a plain Error. */
84
+ function withBatchTimeout(stagehand, timeoutMs) {
85
+ return new Proxy(stagehand, {
86
+ get(target, property) {
87
+ if (property === "experimentalBatch") {
88
+ return async (callback, input, options = {}) => {
89
+ const started = Date.now();
90
+ try {
91
+ return await target.experimentalBatch(callback, input, { ...options, timeout: timeoutMs });
92
+ }
93
+ catch (error) {
94
+ if (Date.now() - started < timeoutMs)
95
+ throw error;
96
+ throw Object.assign(new Error(`the run batch passed its ${timeoutMs} ms deadline`, { cause: error }), { name: "TimeoutError" });
97
+ }
98
+ };
99
+ }
100
+ const value = Reflect.get(target, property, target);
101
+ return typeof value === "function" ? value.bind(target) : value;
102
+ },
103
+ });
104
+ }
105
+ /** The batch deadline comes from `DriverOptions`; a caller that passes none gets the facade's 60 s. */
106
+ export function stagehandDriver() {
107
+ return async (target, signal, options) => {
108
+ const { localBrowser, Stagehand } = await import("@browserbasehq/stagehand");
109
+ // An id the provider supplies names a held extension too, so its worker is reset as well.
110
+ // A failed open names where it went: Stagehand reports it as "[object Object]" and the socket's error has no
111
+ // address.
112
+ const host = new URL(target.dial?.url ?? target.sdkCdpUrl).host;
113
+ const named = (step) => step.catch((error) => { throw new Error(`attaching to the browser at ${host} failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error }); });
114
+ const extensionId = await named(installedExtension(target.sdkCdpUrl, signal, target.extensionId));
115
+ const browser = await named(localBrowser.connect({ cdpUrl: target.sdkCdpUrl, ...(extensionId ? { extensionId } : {}) }));
116
+ const stagehand = await Stagehand.create({ browser, ...SEALED_STAGEHAND });
117
+ const facade = new StagehandFacadeTools(withBatchTimeout(stagehand, options?.batchTimeoutMs ?? 60_000));
118
+ const active = async () => {
119
+ const page = await stagehand.browser.context.activePage();
120
+ if (!page)
121
+ throw new Error("Stagehand has no active page.");
122
+ return page;
123
+ };
124
+ return {
125
+ snapshot: (snapshotOptions) => facade.snapshot(snapshotOptions),
126
+ run: (input) => input.actions !== undefined ? facade.runActions(input.actions) : facade.run(input.code ?? ""),
127
+ url: async () => documentUrl(stagehand, await active()),
128
+ screenshot: async ({ type = "png", quality, fullPage, scale }) => {
129
+ const bytes = await (await active()).screenshot({
130
+ type, ...(fullPage === undefined ? {} : { fullPage }), ...(scale === undefined ? {} : { scale }),
131
+ // CDP takes a quality for jpeg only, and only as an integer.
132
+ ...(type === "jpeg" && quality !== undefined ? { quality: Math.round(quality) } : {}),
133
+ });
134
+ return { data: Buffer.from(bytes).toString("base64"), mimeType: type === "jpeg" ? "image/jpeg" : "image/png" };
135
+ },
136
+ page: async () => await facade.run(PAGE_CODE),
137
+ // Stagehand's own close keeps the browser for another attach; the browser's close would end it.
138
+ close: () => stagehand.close(),
139
+ };
140
+ };
141
+ }
@@ -0,0 +1,6 @@
1
+ import type { ToolOutput } from "./core/custody.js";
2
+ /** pi-durable 1.0 and 1.1 read a tool result's `content`; 1.2 reads `output` and treats a result that lacks it as empty. The model's text goes under both keys. */
3
+ export declare const forModel: (content: ToolOutput["content"]) => {
4
+ content: ToolOutput["content"];
5
+ output: ToolOutput["content"];
6
+ };
@@ -0,0 +1,2 @@
1
+ /** pi-durable 1.0 and 1.1 read a tool result's `content`; 1.2 reads `output` and treats a result that lacks it as empty. The model's text goes under both keys. */
2
+ export const forModel = (content) => ({ content, output: content });
@@ -0,0 +1,75 @@
1
+ import type { Context } from "@earendil-works/chord";
2
+ import { type Conversation, type ConversationDocToken, type ConversationId, type Extension, type Harness, type SessionDocToken, type ToolRegistration } from "@earendil-works/pi-durable";
3
+ import { type DriverFactory } from "./core/custody.js";
4
+ import type { Decisions } from "./core/decisions.js";
5
+ import type { EvidenceSink } from "./core/evidence.js";
6
+ import { EffectObserver } from "./core/effects.js";
7
+ import { type PageDriver, type ToolImpl } from "./core/tools.js";
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";
10
+ export type { DriverFactory, DriverOptions } from "./core/custody.js";
11
+ export type BrowserExtensionOptions<D extends PageDriver = PageDriver> = {
12
+ /** Default "browser"; a second plane installs a second extension under another name. */
13
+ name?: string;
14
+ /** Called per use: the provider for this conversation's plane. Holds the credentials in its closure; nothing it
15
+ * returns is committed. */
16
+ provider: (target: {
17
+ conversationId: ConversationId;
18
+ plane: string;
19
+ config: BrowserConfig;
20
+ }) => BrowserProvider | Promise<BrowserProvider>;
21
+ driver: DriverFactory<D>;
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>>>;
24
+ evidence: EvidenceSink;
25
+ /** Where `browser_downloads` writes files; absent, the tool is not listed. */
26
+ workspace?: (conversationId: ConversationId) => string;
27
+ /** `use_website`'s sites; absent, the tool is not listed. `listing` is the port's `list()`, read once at host setup:
28
+ * the tool's description renders from it. Each local child runs in a conversation this call owns. */
29
+ sites?: {
30
+ port: SiteRunPort;
31
+ listing: readonly SiteInfo[];
32
+ };
33
+ /** Live view and session status; a throw here never fails a call. */
34
+ onSession?: (row: SessionRow, change: SessionChange) => void | Promise<void>;
35
+ /** A session runs without the effect observer its policy asked for; a throw here never fails a call. */
36
+ onObserver?: (row: ObserverRow) => void | Promise<void>;
37
+ prices?: Partial<PriceTable>;
38
+ /** Exact strings to scrub from every output besides the built-in shapes, read at each use. */
39
+ redact?: {
40
+ values: () => readonly string[];
41
+ };
42
+ section?: {
43
+ addendum?: string;
44
+ };
45
+ decisions?: Decisions;
46
+ /** How long a create may still land at the provider after its caller stopped waiting; default 60 s. */
47
+ createDeadlineMs?: number;
48
+ /** How the request observer attaches (default `EffectObserver.open`); a seam for tests that have no Chrome. */
49
+ openObserver?: typeof EffectObserver.open;
50
+ };
51
+ export type BrowserExtensionHandle = {
52
+ /** Install once per Harness, before `resume()`; select per conversation. */
53
+ extension: Extension;
54
+ /** `Children`: the conversation each `use_website` request ran its child in, by `<site>:<request_id>`. */
55
+ docs: {
56
+ Config: ConversationDocToken<BrowserConfig>;
57
+ Sessions: ConversationDocToken<SessionsState>;
58
+ Inventory: SessionDocToken<{
59
+ rows: Record<string, InventoryRow>;
60
+ }>;
61
+ Children: ConversationDocToken<{
62
+ byRequest: Record<string, number>;
63
+ }>;
64
+ };
65
+ tools: readonly ToolRegistration[];
66
+ /** Shutdown path (pi has no conversation-end event): commits `releasing` and a release task; it does not wait. */
67
+ release(conversation: Conversation, reason: ReleaseReason, context: Context): Promise<void>;
68
+ /** At run open, after install and before resume: every open lease is reconciled with its provider. */
69
+ reconcile(harness: Harness, isActive: (conversationId: ConversationId) => boolean, context: Context): Promise<ReconcileReport>;
70
+ /** Drop in-memory driver attachments and idle timers (process exit); never releases. */
71
+ close(): Promise<void>;
72
+ };
73
+ export { createWebExtension, type WebExtensionOptions } from "./web.js";
74
+ export { CONFIRM_POLLS, RELEASE_ATTEMPTS } from "./store.js";
75
+ export declare function createBrowserExtension<D extends PageDriver>(options: BrowserExtensionOptions<D>): BrowserExtensionHandle;