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

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 (71) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/NOTICE +30 -0
  3. package/README.md +33 -199
  4. package/dist/core/contract.d.ts +9 -6
  5. package/dist/core/contract.js +22 -34
  6. package/dist/core/custody.d.ts +6 -0
  7. package/dist/core/custody.js +6 -0
  8. package/dist/core/driving-guard.js +17 -2
  9. package/dist/core/evidence.d.ts +1 -1
  10. package/dist/core/files.d.ts +3 -0
  11. package/dist/core/files.js +4 -1
  12. package/dist/core/host.d.ts +0 -63
  13. package/dist/core/redact.d.ts +0 -2
  14. package/dist/core/redact.js +0 -32
  15. package/dist/core/session-control.d.ts +0 -2
  16. package/dist/core/session-control.js +0 -5
  17. package/dist/core/tools.d.ts +9 -0
  18. package/dist/core/usage.d.ts +0 -2
  19. package/dist/core/usage.js +0 -2
  20. package/dist/core/web.d.ts +2 -111
  21. package/dist/core/web.js +0 -443
  22. package/dist/driver/cdp.d.ts +6 -0
  23. package/dist/driver/cdp.js +245 -0
  24. package/dist/driver/page-driver.js +29 -3
  25. package/dist/durable/store.js +13 -4
  26. package/dist/durable.d.ts +2 -12
  27. package/dist/durable.js +9 -80
  28. package/dist/index.d.ts +0 -1
  29. package/dist/index.js +0 -1
  30. package/dist/live-view/provider.d.ts +2 -2
  31. package/dist/live-view/provider.js +2 -2
  32. package/dist/live-view/server.d.ts +1 -1
  33. package/dist/providers/browserbase.d.ts +0 -31
  34. package/dist/providers/browserbase.js +2 -27
  35. package/dist/providers/chrome-args.d.ts +3 -0
  36. package/dist/providers/chrome-args.js +13 -2
  37. package/dist/testing/backend.d.ts +2 -21
  38. package/dist/testing/backend.js +1 -25
  39. package/dist/vendor/browser-use-pi/ax.d.ts +106 -0
  40. package/dist/vendor/browser-use-pi/ax.js +642 -0
  41. package/dist/vendor/browser-use-pi/cdp.d.ts +19 -0
  42. package/dist/vendor/browser-use-pi/cdp.js +106 -0
  43. package/dist/vendor/browser-use-pi/page.d.ts +38 -0
  44. package/dist/vendor/browser-use-pi/page.js +112 -0
  45. package/package.json +7 -25
  46. package/src/vendor/browser-use-pi/UPSTREAM.json +25 -0
  47. package/src/vendor/stagehand-facade/UPSTREAM.json +0 -4
  48. package/dist/coding-agent-local.d.ts +0 -12
  49. package/dist/coding-agent-local.js +0 -72
  50. package/dist/coding-agent.d.ts +0 -135
  51. package/dist/coding-agent.js +0 -641
  52. package/dist/core/sites.d.ts +0 -33
  53. package/dist/core/sites.js +0 -104
  54. package/dist/durable/web.d.ts +0 -47
  55. package/dist/durable/web.js +0 -41
  56. package/dist/providers/assigned.d.ts +0 -18
  57. package/dist/providers/assigned.js +0 -75
  58. package/dist/recorder/credential.d.ts +0 -9
  59. package/dist/recorder/credential.js +0 -49
  60. package/dist/recorder/follow.d.ts +0 -36
  61. package/dist/recorder/follow.js +0 -163
  62. package/dist/recorder/frames.d.ts +0 -87
  63. package/dist/recorder/frames.js +0 -377
  64. package/dist/recorder/index.d.ts +0 -4
  65. package/dist/recorder/index.js +0 -7
  66. package/dist/recorder/jpeg.d.ts +0 -8
  67. package/dist/recorder/jpeg.js +0 -70
  68. package/dist/recorder/track.d.ts +0 -107
  69. package/dist/recorder/track.js +0 -280
  70. package/dist/vendor/stagehand-facade/screenshot-transport.d.ts +0 -15
  71. package/dist/vendor/stagehand-facade/screenshot-transport.js +0 -51
