turno-browser 0.7.0 → 0.8.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 +13 -0
- package/README.md +5 -1
- package/dist/act.js +4 -29
- package/dist/agent-cursor-overlay.d.ts +10 -0
- package/dist/agent-cursor-overlay.js +50 -5
- package/dist/agent-cursor.d.ts +39 -7
- package/dist/agent-cursor.js +106 -20
- package/dist/cli/flows.js +3 -0
- package/dist/cli/identity.js +3 -4
- package/dist/cli/init.js +4 -2
- package/dist/engine-camoufox.js +1 -0
- package/dist/engine-lightpanda.js +1 -0
- package/dist/host.d.ts +7 -0
- package/dist/host.js +313 -76
- package/dist/human-step-overlay.d.ts +73 -0
- package/dist/human-step-overlay.js +285 -0
- package/dist/human-step.d.ts +128 -0
- package/dist/human-step.js +521 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/live-server.d.ts +7 -3
- package/dist/live-server.js +13 -15
- package/dist/live.d.ts +20 -1
- package/dist/live.js +52 -10
- package/dist/network-redact.d.ts +28 -0
- package/dist/network-redact.js +202 -0
- package/dist/recorder.d.ts +0 -21
- package/dist/recorder.js +1 -41
- package/dist/recordings.d.ts +5 -0
- package/dist/recordings.js +4 -2
- package/dist/redact.d.ts +7 -0
- package/dist/redact.js +32 -1
- package/dist/replay.d.ts +2 -0
- package/dist/replay.js +33 -14
- package/dist/reputation.d.ts +5 -0
- package/dist/reputation.js +12 -7
- package/dist/sensitive.d.ts +79 -0
- package/dist/sensitive.js +275 -0
- package/dist/session.d.ts +12 -0
- package/dist/session.js +24 -0
- package/dist/tools.d.ts +5 -0
- package/dist/tools.js +9 -1
- package/dist/upstream.d.ts +5 -0
- package/dist/watch.d.ts +60 -0
- package/dist/watch.js +114 -0
- package/npm-shrinkwrap.json +2 -2
- package/package.json +1 -1
|
@@ -0,0 +1,521 @@
|
|
|
1
|
+
import { humanStepOverlay } from "./human-step-overlay.js";
|
|
2
|
+
import { describeChanges, formatPause } from "./live.js";
|
|
3
|
+
import { names } from "./names.js";
|
|
4
|
+
import { upstream } from "./upstream.js";
|
|
5
|
+
/**
|
|
6
|
+
* A person step: `browser_request_human`, the tool an agent calls for what only the person may
|
|
7
|
+
* do (a password, a captcha, an emailed code, a second factor, accepting terms or consent).
|
|
8
|
+
*
|
|
9
|
+
* - The tab comes to the front (and its window out of the dock, when Chrome has one), and a
|
|
10
|
+
* banner at the bottom of the page says what to do, with a Done button; a ring marks the
|
|
11
|
+
* target when the agent names one (`human-step-overlay.ts`). The banner is drawn again on each
|
|
12
|
+
* new document while the step lasts, and removed when it ends. The live view shows it too.
|
|
13
|
+
* - The step pauses the browser like the live view's Pause (`live.ts`): every call of every
|
|
14
|
+
* session waits until the step ends, the idle limit and the tab governor hold, a trace stops.
|
|
15
|
+
* Calls already running finish first, so no agent input lands while the person acts.
|
|
16
|
+
* - It ends on the first of: the URL matches or changes, a selector is visible, Done (a trusted
|
|
17
|
+
* click only), the person resumes the agent, the tab closes, the timeout (5 minutes by
|
|
18
|
+
* default, up to 10: typing a password and solving a captcha, or fetching a code from an
|
|
19
|
+
* email, takes minutes, longer than the 2 minutes the live view holds an unplanned pause).
|
|
20
|
+
* - The result says why it ended, where the tab is, what changed in the tabs and how many
|
|
21
|
+
* clicks and changed fields the person made, never what they typed. A page where the person
|
|
22
|
+
* changed a password or code field is held by the vault guard until it navigates, so the
|
|
23
|
+
* script tools cannot read the value back.
|
|
24
|
+
*/
|
|
25
|
+
export const HUMAN_STEP_TOOL = "browser_request_human";
|
|
26
|
+
/** Every person-facing text of the banner, by locale: one place to add a language. */
|
|
27
|
+
const HUMAN_STEP_STRINGS = {
|
|
28
|
+
en: {
|
|
29
|
+
title: "Your turn",
|
|
30
|
+
done: "Done",
|
|
31
|
+
hintDone: "The agent is waiting for you. Press Done when you have finished.",
|
|
32
|
+
hintAuto: "The agent is waiting for you and goes on by itself once this step is done.",
|
|
33
|
+
},
|
|
34
|
+
};
|
|
35
|
+
export const DEFAULT_STEP_TIMEOUT_MS = 5 * 60_000;
|
|
36
|
+
const MAX_STEP_TIMEOUT_MS = 10 * 60_000;
|
|
37
|
+
const MIN_STEP_TIMEOUT_MS = 1_000;
|
|
38
|
+
const MAX_INSTRUCTION = 500;
|
|
39
|
+
/** How often the banner is checked (and drawn again on a new document). */
|
|
40
|
+
const POLL_MS = 150;
|
|
41
|
+
/** How long the step waits for calls already running to finish before it shows the banner. */
|
|
42
|
+
const DRAIN_MS = 15_000;
|
|
43
|
+
/** How often a client that asked for progress hears that the step still waits. */
|
|
44
|
+
const PROGRESS_MS = 15_000;
|
|
45
|
+
const REF = /^(f\d+)?e\d+$/;
|
|
46
|
+
function schema() {
|
|
47
|
+
const z = upstream().utils.z;
|
|
48
|
+
return {
|
|
49
|
+
name: HUMAN_STEP_TOOL,
|
|
50
|
+
title: "Ask the person to do a step",
|
|
51
|
+
description: [
|
|
52
|
+
"Hand the browser to the person for a step only they may do: typing a password, solving a captcha, entering a code from an email or a text message, a second factor, accepting terms or giving consent, or anything that must be their own action.",
|
|
53
|
+
"Never type or click these yourself. The tab comes to the front with a banner that shows your instruction and a Done button, and a ring around the target when you give one.",
|
|
54
|
+
"Every browser call waits while the person acts. The step ends on the first of: the URL matches until.url or changes (until.urlChanges), until.selector is visible, the person presses Done, or the timeout (5 minutes by default, 10 at most).",
|
|
55
|
+
"The result says why it ended, the tab's URL and title, what changed in the tabs and how many clicks and changed fields the person made; it never has what they typed. Take a snapshot before your next action.",
|
|
56
|
+
"Write the instruction for a non-technical person, in their language. The browser must have a window, or the person must have the live view open.",
|
|
57
|
+
].join(" "),
|
|
58
|
+
inputSchema: z.object({
|
|
59
|
+
instruction: z
|
|
60
|
+
.string()
|
|
61
|
+
.describe('What the person should do, in plain words, as the banner shows it (up to 500 characters), for example "Type your password and press Sign in."'),
|
|
62
|
+
element: z
|
|
63
|
+
.string()
|
|
64
|
+
.optional()
|
|
65
|
+
.describe("Human-readable element description used to obtain permission to interact with the element"),
|
|
66
|
+
target: z
|
|
67
|
+
.string()
|
|
68
|
+
.optional()
|
|
69
|
+
.describe("Exact target element reference from the page snapshot, or a unique element selector: the element the banner points the person to"),
|
|
70
|
+
until: z
|
|
71
|
+
.object({
|
|
72
|
+
url: z
|
|
73
|
+
.string()
|
|
74
|
+
.optional()
|
|
75
|
+
.describe("End when the tab's URL matches: a glob (**/dashboard*), a regular expression written /.../, or text the URL contains"),
|
|
76
|
+
urlChanges: z.boolean().optional().describe("End when the tab's URL changes (not just its #fragment)"),
|
|
77
|
+
selector: z.string().optional().describe("End when an element matching this selector is visible"),
|
|
78
|
+
done: z.boolean().optional().describe("Show a Done button the person presses when finished (default true)"),
|
|
79
|
+
timeoutMs: z
|
|
80
|
+
.number()
|
|
81
|
+
.optional()
|
|
82
|
+
.describe("Give up after this many milliseconds (default 300000, from 1000 to 600000)"),
|
|
83
|
+
})
|
|
84
|
+
.optional()
|
|
85
|
+
.describe("When the step ends: the first of these that happens. Without it, when the person presses Done."),
|
|
86
|
+
requireHumanClick: z
|
|
87
|
+
.boolean()
|
|
88
|
+
.optional()
|
|
89
|
+
.describe("Report whether the person's own click landed on the target (needs target)"),
|
|
90
|
+
}),
|
|
91
|
+
type: "action",
|
|
92
|
+
};
|
|
93
|
+
}
|
|
94
|
+
/** The tool. The host runs it (`ctx.human`): it needs the pause gate and the session's tab. */
|
|
95
|
+
export function requestHumanTool() {
|
|
96
|
+
let built;
|
|
97
|
+
return {
|
|
98
|
+
get schema() {
|
|
99
|
+
built ??= schema();
|
|
100
|
+
return built;
|
|
101
|
+
},
|
|
102
|
+
async handle(ctx, params) {
|
|
103
|
+
if (!ctx.human)
|
|
104
|
+
throw new Error(`${HUMAN_STEP_TOOL} runs only in a turno-browser-mcp session`);
|
|
105
|
+
return await ctx.human(params);
|
|
106
|
+
},
|
|
107
|
+
};
|
|
108
|
+
}
|
|
109
|
+
/** The tool's arguments as the step uses them, or why they do not make a step. */
|
|
110
|
+
export function parseStepParams(params) {
|
|
111
|
+
const instruction = typeof params.instruction === "string" ? params.instruction.trim() : "";
|
|
112
|
+
if (!instruction)
|
|
113
|
+
return { error: "instruction must say what the person should do" };
|
|
114
|
+
if (instruction.length > MAX_INSTRUCTION)
|
|
115
|
+
return { error: `instruction is ${instruction.length} characters; keep it to ${MAX_INSTRUCTION}` };
|
|
116
|
+
const until = (params.until ?? {});
|
|
117
|
+
const timeoutMs = until.timeoutMs === undefined ? DEFAULT_STEP_TIMEOUT_MS : Number(until.timeoutMs);
|
|
118
|
+
if (!Number.isFinite(timeoutMs) || timeoutMs < MIN_STEP_TIMEOUT_MS || timeoutMs > MAX_STEP_TIMEOUT_MS)
|
|
119
|
+
return {
|
|
120
|
+
error: `until.timeoutMs must be from ${MIN_STEP_TIMEOUT_MS} to ${MAX_STEP_TIMEOUT_MS} (10 minutes); without it the step waits ${formatPause(DEFAULT_STEP_TIMEOUT_MS)}`,
|
|
121
|
+
};
|
|
122
|
+
const str = (v) => (typeof v === "string" && v.trim() ? v.trim() : undefined);
|
|
123
|
+
const out = {
|
|
124
|
+
instruction,
|
|
125
|
+
urlChanges: until.urlChanges === true,
|
|
126
|
+
done: until.done !== false,
|
|
127
|
+
timeoutMs: Math.round(timeoutMs),
|
|
128
|
+
requireHumanClick: params.requireHumanClick === true,
|
|
129
|
+
};
|
|
130
|
+
const element = str(params.element);
|
|
131
|
+
const target = str(params.target);
|
|
132
|
+
const url = str(until.url);
|
|
133
|
+
const selector = str(until.selector);
|
|
134
|
+
if (element)
|
|
135
|
+
out.element = element;
|
|
136
|
+
if (target)
|
|
137
|
+
out.target = target;
|
|
138
|
+
if (url) {
|
|
139
|
+
const bad = urlPatternError(url);
|
|
140
|
+
if (bad)
|
|
141
|
+
return { error: bad };
|
|
142
|
+
out.url = url;
|
|
143
|
+
}
|
|
144
|
+
if (selector)
|
|
145
|
+
out.selector = selector;
|
|
146
|
+
if (!out.done && !out.url && !out.urlChanges && !out.selector)
|
|
147
|
+
return {
|
|
148
|
+
error: "with until.done false the step needs another way to end: until.url, until.urlChanges or until.selector",
|
|
149
|
+
};
|
|
150
|
+
if (out.requireHumanClick && !out.target)
|
|
151
|
+
return { error: "requireHumanClick needs a target" };
|
|
152
|
+
return out;
|
|
153
|
+
}
|
|
154
|
+
const REGEX_FORM = /^\/(.+)\/([dgimsuvy]*)$/;
|
|
155
|
+
function urlPatternError(pattern) {
|
|
156
|
+
const m = REGEX_FORM.exec(pattern);
|
|
157
|
+
if (!m)
|
|
158
|
+
return undefined;
|
|
159
|
+
try {
|
|
160
|
+
new RegExp(m[1], m[2]);
|
|
161
|
+
return undefined;
|
|
162
|
+
}
|
|
163
|
+
catch (error) {
|
|
164
|
+
return `until.url ${pattern} is not a valid regular expression: ${error.message}`;
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
/**
|
|
168
|
+
* A URL test from `until.url`: `/.../flags` is a regular expression, a pattern with `*` a glob
|
|
169
|
+
* over the whole URL (`*` stops at a `/`, `**` does not), anything else text the URL contains.
|
|
170
|
+
*/
|
|
171
|
+
export function urlMatcher(pattern) {
|
|
172
|
+
const m = REGEX_FORM.exec(pattern);
|
|
173
|
+
if (m) {
|
|
174
|
+
const re = new RegExp(m[1], m[2]?.replace(/[gy]/g, ""));
|
|
175
|
+
return (url) => re.test(url);
|
|
176
|
+
}
|
|
177
|
+
if (pattern.includes("*")) {
|
|
178
|
+
let source = "";
|
|
179
|
+
for (let i = 0; i < pattern.length; i++) {
|
|
180
|
+
const c = pattern[i];
|
|
181
|
+
if (c === "*") {
|
|
182
|
+
if (pattern[i + 1] === "*") {
|
|
183
|
+
source += ".*";
|
|
184
|
+
i++;
|
|
185
|
+
}
|
|
186
|
+
else
|
|
187
|
+
source += "[^/]*";
|
|
188
|
+
}
|
|
189
|
+
else
|
|
190
|
+
source += c.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
|
|
191
|
+
}
|
|
192
|
+
const re = new RegExp(`^${source}$`);
|
|
193
|
+
return (url) => re.test(url);
|
|
194
|
+
}
|
|
195
|
+
return (url) => url.includes(pattern);
|
|
196
|
+
}
|
|
197
|
+
/** A URL without its fragment: a `#` change alone is not a navigation. */
|
|
198
|
+
function withoutHash(url) {
|
|
199
|
+
const at = url.indexOf("#");
|
|
200
|
+
return at < 0 ? url : url.slice(0, at);
|
|
201
|
+
}
|
|
202
|
+
/** Runs the page side in a page or a frame (its utility world); undefined when it does not answer. */
|
|
203
|
+
async function overlay(where, cmd, el) {
|
|
204
|
+
// Playwright passes the handle as the element itself; its types do not follow the union.
|
|
205
|
+
const fn = humanStepOverlay;
|
|
206
|
+
return await where.evaluate(fn, el ? { cmd, el } : { cmd }).catch(() => undefined);
|
|
207
|
+
}
|
|
208
|
+
/** The banner and the target ring of one step on one tab, drawn again on every new document. */
|
|
209
|
+
export class StepBanner {
|
|
210
|
+
page;
|
|
211
|
+
view;
|
|
212
|
+
target;
|
|
213
|
+
docs = new Map();
|
|
214
|
+
latest;
|
|
215
|
+
pressed = false;
|
|
216
|
+
clicked = false;
|
|
217
|
+
constructor(page, view, target) {
|
|
218
|
+
this.page = page;
|
|
219
|
+
this.view = view;
|
|
220
|
+
this.target = target;
|
|
221
|
+
}
|
|
222
|
+
/** Draws the banner (and the ring) on the page as it is now. */
|
|
223
|
+
async show() {
|
|
224
|
+
await this.poll(true);
|
|
225
|
+
}
|
|
226
|
+
/** Reads what the person did, drawing the banner again where a new document has none. */
|
|
227
|
+
async poll(first = false) {
|
|
228
|
+
if (this.page.isClosed())
|
|
229
|
+
return;
|
|
230
|
+
// The ring first: it is on the page no later than the banner that points to it.
|
|
231
|
+
const t = this.target;
|
|
232
|
+
if (t && !t.frame.isDetached()) {
|
|
233
|
+
const mark = await overlay(t.frame, { op: "target", step: this.view.step }, first ? t.handle : undefined);
|
|
234
|
+
if (mark?.target) {
|
|
235
|
+
this.pressed ||= mark.target.pressed;
|
|
236
|
+
this.clicked ||= mark.target.clicked;
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
const report = await overlay(this.page, { op: "banner", view: this.view });
|
|
240
|
+
if (report) {
|
|
241
|
+
if (report.doc)
|
|
242
|
+
this.docs.set(report.doc, report);
|
|
243
|
+
this.latest = report;
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
/** What the person did over every document of the step. */
|
|
247
|
+
totals() {
|
|
248
|
+
let clicks = 0;
|
|
249
|
+
let fields = 0;
|
|
250
|
+
let done = false;
|
|
251
|
+
for (const r of this.docs.values()) {
|
|
252
|
+
clicks += r.clicks;
|
|
253
|
+
fields += r.fields;
|
|
254
|
+
done ||= r.done;
|
|
255
|
+
}
|
|
256
|
+
return {
|
|
257
|
+
done,
|
|
258
|
+
clicks,
|
|
259
|
+
fields,
|
|
260
|
+
// Only the document the tab shows now still holds what was typed.
|
|
261
|
+
sensitive: this.latest?.sensitive === true,
|
|
262
|
+
targetClicked: this.pressed || this.clicked,
|
|
263
|
+
};
|
|
264
|
+
}
|
|
265
|
+
/** Removes the banner and the ring. */
|
|
266
|
+
async remove() {
|
|
267
|
+
if (!this.page.isClosed())
|
|
268
|
+
await overlay(this.page, { op: "remove" });
|
|
269
|
+
const t = this.target;
|
|
270
|
+
if (t && !t.frame.isDetached() && t.frame !== this.page.mainFrame())
|
|
271
|
+
await overlay(t.frame, { op: "remove" });
|
|
272
|
+
await t?.handle.dispose().catch(() => { });
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
function stepError(message, json) {
|
|
276
|
+
return {
|
|
277
|
+
content: [
|
|
278
|
+
{
|
|
279
|
+
type: "text",
|
|
280
|
+
text: json ? JSON.stringify({ isError: true, error: message }, null, 2) : `### Error\n${message}`,
|
|
281
|
+
},
|
|
282
|
+
],
|
|
283
|
+
isError: true,
|
|
284
|
+
};
|
|
285
|
+
}
|
|
286
|
+
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
287
|
+
/** Brings the tab to the front, and its window back when it is minimized. */
|
|
288
|
+
async function toFront(page, window) {
|
|
289
|
+
if (window) {
|
|
290
|
+
try {
|
|
291
|
+
const cdp = await page.context().newCDPSession(page);
|
|
292
|
+
try {
|
|
293
|
+
const { windowId, bounds } = (await cdp.send("Browser.getWindowForTarget"));
|
|
294
|
+
if (bounds.windowState === "minimized")
|
|
295
|
+
await cdp.send("Browser.setWindowBounds", { windowId, bounds: { windowState: "normal" } });
|
|
296
|
+
}
|
|
297
|
+
finally {
|
|
298
|
+
await cdp.detach().catch(() => { });
|
|
299
|
+
}
|
|
300
|
+
}
|
|
301
|
+
catch {
|
|
302
|
+
/* no window to bring back (an engine without the Browser domain) */
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
await page.bringToFront().catch(() => { });
|
|
306
|
+
}
|
|
307
|
+
/** Runs one person step on `deps.page` and says how it went. */
|
|
308
|
+
export async function runHumanStep(params, deps) {
|
|
309
|
+
const { page, watch, json } = deps;
|
|
310
|
+
const now = deps.now ?? Date.now;
|
|
311
|
+
if (deps.unseen)
|
|
312
|
+
return stepError(deps.unseen, json);
|
|
313
|
+
if (page.isClosed())
|
|
314
|
+
return stepError("the current tab is closed; open a page first", json);
|
|
315
|
+
let target;
|
|
316
|
+
if (params.target) {
|
|
317
|
+
const locator = (REF.test(params.target) ? page.getByRef(params.target) : page.locator(params.target)).first();
|
|
318
|
+
const handle = await locator.elementHandle({ timeout: 2_000 }).catch(() => null);
|
|
319
|
+
const frame = handle ? await handle.ownerFrame().catch(() => null) : null;
|
|
320
|
+
if (!handle || !frame)
|
|
321
|
+
return stepError(REF.test(params.target)
|
|
322
|
+
? `Ref ${params.target} not found in the current page snapshot. Try capturing new snapshot.`
|
|
323
|
+
: `"${params.target}" does not match any elements.`, json);
|
|
324
|
+
target = { handle, frame };
|
|
325
|
+
}
|
|
326
|
+
if (params.selector) {
|
|
327
|
+
const bad = await page
|
|
328
|
+
.locator(params.selector)
|
|
329
|
+
.count()
|
|
330
|
+
.then(() => undefined)
|
|
331
|
+
.catch((error) => error.message.split("\n")[0]);
|
|
332
|
+
if (bad) {
|
|
333
|
+
await target?.handle.dispose().catch(() => { });
|
|
334
|
+
return stepError(`until.selector is not a selector the page can use: ${bad}`, json);
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
const began = now();
|
|
338
|
+
const deadline = began + params.timeoutMs;
|
|
339
|
+
const before = await watch.tabStates();
|
|
340
|
+
const startUrl = page.url();
|
|
341
|
+
if (!(await watch.pause(HUMAN_STEP_TOOL, false, { step: true, until: deadline }))) {
|
|
342
|
+
await target?.handle.dispose().catch(() => { });
|
|
343
|
+
const by = watch.gate.paused?.by ?? "the user";
|
|
344
|
+
return stepError(`the browser is paused (${by}); call again once it is resumed`, json);
|
|
345
|
+
}
|
|
346
|
+
const mine = watch.gate.paused?.since;
|
|
347
|
+
watch.follow(deps.session, page);
|
|
348
|
+
// Calls that started before the pause finish first: their input is the agent's, not the person's.
|
|
349
|
+
const drainEnd = now() + (deps.drainMs ?? DRAIN_MS);
|
|
350
|
+
while (watch.inFlight > 0 && now() < drainEnd)
|
|
351
|
+
await sleep(25);
|
|
352
|
+
const strings = HUMAN_STEP_STRINGS[deps.locale ?? "en"];
|
|
353
|
+
const view = {
|
|
354
|
+
step: `${began.toString(36)}${Math.random().toString(36).slice(2, 8)}`,
|
|
355
|
+
lang: deps.locale ?? "en",
|
|
356
|
+
title: strings.title,
|
|
357
|
+
instruction: params.instruction,
|
|
358
|
+
hint: params.done ? strings.hintDone : strings.hintAuto,
|
|
359
|
+
done: params.done ? strings.done : null,
|
|
360
|
+
};
|
|
361
|
+
const banner = new StepBanner(page, view, target);
|
|
362
|
+
let wake;
|
|
363
|
+
const kick = () => wake?.();
|
|
364
|
+
// A navigation starts while the old document still answers: read it once more first.
|
|
365
|
+
const onRequest = (request) => {
|
|
366
|
+
if (request.isNavigationRequest() && request.frame() === page.mainFrame())
|
|
367
|
+
kick();
|
|
368
|
+
};
|
|
369
|
+
page.on("request", onRequest);
|
|
370
|
+
page.on("domcontentloaded", kick);
|
|
371
|
+
page.on("close", kick);
|
|
372
|
+
deps.signal?.addEventListener("abort", kick);
|
|
373
|
+
const matches = params.url ? urlMatcher(params.url) : undefined;
|
|
374
|
+
let ended;
|
|
375
|
+
const ours = () => watch.gate.paused?.since === mine;
|
|
376
|
+
try {
|
|
377
|
+
await toFront(page, deps.window);
|
|
378
|
+
await banner.show();
|
|
379
|
+
let told = began;
|
|
380
|
+
const pollMs = deps.pollMs ?? POLL_MS;
|
|
381
|
+
for (;;) {
|
|
382
|
+
await banner.poll();
|
|
383
|
+
const paused = watch.gate.paused;
|
|
384
|
+
if (page.isClosed())
|
|
385
|
+
ended = "closed";
|
|
386
|
+
else if (deps.signal?.aborted)
|
|
387
|
+
ended = "cancelled";
|
|
388
|
+
else if (!paused || paused.since !== mine)
|
|
389
|
+
ended = "resumed";
|
|
390
|
+
else if (banner.totals().done)
|
|
391
|
+
ended = "done";
|
|
392
|
+
else if (matches?.(page.url()))
|
|
393
|
+
ended = "url";
|
|
394
|
+
else if (params.urlChanges && withoutHash(page.url()) !== withoutHash(startUrl))
|
|
395
|
+
ended = "url-changed";
|
|
396
|
+
else if (params.selector &&
|
|
397
|
+
(await page
|
|
398
|
+
.locator(params.selector)
|
|
399
|
+
.first()
|
|
400
|
+
.isVisible()
|
|
401
|
+
.catch(() => false)))
|
|
402
|
+
ended = "selector";
|
|
403
|
+
else if (now() >= deadline)
|
|
404
|
+
ended = "timeout";
|
|
405
|
+
if (ended) {
|
|
406
|
+
// What ended the step (a click that showed the selector, say) came after the poll above: read it once more.
|
|
407
|
+
if (ended !== "closed")
|
|
408
|
+
await banner.poll();
|
|
409
|
+
break;
|
|
410
|
+
}
|
|
411
|
+
if (deps.progress && now() - told >= PROGRESS_MS) {
|
|
412
|
+
told = now();
|
|
413
|
+
deps.progress(told - began, `Waiting for the person (${formatPause(told - began)})`);
|
|
414
|
+
}
|
|
415
|
+
await new Promise((r) => {
|
|
416
|
+
const timer = setTimeout(r, Math.max(0, Math.min(pollMs, deadline - now())));
|
|
417
|
+
wake = () => {
|
|
418
|
+
clearTimeout(timer);
|
|
419
|
+
r();
|
|
420
|
+
};
|
|
421
|
+
});
|
|
422
|
+
wake = undefined;
|
|
423
|
+
}
|
|
424
|
+
}
|
|
425
|
+
catch (error) {
|
|
426
|
+
// Never leave the browser held: the calls waiting for the step go on.
|
|
427
|
+
if (ours())
|
|
428
|
+
watch.resume();
|
|
429
|
+
throw error;
|
|
430
|
+
}
|
|
431
|
+
finally {
|
|
432
|
+
page.off("request", onRequest);
|
|
433
|
+
page.off("domcontentloaded", kick);
|
|
434
|
+
page.off("close", kick);
|
|
435
|
+
deps.signal?.removeEventListener("abort", kick);
|
|
436
|
+
await banner.remove();
|
|
437
|
+
}
|
|
438
|
+
const totals = banner.totals();
|
|
439
|
+
// A password or code the person typed stays in the page until it navigates: no script reads it back.
|
|
440
|
+
if (totals.sensitive && !page.isClosed())
|
|
441
|
+
deps.guard.mark(page);
|
|
442
|
+
const after = await watch.tabStates();
|
|
443
|
+
const liveInputs = watch.gate.inputsOf(mine);
|
|
444
|
+
if (ours())
|
|
445
|
+
watch.resume();
|
|
446
|
+
const current = deps.currentPage() ?? (page.isClosed() ? undefined : page);
|
|
447
|
+
const { lines } = describeChanges(before, after, watch.idOf(page), current ? watch.idOf(current) : undefined, liveInputs);
|
|
448
|
+
const state = current ? after.find((t) => t.id === watch.idOf(current)) : undefined;
|
|
449
|
+
return stepResult({
|
|
450
|
+
params,
|
|
451
|
+
ended: ended ?? "timeout",
|
|
452
|
+
waitedMs: now() - began,
|
|
453
|
+
url: state?.url ?? (current?.url() || undefined),
|
|
454
|
+
title: state?.title,
|
|
455
|
+
lines,
|
|
456
|
+
clicks: totals.clicks,
|
|
457
|
+
fields: totals.fields,
|
|
458
|
+
liveInputs,
|
|
459
|
+
...(params.requireHumanClick ? { targetClicked: totals.targetClicked } : {}),
|
|
460
|
+
json,
|
|
461
|
+
});
|
|
462
|
+
}
|
|
463
|
+
/** Why the step ended, in a sentence. */
|
|
464
|
+
function endText(ended, params) {
|
|
465
|
+
switch (ended) {
|
|
466
|
+
case "done":
|
|
467
|
+
return "the person pressed Done";
|
|
468
|
+
case "url":
|
|
469
|
+
return `the tab's URL matched ${params.url}`;
|
|
470
|
+
case "url-changed":
|
|
471
|
+
return "the tab's URL changed";
|
|
472
|
+
case "selector":
|
|
473
|
+
return `${params.selector} is visible`;
|
|
474
|
+
case "resumed":
|
|
475
|
+
return `the person resumed the agent (Resume in the live view, or ${names().browser} resume)`;
|
|
476
|
+
case "closed":
|
|
477
|
+
return "the tab was closed";
|
|
478
|
+
case "timeout":
|
|
479
|
+
return `nothing ended the step within ${formatPause(params.timeoutMs)}`;
|
|
480
|
+
case "cancelled":
|
|
481
|
+
return "the call was cancelled";
|
|
482
|
+
}
|
|
483
|
+
}
|
|
484
|
+
const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
|
|
485
|
+
/** The result of a step: why it ended and what changed, never a value the person typed. */
|
|
486
|
+
export function stepResult(o) {
|
|
487
|
+
const isError = o.ended === "timeout" || o.ended === "cancelled";
|
|
488
|
+
const why = endText(o.ended, o.params);
|
|
489
|
+
if (o.json) {
|
|
490
|
+
const payload = {
|
|
491
|
+
...(isError ? { isError: true } : {}),
|
|
492
|
+
ended: o.ended,
|
|
493
|
+
reason: why,
|
|
494
|
+
waitedMs: o.waitedMs,
|
|
495
|
+
...(o.url !== undefined ? { url: o.url } : {}),
|
|
496
|
+
...(o.title !== undefined ? { title: o.title } : {}),
|
|
497
|
+
changes: o.lines,
|
|
498
|
+
clicks: o.clicks,
|
|
499
|
+
fieldsChanged: o.fields,
|
|
500
|
+
liveViewInputs: o.liveInputs,
|
|
501
|
+
...(o.targetClicked !== undefined ? { targetClicked: o.targetClicked } : {}),
|
|
502
|
+
};
|
|
503
|
+
return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], ...(isError ? { isError } : {}) };
|
|
504
|
+
}
|
|
505
|
+
const out = [isError ? "### Error" : "### Person step"];
|
|
506
|
+
out.push(`The step ended after ${formatPause(o.waitedMs)}: ${why}.`);
|
|
507
|
+
if (o.url !== undefined)
|
|
508
|
+
out.push(`Current tab: ${o.url}${o.title ? ` (${JSON.stringify(o.title)})` : ""}`);
|
|
509
|
+
out.push("While the person had the browser:");
|
|
510
|
+
const lines = [...o.lines];
|
|
511
|
+
if (o.clicks || o.fields)
|
|
512
|
+
lines.push(`In the page, the person clicked ${plural(o.clicks, "time", "times")} and changed ${plural(o.fields, "field", "fields")} (what they typed is never read).`);
|
|
513
|
+
if (!lines.length)
|
|
514
|
+
lines.push("Nothing changed in the browser's tabs, and the person made no input.");
|
|
515
|
+
out.push(...lines.map((l) => `- ${l}`));
|
|
516
|
+
if (o.targetClicked !== undefined)
|
|
517
|
+
out.push(o.targetClicked ? "The person clicked the target themselves." : "The person did not click the target themselves.");
|
|
518
|
+
out.push("Take a snapshot before your next action: the refs of your last snapshot may point elsewhere now.");
|
|
519
|
+
return { content: [{ type: "text", text: out.join("\n") }], ...(isError ? { isError } : {}) };
|
|
520
|
+
}
|
|
521
|
+
//# sourceMappingURL=human-step.js.map
|
package/dist/index.d.ts
CHANGED
|
@@ -2,7 +2,7 @@ export { API_VERSION, type ApiVersion, type BrowserApi, type BrowserFunctions, a
|
|
|
2
2
|
export { type BrowserCli, browserCli as cli } from "./cli/commands.js";
|
|
3
3
|
export type { BrowserCliHost, CliDeps, CliNames, OpenUrl, VaultInput } from "./cli/context.js";
|
|
4
4
|
export type { DoSession, DoSessionInfo, DoTarget, DoTransport, ToolResult } from "./cli/do.js";
|
|
5
|
-
export { SESSION_CAPABILITY, SESSION_ENDED_METHOD, SESSION_META_KEY } from "./session.js";
|
|
5
|
+
export { CLIENT_META_KEY, SESSION_CAPABILITY, SESSION_ENDED_METHOD, SESSION_META_KEY } from "./session.js";
|
|
6
6
|
export { manifestSnippet } from "./snippet.js";
|
|
7
7
|
export { IdentityError, type IdentityInfo, addIdentity, assertIdentityId, identityDir, identityExists, identityStateDir, inUseBy, isInUse, isValidIdentityId, listIdentities, parseSingletonLock, removeIdentity, } from "./identities.js";
|
|
8
8
|
export { type HealthCheck, IDENTITY_FORMAT_VERSION, type IdentitySettings, type LiveSettings, type RecordSettings, type SettingsPatch, type TabLockSettings, checkIdentitySettings, identitySettingsPath, readIdentitySettings, systemTimezone, writeIdentitySettings, } from "./settings.js";
|
package/dist/index.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { fileURLToPath } from "node:url";
|
|
2
2
|
export { API_VERSION, api } from "./api.js";
|
|
3
3
|
export { browserCli as cli } from "./cli/commands.js";
|
|
4
|
-
export { SESSION_CAPABILITY, SESSION_ENDED_METHOD, SESSION_META_KEY } from "./session.js";
|
|
4
|
+
export { CLIENT_META_KEY, SESSION_CAPABILITY, SESSION_ENDED_METHOD, SESSION_META_KEY } from "./session.js";
|
|
5
5
|
export { manifestSnippet } from "./snippet.js";
|
|
6
6
|
export { IdentityError, addIdentity, assertIdentityId, identityDir, identityExists, identityStateDir, inUseBy, isInUse, isValidIdentityId, listIdentities, parseSingletonLock, removeIdentity, } from "./identities.js";
|
|
7
7
|
export { IDENTITY_FORMAT_VERSION, checkIdentitySettings, identitySettingsPath, readIdentitySettings, systemTimezone, writeIdentitySettings, } from "./settings.js";
|
package/dist/live-server.d.ts
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
import type { BrowserContext, Page } from "patchright-core";
|
|
2
2
|
import type { IdentityRef } from "./engine.js";
|
|
3
|
-
import { type LivePolicy, PauseGate, type TabState } from "./live.js";
|
|
3
|
+
import { type LivePolicy, PauseGate, type PauseHold, type TabState } from "./live.js";
|
|
4
4
|
import type { Redactor, VaultGuard } from "./redact.js";
|
|
5
|
+
import { type BrowserWatch } from "./watch.js";
|
|
5
6
|
/**
|
|
6
7
|
* The live view server of one turno-browser-mcp process, when identity.json `live.enabled` or
|
|
7
8
|
* `--live` turns it on (off by default).
|
|
@@ -87,7 +88,7 @@ export interface LiveServerOptions {
|
|
|
87
88
|
/** A line for stderr (the server's log); never a token or a code. */
|
|
88
89
|
log?(line: string): void;
|
|
89
90
|
}
|
|
90
|
-
export declare class LiveServer {
|
|
91
|
+
export declare class LiveServer implements BrowserWatch {
|
|
91
92
|
private readonly o;
|
|
92
93
|
readonly gate: PauseGate;
|
|
93
94
|
private browser;
|
|
@@ -117,6 +118,9 @@ export declare class LiveServer {
|
|
|
117
118
|
constructor(o: LiveServerOptions);
|
|
118
119
|
get paused(): boolean;
|
|
119
120
|
get waitMs(): number;
|
|
121
|
+
get inFlight(): number;
|
|
122
|
+
/** Views open now. */
|
|
123
|
+
get viewerCount(): number;
|
|
120
124
|
/** The control socket path (tests). */
|
|
121
125
|
get socket(): string | undefined;
|
|
122
126
|
private get cookieName();
|
|
@@ -144,7 +148,7 @@ export declare class LiveServer {
|
|
|
144
148
|
/** The tabs now, as the note compares them. */
|
|
145
149
|
tabStates(): Promise<TabState[]>;
|
|
146
150
|
/** Pauses the agent. `front`: bring the shown tab to the front of a headed window. */
|
|
147
|
-
pause(by: string, front?: boolean): Promise<boolean>;
|
|
151
|
+
pause(by: string, front?: boolean, hold?: PauseHold): Promise<boolean>;
|
|
148
152
|
resume(): boolean;
|
|
149
153
|
/** The tab the view shows: the one picked, else the agent's latest, else the first. */
|
|
150
154
|
private target;
|
package/dist/live-server.js
CHANGED
|
@@ -6,6 +6,7 @@ import { dirname, join } from "node:path";
|
|
|
6
6
|
import { PauseGate, liveFilePath } from "./live.js";
|
|
7
7
|
import { deniedPage, livePage } from "./live-page.js";
|
|
8
8
|
import { names } from "./names.js";
|
|
9
|
+
import { titleOf } from "./watch.js";
|
|
9
10
|
/** How long a link's code works. */
|
|
10
11
|
const CODE_MS = 2 * 60_000;
|
|
11
12
|
/** Largest request body accepted. */
|
|
@@ -42,18 +43,6 @@ function plainUrl(url) {
|
|
|
42
43
|
return "";
|
|
43
44
|
}
|
|
44
45
|
}
|
|
45
|
-
async function titleOf(page) {
|
|
46
|
-
let timer;
|
|
47
|
-
const late = new Promise((r) => {
|
|
48
|
-
timer = setTimeout(() => r(""), 1_000);
|
|
49
|
-
});
|
|
50
|
-
try {
|
|
51
|
-
return await Promise.race([page.title().catch(() => ""), late]);
|
|
52
|
-
}
|
|
53
|
-
finally {
|
|
54
|
-
clearTimeout(timer);
|
|
55
|
-
}
|
|
56
|
-
}
|
|
57
46
|
function sameSecret(a, b) {
|
|
58
47
|
const x = Buffer.from(a);
|
|
59
48
|
const y = Buffer.from(b);
|
|
@@ -130,6 +119,13 @@ export class LiveServer {
|
|
|
130
119
|
get waitMs() {
|
|
131
120
|
return this.o.policy.waitMs;
|
|
132
121
|
}
|
|
122
|
+
get inFlight() {
|
|
123
|
+
return this.busy;
|
|
124
|
+
}
|
|
125
|
+
/** Views open now. */
|
|
126
|
+
get viewerCount() {
|
|
127
|
+
return this.viewers.size;
|
|
128
|
+
}
|
|
133
129
|
/** The control socket path (tests). */
|
|
134
130
|
get socket() {
|
|
135
131
|
return this.socketDir && join(this.socketDir, "control.sock");
|
|
@@ -292,10 +288,12 @@ export class LiveServer {
|
|
|
292
288
|
return await Promise.all(this.pages().map(async (p) => ({ id: this.idOf(p), url: this.urlOf(p), title: await titleOf(p) })));
|
|
293
289
|
}
|
|
294
290
|
/** Pauses the agent. `front`: bring the shown tab to the front of a headed window. */
|
|
295
|
-
async pause(by, front = false) {
|
|
296
|
-
if (!this.gate.start(by, this.tabStates()))
|
|
291
|
+
async pause(by, front = false, hold = {}) {
|
|
292
|
+
if (!this.gate.start(by, this.tabStates(), hold))
|
|
297
293
|
return false;
|
|
298
|
-
this.o.log?.(
|
|
294
|
+
this.o.log?.(hold.step
|
|
295
|
+
? `"${this.o.identity.id}" waits for the person (${by}); every call waits until the step ends`
|
|
296
|
+
: `"${this.o.identity.id}" paused (${by}); the agent's next call waits up to ${this.o.policy.waitMs / 1000}s`);
|
|
299
297
|
const b = this.browser;
|
|
300
298
|
if (b) {
|
|
301
299
|
this.heldBrowser = b;
|