cdp-toolkit 3.4.0 → 3.5.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 +10 -0
- package/README.md +18 -3
- package/dist/bidi/mux-daemon.js +169 -3
- package/dist/cli.js +243 -11
- package/dist/index.js +243 -11
- package/dist/mcp.js +256 -18
- package/package.json +1 -1
- package/src/cdp/driver.ts +74 -6
- package/src/cdp/hiddenTabs.ts +285 -0
- package/src/client.ts +12 -3
- package/src/driver.ts +6 -0
- package/src/leases-tools.ts +6 -0
- package/src/leases.ts +6 -0
- package/src/mcp.ts +4 -0
- package/src/shared-tools.ts +40 -9
- package/src/toolDocs.ts +6 -6
- package/src/types.ts +3 -0
- package/src/version.ts +1 -1
|
@@ -0,0 +1,285 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Hidden tabs (CDP_HIDDEN_TABS=1, MCP server only): new_page without focus:true opens a
|
|
3
|
+
* `Target.createTarget {background:true, hidden:true}` target that never becomes visible, so the
|
|
4
|
+
* browser APP never comes to the front of the user's screen.
|
|
5
|
+
*
|
|
6
|
+
* WHY. Measured on Vivaldi (Chromium 156) by sampling `lsappinfo front` around raw CDP calls:
|
|
7
|
+
* createTarget with {background:true}, {background:true, focus:false}, {newWindow:true,
|
|
8
|
+
* background:true} and a minimized new window all bring the browser app to the front for a
|
|
9
|
+
* moment (keepFrontApp in ../frontApp.ts puts the user's app back AFTER that flash). Only
|
|
10
|
+
* {background:true, hidden:true} leaves the front app alone. Target.closeTarget and
|
|
11
|
+
* Page.navigate on an existing tab are also clean.
|
|
12
|
+
*
|
|
13
|
+
* WHAT A HIDDEN TARGET IS, measured on the same browser:
|
|
14
|
+
* - It dies when the CDP connection that created it closes. So this module holds ONE owner
|
|
15
|
+
* browser connection per endpoint, for the life of the process. That is also why the feature
|
|
16
|
+
* is MCP-server only: under the one-shot CLI the tab would die at process exit, so the CLI
|
|
17
|
+
* keeps the visible path even with the env set (see hiddenTabsEnabled).
|
|
18
|
+
* - While the owner lives, the target is in /json/list and Target.getTargets, and any other
|
|
19
|
+
* connection can attach, evaluate, navigate and screenshot it. Its listing type is "other",
|
|
20
|
+
* not "page", so markHiddenTargets relabels the ids this process owns (see there).
|
|
21
|
+
* - Its viewport is 0x0: Page.captureScreenshot hangs and clicks land nowhere. The owner
|
|
22
|
+
* attaches (flatten), sets Emulation.setDeviceMetricsOverride and KEEPS that session, and then
|
|
23
|
+
* every other per-call connection sees the emulated viewport. A second connection that sets
|
|
24
|
+
* and clears its own override, or disconnects without clearing, leaves the owner's override
|
|
25
|
+
* in force once it is gone (measured). The device pixel ratio is read from the tab itself
|
|
26
|
+
* before the override: a hidden tab reports the real screen's devicePixelRatio (2 on a Retina
|
|
27
|
+
* Mac) even at 0x0.
|
|
28
|
+
* - It shares the default browser context, so cookies and logins carry over.
|
|
29
|
+
* - Target.activateTarget / Page.bringToFront return ok and show nothing, and window.open from
|
|
30
|
+
* it opens nothing. So a hidden tab cannot be revealed in place; see the driver's activatePage.
|
|
31
|
+
*
|
|
32
|
+
* OWNER LOSS (server restart, browser restart, socket drop) kills every hidden tab. The registry
|
|
33
|
+
* notices on the next access (the owner's `isOpen` is false) and forgets them all, and the next
|
|
34
|
+
* new_page reconnects lazily. A dead hidden id is then an ordinary missing target, so every tool
|
|
35
|
+
* fails it with the existing `no-such-target` error from target resolution, never a hang.
|
|
36
|
+
*
|
|
37
|
+
* LEAK BOUND. The user can neither see nor close these tabs, so at most CDP_HIDDEN_TABS_MAX
|
|
38
|
+
* (default 20) live at once per endpoint. At the cap new_page REFUSES with an error naming the
|
|
39
|
+
* open hidden ids, rather than closing the oldest: silently closing a tab another call may still
|
|
40
|
+
* be driving (or holds a lease on) is the one thing list_pages' reap is also never allowed to do
|
|
41
|
+
* without saying so. dispose() (the MCP server's shutdown) closes them all.
|
|
42
|
+
*
|
|
43
|
+
* THIS MODULE IMPORTS NOTHING AT RUNTIME FROM ../client.ts: client.ts imports it (listTargets
|
|
44
|
+
* calls markHiddenTargets), and the owner's connection factory is injected by ./driver.ts.
|
|
45
|
+
*/
|
|
46
|
+
import type { Target } from "../types.ts";
|
|
47
|
+
|
|
48
|
+
/** Default cap on live hidden tabs per endpoint. */
|
|
49
|
+
export const DEFAULT_HIDDEN_TABS_MAX = 20;
|
|
50
|
+
/** Emulated viewport for a hidden tab, in CSS px. */
|
|
51
|
+
export const HIDDEN_TAB_VIEWPORT = { width: 1280, height: 800 } as const;
|
|
52
|
+
/** Used when the tab cannot report its own devicePixelRatio. */
|
|
53
|
+
export const FALLBACK_DEVICE_SCALE_FACTOR = 2;
|
|
54
|
+
/** Bound on each owner-side command, so a wedged browser costs seconds, never a hang. */
|
|
55
|
+
const OWNER_COMMAND_TIMEOUT_MS = 5_000;
|
|
56
|
+
|
|
57
|
+
const TRUTHY = new Set(["1", "true", "yes", "on"]);
|
|
58
|
+
|
|
59
|
+
/** CDP_HIDDEN_TABS is set to a truthy value. Read per call, so a test can flip it. */
|
|
60
|
+
export function hiddenTabsRequested(): boolean {
|
|
61
|
+
return TRUTHY.has((process.env.CDP_HIDDEN_TABS ?? "").trim().toLowerCase());
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** CDP_HIDDEN_TABS_MAX, else DEFAULT_HIDDEN_TABS_MAX. A non-positive or non-numeric value is ignored. */
|
|
65
|
+
export function hiddenTabsMax(): number {
|
|
66
|
+
const raw = Number(process.env.CDP_HIDDEN_TABS_MAX);
|
|
67
|
+
return Number.isFinite(raw) && raw >= 1 ? Math.floor(raw) : DEFAULT_HIDDEN_TABS_MAX;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** The slice of CdpConnection the owner needs. */
|
|
71
|
+
export interface OwnerConnection {
|
|
72
|
+
send<T = Record<string, unknown>>(method: string, params?: Record<string, unknown>, opts?: { timeoutMs?: number; sessionId?: string }): Promise<T>;
|
|
73
|
+
on(method: string, handler: (params: Record<string, unknown>, sessionId?: string) => void): () => void;
|
|
74
|
+
close(): void;
|
|
75
|
+
readonly isOpen: boolean;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
export interface HiddenTabOwnerDeps {
|
|
79
|
+
/** Opens a fresh browser-endpoint connection (openBrowser in production). */
|
|
80
|
+
connect(): Promise<OwnerConnection>;
|
|
81
|
+
/** Creates the target with the settle wait (createSettledTarget in production). */
|
|
82
|
+
createSettled(conn: OwnerConnection, url: string, opts: { hidden: true }): Promise<string>;
|
|
83
|
+
/** Live cap; hiddenTabsMax by default. */
|
|
84
|
+
max?: () => number;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** Thrown at the cap. `code` makes it pass through noSuchTarget and the MCP error mapping typed. */
|
|
88
|
+
export class HiddenTabCapError extends Error {
|
|
89
|
+
readonly code = "page-error" as const;
|
|
90
|
+
constructor(readonly max: number, readonly openIds: string[]) {
|
|
91
|
+
super(
|
|
92
|
+
`hidden-tab cap reached: ${openIds.length} hidden tabs are open (CDP_HIDDEN_TABS_MAX=${max}). ` +
|
|
93
|
+
`Close one with close_page (open hidden tabs, oldest first: ${openIds.join(", ")}), ` +
|
|
94
|
+
`or pass focus:true to open a visible tab instead.`,
|
|
95
|
+
);
|
|
96
|
+
this.name = "HiddenTabCapError";
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** One endpoint's owner connection and the hidden tabs it keeps alive. */
|
|
101
|
+
export class HiddenTabOwner {
|
|
102
|
+
private conn: OwnerConnection | undefined;
|
|
103
|
+
private connecting: Promise<OwnerConnection> | undefined;
|
|
104
|
+
/** targetId -> the owner's session on it. Insertion order is age (oldest first). */
|
|
105
|
+
private readonly tabs = new Map<string, string>();
|
|
106
|
+
/** Creates in flight, counted against the cap so concurrent new_page calls cannot overshoot it. */
|
|
107
|
+
private reserved = 0;
|
|
108
|
+
|
|
109
|
+
constructor(private readonly deps: HiddenTabOwnerDeps) {}
|
|
110
|
+
|
|
111
|
+
/** Forget everything if the owner socket died: its hidden tabs died with it. */
|
|
112
|
+
private sweep(): void {
|
|
113
|
+
if (this.conn && !this.conn.isOpen) {
|
|
114
|
+
this.conn = undefined;
|
|
115
|
+
this.tabs.clear();
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/** True when `id` is a live hidden tab this owner holds. */
|
|
120
|
+
has(id: string): boolean {
|
|
121
|
+
this.sweep();
|
|
122
|
+
return this.tabs.has(id);
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/** Live hidden ids, oldest first. */
|
|
126
|
+
ids(): string[] {
|
|
127
|
+
this.sweep();
|
|
128
|
+
return [...this.tabs.keys()];
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/** The owner connection, opened lazily and single-flight: concurrent callers share one connect. */
|
|
132
|
+
private async owner(): Promise<OwnerConnection> {
|
|
133
|
+
this.sweep();
|
|
134
|
+
if (this.conn) return this.conn;
|
|
135
|
+
if (!this.connecting) {
|
|
136
|
+
this.connecting = (async () => {
|
|
137
|
+
const conn = await this.deps.connect();
|
|
138
|
+
// A hidden tab closed by anyone (another process's close_page, the browser itself) drops
|
|
139
|
+
// out of the registry here; setDiscoverTargets is sent by createSettled.
|
|
140
|
+
conn.on("Target.targetDestroyed", (params) => {
|
|
141
|
+
const id = (params as { targetId?: unknown }).targetId;
|
|
142
|
+
if (typeof id === "string") this.tabs.delete(id);
|
|
143
|
+
});
|
|
144
|
+
this.conn = conn;
|
|
145
|
+
return conn;
|
|
146
|
+
})().finally(() => {
|
|
147
|
+
this.connecting = undefined;
|
|
148
|
+
});
|
|
149
|
+
}
|
|
150
|
+
return this.connecting;
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/** Create a hidden tab at `url`, attach the owner to it and give it a real viewport. */
|
|
154
|
+
async create(url: string): Promise<string> {
|
|
155
|
+
this.sweep();
|
|
156
|
+
const max = (this.deps.max ?? hiddenTabsMax)();
|
|
157
|
+
if (this.tabs.size + this.reserved >= max) throw new HiddenTabCapError(max, [...this.tabs.keys()]);
|
|
158
|
+
this.reserved++;
|
|
159
|
+
try {
|
|
160
|
+
const conn = await this.owner();
|
|
161
|
+
const id = await this.deps.createSettled(conn, url, { hidden: true });
|
|
162
|
+
try {
|
|
163
|
+
const { sessionId } = await conn.send<{ sessionId: string }>(
|
|
164
|
+
"Target.attachToTarget",
|
|
165
|
+
{ targetId: id, flatten: true },
|
|
166
|
+
{ timeoutMs: OWNER_COMMAND_TIMEOUT_MS },
|
|
167
|
+
);
|
|
168
|
+
const dpr = await conn
|
|
169
|
+
.send<{ result?: { value?: unknown } }>(
|
|
170
|
+
"Runtime.evaluate",
|
|
171
|
+
{ expression: "devicePixelRatio", returnByValue: true },
|
|
172
|
+
{ sessionId, timeoutMs: OWNER_COMMAND_TIMEOUT_MS },
|
|
173
|
+
)
|
|
174
|
+
.then((r) => r.result?.value)
|
|
175
|
+
.catch(() => undefined);
|
|
176
|
+
await conn.send(
|
|
177
|
+
"Emulation.setDeviceMetricsOverride",
|
|
178
|
+
{
|
|
179
|
+
width: HIDDEN_TAB_VIEWPORT.width,
|
|
180
|
+
height: HIDDEN_TAB_VIEWPORT.height,
|
|
181
|
+
deviceScaleFactor: typeof dpr === "number" && Number.isFinite(dpr) && dpr > 0 ? dpr : FALLBACK_DEVICE_SCALE_FACTOR,
|
|
182
|
+
mobile: false,
|
|
183
|
+
},
|
|
184
|
+
{ sessionId, timeoutMs: OWNER_COMMAND_TIMEOUT_MS },
|
|
185
|
+
);
|
|
186
|
+
this.tabs.set(id, sessionId);
|
|
187
|
+
return id;
|
|
188
|
+
} catch (e) {
|
|
189
|
+
// A hidden tab without a viewport cannot be screenshotted or clicked: do not hand it out.
|
|
190
|
+
await conn.send("Target.closeTarget", { targetId: id }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS }).catch(() => undefined);
|
|
191
|
+
throw e;
|
|
192
|
+
}
|
|
193
|
+
} finally {
|
|
194
|
+
this.reserved--;
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/**
|
|
199
|
+
* Close a hidden tab over the owner. Closing the target ends the owner's session on it. When
|
|
200
|
+
* the owner is already gone the tab is too, so this reports success:false like a close of any
|
|
201
|
+
* missing target.
|
|
202
|
+
*/
|
|
203
|
+
async close(id: string): Promise<{ success: boolean }> {
|
|
204
|
+
this.sweep();
|
|
205
|
+
const conn = this.conn;
|
|
206
|
+
const held = this.tabs.delete(id);
|
|
207
|
+
if (!conn || !held) return { success: false };
|
|
208
|
+
const res = await conn.send<{ success?: boolean }>("Target.closeTarget", { targetId: id }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS });
|
|
209
|
+
return { success: res.success ?? true };
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/** Close every hidden tab, then the owner. Best effort and bounded; never throws. */
|
|
213
|
+
async dispose(): Promise<void> {
|
|
214
|
+
const conn = this.conn;
|
|
215
|
+
const ids = [...this.tabs.keys()];
|
|
216
|
+
this.tabs.clear();
|
|
217
|
+
this.conn = undefined;
|
|
218
|
+
if (!conn) return;
|
|
219
|
+
if (conn.isOpen) {
|
|
220
|
+
await Promise.all(ids.map((targetId) => conn.send("Target.closeTarget", { targetId }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS }).catch(() => undefined)));
|
|
221
|
+
}
|
|
222
|
+
conn.close();
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/* ------------------------------ process registry ------------------------------ */
|
|
227
|
+
|
|
228
|
+
/**
|
|
229
|
+
* One owner per endpoint base, MODULE SCOPE like ./driver.ts's beaconSessions: the state belongs
|
|
230
|
+
* to the process (the MCP server), and named endpoints are separate browsers whose target ids
|
|
231
|
+
* mean nothing to each other.
|
|
232
|
+
*/
|
|
233
|
+
const owners = new Map<string, HiddenTabOwner>();
|
|
234
|
+
|
|
235
|
+
/** The owner for `base`, created on first use with `deps`. */
|
|
236
|
+
export function hiddenTabOwner(base: string, deps: () => HiddenTabOwnerDeps): HiddenTabOwner {
|
|
237
|
+
let owner = owners.get(base);
|
|
238
|
+
if (!owner) {
|
|
239
|
+
owner = new HiddenTabOwner(deps());
|
|
240
|
+
owners.set(base, owner);
|
|
241
|
+
}
|
|
242
|
+
return owner;
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/** The owner for `base` if one was ever created. Never creates one. */
|
|
246
|
+
export function existingHiddenTabOwner(base: string): HiddenTabOwner | undefined {
|
|
247
|
+
return owners.get(base);
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
/** True when `id` is a live hidden tab on endpoint `base`. */
|
|
251
|
+
export function isHiddenTab(base: string, id: string): boolean {
|
|
252
|
+
return owners.get(base)?.has(id) ?? false;
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
/**
|
|
256
|
+
* Relabel this process's hidden tabs in a target listing: type "other" becomes "page" with
|
|
257
|
+
* `hidden: true`, so every selector arm (index, url, title, label, the default) and list_pages
|
|
258
|
+
* see them as the pages they are. They move to the END of the listing, so the visible tabs keep
|
|
259
|
+
* their indexes and a call with no target still lands on the same visible tab as before.
|
|
260
|
+
*
|
|
261
|
+
* Returns the SAME array when this process holds no hidden tab on `base`, so with the feature off
|
|
262
|
+
* the listing is untouched. Only ids this process created are relabeled: another process's hidden
|
|
263
|
+
* tabs, and Vivaldi's own "other" targets, are left alone.
|
|
264
|
+
*/
|
|
265
|
+
export function markHiddenTargets(base: string, targets: Target[]): Target[] {
|
|
266
|
+
const owner = owners.get(base);
|
|
267
|
+
if (!owner) return targets;
|
|
268
|
+
const hidden = new Set(owner.ids());
|
|
269
|
+
if (hidden.size === 0) return targets;
|
|
270
|
+
const visible: Target[] = [];
|
|
271
|
+
const marked: Target[] = [];
|
|
272
|
+
for (const t of targets) {
|
|
273
|
+
if (hidden.has(t.id)) marked.push({ ...t, type: "page", hidden: true });
|
|
274
|
+
else visible.push(t);
|
|
275
|
+
}
|
|
276
|
+
return marked.length ? [...visible, ...marked] : targets;
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/** Close every hidden tab on every endpoint and the owner connections. The MCP server's shutdown
|
|
280
|
+
* path (via the CDP driver's dispose). */
|
|
281
|
+
export async function disposeHiddenTabs(): Promise<void> {
|
|
282
|
+
const all = [...owners.values()];
|
|
283
|
+
owners.clear();
|
|
284
|
+
await Promise.all(all.map((o) => o.dispose()));
|
|
285
|
+
}
|
package/src/client.ts
CHANGED
|
@@ -27,6 +27,7 @@ import {
|
|
|
27
27
|
|
|
28
28
|
import { detectEndpoint, resetEndpointCache, type CdpTransport } from "./cdp/endpoint.ts";
|
|
29
29
|
import { openSession, withBrowserSocket, type PageConnection } from "./cdp/session.ts";
|
|
30
|
+
import { markHiddenTargets } from "./cdp/hiddenTabs.ts";
|
|
30
31
|
export { SessionConnection, withBrowserSocket, type PageConnection } from "./cdp/session.ts";
|
|
31
32
|
/**
|
|
32
33
|
* Base HTTP origin of the DEFAULT DevTools endpoint, fixed at import (CDP_BASE, else
|
|
@@ -197,6 +198,12 @@ export class CdpConnection {
|
|
|
197
198
|
});
|
|
198
199
|
}
|
|
199
200
|
|
|
201
|
+
/** False once the socket closed (either side) or before connect(). The hidden-tab owner reads
|
|
202
|
+
* this to notice that the tabs it kept alive died with it. */
|
|
203
|
+
get isOpen(): boolean {
|
|
204
|
+
return !this.closed && this.ws !== undefined;
|
|
205
|
+
}
|
|
206
|
+
|
|
200
207
|
close(): void {
|
|
201
208
|
this.closed = true;
|
|
202
209
|
this.rejectAll(new CdpError("closed by caller"));
|
|
@@ -280,11 +287,13 @@ async function getTargetsOverBrowserWs(): Promise<Target[]> {
|
|
|
280
287
|
*/
|
|
281
288
|
export async function listTargets(): Promise<Target[]> {
|
|
282
289
|
const base = currentEndpoint().base;
|
|
283
|
-
|
|
290
|
+
// markHiddenTargets returns the listing untouched unless this process holds hidden tabs on this
|
|
291
|
+
// endpoint (CDP_HIDDEN_TABS, see cdp/hiddenTabs.ts).
|
|
292
|
+
if (knownTransports.get(base) === "browser-ws") return markHiddenTargets(base, await getTargetsOverBrowserWs());
|
|
284
293
|
try {
|
|
285
294
|
const listing = await httpJson<Target[]>("/json/list");
|
|
286
295
|
knownTransports.set(base, "http");
|
|
287
|
-
return listing;
|
|
296
|
+
return markHiddenTargets(base, listing);
|
|
288
297
|
} catch (httpError) {
|
|
289
298
|
// Switch only when detection says this endpoint really serves no `/json`.
|
|
290
299
|
// A Chrome that does serve it can still fail one `/json/list` (restarting,
|
|
@@ -301,7 +310,7 @@ export async function listTargets(): Promise<Target[]> {
|
|
|
301
310
|
throw httpError;
|
|
302
311
|
});
|
|
303
312
|
knownTransports.set(base, "browser-ws");
|
|
304
|
-
return targets;
|
|
313
|
+
return markHiddenTargets(base, targets);
|
|
305
314
|
}
|
|
306
315
|
}
|
|
307
316
|
|
package/src/driver.ts
CHANGED
|
@@ -212,6 +212,12 @@ export interface PageInfo {
|
|
|
212
212
|
title: string;
|
|
213
213
|
/** CDP target type ("page", "iframe", "worker", ...), when the driver has one. Additive: BiDi leaves it unset. */
|
|
214
214
|
type?: string;
|
|
215
|
+
/** True for a hidden tab (CDP_HIDDEN_TABS=1, MCP server only): it is live and drivable, but it
|
|
216
|
+
* is in no browser window, so the user cannot see it. Absent otherwise. */
|
|
217
|
+
hidden?: boolean;
|
|
218
|
+
/** Set only by activatePage on a hidden tab: that tab cannot be shown in place, so the driver
|
|
219
|
+
* opened its URL in a new visible tab (`id`) and closed the hidden one, whose id this is. */
|
|
220
|
+
revealedFrom?: string;
|
|
215
221
|
}
|
|
216
222
|
|
|
217
223
|
/** How a caller points at an element. Exactly one field is set. */
|
package/src/leases-tools.ts
CHANGED
|
@@ -45,6 +45,9 @@ export interface ClaimPageResult {
|
|
|
45
45
|
* in the answer so a caller knows without a second lookup whether
|
|
46
46
|
* release_page will close the tab. */
|
|
47
47
|
opened: boolean;
|
|
48
|
+
/** true when the tab this call created is a hidden tab (CDP_HIDDEN_TABS): live and drivable,
|
|
49
|
+
* but in no window, so no human can see it. Absent otherwise. */
|
|
50
|
+
hidden?: true;
|
|
48
51
|
/**
|
|
49
52
|
* Milliseconds since the last input this server cannot account for — i.e.
|
|
50
53
|
* since a HUMAN last touched this tab. See src/activity.ts for how that
|
|
@@ -134,6 +137,7 @@ export async function claimPage(
|
|
|
134
137
|
let targetId: string;
|
|
135
138
|
let url: string;
|
|
136
139
|
let opened: boolean;
|
|
140
|
+
let hidden = false;
|
|
137
141
|
if (hasTarget) {
|
|
138
142
|
// Gate-free on purpose: see the header. No tab is created on this path,
|
|
139
143
|
// including when nothing matches.
|
|
@@ -161,6 +165,7 @@ export async function claimPage(
|
|
|
161
165
|
targetId = page.id;
|
|
162
166
|
url = page.url;
|
|
163
167
|
opened = true;
|
|
168
|
+
hidden = page.hidden === true;
|
|
164
169
|
}
|
|
165
170
|
// Gate-free, before the claim, and only for a takeover: a tab this call is
|
|
166
171
|
// about to CREATE cannot have a human in it, so asking would be theatre.
|
|
@@ -185,6 +190,7 @@ export async function claimPage(
|
|
|
185
190
|
ttlMs: record.ttlMs,
|
|
186
191
|
expiresAt: record.lastUsedAt + record.ttlMs,
|
|
187
192
|
opened,
|
|
193
|
+
...(hidden ? { hidden: true as const } : {}),
|
|
188
194
|
// Absent, not null, when the backend has no beacon at all: "cannot answer"
|
|
189
195
|
// and "answered, no data" are different facts (ADR-001's absent-over-
|
|
190
196
|
// throwing rule applied to a field rather than to a whole tool).
|
package/src/leases.ts
CHANGED
|
@@ -114,6 +114,12 @@ export function markLongLivedProcess(value = true): void {
|
|
|
114
114
|
longLived = value;
|
|
115
115
|
}
|
|
116
116
|
|
|
117
|
+
/** Whether markLongLivedProcess ran: true in the MCP server, false under the CLI. Hidden tabs
|
|
118
|
+
* (cdp/hiddenTabs.ts) gate on it for the same reason requireLease does. */
|
|
119
|
+
export function isLongLivedProcess(): boolean {
|
|
120
|
+
return longLived;
|
|
121
|
+
}
|
|
122
|
+
|
|
117
123
|
/**
|
|
118
124
|
* Strict mode: every tool call acquires a lease for the tab it resolves, and
|
|
119
125
|
* stale agent tabs are reaped on read. Off by default, so 1.4.0 consumers are
|
package/src/mcp.ts
CHANGED
|
@@ -41,6 +41,7 @@ import { TOOLS, TOOL_NAMES, BASE } from "./index.ts";
|
|
|
41
41
|
import { MANIFEST } from "./manifest.ts";
|
|
42
42
|
import { resolveBackend, getOrCreateFirefoxSession, disposeFirefoxSession } from "./backend.ts";
|
|
43
43
|
import { disposeBrowserSession } from "./tools/browser-session.ts";
|
|
44
|
+
import { disposeHiddenTabs } from "./cdp/hiddenTabs.ts";
|
|
44
45
|
import { toolAvailability } from "./capabilities.ts";
|
|
45
46
|
import { FIREFOX_TOOLS } from "./firefox-tools.ts";
|
|
46
47
|
import { leaseFromArgs, markLongLivedProcess, withLeaseScope } from "./leases.ts";
|
|
@@ -528,6 +529,9 @@ async function run(argv: string[]): Promise<void> {
|
|
|
528
529
|
// Track P3). Unlike Firefox it owns no OS process, so process.exit would collect it anyway; it is
|
|
529
530
|
// closed explicitly so shutdown does not depend on that, and is a no-op when neither tool ran.
|
|
530
531
|
await disposeBrowserSession();
|
|
532
|
+
// Hidden tabs (CDP_HIDDEN_TABS): the user can neither see nor close them, so close every one
|
|
533
|
+
// and their owner connection. A no-op when none were opened.
|
|
534
|
+
await disposeHiddenTabs().catch(() => undefined);
|
|
531
535
|
// Close the active transport last, so a tool call still in flight over it cannot outlive the
|
|
532
536
|
// browser resources it was driving. For http this also stops accepting new connections.
|
|
533
537
|
if (stdioHandle) await stdioHandle.close().catch(() => undefined);
|
package/src/shared-tools.ts
CHANGED
|
@@ -42,11 +42,11 @@ import { isTiledCapture } from "./driver.ts";
|
|
|
42
42
|
import { stitchPngBandsToFile } from "./png.ts";
|
|
43
43
|
import type { TargetSelector } from "./types.ts";
|
|
44
44
|
import {
|
|
45
|
-
assertLeaseOk, chromeLeaseBackend, claimLease, defaultLabel, leaseTtlMs, listLeases, releaseLeaseFor, requireLease,
|
|
45
|
+
assertLeaseOk, chromeLeaseBackend, claimLease, defaultLabel, leaseTtlMs, listLeases, readLease, releaseLeaseFor, requireLease,
|
|
46
46
|
type LeaseBackend, type LeaseStaleReason, type LeaseToken,
|
|
47
47
|
} from "./leases.ts";
|
|
48
48
|
import { installBeacon, probeRendererActivity, rendererProbeSupported } from "./activity.ts";
|
|
49
|
-
import { newTrackedPage, originIndex, resolveLiveLabel, type PageOrigin } from "./origins.ts";
|
|
49
|
+
import { newTrackedPage, originIndex, readOrigin, recordOrigin, resolveLiveLabel, type PageOrigin } from "./origins.ts";
|
|
50
50
|
import { isWorkerSelector, WORKER_SELECTOR_PAGE_ONLY_MESSAGE, WORKER_SELECTOR_UNSUPPORTED_MESSAGE } from "./workers.ts";
|
|
51
51
|
import { FRAME_SELECTOR_PAGE_ONLY_MESSAGE, FRAME_SELECTOR_UNSUPPORTED_MESSAGE, isFrameSelector } from "./frames.ts";
|
|
52
52
|
import { reapAllowed, reapStaleAgentTabs, type ReapedTab } from "./reap.ts";
|
|
@@ -402,18 +402,20 @@ async function listPagesOne(
|
|
|
402
402
|
export async function newPage(
|
|
403
403
|
driver: BrowserDriver,
|
|
404
404
|
args: { url?: string; claim?: boolean; label?: string; ttlMs?: number; focus?: boolean } = {},
|
|
405
|
-
): Promise<{ targetId: string; url: string; lease?: LeaseToken; label?: string; expiresAt?: number }> {
|
|
405
|
+
): Promise<{ targetId: string; url: string; hidden?: true; lease?: LeaseToken; label?: string; expiresAt?: number }> {
|
|
406
406
|
const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
|
|
407
407
|
// Creates the tab AND writes its creation record. The record outlives any
|
|
408
408
|
// lease taken below, which is the point: a released tab is still an agent's.
|
|
409
409
|
const p = await newTrackedPage(driver, backendOf(driver), { url: args.url, label, focus: args.focus === true });
|
|
410
|
+
// Present only for a hidden tab (CDP_HIDDEN_TABS), so the default output is byte-identical.
|
|
411
|
+
const hidden = p.hidden === true ? { hidden: true as const } : {};
|
|
410
412
|
// Under strict mode a tab nobody holds is a tab nobody may drive, so creating
|
|
411
413
|
// one without claiming it would hand back a target the very next call has to
|
|
412
414
|
// auto-acquire anyway. Doing it here means the tab is never briefly unowned
|
|
413
415
|
// AND the caller is handed a token it can release with, which matters because
|
|
414
416
|
// an auto-acquired lease never returns one.
|
|
415
417
|
const explicit = args.claim === true;
|
|
416
|
-
if (!explicit && !requireLease()) return { targetId: p.id, url: p.url };
|
|
418
|
+
if (!explicit && !requireLease()) return { targetId: p.id, url: p.url, ...hidden };
|
|
417
419
|
// Atomic in the sense that matters: the tab is claimed before this call
|
|
418
420
|
// returns, so no other agent can see it unclaimed and take it first.
|
|
419
421
|
const { record, token } = await claimLease(backendOf(driver), p.id, {
|
|
@@ -430,7 +432,7 @@ export async function newPage(
|
|
|
430
432
|
// it and a person has picked it up, which is the case the beacon exists for.
|
|
431
433
|
// Nothing here is read back: a tab created a moment ago has no human history.
|
|
432
434
|
await installBeacon(driver, p.id);
|
|
433
|
-
return { targetId: p.id, url: p.url, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
|
|
435
|
+
return { targetId: p.id, url: p.url, ...hidden, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
|
|
434
436
|
}
|
|
435
437
|
|
|
436
438
|
export async function closePage(
|
|
@@ -464,13 +466,42 @@ async function writeSelectedFile(id: string): Promise<void> {
|
|
|
464
466
|
* (Target.activateTarget / browsingContext.activate) switches the user's visible
|
|
465
467
|
* tab and takes window focus, so it is never a side effect of selecting.
|
|
466
468
|
* resolvePage already ran the lease gate, so skipping activatePage loses no check.
|
|
469
|
+
*
|
|
470
|
+
* focus:true on a HIDDEN tab (CDP_HIDDEN_TABS) cannot raise it in place: the driver reopens its
|
|
471
|
+
* URL in a new visible tab and closes the hidden one (see the CDP driver's activatePage). The new
|
|
472
|
+
* id is what gets selected and returned, with `revealedFrom` naming the closed hidden tab. The
|
|
473
|
+
* tab's provenance label moves with it, and a lease on the hidden tab is moved to the new tab and
|
|
474
|
+
* its NEW token returned as `lease`, since the old token names a tab that no longer exists.
|
|
467
475
|
*/
|
|
468
|
-
export async function selectPage(
|
|
476
|
+
export async function selectPage(
|
|
477
|
+
driver: BrowserDriver,
|
|
478
|
+
args: { target?: TargetSelector; focus?: boolean },
|
|
479
|
+
): Promise<{ selected: string; focused: boolean; revealedFrom?: string; lease?: LeaseToken }> {
|
|
469
480
|
if (args.target === undefined || args.target === "") throw new SharedToolError("select_page requires an explicit target");
|
|
470
481
|
const p = await resolvePage(driver, args.target);
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
482
|
+
if (args.focus !== true) {
|
|
483
|
+
await writeSelectedFile(p.id);
|
|
484
|
+
return { selected: p.id, focused: false };
|
|
485
|
+
}
|
|
486
|
+
const shown = await driver.activatePage(p.id);
|
|
487
|
+
if (shown.revealedFrom === undefined || shown.id === p.id) {
|
|
488
|
+
await writeSelectedFile(shown.id);
|
|
489
|
+
return { selected: shown.id, focused: true };
|
|
490
|
+
}
|
|
491
|
+
const moved = await moveRevealedTab(backendOf(driver), shown.revealedFrom, shown.id);
|
|
492
|
+
await writeSelectedFile(shown.id);
|
|
493
|
+
return { selected: shown.id, focused: true, revealedFrom: shown.revealedFrom, ...(moved.lease ? { lease: moved.lease } : {}) };
|
|
494
|
+
}
|
|
495
|
+
|
|
496
|
+
/** Carry a revealed hidden tab's origin label and lease over to the visible tab that replaced it. */
|
|
497
|
+
async function moveRevealedTab(backend: LeaseBackend, fromId: string, toId: string): Promise<{ lease?: LeaseToken }> {
|
|
498
|
+
const origin = await readOrigin(backend, fromId).catch(() => undefined);
|
|
499
|
+
if (origin) await recordOrigin(backend, toId, { label: origin.label, now: origin.createdAt });
|
|
500
|
+
const lease = await readLease(backend, fromId).catch(() => undefined);
|
|
501
|
+
if (!lease) return {};
|
|
502
|
+
await releaseLeaseFor(backend, fromId);
|
|
503
|
+
const { token } = await claimLease(backend, toId, { label: lease.label, ttlMs: lease.ttlMs, auto: lease.auto === true });
|
|
504
|
+
return { lease: token };
|
|
474
505
|
}
|
|
475
506
|
|
|
476
507
|
/* ------------------------------ navigation (2) ------------------------------ */
|
package/src/toolDocs.ts
CHANGED
|
@@ -3,7 +3,7 @@ export type ToolDoc = { readonly description: string; readonly params: Record<st
|
|
|
3
3
|
|
|
4
4
|
export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
5
5
|
"list_pages": {
|
|
6
|
-
"description": "Enumerate browser page targets (GET /json/list); page-type tabs only unless all=true, which also lists workers and out-of-process (OOPIF) iframes. Each entry carries its targetId plus an origin field: 'agent' means this toolkit created it (also carries the creating label/createdAt, and stays 'agent' after the lease is released or the creator dies, making stray agent tabs findable), 'unknown' means no creation record - it never says 'human', the honest word for any tab it did not create; a record that exists but won't read adds originUnreadable. An entry under an active, readable lease also carries a 'lease' object {label,pid,idleMs,expiresAt,stale}, with idleMs and expiresAt computed fresh every call (never off disk), independent of probe. Under CDP_REQUIRE_LEASE this call also reaps abandoned agent tabs into an additive reaped array - but a lease reads reclaimable the moment its TTL elapses, while the tab is CLOSED only after a further grace (CDP_REAP_GRACE_MS, default 2700000ms/45min, so 60min total after last use); a dead-pid lease is reaped at once, a tab with no lease never. With probe, each page-type entry also gets 'responsive' (and humanActiveMs where human input is seen); both are absent, never false/null, without probe.",
|
|
6
|
+
"description": "Enumerate browser page targets (GET /json/list); page-type tabs only unless all=true, which also lists workers and out-of-process (OOPIF) iframes. Each entry carries its targetId plus an origin field: 'agent' means this toolkit created it (also carries the creating label/createdAt, and stays 'agent' after the lease is released or the creator dies, making stray agent tabs findable), 'unknown' means no creation record - it never says 'human', the honest word for any tab it did not create; a record that exists but won't read adds originUnreadable. An entry under an active, readable lease also carries a 'lease' object {label,pid,idleMs,expiresAt,stale}, with idleMs and expiresAt computed fresh every call (never off disk), independent of probe. Under CDP_REQUIRE_LEASE this call also reaps abandoned agent tabs into an additive reaped array - but a lease reads reclaimable the moment its TTL elapses, while the tab is CLOSED only after a further grace (CDP_REAP_GRACE_MS, default 2700000ms/45min, so 60min total after last use); a dead-pid lease is reaped at once, a tab with no lease never. With probe, each page-type entry also gets 'responsive' (and humanActiveMs where human input is seen); both are absent, never false/null, without probe. Under CDP_HIDDEN_TABS=1 (MCP server, Chrome), a tab this server opened hidden carries hidden:true: it is live and drivable but in no browser window, so the user cannot see it (select_page focus:true reveals it); hidden tabs are listed after the visible ones.",
|
|
7
7
|
"params": {
|
|
8
8
|
"lease": "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
|
|
9
9
|
"all": "Include non-page targets (service/shared workers, background pages, out-of-process (OOPIF) iframes); default false lists page-type tabs only. A returned non-page targetId is accepted as a bare id by any tool's `target` param.",
|
|
@@ -13,7 +13,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
13
13
|
}
|
|
14
14
|
},
|
|
15
15
|
"new_page": {
|
|
16
|
-
"description": "Open a new browser tab via Target.createTarget and return {targetId,url}. The tab opens in the BACKGROUND (createTarget background:true; browsingContext.create background:true on Firefox), so the user's visible tab and keyboard focus stay put (on macOS the user's frontmost app is put back if the browser app came forward; CDP_RESTORE_FRONT_APP=0 turns that off); pass focus:true to open it in the foreground. Defaults to about:blank; navigation is not awaited here (use navigate_page to load and wait).",
|
|
16
|
+
"description": "Open a new browser tab via Target.createTarget and return {targetId,url}. The tab opens in the BACKGROUND (createTarget background:true; browsingContext.create background:true on Firefox), so the user's visible tab and keyboard focus stay put (on macOS the user's frontmost app is put back if the browser app came forward; CDP_RESTORE_FRONT_APP=0 turns that off); pass focus:true to open it in the foreground. Under CDP_HIDDEN_TABS=1 (MCP server, Chrome; ignored by the CLI) a non-focus new_page opens a HIDDEN tab instead (createTarget hidden:true): the browser app never comes forward, the result carries hidden:true, the tab is fully drivable (1280x800 emulated viewport, screenshots, clicks, typing, same cookies/logins) but the user cannot see it, it dies if this server or the browser restarts (later calls on its id fail no-such-target), and at most CDP_HIDDEN_TABS_MAX (default 20) may be open at once (new_page then refuses and names them; close_page frees one). Use select_page focus:true to show one to the user. Defaults to about:blank; navigation is not awaited here (use navigate_page to load and wait).",
|
|
17
17
|
"params": {
|
|
18
18
|
"lease": "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
|
|
19
19
|
"url": "URL to open in the new tab; defaults to about:blank.",
|
|
@@ -21,22 +21,22 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
|
|
|
21
21
|
"claim": "Claim the new tab atomically and return a lease token alongside {targetId,url}. Under CDP_REQUIRE_LEASE the tab is claimed and a lease returned even without claim:true; claim:true makes it an EXPLICIT lease that demands its token on every later call, even from this process. Default false.",
|
|
22
22
|
"label": "Agent label recorded on the lease when the tab is claimed; surfaced in conflict errors and list_leases. Defaults to pid-<pid>.",
|
|
23
23
|
"ttlMs": "How long a claimed lease survives without use before it is reclaimable. Defaults to CDP_LEASE_TTL_MS, else 900000 (15min); every checked call refreshes it. Ignored when not claiming.",
|
|
24
|
-
"focus": "Open the tab in the foreground, switching the user's visible tab and taking focus. Default false: the tab opens in the background."
|
|
24
|
+
"focus": "Open the tab in the foreground, switching the user's visible tab and taking focus. Default false: the tab opens in the background (a hidden tab under CDP_HIDDEN_TABS=1)."
|
|
25
25
|
}
|
|
26
26
|
},
|
|
27
27
|
"close_page": {
|
|
28
|
-
"description": "Close a page target via Target.closeTarget. Requires an explicit, resolvable target; errors rather than guessing when the selector matches nothing.",
|
|
28
|
+
"description": "Close a page target via Target.closeTarget. Requires an explicit, resolvable target; errors rather than guessing when the selector matches nothing. A hidden tab (CDP_HIDDEN_TABS) is closed over the connection that keeps it alive, and closing it never brings the browser forward.",
|
|
29
29
|
"params": {
|
|
30
30
|
"lease": "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
|
|
31
31
|
"target": "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Prefix any of these with 'endpoint:<name>/' for a named CDP endpoint (Chrome only). Grammar: see server instructions."
|
|
32
32
|
}
|
|
33
33
|
},
|
|
34
34
|
"select_page": {
|
|
35
|
-
"description": "Persist a page target's bare targetId to the selected-state file (CDP_STATE_DIR/selected) and return {selected,focused}. By default it does NOT raise the tab: the user's visible tab and window focus stay put. focus:true also activates it (Target.activateTarget; browsingContext.activate on Firefox), which was the old default. Requires an explicit, resolvable target.",
|
|
35
|
+
"description": "Persist a page target's bare targetId to the selected-state file (CDP_STATE_DIR/selected) and return {selected,focused}. By default it does NOT raise the tab: the user's visible tab and window focus stay put. focus:true also activates it (Target.activateTarget; browsingContext.activate on Firefox), which was the old default. focus:true on a hidden tab (list_pages hidden:true, CDP_HIDDEN_TABS) cannot raise it in place: its current URL is opened in a new VISIBLE foreground tab, the hidden tab is closed, and the result's selected is the NEW targetId with revealedFrom naming the old one (its label moves along; a lease moves too and its new token comes back as lease). In-page state the URL does not carry (form input, scroll position) is lost. Requires an explicit, resolvable target.",
|
|
36
36
|
"params": {
|
|
37
37
|
"lease": "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
|
|
38
38
|
"target": "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Prefix any of these with 'endpoint:<name>/' for a named CDP endpoint (Chrome only). Grammar: see server instructions.",
|
|
39
|
-
"focus": "Also raise the tab and take window focus (Target.activateTarget / browsingContext.activate). Default false: selection only."
|
|
39
|
+
"focus": "Also raise the tab and take window focus (Target.activateTarget / browsingContext.activate); a hidden tab is reopened visibly under a new targetId instead. Default false: selection only."
|
|
40
40
|
}
|
|
41
41
|
},
|
|
42
42
|
"navigate_page": {
|
package/src/types.ts
CHANGED
|
@@ -17,6 +17,9 @@ export interface Target {
|
|
|
17
17
|
/** present on some Chromium builds */
|
|
18
18
|
parentId?: string;
|
|
19
19
|
faviconUrl?: string;
|
|
20
|
+
/** A hidden tab this process owns (CDP_HIDDEN_TABS, see cdp/hiddenTabs.ts). The browser lists
|
|
21
|
+
* it as type "other"; listTargets relabels it "page" and sets this. Absent on every other target. */
|
|
22
|
+
hidden?: boolean;
|
|
20
23
|
}
|
|
21
24
|
|
|
22
25
|
/** Raw CDP response envelope. */
|
package/src/version.ts
CHANGED