@parcha/pi-browser 0.1.0-beta.26 → 0.1.0-beta.28
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/CHANGELOG.md +10 -0
- package/README.md +19 -5
- package/dist/coding-agent-local.d.ts +1 -6
- package/dist/coding-agent-local.js +9 -79
- package/dist/coding-agent.d.ts +10 -1
- package/dist/coding-agent.js +45 -10
- package/dist/core/contract.d.ts +2 -0
- package/dist/core/contract.js +7 -1
- package/dist/core/decisions.d.ts +3 -1
- package/dist/core/effects.d.ts +8 -0
- package/dist/core/effects.js +54 -5
- package/dist/core/host.d.ts +24 -6
- package/dist/core/public-fetch.d.ts +39 -0
- package/dist/core/public-fetch.js +159 -0
- package/dist/core/vault.d.ts +68 -0
- package/dist/core/vault.js +79 -0
- package/dist/core/web.d.ts +31 -0
- package/dist/core/web.js +145 -14
- package/dist/driver/stagehand.js +2 -1
- package/dist/durable/web.d.ts +7 -1
- package/dist/durable/web.js +4 -1
- package/dist/durable.d.ts +2 -1
- package/dist/durable.js +58 -10
- package/dist/index.d.ts +2 -0
- package/dist/index.js +2 -0
- package/dist/providers/browserbase.d.ts +1 -1
- package/dist/providers/browserbase.js +11 -1
- package/dist/providers/cdp-session.d.ts +28 -0
- package/dist/providers/cdp-session.js +153 -0
- package/dist/providers/cdp.d.ts +6 -0
- package/dist/providers/cdp.js +52 -2
- package/dist/providers/chrome-args.d.ts +3 -1
- package/dist/providers/chrome-args.js +3 -2
- package/dist/providers/kernel.js +6 -0
- package/dist/providers/profiles.d.ts +4 -0
- package/dist/providers/profiles.js +10 -0
- package/dist/providers/worker-extension.d.ts +14 -0
- package/dist/providers/worker-extension.js +63 -0
- package/dist/vault-session.d.ts +58 -0
- package/dist/vault-session.js +219 -0
- package/package.json +5 -1
package/dist/durable/web.d.ts
CHANGED
|
@@ -2,7 +2,7 @@ import { defineExtension, type ConversationId, type ToolRegistration } from "@ea
|
|
|
2
2
|
import type { Decisions } from "../core/decisions.js";
|
|
3
3
|
import type { EvidenceSink } from "../core/evidence.js";
|
|
4
4
|
import type { FetchRequest, FetchResult, PriceTable, SearchRequest, SearchResult } from "../core/host.js";
|
|
5
|
-
import { type RenderedPage, type WebBackup, type WebToolsOptions } from "../core/web.js";
|
|
5
|
+
import { type FetchSource, type RenderedPage, type SearchSource, type WebBackup, type WebToolsOptions } from "../core/web.js";
|
|
6
6
|
export type WebExtensionOptions = {
|
|
7
7
|
providers: {
|
|
8
8
|
/** Names the source in `via` (`<name>_fetch`, `<name>_search`); default "provider". */
|
|
@@ -10,6 +10,10 @@ export type WebExtensionOptions = {
|
|
|
10
10
|
fetch?: (request: FetchRequest, signal?: AbortSignal) => Promise<FetchResult>;
|
|
11
11
|
search?: (request: SearchRequest, signal?: AbortSignal) => Promise<SearchResult>;
|
|
12
12
|
};
|
|
13
|
+
/** Searches tried before `providers.search`, in order (see `SearchSource`). */
|
|
14
|
+
searchSources?: readonly SearchSource[];
|
|
15
|
+
/** Readers tried before `providers.fetch` for a markdown read, in order (see `FetchSource`). */
|
|
16
|
+
fetchSources?: readonly FetchSource[];
|
|
13
17
|
evidence: EvidenceSink;
|
|
14
18
|
/** Per use: evidence label and proxies. Default: label "web", proxies on. */
|
|
15
19
|
scope?: (conversationId: ConversationId) => {
|
|
@@ -31,6 +35,8 @@ export type WebExtensionOptions = {
|
|
|
31
35
|
read(url: string, signal?: AbortSignal): Promise<RenderedPage>;
|
|
32
36
|
};
|
|
33
37
|
pdf?: WebToolsOptions["pdf"];
|
|
38
|
+
/** How long the screening of a search answer's snippets may take in all (see `WebToolsOptions`). */
|
|
39
|
+
snippetScreenMs?: number;
|
|
34
40
|
section?: {
|
|
35
41
|
addendum?: string;
|
|
36
42
|
};
|
package/dist/durable/web.js
CHANGED
|
@@ -9,6 +9,8 @@ export function createWebExtension(options) {
|
|
|
9
9
|
name: options.providers.name ?? "provider",
|
|
10
10
|
fetch: options.providers.fetch,
|
|
11
11
|
search: options.providers.search,
|
|
12
|
+
searchSources: options.searchSources,
|
|
13
|
+
fetchSources: options.fetchSources,
|
|
12
14
|
evidence: options.evidence,
|
|
13
15
|
scope: options.scope ?? (() => ({ label: "web", proxies: true })),
|
|
14
16
|
prices: options.prices,
|
|
@@ -17,11 +19,12 @@ export function createWebExtension(options) {
|
|
|
17
19
|
classifyPage: options.decisions?.classifyPage,
|
|
18
20
|
render: options.render,
|
|
19
21
|
pdf: options.pdf,
|
|
22
|
+
snippetScreenMs: options.snippetScreenMs,
|
|
20
23
|
});
|
|
21
24
|
const run = { web_fetch: tools.fetch, web_search: tools.search };
|
|
22
25
|
const result = ({ text, isError, details, usd }) => ({ ...forModel([{ type: "text", text }]), isError, details: details, usage: toolUsage(usd).usage });
|
|
23
26
|
const registrations = WEB_TOOLS
|
|
24
|
-
.filter((tool) => (tool.listedWhen === "fetch" ? options.providers.fetch || options.render?.enabled || options.backups?.length : options.providers.search))
|
|
27
|
+
.filter((tool) => (tool.listedWhen === "fetch" ? options.providers.fetch || options.render?.enabled || options.backups?.length || options.fetchSources?.length : options.providers.search || options.searchSources?.length))
|
|
25
28
|
.map((tool) => defineTool({
|
|
26
29
|
name: tool.name,
|
|
27
30
|
description: tool.description,
|
package/dist/durable.d.ts
CHANGED
|
@@ -4,12 +4,13 @@ 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 VaultOptions } from "./vault-session.js";
|
|
7
8
|
import type { DrivingGates } from "./live-view/protocol.js";
|
|
8
9
|
import { type BrowserToolImpls, type PageDriver } from "./core/tools.js";
|
|
9
10
|
import type { BrowserConfig, BrowserProvider, InventoryRow, ObserverRow, PriceTable, ReconcileReport, ReleaseReason, SessionChange, SessionRow, SessionsState, SiteInfo, SiteRunPort, HandoffPort, WorkspaceFiles } from "./core/host.js";
|
|
10
11
|
export type { BrowserToolArgs, BrowserToolImpls, PageDriver, ToolCall, ToolImpl } from "./core/tools.js";
|
|
11
12
|
export type { DriverFactory, DriverOptions } from "./core/custody.js";
|
|
12
|
-
export type BrowserExtensionOptions<D extends PageDriver = PageDriver> = {
|
|
13
|
+
export type BrowserExtensionOptions<D extends PageDriver = PageDriver> = VaultOptions & {
|
|
13
14
|
/** Default "browser"; a second plane installs a second extension under another name. */
|
|
14
15
|
name?: string;
|
|
15
16
|
/** Called per use: the provider for this conversation's plane. Holds the credentials in its closure; nothing it
|
package/dist/durable.js
CHANGED
|
@@ -7,7 +7,8 @@ import { EffectObserver, effectDecider, observerFailure } from "./core/effects.j
|
|
|
7
7
|
import { browserFailure, classifyBrowserError } from "./core/failures.js";
|
|
8
8
|
import { workspaceFiles } from "./core/files.js";
|
|
9
9
|
import { drivingGuarded } from "./core/driving-guard.js";
|
|
10
|
-
import { drivingGates, keptReason, personOn, rearmWhenLeft } from "./core/driving.js";
|
|
10
|
+
import { drivingGates, keptFor, keptReason, personOn, rearmWhenLeft } from "./core/driving.js";
|
|
11
|
+
import { captureFor, planRestore, untilQuiet, vaultRuntime } from "./vault-session.js";
|
|
11
12
|
import { pageTools } from "./core/tools.js";
|
|
12
13
|
import { useWebsite, useWebsiteContract } from "./core/sites.js";
|
|
13
14
|
import { leaseTag } from "./core/lease.js";
|
|
@@ -63,10 +64,16 @@ class Attachments {
|
|
|
63
64
|
observer(tag) {
|
|
64
65
|
return this.observers.get(tag);
|
|
65
66
|
}
|
|
66
|
-
|
|
67
|
+
captures = new Map();
|
|
68
|
+
attach(tag, driver, observer, capture = null) {
|
|
67
69
|
this.observers.set(tag, observer);
|
|
68
70
|
this.drivers.set(tag, driver);
|
|
71
|
+
if (capture && !this.captures.has(tag))
|
|
72
|
+
this.captures.set(tag, capture);
|
|
69
73
|
}
|
|
74
|
+
/** The vault capture of this session, if it has one: run while its browser still exists. It outlives the driver's attachment (a session held for a person has none) and ends with the session's release. */
|
|
75
|
+
async capture(tag) { await this.captures.get(tag)?.(); }
|
|
76
|
+
dropCapture(tag) { this.captures.delete(tag); }
|
|
70
77
|
async detach(tag) {
|
|
71
78
|
const driver = this.drivers.get(tag);
|
|
72
79
|
this.drivers.delete(tag);
|
|
@@ -166,11 +173,14 @@ async function attachLive(c, scope, record, bound) {
|
|
|
166
173
|
return null;
|
|
167
174
|
}
|
|
168
175
|
}
|
|
169
|
-
async function connect(c, scope, provider, ref) {
|
|
176
|
+
async function connect(c, scope, provider, ref, afterAttach = null, vaulted = true, holdBack) {
|
|
170
177
|
const config = await scopeConfig(c, scope);
|
|
171
178
|
const { actions: policy, batchTimeoutMs } = config.policy;
|
|
172
179
|
c.owned.set(ref.tag, { cid: scope.cid, provider, ref });
|
|
173
180
|
const target = await provider.attach(ref, scope.signal);
|
|
181
|
+
// A kept sign-in is put back before the driver, and so before any page, attaches.
|
|
182
|
+
if (afterAttach)
|
|
183
|
+
await afterAttach(target);
|
|
174
184
|
const driver = await c.options.driver(target, scope.signal, { batchTimeoutMs });
|
|
175
185
|
let unattached = null;
|
|
176
186
|
// A healthy observer that outlived its driver's connection is kept, not opened a second time.
|
|
@@ -182,7 +192,19 @@ async function connect(c, scope, provider, ref) {
|
|
|
182
192
|
await closeDriver(driver);
|
|
183
193
|
throw new BrowserFailureError(browserFailure("browser_unavailable", "The browser's request observer could not attach, and this run's action policy needs it to hold requests; the browser is not used without it.", { retryable: true }));
|
|
184
194
|
}
|
|
185
|
-
|
|
195
|
+
// The capture reads the conversation's CURRENT vault target when it runs, not the one at create: a host may set it mid-run, once it knows the site, and may take it away
|
|
196
|
+
// (a read that succeeds and finds none means "do not keep this session"). Only a read that fails falls back to the target the session was created with.
|
|
197
|
+
const currentVault = async () => {
|
|
198
|
+
if (!c.opened)
|
|
199
|
+
return config.vault;
|
|
200
|
+
try {
|
|
201
|
+
return (await c.opened.harness.snapshot(c.Config, scope.cid, c.opened.context))?.vault;
|
|
202
|
+
}
|
|
203
|
+
catch {
|
|
204
|
+
return config.vault;
|
|
205
|
+
}
|
|
206
|
+
};
|
|
207
|
+
c.held.attach(ref.tag, driver, observer, c.vault ? captureFor(c.vault, currentVault, provider, ref, { vaulted, ...(holdBack ? { holdBack } : {}), gate: () => personOn(c.options.gates ?? drivingGates, ref.tag) }) : null);
|
|
186
208
|
if (policy === "allow" && !observer)
|
|
187
209
|
await emitObserver(c, { conversationId: scope.cid, label: config.label, tag: ref.tag, session_id: ref.id, policy, code: observerFailure(unattached) });
|
|
188
210
|
return driver;
|
|
@@ -217,6 +239,8 @@ async function create(c, scope, overrides, presetTag) {
|
|
|
217
239
|
const unsupported = profileRefusal(spec, provider.caps) ?? navigationRefusal(spec, provider);
|
|
218
240
|
if (unsupported)
|
|
219
241
|
throw new BrowserFailureError(unsupported);
|
|
242
|
+
// The vault may name a context or profile for the provider; the record stored below is made from the spec WITHOUT it, so no context id reaches the store.
|
|
243
|
+
const plan = await planRestore(c.vault, config.vault, provider, spec);
|
|
220
244
|
const record = newSessionRecord({ plane: scope.plane, tag, provider: provider.name, spec, at: now(), honours: provider.caps.settings });
|
|
221
245
|
const row = rowOf(scope.cid, record);
|
|
222
246
|
await scope.commit(async (tx) => {
|
|
@@ -226,7 +250,7 @@ async function create(c, scope, overrides, presetTag) {
|
|
|
226
250
|
await c.store.begin(tx, row);
|
|
227
251
|
});
|
|
228
252
|
// An answer lost on the way back is not a session that never started: it is settled by its tag.
|
|
229
|
-
const ref = await provider.create(spec, scope.signal).then(async (made) => {
|
|
253
|
+
const ref = await provider.create(plan.spec, scope.signal).then(async (made) => {
|
|
230
254
|
// Owned before it is recorded: a store that cannot record it still lets close release it.
|
|
231
255
|
c.owned.set(tag, { cid: scope.cid, provider, ref: made });
|
|
232
256
|
await scope.commit((tx) => c.store.move(tx, row, { state: "live", resourceId: made.id, at: now() }));
|
|
@@ -241,7 +265,10 @@ async function create(c, scope, overrides, presetTag) {
|
|
|
241
265
|
});
|
|
242
266
|
const live = { ...record, state: "live", resourceId: ref.id };
|
|
243
267
|
try {
|
|
244
|
-
const driver = await connect(c, scope, provider, ref);
|
|
268
|
+
const driver = await connect(c, scope, provider, ref, plan.afterAttach, plan.vaulted, plan.holdBack);
|
|
269
|
+
// A context made for this session is given to the vault now, so a restart that loses the provider's memory of it still finds it.
|
|
270
|
+
if (plan.fresh)
|
|
271
|
+
await c.held.capture(ref.tag);
|
|
245
272
|
await emit(c, scope.cid, config.label, live, "launched", provider);
|
|
246
273
|
return { record: live, driver };
|
|
247
274
|
}
|
|
@@ -299,9 +326,20 @@ function replacedOf(state, plane, current) {
|
|
|
299
326
|
return reason === "idle" || reason === "close" || reason === "lost" ? { reason, at: before.endedAt, lastUrl: before.lastUrl } : null;
|
|
300
327
|
}
|
|
301
328
|
async function releaseRecord(c, scope, record, reason) {
|
|
329
|
+
await captureSession(c, record.tag);
|
|
302
330
|
await scope.commit((tx) => c.store.requestRelease(tx, rowOf(scope.cid, record), reason, now()));
|
|
303
331
|
await c.held.detach(record.tag);
|
|
304
332
|
}
|
|
333
|
+
/** The vault capture of one session while its browser exists, skipped while a person is driving it (a capture reads only once they have handed back). Never throws. */
|
|
334
|
+
async function captureSession(c, tag, wait = false) {
|
|
335
|
+
if (!c.vault)
|
|
336
|
+
return;
|
|
337
|
+
const gate = personOn(c.options.gates ?? drivingGates, tag);
|
|
338
|
+
// At a handoff's end the person has just let go: their last input is within the driving window, so it is waited out (bounded) before the browser is read.
|
|
339
|
+
if (!(wait ? await untilQuiet(gate) : !gate || keptFor(gate) !== "person_driving"))
|
|
340
|
+
return;
|
|
341
|
+
await c.held.capture(tag);
|
|
342
|
+
}
|
|
305
343
|
const editState = (c, scope, edit) => scope.commit(async (tx) => edit(await tx.doc(c.Sessions, scope.cid)));
|
|
306
344
|
async function relaunchOn(c, scope, api, slot, overrides) {
|
|
307
345
|
const config = await scopeConfig(c, scope);
|
|
@@ -528,6 +566,10 @@ function portFor(c, api, context) {
|
|
|
528
566
|
const { state } = await api.waitForTask(task, context);
|
|
529
567
|
if (state.outcome.status === "completed" && state.outcome.result) {
|
|
530
568
|
const { outcome } = state.outcome.result;
|
|
569
|
+
// A sign-in just happened and the person has handed back: kept now, so a crash after it does not lose it.
|
|
570
|
+
const current = currentRecord(await stateOf(c, scope), scope.plane);
|
|
571
|
+
if (current)
|
|
572
|
+
await captureSession(c, current.tag, true);
|
|
531
573
|
const told = notices.handedBack(outcome, ask.completionCondition);
|
|
532
574
|
if ((await stateOf(c, scope)).notice?.includes(told)) {
|
|
533
575
|
await editState(c, scope, (sessions) => { sessions.notice = sessions.notice?.replace(told, "").replace(/\s+/g, " ").trim() || null; });
|
|
@@ -590,6 +632,8 @@ async function releasePlane(c, conversation, reason, context, still = () => true
|
|
|
590
632
|
const kept = { gate: null, tag: "" };
|
|
591
633
|
const released = await c.serial.run(key, async () => {
|
|
592
634
|
const mine = () => c.held.tags().filter((tag) => c.owned.get(tag)?.cid === conversation.id);
|
|
635
|
+
// Kept before anything closes: the browser is still there, and a release that is cancelled (a call since) only made one capture more.
|
|
636
|
+
await Promise.all(leasesOf(c, conversation.id).map((tag) => captureSession(c, tag)));
|
|
593
637
|
// Closing a driver needs nothing from the store, so a release other than idle's starts closing the conversation's
|
|
594
638
|
// drivers first and never waits for the commit to do it; the commit runs alongside, so the release task starts as
|
|
595
639
|
// early as before. An idle release leaves it to the commit, which can find a call since or a person on the live view.
|
|
@@ -787,7 +831,10 @@ function endingOf(harness) {
|
|
|
787
831
|
}
|
|
788
832
|
export function createBrowserExtension(options) {
|
|
789
833
|
const name = options.name ?? "browser";
|
|
790
|
-
|
|
834
|
+
// Secrets the package itself comes to hold (a vault's provider context id): registered as they are seen, so no output can carry one.
|
|
835
|
+
const tracked = new Set();
|
|
836
|
+
const redact = createRedactor(() => [...providerKeyValues(process.env, options.redact?.values), ...tracked]);
|
|
837
|
+
const vault = vaultRuntime(options, (secret) => { tracked.add(secret); }, (message) => process.emitWarning(`pi-browser: ${redact(message)}`, { code: "PI_BROWSER_VAULT" }));
|
|
791
838
|
const Config = defineDoc({ kind: `${name}.config`, version: 1, scope: "conversation", history: "latest", fork: "current", initial: () => structuredClone(UNCONFIGURED) });
|
|
792
839
|
const Children = defineDoc({ kind: `${name}.children`, version: 1, scope: "conversation", history: "latest", fork: "current", initial: () => ({ byRequest: {} }) });
|
|
793
840
|
// A fork starts with no sessions: it never shares a live browser.
|
|
@@ -815,6 +862,7 @@ export function createBrowserExtension(options) {
|
|
|
815
862
|
leaving.get(record.tag)?.();
|
|
816
863
|
leaving.delete(record.tag);
|
|
817
864
|
owned.delete(record.tag);
|
|
865
|
+
c.held.dropCapture(record.tag);
|
|
818
866
|
}
|
|
819
867
|
return emit(readers, cid, label, record, change);
|
|
820
868
|
},
|
|
@@ -822,7 +870,7 @@ export function createBrowserExtension(options) {
|
|
|
822
870
|
handedBack: (tag, fence) => c.fences.set(tag, { fence, failure: HANDED_BACK }),
|
|
823
871
|
});
|
|
824
872
|
const c = {
|
|
825
|
-
...readers, name, Sessions, Children, store, meter, held: new Attachments(), fences: new Map(), leaving, serial: keyedSerializer(), childTurns: oneAtATime(), guards: new Map(), owned, failed: false, ending: null, opened: null, incarnation: randomUUID(),
|
|
873
|
+
...readers, name, Sessions, Children, store, meter, held: new Attachments(), vault, fences: new Map(), leaving, serial: keyedSerializer(), childTurns: oneAtATime(), guards: new Map(), owned, failed: false, ending: null, opened: null, incarnation: randomUUID(),
|
|
826
874
|
idle: idleTracker({ idleMs: DEFAULT_BROWSER_POLICY.idleReleaseS * 1000, onIdle: (cid, fired, idleMs) => void releaseIdle(c, cid, fired, idleMs).catch(() => undefined) }),
|
|
827
875
|
};
|
|
828
876
|
// 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
|
|
@@ -851,8 +899,8 @@ export function createBrowserExtension(options) {
|
|
|
851
899
|
c.leaving.clear();
|
|
852
900
|
// A session whose driver was let go and not yet replaced still has its observer attached: close both kinds.
|
|
853
901
|
await Promise.all(c.held.tags().map((tag) => c.held.detach(tag)));
|
|
854
|
-
// A store that failed runs no release task again, so what this process still holds is released at the provider
|
|
855
|
-
|
|
902
|
+
// A store that failed runs no release task again, so what this process still holds is released at the provider.
|
|
903
|
+
// Over a healthy store it is kept, for the next run to resume or reconcile.
|
|
856
904
|
if (c.failed || (c.ending?.closing && await settleWithin(c.ending.failed, FAILED_END_MS, false)))
|
|
857
905
|
await releaseDirectly(c, [...c.owned.keys()]);
|
|
858
906
|
c.owned.clear();
|
package/dist/index.d.ts
CHANGED
|
@@ -12,6 +12,7 @@ export * from "./core/guard.js";
|
|
|
12
12
|
export * from "./core/host.js";
|
|
13
13
|
export * from "./core/images.js";
|
|
14
14
|
export * from "./core/lease.js";
|
|
15
|
+
export { isPrivateAddress, pinnedLookup, PUBLIC_MAX_BYTES, publicFetch, readPage, type PublicAnswer, type PublicFetchOptions } from "./core/public-fetch.js";
|
|
15
16
|
export * from "./core/receipts.js";
|
|
16
17
|
export * from "./core/redact.js";
|
|
17
18
|
export * from "./core/sites.js";
|
|
@@ -19,3 +20,4 @@ export { DEFAULT_BROWSER_POLICY } from "./core/session-control.js";
|
|
|
19
20
|
export * from "./core/tools.js";
|
|
20
21
|
export * from "./core/usage.js";
|
|
21
22
|
export * from "./core/web.js";
|
|
23
|
+
export * from "./core/vault.js";
|
package/dist/index.js
CHANGED
|
@@ -13,6 +13,7 @@ export * from "./core/guard.js";
|
|
|
13
13
|
export * from "./core/host.js";
|
|
14
14
|
export * from "./core/images.js";
|
|
15
15
|
export * from "./core/lease.js";
|
|
16
|
+
export { isPrivateAddress, pinnedLookup, PUBLIC_MAX_BYTES, publicFetch, readPage } from "./core/public-fetch.js";
|
|
16
17
|
export * from "./core/receipts.js";
|
|
17
18
|
export * from "./core/redact.js";
|
|
18
19
|
export * from "./core/sites.js";
|
|
@@ -20,3 +21,4 @@ export { DEFAULT_BROWSER_POLICY } from "./core/session-control.js";
|
|
|
20
21
|
export * from "./core/tools.js";
|
|
21
22
|
export * from "./core/usage.js";
|
|
22
23
|
export * from "./core/web.js";
|
|
24
|
+
export * from "./core/vault.js";
|
|
@@ -2,7 +2,7 @@ import type { BrowserProvider, Geo, PriceTable, SessionSpec } from "../core/host
|
|
|
2
2
|
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
|
-
export { fileProfileStore, type ProfileStore } from "./profiles.js";
|
|
5
|
+
export { fileProfileStore, memoryProfileStore, type ProfileStore } from "./profiles.js";
|
|
6
6
|
export declare const SEARCH_QUERY_MAX = 200;
|
|
7
7
|
export declare const SEARCH_RESULTS_MAX = 25;
|
|
8
8
|
export type BrowserbaseSdk = {
|
|
@@ -8,7 +8,7 @@ import { directFetch } from "./http.js";
|
|
|
8
8
|
import { claimWriter, fileProfileStore, freeWriter, isWriter, noteWriter } from "./profiles.js";
|
|
9
9
|
import { accountKey, assertTag, browserbaseHoldings, defaultSleep, DEFAULT_CONFIRM, extensionArchive, nonEmpty, releaseAndConfirm, tagValue, untilAborted, uploadOnce } from "./shared.js";
|
|
10
10
|
export { rewriteConnectUrl, browserbaseNoProxyHosts, applyBrowserbaseNoProxy } from "./browserbase-net.js";
|
|
11
|
-
export { fileProfileStore } from "./profiles.js";
|
|
11
|
+
export { fileProfileStore, memoryProfileStore } from "./profiles.js";
|
|
12
12
|
export const SEARCH_QUERY_MAX = 200;
|
|
13
13
|
export const SEARCH_RESULTS_MAX = 25;
|
|
14
14
|
/** Into `downloadPath` (default `downloads`, Browserbase's synced-downloads rule); the socket stays open. */
|
|
@@ -76,6 +76,8 @@ export function browserbaseProvider(options = {}) {
|
|
|
76
76
|
const confirm = options.confirm ?? DEFAULT_CONFIRM;
|
|
77
77
|
const prices = resolvePrices(options.prices);
|
|
78
78
|
const profiles = options.profiles ?? fileProfileStore();
|
|
79
|
+
/** The context each live session of this provider runs on, by tag: what a session vault may keep. */
|
|
80
|
+
const contexts = new Map();
|
|
79
81
|
let sdk = null;
|
|
80
82
|
const client = () => (sdk ??= options.client ? Promise.resolve(options.client) : (async () => {
|
|
81
83
|
applyBrowserbaseNoProxy(env);
|
|
@@ -129,13 +131,20 @@ export function browserbaseProvider(options = {}) {
|
|
|
129
131
|
return {
|
|
130
132
|
name: "browserbase",
|
|
131
133
|
caps: CAPS,
|
|
134
|
+
vault: { kind: "context", provider: "browserbase", contextIdsInClear: profiles.clear === true, contextOf: (ref) => contexts.get(ref.tag) ?? null },
|
|
132
135
|
async create(spec, signal) {
|
|
133
136
|
const projectId = nonEmpty(env.BROWSERBASE_PROJECT_ID);
|
|
134
137
|
if (spec.profile?.save)
|
|
135
138
|
await claimWriter(held(`profile:${spec.profile.name}`), spec.profile.name, spec.tag, `${spec.metadata.run}|${spec.metadata.label}`, signal);
|
|
139
|
+
// A context given by id (a vault's kept one) is written back at the end like a profile's: one session at a time saves to it, and the next waits for the write. The id is a capability, so the refusal names no id.
|
|
140
|
+
else if (!spec.profile && spec.contextId)
|
|
141
|
+
await claimWriter(held(`context:${spec.contextId}`), "the kept context", spec.tag, `${spec.metadata.run}|${spec.metadata.label}`, signal);
|
|
136
142
|
let body;
|
|
137
143
|
try {
|
|
138
144
|
const context = spec.profile ? { id: await contextFor(spec.profile.name, projectId, signal), persist: spec.profile.save } : undefined;
|
|
145
|
+
const usedContext = context?.id ?? spec.contextId;
|
|
146
|
+
if (usedContext)
|
|
147
|
+
contexts.set(spec.tag, usedContext);
|
|
139
148
|
// Behind the credential proxy the project is inferred from the injected key and must never be named; a direct key
|
|
140
149
|
// must name it.
|
|
141
150
|
body = sessionCreateBody(spec, { extensionId: await extension(), ...(projectId && !baseUrl && !connectBase ? { projectId } : {}), ...(context ? { context } : {}) });
|
|
@@ -198,6 +207,7 @@ export function browserbaseProvider(options = {}) {
|
|
|
198
207
|
return { sdkCdpUrl: url, ...(connectBase ? { dial: { url: dial } } : {}) };
|
|
199
208
|
},
|
|
200
209
|
async release(ref, signal) {
|
|
210
|
+
contexts.delete(ref.tag);
|
|
201
211
|
await opening.get(held(ref.id));
|
|
202
212
|
endSetting(held(ref.id));
|
|
203
213
|
await releaseAndConfirm({
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { type CapturedState } from "../core/vault.js";
|
|
2
|
+
export interface CdpLink {
|
|
3
|
+
send(method: string, params?: object, sessionId?: string): Promise<any>;
|
|
4
|
+
on(listener: (event: {
|
|
5
|
+
method?: string;
|
|
6
|
+
params?: any;
|
|
7
|
+
sessionId?: string;
|
|
8
|
+
}) => void): () => void;
|
|
9
|
+
close(): void;
|
|
10
|
+
}
|
|
11
|
+
/** One websocket to the browser (its `sdkCdpUrl`). */
|
|
12
|
+
export declare function connectCdp(url: string, timeoutMs?: number): Promise<CdpLink>;
|
|
13
|
+
/** The allowed origins' cookies and local storage, now. The cookies filtered to the origins before they leave this function. */
|
|
14
|
+
export declare function captureCdpState(link: CdpLink, origins: readonly string[], now?: Date): Promise<Extract<CapturedState, {
|
|
15
|
+
kind: "cdp";
|
|
16
|
+
}>>;
|
|
17
|
+
export type RestoreCounts = {
|
|
18
|
+
cookies: number;
|
|
19
|
+
origins: number;
|
|
20
|
+
droppedExpired: number;
|
|
21
|
+
droppedAged: number;
|
|
22
|
+
droppedOutside: number;
|
|
23
|
+
};
|
|
24
|
+
/** Puts a captured state into a browser that has opened no page yet: cookies first (browser level), then each origin's local storage. Only what
|
|
25
|
+
* the requested origins allow is put back, and a cookie is dropped when it expired, or is a session cookie older than the age cap. Returns counts only. */
|
|
26
|
+
export declare function restoreCdpState(link: CdpLink, state: Extract<CapturedState, {
|
|
27
|
+
kind: "cdp";
|
|
28
|
+
}>, origins: readonly string[], now?: Date, maxSessionCookieAgeMs?: number): Promise<RestoreCounts>;
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
// Capture and restore of a local Chrome's signed-in state over the browser's own DevTools websocket, from the harness side: never through the
|
|
2
|
+
// page facade, never reachable by a model. What is captured is what the host's allowed origins would be sent: the cookies by domain, and
|
|
3
|
+
// each origin's localStorage. It stays in memory and goes to the host's vault port; nothing here logs or returns a value.
|
|
4
|
+
// Local storage needs a frame on its origin: a short-lived target is made at the origin and every request it makes is answered locally
|
|
5
|
+
// (Fetch.fulfillRequest with an empty document), so nothing goes to the network and no script of the site runs.
|
|
6
|
+
import { clampSessionCookieAgeMs, cookieKept, vaultOrigins } from "../core/vault.js";
|
|
7
|
+
/** One websocket to the browser (its `sdkCdpUrl`). */
|
|
8
|
+
export async function connectCdp(url, timeoutMs = 10_000) {
|
|
9
|
+
const socket = new WebSocket(url);
|
|
10
|
+
// A socket nobody receives is closed: a handshake that finishes after the deadline, or a setup that fails, leaves no connection open.
|
|
11
|
+
try {
|
|
12
|
+
await new Promise((resolve, reject) => {
|
|
13
|
+
const timer = setTimeout(() => reject(new Error("the browser did not open its DevTools socket")), timeoutMs);
|
|
14
|
+
socket.onopen = () => { clearTimeout(timer); resolve(); };
|
|
15
|
+
socket.onerror = () => { clearTimeout(timer); reject(new Error("the browser's DevTools socket failed")); };
|
|
16
|
+
});
|
|
17
|
+
}
|
|
18
|
+
catch (error) {
|
|
19
|
+
try {
|
|
20
|
+
socket.close();
|
|
21
|
+
}
|
|
22
|
+
catch { /* already closed */ }
|
|
23
|
+
throw error;
|
|
24
|
+
}
|
|
25
|
+
let next = 0;
|
|
26
|
+
const waiting = new Map();
|
|
27
|
+
const listeners = new Set();
|
|
28
|
+
socket.onmessage = (message) => {
|
|
29
|
+
let data;
|
|
30
|
+
try {
|
|
31
|
+
data = JSON.parse(String(message.data));
|
|
32
|
+
}
|
|
33
|
+
catch {
|
|
34
|
+
return;
|
|
35
|
+
}
|
|
36
|
+
if (data.id !== undefined && waiting.has(data.id)) {
|
|
37
|
+
const wait = waiting.get(data.id);
|
|
38
|
+
waiting.delete(data.id);
|
|
39
|
+
if (data.error)
|
|
40
|
+
wait.reject(new Error(String(data.error.message ?? "refused")));
|
|
41
|
+
else
|
|
42
|
+
wait.resolve(data.result);
|
|
43
|
+
}
|
|
44
|
+
else
|
|
45
|
+
for (const listener of listeners)
|
|
46
|
+
listener(data);
|
|
47
|
+
};
|
|
48
|
+
socket.onclose = () => { for (const wait of waiting.values())
|
|
49
|
+
wait.reject(new Error("the DevTools socket closed")); waiting.clear(); };
|
|
50
|
+
return {
|
|
51
|
+
send: (method, params = {}, sessionId) => new Promise((resolve, reject) => {
|
|
52
|
+
const id = ++next;
|
|
53
|
+
const timer = setTimeout(() => { waiting.delete(id); reject(new Error(`the browser did not answer ${method}`)); }, 15_000);
|
|
54
|
+
waiting.set(id, { resolve: (v) => { clearTimeout(timer); resolve(v); }, reject: (e) => { clearTimeout(timer); reject(e); } });
|
|
55
|
+
socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
|
|
56
|
+
}),
|
|
57
|
+
on: (listener) => { listeners.add(listener); return () => listeners.delete(listener); },
|
|
58
|
+
close: () => socket.close(),
|
|
59
|
+
};
|
|
60
|
+
}
|
|
61
|
+
const EMPTY_DOCUMENT = btoa("<!doctype html><title></title>");
|
|
62
|
+
const PATH = "/__pi-browser-vault__";
|
|
63
|
+
/** Runs `use` with a session on a page at `origin` whose every request to that origin was answered locally. */
|
|
64
|
+
async function atOrigin(link, origin, use) {
|
|
65
|
+
const { targetId } = await link.send("Target.createTarget", { url: "about:blank" });
|
|
66
|
+
try {
|
|
67
|
+
const { sessionId } = await link.send("Target.attachToTarget", { targetId, flatten: true });
|
|
68
|
+
const send = (method, params) => link.send(method, params, sessionId);
|
|
69
|
+
const stop = link.on((event) => {
|
|
70
|
+
if (event.sessionId === sessionId && event.method === "Fetch.requestPaused") {
|
|
71
|
+
void send("Fetch.fulfillRequest", { requestId: event.params.requestId, responseCode: 200, responseHeaders: [{ name: "content-type", value: "text/html" }], body: EMPTY_DOCUMENT }).catch(() => undefined);
|
|
72
|
+
}
|
|
73
|
+
});
|
|
74
|
+
try {
|
|
75
|
+
await send("Page.enable");
|
|
76
|
+
await send("Fetch.enable", { patterns: [{ urlPattern: `${origin}/*` }] });
|
|
77
|
+
const loaded = new Promise((resolve) => { const off = link.on((event) => { if (event.sessionId === sessionId && event.method === "Page.loadEventFired") {
|
|
78
|
+
off();
|
|
79
|
+
resolve();
|
|
80
|
+
} }); setTimeout(() => { off(); resolve(); }, 8000); });
|
|
81
|
+
await send("Page.navigate", { url: `${origin}${PATH}` });
|
|
82
|
+
await loaded;
|
|
83
|
+
await send("DOMStorage.enable");
|
|
84
|
+
return await use(send);
|
|
85
|
+
}
|
|
86
|
+
finally {
|
|
87
|
+
stop();
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
finally {
|
|
91
|
+
await link.send("Target.closeTarget", { targetId }).catch(() => undefined);
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
const toVaultCookie = (cookie) => ({
|
|
95
|
+
name: cookie.name, value: cookie.value, domain: cookie.domain, path: cookie.path ?? "/",
|
|
96
|
+
...(cookie.session || !(cookie.expires > 0) ? {} : { expires: cookie.expires }),
|
|
97
|
+
httpOnly: cookie.httpOnly === true, secure: cookie.secure === true,
|
|
98
|
+
...(cookie.sameSite === "Strict" || cookie.sameSite === "Lax" || cookie.sameSite === "None" ? { sameSite: cookie.sameSite } : {}),
|
|
99
|
+
});
|
|
100
|
+
/** The allowed origins' cookies and local storage, now. The cookies filtered to the origins before they leave this function. */
|
|
101
|
+
export async function captureCdpState(link, origins, now = new Date()) {
|
|
102
|
+
const allowed = vaultOrigins(origins);
|
|
103
|
+
const { cookies } = await link.send("Storage.getCookies", {});
|
|
104
|
+
const kept = cookies.filter((cookie) => cookieKept(cookie, allowed)).map(toVaultCookie);
|
|
105
|
+
const localStorage = {};
|
|
106
|
+
for (const origin of allowed) {
|
|
107
|
+
const entries = await atOrigin(link, origin, async (send) => (await send("DOMStorage.getDOMStorageItems", { storageId: { securityOrigin: origin, isLocalStorage: true } })).entries);
|
|
108
|
+
if (entries.length)
|
|
109
|
+
localStorage[origin] = Object.fromEntries(entries);
|
|
110
|
+
}
|
|
111
|
+
return { kind: "cdp", capturedAt: now.toISOString(), cookies: kept, localStorage };
|
|
112
|
+
}
|
|
113
|
+
/** Puts a captured state into a browser that has opened no page yet: cookies first (browser level), then each origin's local storage. Only what
|
|
114
|
+
* the requested origins allow is put back, and a cookie is dropped when it expired, or is a session cookie older than the age cap. Returns counts only. */
|
|
115
|
+
export async function restoreCdpState(link, state, origins, now = new Date(), maxSessionCookieAgeMs) {
|
|
116
|
+
const allowed = vaultOrigins(origins);
|
|
117
|
+
const cap = clampSessionCookieAgeMs(maxSessionCookieAgeMs);
|
|
118
|
+
const counts = { cookies: 0, origins: 0, droppedExpired: 0, droppedAged: 0, droppedOutside: 0 };
|
|
119
|
+
const capturedAt = Date.parse(state.capturedAt);
|
|
120
|
+
const params = [];
|
|
121
|
+
for (const cookie of state.cookies) {
|
|
122
|
+
if (!cookieKept(cookie, allowed)) {
|
|
123
|
+
counts.droppedOutside += 1;
|
|
124
|
+
continue;
|
|
125
|
+
}
|
|
126
|
+
if (cookie.expires !== undefined) {
|
|
127
|
+
if (cookie.expires * 1000 <= now.getTime()) {
|
|
128
|
+
counts.droppedExpired += 1;
|
|
129
|
+
continue;
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
else if (!Number.isFinite(capturedAt) || now.getTime() - capturedAt > cap) {
|
|
133
|
+
counts.droppedAged += 1;
|
|
134
|
+
continue;
|
|
135
|
+
}
|
|
136
|
+
params.push({ name: cookie.name, value: cookie.value, domain: cookie.domain, path: cookie.path, secure: cookie.secure, httpOnly: cookie.httpOnly, ...(cookie.sameSite ? { sameSite: cookie.sameSite } : {}), ...(cookie.expires !== undefined ? { expires: cookie.expires } : {}) });
|
|
137
|
+
}
|
|
138
|
+
if (params.length)
|
|
139
|
+
await link.send("Storage.setCookies", { cookies: params });
|
|
140
|
+
counts.cookies = params.length;
|
|
141
|
+
for (const origin of allowed) {
|
|
142
|
+
const items = state.localStorage[origin];
|
|
143
|
+
if (!items || !Object.keys(items).length)
|
|
144
|
+
continue;
|
|
145
|
+
await atOrigin(link, origin, async (send) => { for (const [key, value] of Object.entries(items))
|
|
146
|
+
await send("DOMStorage.setDOMStorageItem", { storageId: { securityOrigin: origin, isLocalStorage: true }, key, value }); });
|
|
147
|
+
counts.origins += 1;
|
|
148
|
+
}
|
|
149
|
+
for (const origin of Object.keys(state.localStorage))
|
|
150
|
+
if (!allowed.includes(origin))
|
|
151
|
+
counts.droppedOutside += 1;
|
|
152
|
+
return counts;
|
|
153
|
+
}
|
package/dist/providers/cdp.d.ts
CHANGED
|
@@ -5,6 +5,8 @@ export type CdpOptions =
|
|
|
5
5
|
{
|
|
6
6
|
endpoint: string;
|
|
7
7
|
extensionId?: string;
|
|
8
|
+
/** The host asserts this endpoint is the run's OWN browser (the launcher that owns its process and its stop started it for this run alone), not one other runs or people share. Only then is a session of it offered to a session vault. Never set it for a shared browser. */
|
|
9
|
+
ownBrowser?: boolean;
|
|
8
10
|
}
|
|
9
11
|
/** Start Chrome under `profileRoot/<tag>` on a loopback port Chrome picks; release kills that process by exact pid. */
|
|
10
12
|
| {
|
|
@@ -16,6 +18,10 @@ export type CdpOptions =
|
|
|
16
18
|
/** Chrome's own sandbox, on unless `false`; absent, `PI_BROWSER_NO_SANDBOX=1` turns it off. Turn it off only where
|
|
17
19
|
* Chrome cannot start its sandbox (root, a container, confined user namespaces), never because a run is in CI. */
|
|
18
20
|
sandbox?: boolean;
|
|
21
|
+
/** The extension this Chrome is given is a copy whose pages and worker may connect to nothing but the browser's own DevTools
|
|
22
|
+
* socket (default true). `false` gives Stagehand's own directory, unconfined: for tests of the layer beneath. Without a private
|
|
23
|
+
* TMPDIR for the lease (Windows, a long temp path) the extension is Stagehand's own either way. */
|
|
24
|
+
confineExtension?: boolean;
|
|
19
25
|
};
|
|
20
26
|
};
|
|
21
27
|
/** The browser is gone and directories it used are not: a profile left behind holds the session's cookies, so a release that cannot remove
|