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.
Files changed (47) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/README.md +5 -1
  3. package/dist/act.js +4 -29
  4. package/dist/agent-cursor-overlay.d.ts +10 -0
  5. package/dist/agent-cursor-overlay.js +50 -5
  6. package/dist/agent-cursor.d.ts +39 -7
  7. package/dist/agent-cursor.js +106 -20
  8. package/dist/cli/flows.js +3 -0
  9. package/dist/cli/identity.js +3 -4
  10. package/dist/cli/init.js +4 -2
  11. package/dist/engine-camoufox.js +1 -0
  12. package/dist/engine-lightpanda.js +1 -0
  13. package/dist/host.d.ts +7 -0
  14. package/dist/host.js +313 -76
  15. package/dist/human-step-overlay.d.ts +73 -0
  16. package/dist/human-step-overlay.js +285 -0
  17. package/dist/human-step.d.ts +128 -0
  18. package/dist/human-step.js +521 -0
  19. package/dist/index.d.ts +1 -1
  20. package/dist/index.js +1 -1
  21. package/dist/live-server.d.ts +7 -3
  22. package/dist/live-server.js +13 -15
  23. package/dist/live.d.ts +20 -1
  24. package/dist/live.js +52 -10
  25. package/dist/network-redact.d.ts +28 -0
  26. package/dist/network-redact.js +202 -0
  27. package/dist/recorder.d.ts +0 -21
  28. package/dist/recorder.js +1 -41
  29. package/dist/recordings.d.ts +5 -0
  30. package/dist/recordings.js +4 -2
  31. package/dist/redact.d.ts +7 -0
  32. package/dist/redact.js +32 -1
  33. package/dist/replay.d.ts +2 -0
  34. package/dist/replay.js +33 -14
  35. package/dist/reputation.d.ts +5 -0
  36. package/dist/reputation.js +12 -7
  37. package/dist/sensitive.d.ts +79 -0
  38. package/dist/sensitive.js +275 -0
  39. package/dist/session.d.ts +12 -0
  40. package/dist/session.js +24 -0
  41. package/dist/tools.d.ts +5 -0
  42. package/dist/tools.js +9 -1
  43. package/dist/upstream.d.ts +5 -0
  44. package/dist/watch.d.ts +60 -0
  45. package/dist/watch.js +114 -0
  46. package/npm-shrinkwrap.json +2 -2
  47. package/package.json +1 -1
package/dist/replay.js CHANGED
@@ -70,11 +70,9 @@ async function findTarget(stock, target, ms, signal) {
70
70
  await sleep(250);
71
71
  }
72
72
  }
