turno-browser 0.3.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 +98 -0
- package/README.md +32 -3
- 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 +29 -2
- package/dist/api.js +29 -2
- package/dist/argv.d.ts +16 -2
- package/dist/argv.js +100 -3
- package/dist/batch.d.ts +5 -0
- package/dist/batch.js +3 -3
- package/dist/bin/mcp.js +58 -1
- 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/diagnose.d.ts +7 -0
- package/dist/diagnose.js +61 -6
- package/dist/doctor.d.ts +37 -3
- package/dist/doctor.js +230 -5
- 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 +63 -11
- package/dist/engine.js +104 -28
- package/dist/flows.d.ts +127 -0
- package/dist/flows.js +294 -0
- package/dist/governor.d.ts +42 -7
- package/dist/governor.js +82 -32
- package/dist/host.d.ts +17 -2
- package/dist/host.js +618 -41
- 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.js +2 -0
- package/dist/idle-timer.d.ts +12 -0
- package/dist/idle-timer.js +25 -0
- package/dist/index.d.ts +8 -3
- package/dist/index.js +5 -1
- package/dist/lifecycle.d.ts +9 -1
- package/dist/lifecycle.js +9 -1
- 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 +13 -0
- package/dist/login-tool.js +5 -1
- package/dist/login.d.ts +4 -1
- package/dist/login.js +11 -2
- 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/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 +7 -0
- package/dist/redact.js +18 -0
- package/dist/replay.d.ts +20 -0
- package/dist/replay.js +382 -0
- package/dist/reputation.d.ts +24 -2
- package/dist/reputation.js +63 -17
- package/dist/session-export.js +1 -1
- package/dist/session.d.ts +10 -2
- package/dist/session.js +10 -2
- package/dist/settings.d.ts +104 -2
- package/dist/settings.js +204 -6
- package/dist/sharing.d.ts +96 -0
- package/dist/sharing.js +269 -0
- package/dist/snippet.d.ts +8 -2
- package/dist/snippet.js +10 -4
- package/dist/tab-locks.d.ts +63 -0
- package/dist/tab-locks.js +179 -0
- package/dist/tools.d.ts +38 -0
- package/dist/tools.js +20 -1
- package/dist/tuning.d.ts +14 -0
- package/dist/tuning.js +9 -0
- package/dist/upstream.d.ts +11 -0
- package/npm-shrinkwrap.json +2 -2
- package/package.json +1 -1
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
|
package/dist/snippet.d.ts
CHANGED
|
@@ -1,2 +1,8 @@
|
|
|
1
|
-
/**
|
|
2
|
-
|
|
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
CHANGED
|
@@ -1,14 +1,20 @@
|
|
|
1
1
|
import { assertIdentityId } from "./ids.js";
|
|
2
|
-
/**
|
|
3
|
-
|
|
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 = {}) {
|
|
4
8
|
assertIdentityId(id);
|
|
9
|
+
const shared = options.sharing === "tabs";
|
|
5
10
|
return [
|
|
6
11
|
`[server.browser-${id}]`,
|
|
7
12
|
`command = "turno-browser-mcp"`,
|
|
8
13
|
`args = ["--identity", "${id}"]`,
|
|
9
14
|
`scope = "shared"`,
|
|
10
|
-
|
|
11
|
-
|
|
15
|
+
...(shared
|
|
16
|
+
? ["exclusive = false # every agent session at once, each in its own tabs"]
|
|
17
|
+
: ["exclusive = true", `lease = "10m"`]),
|
|
12
18
|
`idle = "30m"`,
|
|
13
19
|
"",
|
|
14
20
|
].join("\n");
|
|
@@ -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
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
import type { BrowserContext, Page } from "patchright-core";
|
|
2
|
+
import type { ActModel, Sampler } from "./act-model.js";
|
|
3
|
+
import { type CaptchaSolver } from "./captcha.js";
|
|
2
4
|
import { type VaultAccess } from "./login-tool.js";
|
|
5
|
+
import { type FlowRecorder } from "./recorder.js";
|
|
3
6
|
import { type ClientInfo, type McpConfig, type ToolResult, type ToolSchema, type UpstreamTool, type Zod, type ZodObject } from "./upstream.js";
|
|
4
7
|
/**
|
|
5
8
|
* The turno tool registry. A turno tool is listed after the stock Playwright MCP
|
|
@@ -34,6 +37,11 @@ export interface StockAccess {
|
|
|
34
37
|
} | undefined>;
|
|
35
38
|
/** The current tab itself (`browser_login` fills it). */
|
|
36
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;
|
|
37
45
|
}
|
|
38
46
|
interface TurnoToolContext {
|
|
39
47
|
config: McpConfig;
|
|
@@ -51,6 +59,25 @@ interface TurnoToolContext {
|
|
|
51
59
|
stock?: StockAccess;
|
|
52
60
|
/** The identity's vault, its redactor and guard; set by the host when it serves an identity. */
|
|
53
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;
|
|
54
81
|
}
|
|
55
82
|
export interface TurnoTool {
|
|
56
83
|
schema: ToolSchema;
|
|
@@ -60,6 +87,17 @@ export interface TurnoTool {
|
|
|
60
87
|
}
|
|
61
88
|
/** The tools turno adds to every session. */
|
|
62
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[];
|
|
63
101
|
/** The zod of the bundle, to build a turno tool's `inputSchema` with. */
|
|
64
102
|
export declare function turnoZod(): Zod;
|
|
65
103
|
/** Throws when a turno tool would shadow an upstream tool or another turno tool. */
|
package/dist/tools.js
CHANGED
|
@@ -1,8 +1,27 @@
|
|
|
1
|
+
import { actTool, extractTool, observeTool } from "./act.js";
|
|
1
2
|
import { batchTool } from "./batch.js";
|
|
3
|
+
import { solveCaptchaTool } from "./captcha.js";
|
|
2
4
|
import { loginTool } from "./login-tool.js";
|
|
5
|
+
import { recordTool } from "./recorder.js";
|
|
6
|
+
import { flowsTool, replayTool } from "./replay.js";
|
|
3
7
|
import { upstream, } from "./upstream.js";
|
|
4
8
|
/** The tools turno adds to every session. */
|
|
5
|
-
export const TURNO_TOOLS = [batchTool(), loginTool()];
|
|
9
|
+
export const TURNO_TOOLS = [batchTool(), loginTool(), recordTool(), replayTool(), flowsTool()];
|
|
10
|
+
/**
|
|
11
|
+
* The tools an identity lists only after the person turns their feature on in identity.json
|
|
12
|
+
* (format 8): natural language actions (`act`) and captcha solving (`captcha`). Off, they are
|
|
13
|
+
* not listed at all, so a default session's tool list stays as it was.
|
|
14
|
+
*/
|
|
15
|
+
export function optInTools(settings) {
|
|
16
|
+
return [
|
|
17
|
+
...(settings?.act ? [actTool(), extractTool(), observeTool()] : []),
|
|
18
|
+
...(settings?.captcha ? [solveCaptchaTool()] : []),
|
|
19
|
+
];
|
|
20
|
+
}
|
|
21
|
+
/** Every opt-in tool, for the name checks (contract test). */
|
|
22
|
+
export function allOptInTools() {
|
|
23
|
+
return optInTools({ act: {}, captcha: {} });
|
|
24
|
+
}
|
|
6
25
|
/** The zod of the bundle, to build a turno tool's `inputSchema` with. */
|
|
7
26
|
export function turnoZod() {
|
|
8
27
|
return upstream().utils.z;
|
package/dist/tuning.d.ts
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
|
+
import type { HumanizeLevel, HumanizeSettings } from "./humanize.js";
|
|
1
2
|
import { type ResourcePolicy } from "./resources.js";
|
|
2
3
|
import type { IdentitySettings } from "./settings.js";
|
|
4
|
+
import type { SharingMode } from "./sharing.js";
|
|
5
|
+
import type { TabLockPolicy } from "./tab-locks.js";
|
|
3
6
|
/**
|
|
4
7
|
* How the host runs one session's Chrome: the tab governor, background tab
|
|
5
8
|
* throttling, the wait after each action, and resource blocking and caching. Each value comes from, in order of precedence, a `turno-browser-mcp` flag, the
|
|
@@ -31,6 +34,15 @@ export interface Tuning {
|
|
|
31
34
|
settleMs?: number;
|
|
32
35
|
/** Opt-in resource blocking and cache, from identity.json `block` and `cache`. */
|
|
33
36
|
resources: ResourcePolicy;
|
|
37
|
+
/** Human-like input (`humanize.ts`), from `--humanize` or identity.json `humanize`; off by default. */
|
|
38
|
+
humanize: HumanizeSettings;
|
|
39
|
+
/**
|
|
40
|
+
* `"session"` (the default): one backend serves every call, as mcpd's `exclusive = true` lets
|
|
41
|
+
* one session at a time. `"tabs"`: each agent session gets its own tabs, with locks (`sharing.ts`).
|
|
42
|
+
*/
|
|
43
|
+
sharing: SharingMode;
|
|
44
|
+
/** With `"sharing": "tabs"`: the lock wait and idle release of identity.json `tabLocks`. */
|
|
45
|
+
tabLocks: Partial<TabLockPolicy>;
|
|
34
46
|
}
|
|
35
47
|
/** The defaults, documented on the browser identities page. */
|
|
36
48
|
export declare const DEFAULT_TABS: Readonly<TabPolicy>;
|
|
@@ -41,6 +53,8 @@ export interface TuningFlags {
|
|
|
41
53
|
parkAfterMs?: number;
|
|
42
54
|
closeAfterMs?: number;
|
|
43
55
|
backgroundThrottling?: boolean;
|
|
56
|
+
humanize?: HumanizeLevel;
|
|
57
|
+
sharing?: SharingMode;
|
|
44
58
|
}
|
|
45
59
|
/** The tuning of a session: flags, then identity.json, then the defaults. */
|
|
46
60
|
export declare function resolveTuning(settings: IdentitySettings | undefined, flags?: TuningFlags): Tuning;
|