@parcha/pi-browser 0.1.0-beta.31 → 0.1.0-beta.33
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 +45 -0
- package/NOTICE +4 -4
- package/README.md +38 -12
- package/dist/coding-agent.d.ts +1 -0
- package/dist/coding-agent.js +2 -2
- package/dist/core/contract.js +1 -1
- package/dist/core/custody.d.ts +7 -2
- package/dist/core/custody.js +7 -3
- package/dist/core/downloads.d.ts +7 -0
- package/dist/core/downloads.js +13 -1
- package/dist/core/driving-guard.d.ts +20 -0
- package/dist/core/driving-guard.js +175 -23
- package/dist/core/driving.d.ts +56 -2
- package/dist/core/driving.js +189 -10
- package/dist/core/effects.d.ts +80 -6
- package/dist/core/effects.js +374 -41
- package/dist/core/failures.d.ts +15 -1
- package/dist/core/failures.js +7 -0
- package/dist/core/host.d.ts +11 -2
- package/dist/core/tools.d.ts +14 -0
- package/dist/core/tools.js +42 -8
- package/dist/driver/page-driver.js +77 -4
- package/dist/driver/sealed.d.ts +4 -12
- package/dist/driver/sealed.js +23 -37
- package/dist/driver/stagehand.d.ts +10 -15
- package/dist/driver/stagehand.js +19 -17
- package/dist/durable/result.d.ts +1 -2
- package/dist/durable/result.js +2 -2
- package/dist/durable/store.d.ts +4 -1
- package/dist/durable/store.js +16 -11
- package/dist/durable.d.ts +14 -1
- package/dist/durable.js +39 -12
- package/dist/live-view/index.d.ts +2 -1
- package/dist/live-view/index.js +1 -0
- package/dist/live-view/protocol.d.ts +38 -6
- package/dist/live-view/protocol.js +2 -0
- package/dist/live-view/server.d.ts +24 -1
- package/dist/live-view/server.js +131 -11
- package/dist/live-view/stream.js +16 -3
- package/dist/live-view/viewer.js +106 -13
- package/dist/providers/cdp.d.ts +0 -1
- package/dist/providers/cdp.js +33 -11
- package/dist/providers/worker-extension.d.ts +6 -0
- package/dist/providers/worker-extension.js +17 -4
- package/package.json +10 -10
- package/dist/driver/extension-worker.d.ts +0 -9
- package/dist/driver/extension-worker.js +0 -185
package/dist/core/failures.d.ts
CHANGED
|
@@ -4,7 +4,10 @@ export type BrowserFailure = {
|
|
|
4
4
|
ok: false;
|
|
5
5
|
code: FailureCode;
|
|
6
6
|
retryable: boolean;
|
|
7
|
-
|
|
7
|
+
/** `partial`: a run of several actions stopped partway, the first `completed` of them done. */
|
|
8
|
+
effect: "none" | "possibly_effected" | "partial";
|
|
9
|
+
/** With `partial`: how many of the run's actions ran before it stopped. */
|
|
10
|
+
completed?: number;
|
|
8
11
|
message: string;
|
|
9
12
|
/** Provider or page text, at most 2,000 characters; redacted before it reaches the model. */
|
|
10
13
|
detail?: string;
|
|
@@ -17,6 +20,17 @@ export type Next = {
|
|
|
17
20
|
action: "drive_page" | "other_source" | "browser_relaunch";
|
|
18
21
|
note: string;
|
|
19
22
|
};
|
|
23
|
+
/** A run of several actions that stopped partway on an error a call's own handling must still see as it is (a dropped
|
|
24
|
+
* connection, whose driver is let go): the error is passed on as it is, marked with how many of the run's actions ran. */
|
|
25
|
+
export declare const PARTIAL: unique symbol;
|
|
26
|
+
export type PartialRun = {
|
|
27
|
+
completed: number;
|
|
28
|
+
of: number;
|
|
29
|
+
};
|
|
30
|
+
/** The mark PARTIAL left on `error`, if any. */
|
|
31
|
+
export declare const partialOf: (error: unknown) => PartialRun | undefined;
|
|
32
|
+
/** `failure` as a run stopped partway says it: partial, with how many ran, before its own words. */
|
|
33
|
+
export declare const asPartial: (failure: BrowserFailure, partial: PartialRun) => BrowserFailure;
|
|
20
34
|
export declare const browserFailure: (code: FailureCode, message: string, options?: {
|
|
21
35
|
retryable?: boolean;
|
|
22
36
|
effect?: BrowserFailure["effect"];
|
package/dist/core/failures.js
CHANGED
|
@@ -5,6 +5,13 @@ export const FAILURE_CODES = Object.freeze([
|
|
|
5
5
|
"browser_unavailable", "auth", "timeout", "aborted", "refused", "stale_snapshot", "session_ended",
|
|
6
6
|
"session_replaced", "effect_unknown", "code_error", "command_failed", "not_content", "blocked", "rate_limited", "waiting_for_human",
|
|
7
7
|
]);
|
|
8
|
+
/** A run of several actions that stopped partway on an error a call's own handling must still see as it is (a dropped
|
|
9
|
+
* connection, whose driver is let go): the error is passed on as it is, marked with how many of the run's actions ran. */
|
|
10
|
+
export const PARTIAL = Symbol.for("pi-browser.partial");
|
|
11
|
+
/** The mark PARTIAL left on `error`, if any. */
|
|
12
|
+
export const partialOf = (error) => (error !== null && typeof error === "object" ? error[PARTIAL] : undefined);
|
|
13
|
+
/** `failure` as a run stopped partway says it: partial, with how many ran, before its own words. */
|
|
14
|
+
export const asPartial = (failure, partial) => ({ ...failure, effect: "partial", completed: partial.completed, message: `${partial.completed} of the ${partial.of} actions ran, then this one failed: ${failure.message}` });
|
|
8
15
|
export const browserFailure = (code, message, options = {}) => ({ ok: false, code, retryable: options.retryable ?? false, effect: options.effect ?? "none", message, ...(options.detail === undefined ? {} : { detail: options.detail }) });
|
|
9
16
|
/** The vendored facade's refusal texts (vendor/stagehand-facade/contract.ts), copied so the root entry does not load the facade; a test pins
|
|
10
17
|
* them to the facade's own. */
|
package/dist/core/host.d.ts
CHANGED
|
@@ -86,7 +86,10 @@ export type AttachTarget = {
|
|
|
86
86
|
headers?: Record<string, string>;
|
|
87
87
|
expiresAt?: number;
|
|
88
88
|
};
|
|
89
|
-
|
|
89
|
+
/** The browser's own DevTools URL, which Stagehand's extension inside the browser dials for its own connection; absent, it
|
|
90
|
+
* dials `sdkCdpUrl`. A proxy in front of the driver then carries both, and a drop that cuts both leaves the extension
|
|
91
|
+
* holding a client it can no longer see leave: Stagehand 4.4 then refuses every attach until its worker restarts. */
|
|
92
|
+
extensionCdpUrl?: string;
|
|
90
93
|
};
|
|
91
94
|
export type ProviderCaps = {
|
|
92
95
|
timeoutModel: "wall-clock" | "inactivity";
|
|
@@ -127,10 +130,12 @@ export type Recording = {
|
|
|
127
130
|
startedAt: string | null;
|
|
128
131
|
durationS: number | null;
|
|
129
132
|
};
|
|
133
|
+
/** `downloading`: the browser is still writing it; it is listed so the caller can say so, and is not read. */
|
|
130
134
|
export type RemoteFile = {
|
|
131
135
|
name: string;
|
|
132
136
|
sizeBytes: number;
|
|
133
137
|
modifiedAt: string | null;
|
|
138
|
+
downloading?: true;
|
|
134
139
|
};
|
|
135
140
|
export type FetchRequest = {
|
|
136
141
|
url: string;
|
|
@@ -259,7 +264,11 @@ export interface HandoffPort {
|
|
|
259
264
|
} | {
|
|
260
265
|
refused: string;
|
|
261
266
|
}>;
|
|
262
|
-
|
|
267
|
+
/** With `reason`: why, in the host's words, for the model (an ask the host ended at its spend cap). */
|
|
268
|
+
outcome(interactionId: string, signal: AbortSignal): Promise<"pending" | HandoffOutcome | {
|
|
269
|
+
outcome: HandoffOutcome;
|
|
270
|
+
reason: string;
|
|
271
|
+
}>;
|
|
263
272
|
}
|
|
264
273
|
export type ReleaseReason = "tool" | "idle" | "relaunch" | "close" | "ended" | "lost" | "create_failed";
|
|
265
274
|
export type SessionRecord = {
|
package/dist/core/tools.d.ts
CHANGED
|
@@ -41,15 +41,22 @@ export type PageDriver = BrowserDriver & {
|
|
|
41
41
|
snapshot(options?: {
|
|
42
42
|
includeIframes?: boolean;
|
|
43
43
|
}): Promise<string>;
|
|
44
|
+
/** `checked`: an action after the first of a run of several, sent alone (driving-guard sends a batch one action at a time)
|
|
45
|
+
* after the whole batch was checked against the page's snapshot: the page's address, which the batch's own earlier
|
|
46
|
+
* actions may have moved (a same-page link), is not checked against the snapshot again. Its ids still are. */
|
|
44
47
|
run(input: {
|
|
45
48
|
code?: string;
|
|
46
49
|
actions?: RunAction[];
|
|
50
|
+
checked?: true;
|
|
47
51
|
}): Promise<unknown>;
|
|
48
52
|
/** The page's URL, cheaply: no page content is read. */
|
|
49
53
|
url(): Promise<string>;
|
|
50
54
|
/** Drops every snapshot's element ids, so an action by an old id fails as a stale snapshot (a person changed the page, whatever its URL). Optional:
|
|
51
55
|
* a driver without ids has none to drop. */
|
|
52
56
|
forgetSnapshots?(): void;
|
|
57
|
+
/** Checks a run's actions against the page's latest snapshot (every id there, the page still its address) without
|
|
58
|
+
* sending any, failing as `run` would. Optional: a driver without it sends a run's actions as one batch. */
|
|
59
|
+
checkActions?(actions: RunAction[]): Promise<void>;
|
|
53
60
|
screenshot(options: ScreenshotOptions): Promise<{
|
|
54
61
|
data: string;
|
|
55
62
|
mimeType: string;
|
|
@@ -134,6 +141,13 @@ type ReconnectTimings = {
|
|
|
134
141
|
tryMs: number;
|
|
135
142
|
backoffMs: readonly number[];
|
|
136
143
|
};
|
|
144
|
+
type Lost = {
|
|
145
|
+
method: string;
|
|
146
|
+
url: string;
|
|
147
|
+
};
|
|
148
|
+
/** Told to a call whose page sent requests the browser lost before they left it (Chrome's network service restarted under
|
|
149
|
+
* them): they were not sent, so the model may send them again. */
|
|
150
|
+
export declare const lostRequests: (lost: readonly Lost[]) => string;
|
|
137
151
|
export declare function pageTools({ guards, reconnect: timings, readDeadlineMs }?: {
|
|
138
152
|
/** Each conversation's repeat guard; a host that owns the conversation's lifecycle passes it to evict one. */
|
|
139
153
|
guards?: Map<number, RepeatGuard>;
|
package/dist/core/tools.js
CHANGED
|
@@ -2,7 +2,7 @@ import { setImmediate as yieldToLoop } from "node:timers/promises";
|
|
|
2
2
|
import { BrowserFailureError, FenceRefusal, refusedError, loadedNoPage, passedThrough } from "./custody.js";
|
|
3
3
|
import { defaultInline } from "./evidence.js";
|
|
4
4
|
import { fetchDownloads } from "./downloads.js";
|
|
5
|
-
import { browserFailure, classifyBrowserError, transportFactOf } from "./failures.js";
|
|
5
|
+
import { asPartial, browserFailure, classifyBrowserError, partialOf, transportFactOf } from "./failures.js";
|
|
6
6
|
import { createRepeatGuard } from "./guard.js";
|
|
7
7
|
import { regionOf } from "./clip.js";
|
|
8
8
|
import { captureWithinBudget } from "./images.js";
|
|
@@ -57,6 +57,18 @@ const pause = (ms, signal) => new Promise((resolve) => {
|
|
|
57
57
|
});
|
|
58
58
|
const text = (value, isError = false) => ({ content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value) }], ...(isError ? { isError: true } : {}) });
|
|
59
59
|
const withNews = (news, body) => (news ? `${news}\n\n${body}` : body);
|
|
60
|
+
const LOST = Symbol("lost requests");
|
|
61
|
+
/** An action's error carries the requests its call lost (`lost` is filled by the flush in the `finally` that follows the
|
|
62
|
+
* throw), so the failure answer still tells them. */
|
|
63
|
+
const withLost = (error, lost) => {
|
|
64
|
+
const carrier = error !== null && typeof error === "object" ? error : Object.assign(new Error(String(error)), { cause: error });
|
|
65
|
+
Object.defineProperty(carrier, LOST, { value: lost, configurable: true });
|
|
66
|
+
return carrier;
|
|
67
|
+
};
|
|
68
|
+
const lostOf = (error) => (error !== null && typeof error === "object" ? (error[LOST] ?? []) : []);
|
|
69
|
+
/** Told to a call whose page sent requests the browser lost before they left it (Chrome's network service restarted under
|
|
70
|
+
* them): they were not sent, so the model may send them again. */
|
|
71
|
+
export const lostRequests = (lost) => `The browser lost ${lost.length === 1 ? "a request" : `${lost.length} requests`} your page made before ${lost.length === 1 ? "the request" : "they"} left the browser: ${lost.map((r) => `${r.method} ${r.url}`).join(", ")}. Chrome's network service restarted while ${lost.length === 1 ? "it was" : "they were"} on ${lost.length === 1 ? "its" : "their"} way, so ${lost.length === 1 ? "the request was" : "the requests were"} not sent. Make ${lost.length === 1 ? "it" : "them"} again if you still need ${lost.length === 1 ? "it" : "them"}.`;
|
|
60
72
|
/** A read of a browser that has loaded no page yet: it is fresh, and the next step is to navigate, to the replaced
|
|
61
73
|
* session's last page when there is one. */
|
|
62
74
|
function freshBrowser(replaced) {
|
|
@@ -207,8 +219,8 @@ export function pageTools({ guards = new Map(), reconnect: timings = RECONNECT,
|
|
|
207
219
|
if (call.signal?.aborted)
|
|
208
220
|
break;
|
|
209
221
|
}
|
|
210
|
-
// The try's attach is bounded by what is left of the budget: one that waits on the browser (
|
|
211
|
-
//
|
|
222
|
+
// The try's attach is bounded by what is left of the budget: one that waits on the browser (a connection held on
|
|
223
|
+
// the way) stops there instead of running past it. The timer is a ref'd one, cleared when the try ends, so a
|
|
212
224
|
// reconnect in progress keeps the process alive (AbortSignal.timeout's timer does not, and Node 22 then drains).
|
|
213
225
|
const deadline = new AbortController();
|
|
214
226
|
const timer = setTimeout(() => deadline.abort(new DOMException("the reconnect's budget ran out", "TimeoutError")), Math.max(0, until - Date.now()));
|
|
@@ -257,7 +269,17 @@ export function pageTools({ guards = new Map(), reconnect: timings = RECONNECT,
|
|
|
257
269
|
const tell = (out) => (facts || previous ? { ...out, details: { ...out.details, ...(facts ? { pendingEffect: facts } : {}), ...(previous ? { previous_session: previous } : {}) } } : out);
|
|
258
270
|
const done = (out) => { guard.note(tool, args, null); return tell(out); };
|
|
259
271
|
// The notice leads a failure, never after its own keys: a call told nothing else first reads it.
|
|
260
|
-
|
|
272
|
+
// A run of several actions that dropped partway (driving-guard's partway): its failure says how many ran.
|
|
273
|
+
let partial;
|
|
274
|
+
// Requests the failed action's call lost: told in the failure's message and listed in details, as on success.
|
|
275
|
+
let lostOnError = [];
|
|
276
|
+
const fail = (given) => {
|
|
277
|
+
const failure = partial ? asPartial(given, partial) : given;
|
|
278
|
+
guard.note(tool, args, failure);
|
|
279
|
+
const told = lostOnError.length ? { ...failure, message: `${failure.message} ${lostRequests(lostOnError)}` } : failure;
|
|
280
|
+
const out = tell(text(news ? { notice: news, ...(previous ? { previous_session: previous } : {}), ...told } : told, true));
|
|
281
|
+
return lostOnError.length ? { ...out, details: { ...out.details, lost: lostOnError } } : out;
|
|
282
|
+
};
|
|
261
283
|
let cuts = [];
|
|
262
284
|
// A look after a refusal settles every refused cut in the chain whose warning a saved answer had already told; one this call is
|
|
263
285
|
// telling stays until a later look, so a process that dies before this answer is saved tells it again.
|
|
@@ -314,6 +336,8 @@ export function pageTools({ guards = new Map(), reconnect: timings = RECONNECT,
|
|
|
314
336
|
return await looked(effect === null ? await body(s, news) : await dispatched(tool, port, call, s, effect, () => body(s, news)));
|
|
315
337
|
}
|
|
316
338
|
catch (error) {
|
|
339
|
+
partial = partialOf(error);
|
|
340
|
+
lostOnError = lostOf(error);
|
|
317
341
|
const failure = await failureOf(error, effectful, port, call, action);
|
|
318
342
|
if (failure.code !== "browser_unavailable" || error instanceof BrowserFailureError)
|
|
319
343
|
return fail(failure);
|
|
@@ -362,11 +386,15 @@ export function pageTools({ guards = new Map(), reconnect: timings = RECONNECT,
|
|
|
362
386
|
const codeSha = sha256Hex(JSON.stringify(args.code ?? args.actions));
|
|
363
387
|
return perform("run", args, port, call, { effect: codeSha }, async (s, news) => {
|
|
364
388
|
const sent = [];
|
|
365
|
-
const
|
|
389
|
+
const lost = [];
|
|
390
|
+
const stop = s.effects?.record((row) => { sent.push({ method: row.method, url: call.redact(`${row.origin}${row.path}`), held: row.held }); return port.journal(row); }, (request) => { lost.push({ method: request.method, url: call.redact(`${request.origin}${request.path}`) }); });
|
|
366
391
|
let value;
|
|
367
392
|
try {
|
|
368
393
|
value = await s.driver.run(args.code !== undefined ? { code: runnableCode(args.code) } : { actions: args.actions });
|
|
369
394
|
}
|
|
395
|
+
catch (error) {
|
|
396
|
+
throw withLost(error, lost);
|
|
397
|
+
}
|
|
370
398
|
finally {
|
|
371
399
|
await s.effects?.flush(call.signal).catch(() => undefined);
|
|
372
400
|
stop?.();
|
|
@@ -379,7 +407,8 @@ export function pageTools({ guards = new Map(), reconnect: timings = RECONNECT,
|
|
|
379
407
|
}
|
|
380
408
|
const reported = args.actions !== undefined && value && typeof value === "object" && typeof value.url === "string" ? { ...value, url: pageUrl(call, value.url) } : value;
|
|
381
409
|
const shown = typeof reported === "string" ? reported : reported === undefined ? "(run completed; the code returned no value: end it with `return <value>` to get one back)" : JSON.stringify(reported, null, 2) ?? String(reported);
|
|
382
|
-
|
|
410
|
+
const told = lost.length ? `${shown}\n\n${lostRequests(lost)}` : shown;
|
|
411
|
+
return { ...text(withNews(news, told)), ...(sent.length || lost.length ? { details: { ...(sent.length ? { sent } : {}), ...(lost.length ? { lost } : {}) } } : {}) };
|
|
383
412
|
});
|
|
384
413
|
},
|
|
385
414
|
screenshot: (args, port, call) => {
|
|
@@ -442,15 +471,20 @@ export function pageTools({ guards = new Map(), reconnect: timings = RECONNECT,
|
|
|
442
471
|
if (!s.driver.setInputFiles)
|
|
443
472
|
throw refusedError("This browser driver cannot set a file input.");
|
|
444
473
|
const sent = [];
|
|
445
|
-
const
|
|
474
|
+
const lost = [];
|
|
475
|
+
const stop = s.effects?.record((row) => { sent.push({ method: row.method, url: call.redact(`${row.origin}${row.path}`), held: row.held }); return port.journal(row); }, (request) => { lost.push({ method: request.method, url: call.redact(`${request.origin}${request.path}`) }); });
|
|
446
476
|
try {
|
|
447
477
|
await s.driver.setInputFiles(selector, { name: file.name, mimeType: file.mime, buffer: file.bytes });
|
|
448
478
|
}
|
|
479
|
+
catch (error) {
|
|
480
|
+
throw withLost(error, lost);
|
|
481
|
+
}
|
|
449
482
|
finally {
|
|
450
483
|
await s.effects?.flush(call.signal).catch(() => undefined);
|
|
451
484
|
stop?.();
|
|
452
485
|
}
|
|
453
|
-
|
|
486
|
+
const notice = [news, lost.length ? lostRequests(lost) : ""].filter(Boolean).join(" ");
|
|
487
|
+
return { content: [{ type: "text", text: JSON.stringify({ ok: true, uploaded, selector, ...(notice ? { notice } : {}) }) }], details: { uploaded, ...(sent.length ? { sent } : {}), ...(lost.length ? { lost } : {}) } };
|
|
454
488
|
});
|
|
455
489
|
},
|
|
456
490
|
browser_downloads: (args, port, call) => perform("browser_downloads", {}, port, call, "read", async (s, news) => {
|
|
@@ -68,6 +68,8 @@ function bounded(stagehand, deadlines) {
|
|
|
68
68
|
browser: overriding(stagehand.browser, { context: overriding(context, { activePage: async () => { const active = await context.activePage(); return active ? page(active) : active; } }) }),
|
|
69
69
|
});
|
|
70
70
|
}
|
|
71
|
+
/** How long a page has to say which document it shows before it is taken not to know. */
|
|
72
|
+
const DOCUMENT_MS = 5_000;
|
|
71
73
|
/** `batchMs` bounds every run batch; the page calls' own deadlines are fixed but for tests. */
|
|
72
74
|
export function pageDriver(stagehand, deadlines) {
|
|
73
75
|
const host = bounded(stagehand, { snapshotMs: SNAPSHOT_MS, screenshotMs: SCREENSHOT_MS, ...deadlines });
|
|
@@ -82,9 +84,78 @@ export function pageDriver(stagehand, deadlines) {
|
|
|
82
84
|
// In a batch of its own, which the browser runs once the new document is its page's.
|
|
83
85
|
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 });
|
|
84
86
|
const reads = documentReads(facade, newDocument);
|
|
87
|
+
const kept = () => facade.snapshotsByPage;
|
|
88
|
+
/** The document a page shows, by its own performance.timeOrigin: new on every navigation to a new document and on a
|
|
89
|
+
* reload, the same across a #hash change or history.pushState/replaceState (Chrome's per-document loaderId, which
|
|
90
|
+
* neither Stagehand's page nor a batch's page can be asked for). Null when the page does not say. */
|
|
91
|
+
const documentOf = async (page) => {
|
|
92
|
+
let timer;
|
|
93
|
+
try {
|
|
94
|
+
const late = new Promise((resolve) => { timer = setTimeout(() => resolve(null), DOCUMENT_MS); });
|
|
95
|
+
const origin = await Promise.race([Promise.resolve(page.evaluate("performance.timeOrigin")).catch(() => null), late]);
|
|
96
|
+
return typeof origin === "number" ? origin : null;
|
|
97
|
+
}
|
|
98
|
+
catch {
|
|
99
|
+
return null;
|
|
100
|
+
}
|
|
101
|
+
finally {
|
|
102
|
+
clearTimeout(timer);
|
|
103
|
+
}
|
|
104
|
+
};
|
|
105
|
+
/** By page, the document each snapshot was taken on (read once the snapshot is), and that snapshot's ids, to know it is
|
|
106
|
+
* still the facade's. Read beside the snapshot, never holding it up: a batch awaits it. */
|
|
107
|
+
const snapshotDocuments = new Map();
|
|
108
|
+
/** An action after the first of a batch checked as one (driving-guard): run by the facade with the snapshot taken as at
|
|
109
|
+
* the page's address now, for this action only, so an address the batch's own earlier actions moved is not a stale
|
|
110
|
+
* snapshot; then the snapshot's own address again, so a later call on the moved page is told to snapshot again. */
|
|
111
|
+
const afterChecked = async (actions) => {
|
|
112
|
+
const page = await active();
|
|
113
|
+
const snapshot = kept().get(page.pageId);
|
|
114
|
+
// Only on the snapshot's own document: an earlier action that loaded a new one (a link to another page, a reload)
|
|
115
|
+
// leaves the snapshot's ids pointing at nothing of this page's, so the batch stops before this action, as stale.
|
|
116
|
+
if (snapshot) {
|
|
117
|
+
const taken = snapshotDocuments.get(page.pageId);
|
|
118
|
+
const was = taken && taken.xpathById === snapshot.xpathById ? await taken.document : null;
|
|
119
|
+
const document = was === null ? null : await documentOf(page);
|
|
120
|
+
if (was === null || document !== was)
|
|
121
|
+
throw new Error(NAVIGATED_SNAPSHOT_ERROR);
|
|
122
|
+
}
|
|
123
|
+
const now = snapshot ? await page.url() : undefined;
|
|
124
|
+
if (!snapshot || now === snapshot.url)
|
|
125
|
+
return facade.runActions(actions);
|
|
126
|
+
kept().set(page.pageId, { ...snapshot, url: now });
|
|
127
|
+
try {
|
|
128
|
+
return await facade.runActions(actions);
|
|
129
|
+
}
|
|
130
|
+
finally {
|
|
131
|
+
const current = kept().get(page.pageId);
|
|
132
|
+
if (current && current.xpathById === snapshot.xpathById)
|
|
133
|
+
kept().set(page.pageId, { ...current, url: snapshot.url });
|
|
134
|
+
}
|
|
135
|
+
};
|
|
85
136
|
return {
|
|
86
|
-
snapshot: (snapshotOptions) =>
|
|
87
|
-
|
|
137
|
+
snapshot: async (snapshotOptions) => {
|
|
138
|
+
const tree = await reads.snapshot(snapshotOptions);
|
|
139
|
+
const page = await active().catch(() => null);
|
|
140
|
+
const taken = page ? kept().get(page.pageId) : undefined;
|
|
141
|
+
if (page && taken)
|
|
142
|
+
snapshotDocuments.set(page.pageId, { xpathById: taken.xpathById, document: documentOf(page) });
|
|
143
|
+
return tree;
|
|
144
|
+
},
|
|
145
|
+
run: (input) => input.actions !== undefined ? (input.checked ? afterChecked(input.actions) : facade.runActions(input.actions)) : facade.run(input.code ?? ""),
|
|
146
|
+
// As the facade's own batch checks a run's actions before it sends any (runActionsNow): the active page's snapshot,
|
|
147
|
+
// the page still at its address, and every id in it. Read from the facade's snapshots, as forgetSnapshots does.
|
|
148
|
+
checkActions: async (actions) => {
|
|
149
|
+
const page = await active();
|
|
150
|
+
const snapshot = facade.snapshotsByPage.get(page.pageId);
|
|
151
|
+
if (!snapshot)
|
|
152
|
+
throw new Error(NO_HYDRATED_SNAPSHOT_ERROR);
|
|
153
|
+
if ((await page.url()) !== snapshot.url)
|
|
154
|
+
throw new Error(NAVIGATED_SNAPSHOT_ERROR);
|
|
155
|
+
for (const action of actions)
|
|
156
|
+
if (!snapshot.xpathById[action.id])
|
|
157
|
+
throw new Error(staleSnapshotIdError(action.id));
|
|
158
|
+
},
|
|
88
159
|
url: async () => documentUrl(stagehand, await active()),
|
|
89
160
|
// The facade keeps each page's last snapshot's ids for its own actions; with none, an action by id fails NO_HYDRATED (a stale snapshot).
|
|
90
161
|
forgetSnapshots: () => { facade.snapshotsByPage.clear(); },
|
|
@@ -122,7 +193,9 @@ export function pageDriver(stagehand, deadlines) {
|
|
|
122
193
|
page: () => reads.page(),
|
|
123
194
|
// An upload is effectful: past its deadline it fails as unanswered, and the page tools tell it as possibly applied.
|
|
124
195
|
setInputFiles: async (selector, file) => { await withinDeadline((await active()).locator(selector).setInputFiles({ name: file.name, mimeType: file.mimeType, buffer: file.buffer }), uploadMs, "locator.setInputFiles"); },
|
|
125
|
-
// Stagehand
|
|
126
|
-
|
|
196
|
+
// Stagehand 4.4 lets one client attach to a browser at a time, and its close leaves this client attached: disconnect closes
|
|
197
|
+
// the instance (waiting 10 s at most), detaches the client and closes the socket, so the next attach is allowed. The
|
|
198
|
+
// browser keeps running; the browser's own close would end it.
|
|
199
|
+
close: () => stagehand.browser.disconnect(),
|
|
127
200
|
};
|
|
128
201
|
}
|
package/dist/driver/sealed.d.ts
CHANGED
|
@@ -1,16 +1,8 @@
|
|
|
1
|
-
/** What Stagehand's extension answers an init while another is still running in it. */
|
|
2
|
-
export declare const INIT_IN_PROGRESS = "Stagehand initialization is already in progress";
|
|
3
|
-
/** Stagehand's own init deadline: an init the extension is still running has ended by then. */
|
|
4
|
-
export declare const IN_FLIGHT_INIT_MS = 60000;
|
|
5
|
-
/** The extension refused an init because another is still running in it (its JSON-RPC error, as Stagehand's cause). */
|
|
6
|
-
export declare const initInProgress: (error: unknown) => boolean;
|
|
7
1
|
/** A failed attach step names where it went: Stagehand reports a failed open as "[object Object]", and the socket's error
|
|
8
2
|
* has no address. */
|
|
9
3
|
export declare const attachStep: (host: string) => <T>(step: Promise<T>) => Promise<T>;
|
|
10
|
-
/** A cancelled call never starts
|
|
4
|
+
/** A cancelled call never starts a step of its own, however the wait ended. */
|
|
11
5
|
export declare function throwIfCancelled(signal?: AbortSignal): void;
|
|
12
|
-
/**
|
|
13
|
-
*
|
|
14
|
-
|
|
15
|
-
* busy, retryable. */
|
|
16
|
-
export declare function createSealed<S>(create: () => Promise<S>, waitForThatInit: () => Promise<unknown>, host: string, signal?: AbortSignal): Promise<S>;
|
|
6
|
+
/** `step`, or the cancel when `signal` ends first: the call stops at once, and a step that still succeeds later is handed to
|
|
7
|
+
* `release` (Stagehand's own steps take no signal, and one left attached would refuse the next attach). */
|
|
8
|
+
export declare function untilCancelled<T>(step: Promise<T>, signal: AbortSignal | undefined, release: (late: T) => unknown): Promise<T>;
|
package/dist/driver/sealed.js
CHANGED
|
@@ -1,47 +1,33 @@
|
|
|
1
|
-
// The steps of attaching a sealed Stagehand that can fail on their own: naming where a failed step went, stopping a
|
|
2
|
-
// cancelled attach
|
|
3
|
-
import { BrowserFailureError } from "../core/custody.js";
|
|
4
|
-
import { browserFailure } from "../core/failures.js";
|
|
5
|
-
/** What Stagehand's extension answers an init while another is still running in it. */
|
|
6
|
-
export const INIT_IN_PROGRESS = "Stagehand initialization is already in progress";
|
|
7
|
-
/** Stagehand's own init deadline: an init the extension is still running has ended by then. */
|
|
8
|
-
export const IN_FLIGHT_INIT_MS = 60_000;
|
|
9
|
-
/** The extension refused an init because another is still running in it (its JSON-RPC error, as Stagehand's cause). */
|
|
10
|
-
export const initInProgress = (error) => {
|
|
11
|
-
const cause = error?.cause;
|
|
12
|
-
return !!cause && typeof cause === "object" && typeof cause.code === "number" && cause.message === INIT_IN_PROGRESS;
|
|
13
|
-
};
|
|
1
|
+
// The steps of attaching a sealed Stagehand that can fail on their own: naming where a failed step went, and stopping a
|
|
2
|
+
// cancelled attach without leaving anything attached to the browser.
|
|
14
3
|
/** A failed attach step names where it went: Stagehand reports a failed open as "[object Object]", and the socket's error
|
|
15
4
|
* has no address. */
|
|
16
5
|
export const attachStep = (host) => (step) => step.catch((error) => {
|
|
17
6
|
throw new Error(`attaching to the browser at ${host} failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
|
|
18
7
|
});
|
|
19
|
-
|
|
8
|
+
const cancelled = (signal) => signal.reason instanceof Error ? signal.reason : Object.assign(new Error("the attach was cancelled"), { name: "AbortError" });
|
|
9
|
+
/** A cancelled call never starts a step of its own, however the wait ended. */
|
|
20
10
|
export function throwIfCancelled(signal) {
|
|
21
11
|
if (signal?.aborted)
|
|
22
|
-
throw signal
|
|
12
|
+
throw cancelled(signal);
|
|
23
13
|
}
|
|
24
|
-
/**
|
|
25
|
-
*
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
catch (error) {
|
|
33
|
-
if (!initInProgress(error))
|
|
34
|
-
throw error;
|
|
35
|
-
}
|
|
36
|
-
throwIfCancelled(signal);
|
|
37
|
-
await waitForThatInit();
|
|
38
|
-
throwIfCancelled(signal);
|
|
39
|
-
try {
|
|
40
|
-
return await create();
|
|
41
|
-
}
|
|
42
|
-
catch (again) {
|
|
43
|
-
if (!initInProgress(again))
|
|
44
|
-
throw again;
|
|
45
|
-
throw new BrowserFailureError(browserFailure("browser_unavailable", `The browser at ${host} is still finishing an earlier connection after ${IN_FLIGHT_INIT_MS / 1_000} s. Call again in a moment, or call browser_relaunch for a fresh session.`, { retryable: true }));
|
|
14
|
+
/** `step`, or the cancel when `signal` ends first: the call stops at once, and a step that still succeeds later is handed to
|
|
15
|
+
* `release` (Stagehand's own steps take no signal, and one left attached would refuse the next attach). */
|
|
16
|
+
export function untilCancelled(step, signal, release) {
|
|
17
|
+
if (!signal)
|
|
18
|
+
return step;
|
|
19
|
+
if (signal.aborted) {
|
|
20
|
+
step.then((late) => release(late), () => undefined).catch(() => undefined);
|
|
21
|
+
return Promise.reject(cancelled(signal));
|
|
46
22
|
}
|
|
23
|
+
return new Promise((resolve, reject) => {
|
|
24
|
+
let over = false;
|
|
25
|
+
const onAbort = () => { over = true; reject(cancelled(signal)); };
|
|
26
|
+
signal.addEventListener("abort", onAbort, { once: true });
|
|
27
|
+
step.then((value) => { signal.removeEventListener("abort", onAbort); if (over)
|
|
28
|
+
Promise.resolve().then(() => release(value)).catch(() => undefined);
|
|
29
|
+
else
|
|
30
|
+
resolve(value); }, (error) => { signal.removeEventListener("abort", onAbort); if (!over)
|
|
31
|
+
reject(error); });
|
|
32
|
+
});
|
|
47
33
|
}
|
|
@@ -1,12 +1,7 @@
|
|
|
1
1
|
import { type DriverFactory } from "../core/custody.js";
|
|
2
2
|
import type { PageDriver } from "../core/tools.js";
|
|
3
|
-
/** A closed loopback port, so no span leaves the host: Stagehand 4.1.0 cannot turn its trace exporter off. */
|
|
4
|
-
export declare const STAGEHAND_TELEMETRY: {
|
|
5
|
-
readonly traces: {
|
|
6
|
-
readonly endpoint: "http://127.0.0.1:9/v1/traces";
|
|
7
|
-
};
|
|
8
|
-
};
|
|
9
3
|
export declare 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.";
|
|
4
|
+
/** No telemetry is given, and Stagehand 4.4 starts its trace exporter only for an endpoint it is given: no span is sent. */
|
|
10
5
|
export declare const SEALED_STAGEHAND: {
|
|
11
6
|
readonly logging: {
|
|
12
7
|
readonly level: "off";
|
|
@@ -15,13 +10,13 @@ export declare const SEALED_STAGEHAND: {
|
|
|
15
10
|
readonly model: {
|
|
16
11
|
readonly generate: () => Promise<never>;
|
|
17
12
|
};
|
|
18
|
-
readonly telemetry: {
|
|
19
|
-
readonly traces: {
|
|
20
|
-
readonly endpoint: "http://127.0.0.1:9/v1/traces";
|
|
21
|
-
};
|
|
22
|
-
};
|
|
23
13
|
};
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
14
|
+
type StagehandModule = Pick<typeof import("@browserbasehq/stagehand"), "localBrowser" | "Stagehand">;
|
|
15
|
+
/** The batch deadline comes from `DriverOptions`; a caller that passes none gets the facade's 60 s. Stagehand allows one
|
|
16
|
+
* client per browser: an attach that fails or is cancelled after it connected disconnects again, and only then fails, so
|
|
17
|
+
* the next attach never meets its slot still taken (Stagehand bounds the disconnect: 10 s for the detach). `internals` is
|
|
18
|
+
* for tests: the Stagehand module the driver uses. */
|
|
19
|
+
export declare function stagehandDriver(internals?: {
|
|
20
|
+
stagehand?: () => Promise<StagehandModule>;
|
|
21
|
+
}): DriverFactory<PageDriver>;
|
|
22
|
+
export {};
|
package/dist/driver/stagehand.js
CHANGED
|
@@ -1,28 +1,30 @@
|
|
|
1
|
-
import { INERT_TRACE_ENDPOINT } from "../core/effects.js";
|
|
2
|
-
import { installedExtension } from "./extension-worker.js";
|
|
3
1
|
import { pageDriver } from "./page-driver.js";
|
|
4
|
-
import { attachStep,
|
|
5
|
-
/** A closed loopback port, so no span leaves the host: Stagehand 4.1.0 cannot turn its trace exporter off. */
|
|
6
|
-
export const STAGEHAND_TELEMETRY = { traces: { endpoint: INERT_TRACE_ENDPOINT } };
|
|
2
|
+
import { attachStep, throwIfCancelled, untilCancelled } from "./sealed.js";
|
|
7
3
|
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.";
|
|
4
|
+
/** No telemetry is given, and Stagehand 4.4 starts its trace exporter only for an endpoint it is given: no span is sent. */
|
|
8
5
|
export const SEALED_STAGEHAND = {
|
|
9
6
|
logging: { level: "off" },
|
|
10
7
|
cache: false,
|
|
11
8
|
model: { generate: async () => { throw new Error(STAGEHAND_INFERENCE_REFUSED); } },
|
|
12
|
-
telemetry: STAGEHAND_TELEMETRY,
|
|
13
9
|
};
|
|
14
|
-
/**
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
10
|
+
/** The batch deadline comes from `DriverOptions`; a caller that passes none gets the facade's 60 s. Stagehand allows one
|
|
11
|
+
* client per browser: an attach that fails or is cancelled after it connected disconnects again, and only then fails, so
|
|
12
|
+
* the next attach never meets its slot still taken (Stagehand bounds the disconnect: 10 s for the detach). `internals` is
|
|
13
|
+
* for tests: the Stagehand module the driver uses. */
|
|
14
|
+
export function stagehandDriver(internals = {}) {
|
|
18
15
|
return async (target, signal, options) => {
|
|
19
|
-
const { localBrowser, Stagehand } = await import("@browserbasehq/stagehand");
|
|
16
|
+
const { localBrowser, Stagehand } = await (internals.stagehand ?? (() => import("@browserbasehq/stagehand")))();
|
|
20
17
|
const host = new URL(target.dial?.url ?? target.sdkCdpUrl).host;
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
const
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
18
|
+
throwIfCancelled(signal);
|
|
19
|
+
const connecting = localBrowser.connect({ cdpUrl: target.sdkCdpUrl, ...(target.extensionCdpUrl ? { extensionCdpUrl: target.extensionCdpUrl } : {}) });
|
|
20
|
+
const browser = await untilCancelled(attachStep(host)(connecting), signal, (late) => late.disconnect());
|
|
21
|
+
try {
|
|
22
|
+
const stagehand = await untilCancelled(Stagehand.create({ browser, ...SEALED_STAGEHAND }), signal, () => undefined);
|
|
23
|
+
return pageDriver(stagehand, { batchMs: options?.batchTimeoutMs ?? 60_000 });
|
|
24
|
+
}
|
|
25
|
+
catch (error) {
|
|
26
|
+
await browser.disconnect().catch(() => undefined);
|
|
27
|
+
throw error;
|
|
28
|
+
}
|
|
27
29
|
};
|
|
28
30
|
}
|
package/dist/durable/result.d.ts
CHANGED
|
@@ -1,6 +1,5 @@
|
|
|
1
1
|
import type { ToolOutput } from "../core/custody.js";
|
|
2
|
-
/**
|
|
2
|
+
/** A tool result's blocks as pi-durable reads them: its `output`. */
|
|
3
3
|
export declare const forModel: (content: ToolOutput["content"]) => {
|
|
4
|
-
content: ToolOutput["content"];
|
|
5
4
|
output: ToolOutput["content"];
|
|
6
5
|
};
|
package/dist/durable/result.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
/**
|
|
2
|
-
export const forModel = (content) => ({
|
|
1
|
+
/** A tool result's blocks as pi-durable reads them: its `output`. */
|
|
2
|
+
export const forModel = (content) => ({ output: content });
|
package/dist/durable/store.d.ts
CHANGED
|
@@ -39,6 +39,7 @@ export type HandoffInput = {
|
|
|
39
39
|
};
|
|
40
40
|
type HandoffResult = {
|
|
41
41
|
outcome: HandoffOutcome;
|
|
42
|
+
reason?: string;
|
|
42
43
|
};
|
|
43
44
|
export type StoreDeps = {
|
|
44
45
|
name: string;
|
|
@@ -56,8 +57,10 @@ export type StoreDeps = {
|
|
|
56
57
|
handoff?: HandoffPort;
|
|
57
58
|
/** A handoff's session came back under `fence`. */
|
|
58
59
|
handedBack?(tag: string, fence: number): void;
|
|
60
|
+
/** A release task (an attempt, or its abort handler) had the provider release `tag`'s session, and the provider answered. */
|
|
61
|
+
stopped?(tag: string): void;
|
|
59
62
|
};
|
|
60
|
-
export declare function custodyStore({ name, Config, Sessions, providerOf, emit, meter, bill, scrubbed, createDeadlineMs, handoff, handedBack }: StoreDeps): {
|
|
63
|
+
export declare function custodyStore({ name, Config, Sessions, providerOf, emit, meter, bill, scrubbed, createDeadlineMs, handoff, handedBack, stopped: stoppedHook }: StoreDeps): {
|
|
61
64
|
Inventory: import("@earendil-works/pi-durable").SessionDocToken<{
|
|
62
65
|
rows: Record<string, InventoryRow>;
|
|
63
66
|
}>;
|