73
- /** Whether a step puts a sensitive value into the page. */
74
- function typesSecret(step, secret) {
75
- return paramRefs(step.args).some((name) => secret.has(name));
76
- }
77
- async function runStep(run, step, values, secret) {
73
+ async function runStep(run, step, values, secret,
74
+ /** The sensitive parameters the agent did not pass: read from the secret store, or typed by the person. */
75
+ trusted) {
78
76
  const { ctx, stock } = run;
79
77
  if (step.tool === "browser_login") {
80
78
  try {
@@ -102,7 +100,7 @@ async function runStep(run, step, values, secret) {
102
100
  const prepared = await prepareParams(ctx, inner, given);
103
101
  if ("error" in prepared)
104
102
  return { ok: false, message: prepared.error };
105
- const state = await runSteps({ ...run, depth: run.depth + 1 }, inner, prepared.values, prepared.secret, 1);
103
+ const state = await runSteps({ ...run, depth: run.depth + 1 }, inner, prepared.values, prepared.secret, prepared.trusted, 1);
106
104
  if (state.failure)
107
105
  return {
108
106
  ok: false,
@@ -139,19 +137,25 @@ async function runStep(run, step, values, secret) {
139
137
  const parsed = schema.safeParse(args);
140
138
  if (!parsed.success)
141
139
  return { ok: false, message: `invalid arguments: ${stock.formatError(parsed.error)}` };
142
- if (typesSecret(step, secret))
140
+ const secrets = paramRefs(step.args).filter((name) => secret.has(name));
141
+ if (secrets.length)
143
142
  await ctx.recording?.pauseForSecret(stock.currentPage());
144
- const result = await stock.call(step.tool, args, { snapshot: false });
143
+ // A password or one-time code field takes only a value the agent did not pass.
144
+ const fromSecretStore = secrets.length > 0 && secrets.every((name) => trusted.has(name));
145
+ const result = await stock.call(step.tool, args, {
146
+ snapshot: false,
147
+ ...(fromSecretStore ? { fromSecretStore } : {}),
148
+ });
145
149
  if (result.isError)
146
150
  return { ok: false, message: sections(textOf(result)).get("Error") ?? textOf(result) };
147
151
  return { ok: true, ...(used.length ? { note: `found by ${used.join(", ")}` } : {}) };
148
152
  }
149
- async function runSteps(run, flow, values, secret, from) {
153
+ async function runSteps(run, flow, values, secret, trusted, from) {
150
154
  const state = { lines: [] };
151
155
  const total = flow.steps.length;
152
156
  for (let i = from - 1; i < total; i++) {
153
157
  const step = flow.steps[i];
154
- const done = await runStep(run, step, values, secret);
158
+ const done = await runStep(run, step, values, secret, trusted);
155
159
  if (!done.ok) {
156
160
  state.lines.push(`${i + 1}. ${describeStep(step)}: failed`);
157
161
  state.failure = { n: i + 1, total, step, message: done.message };
@@ -178,6 +182,9 @@ async function prepareParams(ctx, flow, given) {
178
182
  };
179
183
  const secret = new Set();
180
184
  const refs = new Set();
185
+ // Sensitive values the person typed at the hidden prompt of `turno-browser replay`.
186
+ const prompted = new Set((vault.identity.env[PROMPTED_ENV] ?? "").split(",").filter(Boolean));
187
+ const trusted = new Set();
181
188
  for (const p of flow.params) {
182
189
  let v = values[p.name];
183
190
  if (v.startsWith("keychain:")) {
@@ -193,14 +200,18 @@ async function prepareParams(ctx, flow, given) {
193
200
  v = read;
194
201
  values[p.name] = v;
195
202
  refs.add(p.name);
203
+ trusted.add(p.name);
196
204
  secret.add(p.name);
197
205
  }
198
- else if (p.sensitive)
206
+ else if (p.sensitive) {
199
207
  secret.add(p.name);
208
+ if (prompted.has(p.name))
209
+ trusted.add(p.name);
210
+ }
200
211
  if (secret.has(p.name))
201
212
  vault.redactor.add(v, `sensitive parameter ${p.name}`);
202
213
  }
203
- return { values, secret, refs };
214
+ return { values, secret, refs, trusted };
204
215
  }
205
216
  function replaySchema() {
206
217
  const z = upstream().utils.z;
@@ -266,7 +277,7 @@ export function replayTool() {
266
277
  if ("error" in prepared)
267
278
  return { content: [{ type: "text", text: `### Error\nNothing ran: ${prepared.error}` }], isError: true };
268
279
  const run = { ctx, stock, waitMs: wait * 1000, depth: 0 };
269
- const exec = () => runSteps(run, flow, prepared.values, prepared.secret, from);
280
+ const exec = () => runSteps(run, flow, prepared.values, prepared.secret, prepared.trusted, from);
270
281
  const state = ctx.recorder ? await ctx.recorder.suspend(exec) : await exec();
271
282
  const out = [];
272
283
  if (state.failure) {
@@ -345,6 +356,11 @@ export function flowsTool() {
345
356
  },
346
357
  };
347
358
  }
359
+ /**
360
+ * Names the parameters of `ReplayOptions.prompted` for the server `replayFlow` starts. Only
361
+ * that server, which serves this one replay and no agent, reads it.
362
+ */
363
+ const PROMPTED_ENV = "TURNO_BROWSER_PROMPTED_PARAMS";
348
364
  /**
349
365
  * Replays a flow outside an agent (`turno browser replay`): starts this package's MCP server
350
366
  * on the identity and calls `browser_replay`, so the run goes through exactly the path an agent's
@@ -358,7 +374,10 @@ export async function replayFlow(id, flow, options = {}) {
358
374
  const transport = new StdioClientTransport({
359
375
  command: process.execPath,
360
376
  args: [bin, "--identity", id, ...(options.headless ? ["--headless"] : [])],
361
- env: Object.fromEntries(Object.entries(env).filter((e) => e[1] !== undefined)),
377
+ env: {
378
+ ...Object.fromEntries(Object.entries(env).filter((e) => e[1] !== undefined && e[0] !== PROMPTED_ENV)),
379
+ ...(options.prompted?.length ? { [PROMPTED_ENV]: options.prompted.join(",") } : {}),
380
+ },
362
381
  stderr: "pipe",
363
382
  });
364
383
  const client = new Client({ name: `${names().browser} replay`, version: "1" });
@@ -80,6 +80,11 @@ export interface WatchOptions {
80
80
  /** The same site and kind within this long counts once (a reload loop). */
81
81
  dedupeMs?: number;
82
82
  now?: () => number;
83
+ /**
84
+ * Hears every check of a page load as it starts, with what it will find (any challenge, also
85
+ * one the log counts once), so a tool result can say the page it ended on is one.
86
+ */
87
+ onCheck?: (page: WatchedPage, found: Promise<Omit<ChallengeEvent, "ts"> | undefined>) => void;
83
88
  }
84
89
  /**
85
90
  * Looks at every page the context loads (each main frame `load`, popups included) and reports
@@ -162,30 +162,35 @@ export function watchChallenges(context, onChallenge, opts = {}) {
162
162
  try {
163
163
  const url = new URL(page.url());
164
164
  if (url.protocol !== "http:" && url.protocol !== "https:")
165
- return;
165
+ return undefined;
166
166
  site = url.hostname;
167
167
  }
168
168
  catch {
169
- return;
169
+ return undefined;
170
170
  }
171
171
  const html = await page.content().catch(() => undefined);
172
172
  if (stopped || html === undefined)
173
- return;
173
+ return undefined;
174
174
  const found = classifyChallenge(html);
175
175
  if (!found)
176
- return;
176
+ return undefined;
177
+ const event = { site, kind: found.kind, markers: found.markers };
177
178
  const key = `${site}\n${found.kind}`;
178
179
  const t = now();
179
180
  const previous = last.get(key);
180
181
  if (previous !== undefined && t - previous < dedupeMs)
181
- return;
182
+ return event;
182
183
  last.set(key, t);
183
- onChallenge({ site, kind: found.kind, markers: found.markers });
184
+ onChallenge(event);
185
+ return event;
184
186
  };
185
187
  const attach = (page) => {
186
188
  if (listeners.has(page))
187
189
  return;
188
- const listener = () => void inspect(page).catch(() => { });
190
+ const listener = () => {
191
+ const found = inspect(page).catch(() => undefined);
192
+ opts.onCheck?.(page, found);
193
+ };
189
194
  listeners.set(page, listener);
190
195
  page.on("load", listener);
191
196
  };
@@ -0,0 +1,79 @@
1
+ import type { Page } from "patchright-core";
2
+ /**
3
+ * Sensitive fields: the one classifier for the inputs whose value the model must never read
4
+ * or write, shared by the host (snapshots, results, the refusal of `browser_type`), flow
5
+ * recording and natural language actions.
6
+ *
7
+ * - `password` and `one-time code` are the sensitive fields: an input of type password, an
8
+ * `autocomplete` of `current-password`, `new-password` or `one-time-code`, or a name or id
9
+ * that reads like one (`password`, `passcode`, `otp`, `totp`, `2fa`, `mfa`, `oneTimeCode`). The
10
+ * host masks their values in every snapshot, hides them in every result, and refuses an agent
11
+ * that types into them: the person types those, or `browser_login` fills them from the vault.
12
+ * - `card` and `secret` (a card number, a PIN, a field named like a token or a secret) are
13
+ * never kept in a flow and never sent to a natural language model, but the agent may fill them.
14
+ *
15
+ * The page is read once per frame (open shadow roots included); the values never leave this
16
+ * process except as the redactor's placeholders.
17
+ */
18
+ export type FieldKind = "password" | "one-time code" | "card" | "secret";
19
+ /** What the page says about an input, enough to classify it. */
20
+ export interface FieldInfo {
21
+ type: string;
22
+ autocomplete: string;
23
+ name: string;
24
+ id: string;
25
+ }
26
+ /** An input of the page with a value, as `pageFields` reads it. */
27
+ export interface PageField extends FieldInfo {
28
+ value: string;
29
+ /** The snapshot ref Playwright gave the element (`e12`, `f1e3`), when it is in a snapshot. */
30
+ ref?: string;
31
+ kind?: FieldKind;
32
+ }
33
+ /** What a masked value reads in a snapshot. */
34
+ export declare const SENSITIVE_MARK = "[sensitive field]";
35
+ /** The words of a name: `newPassword`, `new-password` and `new_password` are `new password`. */
36
+ export declare function wordsOf(name: string): string[];
37
+ /** The kind of a field, or undefined when its value is nobody's secret. */
38
+ export declare function fieldKind(info: FieldInfo): FieldKind | undefined;
39
+ /** A field whose typed value must never be stored (a flow, a natural language prompt). */
40
+ export declare function secretField(info: FieldInfo): boolean;
41
+ /**
42
+ * The inputs with a value in every frame of `page` and the kind of each: one evaluate per
43
+ * frame, in parallel. A frame that cannot be read (navigating, detached) is skipped.
44
+ */
45
+ export declare function pageFields(page: Page): Promise<PageField[]>;
46
+ /** The sensitive fields (`sensitiveKind`) of `page` that hold a value. */
47
+ export declare function sensitiveFields(page: Page): Promise<PageField[]>;
48
+ /**
49
+ * An aria snapshot (`mode: "ai"`) with the value of each element in `refs` replaced by
50
+ * `SENSITIVE_MARK`: `- textbox "Password" [ref=e6]: hunter2` reads
51
+ * `- textbox "Password" [ref=e6]: [sensitive field]`, whatever the length of the value.
52
+ */
53
+ export declare function maskSnapshot(text: string, refs: ReadonlySet<string>): string;
54
+ /** The same masking on the JSON form of an aria snapshot (`ariaSnapshotJSON`). */
55
+ export declare function maskSnapshotJSON<T>(json: T, refs: ReadonlySet<string>): T;
56
+ /** The refs of the sensitive fields among `fields`. */
57
+ export declare function sensitiveRefs(fields: readonly PageField[]): Set<string>;
58
+ /**
59
+ * Makes every aria snapshot of `page` mask its sensitive fields: Playwright MCP takes the page
60
+ * snapshot of a tool result with `page.ariaSnapshot` (or `ariaSnapshotJSON` in JSON mode), and
61
+ * writes it to a file or puts it in the result right after. The fields are read after the
62
+ * snapshot, so the refs are the ones it just gave; `onFields` hears them first (the host's
63
+ * redactor learns the values, for the rest of the result). Undone with the returned function.
64
+ */
65
+ export declare function maskSnapshots(page: Page, onFields: (fields: PageField[]) => void): () => void;
66
+ /** The stock tools that type text, and the arguments that say where. */
67
+ export declare const TYPING_TOOLS: ReadonlySet<string>;
68
+ /**
69
+ * The kind of sensitive field a typing call would put text into, or undefined. A target the
70
+ * page cannot resolve counts as not sensitive: the call then fails the same way.
71
+ */
72
+ export declare function typesIntoSensitive(page: Page, tool: string, args: Record<string, unknown>): Promise<"password" | "one-time code" | undefined>;
73
+ /** The error of a typing call into a sensitive field. */
74
+ export declare function sensitiveRefusal(tool: string, kind: "password" | "one-time code"): string;
75
+ /**
76
+ * The values `browser_type` or `browser_fill_form` would put into secret fields (`secretField`),
77
+ * so a recording can stop its trace first.
78
+ */
79
+ export declare function secretValues(page: Page, tool: string, args: Record<string, unknown>): Promise<string[]>;
@@ -0,0 +1,275 @@
1
+ /** What a masked value reads in a snapshot. */
2
+ export const SENSITIVE_MARK = "[sensitive field]";
3
+ const PASSWORD_AUTOCOMPLETE = /(^|\s)(current-password|new-password)(\s|$)/i;
4
+ const CODE_AUTOCOMPLETE = /(^|\s)one-time-code(\s|$)/i;
5
+ const CARD_AUTOCOMPLETE = /(^|\s)(cc-number|cc-csc|cc-exp(-month|-year)?)(\s|$)/i;
6
+ /** Broad on purpose: a flow never keeps what was typed into a field named like this. */
7
+ const SECRET_NAME = /pass(word|wd|code)?|pwd|otp|totp|2fa|mfa|(^|[^a-z])pin([^a-z]|$)|cvv|cvc|csc|secret|token|ssn/i;
8
+ const PASSWORD_WORD = /^(pass|pwd|passwd|passcode|passphrase)$|password/;
9
+ const CODE_WORDS = new Set(["otp", "totp", "hotp", "2fa", "mfa", "tfa", "onetime"]);
10
+ /** The words of a name: `newPassword`, `new-password` and `new_password` are `new password`. */
11
+ export function wordsOf(name) {
12
+ return name
13
+ .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
14
+ .toLowerCase()
15
+ .split(/[^a-z0-9]+/)
16
+ .filter(Boolean);
17
+ }
18
+ function nameKind(name) {
19
+ const words = wordsOf(name);
20
+ if (words.some((w) => PASSWORD_WORD.test(w)))
21
+ return "password";
22
+ if (words.some((w) => CODE_WORDS.has(w)))
23
+ return "one-time code";
24
+ for (let i = 0; i + 1 < words.length; i++)
25
+ if (words[i] === "one" && words[i + 1] === "time")
26
+ return "one-time code";
27
+ return undefined;
28
+ }
29
+ /** The kind of a field, or undefined when its value is nobody's secret. */
30
+ export function fieldKind(info) {
31
+ if (info.type.toLowerCase() === "password")
32
+ return "password";
33
+ if (PASSWORD_AUTOCOMPLETE.test(info.autocomplete))
34
+ return "password";
35
+ if (CODE_AUTOCOMPLETE.test(info.autocomplete))
36
+ return "one-time code";
37
+ if (CARD_AUTOCOMPLETE.test(info.autocomplete))
38
+ return "card";
39
+ const named = nameKind(info.name) ?? nameKind(info.id);
40
+ if (named)
41
+ return named;
42
+ return SECRET_NAME.test(`${info.name} ${info.id}`) ? "secret" : undefined;
43
+ }
44
+ /** A field whose typed value must never be stored (a flow, a natural language prompt). */
45
+ export function secretField(info) {
46
+ return fieldKind(info) !== undefined;
47
+ }
48
+ /** A field only the person or the vault fills, whose value no result shows. */
49
+ function sensitiveKind(kind) {
50
+ return kind === "password" || kind === "one-time code";
51
+ }
52
+ /** Most fields read in one frame; a page with more is not a form anyone signs in with. */
53
+ const MAX_FIELDS = 500;
54
+ /** Every input and textarea of one frame with a value, open shadow roots included. */
55
+ function readFrame(frame) {
56
+ return frame.evaluate((max) => {
57
+ const out = [];
58
+ const skip = new Set(["checkbox", "radio", "submit", "button", "reset", "image", "file", "range", "color"]);
59
+ const walk = (root) => {
60
+ for (const el of Array.from(root.querySelectorAll("*"))) {
61
+ if (out.length >= max)
62
+ return;
63
+ if (el.shadowRoot)
64
+ walk(el.shadowRoot);
65
+ if (el.tagName !== "INPUT" && el.tagName !== "TEXTAREA")
66
+ continue;
67
+ const field = el;
68
+ const type = (field.type || "").toLowerCase();
69
+ if (!field.value || skip.has(type))
70
+ continue;
71
+ // The ref Playwright's snapshot gave this element, so the host can mask that line.
72
+ const ref = el._ariaRef?.ref;
73
+ out.push({
74
+ type,
75
+ autocomplete: field.getAttribute("autocomplete") ?? "",
76
+ name: field.getAttribute("name") ?? "",
77
+ id: field.id,
78
+ value: field.value,
79
+ ...(typeof ref === "string" ? { ref } : {}),
80
+ });
81
+ }
82
+ };
83
+ walk(document);
84
+ return out;
85
+ }, MAX_FIELDS);
86
+ }
87
+ /**
88
+ * The inputs with a value in every frame of `page` and the kind of each: one evaluate per
89
+ * frame, in parallel. A frame that cannot be read (navigating, detached) is skipped.
90
+ */
91
+ export async function pageFields(page) {
92
+ const frames = await Promise.all(page.frames().map((f) => readFrame(f).catch(() => [])));
93
+ return frames.flat().map((f) => {
94
+ const kind = fieldKind(f);
95
+ return kind ? { ...f, kind } : f;
96
+ });
97
+ }
98
+ /** The sensitive fields (`sensitiveKind`) of `page` that hold a value. */
99
+ export async function sensitiveFields(page) {
100
+ return (await pageFields(page)).filter((f) => sensitiveKind(f.kind));
101
+ }
102
+ const REF = /^(f\d+)?e\d+$/;
103
+ /**
104
+ * An aria snapshot (`mode: "ai"`) with the value of each element in `refs` replaced by
105
+ * `SENSITIVE_MARK`: `- textbox "Password" [ref=e6]: hunter2` reads
106
+ * `- textbox "Password" [ref=e6]: [sensitive field]`, whatever the length of the value.
107
+ */
108
+ export function maskSnapshot(text, refs) {
109
+ if (!refs.size || !text)
110
+ return text;
111
+ return text.replace(/^(\s*- [^\n]*?\[ref=((?:f\d+)?e\d+)\](?: \[[^\]\n]*\])*):( .*)?$/gm, (line, head, ref, value) => refs.has(ref) && value !== undefined ? `${head}: ${SENSITIVE_MARK}` : line);
112
+ }
113
+ /** The same masking on the JSON form of an aria snapshot (`ariaSnapshotJSON`). */
114
+ export function maskSnapshotJSON(json, refs) {
115
+ if (!refs.size)
116
+ return json;
117
+ const walk = (node) => {
118
+ if (Array.isArray(node))
119
+ return node.map(walk);
120
+ if (!node || typeof node !== "object")
121
+ return node;
122
+ const n = node;
123
+ const out = { ...n };
124
+ const masked = typeof n.ref === "string" && refs.has(n.ref);
125
+ if (masked) {
126
+ if ("text" in n)
127
+ out.text = SENSITIVE_MARK;
128
+ if ("value" in n)
129
+ out.value = SENSITIVE_MARK;
130
+ }
131
+ if (Array.isArray(n.children))
132
+ out.children = n.children.map((c) => (masked && typeof c === "string" ? SENSITIVE_MARK : walk(c)));
133
+ return out;
134
+ };
135
+ return walk(json);
136
+ }
137
+ /** The refs of the sensitive fields among `fields`. */
138
+ export function sensitiveRefs(fields) {
139
+ return new Set(fields.filter((f) => sensitiveKind(f.kind) && f.ref && REF.test(f.ref)).map((f) => f.ref));
140
+ }
141
+ /**
142
+ * Makes every aria snapshot of `page` mask its sensitive fields: Playwright MCP takes the page
143
+ * snapshot of a tool result with `page.ariaSnapshot` (or `ariaSnapshotJSON` in JSON mode), and
144
+ * writes it to a file or puts it in the result right after. The fields are read after the
145
+ * snapshot, so the refs are the ones it just gave; `onFields` hears them first (the host's
146
+ * redactor learns the values, for the rest of the result). Undone with the returned function.
147
+ */
148
+ export function maskSnapshots(page, onFields) {
149
+ const target = page;
150
+ const text = target.ariaSnapshot;
151
+ const json = target.ariaSnapshotJSON;
152
+ const read = async () => {
153
+ const fields = await sensitiveFields(page).catch(() => []);
154
+ if (fields.length)
155
+ onFields(fields);
156
+ return sensitiveRefs(fields);
157
+ };
158
+ target.ariaSnapshot = async (options) => {
159
+ const out = (await text.call(page, options));
160
+ return maskSnapshot(out, await read());
161
+ };
162
+ if (json)
163
+ target.ariaSnapshotJSON = async (options) => {
164
+ const out = await json.call(page, options);
165
+ return maskSnapshotJSON(out, await read());
166
+ };
167
+ return () => {
168
+ target.ariaSnapshot = text;
169
+ if (json)
170
+ target.ariaSnapshotJSON = json;
171
+ };
172
+ }
173
+ /** Keys that put a character into the focused field (`a`, `Shift+A`), not `Enter` or `Tab`. */
174
+ function typesCharacter(key) {
175
+ if (typeof key !== "string")
176
+ return false;
177
+ const last = key.split("+").pop() ?? "";
178
+ return last.length === 1 && !/^(Control|Meta|Alt)\+/i.test(key);
179
+ }
180
+ async function targetInfo(page, target) {
181
+ const locator = page.locator(REF.test(target) ? `aria-ref=${target}` : target);
182
+ return await locator
183
+ .evaluate((el) => ({
184
+ type: (el.type || "").toLowerCase(),
185
+ autocomplete: el.getAttribute("autocomplete") ?? "",
186
+ name: el.getAttribute("name") ?? "",
187
+ id: el.id,
188
+ }), undefined, { timeout: 2_000 })
189
+ .catch(() => undefined);
190
+ }
191
+ /** The focused element of a frame, through open shadow roots; undefined when the frame has no focus. */
192
+ function focusedInfo(frame) {
193
+ return frame.evaluate(() => {
194
+ if (!document.hasFocus())
195
+ return undefined;
196
+ let el = document.activeElement;
197
+ while (el?.shadowRoot?.activeElement)
198
+ el = el.shadowRoot.activeElement;
199
+ if (!el || (el.tagName !== "INPUT" && el.tagName !== "TEXTAREA"))
200
+ return undefined;
201
+ return {
202
+ type: (el.type || "").toLowerCase(),
203
+ autocomplete: el.getAttribute("autocomplete") ?? "",
204
+ name: el.getAttribute("name") ?? "",
205
+ id: el.id,
206
+ };
207
+ });
208
+ }
209
+ /** The stock tools that type text, and the arguments that say where. */
210
+ export const TYPING_TOOLS = new Set([
211
+ "browser_type",
212
+ "browser_fill_form",
213
+ "browser_press_key",
214
+ "browser_press_sequentially",
215
+ "browser_keydown",
216
+ ]);
217
+ /**
218
+ * The kind of sensitive field a typing call would put text into, or undefined. A target the
219
+ * page cannot resolve counts as not sensitive: the call then fails the same way.
220
+ */
221
+ export async function typesIntoSensitive(page, tool, args) {
222
+ const targets = [];
223
+ if (tool === "browser_type") {
224
+ if (typeof args.target === "string" && typeof args.text === "string" && args.text)
225
+ targets.push(args.target);
226
+ }
227
+ else if (tool === "browser_fill_form") {
228
+ if (Array.isArray(args.fields))
229
+ for (const f of args.fields)
230
+ if (f.type === "textbox" && typeof f.target === "string" && typeof f.value === "string" && f.value)
231
+ targets.push(f.target);
232
+ }
233
+ else if (tool === "browser_press_sequentially" ? typeof args.text === "string" && args.text : typesCharacter(args.key)) {
234
+ for (const frame of page.frames()) {
235
+ const kind = fieldKind((await focusedInfo(frame).catch(() => undefined)) ?? { type: "", autocomplete: "", name: "", id: "" });
236
+ if (sensitiveKind(kind))
237
+ return kind;
238
+ }
239
+ return undefined;
240
+ }
241
+ for (const target of targets) {
242
+ const info = await targetInfo(page, target);
243
+ const kind = info ? fieldKind(info) : undefined;
244
+ if (sensitiveKind(kind))
245
+ return kind;
246
+ }
247
+ return undefined;
248
+ }
249
+ /** The error of a typing call into a sensitive field. */
250
+ export function sensitiveRefusal(tool, kind) {
251
+ return `${tool} was refused: that field takes a ${kind}, and the agent never types one. Ask the person to type it (with browser_request_human, if this server offers it), or sign in with browser_login and a vault entry for this site; a flow replay can type one passed as keychain:<item>.`;
252
+ }
253
+ /**
254
+ * The values `browser_type` or `browser_fill_form` would put into secret fields (`secretField`),
255
+ * so a recording can stop its trace first.
256
+ */
257
+ export async function secretValues(page, tool, args) {
258
+ const pairs = tool === "browser_type"
259
+ ? [[args.target, args.text]]
260
+ : tool === "browser_fill_form" && Array.isArray(args.fields)
261
+ ? args.fields
262
+ .filter((f) => f.type === "textbox")
263
+ .map((f) => [f.target, f.value])
264
+ : [];
265
+ const out = [];
266
+ for (const [target, value] of pairs) {
267
+ if (typeof target !== "string" || typeof value !== "string" || !value)
268
+ continue;
269
+ const info = await targetInfo(page, target);
270
+ if (info && secretField(info))
271
+ out.push(value);
272
+ }
273
+ return out;
274
+ }
275
+ //# sourceMappingURL=sensitive.js.map
package/dist/session.d.ts CHANGED
@@ -5,6 +5,13 @@
5
5
  * keys each session's backend and tab locks on it (`sharing.ts`).
6
6
  */
7
7
  export declare const SESSION_META_KEY = "io.turno/session";
8
+ /**
9
+ * The name of the agent a relayed call comes from (the client's `clientInfo.name`, like
10
+ * "claude-code" or "codex-mcp-client"). mcpd puts it next to the session id when it knows it, so
11
+ * the agent cursor names each session's agent, not mcpd. A server talking to a client directly
12
+ * uses that client's own name instead.
13
+ */
14
+ export declare const CLIENT_META_KEY = "io.turno/client";
8
15
  /**
9
16
  * The experimental capability a server declares in `initialize` to hear when a client session
10
17
  * ends: mcpd then sends it `SESSION_ENDED_METHOD` with `{ session: <the id above> }` for each
@@ -18,3 +25,8 @@ export declare const SESSION_ENDED_METHOD = "notifications/io.turno/session_ende
18
25
  * printable string (a client talking to the server directly may send anything there).
19
26
  */
20
27
  export declare function sessionFromMeta(meta: unknown): string | undefined;
28
+ /**
29
+ * The client name in a request's `_meta` (`CLIENT_META_KEY`), or undefined when there is none
30
+ * or it is not a short printable string.
31
+ */
32
+ export declare function clientFromMeta(meta: unknown): string | undefined;
package/dist/session.js CHANGED
@@ -5,6 +5,13 @@
5
5
  * keys each session's backend and tab locks on it (`sharing.ts`).
6
6
  */
7
7
  export const SESSION_META_KEY = "io.turno/session";
8
+ /**
9
+ * The name of the agent a relayed call comes from (the client's `clientInfo.name`, like
10
+ * "claude-code" or "codex-mcp-client"). mcpd puts it next to the session id when it knows it, so
11
+ * the agent cursor names each session's agent, not mcpd. A server talking to a client directly
12
+ * uses that client's own name instead.
13
+ */
14
+ export const CLIENT_META_KEY = "io.turno/client";
8
15
  /**
9
16
  * The experimental capability a server declares in `initialize` to hear when a client session
10
17
  * ends: mcpd then sends it `SESSION_ENDED_METHOD` with `{ session: <the id above> }` for each
@@ -27,4 +34,21 @@ export function sessionFromMeta(meta) {
27
34
  return undefined;
28
35
  return /^[\x21-\x7e]+$/.test(value) ? value : undefined;
29
36
  }
37
+ /** Longest client name accepted. */
38
+ const MAX_CLIENT = 64;
39
+ /**
40
+ * The client name in a request's `_meta` (`CLIENT_META_KEY`), or undefined when there is none
41
+ * or it is not a short printable string.
42
+ */
43
+ export function clientFromMeta(meta) {
44
+ if (typeof meta !== "object" || meta === null)
45
+ return undefined;
46
+ const value = meta[CLIENT_META_KEY];
47
+ if (typeof value !== "string")
48
+ return undefined;
49
+ const name = value.trim();
50
+ if (name.length === 0 || name.length > MAX_CLIENT)
51
+ return undefined;
52
+ return /^[\x20-\x7e]+$/.test(name) ? name : undefined;
53
+ }
30
54
  //# sourceMappingURL=session.js.map
package/dist/tools.d.ts CHANGED
@@ -26,9 +26,12 @@ export interface StockAccess {
26
26
  /**
27
27
  * Runs a stock tool the way a call of its own runs (tab governor, click diagnosis); with
28
28
  * `snapshot: false` the result leaves out the page snapshot an action would add.
29
+ * `fromSecretStore` says the text typed was read from the secret store (a flow replay's
30
+ * `keychain:` parameter), so it may go into a password or one-time code field.
29
31
  */
30
32
  call(name: string, args: Record<string, unknown>, options: {
31
33
  snapshot: boolean;
34
+ fromSecretStore?: boolean;
32
35
  }): Promise<ToolResult>;
33
36
  /** URL and title of the current tab, when there is one. */
34
37
  page(): Promise<{
@@ -71,6 +74,8 @@ interface TurnoToolContext {
71
74
  engine?: string;
72
75
  /** Providers that replace the configured ones (tests inject fakes). */
73
76
  providers?: Providers;
77
+ /** Runs a person step on the session's tab (`browser_request_human`); set by the host for it. */
78
+ human?: (params: Record<string, unknown>) => Promise<ToolResult>;
74
79
  }
75
80
  /** Stand-ins for the opt-in providers: a model for natural language actions, a captcha solver. */
76
81
  export interface Providers {
package/dist/tools.js CHANGED
@@ -1,12 +1,20 @@
1
1
  import { actTool, extractTool, observeTool } from "./act.js";
2
2
  import { batchTool } from "./batch.js";
3
3
  import { solveCaptchaTool } from "./captcha.js";
4
+ import { requestHumanTool } from "./human-step.js";
4
5
  import { loginTool } from "./login-tool.js";
5
6
  import { recordTool } from "./recorder.js";
6
7
  import { flowsTool, replayTool } from "./replay.js";
7
8
  import { upstream, } from "./upstream.js";
8
9
  /** The tools turno adds to every session. */
9
- export const TURNO_TOOLS = [batchTool(), loginTool(), recordTool(), replayTool(), flowsTool()];
10
+ export const TURNO_TOOLS = [
11
+ batchTool(),
12
+ loginTool(),
13
+ recordTool(),
14
+ replayTool(),
15
+ flowsTool(),
16
+ requestHumanTool(),
17
+ ];
10
18
  /**
11
19
  * The tools an identity lists only after the person turns their feature on in identity.json
12
20
  * (format 8): natural language actions (`act`) and captcha solving (`captcha`). Off, they are
@@ -120,6 +120,11 @@ export interface UpstreamContext {
120
120
  newTab(): Promise<UpstreamTab>;
121
121
  /** Points the stock tools at a tab without bringing it to the front (`"sharing": "tabs"`). */
122
122
  _setCurrentTab(tab: UpstreamTab | undefined): void;
123
+ /**
124
+ * What upstream passes every text result, written file and session log line through (its own
125
+ * `secrets` config). The host chains its redactor here, so a file a tool writes is redacted too.
126
+ */
127
+ redactSecrets(text: string): string;
123
128
  }
124
129
  /**
125
130
  * The tabs of a `BrowserBackend`, for the tab governor: `initialize` builds the