@parcha/pi-browser 0.1.0-beta.30 → 0.1.0-beta.32
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 +52 -0
- package/NOTICE +4 -4
- package/README.md +41 -12
- package/dist/coding-agent.d.ts +1 -0
- package/dist/coding-agent.js +5 -4
- package/dist/core/contract.d.ts +9 -0
- package/dist/core/contract.js +15 -3
- 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 +17 -1
- package/dist/durable.js +41 -14
- 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
|
@@ -1,4 +1,6 @@
|
|
|
1
1
|
export declare const COPY = "stagehand-extension";
|
|
2
|
+
/** The name Stagehand's extension carries, which is how Stagehand finds it in a browser. */
|
|
3
|
+
export declare const STAGEHAND_EXTENSION = "Stagehand Runtime";
|
|
2
4
|
/** `<into>/stagehand-extension`, a copy of Stagehand's extension directory. */
|
|
3
5
|
export declare function copyExtension(into: string, source?: string): Promise<string>;
|
|
4
6
|
/** The policy for the extension's pages and worker: its own files, and the browser's DevTools socket by its whole URL path. A
|
|
@@ -12,3 +14,7 @@ export declare function loadConfined(copy: string, devtoolsUrl: string): Promise
|
|
|
12
14
|
/** Whether the browser already holds, enabled, the extension with this id: the one a copy's path implies, never another that
|
|
13
15
|
* merely carries Stagehand's name (an earlier, unconfined copy would be taken for the lease's own). */
|
|
14
16
|
export declare function isLoaded(devtoolsUrl: string, id: string): Promise<boolean>;
|
|
17
|
+
/** Stagehand finds its extension by name and refuses a browser that holds two enabled, so every other extension carrying that
|
|
18
|
+
* name (an earlier, unconfined copy) is uninstalled: the one Stagehand finds is then the lease's own copy, `id`. Disabled ones
|
|
19
|
+
* go too, so none can be enabled again beside it. */
|
|
20
|
+
export declare function soleStagehand(devtoolsUrl: string, id: string): Promise<void>;
|
|
@@ -8,6 +8,8 @@ import path from "node:path";
|
|
|
8
8
|
import { cdpCall } from "./cdp-call.js";
|
|
9
9
|
import { extensionDirectory, extensionOrigin } from "./chrome-args.js";
|
|
10
10
|
export const COPY = "stagehand-extension";
|
|
11
|
+
/** The name Stagehand's extension carries, which is how Stagehand finds it in a browser. */
|
|
12
|
+
export const STAGEHAND_EXTENSION = "Stagehand Runtime";
|
|
11
13
|
const LOAD_MS = 20_000;
|
|
12
14
|
/** `<into>/stagehand-extension`, a copy of Stagehand's extension directory. */
|
|
13
15
|
export async function copyExtension(into, source = extensionDirectory()) {
|
|
@@ -50,14 +52,25 @@ export async function loadConfined(copy, devtoolsUrl) {
|
|
|
50
52
|
session.close();
|
|
51
53
|
}
|
|
52
54
|
}
|
|
53
|
-
|
|
54
|
-
* merely carries Stagehand's name (an earlier, unconfined copy would be taken for the lease's own). */
|
|
55
|
-
export async function isLoaded(devtoolsUrl, id) {
|
|
55
|
+
const installed = async (devtoolsUrl) => {
|
|
56
56
|
const session = await cdpCall(devtoolsUrl, "Extensions.getExtensions", {}, LOAD_MS);
|
|
57
57
|
try {
|
|
58
|
-
return (session.result?.extensions ?? [])
|
|
58
|
+
return (session.result?.extensions ?? []);
|
|
59
59
|
}
|
|
60
60
|
finally {
|
|
61
61
|
session.close();
|
|
62
62
|
}
|
|
63
|
+
};
|
|
64
|
+
/** Whether the browser already holds, enabled, the extension with this id: the one a copy's path implies, never another that
|
|
65
|
+
* merely carries Stagehand's name (an earlier, unconfined copy would be taken for the lease's own). */
|
|
66
|
+
export async function isLoaded(devtoolsUrl, id) {
|
|
67
|
+
return (await installed(devtoolsUrl)).some((e) => e.id === id && e.enabled);
|
|
68
|
+
}
|
|
69
|
+
/** Stagehand finds its extension by name and refuses a browser that holds two enabled, so every other extension carrying that
|
|
70
|
+
* name (an earlier, unconfined copy) is uninstalled: the one Stagehand finds is then the lease's own copy, `id`. Disabled ones
|
|
71
|
+
* go too, so none can be enabled again beside it. */
|
|
72
|
+
export async function soleStagehand(devtoolsUrl, id) {
|
|
73
|
+
for (const other of (await installed(devtoolsUrl)).filter((e) => e.name === STAGEHAND_EXTENSION && e.id !== id)) {
|
|
74
|
+
(await cdpCall(devtoolsUrl, "Extensions.uninstall", { id: other.id }, LOAD_MS)).close();
|
|
75
|
+
}
|
|
63
76
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@parcha/pi-browser",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
3
|
+
"version": "0.1.0-beta.32",
|
|
4
4
|
"description": "Your agent gets its own browser, and you can take over and hand it back.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"pi-package",
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
"license": "Apache-2.0",
|
|
14
14
|
"author": "Parcha Labs, Inc.",
|
|
15
15
|
"engines": {
|
|
16
|
-
"node": ">=
|
|
16
|
+
"node": ">=24.11.0"
|
|
17
17
|
},
|
|
18
18
|
"exports": {
|
|
19
19
|
".": {
|
|
@@ -92,17 +92,18 @@
|
|
|
92
92
|
"verify:tarball": "node scripts/verify-tarball.mjs"
|
|
93
93
|
},
|
|
94
94
|
"dependencies": {
|
|
95
|
-
"@browserbasehq/stagehand": "~4.
|
|
95
|
+
"@browserbasehq/stagehand": "~4.4.0",
|
|
96
96
|
"node-html-markdown": "^2.0.0",
|
|
97
97
|
"node-html-parser": "^6.1.13",
|
|
98
|
+
"typebox": "1.3.27",
|
|
98
99
|
"undici": "^6.29.1",
|
|
99
100
|
"zod": "~4.6.6"
|
|
100
101
|
},
|
|
101
102
|
"peerDependencies": {
|
|
102
103
|
"@browserbasehq/sdk": ">=2.20.0 <3",
|
|
103
|
-
"@earendil-works/chord": "
|
|
104
|
+
"@earendil-works/chord": "1.5.0",
|
|
104
105
|
"@earendil-works/pi-coding-agent": "*",
|
|
105
|
-
"@earendil-works/pi-durable": "
|
|
106
|
+
"@earendil-works/pi-durable": "1.5.0"
|
|
106
107
|
},
|
|
107
108
|
"peerDependenciesMeta": {
|
|
108
109
|
"@browserbasehq/sdk": {
|
|
@@ -119,11 +120,10 @@
|
|
|
119
120
|
}
|
|
120
121
|
},
|
|
121
122
|
"devDependencies": {
|
|
122
|
-
"@earendil-works/chord": "1.
|
|
123
|
-
"@earendil-works/pi-ai": "1.
|
|
124
|
-
"@earendil-works/pi-coding-agent": "1.
|
|
125
|
-
"@earendil-works/pi-durable": "1.
|
|
126
|
-
"typebox": "1.3.7"
|
|
123
|
+
"@earendil-works/chord": "1.5.0",
|
|
124
|
+
"@earendil-works/pi-ai": "1.5.0",
|
|
125
|
+
"@earendil-works/pi-coding-agent": "1.5.0",
|
|
126
|
+
"@earendil-works/pi-durable": "1.5.0"
|
|
127
127
|
},
|
|
128
128
|
"repository": {
|
|
129
129
|
"type": "git",
|
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
export declare const STAGEHAND_EXTENSION = "Stagehand Runtime";
|
|
2
|
-
/** A held extension runtime keeps one Stagehand instance until that instance's close, which a dead process never sent,
|
|
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
|
-
* 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. A target list the browser does
|
|
6
|
-
* not give by DISCOVERY_MS is not a list without a worker: the attach fails. `replyMs`: how long the close waits for the
|
|
7
|
-
* runtime's reply. An init still running in the extension answers it only once that init ends, since the runtime runs
|
|
8
|
-
* both one after the other; the socket outlives the deadline by that much more. */
|
|
9
|
-
export declare function installedExtension(cdpUrl: string, signal?: AbortSignal, known?: string, replyMs?: number): Promise<string | null>;
|
|
@@ -1,185 +0,0 @@
|
|
|
1
|
-
export const STAGEHAND_EXTENSION = "Stagehand Runtime";
|
|
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;
|
|
5
|
-
const WAKE_TRIES = 60;
|
|
6
|
-
const CLOSE_REPLY_MS = 3_000;
|
|
7
|
-
const SEND_TO_HOST = "__stagehandSendToHost";
|
|
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
|
-
}
|
|
13
|
-
/** One attach's CDP socket, open for `lifeMs` at most and closed at once on an abort. A call settles empty when the
|
|
14
|
-
* browser does not answer within `ms` (the deadline, unless shorter), and every call settles empty once the socket
|
|
15
|
-
* closes (an abort, the browser, the end of its life). */
|
|
16
|
-
class Cdp {
|
|
17
|
-
deadline;
|
|
18
|
-
signal;
|
|
19
|
-
/** Settles when the socket opens; rejects when it fails to open or closes first. */
|
|
20
|
-
opened;
|
|
21
|
-
socket;
|
|
22
|
-
timer;
|
|
23
|
-
stop = () => this.socket.close();
|
|
24
|
-
pending = new Map();
|
|
25
|
-
listeners = new Set();
|
|
26
|
-
next = 0;
|
|
27
|
-
isClosed = false;
|
|
28
|
-
constructor(cdpUrl, deadline, lifeMs, signal) {
|
|
29
|
-
this.deadline = deadline;
|
|
30
|
-
this.signal = signal;
|
|
31
|
-
this.socket = new WebSocket(cdpUrl);
|
|
32
|
-
this.timer = setTimeout(() => this.socket.close(), lifeMs);
|
|
33
|
-
signal?.addEventListener("abort", this.stop, { once: true });
|
|
34
|
-
this.opened = new Promise((resolve, reject) => {
|
|
35
|
-
this.socket.onopen = () => resolve();
|
|
36
|
-
// A refused connection raises `error` and, on Node 22, never `close`: waiting for `close` alone would hang the attach.
|
|
37
|
-
this.socket.onerror = () => reject(new Error("Failed to open CDP WebSocket"));
|
|
38
|
-
this.socket.onclose = () => { this.onClose(); reject(new Error("the CDP socket closed")); };
|
|
39
|
-
this.socket.onmessage = (event) => this.onMessage(event.data);
|
|
40
|
-
});
|
|
41
|
-
}
|
|
42
|
-
/** A send on a closed socket neither throws nor is ever answered (Node 24): once closed, every call settles empty. */
|
|
43
|
-
call(method, params = {}, sessionId, ms = this.deadline - Date.now()) {
|
|
44
|
-
return new Promise((resolve) => {
|
|
45
|
-
if (this.isClosed || this.socket.readyState !== WebSocket.OPEN || ms <= 0)
|
|
46
|
-
return resolve(undefined);
|
|
47
|
-
const id = ++this.next;
|
|
48
|
-
const settle = (result) => { clearTimeout(wait); this.pending.delete(id); resolve(result); };
|
|
49
|
-
const wait = setTimeout(() => settle(undefined), ms);
|
|
50
|
-
this.pending.set(id, settle);
|
|
51
|
-
this.socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
|
|
52
|
-
});
|
|
53
|
-
}
|
|
54
|
-
listen(listener) { this.listeners.add(listener); }
|
|
55
|
-
closed() { return this.isClosed; }
|
|
56
|
-
end() { clearTimeout(this.timer); this.signal?.removeEventListener("abort", this.stop); this.socket.close(); }
|
|
57
|
-
onClose() {
|
|
58
|
-
this.isClosed = true;
|
|
59
|
-
for (const settle of [...this.pending.values()])
|
|
60
|
-
settle(undefined);
|
|
61
|
-
for (const listener of this.listeners)
|
|
62
|
-
listener({ method: "closed" });
|
|
63
|
-
}
|
|
64
|
-
/** A throw in a socket listener ends the process: a frame that is not JSON is dropped. */
|
|
65
|
-
onMessage(data) {
|
|
66
|
-
try {
|
|
67
|
-
const message = JSON.parse(String(data));
|
|
68
|
-
if (message?.id !== undefined)
|
|
69
|
-
this.pending.get(message.id)?.(message.result);
|
|
70
|
-
else if (message)
|
|
71
|
-
for (const listener of this.listeners)
|
|
72
|
-
listener(message);
|
|
73
|
-
}
|
|
74
|
-
catch { }
|
|
75
|
-
}
|
|
76
|
-
}
|
|
77
|
-
/** The one enabled Stagehand extension's id; null when there is none, or more than one. */
|
|
78
|
-
async function stagehandExtensionId(cdp) {
|
|
79
|
-
const extensions = (await cdp.call("Extensions.getExtensions"))?.extensions ?? [];
|
|
80
|
-
const enabled = extensions.filter((extension) => extension.name === STAGEHAND_EXTENSION && extension.enabled);
|
|
81
|
-
return enabled.length === 1 ? enabled[0].id : null;
|
|
82
|
-
}
|
|
83
|
-
/** The extension's workers; null when the browser gave no list, which is not a list without one. */
|
|
84
|
-
async function extensionWorkers(cdp, id) {
|
|
85
|
-
const infos = (await cdp.call("Target.getTargets"))?.targetInfos;
|
|
86
|
-
return infos?.filter((target) => target.type === "service_worker" && target.url.startsWith(`chrome-extension://${id}/`)).map((target) => target.targetId) ?? null;
|
|
87
|
-
}
|
|
88
|
-
/** With no worker running nothing is held, and the worker is woken until it is listed. Every wake page opened stays
|
|
89
|
-
* listed here until a close of it is answered. None is opened within CLEANUP_MS of the deadline, an opening's reply is
|
|
90
|
-
* awaited into the first half of that second, and the socket outlives the deadline by CLEANUP_MS, so the last pages are
|
|
91
|
-
* closed on it. */
|
|
92
|
-
async function wakeWorker(cdp, id, deadline) {
|
|
93
|
-
const wakes = new Set();
|
|
94
|
-
const closeWakes = async (ms) => { for (const page of [...wakes])
|
|
95
|
-
if ((await cdp.call("Target.closeTarget", { targetId: page }, undefined, ms)) !== undefined)
|
|
96
|
-
wakes.delete(page); };
|
|
97
|
-
for (let tries = 0; !cdp.closed() && Date.now() < deadline && tries < WAKE_TRIES && ((await extensionWorkers(cdp, id))?.length ?? 0) === 0; tries += 1) {
|
|
98
|
-
if (tries % 10 === 0 && deadline - Date.now() > CLEANUP_MS) {
|
|
99
|
-
await closeWakes();
|
|
100
|
-
const page = (await cdp.call("Target.createTarget", { url: `chrome-extension://${id}/wake-service-worker.html` }, undefined, deadline + CLEANUP_MS / 2 - Date.now()))?.targetId;
|
|
101
|
-
if (page)
|
|
102
|
-
wakes.add(page);
|
|
103
|
-
}
|
|
104
|
-
await new Promise((r) => setTimeout(r, 100));
|
|
105
|
-
}
|
|
106
|
-
await closeWakes(deadline + CLEANUP_MS - Date.now());
|
|
107
|
-
}
|
|
108
|
-
/** A binding call on `sessionId` that carries the reply to the close (its id is RESET_ID). */
|
|
109
|
-
function isResetReply(event, sessionId) {
|
|
110
|
-
if (event.method !== "Runtime.bindingCalled" || event.sessionId !== sessionId || event.params?.name !== SEND_TO_HOST)
|
|
111
|
-
return false;
|
|
112
|
-
try {
|
|
113
|
-
return JSON.parse(event.params.payload ?? "")?.id === RESET_ID;
|
|
114
|
-
}
|
|
115
|
-
catch {
|
|
116
|
-
return false;
|
|
117
|
-
}
|
|
118
|
-
}
|
|
119
|
-
/** Settles on the runtime's reply to the close, at once when the socket closes, and after `replyMs` at most. */
|
|
120
|
-
function resetReplied(cdp, sessionId, replyMs) {
|
|
121
|
-
return new Promise((resolve) => {
|
|
122
|
-
const wait = setTimeout(resolve, replyMs);
|
|
123
|
-
cdp.listen((event) => {
|
|
124
|
-
if (event.method === "closed" || isResetReply(event, sessionId)) {
|
|
125
|
-
clearTimeout(wait);
|
|
126
|
-
resolve();
|
|
127
|
-
}
|
|
128
|
-
});
|
|
129
|
-
});
|
|
130
|
-
}
|
|
131
|
-
/** The held runtime's close, sent through the worker's own RPC, and its reply awaited for up to `replyMs`; the worker
|
|
132
|
-
* keeps running. */
|
|
133
|
-
async function closeHeldRuntime(cdp, worker, replyMs) {
|
|
134
|
-
const sessionId = (await cdp.call("Target.attachToTarget", { targetId: worker, flatten: true }))?.sessionId;
|
|
135
|
-
if (!sessionId)
|
|
136
|
-
return;
|
|
137
|
-
try {
|
|
138
|
-
await cdp.call("Runtime.enable", {}, sessionId);
|
|
139
|
-
await cdp.call("Runtime.addBinding", { name: SEND_TO_HOST }, sessionId);
|
|
140
|
-
const replied = resetReplied(cdp, sessionId, replyMs);
|
|
141
|
-
const close = JSON.stringify({ jsonrpc: "2.0", id: RESET_ID, method: "stagehand.close", params: {} });
|
|
142
|
-
const sent = await cdp.call("Runtime.evaluate", { expression: `void globalThis.__stagehandReceiveFromHost(${JSON.stringify(close)}); true`, returnByValue: true }, sessionId);
|
|
143
|
-
if (sent && !sent.exceptionDetails)
|
|
144
|
-
await replied;
|
|
145
|
-
}
|
|
146
|
-
finally {
|
|
147
|
-
await cdp.call("Target.detachFromTarget", { sessionId });
|
|
148
|
-
}
|
|
149
|
-
}
|
|
150
|
-
/** A held extension runtime keeps one Stagehand instance until that instance's close, which a dead process never sent,
|
|
151
|
-
* so a new attach would be refused. The close is sent here through the worker's own RPC, and the worker keeps running:
|
|
152
|
-
* a worker closed under load is sometimes never restarted, and its attach waits out Stagehand's 60 s init deadline.
|
|
153
|
-
* With no worker running nothing is held, and the worker is woken until it is listed. A target list the browser does
|
|
154
|
-
* not give by DISCOVERY_MS is not a list without a worker: the attach fails. `replyMs`: how long the close waits for the
|
|
155
|
-
* runtime's reply. An init still running in the extension answers it only once that init ends, since the runtime runs
|
|
156
|
-
* both one after the other; the socket outlives the deadline by that much more. */
|
|
157
|
-
export async function installedExtension(cdpUrl, signal, known, replyMs = CLOSE_REPLY_MS) {
|
|
158
|
-
const deadline = Date.now() + DISCOVERY_MS;
|
|
159
|
-
const cdp = new Cdp(cdpUrl, deadline, DISCOVERY_MS + CLEANUP_MS - CLOSE_REPLY_MS + replyMs, signal);
|
|
160
|
-
try {
|
|
161
|
-
await cdp.opened;
|
|
162
|
-
const id = known || (await stagehandExtensionId(cdp));
|
|
163
|
-
if (!id)
|
|
164
|
-
return null;
|
|
165
|
-
const running = await extensionWorkers(cdp, id);
|
|
166
|
-
if (running === null) {
|
|
167
|
-
if (signal?.aborted || cdp.closed())
|
|
168
|
-
return id;
|
|
169
|
-
throw new TargetsUnlistedError();
|
|
170
|
-
}
|
|
171
|
-
if (running.length === 0)
|
|
172
|
-
await wakeWorker(cdp, id, deadline);
|
|
173
|
-
else
|
|
174
|
-
await closeHeldRuntime(cdp, running[0], replyMs);
|
|
175
|
-
return id;
|
|
176
|
-
}
|
|
177
|
-
catch (error) {
|
|
178
|
-
if (error instanceof TargetsUnlistedError)
|
|
179
|
-
throw error;
|
|
180
|
-
return known ?? null;
|
|
181
|
-
}
|
|
182
|
-
finally {
|
|
183
|
-
cdp.end();
|
|
184
|
-
}
|
|
185
|
-
}
|