turno-browser 0.2.0 → 0.4.0
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 +228 -0
- package/README.md +205 -16
- package/dist/act-model.d.ts +85 -0
- package/dist/act-model.js +116 -0
- package/dist/act.d.ts +37 -0
- package/dist/act.js +599 -0
- package/dist/api.d.ts +96 -0
- package/dist/api.js +88 -0
- package/dist/argv.d.ts +55 -3
- package/dist/argv.js +190 -10
- package/dist/batch.d.ts +19 -0
- package/dist/batch.js +148 -0
- package/dist/bench.d.ts +1 -1
- package/dist/bench.js +21 -5
- package/dist/bin/mcp.js +108 -12
- package/dist/captcha.d.ts +77 -0
- package/dist/captcha.js +333 -0
- package/dist/cdp-relay.d.ts +20 -0
- package/dist/cdp-relay.js +101 -0
- package/dist/chrome-features.d.ts +23 -0
- package/dist/chrome-features.js +44 -0
- package/dist/detectors.d.ts +11 -0
- package/dist/detectors.js +46 -4
- package/dist/diagnose.d.ts +45 -0
- package/dist/diagnose.js +326 -0
- package/dist/doctor.d.ts +85 -0
- package/dist/doctor.js +556 -0
- package/dist/engine-attach.d.ts +27 -0
- package/dist/engine-attach.js +165 -0
- package/dist/engine-camoufox.d.ts +32 -0
- package/dist/engine-camoufox.js +270 -0
- package/dist/engine-lightpanda.d.ts +72 -0
- package/dist/engine-lightpanda.js +292 -0
- package/dist/engine.d.ts +119 -0
- package/dist/engine.js +355 -0
- package/dist/flows.d.ts +127 -0
- package/dist/flows.js +294 -0
- package/dist/governor.d.ts +119 -0
- package/dist/governor.js +325 -0
- package/dist/health.d.ts +60 -0
- package/dist/health.js +86 -0
- package/dist/host.d.ts +95 -0
- package/dist/host.js +1181 -0
- package/dist/human-input.d.ts +84 -0
- package/dist/human-input.js +443 -0
- package/dist/humanize.d.ts +123 -0
- package/dist/humanize.js +241 -0
- package/dist/identities.d.ts +23 -10
- package/dist/identities.js +45 -37
- package/dist/idle-timer.d.ts +12 -0
- package/dist/idle-timer.js +25 -0
- package/dist/ids.d.ts +9 -0
- package/dist/ids.js +34 -0
- package/dist/index.d.ts +21 -6
- package/dist/index.js +19 -18
- package/dist/lifecycle.d.ts +99 -0
- package/dist/lifecycle.js +172 -0
- package/dist/live-client.d.ts +22 -0
- package/dist/live-client.js +93 -0
- package/dist/live-page.d.ts +11 -0
- package/dist/live-page.js +143 -0
- package/dist/live-server.d.ts +173 -0
- package/dist/live-server.js +640 -0
- package/dist/live.d.ts +120 -0
- package/dist/live.js +203 -0
- package/dist/login-tool.d.ts +45 -0
- package/dist/login-tool.js +233 -0
- package/dist/login.d.ts +8 -3
- package/dist/login.js +65 -26
- package/dist/network-chrome.d.ts +74 -0
- package/dist/network-chrome.js +178 -0
- package/dist/network.d.ts +125 -0
- package/dist/network.js +263 -0
- package/dist/opt-in-settings.d.ts +69 -0
- package/dist/opt-in-settings.js +151 -0
- package/dist/patchright.d.ts +4 -2
- package/dist/patchright.js +4 -2
- package/dist/recorder.d.ts +88 -0
- package/dist/recorder.js +538 -0
- package/dist/recordings.d.ts +116 -0
- package/dist/recordings.js +474 -0
- package/dist/redact.d.ts +34 -0
- package/dist/redact.js +135 -0
- package/dist/replay.d.ts +20 -0
- package/dist/replay.js +382 -0
- package/dist/reputation.d.ts +89 -0
- package/dist/reputation.js +203 -0
- package/dist/resources.d.ts +76 -0
- package/dist/resources.js +341 -0
- package/dist/runtime-lock.d.ts +59 -0
- package/dist/runtime-lock.js +131 -0
- package/dist/sealed.d.ts +8 -0
- package/dist/sealed.js +96 -0
- package/dist/session-export.d.ts +67 -0
- package/dist/session-export.js +194 -0
- package/dist/session.d.ts +20 -0
- package/dist/session.js +30 -0
- package/dist/settings.d.ts +246 -0
- package/dist/settings.js +530 -0
- package/dist/sharing.d.ts +96 -0
- package/dist/sharing.js +269 -0
- package/dist/snippet.d.ts +8 -0
- package/dist/snippet.js +22 -0
- package/dist/tab-locks.d.ts +63 -0
- package/dist/tab-locks.js +179 -0
- package/dist/tools.d.ts +111 -0
- package/dist/tools.js +59 -0
- package/dist/totp.d.ts +32 -0
- package/dist/totp.js +82 -0
- package/dist/tuning.d.ts +76 -0
- package/dist/tuning.js +69 -0
- package/dist/units.d.ts +8 -0
- package/dist/units.js +20 -0
- package/dist/upstream.d.ts +243 -0
- package/dist/upstream.js +46 -0
- package/dist/vault.d.ts +91 -0
- package/dist/vault.js +273 -0
- package/npm-shrinkwrap.json +1074 -3
- package/package.json +5 -4
- package/dist/paths.d.ts +0 -17
- package/dist/paths.js +0 -17
package/dist/sharing.js
ADDED
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
import { DIRECT_SESSION, TabLockedError, TabLocks, sessionLabel } from "./tab-locks.js";
|
|
2
|
+
import { backendContext, } from "./upstream.js";
|
|
3
|
+
/**
|
|
4
|
+
* The config of a session's backend: the root's, without what upstream installs on the browser
|
|
5
|
+
* context for each backend (init scripts, the init page module, the allowed and blocked origin
|
|
6
|
+
* routes). The root installed them already and keeps them for the life of the browser.
|
|
7
|
+
*/
|
|
8
|
+
export function viewConfig(config) {
|
|
9
|
+
const c = config;
|
|
10
|
+
const { initScript: _script, initPage: _page, ...browser } = c.browser;
|
|
11
|
+
const out = {
|
|
12
|
+
...config,
|
|
13
|
+
browser,
|
|
14
|
+
timeouts: { ...config.timeouts },
|
|
15
|
+
snapshot: { ...config.snapshot },
|
|
16
|
+
};
|
|
17
|
+
if (c.network) {
|
|
18
|
+
const { allowedOrigins: _allowed, blockedOrigins: _blocked, ...network } = c.network;
|
|
19
|
+
out.network = network;
|
|
20
|
+
}
|
|
21
|
+
return out;
|
|
22
|
+
}
|
|
23
|
+
function shortUrl(url) {
|
|
24
|
+
return url.length > 100 ? `${url.slice(0, 97)}...` : url;
|
|
25
|
+
}
|
|
26
|
+
export class TabSharing {
|
|
27
|
+
options;
|
|
28
|
+
locks;
|
|
29
|
+
views = new Map();
|
|
30
|
+
ready = new Map();
|
|
31
|
+
/** The tab each session last worked on. */
|
|
32
|
+
working = new Map();
|
|
33
|
+
watched = new WeakSet();
|
|
34
|
+
disposed = false;
|
|
35
|
+
constructor(options) {
|
|
36
|
+
this.options = options;
|
|
37
|
+
this.locks = new TabLocks(options.policy, options.now);
|
|
38
|
+
this.views.set(DIRECT_SESSION, Promise.resolve(options.root));
|
|
39
|
+
this.ready.set(DIRECT_SESSION, options.root);
|
|
40
|
+
}
|
|
41
|
+
/** The backend of `session`, created on its first call (`DIRECT_SESSION`: the root). */
|
|
42
|
+
view(session) {
|
|
43
|
+
if (this.disposed)
|
|
44
|
+
return Promise.reject(new Error("the browser closed"));
|
|
45
|
+
const existing = this.views.get(session);
|
|
46
|
+
if (existing)
|
|
47
|
+
return existing;
|
|
48
|
+
const slot = {};
|
|
49
|
+
const created = (async () => {
|
|
50
|
+
const v = await this.options.createView();
|
|
51
|
+
await backendContext(v.backend)?.ensureBrowserContext();
|
|
52
|
+
// Dropped while it was being made (the session ended, the browser closed): not needed.
|
|
53
|
+
if (this.views.get(session) === slot.promise)
|
|
54
|
+
this.ready.set(session, v);
|
|
55
|
+
else
|
|
56
|
+
void v.backend.dispose().catch(() => { });
|
|
57
|
+
return v;
|
|
58
|
+
})();
|
|
59
|
+
slot.promise = created;
|
|
60
|
+
created.catch(() => {
|
|
61
|
+
if (this.views.get(session) === created)
|
|
62
|
+
this.views.delete(session);
|
|
63
|
+
});
|
|
64
|
+
this.views.set(session, created);
|
|
65
|
+
return created;
|
|
66
|
+
}
|
|
67
|
+
/** The tabs as one session's backend sees them, for the tab governor. */
|
|
68
|
+
tabView(view) {
|
|
69
|
+
return {
|
|
70
|
+
current: () => backendContext(view.backend)?.currentTab()?.page,
|
|
71
|
+
tabs: () => backendContext(view.backend)
|
|
72
|
+
?.tabs()
|
|
73
|
+
.map((t) => t.page) ?? [],
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
/** Who holds a page, for the tab governor's cap. */
|
|
77
|
+
owner(page) {
|
|
78
|
+
return this.locks.holder(page);
|
|
79
|
+
}
|
|
80
|
+
/** Every page a session works on now: the governor never parks or closes them. */
|
|
81
|
+
protectedPages() {
|
|
82
|
+
const out = new Set();
|
|
83
|
+
for (const [session, page] of this.working)
|
|
84
|
+
if (this.locks.active(session) && !page.isClosed())
|
|
85
|
+
out.add(page);
|
|
86
|
+
for (const view of this.ready.values()) {
|
|
87
|
+
const page = backendContext(view.backend)?.currentTab()?.page;
|
|
88
|
+
if (page && !page.isClosed())
|
|
89
|
+
out.add(page);
|
|
90
|
+
}
|
|
91
|
+
return [...out];
|
|
92
|
+
}
|
|
93
|
+
/** A page Chrome opened: a popup belongs to the session that holds its opener. */
|
|
94
|
+
async adopt(page) {
|
|
95
|
+
const opener = await page.opener().catch(() => null);
|
|
96
|
+
if (!opener)
|
|
97
|
+
return;
|
|
98
|
+
const holder = this.locks.holder(opener);
|
|
99
|
+
if (holder !== undefined)
|
|
100
|
+
this.claim(holder, page);
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* Before a stock call of `session`: points its backend at its own tab and locks the tab the call
|
|
104
|
+
* acts on. Returns the error for the call when another session holds that tab past the wait.
|
|
105
|
+
*/
|
|
106
|
+
async before(session, name, args, view, signal) {
|
|
107
|
+
const ctx = backendContext(view.backend);
|
|
108
|
+
if (!ctx)
|
|
109
|
+
return undefined;
|
|
110
|
+
await ctx.ensureBrowserContext();
|
|
111
|
+
this.prune(session);
|
|
112
|
+
if (name === "browser_tabs") {
|
|
113
|
+
const index = typeof args.index === "number" ? args.index : undefined;
|
|
114
|
+
if ((args.action === "select" || args.action === "close") && index !== undefined) {
|
|
115
|
+
const target = ctx.tabs()[index]?.page;
|
|
116
|
+
// A missing index is upstream's error ("Tab 7 not found").
|
|
117
|
+
return target ? await this.lock(session, ctx, target, signal) : undefined;
|
|
118
|
+
}
|
|
119
|
+
if (args.action === "new")
|
|
120
|
+
return undefined;
|
|
121
|
+
}
|
|
122
|
+
const page = this.pick(session, ctx) ?? (await ctx.newTab()).page;
|
|
123
|
+
this.select(ctx, page);
|
|
124
|
+
return await this.lock(session, ctx, page, signal);
|
|
125
|
+
}
|
|
126
|
+
/** After a call of `session`: the tab its backend now points at is its own. */
|
|
127
|
+
after(session, view) {
|
|
128
|
+
const ctx = backendContext(view.backend);
|
|
129
|
+
if (!ctx)
|
|
130
|
+
return;
|
|
131
|
+
const page = ctx.currentTab()?.page;
|
|
132
|
+
if (page && !page.isClosed() && this.claim(session, page)) {
|
|
133
|
+
this.working.set(session, page);
|
|
134
|
+
return;
|
|
135
|
+
}
|
|
136
|
+
// Upstream moved the backend to another session's tab (its own tab closed): go back to one of
|
|
137
|
+
// the session's own, or to none, so the next call opens one.
|
|
138
|
+
const own = this.locks.pagesOf(session).find((p) => !p.isClosed());
|
|
139
|
+
if (own) {
|
|
140
|
+
this.select(ctx, own);
|
|
141
|
+
this.working.set(session, own);
|
|
142
|
+
}
|
|
143
|
+
else {
|
|
144
|
+
this.working.delete(session);
|
|
145
|
+
if (page)
|
|
146
|
+
ctx._setCurrentTab(undefined);
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
/** `browser_close` of one session: closes its tabs and lets go of them; the browser stays. */
|
|
150
|
+
async close(session) {
|
|
151
|
+
const pages = this.locks.releaseSession(session).filter((p) => !p.isClosed());
|
|
152
|
+
for (const page of pages)
|
|
153
|
+
await page.close().catch(() => { });
|
|
154
|
+
this.working.delete(session);
|
|
155
|
+
await this.dropView(session);
|
|
156
|
+
const n = pages.length;
|
|
157
|
+
return {
|
|
158
|
+
content: [
|
|
159
|
+
{
|
|
160
|
+
type: "text",
|
|
161
|
+
text: `### Result\nClosed ${n} tab${n === 1 ? "" : "s"} of this session. The browser stays open for the other agent sessions that share it ("sharing": "tabs").`,
|
|
162
|
+
},
|
|
163
|
+
],
|
|
164
|
+
};
|
|
165
|
+
}
|
|
166
|
+
/** mcpd said the session ended: its tabs are free (they stay open; the tab governor parks and closes them). */
|
|
167
|
+
async endSession(session) {
|
|
168
|
+
this.locks.releaseSession(session);
|
|
169
|
+
this.working.delete(session);
|
|
170
|
+
await this.dropView(session);
|
|
171
|
+
}
|
|
172
|
+
/** Marks, in a tab list of a result, the tabs other sessions hold. */
|
|
173
|
+
annotate(text, session, view) {
|
|
174
|
+
if (!/^- \d+: /m.test(text))
|
|
175
|
+
return text;
|
|
176
|
+
const ctx = backendContext(view.backend);
|
|
177
|
+
if (!ctx)
|
|
178
|
+
return text;
|
|
179
|
+
const tabs = ctx.tabs();
|
|
180
|
+
return text.replace(/^- (\d+): .*$/gm, (line, index) => {
|
|
181
|
+
const page = tabs[Number(index)]?.page;
|
|
182
|
+
const holder = page ? this.locks.holder(page) : undefined;
|
|
183
|
+
return holder !== undefined && holder !== session ? `${line} (in use by ${sessionLabel(holder)})` : line;
|
|
184
|
+
});
|
|
185
|
+
}
|
|
186
|
+
/** The browser closed: every session's backend goes (the root is the host's). */
|
|
187
|
+
dispose() {
|
|
188
|
+
if (this.disposed)
|
|
189
|
+
return;
|
|
190
|
+
this.disposed = true;
|
|
191
|
+
for (const [session, view] of this.views) {
|
|
192
|
+
if (session === DIRECT_SESSION)
|
|
193
|
+
continue;
|
|
194
|
+
void view.then((v) => v.backend.dispose()).catch(() => { });
|
|
195
|
+
}
|
|
196
|
+
this.views.clear();
|
|
197
|
+
this.ready.clear();
|
|
198
|
+
this.working.clear();
|
|
199
|
+
}
|
|
200
|
+
/** The tab `session` should act on, or undefined when it needs a new one. */
|
|
201
|
+
pick(session, ctx) {
|
|
202
|
+
const usable = (p) => {
|
|
203
|
+
if (!p || p.isClosed())
|
|
204
|
+
return false;
|
|
205
|
+
const holder = this.locks.holder(p);
|
|
206
|
+
return holder === undefined || holder === session;
|
|
207
|
+
};
|
|
208
|
+
const working = this.working.get(session);
|
|
209
|
+
if (usable(working))
|
|
210
|
+
return working;
|
|
211
|
+
const own = this.locks.pagesOf(session).find((p) => !p.isClosed());
|
|
212
|
+
if (own)
|
|
213
|
+
return own;
|
|
214
|
+
const current = ctx.currentTab()?.page;
|
|
215
|
+
return usable(current) ? current : undefined;
|
|
216
|
+
}
|
|
217
|
+
/** Points the backend at `page` without bringing it to the front. */
|
|
218
|
+
select(ctx, page) {
|
|
219
|
+
if (ctx.currentTab()?.page === page)
|
|
220
|
+
return;
|
|
221
|
+
const tab = ctx.tabs().find((t) => t.page === page);
|
|
222
|
+
if (tab)
|
|
223
|
+
ctx._setCurrentTab(tab);
|
|
224
|
+
}
|
|
225
|
+
async lock(session, ctx, page, signal) {
|
|
226
|
+
const index = ctx.tabs().findIndex((t) => t.page === page);
|
|
227
|
+
const what = `tab ${index} (${shortUrl(page.url())})`;
|
|
228
|
+
try {
|
|
229
|
+
await this.locks.acquire(session, page, what, signal);
|
|
230
|
+
}
|
|
231
|
+
catch (error) {
|
|
232
|
+
if (error instanceof TabLockedError)
|
|
233
|
+
return error.message;
|
|
234
|
+
throw error;
|
|
235
|
+
}
|
|
236
|
+
this.watch(page);
|
|
237
|
+
return undefined;
|
|
238
|
+
}
|
|
239
|
+
claim(session, page) {
|
|
240
|
+
if (!this.locks.claim(session, page))
|
|
241
|
+
return false;
|
|
242
|
+
this.watch(page);
|
|
243
|
+
return true;
|
|
244
|
+
}
|
|
245
|
+
watch(page) {
|
|
246
|
+
if (this.watched.has(page))
|
|
247
|
+
return;
|
|
248
|
+
this.watched.add(page);
|
|
249
|
+
page.once("close", () => this.locks.release(page));
|
|
250
|
+
}
|
|
251
|
+
/** Backends of sessions that lapsed (no call for `releaseMs`) go; a new call makes a new one. */
|
|
252
|
+
prune(caller) {
|
|
253
|
+
for (const session of [...this.ready.keys()]) {
|
|
254
|
+
if (session === DIRECT_SESSION || session === caller || this.locks.active(session))
|
|
255
|
+
continue;
|
|
256
|
+
void this.dropView(session);
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
async dropView(session) {
|
|
260
|
+
if (session === DIRECT_SESSION)
|
|
261
|
+
return;
|
|
262
|
+
const view = this.views.get(session);
|
|
263
|
+
this.views.delete(session);
|
|
264
|
+
this.ready.delete(session);
|
|
265
|
+
if (view)
|
|
266
|
+
await view.then((v) => v.backend.dispose()).catch(() => { });
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
//# sourceMappingURL=sharing.js.map
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The mcp.toml block that serves one identity through mcpd. By default one agent session at a
|
|
3
|
+
* time (`exclusive = true`); with `sharing: "tabs"` every session at once (`exclusive = false`),
|
|
4
|
+
* each in its own tabs, which turno-browser locks (identity.json `"sharing": "tabs"`).
|
|
5
|
+
*/
|
|
6
|
+
export declare function manifestSnippet(id: string, options?: {
|
|
7
|
+
sharing?: "session" | "tabs";
|
|
8
|
+
}): string;
|
package/dist/snippet.js
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { assertIdentityId } from "./ids.js";
|
|
2
|
+
/**
|
|
3
|
+
* The mcp.toml block that serves one identity through mcpd. By default one agent session at a
|
|
4
|
+
* time (`exclusive = true`); with `sharing: "tabs"` every session at once (`exclusive = false`),
|
|
5
|
+
* each in its own tabs, which turno-browser locks (identity.json `"sharing": "tabs"`).
|
|
6
|
+
*/
|
|
7
|
+
export function manifestSnippet(id, options = {}) {
|
|
8
|
+
assertIdentityId(id);
|
|
9
|
+
const shared = options.sharing === "tabs";
|
|
10
|
+
return [
|
|
11
|
+
`[server.browser-${id}]`,
|
|
12
|
+
`command = "turno-browser-mcp"`,
|
|
13
|
+
`args = ["--identity", "${id}"]`,
|
|
14
|
+
`scope = "shared"`,
|
|
15
|
+
...(shared
|
|
16
|
+
? ["exclusive = false # every agent session at once, each in its own tabs"]
|
|
17
|
+
: ["exclusive = true", `lease = "10m"`]),
|
|
18
|
+
`idle = "30m"`,
|
|
19
|
+
"",
|
|
20
|
+
].join("\n");
|
|
21
|
+
}
|
|
22
|
+
//# sourceMappingURL=snippet.js.map
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Per-tab locks for an identity whose browser several agent sessions share (`"sharing": "tabs"`).
|
|
3
|
+
*
|
|
4
|
+
* A session holds every tab it works on: the tab its calls act on, the tabs it opened or selected,
|
|
5
|
+
* and the popups those tabs opened. Another session's call on a held tab waits up to `waitMs` for
|
|
6
|
+
* it and then fails with a message that names the holder. A session lets go of its tabs when
|
|
7
|
+
* mcpd says it ended, when a tab closes, and when it makes no call for `releaseMs` (a session that
|
|
8
|
+
* died without a word frees its tabs on its own). A call in flight always keeps its session's
|
|
9
|
+
* tabs, however long it runs.
|
|
10
|
+
*
|
|
11
|
+
* Generic over the page type so the rules are tested without a browser.
|
|
12
|
+
*/
|
|
13
|
+
export interface TabLockPolicy {
|
|
14
|
+
/** How long a call waits for a tab another session holds before it fails. */
|
|
15
|
+
waitMs: number;
|
|
16
|
+
/** A session that makes no call for this long holds nothing; 0: tabs are free between calls. */
|
|
17
|
+
releaseMs: number;
|
|
18
|
+
}
|
|
19
|
+
/** The defaults, documented on the browser identities page. */
|
|
20
|
+
export declare const DEFAULT_TAB_LOCKS: Readonly<TabLockPolicy>;
|
|
21
|
+
/** The lock key of calls that came without a session id (a client connected without mcpd). */
|
|
22
|
+
export declare const DIRECT_SESSION = "";
|
|
23
|
+
/** A call refused because another session holds the tab. */
|
|
24
|
+
export declare class TabLockedError extends Error {
|
|
25
|
+
name: string;
|
|
26
|
+
}
|
|
27
|
+
/** A short, readable name for a session in a message: the start of mcpd's opaque id. */
|
|
28
|
+
export declare function sessionLabel(session: string): string;
|
|
29
|
+
export declare class TabLocks<P extends object> {
|
|
30
|
+
readonly policy: TabLockPolicy;
|
|
31
|
+
private readonly holds;
|
|
32
|
+
private readonly sessions;
|
|
33
|
+
private readonly waiters;
|
|
34
|
+
private readonly now;
|
|
35
|
+
constructor(policy: TabLockPolicy, now?: () => number);
|
|
36
|
+
/** A call of `session` starts: until it ends, the session keeps every tab it holds. */
|
|
37
|
+
begin(session: string, tool: string): void;
|
|
38
|
+
/** A call of `session` ended. */
|
|
39
|
+
end(session: string): void;
|
|
40
|
+
/** Whether the session still holds its tabs: a call in flight, or one within `releaseMs`. */
|
|
41
|
+
active(session: string): boolean;
|
|
42
|
+
/** The session that holds `page`, or undefined when it is free. A lapsed session holds nothing. */
|
|
43
|
+
holder(page: P): string | undefined;
|
|
44
|
+
/** Takes `page` for `session` when it is free or already its own; false when another holds it. */
|
|
45
|
+
claim(session: string, page: P): boolean;
|
|
46
|
+
/**
|
|
47
|
+
* Takes `page` for `session`, waiting up to `waitMs` while another session holds it. Throws a
|
|
48
|
+
* `TabLockedError` whose message says which tab (`describe`), who holds it and what to do.
|
|
49
|
+
*/
|
|
50
|
+
acquire(session: string, page: P, describe: string, signal?: AbortSignal): Promise<void>;
|
|
51
|
+
/** The tab closed: nobody holds it. */
|
|
52
|
+
release(page: P): void;
|
|
53
|
+
/** Lets go of every tab of `session` and forgets it; returns the tabs it held. */
|
|
54
|
+
releaseSession(session: string): P[];
|
|
55
|
+
/** The tabs `session` holds, most recently used first. */
|
|
56
|
+
pagesOf(session: string): P[];
|
|
57
|
+
/** "session 3f2a9c1b (last call browser_click 12 s ago)". */
|
|
58
|
+
describeHolder(session: string): string;
|
|
59
|
+
private lockedMessage;
|
|
60
|
+
private state;
|
|
61
|
+
private wake;
|
|
62
|
+
private sleep;
|
|
63
|
+
}
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Per-tab locks for an identity whose browser several agent sessions share (`"sharing": "tabs"`).
|
|
3
|
+
*
|
|
4
|
+
* A session holds every tab it works on: the tab its calls act on, the tabs it opened or selected,
|
|
5
|
+
* and the popups those tabs opened. Another session's call on a held tab waits up to `waitMs` for
|
|
6
|
+
* it and then fails with a message that names the holder. A session lets go of its tabs when
|
|
7
|
+
* mcpd says it ended, when a tab closes, and when it makes no call for `releaseMs` (a session that
|
|
8
|
+
* died without a word frees its tabs on its own). A call in flight always keeps its session's
|
|
9
|
+
* tabs, however long it runs.
|
|
10
|
+
*
|
|
11
|
+
* Generic over the page type so the rules are tested without a browser.
|
|
12
|
+
*/
|
|
13
|
+
/** The defaults, documented on the browser identities page. */
|
|
14
|
+
export const DEFAULT_TAB_LOCKS = Object.freeze({ waitMs: 10_000, releaseMs: 5 * 60_000 });
|
|
15
|
+
/** The lock key of calls that came without a session id (a client connected without mcpd). */
|
|
16
|
+
export const DIRECT_SESSION = "";
|
|
17
|
+
/** A call refused because another session holds the tab. */
|
|
18
|
+
export class TabLockedError extends Error {
|
|
19
|
+
name = "TabLockedError";
|
|
20
|
+
}
|
|
21
|
+
/** A short, readable name for a session in a message: the start of mcpd's opaque id. */
|
|
22
|
+
export function sessionLabel(session) {
|
|
23
|
+
return session === DIRECT_SESSION ? "the client connected without mcpd" : `session ${session.slice(0, 8)}`;
|
|
24
|
+
}
|
|
25
|
+
function ago(ms) {
|
|
26
|
+
if (ms < 60_000)
|
|
27
|
+
return `${Math.max(0, Math.round(ms / 1000))} s ago`;
|
|
28
|
+
return `${Math.round(ms / 60_000)} min ago`;
|
|
29
|
+
}
|
|
30
|
+
function seconds(ms) {
|
|
31
|
+
const s = Math.round(ms / 100) / 10;
|
|
32
|
+
return s === 1 ? "1 second" : `${s} seconds`;
|
|
33
|
+
}
|
|
34
|
+
export class TabLocks {
|
|
35
|
+
policy;
|
|
36
|
+
holds = new Map();
|
|
37
|
+
sessions = new Map();
|
|
38
|
+
waiters = new Set();
|
|
39
|
+
now;
|
|
40
|
+
constructor(policy, now = Date.now) {
|
|
41
|
+
this.policy = policy;
|
|
42
|
+
this.now = now;
|
|
43
|
+
}
|
|
44
|
+
/** A call of `session` starts: until it ends, the session keeps every tab it holds. */
|
|
45
|
+
begin(session, tool) {
|
|
46
|
+
const s = this.state(session);
|
|
47
|
+
s.calls++;
|
|
48
|
+
s.lastTool = tool;
|
|
49
|
+
s.lastSeen = this.now();
|
|
50
|
+
}
|
|
51
|
+
/** A call of `session` ended. */
|
|
52
|
+
end(session) {
|
|
53
|
+
const s = this.sessions.get(session);
|
|
54
|
+
if (!s)
|
|
55
|
+
return;
|
|
56
|
+
s.calls = Math.max(0, s.calls - 1);
|
|
57
|
+
s.lastSeen = this.now();
|
|
58
|
+
this.wake();
|
|
59
|
+
}
|
|
60
|
+
/** Whether the session still holds its tabs: a call in flight, or one within `releaseMs`. */
|
|
61
|
+
active(session) {
|
|
62
|
+
const s = this.sessions.get(session);
|
|
63
|
+
if (!s)
|
|
64
|
+
return false;
|
|
65
|
+
return s.calls > 0 || this.now() - s.lastSeen < this.policy.releaseMs;
|
|
66
|
+
}
|
|
67
|
+
/** The session that holds `page`, or undefined when it is free. A lapsed session holds nothing. */
|
|
68
|
+
holder(page) {
|
|
69
|
+
const hold = this.holds.get(page);
|
|
70
|
+
if (!hold)
|
|
71
|
+
return undefined;
|
|
72
|
+
if (this.active(hold.session))
|
|
73
|
+
return hold.session;
|
|
74
|
+
this.releaseSession(hold.session);
|
|
75
|
+
return undefined;
|
|
76
|
+
}
|
|
77
|
+
/** Takes `page` for `session` when it is free or already its own; false when another holds it. */
|
|
78
|
+
claim(session, page) {
|
|
79
|
+
const holder = this.holder(page);
|
|
80
|
+
if (holder !== undefined && holder !== session)
|
|
81
|
+
return false;
|
|
82
|
+
this.state(session);
|
|
83
|
+
this.holds.set(page, { session, lastUsed: this.now() });
|
|
84
|
+
return true;
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Takes `page` for `session`, waiting up to `waitMs` while another session holds it. Throws a
|
|
88
|
+
* `TabLockedError` whose message says which tab (`describe`), who holds it and what to do.
|
|
89
|
+
*/
|
|
90
|
+
async acquire(session, page, describe, signal) {
|
|
91
|
+
const deadline = this.now() + this.policy.waitMs;
|
|
92
|
+
for (;;) {
|
|
93
|
+
if (this.claim(session, page))
|
|
94
|
+
return;
|
|
95
|
+
const holder = this.holder(page);
|
|
96
|
+
if (holder === undefined)
|
|
97
|
+
continue;
|
|
98
|
+
const left = deadline - this.now();
|
|
99
|
+
if (left <= 0 || signal?.aborted)
|
|
100
|
+
throw new TabLockedError(this.lockedMessage(holder, describe));
|
|
101
|
+
const st = this.sessions.get(holder);
|
|
102
|
+
// Wake when the holder lapses, a lock is released or a call ends, or the wait is over.
|
|
103
|
+
const lapse = st && st.calls === 0 ? st.lastSeen + this.policy.releaseMs - this.now() : left;
|
|
104
|
+
await this.sleep(Math.max(1, Math.min(left, lapse)), signal);
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
/** The tab closed: nobody holds it. */
|
|
108
|
+
release(page) {
|
|
109
|
+
if (this.holds.delete(page))
|
|
110
|
+
this.wake();
|
|
111
|
+
}
|
|
112
|
+
/** Lets go of every tab of `session` and forgets it; returns the tabs it held. */
|
|
113
|
+
releaseSession(session) {
|
|
114
|
+
const released = [];
|
|
115
|
+
for (const [page, hold] of this.holds) {
|
|
116
|
+
if (hold.session !== session)
|
|
117
|
+
continue;
|
|
118
|
+
this.holds.delete(page);
|
|
119
|
+
released.push(page);
|
|
120
|
+
}
|
|
121
|
+
const s = this.sessions.get(session);
|
|
122
|
+
if (s && s.calls === 0)
|
|
123
|
+
this.sessions.delete(session);
|
|
124
|
+
if (released.length)
|
|
125
|
+
this.wake();
|
|
126
|
+
return released;
|
|
127
|
+
}
|
|
128
|
+
/** The tabs `session` holds, most recently used first. */
|
|
129
|
+
pagesOf(session) {
|
|
130
|
+
if (!this.active(session))
|
|
131
|
+
return [];
|
|
132
|
+
return [...this.holds]
|
|
133
|
+
.filter(([, h]) => h.session === session)
|
|
134
|
+
.sort(([, a], [, b]) => b.lastUsed - a.lastUsed)
|
|
135
|
+
.map(([page]) => page);
|
|
136
|
+
}
|
|
137
|
+
/** "session 3f2a9c1b (last call browser_click 12 s ago)". */
|
|
138
|
+
describeHolder(session) {
|
|
139
|
+
const s = this.sessions.get(session);
|
|
140
|
+
if (!s)
|
|
141
|
+
return sessionLabel(session);
|
|
142
|
+
const doing = s.calls > 0 ? `running ${s.lastTool}` : `last call ${s.lastTool} ${ago(this.now() - s.lastSeen)}`;
|
|
143
|
+
return `${sessionLabel(session)} (${doing})`;
|
|
144
|
+
}
|
|
145
|
+
lockedMessage(holder, describe) {
|
|
146
|
+
const release = this.policy.releaseMs > 0
|
|
147
|
+
? `it is released when that session ends or after ${seconds(this.policy.releaseMs)} without a call`
|
|
148
|
+
: "it is released when that session's call ends";
|
|
149
|
+
return (`${describe} is in use by another agent session, ${this.describeHolder(holder)}; ` +
|
|
150
|
+
`waited ${seconds(this.policy.waitMs)} for it (${release}). ` +
|
|
151
|
+
`Work in a tab of your own: browser_tabs with action "new" opens one, and action "list" shows which tabs are taken.`);
|
|
152
|
+
}
|
|
153
|
+
state(session) {
|
|
154
|
+
let s = this.sessions.get(session);
|
|
155
|
+
if (!s) {
|
|
156
|
+
s = { lastSeen: this.now(), calls: 0 };
|
|
157
|
+
this.sessions.set(session, s);
|
|
158
|
+
}
|
|
159
|
+
return s;
|
|
160
|
+
}
|
|
161
|
+
wake() {
|
|
162
|
+
for (const w of [...this.waiters])
|
|
163
|
+
w();
|
|
164
|
+
}
|
|
165
|
+
sleep(ms, signal) {
|
|
166
|
+
return new Promise((resolve) => {
|
|
167
|
+
const done = () => {
|
|
168
|
+
clearTimeout(timer);
|
|
169
|
+
this.waiters.delete(done);
|
|
170
|
+
signal?.removeEventListener("abort", done);
|
|
171
|
+
resolve();
|
|
172
|
+
};
|
|
173
|
+
const timer = setTimeout(done, ms);
|
|
174
|
+
this.waiters.add(done);
|
|
175
|
+
signal?.addEventListener("abort", done, { once: true });
|
|
176
|
+
});
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
//# sourceMappingURL=tab-locks.js.map
|
package/dist/tools.d.ts
ADDED
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
import type { BrowserContext, Page } from "patchright-core";
|
|
2
|
+
import type { ActModel, Sampler } from "./act-model.js";
|
|
3
|
+
import { type CaptchaSolver } from "./captcha.js";
|
|
4
|
+
import { type VaultAccess } from "./login-tool.js";
|
|
5
|
+
import { type FlowRecorder } from "./recorder.js";
|
|
6
|
+
import { type ClientInfo, type McpConfig, type ToolResult, type ToolSchema, type UpstreamTool, type Zod, type ZodObject } from "./upstream.js";
|
|
7
|
+
/**
|
|
8
|
+
* The turno tool registry. A turno tool is listed after the stock Playwright MCP
|
|
9
|
+
* tools and called by the host itself; stock tools keep going to upstream's `BrowserBackend`.
|
|
10
|
+
*
|
|
11
|
+
* Rules, checked when the host starts and by the contract test:
|
|
12
|
+
*
|
|
13
|
+
* - A turno tool never takes the name of an upstream tool, whatever its capability, so a stock
|
|
14
|
+
* tool name always means the stock tool. An upgrade of patchright-core that adds a
|
|
15
|
+
* tool with the same name fails the contract test, not a user's session.
|
|
16
|
+
* - Names are unique and match `^[a-z][a-z0-9_]*$`.
|
|
17
|
+
* - The input schema is a zod object of the bundled zod (`turnoZod()`), so `tools/list` renders
|
|
18
|
+
* it exactly like a stock tool's and arguments are validated the same way.
|
|
19
|
+
*/
|
|
20
|
+
/** The session's stock tools, for a turno tool that runs them (`browser_batch`). */
|
|
21
|
+
export interface StockAccess {
|
|
22
|
+
/** Input schema of each stock tool this session lists. */
|
|
23
|
+
schemas: ReadonlyMap<string, ZodObject>;
|
|
24
|
+
/** A zod error as upstream words it. */
|
|
25
|
+
formatError(error: unknown): string;
|
|
26
|
+
/**
|
|
27
|
+
* Runs a stock tool the way a call of its own runs (tab governor, click diagnosis); with
|
|
28
|
+
* `snapshot: false` the result leaves out the page snapshot an action would add.
|
|
29
|
+
*/
|
|
30
|
+
call(name: string, args: Record<string, unknown>, options: {
|
|
31
|
+
snapshot: boolean;
|
|
32
|
+
}): Promise<ToolResult>;
|
|
33
|
+
/** URL and title of the current tab, when there is one. */
|
|
34
|
+
page(): Promise<{
|
|
35
|
+
url: string;
|
|
36
|
+
title: string;
|
|
37
|
+
} | undefined>;
|
|
38
|
+
/** The current tab itself (`browser_login` fills it). */
|
|
39
|
+
currentPage(): Page | undefined;
|
|
40
|
+
/**
|
|
41
|
+
* Why the session's browser calls are held right now (the user paused the agent in the live
|
|
42
|
+
* view), or undefined. A tool that runs several steps stops before its next one.
|
|
43
|
+
*/
|
|
44
|
+
held?(): string | undefined;
|
|
45
|
+
}
|
|
46
|
+
interface TurnoToolContext {
|
|
47
|
+
config: McpConfig;
|
|
48
|
+
clientInfo: ClientInfo;
|
|
49
|
+
/** The session's browser context; launched on demand for a tool with `browser: true`. */
|
|
50
|
+
browserContext?: BrowserContext;
|
|
51
|
+
signal?: AbortSignal;
|
|
52
|
+
/**
|
|
53
|
+
* The client session mcpd relays this call for (`_meta["io.turno/session"]`): an
|
|
54
|
+
* opaque id, the same for every call of one agent session and different for every other.
|
|
55
|
+
* Undefined when the call did not come through mcpd.
|
|
56
|
+
*/
|
|
57
|
+
session?: string;
|
|
58
|
+
/** The session's stock tools; set by the host for a tool with `browser: true`. */
|
|
59
|
+
stock?: StockAccess;
|
|
60
|
+
/** The identity's vault, its redactor and guard; set by the host when it serves an identity. */
|
|
61
|
+
vault?: VaultAccess;
|
|
62
|
+
/** The session's flow recorder; set by the host when it serves an identity. */
|
|
63
|
+
recorder?: FlowRecorder;
|
|
64
|
+
/** The browser's recording (traces, screenshots), when identity.json asks for one. */
|
|
65
|
+
recording?: {
|
|
66
|
+
pauseForSecret(page: Page | undefined): Promise<void>;
|
|
67
|
+
};
|
|
68
|
+
/** MCP sampling, routed to the calling session; set when the client offers it. */
|
|
69
|
+
sample?: Sampler;
|
|
70
|
+
/** The engine running the browser ("chrome", "lightpanda", "attach"), once it runs. */
|
|
71
|
+
engine?: string;
|
|
72
|
+
/** Providers that replace the configured ones (tests inject fakes). */
|
|
73
|
+
providers?: Providers;
|
|
74
|
+
}
|
|
75
|
+
/** Stand-ins for the opt-in providers: a model for natural language actions, a captcha solver. */
|
|
76
|
+
export interface Providers {
|
|
77
|
+
model?: ActModel;
|
|
78
|
+
solver?: CaptchaSolver;
|
|
79
|
+
/** The fetch the provider adapters use. */
|
|
80
|
+
fetch?: typeof fetch;
|
|
81
|
+
}
|
|
82
|
+
export interface TurnoTool {
|
|
83
|
+
schema: ToolSchema;
|
|
84
|
+
/** True (the default) when the tool needs the browser: the host launches it first. */
|
|
85
|
+
browser?: boolean;
|
|
86
|
+
handle(context: TurnoToolContext, params: Record<string, unknown>): Promise<ToolResult>;
|
|
87
|
+
}
|
|
88
|
+
/** The tools turno adds to every session. */
|
|
89
|
+
export declare const TURNO_TOOLS: readonly TurnoTool[];
|
|
90
|
+
/**
|
|
91
|
+
* The tools an identity lists only after the person turns their feature on in identity.json
|
|
92
|
+
* (format 8): natural language actions (`act`) and captcha solving (`captcha`). Off, they are
|
|
93
|
+
* not listed at all, so a default session's tool list stays as it was.
|
|
94
|
+
*/
|
|
95
|
+
export declare function optInTools(settings: {
|
|
96
|
+
act?: unknown;
|
|
97
|
+
captcha?: unknown;
|
|
98
|
+
} | undefined): TurnoTool[];
|
|
99
|
+
/** Every opt-in tool, for the name checks (contract test). */
|
|
100
|
+
export declare function allOptInTools(): TurnoTool[];
|
|
101
|
+
/** The zod of the bundle, to build a turno tool's `inputSchema` with. */
|
|
102
|
+
export declare function turnoZod(): Zod;
|
|
103
|
+
/** Throws when a turno tool would shadow an upstream tool or another turno tool. */
|
|
104
|
+
export declare function checkTurnoTools(turno: readonly TurnoTool[], upstreamTools: readonly UpstreamTool[]): void;
|
|
105
|
+
/** Upstream's argument error, word for word, for a turno tool. */
|
|
106
|
+
export declare function parseArguments(tool: TurnoTool, args: Record<string, unknown>): {
|
|
107
|
+
params: Record<string, unknown>;
|
|
108
|
+
} | {
|
|
109
|
+
error: string;
|
|
110
|
+
};
|
|
111
|
+
export {};
|