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,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The page side of a person step (`browser_request_human`): one function the host evaluates in
|
|
3
|
+
* a frame, like the agent cursor's overlay (`agent-cursor-overlay.ts`). It runs in Playwright's
|
|
4
|
+
* utility world (patchright's `page.evaluate` default), so the state it keeps on `window` is out
|
|
5
|
+
* of the page's own scripts' reach, and it must stay self-contained: it is sent as source.
|
|
6
|
+
*
|
|
7
|
+
* Two parts, each in a closed shadow root on a host element under `<html>` (never in `<body>`):
|
|
8
|
+
*
|
|
9
|
+
* - the banner, in the top frame: a card fixed at the bottom of the page with the instruction
|
|
10
|
+
* and a Done button. It counts the person's clicks in the page and the fields they changed
|
|
11
|
+
* (never what they typed), and Done only from a trusted event (`isTrusted`), so a page script
|
|
12
|
+
* cannot press it;
|
|
13
|
+
* - the target, in the frame of the element the agent pointed at: a ring around it, and whether
|
|
14
|
+
* the person pressed or clicked it, from trusted events only.
|
|
15
|
+
*
|
|
16
|
+
* A new document has neither part: the host evaluates the banner again on each poll, which
|
|
17
|
+
* builds it on the new document. A trusted event is one the browser made from input: the
|
|
18
|
+
* person's own mouse and keys, or the live view's (CDP input). The agent's calls are held while
|
|
19
|
+
* the step lasts, so no agent input reaches the page then.
|
|
20
|
+
*/
|
|
21
|
+
/** What the banner says, from the host's strings table. */
|
|
22
|
+
export interface StepView {
|
|
23
|
+
/** The step this banner belongs to: a new step replaces an old banner. */
|
|
24
|
+
step: string;
|
|
25
|
+
lang: string;
|
|
26
|
+
title: string;
|
|
27
|
+
instruction: string;
|
|
28
|
+
hint: string;
|
|
29
|
+
/** The Done button's label, or null for no button. */
|
|
30
|
+
done: string | null;
|
|
31
|
+
}
|
|
32
|
+
export type StepCommand = {
|
|
33
|
+
op: "banner";
|
|
34
|
+
view: StepView;
|
|
35
|
+
} | {
|
|
36
|
+
op: "target";
|
|
37
|
+
step: string;
|
|
38
|
+
} | {
|
|
39
|
+
op: "remove";
|
|
40
|
+
};
|
|
41
|
+
/** What one document reports. Counts are of this document only; the host adds them up. */
|
|
42
|
+
export interface StepReport {
|
|
43
|
+
/** A random key of this document's parts: a new document gets a new one. */
|
|
44
|
+
doc: string;
|
|
45
|
+
/** The banner is on the page now. */
|
|
46
|
+
shown: boolean;
|
|
47
|
+
/** The person pressed Done (a trusted click). */
|
|
48
|
+
done: boolean;
|
|
49
|
+
/** Trusted clicks outside the banner. */
|
|
50
|
+
clicks: number;
|
|
51
|
+
/** Fields the person changed (each counted once). */
|
|
52
|
+
fields: number;
|
|
53
|
+
/** One of them was a password or one-time code field. */
|
|
54
|
+
sensitive: boolean;
|
|
55
|
+
/** Where the Done button is, in viewport pixels (tests click it; its DOM is behind a closed root). */
|
|
56
|
+
doneBox: {
|
|
57
|
+
x: number;
|
|
58
|
+
y: number;
|
|
59
|
+
width: number;
|
|
60
|
+
height: number;
|
|
61
|
+
} | null;
|
|
62
|
+
/** The target's part, in the frame it was evaluated in. */
|
|
63
|
+
target?: {
|
|
64
|
+
connected: boolean;
|
|
65
|
+
pressed: boolean;
|
|
66
|
+
clicked: boolean;
|
|
67
|
+
};
|
|
68
|
+
}
|
|
69
|
+
/** Applies one command in this frame and reports. Runs in the page. */
|
|
70
|
+
export declare function humanStepOverlay(arg: {
|
|
71
|
+
cmd: StepCommand;
|
|
72
|
+
el?: Element;
|
|
73
|
+
}): StepReport;
|
|
@@ -0,0 +1,285 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The page side of a person step (`browser_request_human`): one function the host evaluates in
|
|
3
|
+
* a frame, like the agent cursor's overlay (`agent-cursor-overlay.ts`). It runs in Playwright's
|
|
4
|
+
* utility world (patchright's `page.evaluate` default), so the state it keeps on `window` is out
|
|
5
|
+
* of the page's own scripts' reach, and it must stay self-contained: it is sent as source.
|
|
6
|
+
*
|
|
7
|
+
* Two parts, each in a closed shadow root on a host element under `<html>` (never in `<body>`):
|
|
8
|
+
*
|
|
9
|
+
* - the banner, in the top frame: a card fixed at the bottom of the page with the instruction
|
|
10
|
+
* and a Done button. It counts the person's clicks in the page and the fields they changed
|
|
11
|
+
* (never what they typed), and Done only from a trusted event (`isTrusted`), so a page script
|
|
12
|
+
* cannot press it;
|
|
13
|
+
* - the target, in the frame of the element the agent pointed at: a ring around it, and whether
|
|
14
|
+
* the person pressed or clicked it, from trusted events only.
|
|
15
|
+
*
|
|
16
|
+
* A new document has neither part: the host evaluates the banner again on each poll, which
|
|
17
|
+
* builds it on the new document. A trusted event is one the browser made from input: the
|
|
18
|
+
* person's own mouse and keys, or the live view's (CDP input). The agent's calls are held while
|
|
19
|
+
* the step lasts, so no agent input reaches the page then.
|
|
20
|
+
*/
|
|
21
|
+
/** Applies one command in this frame and reports. Runs in the page. */
|
|
22
|
+
export function humanStepOverlay(arg) {
|
|
23
|
+
const GLOBAL = "__turnoHumanStep";
|
|
24
|
+
const COLOR = "#2b59ff";
|
|
25
|
+
const w = window;
|
|
26
|
+
const state = w[GLOBAL] ?? {};
|
|
27
|
+
w[GLOBAL] = state;
|
|
28
|
+
const { cmd } = arg;
|
|
29
|
+
const randomKey = () => Math.random().toString(36).slice(2, 10);
|
|
30
|
+
const important = (el, props) => {
|
|
31
|
+
for (const [k, v] of Object.entries(props))
|
|
32
|
+
el.style.setProperty(k, v, "important");
|
|
33
|
+
};
|
|
34
|
+
const makeHost = (tag, inert) => {
|
|
35
|
+
const host = document.createElement(tag);
|
|
36
|
+
if (inert) {
|
|
37
|
+
host.setAttribute("aria-hidden", "true");
|
|
38
|
+
host.setAttribute("inert", "");
|
|
39
|
+
}
|
|
40
|
+
important(host, {
|
|
41
|
+
all: "initial",
|
|
42
|
+
display: "block",
|
|
43
|
+
position: "fixed",
|
|
44
|
+
left: "0",
|
|
45
|
+
top: "0",
|
|
46
|
+
width: "0",
|
|
47
|
+
height: "0",
|
|
48
|
+
margin: "0",
|
|
49
|
+
padding: "0",
|
|
50
|
+
border: "0",
|
|
51
|
+
overflow: "visible",
|
|
52
|
+
"z-index": "2147483647",
|
|
53
|
+
"pointer-events": "none",
|
|
54
|
+
background: "transparent",
|
|
55
|
+
});
|
|
56
|
+
return { host, root: host.attachShadow({ mode: "closed" }) };
|
|
57
|
+
};
|
|
58
|
+
const style = (root, css) => {
|
|
59
|
+
try {
|
|
60
|
+
const sheet = new CSSStyleSheet();
|
|
61
|
+
sheet.replaceSync(css);
|
|
62
|
+
root.adoptedStyleSheets = [sheet];
|
|
63
|
+
}
|
|
64
|
+
catch {
|
|
65
|
+
const el = document.createElement("style");
|
|
66
|
+
el.textContent = css;
|
|
67
|
+
root.append(el);
|
|
68
|
+
}
|
|
69
|
+
};
|
|
70
|
+
const el = (tag, cls, text) => {
|
|
71
|
+
const node = document.createElement(tag);
|
|
72
|
+
node.className = cls;
|
|
73
|
+
if (text !== undefined)
|
|
74
|
+
node.textContent = text;
|
|
75
|
+
return node;
|
|
76
|
+
};
|
|
77
|
+
const isEditable = (node) => {
|
|
78
|
+
if (!node || !node.tagName)
|
|
79
|
+
return false;
|
|
80
|
+
const tag = node.tagName;
|
|
81
|
+
return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT" || node.isContentEditable;
|
|
82
|
+
};
|
|
83
|
+
const isSensitive = (node) => {
|
|
84
|
+
if (node.tagName !== "INPUT")
|
|
85
|
+
return false;
|
|
86
|
+
const input = node;
|
|
87
|
+
return input.type === "password" || /password|one-time-code/.test(input.autocomplete || "");
|
|
88
|
+
};
|
|
89
|
+
const firstOf = (e) => (e.composedPath()[0] ?? e.target);
|
|
90
|
+
const removeBanner = () => {
|
|
91
|
+
state.banner?.off();
|
|
92
|
+
state.banner?.host.remove();
|
|
93
|
+
state.banner = undefined;
|
|
94
|
+
};
|
|
95
|
+
const removeTarget = () => {
|
|
96
|
+
state.target?.off();
|
|
97
|
+
state.target?.host.remove();
|
|
98
|
+
state.target = undefined;
|
|
99
|
+
};
|
|
100
|
+
const BANNER_CSS = `
|
|
101
|
+
*{box-sizing:border-box}
|
|
102
|
+
.card{position:fixed;left:50%;bottom:20px;transform:translateX(-50%);width:min(560px,calc(100vw - 32px));display:flex;gap:14px;align-items:flex-end;padding:14px 16px 14px 14px;border-radius:12px;border:1px solid rgba(0,0,0,.1);border-left:4px solid ${COLOR};background:#fff;color:#1b1d22;box-shadow:0 12px 32px rgba(0,0,0,.24);font:400 14px/20px system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;pointer-events:auto;text-align:left}
|
|
103
|
+
.text{flex:1;min-width:0}
|
|
104
|
+
.title{font-weight:700;font-size:13px;line-height:18px;color:${COLOR};margin:0 0 2px}
|
|
105
|
+
.instruction{font-size:15px;line-height:21px;white-space:pre-wrap;overflow-wrap:anywhere;max-height:40vh;overflow:auto;margin:0}
|
|
106
|
+
.hint{margin:6px 0 0;font-size:12px;line-height:16px;color:#5c5f66}
|
|
107
|
+
button{flex:none;padding:8px 18px;border:0;border-radius:8px;background:${COLOR};color:#fff;font:600 14px/20px system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;cursor:pointer}
|
|
108
|
+
button:hover{filter:brightness(1.08)}
|
|
109
|
+
button:focus-visible{outline:3px solid rgba(43,89,255,.45);outline-offset:2px}
|
|
110
|
+
@media (prefers-color-scheme: dark){
|
|
111
|
+
.card{background:#1f2126;color:#f1f2f4;border-color:rgba(255,255,255,.12);border-left-color:${COLOR}}
|
|
112
|
+
.hint{color:#a4a8b0}
|
|
113
|
+
.title{color:#7d9bff}
|
|
114
|
+
}`;
|
|
115
|
+
const TARGET_CSS = `
|
|
116
|
+
.ring{position:fixed;border:3px solid ${COLOR};border-radius:8px;box-shadow:0 0 0 6px rgba(43,89,255,.22);pointer-events:none;animation:pulse 1.6s ease-in-out infinite}
|
|
117
|
+
@keyframes pulse{50%{box-shadow:0 0 0 11px rgba(43,89,255,.06)}}
|
|
118
|
+
@media (prefers-reduced-motion: reduce){.ring{animation:none}}`;
|
|
119
|
+
const buildBanner = (view) => {
|
|
120
|
+
const { host, root } = makeHost("turno-human-step", false);
|
|
121
|
+
style(root, BANNER_CSS);
|
|
122
|
+
const card = el("div", "card");
|
|
123
|
+
card.setAttribute("role", "region");
|
|
124
|
+
card.setAttribute("aria-label", view.title);
|
|
125
|
+
card.setAttribute("lang", view.lang);
|
|
126
|
+
const text = el("div", "text");
|
|
127
|
+
const instruction = el("p", "instruction", view.instruction);
|
|
128
|
+
instruction.setAttribute("aria-live", "polite");
|
|
129
|
+
text.append(el("p", "title", view.title), instruction, el("p", "hint", view.hint));
|
|
130
|
+
card.append(text);
|
|
131
|
+
const banner = {
|
|
132
|
+
doc: document,
|
|
133
|
+
step: view.step,
|
|
134
|
+
key: randomKey(),
|
|
135
|
+
host,
|
|
136
|
+
button: null,
|
|
137
|
+
done: false,
|
|
138
|
+
clicks: 0,
|
|
139
|
+
fields: 0,
|
|
140
|
+
seen: new WeakSet(),
|
|
141
|
+
sensitive: false,
|
|
142
|
+
off: () => { },
|
|
143
|
+
};
|
|
144
|
+
if (view.done !== null) {
|
|
145
|
+
const button = el("button", "", view.done);
|
|
146
|
+
button.setAttribute("type", "button");
|
|
147
|
+
// Only the browser's own input counts: a click a script dispatches is not trusted.
|
|
148
|
+
button.addEventListener("click", (e) => {
|
|
149
|
+
if (e.isTrusted)
|
|
150
|
+
banner.done = true;
|
|
151
|
+
});
|
|
152
|
+
card.append(button);
|
|
153
|
+
banner.button = button;
|
|
154
|
+
}
|
|
155
|
+
root.append(card);
|
|
156
|
+
const onClick = (e) => {
|
|
157
|
+
if (!e.isTrusted || e.composedPath().includes(host))
|
|
158
|
+
return;
|
|
159
|
+
banner.clicks++;
|
|
160
|
+
};
|
|
161
|
+
const onField = (e) => {
|
|
162
|
+
const node = firstOf(e);
|
|
163
|
+
if (!e.isTrusted || !isEditable(node))
|
|
164
|
+
return;
|
|
165
|
+
if (isSensitive(node))
|
|
166
|
+
banner.sensitive = true;
|
|
167
|
+
if (banner.seen.has(node))
|
|
168
|
+
return;
|
|
169
|
+
banner.seen.add(node);
|
|
170
|
+
banner.fields++;
|
|
171
|
+
};
|
|
172
|
+
window.addEventListener("click", onClick, true);
|
|
173
|
+
window.addEventListener("input", onField, true);
|
|
174
|
+
window.addEventListener("change", onField, true);
|
|
175
|
+
banner.off = () => {
|
|
176
|
+
window.removeEventListener("click", onClick, true);
|
|
177
|
+
window.removeEventListener("input", onField, true);
|
|
178
|
+
window.removeEventListener("change", onField, true);
|
|
179
|
+
};
|
|
180
|
+
document.documentElement.append(host);
|
|
181
|
+
return banner;
|
|
182
|
+
};
|
|
183
|
+
const placeRing = (t) => {
|
|
184
|
+
const r = t.el.isConnected ? t.el.getBoundingClientRect() : undefined;
|
|
185
|
+
if (!r || (r.width === 0 && r.height === 0)) {
|
|
186
|
+
t.ring.style.display = "none";
|
|
187
|
+
return;
|
|
188
|
+
}
|
|
189
|
+
const pad = 5;
|
|
190
|
+
t.ring.style.display = "block";
|
|
191
|
+
t.ring.style.left = `${Math.round(r.left - pad)}px`;
|
|
192
|
+
t.ring.style.top = `${Math.round(r.top - pad)}px`;
|
|
193
|
+
t.ring.style.width = `${Math.round(r.width + 2 * pad)}px`;
|
|
194
|
+
t.ring.style.height = `${Math.round(r.height + 2 * pad)}px`;
|
|
195
|
+
};
|
|
196
|
+
const buildTarget = (step, target) => {
|
|
197
|
+
const { host, root } = makeHost("turno-human-target", true);
|
|
198
|
+
style(root, TARGET_CSS);
|
|
199
|
+
const ring = el("div", "ring");
|
|
200
|
+
root.append(ring);
|
|
201
|
+
const t = {
|
|
202
|
+
doc: document,
|
|
203
|
+
step,
|
|
204
|
+
key: randomKey(),
|
|
205
|
+
el: target,
|
|
206
|
+
host,
|
|
207
|
+
ring,
|
|
208
|
+
pressed: false,
|
|
209
|
+
clicked: false,
|
|
210
|
+
off: () => { },
|
|
211
|
+
};
|
|
212
|
+
const on = (e) => e.isTrusted && e.composedPath().includes(target);
|
|
213
|
+
const onDown = (e) => {
|
|
214
|
+
if (on(e))
|
|
215
|
+
t.pressed = true;
|
|
216
|
+
};
|
|
217
|
+
const onClick = (e) => {
|
|
218
|
+
if (on(e))
|
|
219
|
+
t.clicked = true;
|
|
220
|
+
};
|
|
221
|
+
const onMove = () => placeRing(t);
|
|
222
|
+
window.addEventListener("pointerdown", onDown, true);
|
|
223
|
+
window.addEventListener("click", onClick, true);
|
|
224
|
+
window.addEventListener("scroll", onMove, { capture: true, passive: true });
|
|
225
|
+
window.addEventListener("resize", onMove, { passive: true });
|
|
226
|
+
t.off = () => {
|
|
227
|
+
window.removeEventListener("pointerdown", onDown, true);
|
|
228
|
+
window.removeEventListener("click", onClick, true);
|
|
229
|
+
window.removeEventListener("scroll", onMove, true);
|
|
230
|
+
window.removeEventListener("resize", onMove);
|
|
231
|
+
};
|
|
232
|
+
document.documentElement.append(host);
|
|
233
|
+
placeRing(t);
|
|
234
|
+
return t;
|
|
235
|
+
};
|
|
236
|
+
switch (cmd.op) {
|
|
237
|
+
case "banner": {
|
|
238
|
+
const b = state.banner;
|
|
239
|
+
if (!b || b.doc !== document || b.step !== cmd.view.step) {
|
|
240
|
+
if (b && b.doc === document)
|
|
241
|
+
removeBanner();
|
|
242
|
+
state.banner = buildBanner(cmd.view);
|
|
243
|
+
}
|
|
244
|
+
else if (!b.host.isConnected) {
|
|
245
|
+
// The page replaced <html>'s children (or the host itself): put it back.
|
|
246
|
+
document.documentElement.append(b.host);
|
|
247
|
+
}
|
|
248
|
+
break;
|
|
249
|
+
}
|
|
250
|
+
case "target": {
|
|
251
|
+
const t = state.target;
|
|
252
|
+
if (t && t.doc === document && t.step === cmd.step && (!arg.el || t.el === arg.el)) {
|
|
253
|
+
if (!t.host.isConnected)
|
|
254
|
+
document.documentElement.append(t.host);
|
|
255
|
+
}
|
|
256
|
+
else if (arg.el) {
|
|
257
|
+
if (t && t.doc === document)
|
|
258
|
+
removeTarget();
|
|
259
|
+
state.target = buildTarget(cmd.step, arg.el);
|
|
260
|
+
}
|
|
261
|
+
if (state.target && state.target.doc === document)
|
|
262
|
+
placeRing(state.target);
|
|
263
|
+
break;
|
|
264
|
+
}
|
|
265
|
+
case "remove":
|
|
266
|
+
removeBanner();
|
|
267
|
+
removeTarget();
|
|
268
|
+
w[GLOBAL] = undefined;
|
|
269
|
+
break;
|
|
270
|
+
}
|
|
271
|
+
const b = state.banner && state.banner.doc === document ? state.banner : undefined;
|
|
272
|
+
const r = b?.button?.isConnected ? b.button.getBoundingClientRect() : undefined;
|
|
273
|
+
const t = state.target && state.target.doc === document ? state.target : undefined;
|
|
274
|
+
return {
|
|
275
|
+
doc: b?.key ?? t?.key ?? "",
|
|
276
|
+
shown: b !== undefined && b.host.isConnected,
|
|
277
|
+
done: b?.done ?? false,
|
|
278
|
+
clicks: b?.clicks ?? 0,
|
|
279
|
+
fields: b?.fields ?? 0,
|
|
280
|
+
sensitive: b?.sensitive ?? false,
|
|
281
|
+
doneBox: r ? { x: r.x, y: r.y, width: r.width, height: r.height } : null,
|
|
282
|
+
...(t ? { target: { connected: t.el.isConnected, pressed: t.pressed, clicked: t.clicked } } : {}),
|
|
283
|
+
};
|
|
284
|
+
}
|
|
285
|
+
//# sourceMappingURL=human-step-overlay.js.map
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
import type { ElementHandle, Frame, Page } from "patchright-core";
|
|
2
|
+
import { type StepView } from "./human-step-overlay.js";
|
|
3
|
+
import type { VaultGuard } from "./redact.js";
|
|
4
|
+
import type { TurnoTool } from "./tools.js";
|
|
5
|
+
import type { ToolResult } from "./upstream.js";
|
|
6
|
+
import type { BrowserWatch } from "./watch.js";
|
|
7
|
+
/**
|
|
8
|
+
* A person step: `browser_request_human`, the tool an agent calls for what only the person may
|
|
9
|
+
* do (a password, a captcha, an emailed code, a second factor, accepting terms or consent).
|
|
10
|
+
*
|
|
11
|
+
* - The tab comes to the front (and its window out of the dock, when Chrome has one), and a
|
|
12
|
+
* banner at the bottom of the page says what to do, with a Done button; a ring marks the
|
|
13
|
+
* target when the agent names one (`human-step-overlay.ts`). The banner is drawn again on each
|
|
14
|
+
* new document while the step lasts, and removed when it ends. The live view shows it too.
|
|
15
|
+
* - The step pauses the browser like the live view's Pause (`live.ts`): every call of every
|
|
16
|
+
* session waits until the step ends, the idle limit and the tab governor hold, a trace stops.
|
|
17
|
+
* Calls already running finish first, so no agent input lands while the person acts.
|
|
18
|
+
* - It ends on the first of: the URL matches or changes, a selector is visible, Done (a trusted
|
|
19
|
+
* click only), the person resumes the agent, the tab closes, the timeout (5 minutes by
|
|
20
|
+
* default, up to 10: typing a password and solving a captcha, or fetching a code from an
|
|
21
|
+
* email, takes minutes, longer than the 2 minutes the live view holds an unplanned pause).
|
|
22
|
+
* - The result says why it ended, where the tab is, what changed in the tabs and how many
|
|
23
|
+
* clicks and changed fields the person made, never what they typed. A page where the person
|
|
24
|
+
* changed a password or code field is held by the vault guard until it navigates, so the
|
|
25
|
+
* script tools cannot read the value back.
|
|
26
|
+
*/
|
|
27
|
+
export declare const HUMAN_STEP_TOOL = "browser_request_human";
|
|
28
|
+
/** Every person-facing text of the banner, by locale: one place to add a language. */
|
|
29
|
+
declare const HUMAN_STEP_STRINGS: {
|
|
30
|
+
readonly en: {
|
|
31
|
+
readonly title: "Your turn";
|
|
32
|
+
readonly done: "Done";
|
|
33
|
+
readonly hintDone: "The agent is waiting for you. Press Done when you have finished.";
|
|
34
|
+
readonly hintAuto: "The agent is waiting for you and goes on by itself once this step is done.";
|
|
35
|
+
};
|
|
36
|
+
};
|
|
37
|
+
export declare const DEFAULT_STEP_TIMEOUT_MS: number;
|
|
38
|
+
export interface StepParams {
|
|
39
|
+
instruction: string;
|
|
40
|
+
element?: string;
|
|
41
|
+
target?: string;
|
|
42
|
+
url?: string;
|
|
43
|
+
urlChanges: boolean;
|
|
44
|
+
selector?: string;
|
|
45
|
+
done: boolean;
|
|
46
|
+
timeoutMs: number;
|
|
47
|
+
requireHumanClick: boolean;
|
|
48
|
+
}
|
|
49
|
+
/** The tool. The host runs it (`ctx.human`): it needs the pause gate and the session's tab. */
|
|
50
|
+
export declare function requestHumanTool(): TurnoTool;
|
|
51
|
+
/** The tool's arguments as the step uses them, or why they do not make a step. */
|
|
52
|
+
export declare function parseStepParams(params: Record<string, unknown>): StepParams | {
|
|
53
|
+
error: string;
|
|
54
|
+
};
|
|
55
|
+
/**
|
|
56
|
+
* A URL test from `until.url`: `/.../flags` is a regular expression, a pattern with `*` a glob
|
|
57
|
+
* over the whole URL (`*` stops at a `/`, `**` does not), anything else text the URL contains.
|
|
58
|
+
*/
|
|
59
|
+
export declare function urlMatcher(pattern: string): (url: string) => boolean;
|
|
60
|
+
/** The banner and the target ring of one step on one tab, drawn again on every new document. */
|
|
61
|
+
export declare class StepBanner {
|
|
62
|
+
private readonly page;
|
|
63
|
+
private readonly view;
|
|
64
|
+
private readonly target?;
|
|
65
|
+
private readonly docs;
|
|
66
|
+
private latest;
|
|
67
|
+
private pressed;
|
|
68
|
+
private clicked;
|
|
69
|
+
constructor(page: Page, view: StepView, target?: {
|
|
70
|
+
handle: ElementHandle;
|
|
71
|
+
frame: Frame;
|
|
72
|
+
} | undefined);
|
|
73
|
+
/** Draws the banner (and the ring) on the page as it is now. */
|
|
74
|
+
show(): Promise<void>;
|
|
75
|
+
/** Reads what the person did, drawing the banner again where a new document has none. */
|
|
76
|
+
poll(first?: boolean): Promise<void>;
|
|
77
|
+
/** What the person did over every document of the step. */
|
|
78
|
+
totals(): {
|
|
79
|
+
done: boolean;
|
|
80
|
+
clicks: number;
|
|
81
|
+
fields: number;
|
|
82
|
+
sensitive: boolean;
|
|
83
|
+
targetClicked: boolean;
|
|
84
|
+
};
|
|
85
|
+
/** Removes the banner and the ring. */
|
|
86
|
+
remove(): Promise<void>;
|
|
87
|
+
}
|
|
88
|
+
/** Why a step ended. */
|
|
89
|
+
export type StepEnd = "done" | "url" | "url-changed" | "selector" | "resumed" | "closed" | "timeout" | "cancelled";
|
|
90
|
+
export interface StepDeps {
|
|
91
|
+
/** The session's current tab: the step happens there. */
|
|
92
|
+
page: Page;
|
|
93
|
+
watch: BrowserWatch;
|
|
94
|
+
guard: VaultGuard;
|
|
95
|
+
/** The client session, for the tab the live view follows. */
|
|
96
|
+
session: string;
|
|
97
|
+
/** Why the person cannot see this browser now; the step does not start. */
|
|
98
|
+
unseen?: string;
|
|
99
|
+
/** Chrome has a window of its own: bring it back when it is minimized. */
|
|
100
|
+
window: boolean;
|
|
101
|
+
json: boolean;
|
|
102
|
+
signal?: AbortSignal;
|
|
103
|
+
/** Tells a client that asked for progress that the step still waits. */
|
|
104
|
+
progress?: (elapsedMs: number, message: string) => void;
|
|
105
|
+
/** The session's current tab when the step ends. */
|
|
106
|
+
currentPage(): Page | undefined;
|
|
107
|
+
locale?: keyof typeof HUMAN_STEP_STRINGS;
|
|
108
|
+
pollMs?: number;
|
|
109
|
+
drainMs?: number;
|
|
110
|
+
now?: () => number;
|
|
111
|
+
}
|
|
112
|
+
/** Runs one person step on `deps.page` and says how it went. */
|
|
113
|
+
export declare function runHumanStep(params: StepParams, deps: StepDeps): Promise<ToolResult>;
|
|
114
|
+
/** The result of a step: why it ended and what changed, never a value the person typed. */
|
|
115
|
+
export declare function stepResult(o: {
|
|
116
|
+
params: StepParams;
|
|
117
|
+
ended: StepEnd;
|
|
118
|
+
waitedMs: number;
|
|
119
|
+
url?: string | undefined;
|
|
120
|
+
title?: string | undefined;
|
|
121
|
+
lines: readonly string[];
|
|
122
|
+
clicks: number;
|
|
123
|
+
fields: number;
|
|
124
|
+
liveInputs: number;
|
|
125
|
+
targetClicked?: boolean;
|
|
126
|
+
json: boolean;
|
|
127
|
+
}): ToolResult;
|
|
128
|
+
export {};
|