@parcha/pi-browser 0.0.0-stage → 0.1.0-beta.13
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 +16 -0
- package/LICENSE +202 -0
- package/NOTICE +33 -0
- package/README.md +329 -2
- package/dist/coding-agent-local.d.ts +16 -0
- package/dist/coding-agent-local.js +138 -0
- package/dist/coding-agent.d.ts +78 -0
- package/dist/coding-agent.js +446 -0
- package/dist/core/contract.d.ts +26 -0
- package/dist/core/contract.js +154 -0
- package/dist/core/custody.d.ts +111 -0
- package/dist/core/custody.js +122 -0
- package/dist/core/decisions.d.ts +43 -0
- package/dist/core/decisions.js +4 -0
- package/dist/core/downloads.d.ts +35 -0
- package/dist/core/downloads.js +131 -0
- package/dist/core/effects.d.ts +63 -0
- package/dist/core/effects.js +256 -0
- package/dist/core/evidence.d.ts +43 -0
- package/dist/core/evidence.js +6 -0
- package/dist/core/failures.d.ts +28 -0
- package/dist/core/failures.js +59 -0
- package/dist/core/find.d.ts +32 -0
- package/dist/core/find.js +179 -0
- package/dist/core/guard.d.ts +6 -0
- package/dist/core/guard.js +24 -0
- package/dist/core/host.d.ts +279 -0
- package/dist/core/host.js +2 -0
- package/dist/core/images.d.ts +37 -0
- package/dist/core/images.js +60 -0
- package/dist/core/lease.d.ts +16 -0
- package/dist/core/lease.js +30 -0
- package/dist/core/receipts.d.ts +19 -0
- package/dist/core/receipts.js +22 -0
- package/dist/core/redact.d.ts +13 -0
- package/dist/core/redact.js +83 -0
- package/dist/core/session-control.d.ts +25 -0
- package/dist/core/session-control.js +75 -0
- package/dist/core/sites.d.ts +33 -0
- package/dist/core/sites.js +102 -0
- package/dist/core/tools.d.ts +37 -0
- package/dist/core/tools.js +170 -0
- package/dist/core/uri.d.ts +11 -0
- package/dist/core/uri.js +37 -0
- package/dist/core/usage.d.ts +38 -0
- package/dist/core/usage.js +44 -0
- package/dist/core/web.d.ts +98 -0
- package/dist/core/web.js +327 -0
- package/dist/driver/stagehand.d.ts +25 -0
- package/dist/driver/stagehand.js +141 -0
- package/dist/durable-result.d.ts +6 -0
- package/dist/durable-result.js +2 -0
- package/dist/durable.d.ts +75 -0
- package/dist/durable.js +484 -0
- package/dist/index.d.ts +18 -0
- package/dist/index.js +19 -0
- package/dist/providers/browserbase-net.d.ts +13 -0
- package/dist/providers/browserbase-net.js +96 -0
- package/dist/providers/browserbase.d.ts +152 -0
- package/dist/providers/browserbase.js +262 -0
- package/dist/providers/cdp-call.d.ts +6 -0
- package/dist/providers/cdp-call.js +25 -0
- package/dist/providers/cdp.d.ts +48 -0
- package/dist/providers/cdp.js +353 -0
- package/dist/providers/http.d.ts +2 -0
- package/dist/providers/http.js +21 -0
- package/dist/providers/kernel.d.ts +49 -0
- package/dist/providers/kernel.js +246 -0
- package/dist/providers/shared.d.ts +47 -0
- package/dist/providers/shared.js +82 -0
- package/dist/recorder/credential.d.ts +9 -0
- package/dist/recorder/credential.js +49 -0
- package/dist/recorder/follow.d.ts +26 -0
- package/dist/recorder/follow.js +138 -0
- package/dist/recorder/frames.d.ts +80 -0
- package/dist/recorder/frames.js +309 -0
- package/dist/recorder/index.d.ts +3 -0
- package/dist/recorder/index.js +6 -0
- package/dist/recorder/jpeg.d.ts +5 -0
- package/dist/recorder/jpeg.js +34 -0
- package/dist/store.d.ts +56 -0
- package/dist/store.js +196 -0
- package/dist/testing/backend.d.ts +231 -0
- package/dist/testing/backend.js +414 -0
- package/dist/testing/driver.d.ts +28 -0
- package/dist/testing/driver.js +32 -0
- package/dist/testing/index.d.ts +4 -0
- package/dist/testing/index.js +4 -0
- package/dist/testing/pages.d.ts +3 -0
- package/dist/testing/pages.js +10 -0
- package/dist/testing/sentinels.d.ts +29 -0
- package/dist/testing/sentinels.js +38 -0
- package/dist/vendor/stagehand-facade/contract.d.ts +348 -0
- package/dist/vendor/stagehand-facade/contract.js +155 -0
- package/dist/vendor/stagehand-facade/runtime.d.ts +90 -0
- package/dist/vendor/stagehand-facade/runtime.js +1640 -0
- package/dist/vendor/stagehand-facade/screenshot-transport.d.ts +15 -0
- package/dist/vendor/stagehand-facade/screenshot-transport.js +51 -0
- package/dist/vendor/stagehand-facade/tools.d.ts +31 -0
- package/dist/vendor/stagehand-facade/tools.js +139 -0
- package/dist/web.d.ts +41 -0
- package/dist/web.js +38 -0
- package/package.json +123 -4
- package/src/vendor/stagehand-facade/UPSTREAM.json +24 -0
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
import type { Decisions, EffectRequest, EffectVerdict } from "./decisions.js";
|
|
2
|
+
import type { AttachTarget, ObserverFailure, SentEffect } from "./host.js";
|
|
3
|
+
/** What a request judged irreversible (or not judged) meets: sent, refused, or the host's answer. */
|
|
4
|
+
export type ActionPolicy = "allow" | "deny" | "ask";
|
|
5
|
+
/** `held` is the decision when the observer held it (`pending` while deciding), null when it went out unheld. */
|
|
6
|
+
export type EffectRow = SentEffect;
|
|
7
|
+
export type EffectDecision = {
|
|
8
|
+
allow: boolean;
|
|
9
|
+
verdict: EffectVerdict | null;
|
|
10
|
+
};
|
|
11
|
+
export type EffectDecider = (request: EffectRequest) => Promise<EffectDecision>;
|
|
12
|
+
/** Judgments are memoized per request shape, so a page that beacons every second costs one question; `ask` approvals
|
|
13
|
+
* are not. No judge, a null answer or a failure leaves the request judged irreversible. */
|
|
14
|
+
export declare function effectDecider(policy: ActionPolicy, decisions?: Pick<Decisions, "judgeEffect" | "approveEffect">): EffectDecider;
|
|
15
|
+
export declare function describeRequest(method: string, url: string, postData?: string, headers?: Record<string, string>): EffectRequest;
|
|
16
|
+
/** The code of an observer failure (`attach_failed` when untagged). Never reads the message. */
|
|
17
|
+
export declare const observerFailure: (error: unknown) => ObserverFailure;
|
|
18
|
+
export declare class EffectObserver {
|
|
19
|
+
private readonly ws;
|
|
20
|
+
private readonly decide;
|
|
21
|
+
private readonly decideMs;
|
|
22
|
+
private next;
|
|
23
|
+
private readonly pending;
|
|
24
|
+
private readonly sessions;
|
|
25
|
+
private readonly rows;
|
|
26
|
+
private listener;
|
|
27
|
+
private readonly inflight;
|
|
28
|
+
/** Announced by `Network.requestWillBeSent` (in order with page commands) but not yet paused by `Fetch.requestPaused`
|
|
29
|
+
* (which can lag). A holding session journals only at the pause, so `flush` waits for these. */
|
|
30
|
+
private readonly announced;
|
|
31
|
+
private announceSeq;
|
|
32
|
+
private announcedWaiters;
|
|
33
|
+
closed: boolean;
|
|
34
|
+
/** Resolves when a call is cut; decisions open then or taken later are refused until the next `record`, so a cut
|
|
35
|
+
* run's page sends nothing. */
|
|
36
|
+
private cutoff;
|
|
37
|
+
private cut;
|
|
38
|
+
private isCut;
|
|
39
|
+
private constructor();
|
|
40
|
+
/** True when every effect waits for its journal row to be committed before it may leave. */
|
|
41
|
+
get holding(): boolean;
|
|
42
|
+
/** `decide` null observes without holding; a decision not made within `decideMs` is a refusal. */
|
|
43
|
+
static open(target: AttachTarget, decide: EffectDecider | null, decideMs?: number): Promise<EffectObserver>;
|
|
44
|
+
/** Journal every effect from now on (a held one before it is sent); returns the stop. Lifts the previous call's cut. */
|
|
45
|
+
record(listener: (row: EffectRow) => unknown): () => void;
|
|
46
|
+
/** Resolves once everything the page started before this call is journaled. */
|
|
47
|
+
flush(signal?: AbortSignal, timeoutMs?: number): Promise<void>;
|
|
48
|
+
close(): void;
|
|
49
|
+
private arm;
|
|
50
|
+
private send;
|
|
51
|
+
private receive;
|
|
52
|
+
private announce;
|
|
53
|
+
private unannounce;
|
|
54
|
+
/** Bounded: a request the browser never pauses (it ended some other way) must not hold a flush forever. */
|
|
55
|
+
private announcedSettled;
|
|
56
|
+
/** Every command is sent before any answer is awaited, and the resume goes last: a paused target answers
|
|
57
|
+
* renderer-side commands only after it resumes. */
|
|
58
|
+
private setup;
|
|
59
|
+
private track;
|
|
60
|
+
private journal;
|
|
61
|
+
private sent;
|
|
62
|
+
private paused;
|
|
63
|
+
}
|
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
const SAFE = new Set(["GET", "HEAD", "OPTIONS"]);
|
|
2
|
+
const SESSIONS = new Set(["page", "iframe", "worker", "service_worker", "shared_worker"]);
|
|
3
|
+
const HARMLESS = { irreversibleBelow: 0.5, atLeast: 0.7 };
|
|
4
|
+
const REFUSED = { allow: false, verdict: null };
|
|
5
|
+
/** Judgments are memoized per request shape, so a page that beacons every second costs one question; `ask` approvals
|
|
6
|
+
* are not. No judge, a null answer or a failure leaves the request judged irreversible. */
|
|
7
|
+
export function effectDecider(policy, decisions = {}) {
|
|
8
|
+
const judged = new Map();
|
|
9
|
+
return async (request) => {
|
|
10
|
+
const key = JSON.stringify([request.method, request.origin, request.path, [...request.queryKeys].sort(), [...request.formFields].sort()]);
|
|
11
|
+
if (!judged.has(key))
|
|
12
|
+
judged.set(key, decisions.judgeEffect ? decisions.judgeEffect(request).catch(() => null) : Promise.resolve(null));
|
|
13
|
+
const verdict = await judged.get(key);
|
|
14
|
+
const harmless = verdict !== null && verdict.irreversible < HARMLESS.irreversibleBelow && (verdict.telemetry >= HARMLESS.atLeast || verdict.queryOnly >= HARMLESS.atLeast);
|
|
15
|
+
if (harmless || policy === "allow")
|
|
16
|
+
return { allow: true, verdict };
|
|
17
|
+
if (policy === "deny" || !decisions.approveEffect)
|
|
18
|
+
return { allow: false, verdict };
|
|
19
|
+
return { allow: await decisions.approveEffect(request, verdict).catch(() => false), verdict };
|
|
20
|
+
};
|
|
21
|
+
}
|
|
22
|
+
export function describeRequest(method, url, postData, headers = {}) {
|
|
23
|
+
const u = new URL(url);
|
|
24
|
+
const type = Object.entries(headers).find(([name]) => name.toLowerCase() === "content-type")?.[1] ?? "";
|
|
25
|
+
let formFields = [];
|
|
26
|
+
if (postData && type.includes("application/x-www-form-urlencoded"))
|
|
27
|
+
formFields = [...new URLSearchParams(postData).keys()];
|
|
28
|
+
else if (postData && type.includes("json"))
|
|
29
|
+
try {
|
|
30
|
+
const body = JSON.parse(postData);
|
|
31
|
+
if (body && typeof body === "object" && !Array.isArray(body))
|
|
32
|
+
formFields = Object.keys(body);
|
|
33
|
+
}
|
|
34
|
+
catch { }
|
|
35
|
+
return { method, origin: u.origin, path: u.pathname, queryKeys: [...new Set(u.searchParams.keys())], formFields, pageTitle: null, trigger: null, task: null };
|
|
36
|
+
}
|
|
37
|
+
const failed = (code, message) => Object.assign(new Error(message), { observerCode: code });
|
|
38
|
+
const CODES = ["attach_refused", "cdp_closed", "cdp_error", "attach_failed"];
|
|
39
|
+
/** The code of an observer failure (`attach_failed` when untagged). Never reads the message. */
|
|
40
|
+
export const observerFailure = (error) => {
|
|
41
|
+
const code = error?.observerCode;
|
|
42
|
+
return CODES.find((c) => c === code) ?? "attach_failed";
|
|
43
|
+
};
|
|
44
|
+
export class EffectObserver {
|
|
45
|
+
ws;
|
|
46
|
+
decide;
|
|
47
|
+
decideMs;
|
|
48
|
+
next = 1;
|
|
49
|
+
pending = new Map();
|
|
50
|
+
sessions = new Map();
|
|
51
|
+
rows = new Map();
|
|
52
|
+
listener = null;
|
|
53
|
+
inflight = new Set();
|
|
54
|
+
/** Announced by `Network.requestWillBeSent` (in order with page commands) but not yet paused by `Fetch.requestPaused`
|
|
55
|
+
* (which can lag). A holding session journals only at the pause, so `flush` waits for these. */
|
|
56
|
+
announced = new Map();
|
|
57
|
+
announceSeq = 0;
|
|
58
|
+
announcedWaiters = [];
|
|
59
|
+
closed = false;
|
|
60
|
+
/** Resolves when a call is cut; decisions open then or taken later are refused until the next `record`, so a cut
|
|
61
|
+
* run's page sends nothing. */
|
|
62
|
+
cutoff;
|
|
63
|
+
cut;
|
|
64
|
+
isCut = false;
|
|
65
|
+
constructor(ws, decide, decideMs) {
|
|
66
|
+
this.ws = ws;
|
|
67
|
+
this.decide = decide;
|
|
68
|
+
this.decideMs = decideMs;
|
|
69
|
+
this.arm();
|
|
70
|
+
}
|
|
71
|
+
/** True when every effect waits for its journal row to be committed before it may leave. */
|
|
72
|
+
get holding() { return this.decide !== null && !this.closed; }
|
|
73
|
+
/** `decide` null observes without holding; a decision not made within `decideMs` is a refusal. */
|
|
74
|
+
static async open(target, decide, decideMs = 60_000) {
|
|
75
|
+
const init = target.dial?.headers ? { headers: target.dial.headers } : undefined;
|
|
76
|
+
const ws = new WebSocket(target.dial?.url ?? target.sdkCdpUrl, init);
|
|
77
|
+
await new Promise((resolve, reject) => { ws.onopen = () => resolve(); ws.onerror = () => reject(failed("attach_refused", "the effect observer could not reach the browser")); });
|
|
78
|
+
const observer = new EffectObserver(ws, decide, decideMs);
|
|
79
|
+
ws.onmessage = (event) => observer.receive(JSON.parse(String(event.data)));
|
|
80
|
+
ws.onclose = () => { observer.closed = true; for (const p of observer.pending.values())
|
|
81
|
+
p.reject(failed("cdp_closed", "the effect observer's socket closed")); observer.pending.clear(); };
|
|
82
|
+
// New targets start paused, so nothing they send escapes before their Network and Fetch domains are on.
|
|
83
|
+
await observer.send("Target.setAutoAttach", { autoAttach: true, waitForDebuggerOnStart: true, flatten: true });
|
|
84
|
+
await new Promise((r) => setTimeout(r, 150));
|
|
85
|
+
const attached = new Set([...observer.sessions.values()].map((s) => s.targetId));
|
|
86
|
+
for (const t of (await observer.send("Target.getTargets")).targetInfos) {
|
|
87
|
+
if (t.type === "page" && !attached.has(t.targetId))
|
|
88
|
+
await observer.send("Target.attachToTarget", { targetId: t.targetId, flatten: true });
|
|
89
|
+
}
|
|
90
|
+
return observer;
|
|
91
|
+
}
|
|
92
|
+
/** Journal every effect from now on (a held one before it is sent); returns the stop. Lifts the previous call's cut. */
|
|
93
|
+
record(listener) {
|
|
94
|
+
if (this.isCut)
|
|
95
|
+
this.arm();
|
|
96
|
+
this.listener = listener;
|
|
97
|
+
return () => { if (this.listener === listener)
|
|
98
|
+
this.listener = null; };
|
|
99
|
+
}
|
|
100
|
+
/** Resolves once everything the page started before this call is journaled. */
|
|
101
|
+
async flush(signal, timeoutMs = 1000) {
|
|
102
|
+
await Promise.all([...this.sessions].filter(([, s]) => SESSIONS.has(s.type)).map(([id]) => Promise.race([this.send("Runtime.evaluate", { expression: "0" }, id).catch(() => undefined), new Promise((r) => setTimeout(r, timeoutMs))])));
|
|
103
|
+
const cut = () => { this.isCut = true; this.cut(); };
|
|
104
|
+
if (signal?.aborted)
|
|
105
|
+
cut();
|
|
106
|
+
else
|
|
107
|
+
signal?.addEventListener("abort", cut, { once: true });
|
|
108
|
+
try {
|
|
109
|
+
await this.announcedSettled(timeoutMs);
|
|
110
|
+
while (this.inflight.size)
|
|
111
|
+
await Promise.allSettled([...this.inflight]);
|
|
112
|
+
}
|
|
113
|
+
finally {
|
|
114
|
+
signal?.removeEventListener("abort", cut);
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
close() { try {
|
|
118
|
+
this.ws.close();
|
|
119
|
+
}
|
|
120
|
+
catch { } }
|
|
121
|
+
arm() { this.isCut = false; this.cutoff = new Promise((resolve) => { this.cut = () => resolve(REFUSED); }); }
|
|
122
|
+
send(method, params = {}, sessionId) {
|
|
123
|
+
const id = this.next++;
|
|
124
|
+
return new Promise((resolve, reject) => {
|
|
125
|
+
this.pending.set(id, { resolve, reject });
|
|
126
|
+
try {
|
|
127
|
+
this.ws.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
|
|
128
|
+
}
|
|
129
|
+
catch (error) {
|
|
130
|
+
this.pending.delete(id);
|
|
131
|
+
reject(error);
|
|
132
|
+
}
|
|
133
|
+
});
|
|
134
|
+
}
|
|
135
|
+
receive(m) {
|
|
136
|
+
if (m.id !== undefined) {
|
|
137
|
+
const p = this.pending.get(m.id);
|
|
138
|
+
this.pending.delete(m.id);
|
|
139
|
+
if (m.error)
|
|
140
|
+
p?.reject(failed("cdp_error", m.error.message));
|
|
141
|
+
else
|
|
142
|
+
p?.resolve(m.result);
|
|
143
|
+
return;
|
|
144
|
+
}
|
|
145
|
+
if (m.method === "Target.attachedToTarget")
|
|
146
|
+
void this.setup(m.params);
|
|
147
|
+
else if (m.method === "Target.detachedFromTarget") {
|
|
148
|
+
this.sessions.delete(m.params.sessionId);
|
|
149
|
+
for (const [id, entry] of [...this.announced])
|
|
150
|
+
if (entry.sessionId === m.params.sessionId)
|
|
151
|
+
this.unannounce(id);
|
|
152
|
+
}
|
|
153
|
+
else if (m.method === "Network.requestWillBeSent") {
|
|
154
|
+
this.announce(m.sessionId, m.params);
|
|
155
|
+
this.track(this.sent(m.sessionId, m.params));
|
|
156
|
+
}
|
|
157
|
+
else if (m.method === "Fetch.requestPaused") {
|
|
158
|
+
this.track(this.paused(m.sessionId, m.params));
|
|
159
|
+
// A preflight (OPTIONS) is paused first and says nothing about the request it precedes.
|
|
160
|
+
if (!SAFE.has(m.params.request.method)) {
|
|
161
|
+
this.unannounce(m.params.networkId ?? m.params.requestId);
|
|
162
|
+
if (m.params.resourceType === "Document")
|
|
163
|
+
this.unannounce(`navigation:${m.params.frameId}`);
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
else if (m.method === "Network.loadingFailed" || m.method === "Network.loadingFinished")
|
|
167
|
+
this.unannounce(m.params.requestId);
|
|
168
|
+
else if (m.method === "Page.frameRequestedNavigation" && m.params.reason === "formSubmissionPost" && this.sessions.get(m.sessionId)?.holds)
|
|
169
|
+
this.announced.set(`navigation:${m.params.frameId}`, { sessionId: m.sessionId, seq: (this.announceSeq += 1) });
|
|
170
|
+
}
|
|
171
|
+
announce(sessionId, p) {
|
|
172
|
+
if (this.sessions.get(sessionId)?.holds && !SAFE.has(p.request.method))
|
|
173
|
+
this.announced.set(p.requestId, { sessionId, seq: (this.announceSeq += 1) });
|
|
174
|
+
}
|
|
175
|
+
unannounce(requestId) {
|
|
176
|
+
if (this.announced.delete(requestId) && this.announced.size === 0)
|
|
177
|
+
for (const wake of this.announcedWaiters.splice(0))
|
|
178
|
+
wake();
|
|
179
|
+
}
|
|
180
|
+
/** Bounded: a request the browser never pauses (it ended some other way) must not hold a flush forever. */
|
|
181
|
+
announcedSettled(ms) {
|
|
182
|
+
if (this.announced.size === 0)
|
|
183
|
+
return Promise.resolve();
|
|
184
|
+
return new Promise((resolve) => {
|
|
185
|
+
const done = () => { clearTimeout(timer); this.announcedWaiters = this.announcedWaiters.filter((w) => w !== done); resolve(); };
|
|
186
|
+
const covered = this.announceSeq;
|
|
187
|
+
const timer = setTimeout(() => { for (const [id, entry] of [...this.announced])
|
|
188
|
+
if (entry.seq <= covered)
|
|
189
|
+
this.unannounce(id); done(); }, ms);
|
|
190
|
+
this.announcedWaiters.push(done);
|
|
191
|
+
});
|
|
192
|
+
}
|
|
193
|
+
/** Every command is sent before any answer is awaited, and the resume goes last: a paused target answers
|
|
194
|
+
* renderer-side commands only after it resumes. */
|
|
195
|
+
async setup({ sessionId, targetInfo, waitingForDebugger }) {
|
|
196
|
+
const { targetId, type, url } = targetInfo;
|
|
197
|
+
const holds = this.decide !== null && SESSIONS.has(type) && type !== "worker" && !url.startsWith("chrome-extension://");
|
|
198
|
+
this.sessions.set(sessionId, { targetId, type, url, holds });
|
|
199
|
+
const steps = [];
|
|
200
|
+
if (SESSIONS.has(type))
|
|
201
|
+
steps.push(this.send("Network.enable", {}, sessionId));
|
|
202
|
+
if (holds)
|
|
203
|
+
steps.push(this.send("Fetch.enable", { patterns: [{ urlPattern: "*", requestStage: "Request" }] }, sessionId));
|
|
204
|
+
// A form's request is announced late (it starts in the browser process); the page announces the intent first. An
|
|
205
|
+
// out-of-process frame announces its own forms, so it needs the Page domain too.
|
|
206
|
+
if (holds && (type === "page" || type === "iframe"))
|
|
207
|
+
steps.push(this.send("Page.enable", {}, sessionId));
|
|
208
|
+
if (SESSIONS.has(type) || type === "tab")
|
|
209
|
+
steps.push(this.send("Target.setAutoAttach", { autoAttach: true, waitForDebuggerOnStart: true, flatten: true }, sessionId));
|
|
210
|
+
if (waitingForDebugger)
|
|
211
|
+
steps.push(this.send("Runtime.runIfWaitingForDebugger", {}, sessionId));
|
|
212
|
+
await Promise.allSettled(steps);
|
|
213
|
+
}
|
|
214
|
+
track(work) {
|
|
215
|
+
const done = work.catch(() => undefined).finally(() => this.inflight.delete(done));
|
|
216
|
+
this.inflight.add(done);
|
|
217
|
+
}
|
|
218
|
+
async journal(requestId, request, held, verdict) {
|
|
219
|
+
const prior = this.rows.get(requestId);
|
|
220
|
+
if (prior && (held === null || prior.held === held))
|
|
221
|
+
return true;
|
|
222
|
+
const row = { requestId, method: request.method, origin: request.origin, path: request.path, at: prior?.at ?? new Date().toISOString(), held, irreversible: verdict?.irreversible ?? prior?.irreversible ?? null };
|
|
223
|
+
this.rows.set(requestId, row);
|
|
224
|
+
try {
|
|
225
|
+
await this.listener?.(row);
|
|
226
|
+
return true;
|
|
227
|
+
}
|
|
228
|
+
catch {
|
|
229
|
+
return false;
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
async sent(sessionId, p) {
|
|
233
|
+
const session = this.sessions.get(sessionId);
|
|
234
|
+
if (SAFE.has(p.request.method) || !session || session.url.startsWith("chrome-extension://") || session.holds)
|
|
235
|
+
return;
|
|
236
|
+
await this.journal(p.requestId, describeRequest(p.request.method, p.request.url), null, null);
|
|
237
|
+
}
|
|
238
|
+
async paused(sessionId, p) {
|
|
239
|
+
const { method, url, postData, headers } = p.request;
|
|
240
|
+
if (SAFE.has(method) || !this.decide)
|
|
241
|
+
return this.send("Fetch.continueRequest", { requestId: p.requestId }, sessionId);
|
|
242
|
+
const request = describeRequest(method, url, postData, headers);
|
|
243
|
+
const cutoff = this.cutoff;
|
|
244
|
+
// Journaled `pending` and committed before deciding: a process that dies mid-decision loses the hold and the
|
|
245
|
+
// request goes, so the journal must already name it. A request whose row could not be saved never leaves.
|
|
246
|
+
const id = p.networkId ?? p.requestId;
|
|
247
|
+
const saved = await this.journal(id, request, "pending", null);
|
|
248
|
+
let timer;
|
|
249
|
+
const limit = new Promise((resolve) => { timer = setTimeout(() => resolve(REFUSED), this.decideMs); });
|
|
250
|
+
const { allow, verdict } = saved ? await Promise.race([this.decide(request), cutoff, limit]).finally(() => clearTimeout(timer)) : REFUSED;
|
|
251
|
+
const recorded = await this.journal(id, request, allow ? "allowed" : "denied", verdict);
|
|
252
|
+
if (allow && !recorded)
|
|
253
|
+
return this.send("Fetch.failRequest", { requestId: p.requestId, errorReason: "BlockedByClient" }, sessionId);
|
|
254
|
+
await this.send(allow ? "Fetch.continueRequest" : "Fetch.failRequest", allow ? { requestId: p.requestId } : { requestId: p.requestId, errorReason: "BlockedByClient" }, sessionId);
|
|
255
|
+
}
|
|
256
|
+
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
export type EvidenceTool = "browser_read" | "web_fetch" | "screenshot" | "browser_downloads";
|
|
2
|
+
export type EvidenceRecord = {
|
|
3
|
+
tool: EvidenceTool;
|
|
4
|
+
args: Record<string, unknown>;
|
|
5
|
+
status: "ok" | "failed";
|
|
6
|
+
facts: {
|
|
7
|
+
requested_url?: string;
|
|
8
|
+
final_url?: string;
|
|
9
|
+
title?: string;
|
|
10
|
+
status_code?: number;
|
|
11
|
+
content_type?: string;
|
|
12
|
+
/** Of the filed body bytes. */
|
|
13
|
+
sha256: string;
|
|
14
|
+
extractor?: "readability-md" | "inner-text" | "provider-markdown" | "raw" | "pdf-text";
|
|
15
|
+
/** `browserbase_fetch`, `browser` or `backup:<tool>`. */
|
|
16
|
+
via?: string;
|
|
17
|
+
session?: string;
|
|
18
|
+
/** From the session's start, to find the read in the session recording. */
|
|
19
|
+
recording_at_s?: number;
|
|
20
|
+
page_guard?: string;
|
|
21
|
+
};
|
|
22
|
+
body: string | Uint8Array;
|
|
23
|
+
ext?: string;
|
|
24
|
+
};
|
|
25
|
+
export type EvidenceSink = {
|
|
26
|
+
/** `path` is what the model cites; `bodyLine` is the 1-indexed line where the body starts. Null: nothing was filed. */
|
|
27
|
+
file(label: string, record: EvidenceRecord): Promise<{
|
|
28
|
+
path: string;
|
|
29
|
+
bodyLine?: number;
|
|
30
|
+
} | null>;
|
|
31
|
+
/** The model's whole result for a filed body; absent, a head under DEFAULT_INLINE_CHARS and the file's path. */
|
|
32
|
+
inline?(body: string, at: {
|
|
33
|
+
path: string | null;
|
|
34
|
+
bodyLine: number | null;
|
|
35
|
+
prefix: string;
|
|
36
|
+
filed: string;
|
|
37
|
+
}): string;
|
|
38
|
+
};
|
|
39
|
+
export declare const DEFAULT_INLINE_CHARS = 8000;
|
|
40
|
+
export declare function defaultInline(body: string, at: {
|
|
41
|
+
path: string | null;
|
|
42
|
+
prefix: string;
|
|
43
|
+
}): string;
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export const DEFAULT_INLINE_CHARS = 8_000;
|
|
2
|
+
export function defaultInline(body, at) {
|
|
3
|
+
const cap = Math.max(0, DEFAULT_INLINE_CHARS - at.prefix.length);
|
|
4
|
+
const where = at.path ? `the complete body is filed at ${at.path}` : "the complete body could not be filed";
|
|
5
|
+
return at.prefix + (body.length <= cap ? `${body}${at.path ? `\n\n(receipt: ${at.path})` : ""}` : `${body.slice(0, cap)}\n\n(shown ${cap} of ${body.length} characters; ${where})`);
|
|
6
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
export declare const FAILURE_CODES: readonly ["browser_unavailable", "auth", "timeout", "aborted", "refused", "stale_snapshot", "session_ended", "session_replaced", "effect_unknown", "code_error", "command_failed", "not_content", "blocked", "rate_limited"];
|
|
2
|
+
export type FailureCode = (typeof FAILURE_CODES)[number];
|
|
3
|
+
export type BrowserFailure = {
|
|
4
|
+
ok: false;
|
|
5
|
+
code: FailureCode;
|
|
6
|
+
retryable: boolean;
|
|
7
|
+
effect: "none" | "possibly_effected";
|
|
8
|
+
message: string;
|
|
9
|
+
/** Provider or page text, at most 2,000 characters; redacted before it reaches the model. */
|
|
10
|
+
detail?: string;
|
|
11
|
+
};
|
|
12
|
+
/** `timedOut`: the call ran to the driver's batch deadline, which Stagehand reports as a plain Error. */
|
|
13
|
+
export type FailureFacts = {
|
|
14
|
+
sessionEnded?: boolean;
|
|
15
|
+
aborted?: boolean;
|
|
16
|
+
timedOut?: boolean;
|
|
17
|
+
};
|
|
18
|
+
export declare const NO_HYDRATED_SNAPSHOT_ERROR = "No hydrated snapshot exists for the active page; call snapshot first.";
|
|
19
|
+
export declare const NAVIGATED_SNAPSHOT_ERROR = "The active page navigated after its snapshot; call snapshot again.";
|
|
20
|
+
export declare const STALE_SNAPSHOT_ID_ERROR = "Snapshot ID \"${id}\" is stale or not actionable; call snapshot again.";
|
|
21
|
+
export type TransportFact = {
|
|
22
|
+
status?: number;
|
|
23
|
+
errorName?: string;
|
|
24
|
+
causeCode?: string;
|
|
25
|
+
};
|
|
26
|
+
/** A throw site's `transport` record, else class name, `code` and `status` down the cause chain; first found wins. */
|
|
27
|
+
export declare function transportFactOf(error: unknown): TransportFact;
|
|
28
|
+
export declare function classifyBrowserError(error: unknown, effectful: boolean, facts?: FailureFacts): BrowserFailure;
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
// A code comes from typed facts only (status, class names, cause-chain codes, refusal constants by identity), never
|
|
2
|
+
// from an error's message.
|
|
3
|
+
export const FAILURE_CODES = Object.freeze([
|
|
4
|
+
"browser_unavailable", "auth", "timeout", "aborted", "refused", "stale_snapshot", "session_ended",
|
|
5
|
+
"session_replaced", "effect_unknown", "code_error", "command_failed", "not_content", "blocked", "rate_limited",
|
|
6
|
+
]);
|
|
7
|
+
export const NO_HYDRATED_SNAPSHOT_ERROR = "No hydrated snapshot exists for the active page; call snapshot first.";
|
|
8
|
+
export const NAVIGATED_SNAPSHOT_ERROR = "The active page navigated after its snapshot; call snapshot again.";
|
|
9
|
+
export const STALE_SNAPSHOT_ID_ERROR = 'Snapshot ID "${id}" is stale or not actionable; call snapshot again.';
|
|
10
|
+
const [STALE_ID_HEAD, STALE_ID_TAIL] = STALE_SNAPSHOT_ID_ERROR.split("${id}");
|
|
11
|
+
const isStaleSnapshot = (message) => message === NO_HYDRATED_SNAPSHOT_ERROR || message === NAVIGATED_SNAPSHOT_ERROR
|
|
12
|
+
|| (message.startsWith(STALE_ID_HEAD) && message.endsWith(STALE_ID_TAIL) && message.length > STALE_ID_HEAD.length + STALE_ID_TAIL.length);
|
|
13
|
+
const UNREACHABLE_CAUSES = new Set(["ECONNREFUSED", "ENOTFOUND", "ECONNRESET", "EAI_AGAIN", "EPIPE", "UND_ERR_SOCKET", "UND_ERR_CONNECT_TIMEOUT"]);
|
|
14
|
+
const UNREACHABLE_NAMES = new Set(["CDPConnectionClosedError"]);
|
|
15
|
+
/** A throw site's `transport` record, else class name, `code` and `status` down the cause chain; first found wins. */
|
|
16
|
+
export function transportFactOf(error) {
|
|
17
|
+
const out = {};
|
|
18
|
+
let current = error;
|
|
19
|
+
for (let depth = 0; current && typeof current === "object" && depth < 6; depth += 1, current = current.cause) {
|
|
20
|
+
const attached = current.transport;
|
|
21
|
+
if (attached && typeof attached === "object") {
|
|
22
|
+
for (const [key, value] of Object.entries(attached))
|
|
23
|
+
if (value !== undefined && out[key] === undefined)
|
|
24
|
+
out[key] = value;
|
|
25
|
+
}
|
|
26
|
+
if (out.errorName === undefined && typeof current.name === "string" && current.name !== "Error")
|
|
27
|
+
out.errorName = current.name;
|
|
28
|
+
if (out.causeCode === undefined && typeof current.code === "string" && current.code)
|
|
29
|
+
out.causeCode = current.code;
|
|
30
|
+
if (out.status === undefined && Number.isInteger(current.status))
|
|
31
|
+
out.status = current.status;
|
|
32
|
+
}
|
|
33
|
+
return out;
|
|
34
|
+
}
|
|
35
|
+
export function classifyBrowserError(error, effectful, facts = {}) {
|
|
36
|
+
// Stagehand wraps SDK failures with { cause }: the HTTP status and the real message live on the cause.
|
|
37
|
+
const cause = error?.cause;
|
|
38
|
+
const own = error instanceof Error ? error.message : String(error);
|
|
39
|
+
const message = [own, cause instanceof Error ? cause.message : cause ? String(cause) : ""].filter(Boolean).join(": ");
|
|
40
|
+
const fact = transportFactOf(error);
|
|
41
|
+
const status = fact.status ?? Number(error?.statusCode ?? cause?.statusCode ?? NaN);
|
|
42
|
+
const effect = effectful ? "possibly_effected" : "none";
|
|
43
|
+
const detail = message.slice(0, 2_000);
|
|
44
|
+
if (facts.aborted || fact.errorName === "AbortError")
|
|
45
|
+
return { ok: false, code: "aborted", retryable: false, effect, message: "The browser call was cancelled by the run.", detail };
|
|
46
|
+
if (status === 401)
|
|
47
|
+
return { ok: false, code: "auth", retryable: false, effect: "none", message: "Browserbase refused the credential (401). The browser plane is unavailable for this run; use fetch (executor tools).", detail };
|
|
48
|
+
if (status === 403)
|
|
49
|
+
return { ok: false, code: "auth", retryable: false, effect: "none", message: "Browserbase refused this session type (403). Retry without `verified`, or use web_fetch.", detail };
|
|
50
|
+
if (facts.sessionEnded)
|
|
51
|
+
return { ok: false, code: "session_ended", retryable: true, effect, message: "The browser session ended (Browserbase closes a session at its timeout, or the browser died). Your next browser call opens a fresh session automatically; the old tabs, page state and cookies are gone — navigate to the page again with run, then continue from there.", detail };
|
|
52
|
+
if (facts.timedOut || fact.errorName === "TimeoutError")
|
|
53
|
+
return { ok: false, code: "timeout", retryable: true, effect, message: "The browser call timed out. Take a fresh snapshot before acting again; split a long `run` into smaller batches; if the page never loads, use web_fetch or another source.", detail };
|
|
54
|
+
if (isStaleSnapshot(own))
|
|
55
|
+
return { ok: false, code: "stale_snapshot", retryable: true, effect: "none", message, detail };
|
|
56
|
+
if ((fact.causeCode && UNREACHABLE_CAUSES.has(fact.causeCode)) || (fact.errorName && UNREACHABLE_NAMES.has(fact.errorName)))
|
|
57
|
+
return { ok: false, code: "browser_unavailable", retryable: false, effect, message: "The browser could not be reached on this lane. The browser plane is unavailable for this run; use web_fetch or executor tools.", detail };
|
|
58
|
+
return { ok: false, code: effectful ? "code_error" : "command_failed", retryable: true, effect, message: effectful ? `Your browser code threw: ${message.slice(0, 600)}` : `The browser call failed: ${message.slice(0, 600)}`, detail };
|
|
59
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import type { Decisions } from "./decisions.js";
|
|
2
|
+
export declare const FIND_CHUNK_CHARS = 2000;
|
|
3
|
+
export declare const FIND_MAX_RANKED = 200;
|
|
4
|
+
export declare const FIND_SHOWN_CHUNKS = 8;
|
|
5
|
+
export declare const FIND_SHOWN_CHARS = 8000;
|
|
6
|
+
export type Chunk = {
|
|
7
|
+
index: number;
|
|
8
|
+
text: string;
|
|
9
|
+
path: string[];
|
|
10
|
+
ids: string[];
|
|
11
|
+
};
|
|
12
|
+
/** Snapshot lines (` [0-14] link: Go to page B`, two spaces a level) cut into subtrees of at most `max` characters. */
|
|
13
|
+
export declare function chunkTree(tree: string, max?: number): Chunk[];
|
|
14
|
+
/** Sections under the headings (a `#` inside a code fence is not one); an oversize section is cut further. */
|
|
15
|
+
export declare function chunkPage(markdown: string, max?: number): Chunk[];
|
|
16
|
+
export type FindOptions = {
|
|
17
|
+
kind: "tree" | "page";
|
|
18
|
+
rank?: Decisions["rankChunks"];
|
|
19
|
+
filedAt?: string | null;
|
|
20
|
+
maxChars?: number;
|
|
21
|
+
shownChunks?: number;
|
|
22
|
+
shownChars?: number;
|
|
23
|
+
};
|
|
24
|
+
export type FindResult = {
|
|
25
|
+
text: string;
|
|
26
|
+
applied: boolean;
|
|
27
|
+
chunks: number;
|
|
28
|
+
shown: number[];
|
|
29
|
+
ids: string[];
|
|
30
|
+
};
|
|
31
|
+
/** Without a usable ranker the whole source comes back with a line saying find was not applied: never a silent cut. */
|
|
32
|
+
export declare function findInText(source: string, query: string, options: FindOptions): Promise<FindResult>;
|