@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/CHANGELOG.md +5 -0
- package/README.md +2 -0
- package/dist/coding-agent.d.ts +6 -0
- package/dist/coding-agent.js +28 -13
- package/dist/core/custody.d.ts +7 -0
- package/dist/core/custody.js +16 -3
- package/dist/core/downloads.d.ts +1 -0
- package/dist/core/downloads.js +2 -2
- package/dist/core/host.d.ts +9 -0
- package/dist/core/sites.js +2 -1
- package/dist/driver/extension-worker.d.ts +2 -1
- package/dist/driver/extension-worker.js +47 -20
- package/dist/driver/new-document.d.ts +26 -0
- package/dist/driver/new-document.js +40 -0
- package/dist/driver/stagehand.js +8 -10
- package/dist/durable.d.ts +7 -0
- package/dist/durable.js +60 -20
- package/dist/providers/browserbase.d.ts +17 -0
- package/dist/providers/browserbase.js +49 -8
- package/dist/providers/cdp.d.ts +7 -0
- package/dist/providers/cdp.js +189 -55
- package/dist/providers/kernel.js +40 -6
- package/dist/providers/profiles.d.ts +19 -0
- package/dist/providers/profiles.js +124 -0
- package/dist/providers/shared.d.ts +1 -1
- package/dist/recorder/track.js +23 -2
- package/dist/testing/backend.js +2 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
## Unreleased
|
|
4
4
|
|
|
5
|
+
## 0.1.0-beta.15 (2026-10-16)
|
|
6
|
+
|
|
7
|
+
- `@parcha/pi-browser`: a session can ask for a named saved profile. `SessionSpec` and `BrowserPolicy` take `profile: { name, save }`, `ProviderCaps` gains `profiles`, and the session record names the profile (the name only; older records read as none). The local Chrome (`cdp`) keeps a named profile in its own directory, and a session can work from a copy that is never saved; Kernel keeps one through its own profiles (created on first use, one saver per profile); Browserbase keeps one as a context made on first use and remembered by name. A provider that cannot keep a profile, a profile beside a context id and a bad name are refused with the typed envelope before any session or record is made. A host can pass an optional `crossing` callback that is called at the two page-action moments a kill sweep needs (after one page action's answer is committed and before the next is dispatched; after a page action's driver call returned and before its answer is committed). `use_website` calls in one turn now run at once, each child in its own browser. `browser_release` on a session that already ended, or is ending, answers `already_released: { reason, at }` and one sentence beside `released`, which keeps its meaning.
|
|
8
|
+
- `@parcha/pi-browser`: a `snapshot` or `browser_read` that lands in a document a navigation replaced waits for the new one and reads once more, instead of failing with Chrome's "Cannot find context with specified id". The held-runtime reset (Stagehand's extension) fails on a target list the browser never gives, instead of reading it as "nothing held", and closes its last wake page before the socket goes, so a runtime still held no longer refuses the next attach. `exportFrameTracks` bounds each blob read by the session's deadline and the abort signal.
|
|
9
|
+
|
|
5
10
|
## 0.1.0-beta.14 (2026-10-16)
|
|
6
11
|
|
|
7
12
|
- Accept pi 1.3: the `@earendil-works/pi-durable` and `@earendil-works/chord` peer ranges now end below 1.4, with the floors unchanged (1.0.4, and 1.1.0 for `@parcha/pi-browser`). pi 1.3.0 pins its own packages to exact versions, so an install is all 1.2 or all 1.3; CI runs every package's whole suite on a 1.3.0 family as well as on 1.2.0.
|
package/README.md
CHANGED
|
@@ -28,6 +28,8 @@ Stagehand, undici, zod and the two HTML packages are dependencies. Four optional
|
|
|
28
28
|
|
|
29
29
|
The pi peers are `@earendil-works/pi-durable` and `chord` `>=1.1.0 <1.4.0`, and `@earendil-works/pi-coding-agent` at any version, as pi's package guidance asks of the packages it supplies. The suite passes on pi 1.1, 1.2 and 1.3, and the coding-agent entry's tests also pass on a pi 1.0.4 family.
|
|
30
30
|
|
|
31
|
+
pi 1.0.4 or 1.1.x users: pin `@earendil-works/pi-codemode` to the same version as `@earendil-works/pi-coding-agent` (`@1.0.4`, or `@1.1.0`), because pi-codemode 1.2.0 removed an export those versions import, or use pi 1.2.
|
|
32
|
+
|
|
31
33
|
## Quick start
|
|
32
34
|
|
|
33
35
|
A local Chrome, one page, one snapshot. It needs Chrome or Chromium; `CHROME_PATH` names it.
|
package/dist/coding-agent.d.ts
CHANGED
|
@@ -32,6 +32,8 @@ export declare class LocalCustody implements CustodyPort<PageDriver> {
|
|
|
32
32
|
private live;
|
|
33
33
|
/** Browsers that are gone whose directories are not: each is released again as cleanup, never kept as the live session. */
|
|
34
34
|
private leftovers;
|
|
35
|
+
/** The last session this custody released, so a release asked after it can say how and when it ended. */
|
|
36
|
+
private lastReleased;
|
|
35
37
|
private seq;
|
|
36
38
|
private notice;
|
|
37
39
|
private readonly queue;
|
|
@@ -62,6 +64,10 @@ export declare class LocalCustody implements CustodyPort<PageDriver> {
|
|
|
62
64
|
release(): Promise<{
|
|
63
65
|
released: boolean;
|
|
64
66
|
sessionId: string | null;
|
|
67
|
+
ended?: {
|
|
68
|
+
reason: ReleaseReason;
|
|
69
|
+
at: string | null;
|
|
70
|
+
};
|
|
65
71
|
}>;
|
|
66
72
|
/** Releases without failing the caller; idempotent. */
|
|
67
73
|
close(reason: ReleaseReason): Promise<void>;
|
package/dist/coding-agent.js
CHANGED
|
@@ -4,7 +4,7 @@ import { mkdtemp, rm } from "node:fs/promises";
|
|
|
4
4
|
import os from "node:os";
|
|
5
5
|
import path from "node:path";
|
|
6
6
|
import { BROWSER_TOOLS, WEB_TOOLS, browserSection } from "./core/contract.js";
|
|
7
|
-
import { BrowserFailureError, closeDriver, custodyTools, newSessionRecord, notices, sessionSpec, } from "./core/custody.js";
|
|
7
|
+
import { BrowserFailureError, closeDriver, custodyTools, newSessionRecord, notices, profileRefusal, sessionSpec, } from "./core/custody.js";
|
|
8
8
|
import { browserFailure, classifyBrowserError } from "./core/failures.js";
|
|
9
9
|
import { leaseTag } from "./core/lease.js";
|
|
10
10
|
import { createRedactor, redactDeep, scrubPageUrl } from "./core/redact.js";
|
|
@@ -26,6 +26,8 @@ export class LocalCustody {
|
|
|
26
26
|
live = null;
|
|
27
27
|
/** Browsers that are gone whose directories are not: each is released again as cleanup, never kept as the live session. */
|
|
28
28
|
leftovers = [];
|
|
29
|
+
/** The last session this custody released, so a release asked after it can say how and when it ended. */
|
|
30
|
+
lastReleased = null;
|
|
29
31
|
seq = 0;
|
|
30
32
|
notice = null;
|
|
31
33
|
queue = keyedSerializer();
|
|
@@ -41,7 +43,7 @@ export class LocalCustody {
|
|
|
41
43
|
return this.queue.run(this.d.config.label, run);
|
|
42
44
|
}
|
|
43
45
|
save(record) {
|
|
44
|
-
this.d.keep(SESSION_ENTRY, { tag: record.tag, resourceId: record.resourceId, state: record.state, reason: record.releaseReason });
|
|
46
|
+
this.d.keep(SESSION_ENTRY, { tag: record.tag, resourceId: record.resourceId, state: record.state, reason: record.releaseReason, ...(record.endedAt ? { endedAt: record.endedAt } : {}) });
|
|
45
47
|
}
|
|
46
48
|
failure(error, signal) {
|
|
47
49
|
return error instanceof BrowserFailureError ? error : new BrowserFailureError(classifyBrowserError(error, false, { aborted: signal?.aborted === true }));
|
|
@@ -84,6 +86,9 @@ export class LocalCustody {
|
|
|
84
86
|
const provider = await this.d.provider();
|
|
85
87
|
const tag = leaseTag("pib", this.d.config.run, randomUUID().slice(0, 8), ++this.seq);
|
|
86
88
|
const spec = sessionSpec(this.d.config, tag, overrides);
|
|
89
|
+
const unsupported = profileRefusal(spec, provider.caps);
|
|
90
|
+
if (unsupported)
|
|
91
|
+
throw new BrowserFailureError(unsupported);
|
|
87
92
|
const record = newSessionRecord({ plane: "browser", tag, provider: provider.name, spec, at: now(), honours: provider.caps.settings });
|
|
88
93
|
this.save(record);
|
|
89
94
|
const signal = AbortSignal.any([this.d.signal, AbortSignal.timeout(CREATE_DEADLINE_MS)]);
|
|
@@ -106,7 +111,8 @@ export class LocalCustody {
|
|
|
106
111
|
if (!(await provider.release(ref).then(() => true, () => false)))
|
|
107
112
|
released = false;
|
|
108
113
|
if (released) {
|
|
109
|
-
Object.assign(record, { state: "released", releaseReason: "create_failed" });
|
|
114
|
+
Object.assign(record, { state: "released", releaseReason: "create_failed", endedAt: now() });
|
|
115
|
+
this.lastReleased = record;
|
|
110
116
|
this.save(record);
|
|
111
117
|
}
|
|
112
118
|
throw this.failure(error, signal);
|
|
@@ -131,13 +137,15 @@ export class LocalCustody {
|
|
|
131
137
|
this.live = null;
|
|
132
138
|
live.driver = null;
|
|
133
139
|
Object.assign(live.record, { state: "releasing", releaseReason: reason });
|
|
140
|
+
this.lastReleased = live.record;
|
|
134
141
|
this.save(live.record);
|
|
135
142
|
this.leftovers.push(live);
|
|
136
143
|
throw this.failure(error);
|
|
137
144
|
}
|
|
138
145
|
if (this.live === live)
|
|
139
146
|
this.live = null;
|
|
140
|
-
Object.assign(live.record, { state: "released", releaseReason: reason });
|
|
147
|
+
Object.assign(live.record, { state: "released", releaseReason: reason, endedAt: now() });
|
|
148
|
+
this.lastReleased = live.record;
|
|
141
149
|
this.save(live.record);
|
|
142
150
|
}
|
|
143
151
|
/** Releases again each browser that is gone and whose directory was left; one that still cannot be removed stays for the next time, and the
|
|
@@ -154,7 +162,7 @@ export class LocalCustody {
|
|
|
154
162
|
stillLeft = error;
|
|
155
163
|
continue;
|
|
156
164
|
}
|
|
157
|
-
Object.assign(live.record, { state: "released" });
|
|
165
|
+
Object.assign(live.record, { state: "released", endedAt: now() });
|
|
158
166
|
this.save(live.record);
|
|
159
167
|
}
|
|
160
168
|
return stillLeft;
|
|
@@ -185,14 +193,15 @@ export class LocalCustody {
|
|
|
185
193
|
release() {
|
|
186
194
|
return this.serial(async () => {
|
|
187
195
|
const live = this.live;
|
|
188
|
-
if (live)
|
|
196
|
+
if (live) {
|
|
189
197
|
await this.finish(live, "tool");
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
198
|
+
return { released: true, sessionId: live.ref.id };
|
|
199
|
+
}
|
|
200
|
+
const stillLeft = await this.sweepLeftovers(); // no browser, but a directory an earlier release left
|
|
201
|
+
if (stillLeft)
|
|
202
|
+
throw this.failure(stillLeft);
|
|
203
|
+
const last = this.lastReleased;
|
|
204
|
+
return last ? { released: false, sessionId: last.resourceId, ended: { reason: last.releaseReason ?? "tool", at: last.endedAt } } : { released: false, sessionId: null };
|
|
196
205
|
});
|
|
197
206
|
}
|
|
198
207
|
/** Releases without failing the caller; idempotent. */
|
|
@@ -342,6 +351,9 @@ export function createBrowserExtension(options = {}) {
|
|
|
342
351
|
let opening = null;
|
|
343
352
|
let webSearchRegistered = false;
|
|
344
353
|
let sitesRegistered = false;
|
|
354
|
+
// Children on one existing browser (--browser-endpoint) would drive the same pages, so there they take turns.
|
|
355
|
+
let turn = Promise.resolve();
|
|
356
|
+
const inTurn = (run) => { const mine = turn.then(run, run); turn = mine.catch(() => undefined); return mine; };
|
|
345
357
|
pi.registerFlag("browser-provider", { type: "string", description: "Browser provider: cdp (a local Chrome, the default), browserbase (needs BROWSERBASE_API_KEY) or kernel (needs KERNEL_API_KEY)" });
|
|
346
358
|
pi.registerFlag("browser-endpoint", { type: "string", description: "Attach to a Chrome DevTools endpoint (http://host:port or ws://...) instead of starting Chrome" });
|
|
347
359
|
pi.registerFlag("browser-chrome", { type: "string", description: "Path to the Chrome or Chromium to start" });
|
|
@@ -432,7 +444,10 @@ export function createBrowserExtension(options = {}) {
|
|
|
432
444
|
annotations: { readOnlyHint: false, openWorldHint: true },
|
|
433
445
|
async execute(_callId, params, signal, _onUpdate, ctx) {
|
|
434
446
|
const rt = await runtimeOf(ctx);
|
|
435
|
-
const out = await useWebsite(params, port, listing, { signal: signal ?? new AbortController().signal, runChild: (task, childSignal) =>
|
|
447
|
+
const out = await useWebsite(params, port, listing, { signal: signal ?? new AbortController().signal, runChild: (task, childSignal) => {
|
|
448
|
+
const run = () => childSession(ctx, task.prompt, childSignal);
|
|
449
|
+
return flagOf(pi, "browser-endpoint", env.PI_BROWSER_ENDPOINT) ? inTurn(run) : run();
|
|
450
|
+
} });
|
|
436
451
|
return { content: out.content.map((item) => item.type === "text" ? { ...item, text: rt.redact(item.text) } : item), details: undefined, ...(out.isError ? { isError: true } : {}) };
|
|
437
452
|
},
|
|
438
453
|
});
|
package/dist/core/custody.d.ts
CHANGED
|
@@ -38,9 +38,14 @@ export interface CustodyPort<D extends BrowserDriver = BrowserDriver> {
|
|
|
38
38
|
/** A rerun finds the session it launched. */
|
|
39
39
|
relaunch(overrides: Overrides): Promise<AttachedSession<D>>;
|
|
40
40
|
/** No session, or one already released, is not an error. */
|
|
41
|
+
/** `ended`: the session was released, or is being released, before this call: by what and when (null while in flight). */
|
|
41
42
|
release(): Promise<{
|
|
42
43
|
released: boolean;
|
|
43
44
|
sessionId: string | null;
|
|
45
|
+
ended?: {
|
|
46
|
+
reason: ReleaseReason;
|
|
47
|
+
at: string | null;
|
|
48
|
+
};
|
|
44
49
|
}>;
|
|
45
50
|
/** Committed before the `run` is dispatched. */
|
|
46
51
|
dispatching(effect: {
|
|
@@ -102,7 +107,9 @@ export declare function moveRecord(record: SessionRecord, next: {
|
|
|
102
107
|
reason?: ReleaseReason;
|
|
103
108
|
at: string;
|
|
104
109
|
}): void;
|
|
110
|
+
export declare const PROFILE_NAME: RegExp;
|
|
105
111
|
export declare function sessionSpec(config: BrowserConfig, tag: string, overrides?: Overrides): SessionSpec;
|
|
112
|
+
export declare function profileRefusal(spec: SessionSpec, caps: ProviderCaps): BrowserFailure | null;
|
|
106
113
|
/** With proxies off a geolocation is refused up front: the session would browse from the provider's default place,
|
|
107
114
|
* silently. */
|
|
108
115
|
export declare function relaunchRefusal(policy: BrowserConfig["policy"], overrides: Overrides): BrowserFailure | null;
|
package/dist/core/custody.js
CHANGED
|
@@ -38,7 +38,7 @@ export function newSessionRecord(input) {
|
|
|
38
38
|
settings: {
|
|
39
39
|
proxies, verified: spec.verified && honours.verified !== false,
|
|
40
40
|
geolocation: proxies && honours.geolocation !== false && typeof spec.proxies === "object" ? spec.proxies.geolocation : null,
|
|
41
|
-
region: honours.region === false ? null : spec.region ?? null, contextId: honours.context === false ? null : spec.contextId ?? null,
|
|
41
|
+
region: honours.region === false ? null : spec.region ?? null, contextId: honours.context === false ? null : spec.contextId ?? null, profile: spec.profile?.name ?? null,
|
|
42
42
|
},
|
|
43
43
|
navigation: [], lastUrl: null, pendingEffect: null, spent: startSpent(input.at),
|
|
44
44
|
};
|
|
@@ -56,8 +56,14 @@ export function moveRecord(record, next) {
|
|
|
56
56
|
if (next.state === "released" || next.state === "lost")
|
|
57
57
|
record.endedAt = next.at;
|
|
58
58
|
}
|
|
59
|
+
export const PROFILE_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
|
|
60
|
+
const refused = (message) => ({ ok: false, code: "refused", retryable: false, effect: "none", message });
|
|
59
61
|
export function sessionSpec(config, tag, overrides = {}) {
|
|
60
62
|
const { policy } = config;
|
|
63
|
+
if (policy.profile && !PROFILE_NAME.test(policy.profile.name))
|
|
64
|
+
throw new BrowserFailureError(refused("browser profile: a profile name is 1 to 64 characters of letters, digits, dot, underscore and dash, starting with a letter or digit. No session was started."));
|
|
65
|
+
if (policy.profile && policy.contextId)
|
|
66
|
+
throw new BrowserFailureError(refused("browser profile: a saved profile and a context id are two ways to ask for the same saved state; set one. No session was started."));
|
|
61
67
|
const geolocation = overrides.geolocation === undefined ? policy.geolocation : overrides.geolocation;
|
|
62
68
|
return {
|
|
63
69
|
tag, maxLifetimeS: policy.sessionTimeoutS, idleTimeoutS: policy.idleReleaseS,
|
|
@@ -66,10 +72,14 @@ export function sessionSpec(config, tag, overrides = {}) {
|
|
|
66
72
|
...(policy.region ? { region: policy.region } : {}),
|
|
67
73
|
viewport: { ...VIEWPORT },
|
|
68
74
|
...(policy.contextId ? { contextId: policy.contextId } : {}),
|
|
75
|
+
...(policy.profile ? { profile: { name: policy.profile.name, save: policy.profile.save } } : {}),
|
|
69
76
|
...(policy.navigation ? { navigation: policy.navigation } : {}),
|
|
70
77
|
metadata: { run: config.run, label: config.label },
|
|
71
78
|
};
|
|
72
79
|
}
|
|
80
|
+
export function profileRefusal(spec, caps) {
|
|
81
|
+
return spec.profile && !caps.profiles ? refused(`browser profile: this browser provider cannot keep a saved sign-in, so profile "${spec.profile.name}" cannot be used. No session was started.`) : null;
|
|
82
|
+
}
|
|
73
83
|
/** With proxies off a geolocation is refused up front: the session would browse from the provider's default place,
|
|
74
84
|
* silently. */
|
|
75
85
|
export function relaunchRefusal(policy, overrides) {
|
|
@@ -103,8 +113,11 @@ const failed = (error) => {
|
|
|
103
113
|
export const custodyTools = {
|
|
104
114
|
async browser_release(_args, port) {
|
|
105
115
|
try {
|
|
106
|
-
const { released, sessionId } = await port.release();
|
|
107
|
-
|
|
116
|
+
const { released, sessionId, ended } = await port.release();
|
|
117
|
+
const note = ended
|
|
118
|
+
? `The session was already ${ended.at ? `released (${ended.reason}, at ${ended.at})` : `being released (${ended.reason})`} before this call; there was nothing more to release.`
|
|
119
|
+
: sessionId === null ? "no open browser session" : null;
|
|
120
|
+
return text({ ok: true, released, session_id: sessionId, ...(ended ? { already_released: ended } : {}), ...(note ? { note } : {}) });
|
|
108
121
|
}
|
|
109
122
|
catch (error) {
|
|
110
123
|
return failed(error);
|
package/dist/core/downloads.d.ts
CHANGED
|
@@ -23,6 +23,7 @@ export type DownloadsResult = {
|
|
|
23
23
|
};
|
|
24
24
|
/** A name that stays inside `downloads/`: the last path segment, no control characters, not hidden, not the manifest. */
|
|
25
25
|
export declare function safeDownloadName(remote: string): string;
|
|
26
|
+
export declare function withLock<T>(file: string, run: () => Promise<T>, what?: string): Promise<T>;
|
|
26
27
|
/** Skips what the workspace already holds; one failing file is skipped with its reason. */
|
|
27
28
|
export declare function fetchDownloads(options: {
|
|
28
29
|
provider: Pick<BrowserProvider, "downloads">;
|
package/dist/core/downloads.js
CHANGED
|
@@ -19,7 +19,7 @@ const sameRemote = (row, session, file) => row.session === session && row.remote
|
|
|
19
19
|
const exists = (file) => stat(file).then((s) => s.isFile(), () => false);
|
|
20
20
|
const hashOf = async (file) => createHash("sha256").update(await readFile(file)).digest("hex");
|
|
21
21
|
const withRow = (rows, row) => [...rows.filter((r) => r.path !== row.path || (r.sha256 === row.sha256 && !(r.session === row.session && r.remote.name === row.remote.name))), row];
|
|
22
|
-
async function withLock(file, run) {
|
|
22
|
+
export async function withLock(file, run, what = "downloads/manifest.json") {
|
|
23
23
|
for (const deadline = Date.now() + 10_000;; await new Promise((r) => setTimeout(r, 25 + Math.random() * 50))) {
|
|
24
24
|
try {
|
|
25
25
|
await (await open(file, "wx")).close();
|
|
@@ -31,7 +31,7 @@ async function withLock(file, run) {
|
|
|
31
31
|
if (Date.now() - (await stat(file).then((s) => s.mtimeMs, () => Date.now())) > 30_000)
|
|
32
32
|
await rm(file, { force: true });
|
|
33
33
|
else if (Date.now() > deadline)
|
|
34
|
-
throw new Error(
|
|
34
|
+
throw new Error(`${what} is locked by another writer`);
|
|
35
35
|
}
|
|
36
36
|
}
|
|
37
37
|
try {
|
package/dist/core/host.d.ts
CHANGED
|
@@ -29,6 +29,11 @@ export type BrowserConfig = {
|
|
|
29
29
|
run: string;
|
|
30
30
|
policy: BrowserPolicy;
|
|
31
31
|
};
|
|
32
|
+
/** A named saved sign-in; `save` keeps the session's changes. One saver per profile within a process; across processes the last to end wins. */
|
|
33
|
+
export type SavedProfile = {
|
|
34
|
+
name: string;
|
|
35
|
+
save: boolean;
|
|
36
|
+
};
|
|
32
37
|
export type BrowserPolicy = {
|
|
33
38
|
proxies: boolean;
|
|
34
39
|
verified: boolean;
|
|
@@ -36,6 +41,7 @@ export type BrowserPolicy = {
|
|
|
36
41
|
geolocation: Geo | null;
|
|
37
42
|
region: string | null;
|
|
38
43
|
contextId: string | null;
|
|
44
|
+
profile?: SavedProfile;
|
|
39
45
|
sessionTimeoutS: number;
|
|
40
46
|
idleReleaseS: number;
|
|
41
47
|
batchTimeoutMs: number;
|
|
@@ -61,6 +67,7 @@ export type SessionSpec = {
|
|
|
61
67
|
height: number;
|
|
62
68
|
};
|
|
63
69
|
contextId?: string;
|
|
70
|
+
profile?: SavedProfile;
|
|
64
71
|
navigation?: {
|
|
65
72
|
allow?: string[];
|
|
66
73
|
block?: string[];
|
|
@@ -82,6 +89,7 @@ export type ProviderCaps = {
|
|
|
82
89
|
maxLifetimeS: number;
|
|
83
90
|
survivesDisconnect: boolean;
|
|
84
91
|
releaseIsAsync: boolean;
|
|
92
|
+
profiles: boolean;
|
|
85
93
|
extension: "uploaded-per-launch" | "preinstalled" | "loaded-locally";
|
|
86
94
|
/** The session settings this provider applies; a setting left out is applied. */
|
|
87
95
|
settings?: Partial<SessionSettingsSupport>;
|
|
@@ -212,6 +220,7 @@ export type SessionRecord = {
|
|
|
212
220
|
geolocation: Geo | null;
|
|
213
221
|
region: string | null;
|
|
214
222
|
contextId: string | null;
|
|
223
|
+
profile: string | null;
|
|
215
224
|
};
|
|
216
225
|
/** Every page the session moved to, in order; the last 500 kept. */
|
|
217
226
|
navigation: Array<{
|
package/dist/core/sites.js
CHANGED
|
@@ -12,6 +12,7 @@ export function useWebsiteContract(sites) {
|
|
|
12
12
|
"Hand a task to an agent that works on one of these websites in its own browser, and get back what it found or did:",
|
|
13
13
|
...sites.map((site) => `- ${site.site}: ${site.title}. ${site.description}`),
|
|
14
14
|
"Give a new request_id (a UUID) for each new task. Calling again with the request_id of a finished task answers its result without running it again; a task that failed runs again, and may repeat what it already did on the site.",
|
|
15
|
+
"Several calls in one turn run at once, each agent in its own browser.",
|
|
15
16
|
].join("\n"),
|
|
16
17
|
parameters: {
|
|
17
18
|
type: "object", additionalProperties: false, required: ["site", "request_id", "instructions"],
|
|
@@ -21,7 +22,7 @@ export function useWebsiteContract(sites) {
|
|
|
21
22
|
instructions: { type: "string", maxLength: MAX_SITE_INSTRUCTIONS, description: "What to do on the website and what to report back." },
|
|
22
23
|
},
|
|
23
24
|
},
|
|
24
|
-
effect: "effect", replay: "safe", executionMode: "
|
|
25
|
+
effect: "effect", replay: "safe", executionMode: "parallel", evidence: "none", listedWhen: "sites",
|
|
25
26
|
};
|
|
26
27
|
}
|
|
27
28
|
/** Only the declared shape crosses back to the model: a port's extra fields, such as capabilities or URLs, are dropped
|
|
@@ -2,5 +2,6 @@ export declare const STAGEHAND_EXTENSION = "Stagehand Runtime";
|
|
|
2
2
|
/** A held extension runtime keeps one Stagehand instance until that instance's close, which a dead process never sent,
|
|
3
3
|
* so a new attach would be refused. The close is sent here through the worker's own RPC, and the worker keeps running:
|
|
4
4
|
* a worker closed under load is sometimes never restarted, and its attach waits out Stagehand's 60 s init deadline.
|
|
5
|
-
* With no worker running nothing is held, and the worker is woken until it is listed.
|
|
5
|
+
* With no worker running nothing is held, and the worker is woken until it is listed. A target list the browser does
|
|
6
|
+
* not give by DISCOVERY_MS is not a list without a worker: the attach fails. */
|
|
6
7
|
export declare function installedExtension(cdpUrl: string, signal?: AbortSignal, known?: string): Promise<string | null>;
|
|
@@ -1,29 +1,41 @@
|
|
|
1
1
|
export const STAGEHAND_EXTENSION = "Stagehand Runtime";
|
|
2
2
|
const DISCOVERY_MS = 10_000;
|
|
3
|
+
/** Kept past the deadline so the last wake page is closed on the same socket. */
|
|
4
|
+
const CLEANUP_MS = 1_000;
|
|
3
5
|
const WAKE_TRIES = 60;
|
|
4
6
|
const CLOSE_REPLY_MS = 3_000;
|
|
5
7
|
const SEND_TO_HOST = "__stagehandSendToHost";
|
|
6
8
|
const RESET_ID = 2_147_000_000;
|
|
9
|
+
/** The browser did not list its targets by the deadline, so a runtime it may hold could not be freed. */
|
|
10
|
+
class TargetsUnlistedError extends Error {
|
|
11
|
+
constructor() { super(`the browser did not list its targets within ${DISCOVERY_MS} ms, so a Stagehand runtime it may hold could not be freed`); }
|
|
12
|
+
}
|
|
7
13
|
/** A held extension runtime keeps one Stagehand instance until that instance's close, which a dead process never sent,
|
|
8
14
|
* so a new attach would be refused. The close is sent here through the worker's own RPC, and the worker keeps running:
|
|
9
15
|
* a worker closed under load is sometimes never restarted, and its attach waits out Stagehand's 60 s init deadline.
|
|
10
|
-
* With no worker running nothing is held, and the worker is woken until it is listed.
|
|
16
|
+
* With no worker running nothing is held, and the worker is woken until it is listed. A target list the browser does
|
|
17
|
+
* not give by DISCOVERY_MS is not a list without a worker: the attach fails. */
|
|
11
18
|
export async function installedExtension(cdpUrl, signal, known) {
|
|
12
19
|
const socket = new WebSocket(cdpUrl);
|
|
13
|
-
const
|
|
20
|
+
const deadline = Date.now() + DISCOVERY_MS;
|
|
21
|
+
const timer = setTimeout(() => socket.close(), DISCOVERY_MS + CLEANUP_MS);
|
|
14
22
|
const stop = () => socket.close();
|
|
15
23
|
signal?.addEventListener("abort", stop, { once: true });
|
|
16
|
-
// A call the browser
|
|
24
|
+
// A call the browser does not answer within `ms` (the deadline, unless shorter) settles empty, as does every call once
|
|
25
|
+
// the socket closes (an abort, the browser).
|
|
17
26
|
const pending = new Map();
|
|
18
27
|
const listeners = new Set();
|
|
19
28
|
let next = 0;
|
|
20
29
|
let closed = false;
|
|
21
30
|
// A send on a closed socket neither throws nor is ever answered (Node 24): once closed, every call settles empty.
|
|
22
|
-
const call = (method, params = {}, sessionId) => new Promise((resolve) => {
|
|
23
|
-
if (closed || socket.readyState !== WebSocket.OPEN)
|
|
31
|
+
const call = (method, params = {}, sessionId, ms = deadline - Date.now()) => new Promise((resolve) => {
|
|
32
|
+
if (closed || socket.readyState !== WebSocket.OPEN || ms <= 0)
|
|
24
33
|
return resolve(undefined);
|
|
25
|
-
|
|
26
|
-
|
|
34
|
+
const id = ++next;
|
|
35
|
+
const settle = (result) => { clearTimeout(wait); pending.delete(id); resolve(result); };
|
|
36
|
+
const wait = setTimeout(() => settle(undefined), ms);
|
|
37
|
+
pending.set(id, settle);
|
|
38
|
+
socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
|
|
27
39
|
});
|
|
28
40
|
try {
|
|
29
41
|
await new Promise((resolve, reject) => {
|
|
@@ -33,7 +45,7 @@ export async function installedExtension(cdpUrl, signal, known) {
|
|
|
33
45
|
socket.onerror = () => reject(new Error("Failed to open CDP WebSocket"));
|
|
34
46
|
socket.onclose = () => {
|
|
35
47
|
closed = true;
|
|
36
|
-
for (const settle of pending.values())
|
|
48
|
+
for (const settle of [...pending.values()])
|
|
37
49
|
settle(undefined);
|
|
38
50
|
for (const listener of listeners)
|
|
39
51
|
listener({ method: "closed" });
|
|
@@ -56,22 +68,35 @@ export async function installedExtension(cdpUrl, signal, known) {
|
|
|
56
68
|
return null;
|
|
57
69
|
id = enabled[0].id;
|
|
58
70
|
}
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
71
|
+
/** The extension's workers; null when the browser gave no list, which is not a list without one. */
|
|
72
|
+
const workers = async () => {
|
|
73
|
+
const infos = (await call("Target.getTargets"))?.targetInfos;
|
|
74
|
+
return infos?.filter((target) => target.type === "service_worker" && target.url.startsWith(`chrome-extension://${id}/`)).map((target) => target.targetId) ?? null;
|
|
75
|
+
};
|
|
62
76
|
const running = await workers();
|
|
77
|
+
if (running === null) {
|
|
78
|
+
if (signal?.aborted || closed)
|
|
79
|
+
return id;
|
|
80
|
+
throw new TargetsUnlistedError();
|
|
81
|
+
}
|
|
63
82
|
if (running.length === 0) {
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
83
|
+
// Every wake page opened stays listed here until a close of it is answered. None is opened within CLEANUP_MS of the
|
|
84
|
+
// deadline, an opening's reply is awaited into the first half of that second, and the socket outlives the deadline
|
|
85
|
+
// by CLEANUP_MS, so the last pages are closed on it.
|
|
86
|
+
const wakes = new Set();
|
|
87
|
+
const closeWakes = async (ms) => { for (const page of [...wakes])
|
|
88
|
+
if ((await call("Target.closeTarget", { targetId: page }, undefined, ms)) !== undefined)
|
|
89
|
+
wakes.delete(page); };
|
|
90
|
+
for (let tries = 0; !closed && Date.now() < deadline && tries < WAKE_TRIES && ((await workers())?.length ?? 0) === 0; tries += 1) {
|
|
91
|
+
if (tries % 10 === 0 && deadline - Date.now() > CLEANUP_MS) {
|
|
92
|
+
await closeWakes();
|
|
93
|
+
const page = (await call("Target.createTarget", { url: `chrome-extension://${id}/wake-service-worker.html` }, undefined, deadline + CLEANUP_MS / 2 - Date.now()))?.targetId;
|
|
94
|
+
if (page)
|
|
95
|
+
wakes.add(page);
|
|
70
96
|
}
|
|
71
97
|
await new Promise((r) => setTimeout(r, 100));
|
|
72
98
|
}
|
|
73
|
-
|
|
74
|
-
await call("Target.closeTarget", { targetId: wake });
|
|
99
|
+
await closeWakes(deadline + CLEANUP_MS - Date.now());
|
|
75
100
|
return id;
|
|
76
101
|
}
|
|
77
102
|
const sessionId = (await call("Target.attachToTarget", { targetId: running[0], flatten: true }))?.sessionId;
|
|
@@ -110,7 +135,9 @@ export async function installedExtension(cdpUrl, signal, known) {
|
|
|
110
135
|
}
|
|
111
136
|
return id;
|
|
112
137
|
}
|
|
113
|
-
catch {
|
|
138
|
+
catch (error) {
|
|
139
|
+
if (error instanceof TargetsUnlistedError)
|
|
140
|
+
throw error;
|
|
114
141
|
return known ?? null;
|
|
115
142
|
}
|
|
116
143
|
finally {
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/** Chrome's answer to an evaluate sent with a document's context id after a navigation replaced it. Stagehand's extension
|
|
2
|
+
* relays it as a JSON-RPC error with this text, and the facade's code runs rebuild it as a plain Error with the same
|
|
3
|
+
* text and no cause. Matched by identity. */
|
|
4
|
+
export declare const CONTEXT_GONE = "-32000 Cannot find context with specified id";
|
|
5
|
+
/** A read that lands in a document a navigation has just replaced waits for the new one, then reads once more. The
|
|
6
|
+
* wait's own failure is not the read's: the second read's answer, or its error, is what comes back. */
|
|
7
|
+
export declare function readOnNewDocument<T>(read: () => Promise<T>, waitForDocument: () => Promise<unknown>): Promise<T>;
|
|
8
|
+
type Facade = {
|
|
9
|
+
snapshot(options?: {
|
|
10
|
+
includeIframes?: boolean;
|
|
11
|
+
}): Promise<string>;
|
|
12
|
+
run(code: string): Promise<unknown>;
|
|
13
|
+
};
|
|
14
|
+
/** The driver's snapshot and page reads, each read once more on the new document when a navigation replaced its own. */
|
|
15
|
+
export declare function documentReads(facade: Facade, waitForDocument: () => Promise<unknown>): {
|
|
16
|
+
snapshot: (options?: {
|
|
17
|
+
includeIframes?: boolean;
|
|
18
|
+
}) => Promise<string>;
|
|
19
|
+
page: () => Promise<{
|
|
20
|
+
url: string;
|
|
21
|
+
title: string;
|
|
22
|
+
text: string;
|
|
23
|
+
html: string;
|
|
24
|
+
}>;
|
|
25
|
+
};
|
|
26
|
+
export {};
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/** Chrome's answer to an evaluate sent with a document's context id after a navigation replaced it. Stagehand's extension
|
|
2
|
+
* relays it as a JSON-RPC error with this text, and the facade's code runs rebuild it as a plain Error with the same
|
|
3
|
+
* text and no cause. Matched by identity. */
|
|
4
|
+
export const CONTEXT_GONE = "-32000 Cannot find context with specified id";
|
|
5
|
+
const contextGone = (error) => {
|
|
6
|
+
if (!(error instanceof Error))
|
|
7
|
+
return false;
|
|
8
|
+
const cause = error.cause;
|
|
9
|
+
if (cause && typeof cause === "object")
|
|
10
|
+
return typeof cause.code === "number" && cause.message === CONTEXT_GONE;
|
|
11
|
+
return error.message === CONTEXT_GONE;
|
|
12
|
+
};
|
|
13
|
+
/** A read that lands in a document a navigation has just replaced waits for the new one, then reads once more. The
|
|
14
|
+
* wait's own failure is not the read's: the second read's answer, or its error, is what comes back. */
|
|
15
|
+
export async function readOnNewDocument(read, waitForDocument) {
|
|
16
|
+
try {
|
|
17
|
+
return await read();
|
|
18
|
+
}
|
|
19
|
+
catch (error) {
|
|
20
|
+
if (!contextGone(error))
|
|
21
|
+
throw error;
|
|
22
|
+
await waitForDocument().catch(() => undefined);
|
|
23
|
+
return await read();
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
// A page's address is its document's (location.href): page.url() names a goto's target once Chrome starts it, so a
|
|
27
|
+
// receipt could cite a page it does not hold. One evaluate reads all four, so they are one document's.
|
|
28
|
+
const PAGE_CODE = `return await page.evaluate(() => ({
|
|
29
|
+
url: location.href,
|
|
30
|
+
title: document.title,
|
|
31
|
+
text: document.body ? document.body.innerText : "",
|
|
32
|
+
html: document.documentElement ? document.documentElement.outerHTML : "",
|
|
33
|
+
}));`;
|
|
34
|
+
/** The driver's snapshot and page reads, each read once more on the new document when a navigation replaced its own. */
|
|
35
|
+
export function documentReads(facade, waitForDocument) {
|
|
36
|
+
return {
|
|
37
|
+
snapshot: (options) => readOnNewDocument(() => facade.snapshot(options), waitForDocument),
|
|
38
|
+
page: async () => await readOnNewDocument(() => facade.run(PAGE_CODE), waitForDocument),
|
|
39
|
+
};
|
|
40
|
+
}
|
package/dist/driver/stagehand.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { StagehandFacadeTools } from "../vendor/stagehand-facade/tools.js";
|
|
2
2
|
import { installedExtension } from "./extension-worker.js";
|
|
3
|
+
import { documentReads } from "./new-document.js";
|
|
3
4
|
/** A closed loopback port, so no span leaves the host: Stagehand 4.1.0 cannot turn its trace exporter off. */
|
|
4
5
|
export const STAGEHAND_TELEMETRY = { traces: { endpoint: "http://127.0.0.1:9/v1/traces" } };
|
|
5
6
|
export const STAGEHAND_INFERENCE_REFUSED = "Stagehand inference is off in this harness: act, extract and observe are unavailable. Drive the page with run code or snapshot IDs.";
|
|
@@ -9,15 +10,9 @@ export const SEALED_STAGEHAND = {
|
|
|
9
10
|
model: { generate: async () => { throw new Error(STAGEHAND_INFERENCE_REFUSED); } },
|
|
10
11
|
telemetry: STAGEHAND_TELEMETRY,
|
|
11
12
|
};
|
|
12
|
-
// A page's address is its document's (location.href): page.url() names a goto's target once Chrome starts it, so a
|
|
13
|
-
// receipt could cite a page it does not hold. One evaluate reads all four, so they are one document's.
|
|
14
|
-
const PAGE_CODE = `return await page.evaluate(() => ({
|
|
15
|
-
url: location.href,
|
|
16
|
-
title: document.title,
|
|
17
|
-
text: document.body ? document.body.innerText : "",
|
|
18
|
-
html: document.documentElement ? document.documentElement.outerHTML : "",
|
|
19
|
-
}));`;
|
|
20
13
|
const URL_READ_MS = 2_000;
|
|
14
|
+
/** How long a read that landed in a document a navigation replaced waits for the new one's DOMContentLoaded. */
|
|
15
|
+
const NEW_DOCUMENT_MS = 15_000;
|
|
21
16
|
/** In a batch of its own, which the browser runs after any batch still running, so the read never lands inside a
|
|
22
17
|
* pending navigation (a page call issued then never returns). Past URL_READ_MS, Stagehand's page.url(). */
|
|
23
18
|
async function documentUrl(stagehand, page) {
|
|
@@ -71,8 +66,11 @@ export function stagehandDriver() {
|
|
|
71
66
|
throw new Error("Stagehand has no active page.");
|
|
72
67
|
return page;
|
|
73
68
|
};
|
|
69
|
+
// In a batch of its own, which the browser runs once the new document is its page's.
|
|
70
|
+
const newDocument = async () => stagehand.experimentalBatch(async (batch, input) => { await batch.page.waitForLoadState("domcontentloaded", input.ms); }, { ms: NEW_DOCUMENT_MS }, { page: await active(), timeout: NEW_DOCUMENT_MS + 1_000 });
|
|
71
|
+
const reads = documentReads(facade, newDocument);
|
|
74
72
|
return {
|
|
75
|
-
snapshot: (snapshotOptions) =>
|
|
73
|
+
snapshot: (snapshotOptions) => reads.snapshot(snapshotOptions),
|
|
76
74
|
run: (input) => input.actions !== undefined ? facade.runActions(input.actions) : facade.run(input.code ?? ""),
|
|
77
75
|
url: async () => documentUrl(stagehand, await active()),
|
|
78
76
|
screenshot: async ({ type = "png", quality, fullPage, scale }) => {
|
|
@@ -83,7 +81,7 @@ export function stagehandDriver() {
|
|
|
83
81
|
});
|
|
84
82
|
return { data: Buffer.from(bytes).toString("base64"), mimeType: type === "jpeg" ? "image/jpeg" : "image/png" };
|
|
85
83
|
},
|
|
86
|
-
page:
|
|
84
|
+
page: () => reads.page(),
|
|
87
85
|
// Stagehand's own close keeps the browser for another attach; the browser's close would end it.
|
|
88
86
|
close: () => stagehand.close(),
|
|
89
87
|
};
|
package/dist/durable.d.ts
CHANGED
|
@@ -47,7 +47,14 @@ export type BrowserExtensionOptions<D extends PageDriver = PageDriver> = {
|
|
|
47
47
|
createDeadlineMs?: number;
|
|
48
48
|
/** How the request observer attaches (default `EffectObserver.open`); a seam for tests that have no Chrome. */
|
|
49
49
|
openObserver?: typeof EffectObserver.open;
|
|
50
|
+
/** Called synchronously at two moments of a page action, for a host that kills the process there to test a resume:
|
|
51
|
+
* `browser.between-actions` once a page action's answer is committed, before the next page action dispatches, and
|
|
52
|
+
* `browser.action-returned` once the driver call returned (or threw) and the action's entry is marked finished,
|
|
53
|
+
* before pi commits its answer. A throw, or a rejected promise, is a process warning (`PI_BROWSER_CROSSING`) and
|
|
54
|
+
* never changes the call. */
|
|
55
|
+
crossing?: (point: Crossing) => void;
|
|
50
56
|
};
|
|
57
|
+
type Crossing = "browser.between-actions" | "browser.action-returned";
|
|
51
58
|
export type BrowserExtensionHandle = {
|
|
52
59
|
/** Install once per Harness, before `resume()`; select per conversation. */
|
|
53
60
|
extension: Extension;
|