@@ -0,0 +1,245 @@
1
+ import { refusedError } from "../core/custody.js";
2
+ import { openDial } from "../core/dial.js";
3
+ import { AxHelpers, UnknownIdError } from "../vendor/browser-use-pi/ax.js";
4
+ import { CDP, CDPConnectionClosedError } from "../vendor/browser-use-pi/cdp.js";
5
+ import { Page } from "../vendor/browser-use-pi/page.js";
6
+ import { NAVIGATED_SNAPSHOT_ERROR, NO_HYDRATED_SNAPSHOT_ERROR, STALE_SNAPSHOT_ID_ERROR } from "../core/failures.js";
7
+ /** The package's stale-snapshot words, as the Stagehand driver says them: plain errors, so a failure reads them as a stale snapshot. */
8
+ const stale = (message) => new Error(message);
9
+ const staleSnapshotIdError = (id) => STALE_SNAPSHOT_ID_ERROR.replace("${id}", id);
10
+ /** What `run` with code is told on this browser. */
11
+ export const CDP_CODE_REFUSED = 'run code is not available on this browser (the agent\'s browser computer): send actions instead, each an op with a snapshot id and a value, for example {"actions":[{"op":"click","id":"0-42"}]}, and navigate with {"actions":[{"op":"goto","url":"https://example.com"}]}. Read the page with browser_read.';
12
+ /** How long one CDP command may take before the action is said to be unanswered. */
13
+ const COMMAND_MS = 30_000;
14
+ /**
15
+ * One element's box once it is scrolled into view, in CSS pixels from the top page's viewport corner, or how many a
16
+ * selector matches. An element in a same-origin iframe (an id from the snapshot) gets each enclosing frame's
17
+ * content-box offset added, and the viewport is the top page's, as the screenshot's clip is.
18
+ */
19
+ const LOCATE_JS = `function(selector){
20
+ let top = (this && this.ownerDocument ? this.ownerDocument : document).defaultView;
21
+ while (top.frameElement) top = top.parent;
22
+ const viewport = { width: top.innerWidth, height: top.innerHeight };
23
+ const found = selector === null ? null : selector === undefined ? this : document.querySelectorAll(selector);
24
+ if (found === null) return { viewport };
25
+ const list = found instanceof NodeList ? [...found] : [found.nodeType === 1 ? found : found.parentElement];
26
+ if (list.length !== 1 || !list[0]) return { viewport, matches: list.filter(Boolean).length };
27
+ list[0].scrollIntoView({ block: 'center', inline: 'center' });
28
+ const r = list[0].getBoundingClientRect();
29
+ let x = r.x, y = r.y;
30
+ for (let w = list[0].ownerDocument.defaultView; w && w.frameElement; w = w.parent) {
31
+ const f = w.frameElement, fr = f.getBoundingClientRect(), cs = getComputedStyle(f);
32
+ x += fr.x + f.clientLeft + parseFloat(cs.paddingLeft);
33
+ y += fr.y + f.clientTop + parseFloat(cs.paddingTop);
34
+ }
35
+ return { viewport, matches: 1, box: { x, y, width: r.width, height: r.height } };
36
+ }`;
37
+ /** The browser's tabs, in the browser's order (DevTools' own pages left out). */
38
+ async function tabsOf(cdp) {
39
+ const { targetInfos } = await cdp.send("Target.getTargets");
40
+ return targetInfos.filter((t) => t.type === "page" && !t.url.startsWith("devtools://"));
41
+ }
42
+ /** A blank tab opened for the driver, when the browser has none. */
43
+ async function blankTab(cdp) {
44
+ return (await cdp.send("Target.createTarget", { url: "about:blank" })).targetId;
45
+ }
46
+ /** The raw-CDP page driver: snapshot ids and actions only. */
47
+ export function cdpDriver() {
48
+ return async (target, signal) => {
49
+ signal?.throwIfAborted();
50
+ const cdp = await CDP.open(openDial(target), COMMAND_MS);
51
+ let page;
52
+ /** Every tab the driver has seen, so one that appears later is known as new. */
53
+ const seen = new Set();
54
+ /** The tab that opened each tab the driver followed, to go back to when that one closes. */
55
+ const openers = new Map();
56
+ /** Whether the last run moved to another tab (movedTab). */
57
+ let movedTab = false;
58
+ try {
59
+ const tabs = await tabsOf(cdp);
60
+ for (const t of tabs)
61
+ seen.add(t.targetId);
62
+ // The browser's first tab, or a blank one opened for the driver when it has none.
63
+ page = await Page.attach(cdp, tabs[0]?.targetId ?? (await blankTab(cdp)));
64
+ seen.add(page.targetId);
65
+ }
66
+ catch (error) {
67
+ cdp.close();
68
+ throw error;
69
+ }
70
+ const ax = new AxHelpers(() => page, () => cdp);
71
+ /**
72
+ * Drives the tab the driven tab opened (a popup, or a link that opens a new tab), or, when the driven tab has closed,
73
+ * the tab that opened it (else the browser's last, else a blank one). The old tab's snapshot ids are dropped, so an
74
+ * action by id fails as a stale snapshot until the next snapshot. Answers the line that says so, or nothing when
75
+ * the driven tab stays.
76
+ */
77
+ const follow = async () => {
78
+ const tabs = await tabsOf(cdp);
79
+ const opened = tabs.filter((t) => !seen.has(t.targetId) && t.openerId === page.targetId).at(-1);
80
+ for (const t of tabs)
81
+ seen.add(t.targetId);
82
+ let next = opened?.targetId;
83
+ if (!next && !tabs.some((t) => t.targetId === page.targetId)) {
84
+ const back = openers.get(page.targetId);
85
+ next = tabs.find((t) => t.targetId === back)?.targetId ?? tabs.at(-1)?.targetId ?? (await blankTab(cdp));
86
+ seen.add(next);
87
+ }
88
+ if (!next)
89
+ return undefined;
90
+ const old = page;
91
+ page = await Page.attach(cdp, next);
92
+ if (opened)
93
+ openers.set(next, old.targetId);
94
+ ax.forget();
95
+ await cdp.send("Target.detachFromTarget", { sessionId: old.sessionId }).catch(() => undefined);
96
+ await ax.settle({ capMs: 3000 }).catch(() => undefined);
97
+ const { targetInfo } = await cdp.send("Target.getTargetInfo", { targetId: next });
98
+ const now = opened ? "the page opened a new tab; now driving it" : "the tab closed; now driving another";
99
+ return `[tab] ${now}: ${targetInfo.url}.`;
100
+ };
101
+ /** The latest snapshot's ids hold: there is one, the page still shows its document, and every id is in it. */
102
+ const check = async (actions, checked = false) => {
103
+ if (actions.every((a) => a.op === "goto"))
104
+ return;
105
+ if (!ax.hydrated || !ax.taken)
106
+ throw stale(NO_HYDRATED_SNAPSHOT_ERROR);
107
+ if (!checked) {
108
+ // A probe the page can't answer is a navigated page; a dropped connection is said as one, not as a stale snapshot.
109
+ const now = await ax.probe().catch((error) => {
110
+ if (error instanceof CDPConnectionClosedError)
111
+ throw error;
112
+ return undefined;
113
+ });
114
+ if (!now || now.doc !== ax.taken.doc)
115
+ throw stale(NAVIGATED_SNAPSHOT_ERROR);
116
+ }
117
+ for (const action of actions) {
118
+ if (action.op === "goto")
119
+ break; // what follows a goto is on the next page: its ids are checked when it runs
120
+ try {
121
+ ax.nodeOf(action.id);
122
+ }
123
+ catch {
124
+ throw stale(staleSnapshotIdError(action.id));
125
+ }
126
+ }
127
+ };
128
+ const runOne = async (action) => {
129
+ switch (action.op) {
130
+ case "goto": {
131
+ const before = await ax.probe().catch(() => undefined);
132
+ await page.goto(action.url);
133
+ // The page's ids were the old document's: the next action by id fails as a stale snapshot.
134
+ ax.forget();
135
+ const settled = await ax.settle({ capMs: 3000 });
136
+ return `[ok] goto ${action.url} -> ${await ax.change(before, settled.probe)}`;
137
+ }
138
+ case "click":
139
+ return ax.click(action.id);
140
+ case "hover":
141
+ return ax.hover(action.id);
142
+ case "fill":
143
+ return ax.fill(action.id, action.value);
144
+ case "type":
145
+ return ax.type(action.id, action.text, action.delay);
146
+ case "press":
147
+ return ax.press(action.id, action.key);
148
+ case "select":
149
+ return ax.select(action.id, action.values);
150
+ default:
151
+ throw refusedError(`run takes the ops goto, click, hover, fill, type, press and select, not ${JSON.stringify(action.op)}`);
152
+ }
153
+ };
154
+ return {
155
+ // A snapshot is of the tab the agent is on now: a tab the page opened since, or the one left when it closed.
156
+ snapshot: async (options = {}) => {
157
+ const moved = await follow();
158
+ const shot = await ax.snapshot(options.includeIframes === undefined ? {} : { includeIframes: options.includeIframes });
159
+ return moved ? `${moved}\n${shot}` : shot;
160
+ },
161
+ run: async ({ code, actions, checked, rest: after = 0 }) => {
162
+ movedTab = false;
163
+ if (code !== undefined)
164
+ throw refusedError(CDP_CODE_REFUSED);
165
+ if (!actions?.length)
166
+ throw refusedError("run requires exactly one of code or actions");
167
+ await check(actions, checked === true);
168
+ const lines = [];
169
+ for (const [i, action] of actions.entries()) {
170
+ try {
171
+ lines.push(await runOne(action));
172
+ }
173
+ catch (error) {
174
+ // An id after a goto in the same run names nothing of the new page: a stale snapshot.
175
+ if (error instanceof UnknownIdError)
176
+ throw stale(staleSnapshotIdError(error.id));
177
+ if (!lines.length)
178
+ throw error;
179
+ // What ran is said with what failed: the actions before it took effect.
180
+ throw new Error(`${lines.join("\n")}\n${error instanceof Error ? error.message : String(error)}`, { cause: error });
181
+ }
182
+ // An action that opened a tab (or closed this one) moves the driver there; the rest name the old tab's ids.
183
+ // The action already took effect, so a failure to look is not its failure.
184
+ const moved = await follow().catch(() => undefined);
185
+ if (moved) {
186
+ movedTab = true;
187
+ lines.push(`${moved} Take a snapshot before acting by id.`);
188
+ // This run's actions after this one, and the batch's that the guard would send after them.
189
+ const rest = actions.length - i - 1 + after;
190
+ if (rest)
191
+ lines.push(`[stopped] ${rest} more action${rest === 1 ? "" : "s"} not run: they name the old tab's snapshot ids.`);
192
+ break;
193
+ }
194
+ }
195
+ return lines.join("\n");
196
+ },
197
+ movedTab: () => movedTab,
198
+ checkActions: (actions) => check(actions),
199
+ url: async () => {
200
+ const { targetInfo } = await cdp.send("Target.getTargetInfo", { targetId: page.targetId });
201
+ return targetInfo.url;
202
+ },
203
+ forgetSnapshots: () => ax.forget(),
204
+ locate: async (place) => {
205
+ if (place?.id !== undefined) {
206
+ let node;
207
+ try {
208
+ node = ax.nodeOf(place.id);
209
+ }
210
+ catch {
211
+ throw stale(ax.hydrated ? staleSnapshotIdError(place.id) : NO_HYDRATED_SNAPSHOT_ERROR);
212
+ }
213
+ const { object } = await page.cdp("DOM.resolveNode", { backendNodeId: node });
214
+ if (!object.objectId)
215
+ return { viewport: await page.evaluate(() => ({ width: innerWidth, height: innerHeight })), matches: 0 };
216
+ try {
217
+ const answer = await page.cdp("Runtime.callFunctionOn", { objectId: object.objectId, functionDeclaration: LOCATE_JS, arguments: [{ value: undefined }], returnByValue: true });
218
+ return answer.result.value;
219
+ }
220
+ finally {
221
+ await page.cdp("Runtime.releaseObject", { objectId: object.objectId }).catch(() => { });
222
+ }
223
+ }
224
+ const selector = place?.selector ?? null;
225
+ return page.evaluate(`(${LOCATE_JS}).call(document, ${JSON.stringify(selector)})`);
226
+ },
227
+ screenshot: async ({ type = "png", quality, fullPage, clip }) => {
228
+ const data = await page.screenshot({ type, ...(quality === undefined ? {} : { quality }), ...(fullPage === undefined ? {} : { fullPage }), ...(clip ? { clip } : {}) });
229
+ return { data, mimeType: type === "jpeg" ? "image/jpeg" : "image/png" };
230
+ },
231
+ // One evaluate reads all four, so they are one document's.
232
+ page: () => page.evaluate(() => ({
233
+ url: location.href,
234
+ title: document.title,
235
+ text: document.body ? document.body.innerText : "",
236
+ html: document.documentElement ? document.documentElement.outerHTML : "",
237
+ })),
238
+ // The browser keeps running: custody releases it through the provider.
239
+ close: async () => {
240
+ await cdp.send("Target.detachFromTarget", { sessionId: page.sessionId }).catch(() => undefined);
241
+ cdp.close();
242
+ },
243
+ };
244
+ };
245
+ }
@@ -133,6 +133,25 @@ export function pageDriver(stagehand, deadlines) {
133
133
  kept().set(page.pageId, { ...current, url: snapshot.url });
134
134
  }
