turno-browser 0.6.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 (76) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/README.md +13 -5
  3. package/dist/act.js +4 -29
  4. package/dist/agent-cursor-overlay.d.ts +95 -0
  5. package/dist/agent-cursor-overlay.js +358 -0
  6. package/dist/agent-cursor.d.ts +191 -0
  7. package/dist/agent-cursor.js +494 -0
  8. package/dist/api.d.ts +8 -3
  9. package/dist/api.js +6 -3
  10. package/dist/argv.d.ts +2 -1
  11. package/dist/argv.js +7 -1
  12. package/dist/bin/mcp.js +5 -0
  13. package/dist/cli/commands.js +12 -3
  14. package/dist/cli/completion.js +3 -0
  15. package/dist/cli/context.d.ts +2 -0
  16. package/dist/cli/context.js +8 -4
  17. package/dist/cli/do-background.d.ts +2 -0
  18. package/dist/cli/do-background.js +15 -0
  19. package/dist/cli/do.d.ts +4 -0
  20. package/dist/cli/do.js +17 -1
  21. package/dist/cli/flows.js +3 -0
  22. package/dist/cli/identity.d.ts +2 -0
  23. package/dist/cli/identity.js +67 -11
  24. package/dist/cli/init.d.ts +12 -0
  25. package/dist/cli/init.js +219 -0
  26. package/dist/cli/login-summary.d.ts +6 -0
  27. package/dist/cli/login-summary.js +11 -0
  28. package/dist/cli/main.js +3 -0
  29. package/dist/cli/setup.d.ts +32 -0
  30. package/dist/cli/setup.js +32 -23
  31. package/dist/doctor.js +18 -2
  32. package/dist/engine-camoufox.js +1 -0
  33. package/dist/engine-lightpanda.js +1 -0
  34. package/dist/host.d.ts +7 -0
  35. package/dist/host.js +330 -68
  36. package/dist/human-input.d.ts +5 -0
  37. package/dist/human-input.js +1 -1
  38. package/dist/human-step-overlay.d.ts +73 -0
  39. package/dist/human-step-overlay.js +285 -0
  40. package/dist/human-step.d.ts +128 -0
  41. package/dist/human-step.js +521 -0
  42. package/dist/index.d.ts +2 -2
  43. package/dist/index.js +2 -2
  44. package/dist/live-server.d.ts +7 -3
  45. package/dist/live-server.js +13 -15
  46. package/dist/live.d.ts +20 -1
  47. package/dist/live.js +52 -10
  48. package/dist/login.d.ts +22 -2
  49. package/dist/login.js +95 -7
  50. package/dist/network-redact.d.ts +28 -0
  51. package/dist/network-redact.js +202 -0
  52. package/dist/recorder.d.ts +0 -21
  53. package/dist/recorder.js +1 -41
  54. package/dist/recordings.d.ts +5 -0
  55. package/dist/recordings.js +4 -2
  56. package/dist/redact.d.ts +7 -0
  57. package/dist/redact.js +32 -1
  58. package/dist/replay.d.ts +2 -0
  59. package/dist/replay.js +33 -14
  60. package/dist/reputation.d.ts +5 -0
  61. package/dist/reputation.js +12 -7
  62. package/dist/sensitive.d.ts +79 -0
  63. package/dist/sensitive.js +275 -0
  64. package/dist/session.d.ts +12 -0
  65. package/dist/session.js +24 -0
  66. package/dist/settings.d.ts +12 -2
  67. package/dist/settings.js +14 -2
  68. package/dist/tools.d.ts +5 -0
  69. package/dist/tools.js +9 -1
  70. package/dist/tuning.d.ts +4 -1
  71. package/dist/tuning.js +1 -0
  72. package/dist/upstream.d.ts +5 -0
  73. package/dist/watch.d.ts +60 -0
  74. package/dist/watch.js +114 -0
  75. package/npm-shrinkwrap.json +2 -2
  76. package/package.json +1 -1
package/dist/api.d.ts CHANGED
@@ -3,7 +3,7 @@ import { runDoctor } from "./doctor.js";
3
3
  import { readHealth } from "./health.js";
4
4
  import { addIdentity, identityExists, inUseBy, isInUse, listIdentities, removeIdentity } from "./identities.js";
5
5
  import { assertIdentityId, identityDir } from "./ids.js";
6
- import { loginIdentity } from "./login.js";
6
+ import { loginIdentity, profileHasCookies, readLoginRecord } from "./login.js";
7
7
  import { reputationReport } from "./reputation.js";
8
8
  import { exportSession, importSession, readSessionExport } from "./session-export.js";
9
9
  import { flowsDir, listFlows, readFlow, removeFlow } from "./flows.js";
@@ -30,7 +30,7 @@ import { browserCli } from "./cli/commands.js";
30
30
  */
31
31
  export declare const API_VERSION: Readonly<{
32
32
  readonly major: 1;
33
- readonly minor: 12;
33
+ readonly minor: 13;
34
34
  }>;
