@parcha/pi-browser 0.1.0-beta.14 → 0.1.0-beta.16

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.
package/dist/durable.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { randomUUID } from "node:crypto";
2
2
  import { configure, defineDoc, defineExtension, defineTool, ToolResultEntry } from "@earendil-works/pi-durable";
3
3
  import { BROWSER_TOOL_NAMES, BROWSER_TOOLS, browserSection, WEB_TOOL_NAMES } from "./core/contract.js";
4
- import { BrowserFailureError, closeDriver, currentRecord, custodyTools, newSessionRecord, notices, NAVIGATION_CAP, relaunchRefusal, SESSION_REPLACED, sessionSpec } from "./core/custody.js";
4
+ import { BrowserFailureError, closeDriver, currentRecord, custodyTools, newSessionRecord, notices, NAVIGATION_CAP, profileRefusal, relaunchRefusal, SESSION_REPLACED, sessionSpec } from "./core/custody.js";
5
5
  import { forModel } from "./durable-result.js";
6
6
  import { EffectObserver, effectDecider, observerFailure } from "./core/effects.js";
7
7
  import { browserFailure, classifyBrowserError } from "./core/failures.js";
@@ -92,6 +92,20 @@ async function emitObserver(c, row) {
92
92
  }
93
93
  catch { }
94
94
  }