135
135
  };
136
+ /** A batch with a goto: the actions one at a time, a goto through the facade's page (http, https or about:blank only), each
137
+ * other action by its id as the facade runs it, so an id after a goto meets the new page and fails as a stale snapshot. */
138
+ const withGoto = async (actions, checked) => {
139
+ if (!actions.some((action) => action.op === "goto"))
140
+ return checked ? afterChecked(actions) : facade.runActions(actions);
141
+ let completed = 0;
142
+ let url = "";
143
+ for (const action of actions) {
144
+ if (action.op === "goto") {
145
+ if (!/^(https?:\/\/|about:blank$)/i.test(action.url))
146
+ throw new Error(`goto takes an http or https URL (or about:blank), not ${JSON.stringify(action.url.slice(0, 100))}`);
147
+ url = await facade.run(`await page.goto(${JSON.stringify(action.url)}); return page.url();`);
148
+ }
149
+ else
150
+ url = (await facade.runActions([action])).url;
151
+ completed++;
152
+ }
153
+ return { completed, url };
154
+ };
136
155
  return {
137
156
  snapshot: async (snapshotOptions) => {
138
157
  const tree = await reads.snapshot(snapshotOptions);
@@ -142,19 +161,26 @@ export function pageDriver(stagehand, deadlines) {
142
161
  snapshotDocuments.set(page.pageId, { xpathById: taken.xpathById, document: documentOf(page) });
143
162
  return tree;
144
163
  },
145
- run: (input) => input.actions !== undefined ? (input.checked ? afterChecked(input.actions) : facade.runActions(input.actions)) : facade.run(input.code ?? ""),
164
+ run: (input) => input.actions !== undefined ? withGoto(input.actions, input.checked === true) : facade.run(input.code ?? ""),
146
165
  // As the facade's own batch checks a run's actions before it sends any (runActionsNow): the active page's snapshot,
147
- // the page still at its address, and every id in it. Read from the facade's snapshots, as forgetSnapshots does.
166
+ // the page still at its address, and every id in it. Read from the facade's snapshots, as forgetSnapshots does. A
167
+ // batch of gotos alone names no id, so it needs no snapshot, as the raw-CDP driver's check holds too.
148
168
  checkActions: async (actions) => {
169
+ if (actions.every((action) => action.op === "goto"))
170
+ return;
149
171
  const page = await active();
150
172
  const snapshot = facade.snapshotsByPage.get(page.pageId);
151
173
  if (!snapshot)
152
174
  throw new Error(NO_HYDRATED_SNAPSHOT_ERROR);
153
175
  if ((await page.url()) !== snapshot.url)
154
176
  throw new Error(NAVIGATED_SNAPSHOT_ERROR);
155
- for (const action of actions)
177
+ for (const action of actions) {
178
+ // What follows a goto is on the next page: its ids are checked when it runs.
179
+ if (action.op === "goto")
180
+ break;
156
181
  if (!snapshot.xpathById[action.id])
157
182
  throw new Error(staleSnapshotIdError(action.id));
183
+ }
158
184
  },
159
185
  url: async () => documentUrl(stagehand, await active()),
160
186
  // The facade keeps each page's last snapshot's ids for its own actions; with none, an action by id fails NO_HYDRATED (a stale snapshot).
@@ -1,5 +1,5 @@
1
1
  import { defineDoc, defineTask } from "@earendil-works/pi-durable";
2
- import { backoffMs, moveRecord, notices } from "../core/custody.js";
2
+ import { backoffMs, HANDOFF_POLL_MS, moveRecord, notices } from "../core/custody.js";
3
3
  export const now = () => new Date().toISOString();
4
4
  const iso = (ms) => new Date(ms).toISOString();
5
5
  const cidOf = (row) => row.conversationId;
@@ -183,8 +183,9 @@ export function custodyStore({ name, Config, Sessions, providerOf, emit, meter,
183
183
  }, context);
184
184
  },
185
185
  });
