turno-browser 0.5.0 → 0.7.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.
@@ -0,0 +1,408 @@
1
+ import { cursorOverlay } from "./agent-cursor-overlay.js";
2
+ import { HUMANIZED_TOOLS, overlay as override } from "./human-input.js";
3
+ /**
4
+ * Whether the agent cursor is drawn: never in read mode, always with `on`, and with `auto` (the
5
+ * default) when someone can see the browser: a Chrome window, or the live view.
6
+ */
7
+ export function resolveCursor(mode, ctx) {
8
+ if (ctx.engine === "lightpanda")
9
+ return false;
10
+ const m = mode ?? "auto";
11
+ if (m === "off")
12
+ return false;
13
+ if (m === "on")
14
+ return true;
15
+ return !ctx.headless || ctx.live;
16
+ }
17
+ /** One color per agent session, in order: turno's blue first. */
18
+ export const CURSOR_COLORS = ["#2b59ff", "#e8590c", "#2f9e44", "#ae3ec9", "#d6336c", "#0c8599"];
19
+ /** The longest glide to a target: long enough to follow, short enough to cost little. */
20
+ export const MAX_GLIDE_MS = 420;
21
+ /** How long the arrow takes from `from` to `to`: a short base plus the distance, capped. */
22
+ export function glideMs(from, to, max = MAX_GLIDE_MS) {
23
+ if (max <= 0)
24
+ return 0;
25
+ if (!from)
26
+ return Math.min(max, 220);
27
+ const d = Math.hypot(to.x - from.x, to.y - from.y);
28
+ if (d < 2)
29
+ return 0;
30
+ return Math.round(Math.min(max, 140 + d * 0.35));
31
+ }
32
+ /** The center of a box. */
33
+ export function centerOf(box) {
34
+ return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
35
+ }
36
+ /** True when some of the box is inside a viewport of this size. */
37
+ export function inView(box, view) {
38
+ return box.x + box.width > 0 && box.y + box.height > 0 && box.x < view.width && box.y < view.height;
39
+ }
40
+ /** The pill of a session's cursor: the client's name, and the identity when there is one. */
41
+ export function cursorLabel(client, identity) {
42
+ const name = client.trim() || "Agent";
43
+ return identity ? `${name} · ${identity}` : name;
44
+ }
45
+ const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
46
+ /** The agent cursor of one running browser: its actors and what each page shows. */
47
+ export class AgentCursor {
48
+ options;
49
+ actors = new Map();
50
+ /** The session acting on each page now (set when a call begins on it). */
51
+ owners = new WeakMap();
52
+ /** Where each session's arrow is on each page, so a new document puts it back. */
53
+ points = new WeakMap();
54
+ reports = new WeakMap();
55
+ sleep;
56
+ maxGlideMs;
57
+ lastKey = "";
58
+ paused = false;
59
+ constructor(options) {
60
+ this.options = options;
61
+ this.sleep = options.sleep ?? defaultSleep;
62
+ this.maxGlideMs = options.maxGlideMs ?? MAX_GLIDE_MS;
63
+ }
64
+ /** The actor of a session, with its label and color, made on first use. */
65
+ actor(key) {
66
+ let a = this.actors.get(key);
67
+ if (a)
68
+ return a;
69
+ const n = this.actors.size;
70
+ const client = n === 0 ? this.options.title : `${this.options.title} (${n + 1})`;
71
+ a = {
72
+ key,
73
+ name: client.trim() || "Agent",
74
+ label: cursorLabel(client, this.options.identity),
75
+ color: CURSOR_COLORS[n % CURSOR_COLORS.length],
76
+ };
77
+ this.actors.set(key, a);
78
+ return a;
79
+ }
80
+ /** The session acting on this page now, or the last one that acted anywhere. */
81
+ ownerOf(page) {
82
+ return this.owners.get(page) ?? this.lastKey;
83
+ }
84
+ /** Where the session's arrow is on this page, if it has been there. */
85
+ pointOf(page, key = this.ownerOf(page)) {
86
+ return this.points.get(page)?.get(key);
87
+ }
88
+ /** The viewport and motion preference the page last reported. */
89
+ reportOf(page) {
90
+ return this.reports.get(page);
91
+ }
92
+ /**
93
+ * Sends commands to the page's overlay, with the actor and the arrow's last place first, so a
94
+ * document the overlay has not been on yet shows the same thing. Never throws: a page that
95
+ * closed or navigated away just misses one frame.
96
+ */
97
+ async send(page, commands, key = this.ownerOf(page)) {
98
+ if (page.isClosed())
99
+ return undefined;
100
+ // The direct session's key is "" (`DIRECT_SESSION`): every key, that one too, is an actor.
101
+ const a = this.actor(key);
102
+ const prelude = [{ op: "actor", key, label: a.label, name: a.name, color: a.color }];
103
+ const at = this.pointOf(page, key);
104
+ if (at)
105
+ prelude.push({ op: "move", key, x: at.x, y: at.y, ms: 0 });
106
+ prelude.push({ op: "paused", on: this.paused });
107
+ try {
108
+ const report = await page.evaluate(cursorOverlay, [...prelude, ...commands]);
109
+ this.reports.set(page, report);
110
+ return report;
111
+ }
112
+ catch {
113
+ return undefined;
114
+ }
115
+ }
116
+ remember(page, key, point) {
117
+ let m = this.points.get(page);
118
+ if (!m) {
119
+ m = new Map();
120
+ this.points.set(page, m);
121
+ }
122
+ m.set(key, point);
123
+ }
124
+ /** A call of session `key` begins on this page: the frame and badge come on. */
125
+ async begin(page, key) {
126
+ if (!page)
127
+ return;
128
+ this.owners.set(page, key);
129
+ this.lastKey = key;
130
+ await this.send(page, [{ op: "busy", key, on: true }], key);
131
+ }
132
+ /** The call ended (on this page, which may be a new one): the frame fades after a moment. */
133
+ async end(page, key) {
134
+ if (!page)
135
+ return;
136
+ this.owners.set(page, key);
137
+ await this.send(page, [{ op: "busy", key, on: false }], key);
138
+ }
139
+ /** Glides the arrow to `to` and waits for it to arrive. */
140
+ async glideTo(page, to) {
141
+ const key = this.ownerOf(page);
142
+ const report = this.reports.get(page);
143
+ const ms = report?.reducedMotion ? 0 : glideMs(this.pointOf(page, key), to, this.maxGlideMs);
144
+ // Sent from the last place (the batch's prelude puts the arrow there), then remembered.
145
+ await this.send(page, [{ op: "move", key, x: to.x, y: to.y, ms }], key);
146
+ this.remember(page, key, to);
147
+ if (ms > 0)
148
+ await this.sleep(ms);
149
+ }
150
+ /** Moves the arrow along with a pointer path someone else plays (humanize): a short ease per step. */
151
+ async track(page, to) {
152
+ const key = this.ownerOf(page);
153
+ await this.send(page, [{ op: "move", key, x: to.x, y: to.y, ms: 40 }], key);
154
+ this.remember(page, key, to);
155
+ }
156
+ /** Puts the arrow at `to` without a glide. */
157
+ async place(page, to) {
158
+ const key = this.ownerOf(page);
159
+ await this.send(page, [{ op: "move", key, x: to.x, y: to.y, ms: 0 }], key);
160
+ this.remember(page, key, to);
161
+ }
162
+ async ring(page, box) {
163
+ const key = this.ownerOf(page);
164
+ await this.send(page, [{ op: "ring", key, box }], key);
165
+ }
166
+ async ripple(page, at) {
167
+ const key = this.ownerOf(page);
168
+ await this.send(page, [{ op: "ripple", key, x: at.x, y: at.y }], key);
169
+ }
170
+ async typing(page, box) {
171
+ const key = this.ownerOf(page);
172
+ await this.send(page, [{ op: "typing", key, box }], key);
173
+ }
174
+ /** The live view's pause: every page says the user has the controls. */
175
+ async setPaused(pages, on) {
176
+ this.paused = on;
177
+ await Promise.all(pages.map((page) => this.send(page, [])));
178
+ }
179
+ /** Runs `fn` with the page's overlay hidden: the model's screenshot shows the page alone. */
180
+ async hiddenDuring(page, fn) {
181
+ if (!page || !this.reports.has(page))
182
+ return await fn();
183
+ await this.send(page, [{ op: "visible", on: false }]);
184
+ try {
185
+ return await fn();
186
+ }
187
+ finally {
188
+ await this.send(page, [{ op: "visible", on: true }]);
189
+ }
190
+ }
191
+ }
192
+ /** How long the cursor waits for an element's box before it lets the action run without it. */
193
+ const BOX_TIMEOUT_MS = 500;
194
+ /** The locator methods the input tools call, and the mark each leaves. */
195
+ const LOCATOR_KINDS = {
196
+ click: "click",
197
+ dblclick: "click",
198
+ tap: "click",
199
+ check: "click",
200
+ uncheck: "click",
201
+ setChecked: "click",
202
+ selectOption: "click",
203
+ hover: "hover",
204
+ fill: "type",
205
+ pressSequentially: "type",
206
+ press: "type",
207
+ dragTo: "drag",
208
+ };
209
+ /**
210
+ * The input tools' view of a tab that moves the agent cursor: each locator action glides the
211
+ * arrow to its target first, and the coordinate tools' mouse does the same. With humanize on
212
+ * (`humanized`), the pointer path humanize plays goes through this view's mouse, so the arrow
213
+ * follows it step by step instead of gliding on its own.
214
+ */
215
+ export class CursorInput {
216
+ cursor;
217
+ humanized;
218
+ /** One view per page, so humanize, which keys its pointer state by page, sees the same one. */
219
+ views = new WeakMap();
220
+ /** The last element marked on each page: where keys typed through the keyboard go. */
221
+ marked = new WeakMap();
222
+ typingTimers = new WeakMap();
223
+ constructor(cursor, humanized) {
224
+ this.cursor = cursor;
225
+ this.humanized = humanized;
226
+ }
227
+ async boxOf(locator, timeout = BOX_TIMEOUT_MS) {
228
+ try {
229
+ const box = await locator.boundingBox({ timeout });
230
+ return box && box.width > 0 && box.height > 0 ? box : null;
231
+ }
232
+ catch {
233
+ return null;
234
+ }
235
+ }
236
+ /** Marks the target of an action, runs it, and leaves the mark of its kind. */
237
+ async act(page, locator, kind, run, to) {
238
+ const c = this.cursor;
239
+ let box = await this.boxOf(locator);
240
+ const view = c.reportOf(page) ?? (await c.send(page, []));
241
+ if (box && view && !inView(box, view))
242
+ box = null; // Playwright scrolls it in: mark it after
243
+ if (box) {
244
+ this.marked.set(page, box);
245
+ void c.ring(page, box);
246
+ if (!this.humanized)
247
+ await c.glideTo(page, centerOf(box));
248
+ if (kind === "type")
249
+ void c.typing(page, box);
250
+ if (kind === "click" && !this.humanized)
251
+ void c.ripple(page, centerOf(box));
252
+ }
253
+ try {
254
+ const result = await run();
255
+ if (kind === "drag" && to) {
256
+ const end = await this.boxOf(to, 200);
257
+ if (end) {
258
+ void c.ring(page, end);
259
+ await c.place(page, centerOf(end));
260
+ }
261
+ }
262
+ else if (!box || (kind === "click" && this.humanized)) {
263
+ // Marked after: the element came into view during the action, or humanize moved there.
264
+ const after = box ?? (await this.boxOf(locator, 200));
265
+ const center = after ? centerOf(after) : undefined;
266
+ const at = this.humanized ? (c.pointOf(page) ?? center) : center;
267
+ if (after && !box) {
268
+ this.marked.set(page, after);
269
+ void c.ring(page, after);
270
+ }
271
+ if (at) {
272
+ if (!this.humanized)
273
+ await c.place(page, at);
274
+ if (kind === "click")
275
+ void c.ripple(page, at);
276
+ }
277
+ }
278
+ return result;
279
+ }
280
+ finally {
281
+ if (kind === "type")
282
+ void c.typing(page, null);
283
+ }
284
+ }
285
+ /** The cursor view of one of the page's locators. */
286
+ wrapLocator(locator, page) {
287
+ const original = locator;
288
+ const overrides = {};
289
+ for (const [method, kind] of Object.entries(LOCATOR_KINDS)) {
290
+ overrides[method] = (...args) => {
291
+ const to = method === "dragTo" ? args[0] : undefined;
292
+ return this.act(page, locator, kind, () => original[method].apply(locator, args), to);
293
+ };
294
+ }
295
+ return override(locator, overrides);
296
+ }
297
+ /** The cursor view of the page's mouse (the coordinate tools, and humanize's pointer path). */
298
+ wrapMouse(page) {
299
+ const mouse = page.mouse;
300
+ const c = this.cursor;
301
+ return override(mouse, {
302
+ move: async (x, y, options) => {
303
+ if (this.humanized)
304
+ void c.track(page, { x, y });
305
+ else
306
+ await c.glideTo(page, { x, y });
307
+ await mouse.move(x, y, options);
308
+ },
309
+ click: async (x, y, options) => {
310
+ if (!this.humanized)
311
+ await c.glideTo(page, { x, y });
312
+ void c.ripple(page, { x, y });
313
+ await mouse.click(x, y, options);
314
+ },
315
+ dblclick: async (x, y, options) => {
316
+ if (!this.humanized)
317
+ await c.glideTo(page, { x, y });
318
+ void c.ripple(page, { x, y });
319
+ await mouse.dblclick(x, y, options);
320
+ },
321
+ down: async (options) => {
322
+ const at = c.pointOf(page);
323
+ if (at)
324
+ void c.ripple(page, at);
325
+ await mouse.down(options);
326
+ },
327
+ });
328
+ }
329
+ /** Keys typed through the keyboard (humanize's typing, browser_press_key): a typing bubble a moment. */
330
+ keys(page) {
331
+ const box = this.marked.get(page);
332
+ if (!box)
333
+ return;
334
+ const old = this.typingTimers.get(page);
335
+ if (old)
336
+ clearTimeout(old);
337
+ else
338
+ void this.cursor.typing(page, box);
339
+ const timer = setTimeout(() => {
340
+ this.typingTimers.delete(page);
341
+ void this.cursor.typing(page, null);
342
+ }, 900);
343
+ timer.unref?.();
344
+ this.typingTimers.set(page, timer);
345
+ }
346
+ /** The cursor view of the page's keyboard. */
347
+ wrapKeyboard(page) {
348
+ const keyboard = page.keyboard;
349
+ return override(keyboard, {
350
+ press: async (key, options) => {
351
+ this.keys(page);
352
+ await keyboard.press(key, options);
353
+ },
354
+ type: async (text, options) => {
355
+ this.keys(page);
356
+ await keyboard.type(text, options);
357
+ },
358
+ insertText: async (text) => {
359
+ this.keys(page);
360
+ await keyboard.insertText(text);
361
+ },
362
+ });
363
+ }
364
+ /** The cursor view of the page itself: the same object for every call on that page. */
365
+ viewOf(page) {
366
+ let v = this.views.get(page);
367
+ if (!v) {
368
+ v = override(page, { mouse: this.wrapMouse(page), keyboard: this.wrapKeyboard(page) });
369
+ this.views.set(page, v);
370
+ }
371
+ return v;
372
+ }
373
+ /** A view of one of upstream's tabs whose locators and mouse move the agent cursor. */
374
+ wrapTab(tab) {
375
+ const page = tab.page;
376
+ const t = tab;
377
+ return override(tab, {
378
+ page: this.viewOf(page),
379
+ targetLocator: async (params) => {
380
+ const r = await t.targetLocator(params);
381
+ return { ...r, locator: this.wrapLocator(r.locator, page) };
382
+ },
383
+ targetLocators: async (params) => (await t.targetLocators(params)).map((r) => ({ ...r, locator: this.wrapLocator(r.locator, page) })),
384
+ });
385
+ }
386
+ /** A view of upstream's per-session `Context` whose `ensureTab` hands out cursor tabs. */
387
+ wrapContext(context) {
388
+ const c = context;
389
+ return override(context, {
390
+ ensureTab: async (...args) => this.wrapTab(await c.ensureTab(...args)),
391
+ });
392
+ }
393
+ }
394
+ /**
395
+ * The stock tools of one browser, with the input tools running on cursor tabs. It goes under
396
+ * `humanizeTools` (applied to its result), so humanize's pointer path runs through the cursor's
397
+ * mouse. Schemas and every other tool are upstream's own objects.
398
+ */
399
+ export function cursorTools(tools, input) {
400
+ return tools.map((tool) => {
401
+ if (!HUMANIZED_TOOLS.has(tool.schema.name))
402
+ return tool;
403
+ const handled = tool;
404
+ const handle = (context, params, response, signal) => handled.handle(input.wrapContext(context), params, response, signal);
405
+ return { ...tool, handle };
406
+ });
407
+ }
408
+ //# sourceMappingURL=agent-cursor.js.map
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]",
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Shell completion for the turno-browser program: `turno-browser completion <shell>` prints the
3
+ * script, and the script calls `turno-browser __complete -- <words...>` for candidates. It only
4
+ * reads identity folders: completing never starts Chrome or reads the secret store.
5
+ */
6
+ import { type Sub } from "turno-core/cli";
7
+ /** Candidates for the last word, given the words before it (both after `turno-browser`). */
8
+ export declare function complete(words: readonly string[], subs: Record<string, Sub>, env: NodeJS.ProcessEnv): string[];
9
+ /** `turno-browser completion <shell>`: the script, or undefined for an unknown shell. */
10
+ export declare function completionScript(program: string, shell: string | undefined): string | undefined;
11
+ export declare const COMPLETION_USAGE: (program: string) => string;