35
35
  /** What `API_VERSION` looks like to a reader that does not know this package's version. */
36
36
  export interface ApiVersion {
@@ -52,7 +52,8 @@ export interface ApiVersion {
52
52
  * the Camoufox and network checks of `runDoctor` (no new member: an older package refuses them),
53
53
  * and (1.11) the background server of an identity: start, status, stop, and its sessions.
54
54
  * and (1.12) `cli`, the identity commands themselves (`turno-browser <cmd>`), which turno-cli runs
55
- * as `turno browser <cmd>` and `turno identity ... browser:<id>` with a host of its own.
55
+ * as `turno browser <cmd>` and `turno identity ... browser:<id>` with a host of its own,
56
+ * and (1.13) `readLoginRecord`, the last sign-in by hand, `profileHasCookies`, and the sites `loginIdentity` returns.
56
57
  */
57
58
  declare const functions: {
58
59
  ENGINES: readonly ["chrome-headed", "chrome-headless", "chrome-baseline", "firefox"];
@@ -68,6 +69,8 @@ declare const functions: {
68
69
  assertIdentityId: typeof assertIdentityId;
69
70
  manifestSnippet: typeof manifestSnippet;
70
71
  loginIdentity: typeof loginIdentity;
72
+ readLoginRecord: typeof readLoginRecord;
73
+ profileHasCookies: typeof profileHasCookies;
71
74
  checkIdentitySettings: typeof checkIdentitySettings;
72
75
  writeIdentitySettings: typeof writeIdentitySettings;
73
76
  readHealth: typeof readHealth;
@@ -118,6 +121,8 @@ export declare const api: Readonly<{
118
121
  assertIdentityId: typeof assertIdentityId;
119
122
  manifestSnippet: typeof manifestSnippet;
120
123
  loginIdentity: typeof loginIdentity;
124
+ readLoginRecord: typeof readLoginRecord;
125
+ profileHasCookies: typeof profileHasCookies;
121
126
  checkIdentitySettings: typeof checkIdentitySettings;
122
127
  writeIdentitySettings: typeof writeIdentitySettings;
123
128
  readHealth: typeof readHealth;
package/dist/api.js CHANGED
@@ -3,7 +3,7 @@ import { runDoctor } from "./doctor.js";
3
3
  import { readHealth } from "./health.js";
4
4
  import { addIdentity, identityExists, inUseBy, isInUse, listIdentities, removeIdentity } from "./identities.js";
5
5
  import { assertIdentityId, identityDir } from "./ids.js";
6
- import { loginIdentity } from "./login.js";
6
+ import { loginIdentity, profileHasCookies, readLoginRecord } from "./login.js";
7
7
  import { reputationReport } from "./reputation.js";
8
8
  import { exportSession, importSession, readSessionExport } from "./session-export.js";
9
9
  import { flowsDir, listFlows, readFlow, removeFlow } from "./flows.js";
@@ -28,7 +28,7 @@ import { browserCli } from "./cli/commands.js";
28
28
  *
29
29
  * `test/api.test.ts` lists the members, so a change here cannot ship without the version.
30
30
  */
31
- export const API_VERSION = Object.freeze({ major: 1, minor: 12 });
31
+ export const API_VERSION = Object.freeze({ major: 1, minor: 13 });
32
32
  /**
33
33
  * The functions turno-cli calls: identities, their settings, login, doctor, reputation, bench
34
34
  * (1.1) the credential vault, (1.2) session export and import, (1.3) the `humanize` key of
@@ -44,7 +44,8 @@ export const API_VERSION = Object.freeze({ major: 1, minor: 12 });
44
44
  * the Camoufox and network checks of `runDoctor` (no new member: an older package refuses them),
45
45
  * and (1.11) the background server of an identity: start, status, stop, and its sessions.
46
46
  * and (1.12) `cli`, the identity commands themselves (`turno-browser <cmd>`), which turno-cli runs
47
- * as `turno browser <cmd>` and `turno identity ... browser:<id>` with a host of its own.
47
+ * as `turno browser <cmd>` and `turno identity ... browser:<id>` with a host of its own,
48
+ * and (1.13) `readLoginRecord`, the last sign-in by hand, `profileHasCookies`, and the sites `loginIdentity` returns.
48
49
  */
49
50
  const functions = {
50
51
  ENGINES,
@@ -60,6 +61,8 @@ const functions = {
60
61
  assertIdentityId,
61
62
  manifestSnippet,
62
63
  loginIdentity,
64
+ readLoginRecord,
65
+ profileHasCookies,
63
66
  checkIdentitySettings,
64
67
  writeIdentitySettings,
65
68
  readHealth,
package/dist/argv.d.ts CHANGED
@@ -18,7 +18,7 @@ import type { TuningFlags } from "./tuning.js";
18
18
  * Headed mode and `viewport: null` are already the program's defaults for headed runs, so
19
19
  * nothing is added for them; no init scripts are ever added.
20
20
  *
21
- * The tab governor, background throttling, humanize and sharing flags (`TUNING_FLAGS`) are turno's: they are
21
+ * The tab governor, background throttling, humanize, sharing and cursor flags (`TUNING_FLAGS`) are turno's: they are
22
22
  * taken out here and win over identity.json. So are `--engine <chrome|lightpanda|camoufox>` and `--attach <target>` (`engine.ts`); with either and
23
23
  * no identity there is no Chrome profile to create. So are `--live` and `--live-wait <duration>` (`live.ts`), which need an identity.
24
24
  *
@@ -70,6 +70,7 @@ export declare const TUNING_FLAGS: {
70
70
  readonly "--background-throttling": "";
71
71
  readonly "--humanize": "<off|light|full|adaptive>";
72
72
  readonly "--sharing": "<session|tabs>";
73
+ readonly "--cursor": "<auto|on|off>";
73
74
  };
74
75
  /** Removes turno's tuning flags (`TUNING_FLAGS`) from args and returns their values. */
75
76
  export declare function extractTuning(args: string[]): {
package/dist/argv.js CHANGED
@@ -4,7 +4,7 @@ import { join } from "node:path";
4
4
  import { browserPaths as paths } from "turno-core/paths";
5
5
  import { HUMANIZE_LEVELS } from "./humanize.js";
6
6
  import { assertIdentityId, identityDir } from "./identities.js";
7
- import { MAX_LIVE_WAIT_MS, MIN_LIVE_WAIT_MS } from "./settings.js";
7
+ import { CURSOR_MODES, MAX_LIVE_WAIT_MS, MIN_LIVE_WAIT_MS } from "./settings.js";
8
8
  import { parseAttachTarget } from "./engine-attach.js";
9
9
  import { parseDuration } from "./units.js";
10
10
  /** How long Chrome stays open without a tool call, unless TURNO_BROWSER_IDLE says otherwise. */
@@ -74,6 +74,7 @@ export const TUNING_FLAGS = {
74
74
  "--background-throttling": "",
75
75
  "--humanize": "<off|light|full|adaptive>",
76
76
  "--sharing": "<session|tabs>",
77
+ "--cursor": "<auto|on|off>",
77
78
  };
78
79
  function tuningValue(flag, value, out) {
79
80
  if (flag === "--max-tabs") {
@@ -96,6 +97,11 @@ function tuningValue(flag, value, out) {
96
97
  throw new Error(`--sharing must be "session" (one agent session at a time) or "tabs", not "${value}"`);
97
98
  out.sharing = value;
98
99
  }
100
+ else if (flag === "--cursor") {
101
+ if (!CURSOR_MODES.includes(value))
102
+ throw new Error(`--cursor must be "auto" (when the browser can be seen), "on" or "off", not "${value}"`);
103
+ out.cursor = value;
104
+ }
99
105
  else {
100
106
  const ms = parseDuration(value);
101
107
  if (ms === undefined)
package/dist/bin/mcp.js CHANGED
@@ -49,6 +49,11 @@ Input (wins over the identity's identity.json):
49
49
  to a point inside the target, keys are typed with human delays;
50
50
  full adds overshoot, reading pauses and wheel scrolling; adaptive is
51
51
  light, and full on a site that showed a challenge page
52
+ --cursor <auto|on|off> the agent cursor: a named arrow that glides to what the agent acts
53
+ on, a ring, click ripples and a frame with a badge while it works.
54
+ auto (default): when the browser can be seen (a window, or the live
55
+ view). It is an element in each page, which a page script can see:
56
+ off leaves pages as they are
52
57
 
53
58
  Engines (these flags win over the identity's identity.json; all off by default):
54
59
  --engine lightpanda read mode: Lightpanda instead of Chrome, for reading pages
@@ -11,6 +11,8 @@ import { vaultCommand } from "./vault.js";
11
11
  import { BACKGROUND_JSON, backgroundCommand } from "./background.js";
12
12
  import { secretCommand } from "./secret.js";
13
13
  import { SETUP_DETAILS, SETUP_JSON, setup } from "./setup.js";
14
+ import { INIT_DETAILS, INIT_SYNOPSIS, init } from "./init.js";
15
+ import { loginSummary } from "./login-summary.js";
14
16
  /**
15
17
  * The identity commands of turno-browser: `turno-browser <cmd>` on its own, `turno browser <cmd>`
16
18
  * inside turno-cli. Each command reads its names from the host, so help, hints and errors name
@@ -106,7 +108,7 @@ function identities(c, args, io) {
106
108
  }
107
109
  const width = Math.max(...list.map((i) => i.id.length));
108
110
  for (const i of list) {
109
- const state = i.inUse ? paint(io, "in use", "33") : paint(io, "free ", "32");
111
+ const state = i.inUse ? paint(io, "in use ", "33") : paint(io, "not in use", "32");
110
112
  io.out(`${i.id.padEnd(width)} ${state} ${tildify(i.dir, io.env)}`);
111
113
  }
112
114
  return 0;
@@ -161,8 +163,8 @@ async function login(c, args, io) {
161
163
  const options = { env: io.env };
162
164
  if (url)
163
165
  options.url = url;
164
- await mod.loginIdentity(id, options);
165
- io.out(`saved. Sessions using browser-${id} now start signed in.`);
166
+ const result = await mod.loginIdentity(id, options);
167
+ io.out(loginSummary(c, id, result?.sites ?? []));
166
168
  return 0;
167
169
  }
168
170
  /** The first argument that is not a flag, without parsing the flags. */
@@ -281,6 +283,13 @@ function subcommands(c) {
281
283
  // configs, `turno secret` stores secrets and `do` goes through mcpd, not a background server.
282
284
  const own = alone
283
285
  ? {
286
+ init: {
287
+ summary: "set up step by step: an identity, a sign-in by hand, and your agent (asks first)",
288
+ synopsis: INIT_SYNOPSIS,
289
+ details: INIT_DETAILS,
290
+ flags: ["--identity", "--agent", "--url", "--no-login", "--yes", "--dry-run"],
291
+ run: (args, io) => init(c, args, io, c.deps.run),
292
+ },
284
293
  setup: {
285
294
  summary: "print the MCP config that gives an agent an identity (Claude Code, Codex, Cursor...)",
286
295
  synopsis: "<claude-code|codex|cursor|copilot|gemini|json> [--identity <id>] [--json]",
@@ -5,6 +5,7 @@
5
5
  */
6
6
  import { SHELLS, completionScripts } from "turno-core/cli";
7
7
  import { listIdentities } from "../identities.js";
8
+ import { CURSOR_MODES } from "../settings.js";
8
9
  import { ACTION_NAMES } from "./do.js";
9
10
  import { SETUP_AGENTS } from "./setup.js";
10
11
  /** Commands whose first argument is an identity. */
@@ -36,6 +37,8 @@ const FLAG_VALUES = {
36
37
  "--engine": ["chrome", "lightpanda", "camoufox"],
37
38
  "--out": "file",
38
39
  "--color": ["auto", "always", "never"],
40
+ "--agent": [...SETUP_AGENTS, "none"],
41
+ "--cursor": CURSOR_MODES,
39
42
  };
40
43
  const GLOBAL_FLAGS = ["--help", "--version", "--no-input", "--color"];
41
44
  function identities(env) {
@@ -60,6 +60,8 @@ export interface CliDeps {
60
60
  input?: VaultInput;
61
61
  /** All of stdin, for `do <id> type <ref> -`. */
62
62
  stdin?: () => Promise<string>;
63
+ /** Runs an agent's `mcp add` command for `init` (default: spawn it on this terminal). */
64
+ run?: (command: string, args: readonly string[], io: Io) => Promise<number>;
63
65
  }
64
66
  /** Everything a command gets: the host and the dependencies. */
65
67
  export interface Ctx {
@@ -32,10 +32,14 @@ settings in identity.json (turno-browser show <id>), its sign-ins in its own pro
32
32
  credentials in the secret store (turno-browser vault).`,
33
33
  addSummary: "create an identity (pinned to this time zone) and print how an agent uses it",
34
34
  connect(id, _settings, io) {
35
- io.out("\nConnect an agent to it:");
36
- io.out(` ${setupLine(id)} # prints the config for Claude Code (codex, cursor, ...)`);
37
- io.out(` turno-browser-mcp --identity ${id} # the stdio command any MCP client runs`);
38
- io.out(`Sign in to your sites once with \`turno-browser login ${id}\`.`);
35
+ // No inline "# comment" on a command line: zsh does not take comments typed at its prompt,
36
+ // so a pasted line would pass the comment's words as arguments.
37
+ io.out("\nNext:");
38
+ io.out(` turno-browser login ${id}`);
39
+ io.out(" sign in to your sites by hand once; the cookies stay in the profile");
40
+ io.out(` ${setupLine(id)}`);
41
+ io.out(" prints how Claude Code gets this browser (also codex, cursor, copilot, gemini, json)");
42
+ io.out(`Any other MCP client runs: turno-browser-mcp --identity ${id}`);
39
43
  },
40
44
  restart: "a new agent session",
41
45
  doTransport: backgroundTransport(doDeps),
@@ -23,5 +23,7 @@ export interface BackgroundDoDeps {
23
23
  openBackgroundSession: typeof openBackgroundSession;
24
24
  }
25
25
  export declare const defaultBackgroundDoDeps: BackgroundDoDeps;
26
+ /** An idle limit in words: 15m, 1h, 90s. */
27
+ export declare function formatIdle(ms: number): string;
26
28
  /** The background transport of `turno-browser do`. */
27
29
  export declare function backgroundTransport(deps?: BackgroundDoDeps): DoTransport;
@@ -64,6 +64,14 @@ function sweepSaved(dir) {
64
64
  dropSaved(join(dir, f));
65
65
  }
66
66
  }
67
+ /** An idle limit in words: 15m, 1h, 90s. */
68
+ export function formatIdle(ms) {
69
+ if (ms % 3_600_000 === 0)
70
+ return `${ms / 3_600_000}h`;
71
+ if (ms % 60_000 === 0)
72
+ return `${ms / 60_000}m`;
73
+ return `${Math.round(ms / 1000)}s`;
74
+ }
67
75
  function message(err) {
68
76
  return (err?.message ?? String(err)).replace(/^(Error: )?/, "");
69
77
  }
@@ -132,6 +140,13 @@ export function backgroundTransport(deps = defaultBackgroundDoDeps) {
132
140
  dropSaved(file);
133
141
  return true;
134
142
  },
143
+ afterEnd() {
144
+ const server = api.backgroundStatus(id, { env });
145
+ if (!server)
146
+ return undefined;
147
+ const idle = server.idleMs > 0 ? `until it has been idle for ${formatIdle(server.idleMs)}` : "until you stop it";
148
+ return `Chrome stays open in the background server ${idle}; turno-browser background stop ${id} closes it now.`;
149
+ },
135
150
  session: (fn) => withLock(file, env, async () => {
136
151
  let saved = current();
137
152
  if (!saved)
package/dist/cli/do.d.ts CHANGED
@@ -56,6 +56,8 @@ export interface DoTarget {
56
56
  };
57
57
  /** `do <id> end`: end the saved session at once; false when there was none. */
58
58
  end(): Promise<boolean>;
59
+ /** After `end`: what still runs (the server and its Chrome) and how to close it now, when anything does. */
60
+ afterEnd?(): string | undefined;
59
61
  /** Open a session, or continue the saved one, run `fn` in it, and keep it for the next command. */
60
62
  session<T>(fn: (s: DoSession) => Promise<T>): Promise<T>;
61
63
  }
@@ -75,6 +77,8 @@ export interface DoTransport {
75
77
  /** The server that serves identity `id`, and this caller's session; throws when there is none. */
76
78
  target(id: string, p: Parsed, io: Io): Promise<DoTarget>;
77
79
  }
80
+ /** A next step for the errors a first `do` meets most: a ref from an old snapshot, or text where a ref goes. */
81
+ export declare function errorHint(error: string, browser: string, id: string): string | undefined;
78
82
  /** Every action name, for the short form and for completion. */
79
83
  export declare const ACTION_NAMES: readonly string[];
80
84
  /** The flags of `do`, for completion: the common ones, the transport's, then the actions'. */
package/dist/cli/do.js CHANGED
@@ -287,8 +287,17 @@ function errorText(parts, whole) {
287
287
  return raw
288
288
  .replace(ANSI, "")
289
289
  .replace(/^(Error: )?browserBackend\.callTool: (Error: )?/, "")
290
+ .replace(/^Error: /, "")
290
291
  .trim();
291
292
  }
293
+ /** A next step for the errors a first `do` meets most: a ref from an old snapshot, or text where a ref goes. */
294
+ export function errorHint(error, browser, id) {
295
+ if (/^Ref \S+ not found/.test(error))
296
+ return `refs change with the page: \`${browser} do ${id} snapshot\` prints the current ones`;
297
+ if (/does not match any elements/.test(error))
298
+ return `pass a ref from \`${browser} do ${id} snapshot\` (like e12), or find one by its text with \`${browser} do ${id} find "<text>"\``;
299
+ return undefined;
300
+ }
292
301
  /**
293
302
  * Notes worth a line: a pause by the user (the live view: how long, what changed while the
294
303
  * command waited), a dialog, new tabs and downloads, what the tab governor did.
@@ -512,8 +521,12 @@ export async function browserDo(c, args, io) {
512
521
  const { name } = t.info(null);
513
522
  if (json)
514
523
  emit(io, p, DO_JSON, { ...head, session: t.info(null), action, ...blank, result: ended ? "ended" : "none" });
515
- else
524
+ else {
516
525
  io.out(ended ? `ended session ${name} of ${head.identity}` : `no session ${name} of ${head.identity} to end`);
526
+ const note = t.afterEnd?.();
527
+ if (note)
528
+ io.out(note);
529
+ }
517
530
  return Exit.ok;
518
531
  }
519
532
  const cl = call;
@@ -552,6 +565,9 @@ export async function browserDo(c, args, io) {
552
565
  error: r.error,
553
566
  });
554
567
  printText(io, r, json, c.names.program);
568
+ const hint = !json && r.error ? errorHint(r.error, b, id) : undefined;
569
+ if (hint)
570
+ io.err(`hint: ${hint}`);
555
571
  return r.ok ? Exit.ok : Exit.failure;
556
572
  });
557
573
  }
package/dist/cli/flows.js CHANGED
@@ -135,6 +135,7 @@ export async function replay(c, args, io) {
135
135
  return fail(`usage: ${c.names.browser} replay <id> <flow> [--param name=value]... [--from <step>] [--headless]`);
136
136
  const flow = mod.readFlow(id, name, io.env);
137
137
  const params = {};
138
+ const prompted = [];
138
139
  for (const pair of p.values.param ?? []) {
139
140
  const eq = pair.indexOf("=");
140
141
  if (eq <= 0)
@@ -149,6 +150,7 @@ export async function replay(c, args, io) {
149
150
  if (!input.isTty() || noInputReason(io.env))
150
151
  needsAnswer(`browser replay (parameter ${param.name})`, `--param ${param.name}=keychain:<item>`);
151
152
  params[param.name] = await input.hidden(`${param.name} (input hidden): `);
153
+ prompted.push(param.name);
152
154
  }
153
155
  }
154
156
  const from = str(p, "from");
@@ -159,6 +161,7 @@ export async function replay(c, args, io) {
159
161
  return fail(holder);
160
162
  const result = await mod.replayFlow(id, name, {
161
163
  params,
164
+ ...(prompted.length ? { prompted } : {}),
162
165
  ...(from ? { from: Number(from) } : {}),
163
166
  headless: bool(p, "headless"),
164
167
  env: io.env,
@@ -24,6 +24,8 @@ export declare function settingsPatch(p: Parsed, current?: IdentitySettings): Se
24
24
  /** What an identity records, in a few words: "flows, traces (up to 200MB)". */
25
25
  export declare function describeRecord(r: RecordSettings | undefined): string | undefined;
26
26
  export declare function hasSettings(patch: SettingsPatch): boolean;
27
+ /** An ISO time as this machine's local time, to the minute: 2026-11-19 23:46. Anything else as it is. */
28
+ export declare function localTime(iso: string | undefined): string;
27
29
  export declare function show(c: Ctx, id: string, args: string[], io: Io): number;
28
30
  /** The arguments of `set` after the identity, for the usage line. */
29
31
  export declare const SET_SYNOPSIS: string;
@@ -4,7 +4,17 @@ import { dirname, join } from "node:path";
4
4
  import { Exit, JSON_FLAG, bool, emit, fail, jsonOutput, parseFlags, str, style, } from "turno-core/cli";
5
5
  import { tildify } from "turno-core/paths";
6
6
  /** `show --json` (`turno identity show browser:<id> --json` in turno). */
7
- export const SHOW_JSON = jsonOutput(["id", "dir", "settingsFile", "settings", "problems", "inUse", "holder", "health"]);
7
+ export const SHOW_JSON = jsonOutput([
8
+ "id",
9
+ "dir",
10
+ "settingsFile",
11
+ "settings",
12
+ "problems",
13
+ "inUse",
14
+ "holder",
15
+ "health",
16
+ "login",
17
+ ]);
8
18
  /** `set --json`: what changed, or would. */
9
19
  export const SET_JSON = jsonOutput(["id", "settingsFile", "dryRun", "changes", "settings"]);
10
20
  /** `doctor --json`: the shape of `turno doctor --json`. */
@@ -79,6 +89,8 @@ export const SETTINGS_FLAGS = {
79
89
  "proxy-username": { type: "string" },
80
90
  "proxy-password": { type: "string" },
81
91
  "no-proxy": { type: "boolean" },
92
+ // The agent cursor (format 12): auto, on or off.
93
+ cursor: { type: "string" },
82
94
  };
83
95
  /** The identity.json key behind each tuning flag, so the package's messages name the flag. */
84
96
  const KEY_FLAGS = [
@@ -94,6 +106,7 @@ const KEY_FLAGS = [
94
106
  ["cache.maxSize", "--cache-max-size"],
95
107
  ["humanize.level", "--humanize"],
96
108
  ["sharing", "--sharing"],
109
+ ["cursor", "--cursor"],
97
110
  ["tabLocks.wait", "--tab-lock-wait"],
98
111
  ["tabLocks.release", "--tab-lock-release"],
99
112
  ["engine", "--engine"],
@@ -302,6 +315,10 @@ function tuningPatch(p, value, patch, current) {
302
315
  const sharing = value("sharing");
303
316
  if (sharing !== undefined)
304
317
  patch.sharing = sharing;
318
+ // Checked by the package too: an unknown value comes back as `--cursor must be ...`.
319
+ const cursor = value("cursor");
320
+ if (cursor !== undefined)
321
+ patch.cursor = cursor;
305
322
  const locks = { wait: value("tab-lock-wait"), release: value("tab-lock-release") };
306
323
  if (locks.wait !== undefined || locks.release !== undefined)
307
324
  patch.tabLocks = mergeGroup(current?.tabLocks, locks);
@@ -451,6 +468,22 @@ const HUMANIZE_TEXT = {
451
468
  full: "human-like pointer, typing and scrolling (full)",
452
469
  adaptive: "light, full on sites that showed a challenge (adaptive)",
453
470
  };
471
+ /** An ISO time as this machine's local time, to the minute: 2026-11-19 23:46. Anything else as it is. */
472
+ export function localTime(iso) {
473
+ if (!iso)
474
+ return "";
475
+ const d = new Date(iso);
476
+ if (Number.isNaN(d.getTime()))
477
+ return iso;
478
+ const two = (n) => String(n).padStart(2, "0");
479
+ return `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())} ${two(d.getHours())}:${two(d.getMinutes())}`;
480
+ }
481
+ /** What each agent cursor mode does, for `show`. */
482
+ const CURSOR_TEXT = {
483
+ auto: "shown when the browser can be seen: a window, or the live view (auto)",
484
+ on: "always shown (on)",
485
+ off: "never shown: pages stay as they are (off)",
486
+ };
454
487
  export function show(c, id, args, io) {
455
488
  const m = c.api;
456
489
  const p = parseFlags(args, JSON_FLAG, 1);
@@ -459,6 +492,7 @@ export function show(c, id, args, io) {
459
492
  const { path, settings, problems } = m.checkIdentitySettings(id, io.env);
460
493
  const holder = m.inUseBy(id, io.env);
461
494
  const health = m.readHealth(id, io.env);
495
+ const login = m.readLoginRecord(id, io.env);
462
496
  if (bool(p, "json")) {
463
497
  emit(io, p, SHOW_JSON, {
464
498
  id: `browser:${id}`,
@@ -469,6 +503,7 @@ export function show(c, id, args, io) {
469
503
  inUse: holder !== undefined,
470
504
  holder: holder ?? null,
471
505
  health: health ?? null,
506
+ login: login ?? null,
472
507
  });
473
508
  return Exit.ok;
474
509
  }
@@ -490,7 +525,12 @@ export function show(c, id, args, io) {
490
525
  ]);
491
526
  if (settings.region)
492
527
  rows.push(["region", settings.region]);
493
- rows.push(["health check", settings.health ? describeHealth(settings.health) : s.muted("(none)")]);
528
+ rows.push([
529
+ "health check",
530
+ settings.health
531
+ ? describeHealth(settings.health)
532
+ : s.muted(`off (to turn on: ${c.names.browser} set ${id} --health-url <url> --health-text <text>)`),
533
+ ]);
494
534
  if (settings.tabs)
495
535
  rows.push(["tabs", `${describeTabs(settings.tabs)}${s.muted(" (the rest as default)")}`]);
496
536
  if (settings.backgroundThrottling !== undefined)
@@ -513,6 +553,7 @@ export function show(c, id, args, io) {
513
553
  ]);
514
554
  if (settings.sharing === "tabs")
515
555
  rows.push(["sharing", "every agent session at once, each in its own tabs"]);
556
+ rows.push(["agent cursor", CURSOR_TEXT[settings.cursor ?? "auto"] ?? String(settings.cursor)]);
516
557
  if (settings.tabLocks)
517
558
  rows.push([
518
559
  "tab locks",
@@ -546,8 +587,8 @@ export function show(c, id, args, io) {
546
587
  "live view",
547
588
  `on (${c.names.browser} live ${id}); a paused call waits up to ${settings.live.wait ?? "2m"}`,
548
589
  ]);
549
- rows.push(["created", settings.created]);
550
- rows.push(["updated", settings.updated]);
590
+ rows.push(["created", localTime(settings.created)]);
591
+ rows.push(["updated", localTime(settings.updated)]);
551
592
  }
552
593
  if (health) {
553
594
  const state = health.status === "ok"
@@ -555,11 +596,22 @@ export function show(c, id, args, io) {
555
596
  : health.status === "needs_auth"
556
597
  ? s.err("NEEDS_AUTH")
557
598
  : s.warn("check failed");
558
- rows.push(["last check", `${state} ${s.muted(`${health.checkedAt}${health.detail ? `: ${health.detail}` : ""}`)}`]);
599
+ rows.push([
600
+ "last check",
601
+ `${state} ${s.muted(`${localTime(health.checkedAt)}${health.detail ? `: ${health.detail}` : ""}`)}`,
602
+ ]);
559
603
  }
604
+ rows.push([
605
+ "last sign-in",
606
+ login
607
+ ? `${localTime(login.at)}${login.sites.length ? s.muted(` (${login.sites.join(", ")})`) : s.muted(" (no site opened)")}`
608
+ : m.profileHasCookies(id, io.env)
609
+ ? s.muted(`no record yet (the next ${c.names.identity("login", id)} keeps one)`)
610
+ : s.warn(`never by hand (${c.names.identity("login", id)})`),
611
+ ]);
560
612
  rows.push([
561
613
  "state",
562
- holder ? s.warn(holder.replace(/^browser identity "[^"]+" is /, "").replace(/\. .*$/, "")) : s.ok("free"),
614
+ holder ? s.warn(holder.replace(/^browser identity "[^"]+" is /, "").replace(/\. .*$/, "")) : s.ok("not in use"),
563
615
  ]);
564
616
  io.out(s.bold(`browser:${id}`));
565
617
  const width = Math.max(...rows.map(([k]) => k.length));
@@ -575,7 +627,7 @@ const SET_FLAGS = { ...SETTINGS_FLAGS, "dry-run": { type: "boolean" }, ...JSON_F
575
627
  /** The arguments of `set` after the identity, for the usage line. */
576
628
  export const SET_SYNOPSIS = "[--timezone <zone>] [--locale <tag>] [--languages <tag,...>] [--region <CC>] [--health-url <url>] [--health-text <text>] [--health-selector <css>] [--no-health] " +
577
629
  "[--tabs-max <n>] [--tabs-popups close|keep] [--tabs-park <duration>] [--tabs-close <duration>] [--no-tabs] [--background-throttling true|false] [--settle <duration>] " +
578
- "[--block-trackers true|false] [--block-types image,media,font] [--block-patterns <host|glob>,...] [--no-block] [--cache] [--cache-max-size <size>] [--no-cache] [--humanize off|light|full|adaptive] [--sharing session|tabs] [--tab-lock-wait <duration>] [--tab-lock-release <duration>] " +
630
+ "[--block-trackers true|false] [--block-types image,media,font] [--block-patterns <host|glob>,...] [--no-block] [--cache] [--cache-max-size <size>] [--no-cache] [--humanize off|light|full|adaptive] [--cursor auto|on|off] [--sharing session|tabs] [--tab-lock-wait <duration>] [--tab-lock-release <duration>] " +
579
631
  "[--engine chrome|lightpanda] [--attach auto|<dir>|<url>] [--record-flows true|false] [--record-traces true|false] [--record-screenshots true|false] [--record-max-size <size>] [--no-record] " +
580
632
  "[--act] [--act-sampling true|false] [--act-provider chat-completions] [--act-endpoint <url>] [--act-model <name>] [--act-key keychain:<item>] [--act-max-steps <n>] [--act-max-tokens <n>] [--act-timeout <duration>] [--no-act] " +
581
633
  "[--captcha-provider task-api] [--captcha-endpoint <url>] [--captcha-key keychain:<item>] [--captcha-timeout <duration>] [--no-captcha] [--live true|false] [--live-wait <duration>] [--no-live] " +
@@ -614,14 +666,18 @@ Input:
614
666
  inside the target, keys typed with human delays), full (plus
615
667
  overshoot, reading pauses, wheel scrolling) or adaptive
616
668
  (light, full on a site after a challenge page there)
669
+ --cursor auto|on|off the agent cursor: an arrow with the agent's name that glides to
670
+ what it acts on, a ring, click ripples, and a frame with a badge
671
+ while it works. auto (default): when the browser can be seen (a
672
+ window, or the live view). It is an element in each page that a
673
+ page script can see: off leaves pages exactly as they are
617
674
 
618
675
  Which engine runs this identity (all off by default):
619
676
  --engine lightpanda read mode: Lightpanda instead of Chrome, for reading pages;
620
677
  needs lightpanda on PATH (${b} doctor says how)
621
- --engine camoufox Camoufox (a Firefox build) with its own profile; not
622
- recommended for your own accounts; needs Camoufox and
623
- playwright-core (${b} doctor says how); no captcha
624
- solving, and no picture in the live view
678
+ --engine camoufox Camoufox (a Firefox build) with its own profile; needs
679
+ Camoufox and playwright-core (${b} doctor says how); no
680
+ captcha solving, and no picture in the live view
625
681
  --attach auto|<dir>|<url> use the Chrome you have open instead of the identity's own:
626
682
  "auto" is your default Chrome profile, after you turn on
627
683
  chrome://inspect/#remote-debugging; Chrome asks you to allow
@@ -0,0 +1,12 @@
1
+ import { type Io } from "turno-core/cli";
2
+ import type { Ctx } from "./context.js";
3
+ import { type SetupAgent } from "./setup.js";
4
+ export declare const INIT_SYNOPSIS = "[--identity <id>] [--agent <claude-code|codex|cursor|copilot|gemini|json|none>] [--url <url>] [--no-login] [--yes] [--dry-run]";
5
+ export declare const INIT_DETAILS = "Sets up a browser identity and gives it to your agent, asking at each step:\n 1. the identity's name (a new one is created; an existing one is used as it is)\n 2. signing in by hand: Chrome opens on the identity's profile (--url opens a first site)\n 3. the agent: the agents found on this machine; its mcp add command runs only if you say yes,\n and an agent without one (cursor, json) gets the block to paste\n\n--yes answers yes to every step, --no-login skips the sign-in, --agent none skips the agent.\nWithout a terminal (--no-input, a pipe or an agent session) it needs --identity and --agent,\nskips the sign-in and prints the agent's command instead of running it.";
6
+ /** Runs an agent's `mcp add` command; tests replace it. Resolves to the exit code. */
7
+ export type RunCommand = (command: string, args: readonly string[], io: Io) => Promise<number>;
8
+ /** The agents installed here, in the order the question lists them. */
9
+ export declare function detectAgents(env: NodeJS.ProcessEnv): SetupAgent[];
10
+ /** Split a printed shell line back into words: setup only quotes with single quotes. */
11
+ export declare function shellWords(line: string): string[];
12
+ export declare function init(c: Ctx, args: string[], io: Io, run?: RunCommand): Promise<number>;