turno-browser 0.2.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +228 -0
- package/README.md +205 -16
- package/dist/act-model.d.ts +85 -0
- package/dist/act-model.js +116 -0
- package/dist/act.d.ts +37 -0
- package/dist/act.js +599 -0
- package/dist/api.d.ts +96 -0
- package/dist/api.js +88 -0
- package/dist/argv.d.ts +55 -3
- package/dist/argv.js +190 -10
- package/dist/batch.d.ts +19 -0
- package/dist/batch.js +148 -0
- package/dist/bench.d.ts +1 -1
- package/dist/bench.js +21 -5
- package/dist/bin/mcp.js +108 -12
- package/dist/captcha.d.ts +77 -0
- package/dist/captcha.js +333 -0
- package/dist/cdp-relay.d.ts +20 -0
- package/dist/cdp-relay.js +101 -0
- package/dist/chrome-features.d.ts +23 -0
- package/dist/chrome-features.js +44 -0
- package/dist/detectors.d.ts +11 -0
- package/dist/detectors.js +46 -4
- package/dist/diagnose.d.ts +45 -0
- package/dist/diagnose.js +326 -0
- package/dist/doctor.d.ts +85 -0
- package/dist/doctor.js +556 -0
- package/dist/engine-attach.d.ts +27 -0
- package/dist/engine-attach.js +165 -0
- package/dist/engine-camoufox.d.ts +32 -0
- package/dist/engine-camoufox.js +270 -0
- package/dist/engine-lightpanda.d.ts +72 -0
- package/dist/engine-lightpanda.js +292 -0
- package/dist/engine.d.ts +119 -0
- package/dist/engine.js +355 -0
- package/dist/flows.d.ts +127 -0
- package/dist/flows.js +294 -0
- package/dist/governor.d.ts +119 -0
- package/dist/governor.js +325 -0
- package/dist/health.d.ts +60 -0
- package/dist/health.js +86 -0
- package/dist/host.d.ts +95 -0
- package/dist/host.js +1181 -0
- package/dist/human-input.d.ts +84 -0
- package/dist/human-input.js +443 -0
- package/dist/humanize.d.ts +123 -0
- package/dist/humanize.js +241 -0
- package/dist/identities.d.ts +23 -10
- package/dist/identities.js +45 -37
- package/dist/idle-timer.d.ts +12 -0
- package/dist/idle-timer.js +25 -0
- package/dist/ids.d.ts +9 -0
- package/dist/ids.js +34 -0
- package/dist/index.d.ts +21 -6
- package/dist/index.js +19 -18
- package/dist/lifecycle.d.ts +99 -0
- package/dist/lifecycle.js +172 -0
- package/dist/live-client.d.ts +22 -0
- package/dist/live-client.js +93 -0
- package/dist/live-page.d.ts +11 -0
- package/dist/live-page.js +143 -0
- package/dist/live-server.d.ts +173 -0
- package/dist/live-server.js +640 -0
- package/dist/live.d.ts +120 -0
- package/dist/live.js +203 -0
- package/dist/login-tool.d.ts +45 -0
- package/dist/login-tool.js +233 -0
- package/dist/login.d.ts +8 -3
- package/dist/login.js +65 -26
- package/dist/network-chrome.d.ts +74 -0
- package/dist/network-chrome.js +178 -0
- package/dist/network.d.ts +125 -0
- package/dist/network.js +263 -0
- package/dist/opt-in-settings.d.ts +69 -0
- package/dist/opt-in-settings.js +151 -0
- package/dist/patchright.d.ts +4 -2
- package/dist/patchright.js +4 -2
- package/dist/recorder.d.ts +88 -0
- package/dist/recorder.js +538 -0
- package/dist/recordings.d.ts +116 -0
- package/dist/recordings.js +474 -0
- package/dist/redact.d.ts +34 -0
- package/dist/redact.js +135 -0
- package/dist/replay.d.ts +20 -0
- package/dist/replay.js +382 -0
- package/dist/reputation.d.ts +89 -0
- package/dist/reputation.js +203 -0
- package/dist/resources.d.ts +76 -0
- package/dist/resources.js +341 -0
- package/dist/runtime-lock.d.ts +59 -0
- package/dist/runtime-lock.js +131 -0
- package/dist/sealed.d.ts +8 -0
- package/dist/sealed.js +96 -0
- package/dist/session-export.d.ts +67 -0
- package/dist/session-export.js +194 -0
- package/dist/session.d.ts +20 -0
- package/dist/session.js +30 -0
- package/dist/settings.d.ts +246 -0
- package/dist/settings.js +530 -0
- package/dist/sharing.d.ts +96 -0
- package/dist/sharing.js +269 -0
- package/dist/snippet.d.ts +8 -0
- package/dist/snippet.js +22 -0
- package/dist/tab-locks.d.ts +63 -0
- package/dist/tab-locks.js +179 -0
- package/dist/tools.d.ts +111 -0
- package/dist/tools.js +59 -0
- package/dist/totp.d.ts +32 -0
- package/dist/totp.js +82 -0
- package/dist/tuning.d.ts +76 -0
- package/dist/tuning.js +69 -0
- package/dist/units.d.ts +8 -0
- package/dist/units.js +20 -0
- package/dist/upstream.d.ts +243 -0
- package/dist/upstream.js +46 -0
- package/dist/vault.d.ts +91 -0
- package/dist/vault.js +273 -0
- package/npm-shrinkwrap.json +1074 -3
- package/package.json +5 -4
- package/dist/paths.d.ts +0 -17
- package/dist/paths.js +0 -17
package/dist/replay.js
ADDED
|
@@ -0,0 +1,382 @@
|
|
|
1
|
+
import { fileURLToPath } from "node:url";
|
|
2
|
+
import { secretStore } from "turno-core/secrets";
|
|
3
|
+
import { FlowError, describeStep, fillParams, listFlows, paramRefs, readFlow, resolveParams, setPath, } from "./flows.js";
|
|
4
|
+
import { loginTool } from "./login-tool.js";
|
|
5
|
+
import { upstream } from "./upstream.js";
|
|
6
|
+
/**
|
|
7
|
+
* `browser_replay` and `browser_flows`: run a saved flow again, and list the saved ones.
|
|
8
|
+
*
|
|
9
|
+
* Each step runs through the same path as a call of its own (tab governor, click diagnosis,
|
|
10
|
+
* recordings), with the element found again from the step's locators, in order: the first that
|
|
11
|
+
* matches exactly one visible element is passed to the stock tool as its target. When a step
|
|
12
|
+
* fails, the replay stops and says which step, every locator it tried and why each did not
|
|
13
|
+
* fit, which steps did not run, and how to continue (`from`), with a fresh snapshot of the page:
|
|
14
|
+
* the agent does that step by hand and lets the replay go on.
|
|
15
|
+
*
|
|
16
|
+
* Parameters: a sensitive one (no stored value) must be given. A value written
|
|
17
|
+
* `keychain:<item>` is read from the secret store (`turno secret set <item>`), so the model
|
|
18
|
+
* never sees it; every sensitive or secret-store value joins the redactor, and before one goes
|
|
19
|
+
* into a page the recording stops its trace and holds the page like a vault fill.
|
|
20
|
+
*/
|
|
21
|
+
/** Longest wait for one step's element, in seconds. */
|
|
22
|
+
const MAX_WAIT_S = 30;
|
|
23
|
+
const DEFAULT_WAIT_S = 5;
|
|
24
|
+
/** How deep a flow may replay other flows. */
|
|
25
|
+
const MAX_DEPTH = 3;
|
|
26
|
+
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
27
|
+
function textOf(result) {
|
|
28
|
+
return result.content
|
|
29
|
+
.filter((c) => c.type === "text")
|
|
30
|
+
.map((c) => c.text)
|
|
31
|
+
.join("\n");
|
|
32
|
+
}
|
|
33
|
+
/** The sections of an upstream result text (`### Title` then the body). */
|
|
34
|
+
function sections(text) {
|
|
35
|
+
const out = new Map();
|
|
36
|
+
for (const part of text.split(/^### /m).slice(1)) {
|
|
37
|
+
const nl = part.indexOf("\n");
|
|
38
|
+
if (nl < 0)
|
|
39
|
+
continue;
|
|
40
|
+
out.set(part.slice(0, nl), part.slice(nl + 1).trim());
|
|
41
|
+
}
|
|
42
|
+
return out;
|
|
43
|
+
}
|
|
44
|
+
/** The first locator of a target that finds exactly one visible element, waiting up to `ms`. */
|
|
45
|
+
async function findTarget(stock, target, ms, signal) {
|
|
46
|
+
const end = Date.now() + ms;
|
|
47
|
+
for (;;) {
|
|
48
|
+
const page = stock.currentPage();
|
|
49
|
+
const tried = [];
|
|
50
|
+
let unchecked;
|
|
51
|
+
for (const l of target.locators) {
|
|
52
|
+
if (!page)
|
|
53
|
+
break;
|
|
54
|
+
const locator = page.locator(l.selector);
|
|
55
|
+
const n = await locator.count().catch(() => -1);
|
|
56
|
+
if (n === 1 && (await locator.isVisible().catch(() => false)))
|
|
57
|
+
return { selector: l.selector, kind: l.kind };
|
|
58
|
+
if (n < 0 && l.kind === "generated")
|
|
59
|
+
unchecked ??= { selector: l.selector, kind: l.kind };
|
|
60
|
+
tried.push(`${l.kind} ${l.selector}: ${n < 0 ? "not a selector this page can check" : n === 0 ? "no element" : n === 1 ? "not visible" : `${n} elements`}`);
|
|
61
|
+
}
|
|
62
|
+
// A locator the agent wrote in Playwright's JavaScript syntax: upstream parses it itself.
|
|
63
|
+
if (unchecked && tried.length === target.locators.length && tried.every((t) => !t.endsWith("not visible")))
|
|
64
|
+
return unchecked;
|
|
65
|
+
if (!page)
|
|
66
|
+
tried.push("no page is open");
|
|
67
|
+
if (Date.now() >= end || signal?.aborted)
|
|
68
|
+
return { tried };
|
|
69
|
+
await sleep(250);
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
/** Whether a step puts a sensitive value into the page. */
|
|
73
|
+
function typesSecret(step, secret) {
|
|
74
|
+
return paramRefs(step.args).some((name) => secret.has(name));
|
|
75
|
+
}
|
|
76
|
+
async function runStep(run, step, values, secret) {
|
|
77
|
+
const { ctx, stock } = run;
|
|
78
|
+
if (step.tool === "browser_login") {
|
|
79
|
+
try {
|
|
80
|
+
const result = await loginTool().handle(ctx, { site: step.args.site });
|
|
81
|
+
if (result.isError)
|
|
82
|
+
return { ok: false, message: sections(textOf(result)).get("Error") ?? textOf(result) };
|
|
83
|
+
return { ok: true };
|
|
84
|
+
}
|
|
85
|
+
catch (error) {
|
|
86
|
+
return { ok: false, message: error.message ?? String(error) };
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
if (step.tool === "browser_replay") {
|
|
90
|
+
if (run.depth >= MAX_DEPTH)
|
|
91
|
+
return { ok: false, message: `flows replay other flows at most ${MAX_DEPTH} deep` };
|
|
92
|
+
const vault = ctx.vault;
|
|
93
|
+
let inner;
|
|
94
|
+
try {
|
|
95
|
+
inner = readFlow(vault.identity.id, String(step.args.flow), vault.identity.env);
|
|
96
|
+
}
|
|
97
|
+
catch (error) {
|
|
98
|
+
return { ok: false, message: error.message };
|
|
99
|
+
}
|
|
100
|
+
const given = fillParams(step.args.params ?? {}, values);
|
|
101
|
+
const prepared = await prepareParams(ctx, inner, given);
|
|
102
|
+
if ("error" in prepared)
|
|
103
|
+
return { ok: false, message: prepared.error };
|
|
104
|
+
const state = await runSteps({ ...run, depth: run.depth + 1 }, inner, prepared.values, prepared.secret, 1);
|
|
105
|
+
if (state.failure)
|
|
106
|
+
return {
|
|
107
|
+
ok: false,
|
|
108
|
+
message: `step ${state.failure.n} of flow "${inner.name}" (${describeStep(state.failure.step)}) failed: ${state.failure.message}`,
|
|
109
|
+
};
|
|
110
|
+
return { ok: true, note: `${inner.steps.length} steps` };
|
|
111
|
+
}
|
|
112
|
+
const args = fillParams(step.args, values);
|
|
113
|
+
const used = [];
|
|
114
|
+
for (const [path, target] of Object.entries(step.targets ?? {})) {
|
|
115
|
+
const found = await findTarget(stock, target, run.waitMs, ctx.signal);
|
|
116
|
+
if ("tried" in found) {
|
|
117
|
+
const what = target.description ? `"${target.description}"` : "the element";
|
|
118
|
+
return {
|
|
119
|
+
ok: false,
|
|
120
|
+
message: `no locator of ${what} found exactly one visible element within ${run.waitMs / 1000}s:\n${found.tried.map((t) => `- ${t}`).join("\n")}`,
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
setPath(args, path, found.selector);
|
|
124
|
+
used.push(found.kind);
|
|
125
|
+
const element = path === "target"
|
|
126
|
+
? "element"
|
|
127
|
+
: path === "startTarget"
|
|
128
|
+
? "startElement"
|
|
129
|
+
: path === "endTarget"
|
|
130
|
+
? "endElement"
|
|
131
|
+
: undefined;
|
|
132
|
+
if (element && target.description && args[element] === undefined)
|
|
133
|
+
args[element] = target.description;
|
|
134
|
+
}
|
|
135
|
+
const schema = stock.schemas.get(step.tool);
|
|
136
|
+
if (!schema)
|
|
137
|
+
return { ok: false, message: `this server does not offer ${step.tool} (its capability is off)` };
|
|
138
|
+
const parsed = schema.safeParse(args);
|
|
139
|
+
if (!parsed.success)
|
|
140
|
+
return { ok: false, message: `invalid arguments: ${stock.formatError(parsed.error)}` };
|
|
141
|
+
if (typesSecret(step, secret))
|
|
142
|
+
await ctx.recording?.pauseForSecret(stock.currentPage());
|
|
143
|
+
const result = await stock.call(step.tool, args, { snapshot: false });
|
|
144
|
+
if (result.isError)
|
|
145
|
+
return { ok: false, message: sections(textOf(result)).get("Error") ?? textOf(result) };
|
|
146
|
+
return { ok: true, ...(used.length ? { note: `found by ${used.join(", ")}` } : {}) };
|
|
147
|
+
}
|
|
148
|
+
async function runSteps(run, flow, values, secret, from) {
|
|
149
|
+
const state = { lines: [] };
|
|
150
|
+
const total = flow.steps.length;
|
|
151
|
+
for (let i = from - 1; i < total; i++) {
|
|
152
|
+
const step = flow.steps[i];
|
|
153
|
+
const done = await runStep(run, step, values, secret);
|
|
154
|
+
if (!done.ok) {
|
|
155
|
+
state.lines.push(`${i + 1}. ${describeStep(step)}: failed`);
|
|
156
|
+
state.failure = { n: i + 1, total, step, message: done.message };
|
|
157
|
+
return state;
|
|
158
|
+
}
|
|
159
|
+
state.lines.push(`${i + 1}. ${describeStep(step)}: ok${done.note ? ` (${done.note})` : ""}`);
|
|
160
|
+
}
|
|
161
|
+
return state;
|
|
162
|
+
}
|
|
163
|
+
/**
|
|
164
|
+
* The values a flow runs with: given ones (a `keychain:<item>` read from the secret store),
|
|
165
|
+
* then defaults. Sensitive and secret-store values join the redactor first.
|
|
166
|
+
*/
|
|
167
|
+
async function prepareParams(ctx, flow, given) {
|
|
168
|
+
const vault = ctx.vault;
|
|
169
|
+
const { values, missing, unknown } = resolveParams(flow, given);
|
|
170
|
+
if (unknown.length)
|
|
171
|
+
return {
|
|
172
|
+
error: `flow "${flow.name}" has no parameter ${unknown.map((u) => `"${u}"`).join(", ")} (its parameters: ${flow.params.map((p) => p.name).join(", ") || "none"})`,
|
|
173
|
+
};
|
|
174
|
+
if (missing.length)
|
|
175
|
+
return {
|
|
176
|
+
error: `flow "${flow.name}" needs ${missing.map((p) => `"${p.name}"${p.sensitive ? " (sensitive)" : ""}`).join(", ")}: pass them in params; a value written keychain:<item> is read from the secret store (turno secret set <item>) so it never passes through you.`,
|
|
177
|
+
};
|
|
178
|
+
const secret = new Set();
|
|
179
|
+
const refs = new Set();
|
|
180
|
+
for (const p of flow.params) {
|
|
181
|
+
let v = values[p.name];
|
|
182
|
+
if (v.startsWith("keychain:")) {
|
|
183
|
+
const item = v.slice("keychain:".length);
|
|
184
|
+
const store = vault.store ?? secretStore(vault.identity.env);
|
|
185
|
+
if (!store)
|
|
186
|
+
return { error: `parameter "${p.name}" names ${v}, but this machine has no secret store` };
|
|
187
|
+
const read = await store.get(item).catch(() => undefined);
|
|
188
|
+
if (read === undefined)
|
|
189
|
+
return {
|
|
190
|
+
error: `parameter "${p.name}": the secret store has no item "${item}" (store it with: turno secret set ${item})`,
|
|
191
|
+
};
|
|
192
|
+
v = read;
|
|
193
|
+
values[p.name] = v;
|
|
194
|
+
refs.add(p.name);
|
|
195
|
+
secret.add(p.name);
|
|
196
|
+
}
|
|
197
|
+
else if (p.sensitive)
|
|
198
|
+
secret.add(p.name);
|
|
199
|
+
if (secret.has(p.name))
|
|
200
|
+
vault.redactor.add(v, `sensitive parameter ${p.name}`);
|
|
201
|
+
}
|
|
202
|
+
return { values, secret, refs };
|
|
203
|
+
}
|
|
204
|
+
function replaySchema() {
|
|
205
|
+
const z = upstream().utils.z;
|
|
206
|
+
return {
|
|
207
|
+
name: "browser_replay",
|
|
208
|
+
title: "Replay a saved browser flow",
|
|
209
|
+
description: [
|
|
210
|
+
"Run a flow saved with browser_record (list them with browser_flows) on this browser identity, step by step, finding each element again by its saved locators.",
|
|
211
|
+
"Pass the flow's parameters in params; sensitive ones have no saved value and must be given. Write a value as keychain:<item> to have it read from the secret store instead of passing it yourself.",
|
|
212
|
+
"When a step fails it stops and reports the step, the locators it tried and a fresh snapshot: do that step yourself, then call browser_replay again with from set to the next step.",
|
|
213
|
+
].join(" "),
|
|
214
|
+
inputSchema: z.object({
|
|
215
|
+
flow: z.string().describe("The flow name"),
|
|
216
|
+
params: z.record(z.string(), z.string()).optional().describe("Parameter values by name"),
|
|
217
|
+
from: z
|
|
218
|
+
.number()
|
|
219
|
+
.optional()
|
|
220
|
+
.describe("Start at this step (1 is the first), to continue after a step done by hand"),
|
|
221
|
+
wait: z
|
|
222
|
+
.number()
|
|
223
|
+
.optional()
|
|
224
|
+
.describe(`Seconds to wait for each step's element (default ${DEFAULT_WAIT_S}, at most ${MAX_WAIT_S})`),
|
|
225
|
+
snapshot: z.boolean().optional().describe("Return a snapshot of the page after the last step (default true)"),
|
|
226
|
+
}),
|
|
227
|
+
type: "action",
|
|
228
|
+
};
|
|
229
|
+
}
|
|
230
|
+
/** The snapshot sections of a stock result, for the end of a replay's result. */
|
|
231
|
+
async function pageSections(stock, snapshot) {
|
|
232
|
+
if (!snapshot) {
|
|
233
|
+
const page = await stock.page();
|
|
234
|
+
return page ? ["### Page", `- Page URL: ${page.url}`, ...(page.title ? [`- Page Title: ${page.title}`] : [])] : [];
|
|
235
|
+
}
|
|
236
|
+
const snap = sections(textOf(await stock.call("browser_snapshot", {}, { snapshot: true })));
|
|
237
|
+
const out = [];
|
|
238
|
+
for (const title of ["Open tabs", "Page", "Modal state", "Snapshot", "Tab governor"]) {
|
|
239
|
+
const body = snap.get(title);
|
|
240
|
+
if (body)
|
|
241
|
+
out.push(`### ${title}`, body);
|
|
242
|
+
}
|
|
243
|
+
return out;
|
|
244
|
+
}
|
|
245
|
+
/** `browser_replay`. */
|
|
246
|
+
export function replayTool() {
|
|
247
|
+
let built;
|
|
248
|
+
return {
|
|
249
|
+
get schema() {
|
|
250
|
+
built ??= replaySchema();
|
|
251
|
+
return built;
|
|
252
|
+
},
|
|
253
|
+
async handle(ctx, params) {
|
|
254
|
+
const vault = ctx.vault;
|
|
255
|
+
const stock = ctx.stock;
|
|
256
|
+
if (!vault || !stock)
|
|
257
|
+
throw new FlowError("browser_replay needs a browser identity: this server runs without --identity");
|
|
258
|
+
const flow = readFlow(vault.identity.id, String(params.flow), vault.identity.env);
|
|
259
|
+
const from = params.from === undefined ? 1 : Number(params.from);
|
|
260
|
+
if (!Number.isInteger(from) || from < 1 || from > flow.steps.length)
|
|
261
|
+
throw new FlowError(`from must be a step number from 1 to ${flow.steps.length}`);
|
|
262
|
+
const wait = Math.min(MAX_WAIT_S, Math.max(0, Number(params.wait ?? DEFAULT_WAIT_S)));
|
|
263
|
+
const given = params.params ?? {};
|
|
264
|
+
const prepared = await prepareParams(ctx, flow, given);
|
|
265
|
+
if ("error" in prepared)
|
|
266
|
+
return { content: [{ type: "text", text: `### Error\nNothing ran: ${prepared.error}` }], isError: true };
|
|
267
|
+
const run = { ctx, stock, waitMs: wait * 1000, depth: 0 };
|
|
268
|
+
const exec = () => runSteps(run, flow, prepared.values, prepared.secret, from);
|
|
269
|
+
const state = ctx.recorder ? await ctx.recorder.suspend(exec) : await exec();
|
|
270
|
+
const out = [];
|
|
271
|
+
if (state.failure) {
|
|
272
|
+
const { n, total, step, message } = state.failure;
|
|
273
|
+
const left = total - n;
|
|
274
|
+
out.push("### Error", `Step ${n} of ${total} (${describeStep(step)}) failed: ${message}`, left
|
|
275
|
+
? `Steps ${n + 1} to ${total} did not run. Do step ${n} yourself on the page below, then continue with browser_replay {"flow": "${flow.name}", "from": ${n + 1}} and the same params.`
|
|
276
|
+
: `It was the last step: do it yourself on the page below.`);
|
|
277
|
+
}
|
|
278
|
+
out.push("### Replay", `Flow "${flow.name}"${from > 1 ? ` from step ${from}` : ""}:`, ...state.lines);
|
|
279
|
+
if (state.failure && state.failure.n < flow.steps.length)
|
|
280
|
+
out.push("### Remaining steps", ...flow.steps.slice(state.failure.n).map((s, i) => `${state.failure.n + i + 1}. ${describeStep(s)}`));
|
|
281
|
+
out.push(...(await pageSections(stock, params.snapshot !== false || state.failure !== undefined)));
|
|
282
|
+
if (!state.failure && from === 1 && ctx.recorder) {
|
|
283
|
+
// A recording session keeps the replay as one step; a value read from the secret store
|
|
284
|
+
// keeps its keychain: reference, which is not a secret.
|
|
285
|
+
const slots = flow.params.map((p) => {
|
|
286
|
+
const raw = given[p.name];
|
|
287
|
+
const ref = raw?.startsWith("keychain:");
|
|
288
|
+
return {
|
|
289
|
+
path: `params.${p.name}`,
|
|
290
|
+
value: ref ? raw : prepared.values[p.name],
|
|
291
|
+
sensitive: !ref && prepared.secret.has(p.name),
|
|
292
|
+
label: p.name,
|
|
293
|
+
};
|
|
294
|
+
});
|
|
295
|
+
ctx.recorder.record("browser_replay", { flow: flow.name, params: Object.fromEntries(flow.params.map((p) => [p.name, ""])) }, slots);
|
|
296
|
+
}
|
|
297
|
+
return { content: [{ type: "text", text: out.join("\n") }], ...(state.failure ? { isError: true } : {}) };
|
|
298
|
+
},
|
|
299
|
+
};
|
|
300
|
+
}
|
|
301
|
+
function flowsSchema() {
|
|
302
|
+
const z = upstream().utils.z;
|
|
303
|
+
return {
|
|
304
|
+
name: "browser_flows",
|
|
305
|
+
title: "List saved browser flows",
|
|
306
|
+
description: "List the flows saved for this browser identity (browser_record saves them), with their steps and parameters; name one to see its steps.",
|
|
307
|
+
inputSchema: z.object({ name: z.string().optional().describe("A flow name, to see its steps") }),
|
|
308
|
+
type: "readOnly",
|
|
309
|
+
};
|
|
310
|
+
}
|
|
311
|
+
/** `browser_flows`. */
|
|
312
|
+
export function flowsTool() {
|
|
313
|
+
let built;
|
|
314
|
+
return {
|
|
315
|
+
get schema() {
|
|
316
|
+
built ??= flowsSchema();
|
|
317
|
+
return built;
|
|
318
|
+
},
|
|
319
|
+
browser: false,
|
|
320
|
+
async handle(ctx, params) {
|
|
321
|
+
const vault = ctx.vault;
|
|
322
|
+
if (!vault)
|
|
323
|
+
throw new FlowError("browser_flows needs a browser identity: this server runs without --identity");
|
|
324
|
+
const { id, env } = vault.identity;
|
|
325
|
+
const describeParam = (p) => `${p.name}${p.sensitive ? " (sensitive, required)" : p.hasDefault ? "" : " (required)"}`;
|
|
326
|
+
if (typeof params.name === "string") {
|
|
327
|
+
const flow = readFlow(id, params.name, env);
|
|
328
|
+
const lines = [
|
|
329
|
+
`### Flow ${flow.name}`,
|
|
330
|
+
...(flow.description ? [flow.description] : []),
|
|
331
|
+
...flow.steps.map((s, i) => `${i + 1}. ${describeStep(s)}`),
|
|
332
|
+
"### Parameters",
|
|
333
|
+
...(flow.params.length
|
|
334
|
+
? flow.params.map((p) => `- ${describeParam({ name: p.name, sensitive: p.sensitive, hasDefault: p.default !== undefined })}`)
|
|
335
|
+
: ["(none)"]),
|
|
336
|
+
];
|
|
337
|
+
return { content: [{ type: "text", text: lines.join("\n") }] };
|
|
338
|
+
}
|
|
339
|
+
const flows = listFlows(id, env);
|
|
340
|
+
const lines = flows.length
|
|
341
|
+
? flows.map((f) => `- ${f.name}: ${f.steps} step${f.steps === 1 ? "" : "s"}${f.start ? `, starts at ${f.start}` : ""}${f.params.length ? `; params ${f.params.map(describeParam).join(", ")}` : ""}${f.description ? `. ${f.description}` : ""}`)
|
|
342
|
+
: [`Identity "${id}" has no saved flows yet: record one with browser_record.`];
|
|
343
|
+
return { content: [{ type: "text", text: ["### Flows", ...lines].join("\n") }] };
|
|
344
|
+
},
|
|
345
|
+
};
|
|
346
|
+
}
|
|
347
|
+
/**
|
|
348
|
+
* Replays a flow outside an agent (`turno browser replay`): starts this package's MCP server
|
|
349
|
+
* on the identity and calls `browser_replay`, so the run goes through exactly the path an agent's
|
|
350
|
+
* does (lock, vault, redaction, recordings). Parameter values travel over the server's stdin.
|
|
351
|
+
*/
|
|
352
|
+
export async function replayFlow(id, flow, options = {}) {
|
|
353
|
+
const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
|
|
354
|
+
const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
|
|
355
|
+
const env = options.env ?? process.env;
|
|
356
|
+
const bin = fileURLToPath(new URL("./bin/mcp.js", import.meta.url));
|
|
357
|
+
const transport = new StdioClientTransport({
|
|
358
|
+
command: process.execPath,
|
|
359
|
+
args: [bin, "--identity", id, ...(options.headless ? ["--headless"] : [])],
|
|
360
|
+
env: Object.fromEntries(Object.entries(env).filter((e) => e[1] !== undefined)),
|
|
361
|
+
stderr: "pipe",
|
|
362
|
+
});
|
|
363
|
+
const client = new Client({ name: "turno browser replay", version: "1" });
|
|
364
|
+
await client.connect(transport);
|
|
365
|
+
try {
|
|
366
|
+
const result = await client.callTool({
|
|
367
|
+
name: "browser_replay",
|
|
368
|
+
arguments: {
|
|
369
|
+
flow,
|
|
370
|
+
...(options.params ? { params: options.params } : {}),
|
|
371
|
+
...(options.from ? { from: options.from } : {}),
|
|
372
|
+
snapshot: false,
|
|
373
|
+
},
|
|
374
|
+
}, undefined, { timeout: 10 * 60_000 });
|
|
375
|
+
const text = (result.content ?? []).map((c) => c.text ?? "").join("\n");
|
|
376
|
+
return { ok: !result.isError, text };
|
|
377
|
+
}
|
|
378
|
+
finally {
|
|
379
|
+
await client.close().catch(() => { });
|
|
380
|
+
}
|
|
381
|
+
}
|
|
382
|
+
//# sourceMappingURL=replay.js.map
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
import { type ChallengeKind } from "./detectors.js";
|
|
2
|
+
/**
|
|
3
|
+
* The reputation log: every challenge a page of an identity showed, one JSON line in
|
|
4
|
+
* `<state>/browser/identities/<id>/reputation.jsonl`:
|
|
5
|
+
*
|
|
6
|
+
* {"ts":"2026-11-17T16:00:00.000Z","site":"mail.example.com","kind":"verify","markers":["verify it's you"]}
|
|
7
|
+
*
|
|
8
|
+
* Only the host name and the matched phrases (from the fixed list in `detectors.ts`): no path,
|
|
9
|
+
* no query, no page content. A site's reputation is not a score a test page gives; it is how
|
|
10
|
+
* often the site stops the identity, and whether that goes up or down. `turno browser
|
|
11
|
+
* reputation` shows the counts and the trend of the last 7 days against the 7 before.
|
|
12
|
+
*
|
|
13
|
+
* With captcha solving on (identity.json `captcha`), each attempt of `browser_solve_captcha`
|
|
14
|
+
* is a line of its own, with the widget kind, the provider and whether it worked:
|
|
15
|
+
*
|
|
16
|
+
* {"ts":"2026-11-19T16:00:00.000Z","site":"shop.example.com","kind":"solve","widget":"recaptcha","provider":"task-api","ok":true}
|
|
17
|
+
*
|
|
18
|
+
* An older turno-browser skips those lines when it reads the log.
|
|
19
|
+
*/
|
|
20
|
+
export interface ChallengeEvent {
|
|
21
|
+
ts: string;
|
|
22
|
+
site: string;
|
|
23
|
+
kind: ChallengeKind;
|
|
24
|
+
markers: string[];
|
|
25
|
+
}
|
|
26
|
+
/** One `browser_solve_captcha` attempt. Never the token, the key or the page's path. */
|
|
27
|
+
export interface SolveEvent {
|
|
28
|
+
ts: string;
|
|
29
|
+
site: string;
|
|
30
|
+
kind: "solve";
|
|
31
|
+
widget: string;
|
|
32
|
+
provider: string;
|
|
33
|
+
ok: boolean;
|
|
34
|
+
}
|
|
35
|
+
export interface SiteSummary {
|
|
36
|
+
site: string;
|
|
37
|
+
total: number;
|
|
38
|
+
/** Captchas a solver answered (identity.json `captcha`); not counted in `total`. */
|
|
39
|
+
solved: number;
|
|
40
|
+
captcha: number;
|
|
41
|
+
verify: number;
|
|
42
|
+
block: number;
|
|
43
|
+
last7d: number;
|
|
44
|
+
prev7d: number;
|
|
45
|
+
trend: "up" | "down" | "flat";
|
|
46
|
+
lastSeen: string;
|
|
47
|
+
}
|
|
48
|
+
export interface IdentityReputation {
|
|
49
|
+
id: string;
|
|
50
|
+
file: string;
|
|
51
|
+
total: number;
|
|
52
|
+
sites: SiteSummary[];
|
|
53
|
+
}
|
|
54
|
+
export declare function reputationPath(id: string, env?: NodeJS.ProcessEnv): string;
|
|
55
|
+
export declare function recordChallenge(id: string, env: NodeJS.ProcessEnv, event: Omit<ChallengeEvent, "ts">, now?: Date): void;
|
|
56
|
+
/** Logs one captcha solving attempt. */
|
|
57
|
+
export declare function recordSolve(id: string, env: NodeJS.ProcessEnv, event: Omit<SolveEvent, "ts" | "kind">, now?: Date): void;
|
|
58
|
+
/** Every challenge of the identity's log, oldest first. Lines that do not parse are skipped. */
|
|
59
|
+
export declare function readChallenges(id: string, env?: NodeJS.ProcessEnv): ChallengeEvent[];
|
|
60
|
+
/** Every captcha solving attempt of the identity's log, oldest first. */
|
|
61
|
+
export declare function readSolves(id: string, env?: NodeJS.ProcessEnv): SolveEvent[];
|
|
62
|
+
/** Counts per site, most recent first, with the trend of the last 7 days against the 7 before. */
|
|
63
|
+
export declare function summarizeChallenges(events: readonly ChallengeEvent[], now?: Date, solves?: readonly SolveEvent[]): SiteSummary[];
|
|
64
|
+
/** The report of `turno browser reputation`: the identities asked for, or every one. */
|
|
65
|
+
export declare function reputationReport(env?: NodeJS.ProcessEnv, ids?: readonly string[], now?: Date): {
|
|
66
|
+
identities: IdentityReputation[];
|
|
67
|
+
};
|
|
68
|
+
interface WatchedPage {
|
|
69
|
+
url(): string;
|
|
70
|
+
content(): Promise<string>;
|
|
71
|
+
on(event: "load", listener: () => void): unknown;
|
|
72
|
+
off?(event: "load", listener: () => void): unknown;
|
|
73
|
+
}
|
|
74
|
+
interface WatchedContext {
|
|
75
|
+
pages(): WatchedPage[];
|
|
76
|
+
on(event: "page", listener: (page: WatchedPage) => void): unknown;
|
|
77
|
+
off?(event: "page", listener: (page: WatchedPage) => void): unknown;
|
|
78
|
+
}
|
|
79
|
+
export interface WatchOptions {
|
|
80
|
+
/** The same site and kind within this long counts once (a reload loop). */
|
|
81
|
+
dedupeMs?: number;
|
|
82
|
+
now?: () => number;
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* Looks at every page the context loads (each main frame `load`, popups included) and reports
|
|
86
|
+
* a challenge page: its host name, kind and matched phrases. Returns a function that stops.
|
|
87
|
+
*/
|
|
88
|
+
export declare function watchChallenges(context: WatchedContext, onChallenge: (event: Omit<ChallengeEvent, "ts">) => void, opts?: WatchOptions): () => void;
|
|
89
|
+
export {};
|
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
import { appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
|
|
2
|
+
import { join } from "node:path";
|
|
3
|
+
import { classifyChallenge } from "./detectors.js";
|
|
4
|
+
import { IdentityError, identityStateDir } from "./ids.js";
|
|
5
|
+
import { identityExists, listIdentities } from "./identities.js";
|
|
6
|
+
/** The log keeps about this many bytes; older lines go first. */
|
|
7
|
+
const MAX_BYTES = 1024 * 1024;
|
|
8
|
+
const DAY = 86_400_000;
|
|
9
|
+
export function reputationPath(id, env = process.env) {
|
|
10
|
+
return join(identityStateDir(id, env), "reputation.jsonl");
|
|
11
|
+
}
|
|
12
|
+
export function recordChallenge(id, env, event, now = new Date()) {
|
|
13
|
+
appendLine(id, env, { ts: now.toISOString(), site: event.site, kind: event.kind, markers: event.markers });
|
|
14
|
+
}
|
|
15
|
+
/** Logs one captcha solving attempt. */
|
|
16
|
+
export function recordSolve(id, env, event, now = new Date()) {
|
|
17
|
+
const line = {
|
|
18
|
+
ts: now.toISOString(),
|
|
19
|
+
site: event.site,
|
|
20
|
+
kind: "solve",
|
|
21
|
+
widget: event.widget,
|
|
22
|
+
provider: event.provider,
|
|
23
|
+
ok: event.ok,
|
|
24
|
+
};
|
|
25
|
+
appendLine(id, env, line);
|
|
26
|
+
}
|
|
27
|
+
function appendLine(id, env, line) {
|
|
28
|
+
const file = reputationPath(id, env);
|
|
29
|
+
mkdirSync(identityStateDir(id, env), { recursive: true, mode: 0o700 });
|
|
30
|
+
appendFileSync(file, `${JSON.stringify(line)}\n`, { mode: 0o600 });
|
|
31
|
+
try {
|
|
32
|
+
if (statSync(file).size > MAX_BYTES) {
|
|
33
|
+
const lines = readFileSync(file, "utf8").trim().split("\n");
|
|
34
|
+
writeFileSync(file, `${lines.slice(Math.floor(lines.length / 2)).join("\n")}\n`, { mode: 0o600 });
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
catch {
|
|
38
|
+
/* trimming is best effort */
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
function isEvent(v) {
|
|
42
|
+
const e = v;
|
|
43
|
+
return (typeof e === "object" &&
|
|
44
|
+
e !== null &&
|
|
45
|
+
typeof e.ts === "string" &&
|
|
46
|
+
typeof e.site === "string" &&
|
|
47
|
+
(e.kind === "captcha" || e.kind === "verify" || e.kind === "block") &&
|
|
48
|
+
Array.isArray(e.markers));
|
|
49
|
+
}
|
|
50
|
+
function isSolve(v) {
|
|
51
|
+
const e = v;
|
|
52
|
+
return (typeof e === "object" &&
|
|
53
|
+
e !== null &&
|
|
54
|
+
e.kind === "solve" &&
|
|
55
|
+
typeof e.ts === "string" &&
|
|
56
|
+
typeof e.site === "string" &&
|
|
57
|
+
typeof e.ok === "boolean");
|
|
58
|
+
}
|
|
59
|
+
function readLines(id, env, keep) {
|
|
60
|
+
let text;
|
|
61
|
+
try {
|
|
62
|
+
text = readFileSync(reputationPath(id, env), "utf8");
|
|
63
|
+
}
|
|
64
|
+
catch {
|
|
65
|
+
return [];
|
|
66
|
+
}
|
|
67
|
+
const out = [];
|
|
68
|
+
for (const line of text.split("\n")) {
|
|
69
|
+
if (!line.trim())
|
|
70
|
+
continue;
|
|
71
|
+
try {
|
|
72
|
+
const v = JSON.parse(line);
|
|
73
|
+
if (keep(v))
|
|
74
|
+
out.push(v);
|
|
75
|
+
}
|
|
76
|
+
catch {
|
|
77
|
+
/* a torn or foreign line */
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
return out;
|
|
81
|
+
}
|
|
82
|
+
/** Every challenge of the identity's log, oldest first. Lines that do not parse are skipped. */
|
|
83
|
+
export function readChallenges(id, env = process.env) {
|
|
84
|
+
return readLines(id, env, isEvent);
|
|
85
|
+
}
|
|
86
|
+
/** Every captcha solving attempt of the identity's log, oldest first. */
|
|
87
|
+
export function readSolves(id, env = process.env) {
|
|
88
|
+
return readLines(id, env, isSolve);
|
|
89
|
+
}
|
|
90
|
+
/** Counts per site, most recent first, with the trend of the last 7 days against the 7 before. */
|
|
91
|
+
export function summarizeChallenges(events, now = new Date(), solves = []) {
|
|
92
|
+
const bySite = new Map();
|
|
93
|
+
const t = now.getTime();
|
|
94
|
+
const empty = (site, ts) => ({
|
|
95
|
+
site,
|
|
96
|
+
total: 0,
|
|
97
|
+
solved: 0,
|
|
98
|
+
captcha: 0,
|
|
99
|
+
verify: 0,
|
|
100
|
+
block: 0,
|
|
101
|
+
last7d: 0,
|
|
102
|
+
prev7d: 0,
|
|
103
|
+
trend: "flat",
|
|
104
|
+
lastSeen: ts,
|
|
105
|
+
});
|
|
106
|
+
for (const e of events) {
|
|
107
|
+
const s = bySite.get(e.site) ?? empty(e.site, e.ts);
|
|
108
|
+
s.total++;
|
|
109
|
+
s[e.kind]++;
|
|
110
|
+
const age = t - Date.parse(e.ts);
|
|
111
|
+
if (age <= 7 * DAY)
|
|
112
|
+
s.last7d++;
|
|
113
|
+
else if (age <= 14 * DAY)
|
|
114
|
+
s.prev7d++;
|
|
115
|
+
if (e.ts > s.lastSeen)
|
|
116
|
+
s.lastSeen = e.ts;
|
|
117
|
+
bySite.set(e.site, s);
|
|
118
|
+
}
|
|
119
|
+
for (const e of solves) {
|
|
120
|
+
if (!e.ok)
|
|
121
|
+
continue;
|
|
122
|
+
const s = bySite.get(e.site) ?? empty(e.site, e.ts);
|
|
123
|
+
s.solved++;
|
|
124
|
+
if (e.ts > s.lastSeen)
|
|
125
|
+
s.lastSeen = e.ts;
|
|
126
|
+
bySite.set(e.site, s);
|
|
127
|
+
}
|
|
128
|
+
for (const s of bySite.values())
|
|
129
|
+
s.trend = s.last7d > s.prev7d ? "up" : s.last7d < s.prev7d ? "down" : "flat";
|
|
130
|
+
return [...bySite.values()].sort((a, b) => b.lastSeen.localeCompare(a.lastSeen) || a.site.localeCompare(b.site));
|
|
131
|
+
}
|
|
132
|
+
/** The report of `turno browser reputation`: the identities asked for, or every one. */
|
|
133
|
+
export function reputationReport(env = process.env, ids, now = new Date()) {
|
|
134
|
+
const list = ids?.length ? [...ids] : listIdentities(env).map((i) => i.id);
|
|
135
|
+
for (const id of list)
|
|
136
|
+
if (!identityExists(id, env))
|
|
137
|
+
throw new IdentityError(`identity "${id}" does not exist`);
|
|
138
|
+
return {
|
|
139
|
+
identities: list.map((id) => {
|
|
140
|
+
const events = readChallenges(id, env);
|
|
141
|
+
return {
|
|
142
|
+
id,
|
|
143
|
+
file: reputationPath(id, env),
|
|
144
|
+
total: events.length,
|
|
145
|
+
sites: summarizeChallenges(events, now, readSolves(id, env)),
|
|
146
|
+
};
|
|
147
|
+
}),
|
|
148
|
+
};
|
|
149
|
+
}
|
|
150
|
+
/**
|
|
151
|
+
* Looks at every page the context loads (each main frame `load`, popups included) and reports
|
|
152
|
+
* a challenge page: its host name, kind and matched phrases. Returns a function that stops.
|
|
153
|
+
*/
|
|
154
|
+
export function watchChallenges(context, onChallenge, opts = {}) {
|
|
155
|
+
const dedupeMs = opts.dedupeMs ?? 60_000;
|
|
156
|
+
const now = opts.now ?? Date.now;
|
|
157
|
+
const last = new Map();
|
|
158
|
+
const listeners = new Map();
|
|
159
|
+
let stopped = false;
|
|
160
|
+
const inspect = async (page) => {
|
|
161
|
+
let site;
|
|
162
|
+
try {
|
|
163
|
+
const url = new URL(page.url());
|
|
164
|
+
if (url.protocol !== "http:" && url.protocol !== "https:")
|
|
165
|
+
return;
|
|
166
|
+
site = url.hostname;
|
|
167
|
+
}
|
|
168
|
+
catch {
|
|
169
|
+
return;
|
|
170
|
+
}
|
|
171
|
+
const html = await page.content().catch(() => undefined);
|
|
172
|
+
if (stopped || html === undefined)
|
|
173
|
+
return;
|
|
174
|
+
const found = classifyChallenge(html);
|
|
175
|
+
if (!found)
|
|
176
|
+
return;
|
|
177
|
+
const key = `${site}\n${found.kind}`;
|
|
178
|
+
const t = now();
|
|
179
|
+
const previous = last.get(key);
|
|
180
|
+
if (previous !== undefined && t - previous < dedupeMs)
|
|
181
|
+
return;
|
|
182
|
+
last.set(key, t);
|
|
183
|
+
onChallenge({ site, kind: found.kind, markers: found.markers });
|
|
184
|
+
};
|
|
185
|
+
const attach = (page) => {
|
|
186
|
+
if (listeners.has(page))
|
|
187
|
+
return;
|
|
188
|
+
const listener = () => void inspect(page).catch(() => { });
|
|
189
|
+
listeners.set(page, listener);
|
|
190
|
+
page.on("load", listener);
|
|
191
|
+
};
|
|
192
|
+
for (const p of context.pages())
|
|
193
|
+
attach(p);
|
|
194
|
+
context.on("page", attach);
|
|
195
|
+
return () => {
|
|
196
|
+
stopped = true;
|
|
197
|
+
context.off?.("page", attach);
|
|
198
|
+
for (const [page, listener] of listeners)
|
|
199
|
+
page.off?.("load", listener);
|
|
200
|
+
listeners.clear();
|
|
201
|
+
};
|
|
202
|
+
}
|
|
203
|
+
//# sourceMappingURL=reputation.js.map
|