95
+ /** The host's crossing: called synchronously; what it throws or rejects with is reported and never reaches the call. */
96
+ function cross(c, point) {
97
+ const crossing = c.options.crossing;
98
+ if (!crossing)
99
+ return;
100
+ const warn = (error) => process.emitWarning(`pi-browser: the host's crossing threw at ${point}; the call goes on: ${error instanceof Error ? error.message : String(error)}`, { code: "PI_BROWSER_CROSSING" });
101
+ // Promise.resolve, not instanceof: a promise from another realm (node:vm) is caught too.
102
+ try {
103
+ Promise.resolve(crossing(point)).catch(warn);
104
+ }
105
+ catch (error) {
106
+ warn(error);
107
+ }
108
+ }
95
109
  async function emit(c, cid, label, record, change, provider) {
96
110
  if (!c.options.onSession)
97
111
  return;
@@ -170,6 +184,9 @@ async function create(c, scope, overrides, presetTag) {
170
184
  const provider = await c.options.provider({ conversationId: scope.cid, plane: scope.plane, config });
171
185
  const tag = presetTag ?? leaseTag("ar", config.run, scope.cid, (await stateOf(c, scope)).sessions.length + 1);
172
186
  const spec = sessionSpec(config, tag, overrides);
187
+ const unsupported = profileRefusal(spec, provider.caps);
188
+ if (unsupported)
189
+ throw new BrowserFailureError(unsupported);
173
190
  const record = newSessionRecord({ plane: scope.plane, tag, provider: provider.name, spec, at: now(), honours: provider.caps.settings });
174
191
  const row = rowOf(scope.cid, record);
175
192
  await scope.commit(async (tx) => {
@@ -229,12 +246,13 @@ const journalOf = (state, plane) => [...state.sessions].reverse().find((r) => r.
229
246
  const clearJournal = (c, scope, callId) => editState(c, scope, (state) => { for (const record of state.sessions)
230
247
  if (record.plane === scope.plane && record.pendingEffect?.callId === callId)
231
248
  record.pendingEffect = null; });
232
- /** Whether a journaled action's own answer was committed as a success: its result, found by pi's typed tool-result
233
- * entry. The scan covers only the entry's conversation from where it was journaled on, never the whole history. */
234
- async function answered(scope, pending) {
249
+ /** A journaled action's own answer as pi committed it, found by pi's typed tool-result entry: true for a success, false
250
+ * for an error, null for none yet. The scan covers only the entry's conversation from where it was journaled on, never
251
+ * the whole history. */
252
+ async function answerOf(scope, pending) {
235
253
  const after = pending.after;
236
254
  if (after === undefined)
237
- return false;
255
+ return null;
238
256
  return scope.commit(async (tx) => {
239
257
  let cursor;
240
258
  do {
@@ -246,9 +264,11 @@ async function answered(scope, pending) {
246
264
  }
247
265
  cursor = page.next;
248
266
  } while (cursor !== undefined);
249
- return false;
267
+ return null;
250
268
  });
251
269
  }
270
+ /** Whether a journaled action's own answer was committed as a success. */
271
+ const answered = async (scope, pending) => (await answerOf(scope, pending)) === true;
252
272
  /** The cut a call answers for. In this process an entry is in flight or answered, never cut; one an earlier process
253
273
  * wrote is a cut unless its action finished and pi committed its answer, which only then is looked up. */
254
274
  async function cutOf(c, scope, pending) {
@@ -314,18 +334,29 @@ function portFor(c, api, context) {
314
334
  relaunch: (overrides) => c.serial.run(key, () => relaunchOn(c, scope, api, memo("relaunch"), overrides)),
315
335
  release: () => c.serial.run(key, async () => {
316
336
  const record = currentRecord(await stateOf(c, scope), scope.plane);
317
- if (!record || !open(record))
318
- return { released: record?.state === "releasing", sessionId: record?.resourceId ?? null };
337
+ if (!record || !open(record)) {
338
+ // Only a release under way or done says so: a lost record is custody giving up, and its browser may still run.
339
+ const ended = (record?.state === "releasing" || record?.state === "released") && record.releaseReason ? { ended: { reason: record.releaseReason, at: record.endedAt } } : {};
340
+ return { released: record?.state === "releasing", sessionId: record?.resourceId ?? null, ...ended };
341
+ }
319
342
  await releaseRecord(c, scope, record, "tool");
320
343
  return { released: true, sessionId: record.resourceId };
321
344
  }),
322
- dispatching: (effect) => scope.commit(async (tx) => {
323
- const record = currentRecord(await tx.doc(c.Sessions, scope.cid), scope.plane);
324
- if (!record)
325
- return;
326
- const newest = (await tx.scanEntries({ conversationId: scope.cid, order: "descending" }, 1)).items[0]?.id;
327
- record.pendingEffect = { ...effect, url: effect.url === null ? null : scrubPageUrl(effect.url, c.redact), at: now(), sent: [], incarnation: c.incarnation, ...(newest === undefined ? {} : { after: newest }) };
328
- }),
345
+ dispatching: async (effect) => {
346
+ // The host's mid-browse crossing: the page action before this one finished and pi committed its answer.
347
+ if (c.options.crossing) {
348
+ const previous = journalOf(await stateOf(c, scope), scope.plane);
349
+ if (previous?.finished && (await answerOf(scope, previous)) !== null)
350
+ cross(c, "browser.between-actions");
351
+ }
352
+ await scope.commit(async (tx) => {
353
+ const record = currentRecord(await tx.doc(c.Sessions, scope.cid), scope.plane);
354
+ if (!record)
355
+ return;
356
+ const newest = (await tx.scanEntries({ conversationId: scope.cid, order: "descending" }, 1)).items[0]?.id;
357
+ record.pendingEffect = { ...effect, url: effect.url === null ? null : scrubPageUrl(effect.url, c.redact), at: now(), sent: [], incarnation: c.incarnation, ...(newest === undefined ? {} : { after: newest }) };
358
+ });
359
+ },
329
360
  journal: (row) => editState(c, scope, (state) => {
330
361
  const pending = currentRecord(state, scope.plane)?.pendingEffect;
331
362
  if (!pending)
@@ -338,11 +369,20 @@ function portFor(c, api, context) {
338
369
  else
339
370
  sent[at] = scrubbed;
340
371
  }),
341
- mark: (step, callId) => editState(c, scope, (state) => {
342
- const pending = state.sessions.find((r) => r.plane === scope.plane && r.pendingEffect?.callId === callId)?.pendingEffect;
343
- if (pending)
344
- pending[step] = true;
345
- }),
372
+ mark: async (step, callId) => {
373
+ const found = { pending: false };
374
+ await editState(c, scope, (state) => {
375
+ const pending = state.sessions.find((r) => r.plane === scope.plane && r.pendingEffect?.callId === callId)?.pendingEffect;
376
+ if (pending) {
377
+ pending[step] = true;
378
+ found.pending = true;
379
+ }
380
+ });
381
+ // The host's double-run crossing: the action's driver call is over and its entry says so; pi has not committed
382
+ // the answer.
383
+ if (found.pending && step === "finished")
384
+ cross(c, "browser.action-returned");
385
+ },
346
386
  settle: (callId) => clearJournal(c, scope, callId),
347
387
  navigated: async (page) => {
348
388
  // A page URL can carry a credential in any query value, its fragment or its userinfo: scrubbed before it is
@@ -1,6 +1,8 @@
1
1
  import type { BrowserProvider, Geo, PriceTable, SessionSpec } from "../core/host.js";
2
2
  import { type CdpSession } from "./cdp-call.js";
3
+ import { type ProfileStore } from "./profiles.js";
3
4
  export { rewriteConnectUrl, browserbaseNoProxyHosts, applyBrowserbaseNoProxy } from "./browserbase-net.js";
5
+ export { fileProfileStore, type ProfileStore } from "./profiles.js";
4
6
  export declare const SEARCH_QUERY_MAX = 200;
5
7
  export declare const SEARCH_RESULTS_MAX = 25;
6
8
  export type BrowserbaseSdk = {
@@ -53,6 +55,13 @@ export type BrowserbaseSdk = {
53
55
  id: string;
54
56
  }>;
55
57
  };
58
+ contexts: {
59
+ create(body: {
60
+ projectId?: string;
61
+ }, options?: RequestOptions): Promise<{
62
+ id: string;
63
+ }>;
64
+ };
56
65
  fetchAPI: {
57
66
  create(body: {
58
67
  url: string;
@@ -130,6 +139,10 @@ export type BrowserbaseOptions = {
130
139
  intervalMs: number;
131
140
  };
132
141
  sleep?: (ms: number) => Promise<void>;
142
+ /** Where profile names find their Browserbase contexts. Default: a file under the user's config directory. */
143
+ profiles?: ProfileStore;
144
+ /** How long a release that saved a profile waits for Browserbase to write the context back. */
145
+ profileSettleMs?: number;
133
146
  };
134
147
  /** `Browser.setDownloadBehavior` lasts only as long as the socket that sent it, so the socket stays open until
135
148
  * `close()`. */
@@ -148,5 +161,9 @@ export declare function proxiesField(proxies: SessionSpec["proxies"]): boolean |
148
161
  export declare function sessionCreateBody(spec: SessionSpec, extra?: {
149
162
  extensionId?: string;
150
163
  projectId?: string;
164
+ context?: {
165
+ id: string;
166
+ persist: boolean;
167
+ };
151
168
  }): BrowserbaseSessionBody;
152
169
  export declare function browserbaseProvider(options?: BrowserbaseOptions): BrowserbaseProvider;
@@ -5,14 +5,18 @@ import { fetchUsage, resolvePrices, searchUsage } from "../core/usage.js";
5
5
  import { cdpCall } from "./cdp-call.js";
6
6
  import { applyBrowserbaseNoProxy, bindConnectDial, installWebSocketWrapper, rewriteConnectUrl, unbindConnectDial } from "./browserbase-net.js";
7
7
  import { directFetch } from "./http.js";
8
+ import { claimWriter, fileProfileStore, freeWriter, isWriter, noteWriter } from "./profiles.js";
8
9
  import { accountKey, assertTag, browserbaseHoldings, defaultSleep, DEFAULT_CONFIRM, extensionArchive, nonEmpty, releaseAndConfirm, tagValue, untilAborted, uploadOnce } from "./shared.js";
9
10
  export { rewriteConnectUrl, browserbaseNoProxyHosts, applyBrowserbaseNoProxy } from "./browserbase-net.js";
11
+ export { fileProfileStore } from "./profiles.js";
10
12
  export const SEARCH_QUERY_MAX = 200;
11
13
  export const SEARCH_RESULTS_MAX = 25;
12
14
  /** Into `downloadPath` (default `downloads`, Browserbase's synced-downloads rule); the socket stays open. */
13
15
  export const setDownloadBehavior = (url, options = {}) => cdpCall(url, "Browser.setDownloadBehavior", { behavior: "allow", downloadPath: options.downloadPath ?? "downloads", eventsEnabled: true }, options.timeoutMs);
14
- const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 21_600, survivesDisconnect: true, releaseIsAsync: true, extension: "uploaded-per-launch", settings: { proxies: true, verified: true, geolocation: true, region: true, context: true } };
16
+ const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 21_600, survivesDisconnect: true, releaseIsAsync: true, profiles: true, extension: "uploaded-per-launch", settings: { proxies: true, verified: true, geolocation: true, region: true, context: true } };
15
17
  const notFound = (e) => e?.status === 404;
18
+ /** One signal for whichever of these there is (a store may call `make` without its limit). */
19
+ const stopWhen = (...signals) => { const some = signals.filter((s) => s !== undefined); return some.length > 1 ? AbortSignal.any(some) : some[0]; };
16
20
  /** ISO alpha-2 country, US state abbreviation, upper-case city; no two-letter country, no geolocation. */
17
21
  export function browserbaseGeolocation(raw) {
18
22
  const country = nonEmpty(raw?.country).toUpperCase();
@@ -38,7 +42,7 @@ export function sessionCreateBody(spec, extra = {}) {
38
42
  solveCaptchas: spec.captcha,
39
43
  viewport: spec.viewport,
40
44
  ...(spec.verified ? { verified: true } : {}),
41
- ...(spec.contextId ? { context: { id: spec.contextId, persist: true } } : {}),
45
+ ...(extra.context ? { context: extra.context } : spec.contextId ? { context: { id: spec.contextId, persist: true } } : {}),
42
46
  ...(spec.navigation?.allow?.length ? { allowedDomains: spec.navigation.allow } : {}),
43
47
  };
44
48
  const userMetadata = Object.fromEntries(Object.entries(spec.metadata).map(([k, v]) => [k, tagValue(v)]));
@@ -69,6 +73,7 @@ export function browserbaseProvider(options = {}) {
69
73
  const sleep = options.sleep ?? defaultSleep;
70
74
  const confirm = options.confirm ?? DEFAULT_CONFIRM;
71
75
  const prices = resolvePrices(options.prices);
76
+ const profiles = options.profiles ?? fileProfileStore();
72
77
  let sdk = null;
73
78
  const client = () => (sdk ??= options.client ? Promise.resolve(options.client) : (async () => {
74
79
  applyBrowserbaseNoProxy(env);
@@ -80,6 +85,7 @@ export function browserbaseProvider(options = {}) {
80
85
  const extension = () => options.extensionId
81
86
  ? options.extensionId()
82
87
  : uploadOnce(uploads, account, async () => (await (await client()).extensions.create({ file: createReadStream(extensionArchive()) }, { maxRetries: 0 })).id);
88
+ const contextFor = (name, projectId, signal) => profiles.resolve(held(`profile:${name}`), async (limit) => (await (await client()).contexts.create({ ...(projectId && !baseUrl && !connectBase ? { projectId } : {}) }, { maxRetries: 0, signal: stopWhen(signal, limit) })).id);
83
89
  const rows = async (sessionId) => {
84
90
  const all = [];
85
91
  for (let offset = 0;;) {
@@ -91,6 +97,23 @@ export function browserbaseProvider(options = {}) {
91
97
  return all;
92
98
  }
93
99
  };
100
+ const settling = new Set();
101
+ const running = (ref) => async (signal) => { if (settling.has(ref.tag))
102
+ return true; const now = await status(ref, signal); return now === "running" || now === "pending"; };
103
+ /** A saving session's context is written back after it ends, and the next session must not read it before then. */
104
+ const finished = async (ref) => {
105
+ forget(held(ref.id));
106
+ if (isWriter(ref.tag)) {
107
+ settling.add(ref.tag);
108
+ try {
109
+ await sleep(options.profileSettleMs ?? 5_000);
110
+ }
111
+ finally {
112
+ settling.delete(ref.tag);
113
+ }
114
+ }
115
+ freeWriter(ref.tag);
116
+ };
94
117
  const status = async (ref, signal) => {
95
118
  try {
96
119
  const found = await (await client()).sessions.retrieve(ref.id, { signal, timeout: 5_000 });
@@ -107,12 +130,24 @@ export function browserbaseProvider(options = {}) {
107
130
  caps: CAPS,
108
131
  async create(spec, signal) {
109
132
  const projectId = nonEmpty(env.BROWSERBASE_PROJECT_ID);
110
- // Behind the credential proxy the project is inferred from the injected key and must never be named; a direct key
111
- // must name it.
112
- const body = sessionCreateBody(spec, { extensionId: await extension(), ...(projectId && !baseUrl && !connectBase ? { projectId } : {}) });
113
- // At most once: an SDK retry of a create the server already served would open a second paid browser.
133
+ if (spec.profile?.save)
134
+ await claimWriter(held(`profile:${spec.profile.name}`), spec.profile.name, spec.tag, `${spec.metadata.run}|${spec.metadata.label}`, signal);
135
+ let body;
136
+ try {
137
+ const context = spec.profile ? { id: await contextFor(spec.profile.name, projectId, signal), persist: spec.profile.save } : undefined;
138
+ // Behind the credential proxy the project is inferred from the injected key and must never be named; a direct key
139
+ // must name it.
140
+ body = sessionCreateBody(spec, { extensionId: await extension(), ...(projectId && !baseUrl && !connectBase ? { projectId } : {}), ...(context ? { context } : {}) });
141
+ }
142
+ catch (error) {
143
+ freeWriter(spec.tag);
144
+ throw error;
145
+ }
146
+ // At most once: an SDK retry of a create the server already served would open a second paid browser. A failed send keeps
147
+ // the profile's claim until findByTag has looked: the session may exist.
114
148
  const created = await (await client()).sessions.create(body, { maxRetries: 0, signal });
115
149
  connectUrls.set(held(created.id), created.connectUrl);
150
+ noteWriter(spec.tag, running({ id: created.id, tag: spec.tag }), () => sleep(options.profileSettleMs ?? 5_000));
116
151
  return { id: created.id, tag: spec.tag };
117
152
  },
118
153
  async findByTag(tag, signal) {
@@ -124,7 +159,13 @@ export function browserbaseProvider(options = {}) {
124
159
  // The query is the provider's, the match is ours: a lane that ignores `q` must never hand back someone else's
125
160
  // session. Both queries must answer: custody releases exactly these ids, so a failed status throws.
126
161
  const seen = new Set();
127
- return asked.flat().filter((r) => r.userMetadata?.agentrun_tag === tag && !seen.has(r.id) && seen.add(r.id)).map((r) => ({ id: r.id, tag }));
162
+ const found = asked.flat().filter((r) => r.userMetadata?.agentrun_tag === tag && !seen.has(r.id) && seen.add(r.id)).map((r) => ({ id: r.id, tag }));
163
+ if (!found.length)
164
+ freeWriter(tag);
165
+ for (const ref of found)
166
+ if (isWriter(ref.tag))
167
+ noteWriter(ref.tag, running(ref), () => sleep(options.profileSettleMs ?? 5_000));
168
+ return found;
128
169
  },
129
170
  status,
130
171
  async attach(ref, signal) {
@@ -170,7 +211,7 @@ export function browserbaseProvider(options = {}) {
170
211
  }
171
212
  },
172
213
  status: () => status(ref, signal),
173
- forget: () => forget(held(ref.id)),
214
+ forget: () => finished(ref),
174
215
  confirm,
175
216
  sleep,
176
217
  stillRunning: `Browserbase session ${ref.id} still running after a release request`,
@@ -1,3 +1,4 @@
1
+ import { type ChildProcess } from "node:child_process";
1
2
  import type { BrowserProvider } from "../core/host.js";
2
3
  export type CdpOptions =
3
4
  /** An existing browser: `http://host:port` or a `ws://` debugger URL. Release leaves it running. */
@@ -41,6 +42,12 @@ export declare class ProfileOwnershipUnclearError extends Error {
41
42
  readonly code = "profile_ownership_unclear";
42
43
  constructor(dir: string, port: number);
43
44
  }
45
+ /** A copy of a profile another Chrome is writing: that Chrome renames, truncates and deletes its journals and temp files
46
+ * all the time. A file gone by the time it is reached is skipped. `fs.cp` fails the whole copy on it, and `fs.copyFile`
47
+ * never returns for a file truncated while it copies (libuv's sendfile loop makes no progress and does not stop), so
48
+ * files go through streams, which end where the file ends. A cancelled `signal` stops the copy at the next file or chunk. */
49
+ export declare function copyProfile(from: string, to: string, signal?: AbortSignal): Promise<void>;
50
+ export declare function closeGracefully(port: number, pid: number, children: Map<number, ChildProcess>): Promise<void>;
44
51
  /** A pid reaches here from a ref's id, which a restart reads back from a record: `kill(-1)` signals every process the user can,
45
52
  * `kill(0)` this process's own group, so neither a pid below 2 nor our own is ever signalled, and a negative pid (a whole group)
46
53
  * only for a process that leads one. */