186
- /** Polls the port until it answers, then gives the session back with the outcome's notice, if it is still held for
187
- * this request. */
186
+ /** Polls the port until it answers, every HANDOFF_POLL_MS while the answer is pending, then gives the session back with
187
+ * the outcome's notice, if it is still held for this request. `attempt` counts the reads in a row that failed, which
188
+ * back off (backoffMs); a read that answers "pending" starts it again. */
188
189
  const HandoffTask = defineTask({
189
190
  name: `${name}.handoff`,
190
191
  version: 1,
@@ -206,6 +207,7 @@ export function custodyStore({ name, Config, Sessions, providerOf, emit, meter,
206
207
  if (over)
207
208
  return;
208
209
  let answer = "pending";
210
+ let failed = false;
209
211
  try {
210
212
  if (handoff)
211
213
  answer = await handoff.outcome(interactionId, runtime.signal);
@@ -214,11 +216,18 @@ export function custodyStore({ name, Config, Sessions, providerOf, emit, meter,
214
216
  if (runtime.signal.aborted)
215
217
  throw error;
216
218
  runtime.report(scrubbed(error));
219
+ failed = true;
217
220
  }
218
- if (answer === "pending") {
221
+ // A person's answer can come at any moment: while it is pending, it is asked again at a short fixed interval, so
222
+ // a hand-back resumes the agent within one poll. A read that failed backs off instead.
223
+ if (failed) {
219
224
  await runtime.sleepUntil(runtime.now() + backoffMs(attempt), { phase: "poll", attempt: attempt + 1 }, context);
220
225
  return;
221
226
  }
227
+ if (answer === "pending") {
228
+ await runtime.sleepUntil(runtime.now() + HANDOFF_POLL_MS, { phase: "poll", attempt: 0 }, context);
229
+ return;
230
+ }
222
231
  const outcome = typeof answer === "string" ? answer : answer.outcome;
223
232
  const reason = typeof answer === "string" ? undefined : answer.reason;
224
233
  await runtime.commit(async (tx) => {
package/dist/durable.d.ts CHANGED
@@ -7,7 +7,7 @@ import { EffectObserver } from "./core/effects.js";
7
7
  import { type VaultOptions } from "./vault-session.js";
8
8
  import type { DrivingGates } from "./live-view/protocol.js";
9
9
  import { type BrowserToolImpls, type PageDriver } from "./core/tools.js";
10
- import type { BrowserConfig, BrowserProvider, InventoryRow, ObserverRow, PriceTable, ReconcileReport, ReleaseReason, SessionChange, SessionCharge, SessionRow, SessionsState, SiteInfo, SiteRunPort, HandoffPort, WorkspaceFiles } from "./core/host.js";
10
+ import type { BrowserConfig, BrowserProvider, InventoryRow, ObserverRow, PriceTable, ReconcileReport, ReleaseReason, SessionChange, SessionCharge, SessionRow, SessionsState, HandoffPort, WorkspaceFiles } from "./core/host.js";
11
11
  export type { BrowserToolArgs, BrowserToolImpls, PageDriver, ToolCall, ToolImpl } from "./core/tools.js";
12
12
  export type { DriverFactory, DriverOptions } from "./core/custody.js";
13
13
  /** A host's step before a session is created at its provider (`BrowserExtensionOptions.beforeCreate`): the session's
@@ -40,12 +40,6 @@ export type BrowserExtensionOptions<D extends PageDriver = PageDriver> = VaultOp
40
40
  handoff?: HandoffPort;
41
41
  /** Resolves `browser_upload` paths; defaults to files under `workspace`. */
42
42
  files?: WorkspaceFiles;
43
- /** `use_website`'s sites; absent, the tool is not listed. `listing` is the port's `list()`, read once at host setup:
44
- * the tool's description renders from it. Each local child runs in a conversation this call owns. */
45
- sites?: {
46
- port: SiteRunPort;
47
- listing: readonly SiteInfo[];
48
- };
49
43
  /** Live view and session status; a throw here never fails a call. */
50
44
  onSession?: (row: SessionRow, change: SessionChange) => void | Promise<void>;
51
45
  /** The person/model mutex shared with the live view (`createLiveView`'s `gates`); the default, the package's process-wide `drivingGates`, is the one the live view
@@ -90,16 +84,12 @@ type Crossing = "browser.between-actions" | "browser.action-returned";
90
84
  export type BrowserExtensionHandle = {
91
85
  /** Install once per Harness, before `resume()`; select per conversation. */
92
86
  extension: Extension;
93
- /** `Children`: the conversation each `use_website` request ran its child in, by `<site>:<request_id>`. */
94
87
  docs: {
95
88
  Config: ConversationDocToken<BrowserConfig>;
96
89
  Sessions: ConversationDocToken<SessionsState>;
97
90
  Inventory: SessionDocToken<{
98
91
  rows: Record<string, InventoryRow>;
99
92
  }>;
100
- Children: ConversationDocToken<{
101
- byRequest: Record<string, number>;
102
- }>;
103
93
  };
104
94
  tools: readonly ToolRegistration[];
105
95
  /** Shutdown path (pi has no conversation-end event): closes the conversation's drivers and commits `releasing` and a
@@ -118,6 +108,6 @@ export type BrowserExtensionHandle = {
118
108
  /** How many conversations the extension still holds in-memory state for: a repeat guard, an idle timer or a queued call. */
119
109
  retained(): number;
120
110
  };
121
- export { createWebExtension, type WebExtensionOptions } from "./durable/web.js";
122
111
  export { CONFIRM_POLLS, RELEASE_ATTEMPTS } from "./durable/store.js";
112
+ export { HANDOFF_POLL_MS } from "./core/custody.js";
123
113
  export declare function createBrowserExtension<D extends PageDriver>(options: BrowserExtensionOptions<D>): BrowserExtensionHandle;
package/dist/durable.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import { randomUUID } from "node:crypto";
2
- import { configure, defineDoc, defineExtension, defineTool } from "@earendil-works/pi-durable";
3
- import { BROWSER_TOOL_NAMES, browserSection, browserToolsFor, listedFor, WEB_TOOL_NAMES } from "./core/contract.js";
2
+ import { defineDoc, defineExtension, defineTool } from "@earendil-works/pi-durable";
3
+ import { browserSection, browserToolsFor, listedFor } from "./core/contract.js";
4
4
  import { BrowserFailureError, closeDriver, currentRecord, loadedNoPage, custodyTools, FIXED_SESSION_RELAUNCH, fenced, HANDED_BACK, newSessionRecord, notices, NAVIGATION_CAP, NOTHING_TO_HOLD, navigationRefusal, profileRefusal, relaunchRefusal, SESSION_REPLACED, sessionSpec, waitingForHuman, NO_HANDOFF } from "./core/custody.js";
5
5
  import { forModel } from "./durable/result.js";
6
6
  import { EffectObserver, effectDecider, observerFailure } from "./core/effects.js";
@@ -10,16 +10,15 @@ import { drivingGuarded } from "./core/driving-guard.js";
10
10
  import { drivingGates, keptFor, keptReason, personOn, rearmWhenLeft } from "./core/driving.js";
11
11
  import { captureFor, planRestore, untilQuiet, vaultRuntime } from "./vault-session.js";
12
12
  import { pageTools } from "./core/tools.js";
13
- import { useWebsite, useWebsiteContract } from "./core/sites.js";
14
13
  import { leaseTag } from "./core/lease.js";
15
14
  import { createRedactor, hostLiveView, redactContent, redactDeep, scrubPageUrl } from "./core/redact.js";
16
- import { CREATE_DEADLINE_MS, DEFAULT_BROWSER_POLICY, idleTracker, keyedSerializer, oneAtATime, providerKeyValues } from "./core/session-control.js";
15
+ import { CREATE_DEADLINE_MS, DEFAULT_BROWSER_POLICY, idleTracker, keyedSerializer, providerKeyValues } from "./core/session-control.js";
17
16
  import { custodyStore, now } from "./durable/store.js";
18
17
  import { answerOf, clearJournal, cutOf, cutsOf, inChain, journalOf, owed } from "./durable/journal.js";
19
18
  import { withinDeadline } from "./core/unanswered.js";
20
19
  import { resolvePrices, sessionCharge, withEstimate } from "./core/usage.js";
21
- export { createWebExtension } from "./durable/web.js";
22
20
  export { CONFIRM_POLLS, RELEASE_ATTEMPTS } from "./durable/store.js";
21
+ export { HANDOFF_POLL_MS } from "./core/custody.js";
23
22
  const PLANE = "default";
24
23
  const UNCONFIGURED = { label: "", run: "", policy: DEFAULT_BROWSER_POLICY };
25
24
  const HANDOFF_ENDED = new BrowserFailureError(browserFailure("session_ended", "The browser session left the person's hands before their answer could be waited on. Your next browser call opens a fresh session; take a snapshot there before acting.", { retryable: true }));
@@ -48,9 +47,6 @@ async function drainReleases(name, harness, context, signal) {
48
47
  const open = (record) => record?.state === "live" || record?.state === "creating";
49
48
  const releasable = (record, reason) => open(record) || (record?.state === "held" && reason !== "idle");
50
49
  const waiting = (record) => new BrowserFailureError(waitingForHuman(record.handoff));
51
- // A child gets the browser and web tools only: never use_website, so it cannot start children of its own, and never
52
- // browser_upload or browser_downloads, since its report is all that crosses back (invariant 10) and a site run has no files.
53
- const CHILD_TOOLS = new Set([...BROWSER_TOOL_NAMES, ...WEB_TOOL_NAMES].filter((name) => name !== "browser_upload" && name !== "browser_downloads"));
54
50
  /** How long a release the store could not record may take at the provider. */
55
51
  const DIRECT_RELEASE_MS = 30_000;
56
52
  /** How long close waits to learn whether a Session that began closing failed. */
@@ -770,75 +766,10 @@ function sectionFor(c, names) {
770
766
  return undefined;
771
767
  const config = await input.read.snapshot(c.Config, input.conversationId, context);
772
768
  const offered = (tool) => input.agent.tools.some((t) => t.name === tool && names.has(tool));
773
- return [browserSection({ idleReleaseS: config?.policy.idleReleaseS ?? UNCONFIGURED.policy.idleReleaseS }, { downloads: offered("browser_downloads"), upload: offered("browser_upload") }), c.options.section?.addendum].filter(Boolean).join("\n\n");
769
+ return [browserSection({ idleReleaseS: config?.policy.idleReleaseS ?? UNCONFIGURED.policy.idleReleaseS }, { downloads: offered("browser_downloads"), upload: offered("browser_upload"), signedIn: c.options.signIns ?? !!c.options.sessionVault }), c.options.section?.addendum].filter(Boolean).join("\n\n");
774
770
  },
775
771
  };
776
772
  }
777
- function childConversation(c, api, context) {
778
- return async (task) => {
779
- const config = await api.snapshot(c.Config, api.conversationId, context);
780
- const childTools = (await api.agent(context)).tools.filter((tool) => CHILD_TOOLS.has(tool.name));
781
- // One child per request, recorded in the commit that creates it: a replay or a repeated call finds it again, and
782
- // its submission is deduplicated by request_id.
783
- const id = await api.commit(async (tx) => {
784
- const children = await tx.doc(c.Children, api.conversationId);
785
- const key = `${task.site}:${task.requestId}`;
786
- const known = children.byRequest[key];
787
- if (known !== undefined)
788
- return known;
789
- const child = await tx.createConversation({ ownership: { kind: "task", taskId: api.taskId } });
790
- await configure(tx, child.id, { tools: childTools, instructions: null });
791
- Object.assign(await tx.doc(c.Config, child.id), config ?? UNCONFIGURED);
792
- children.byRequest[key] = child.id;
793
- return child.id;
794
- }, context);
795
- const child = await api.conversation(id, context);
796
- if (!child)
797
- throw new Error("the child conversation is gone");
798
- // Children on a provider whose sessions share one browser would drive the same pages, so there they take turns. One
799
- // whose provider cannot be looked up waits its turn too: its own browser calls ask the factory again.
800
- const shared = await providerOf(c, api, id, PLANE, context).then((provider) => provider.caps.sharedBrowser === true, () => true);
801
- // The turn covers the report and the release too: on a shared browser the next child attaches only once this one has let go.
802
- const run = async () => {
803
- try {
804
- const settled = await (await child.submit({ type: "input", content: task.prompt, requestId: task.requestId }, context)).wait(context);
805
- const report = await api.commit(async (tx) => {
806
- for (const entry of (await tx.scanEntries({ conversationId: id, order: "descending" }, 50)).items) {
807
- for (const message of [...(entry.model ?? [])].reverse()) {
808
- if (message.role !== "assistant")
809
- continue;
810
- const text = message.content.filter((part) => part.type === "text").map((part) => part.text).join("").trim();
811
- if (text)
812
- return text;
813
- }
814
- }
815
- return "";
816
- }, context);
817
- if (settled.status !== "done" || !report)
818
- throw new Error("the child finished without a report");
819
- return report;
820
- }
821
- finally {
822
- await releasePlane(c, { id, commit: (change, ctx) => api.commit(change, ctx) }, "close", context).catch(() => undefined);
823
- }
824
- };
825
- return await (shared ? c.childTurns(run) : run());
826
- };
827
- }
828
- function siteTool(c, sites) {
829
- const contract = useWebsiteContract(sites.listing);
830
- return defineTool({
831
- name: contract.name,
832
- description: contract.description,
833
- parameters: contract.parameters,
834
- replay: contract.replay,
835
- executionMode: contract.executionMode,
836
- execute: async (args, api, context) => {
837
- const out = await useWebsite(args, sites.port, sites.listing, { signal: context.abortSignal ?? new AbortController().signal, runChild: childConversation(c, api, context) });
838
- return { ...forModel(redactContent(out.content, c.redact)), ...(out.isError ? { isError: true } : {}) };
839
- },
840
- });
841
- }
842
773
  /** A Session that a storage error failed ends `{ kind: "failed" }` (`closed`, pi-durable's SessionEnd), and close begins
843
774
  * at once (`subscribeClose`). */
844
775
  function endingOf(harness) {
@@ -859,7 +790,6 @@ export function createBrowserExtension(options) {
859
790
  const redact = createRedactor(() => [...providerKeyValues(process.env, options.redact?.values), ...tracked]);
860
791
  const vault = vaultRuntime(options, (secret) => { tracked.add(secret); }, (message) => process.emitWarning(`pi-browser: ${redact(message)}`, { code: "PI_BROWSER_VAULT" }));
861
792
  const Config = defineDoc({ kind: `${name}.config`, version: 1, scope: "conversation", history: "latest", fork: "current", initial: () => structuredClone(UNCONFIGURED), checkpointWhen: () => false });
862
- const Children = defineDoc({ kind: `${name}.children`, version: 1, scope: "conversation", history: "latest", fork: "current", initial: () => ({ byRequest: {} }), checkpointWhen: () => false });
863
793
  // A fork starts with no sessions: it never shares a live browser.
864
794
  const Sessions = defineDoc({ kind: `${name}.sessions`, version: 1, scope: "conversation", history: "latest", fork: "initial", initial: emptySessions, checkpointWhen: () => false });
865
795
  const readers = { options, redact, Config };
@@ -904,7 +834,7 @@ export function createBrowserExtension(options) {
904
834
  stopped: (tag) => { c.stops.get(tag)?.stop(); c.stops.delete(tag); },
905
835
  });
906
836
  const c = {
907
- ...readers, name, Sessions, Children, store, bill, held: new Attachments(), vault, fences: new Map(), leaving, serial: keyedSerializer(), childTurns: oneAtATime(), 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, serial: keyedSerializer(), guards: new Map(), owned, failed: false, stops: new Map(), ending: null, opened: null, incarnation: randomUUID(),
908
838
  idle: idleTracker({ idleMs: DEFAULT_BROWSER_POLICY.idleReleaseS * 1000, onIdle: (cid, fired, idleMs) => void releaseIdle(c, cid, fired, idleMs).catch(() => undefined) }),
909
839
  };
910
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
@@ -913,11 +843,10 @@ export function createBrowserExtension(options) {
913
843
  // pi checks a call's arguments against the tool's schema before execute, so each implementation receives its own shape.
914
844
  const tools = toolsFor(c, own);
915
845
  const names = new Set(tools.map((tool) => tool.name));
916
- const siteTools = options.sites ? [siteTool(c, options.sites)] : [];
917
846
  return {
918
- extension: defineExtension({ name, tools: [...tools, ...siteTools], sections: [sectionFor(c, names)], tasks: [store.ReleaseTask, store.HandoffTask] }),
919
- docs: { Config, Sessions, Inventory: store.Inventory, Children },
920
- tools: [...tools, ...siteTools],
847
+ extension: defineExtension({ name, tools, sections: [sectionFor(c, names)], tasks: [store.ReleaseTask, store.HandoffTask] }),
848
+ docs: { Config, Sessions, Inventory: store.Inventory },
849
+ tools,
921
850
  release: (conversation, reason, context) => releasePlane(c, conversation, reason, context),
922
851
  async reconcile(harness, isActive, context) {
923
852
  c.opened = { harness, context };
package/dist/index.d.ts CHANGED
@@ -17,7 +17,6 @@ export { isPrivateAddress, pinnedLookup, PUBLIC_MAX_BYTES, publicFetch, type Pub
17
17
  export { READ_DEADLINE_MS, READ_MAX_CHARS, readPage, type PageRead, type ReadPageOptions } from "./core/read-page.js";
18
18
  export * from "./core/receipts.js";
19
19
  export * from "./core/redact.js";
20
- export * from "./core/sites.js";
21
20
  export { DEFAULT_BROWSER_POLICY } from "./core/session-control.js";
22
21
  export * from "./core/tools.js";
23
22
  export * from "./core/usage.js";
package/dist/index.js CHANGED
@@ -18,7 +18,6 @@ export { isPrivateAddress, pinnedLookup, PUBLIC_MAX_BYTES, publicFetch } from ".
18
18
  export { READ_DEADLINE_MS, READ_MAX_CHARS, readPage } from "./core/read-page.js";
19
19
  export * from "./core/receipts.js";
20
20
  export * from "./core/redact.js";
21
- export * from "./core/sites.js";
22
21
  export { DEFAULT_BROWSER_POLICY } from "./core/session-control.js";
23
22
  export * from "./core/tools.js";
24
23
  export * from "./core/usage.js";
@@ -1,6 +1,6 @@
1
1
  import type { BrowserProvider } from "../core/host.js";
2
2
  import type { LiveViewHost } from "./server.js";
3
3
  /** The provider with a live view: `liveView(ref)` reports the viewer's URL (to the host only: its `onSession` and a handoff's `request`), and a release kills the
4
- * token before the provider's own release runs, so a session that is going away cannot be driven. Wrap the cdp provider with it, as the frame recorder
5
- * wraps a provider with `watch`; the provider's own methods are untouched. */
4
+ * token before the provider's own release runs, so a session that is going away cannot be driven. Wrap the cdp provider with it; the provider's own
5
+ * methods are untouched. */
6
6
  export declare function liveViewProvider(provider: BrowserProvider, host: LiveViewHost): BrowserProvider;
@@ -1,6 +1,6 @@
1
1
  /** The provider with a live view: `liveView(ref)` reports the viewer's URL (to the host only: its `onSession` and a handoff's `request`), and a release kills the
2
- * token before the provider's own release runs, so a session that is going away cannot be driven. Wrap the cdp provider with it, as the frame recorder
3
- * wraps a provider with `watch`; the provider's own methods are untouched. */
2
+ * token before the provider's own release runs, so a session that is going away cannot be driven. Wrap the cdp provider with it; the provider's own
3
+ * methods are untouched. */
4
4
  export function liveViewProvider(provider, host) {
5
5
  const wrapped = Object.create(provider);
6
6
  wrapped.liveView = async (ref) => {
@@ -58,7 +58,7 @@ export type LiveViewHost = {
58
58
  open(tag: string, cdpUrl: string): Promise<LiveView>;
59
59
  /** The view `open` gave for a tag, or null: for a caller that must not start anything (`liveViewProvider` asks before it attaches). */
60
60
  known(tag: string): LiveView | null;
61
- /** True while a person is driving this session (viewer input within the gate's idle window): the frame recorder holds its capture meanwhile. */
61
+ /** True while a person is driving this session (viewer input within the gate's idle window). */
62
62
  driving(tag: string): boolean;
63
63
  /** The token is dead, the viewer's socket closed, the stream and the gate ended. Idempotent. */
64
64
  release(tag: string): Promise<void>;
@@ -3,8 +3,6 @@ import { type CdpSession } from "./cdp-call.js";
3
3
  import { type ProfileStore } from "./profiles.js";
4
4
  export { rewriteConnectUrl, browserbaseNoProxyHosts, applyBrowserbaseNoProxy } from "./browserbase-net.js";
5
5
  export { fileProfileStore, memoryProfileStore, type ProfileStore } from "./profiles.js";
6
- export declare const SEARCH_QUERY_MAX = 200;
7
- export declare const SEARCH_RESULTS_MAX = 25;
8
6
  export type BrowserbaseSdk = {
9
7
  sessions: {
10
8
  create(body: BrowserbaseSessionBody, options?: RequestOptions): Promise<{
@@ -62,41 +60,12 @@ export type BrowserbaseSdk = {
62
60
  id: string;
63
61
  }>;
64
62
  };
65
- fetchAPI: {
66
- create(body: {
67
- url: string;
68
- allowRedirects?: boolean;
69
- proxies?: boolean;
70
- format?: string;
71
- }, options?: RequestOptions): Promise<FetchApiResult>;
72
- };
73
- search: {
74
- web(body: {
75
- query: string;
76
- numResults?: number;
77
- }, options?: RequestOptions): Promise<SearchApiResult>;
78
- };
79
63
  get<T = unknown>(path: string, options?: RequestOptions & {
80
64
  query?: Record<string, unknown>;
81
65
  headers?: Record<string, string>;
82
66
  __binaryResponse?: boolean;
83
67
  }): Promise<T>;
84
68
  };
85
- type FetchApiResult = {
86
- statusCode?: unknown;
87
- contentType?: unknown;
88
- content?: unknown;
89
- } | null | undefined;
90
- type SearchRow = {
91
- url?: unknown;
92
- title?: string | null;
93
- author?: string | null;
94
- publishedDate?: string | null;
95
- published?: string | null;
96
- };
97
- type SearchApiResult = {
98
- results?: SearchRow[];
99
- } | null | undefined;
100
69
  type BrowserbaseSessionBody = {
101
70
  proxies: boolean | Array<Record<string, unknown>>;
102
71
  timeout: number;