turno-browser 0.4.0 → 0.6.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 (72) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +92 -149
  3. package/dist/act-model.js +4 -3
  4. package/dist/act.js +2 -1
  5. package/dist/api.d.ts +63 -2
  6. package/dist/api.js +14 -4
  7. package/dist/background-state.d.ts +54 -0
  8. package/dist/background-state.js +97 -0
  9. package/dist/background.d.ts +69 -0
  10. package/dist/background.js +458 -0
  11. package/dist/bin/mcp.js +48 -8
  12. package/dist/captcha.js +3 -2
  13. package/dist/cli/background.d.ts +11 -0
  14. package/dist/cli/background.js +132 -0
  15. package/dist/cli/commands.d.ts +16 -0
  16. package/dist/cli/commands.js +515 -0
  17. package/dist/cli/completion.d.ts +11 -0
  18. package/dist/cli/completion.js +107 -0
  19. package/dist/cli/context.d.ts +75 -0
  20. package/dist/cli/context.js +44 -0
  21. package/dist/cli/do-background.d.ts +27 -0
  22. package/dist/cli/do-background.js +212 -0
  23. package/dist/cli/do.d.ts +85 -0
  24. package/dist/cli/do.js +558 -0
  25. package/dist/cli/flows.d.ts +28 -0
  26. package/dist/cli/flows.js +303 -0
  27. package/dist/cli/identity.d.ts +37 -0
  28. package/dist/cli/identity.js +906 -0
  29. package/dist/cli/live.d.ts +7 -0
  30. package/dist/cli/live.js +99 -0
  31. package/dist/cli/main.d.ts +16 -0
  32. package/dist/cli/main.js +194 -0
  33. package/dist/cli/secret.d.ts +4 -0
  34. package/dist/cli/secret.js +151 -0
  35. package/dist/cli/session.d.ts +6 -0
  36. package/dist/cli/session.js +106 -0
  37. package/dist/cli/setup.d.ts +13 -0
  38. package/dist/cli/setup.js +180 -0
  39. package/dist/cli/vault.d.ts +5 -0
  40. package/dist/cli/vault.js +192 -0
  41. package/dist/client.d.ts +82 -0
  42. package/dist/client.js +303 -0
  43. package/dist/doctor.js +34 -1
  44. package/dist/engine-camoufox.js +5 -4
  45. package/dist/engine-lightpanda.js +3 -2
  46. package/dist/engine.js +2 -1
  47. package/dist/health.js +2 -1
  48. package/dist/host.d.ts +21 -0
  49. package/dist/host.js +75 -15
  50. package/dist/human-input.js +7 -2
  51. package/dist/identities.js +2 -1
  52. package/dist/index.d.ts +5 -1
  53. package/dist/index.js +2 -0
  54. package/dist/lifecycle.d.ts +2 -0
  55. package/dist/lifecycle.js +2 -1
  56. package/dist/live-client.js +8 -6
  57. package/dist/live-page.d.ts +0 -7
  58. package/dist/live-page.js +3 -2
  59. package/dist/live-server.js +6 -3
  60. package/dist/live.js +2 -1
  61. package/dist/login-tool.js +3 -2
  62. package/dist/login.js +2 -1
  63. package/dist/names.d.ts +28 -0
  64. package/dist/names.js +25 -0
  65. package/dist/network.d.ts +1 -1
  66. package/dist/network.js +4 -3
  67. package/dist/opt-in-settings.js +3 -2
  68. package/dist/replay.js +4 -3
  69. package/dist/runtime-lock.js +3 -2
  70. package/dist/vault.js +5 -4
  71. package/npm-shrinkwrap.json +6 -5
  72. package/package.json +13 -7
package/dist/bin/mcp.js CHANGED
@@ -2,6 +2,7 @@
2
2
  import { mkdirSync, rmSync, writeFileSync } from "node:fs";
3
3
  import { dirname } from "node:path";
4
4
  import { buildArgv } from "../argv.js";
5
+ import { extractBackground, serveBackground, sharingOf } from "../background.js";
5
6
  import { engineChoice } from "../engine.js";
6
7
  import { lightpandaCookieJar, sweepOrphanLightpandas } from "../engine-lightpanda.js";
7
8
  import { runHost } from "../host.js";
@@ -15,10 +16,11 @@ import { readIdentitySettings } from "../settings.js";
15
16
  * Chrome an earlier run left behind on the same profile, and a deadline on shutdown. With
16
17
  * `--identity`, the identity module: identity.json applied at launch,
17
18
  * a runtime lock while Chrome runs, the session health check and the reputation log.
18
- * Speaks MCP over stdio; `--port` with `--identity` needs `--allow-http-identity`.
19
+ * Speaks MCP over stdio; `--port` with `--identity` needs `--allow-http-identity`; `--background`
20
+ * serves the identity to the shell from a private socket (`background.ts`).
19
21
  */
20
22
  const HELP = `turno-browser-mcp: a browser MCP server that drives your installed Chrome, with one
21
- persistent profile per identity (turno identity add browser:<id>).
23
+ persistent profile per identity (turno-browser add <id>).
22
24
 
23
25
  --identity <id> use the identity's saved profile (served one session at a time by
24
26
  mcpd, unless the identity's "sharing" is "tabs")
@@ -53,8 +55,8 @@ Engines (these flags win over the identity's identity.json; all off by default):
53
55
  (navigate, snapshot, find, click a link, evaluate); other tools are
54
56
  refused. Needs lightpanda on PATH or TURNO_LIGHTPANDA_PATH
55
57
  --engine camoufox Camoufox (a Firefox build) instead of Chrome, with its own profile;
56
- not recommended for your own accounts. Needs Camoufox and
57
- playwright-core (turno browser doctor says how); never downloaded
58
+ off by default. Needs Camoufox and
59
+ playwright-core (turno-browser doctor says how); never downloaded
58
60
  --engine chrome the default; turns off an identity's read, Camoufox or attach mode
59
61
  --attach <target> connect to a Chrome you already have open instead of launching
60
62
  one: "auto" (your default Chrome profile, after you turn on remote
@@ -63,11 +65,26 @@ Engines (these flags win over the identity's identity.json; all off by default):
63
65
  that profile; turno closes only the tabs it opened
64
66
 
65
67
  Live view (wins over the identity's identity.json; off by default):
66
- --live serve a view of the agent's tab on 127.0.0.1 (turno browser live
68
+ --live serve a view of the agent's tab on 127.0.0.1 (turno-browser live
67
69
  <id> opens it) and let you pause the agent to take the controls
68
70
  --live-wait <duration> how long a call waits while you have the agent paused (default 2m,
69
71
  "5s" to "30m"); then it fails and tells the agent you still have it
70
72
 
73
+ Background server (for shell use without turno; turno-browser do starts it):
74
+ --background serve the identity over MCP streamable HTTP on a Unix socket in a
75
+ folder only you can enter (<state>/browser/identities/<id>/background),
76
+ or on 127.0.0.1 with a per-server token in a file only you can read
77
+ where a socket cannot be used. Writes server.json there while it runs.
78
+ Needs --identity; --port and --host do not apply
79
+ --background-idle <duration>
80
+ exit after this long without a request (default 15m; "0" never);
81
+ also TURNO_BROWSER_BACKGROUND_IDLE. Chrome closes first
82
+ While the background server of an identity runs, it alone drives the identity's browser: a
83
+ stdio server of that identity (an agent's, or mcpd's) answers each call that needs the browser
84
+ with an error that names the background server, and the background server does not start while
85
+ another process has the identity's Chrome open. Stop it with turno-browser background stop <id>
86
+ (or kill <pid>); turno-browser background shows which run.
87
+
71
88
  Examples:
72
89
  turno-browser-mcp --identity work
73
90
  turno-browser-mcp --identity work --max-tabs 4 --park-after 2m
@@ -76,6 +93,7 @@ Examples:
76
93
  turno-browser-mcp --engine lightpanda
77
94
  turno-browser-mcp --attach auto
78
95
  turno-browser-mcp --identity work --live
96
+ turno-browser-mcp --identity work --background --background-idle 30m
79
97
 
80
98
  Every other flag is a Playwright MCP flag:
81
99
  `;
@@ -83,8 +101,12 @@ const help = process.argv.includes("--help") || process.argv.includes("-h");
83
101
  if (help)
84
102
  process.stdout.write(`${HELP}\n`);
85
103
  let built;
104
+ let background;
86
105
  try {
87
- built = buildArgv(process.argv.slice(2));
106
+ background = extractBackground(process.argv.slice(2));
107
+ built = buildArgv(background.rest);
108
+ if (background.background && built.identity === undefined)
109
+ throw new Error("--background needs --identity <id>: it serves one identity's browser");
88
110
  }
89
111
  catch (err) {
90
112
  process.stderr.write(`turno-browser-mcp: ${err.message}\n`);
@@ -108,7 +130,7 @@ if (built.userDataDir && !help) {
108
130
  else if (swept.action === "survived") {
109
131
  process.stderr.write(`turno-browser-mcp: a Chrome an earlier run left open on this profile (pid ${swept.pid}) did not stop\n`);
110
132
  }
111
- installShutdownGuard(built.userDataDir);
133
+ installShutdownGuard(built.userDataDir, { stdin: !background.background });
112
134
  }
113
135
  if (!help && readMode(built)) {
114
136
  const jar = built.identity !== undefined ? lightpandaCookieJar(built.identity, process.env) : undefined;
@@ -128,10 +150,28 @@ function readMode(argv) {
128
150
  return false; // the launch reports a bad identity.json or flag
129
151
  }
130
152
  }
153
+ const identity = built.identity !== undefined ? { id: built.identity, env: process.env } : undefined;
131
154
  await runHost(built.args, {
132
- ...(built.identity !== undefined ? { identity: { id: built.identity, env: process.env } } : {}),
155
+ ...(identity ? { identity } : {}),
133
156
  ...(built.tuning ? { tuning: built.tuning } : {}),
134
157
  ...(built.engineFlags ? { engineFlags: built.engineFlags } : {}),
135
158
  ...(built.live ? { live: built.live } : {}),
159
+ ...(background.background && identity
160
+ ? {
161
+ serve: async (host) => {
162
+ try {
163
+ await serveBackground(host, {
164
+ identity,
165
+ idleMs: background.idleMs,
166
+ sharing: sharingOf(built.tuning?.sharing, () => readIdentitySettings(identity.id, identity.env)?.sharing),
167
+ });
168
+ }
169
+ catch (err) {
170
+ process.stderr.write(`turno-browser-mcp: ${err.message}\n`);
171
+ process.exit(1);
172
+ }
173
+ },
174
+ }
175
+ : {}),
136
176
  });
137
177
  //# sourceMappingURL=mcp.js.map
package/dist/captcha.js CHANGED
@@ -3,6 +3,7 @@ import { captchaTimeoutMs } from "./opt-in-settings.js";
3
3
  import { recordSolve } from "./reputation.js";
4
4
  import { readIdentitySettings } from "./settings.js";
5
5
  import { upstream } from "./upstream.js";
6
+ import { names } from "./names.js";
6
7
  /**
7
8
  * Captcha solving, off by default (identity.json `captcha`). `browser_solve_captcha` finds a
8
9
  * captcha widget on the current tab, sends its kind, site key and the page URL to the solver
@@ -207,7 +208,7 @@ async function resolveSolver(ctx, settings) {
207
208
  throw new SolverError(`captcha.key names ${settings.key}, but this machine has no secret store`);
208
209
  const key = await store.get(item).catch(() => undefined);
209
210
  if (key === undefined)
210
- throw new SolverError(`the secret store has no item "${item}" for captcha.key (store it with: turno secret set ${item})`);
211
+ throw new SolverError(`the secret store has no item "${item}" for captcha.key (store it with: ${names().secretSet(item)})`);
211
212
  vault.redactor.add(key, "captcha solver key");
212
213
  return taskApiSolver({
213
214
  endpoint: settings.endpoint,
@@ -254,7 +255,7 @@ export function solveCaptchaTool() {
254
255
  return fail(error.message);
255
256
  }
256
257
  if (!settings)
257
- return fail(`captcha solving is off for identity "${identity.id}"; only the person can turn it on (turno identity set browser:${identity.id} --captcha-provider task-api --captcha-endpoint <url> --captcha-key keychain:<item>). Otherwise ask them to answer it in the browser window.`);
258
+ return fail(`captcha solving is off for identity "${identity.id}"; only the person can turn it on (${names().identity("set", identity.id)} --captcha-provider task-api --captcha-endpoint <url> --captcha-key keychain:<item>). Otherwise ask them to answer it in the browser window.`);
258
259
  if (!page)
259
260
  return fail("there is no page open: navigate to the page with the captcha first");
260
261
  let url;
@@ -0,0 +1,11 @@
1
+ import { type Command } from "turno-core/cli";
2
+ import type { Ctx } from "./context.js";
3
+ /**
4
+ * `turno-browser background`: the background server of each identity, the turno-browser-mcp
5
+ * that `turno-browser do` starts to reach the identity's browser from the shell. `status` shows
6
+ * which run, `start` starts one ahead, `stop` stops one (it closes its Chrome first).
7
+ */
8
+ /** `background status --json`: one element per running server. */
9
+ export declare const BACKGROUND_JSON: import("turno-core/cli").JsonOutput;
10
+ /** The `background` group. */
11
+ export declare function backgroundCommand(c: Ctx): Command;
@@ -0,0 +1,132 @@
1
+ import { JSON_FLAG, bool, emit, fail, group, jsonOutput, parseFlags, str, } from "turno-core/cli";
2
+ /**
3
+ * `turno-browser background`: the background server of each identity, the turno-browser-mcp
4
+ * that `turno-browser do` starts to reach the identity's browser from the shell. `status` shows
5
+ * which run, `start` starts one ahead, `stop` stops one (it closes its Chrome first).
6
+ */
7
+ /** `background status --json`: one element per running server. */
8
+ export const BACKGROUND_JSON = jsonOutput(["identity", "pid", "startedAt", "idleMs", "transport", "version"]);
9
+ function duration(ms) {
10
+ if (ms <= 0)
11
+ return "never";
12
+ if (ms % 3_600_000 === 0)
13
+ return `${ms / 3_600_000}h`;
14
+ if (ms % 60_000 === 0)
15
+ return `${ms / 60_000}m`;
16
+ return `${Math.round(ms / 1000)}s`;
17
+ }
18
+ function row(s) {
19
+ return {
20
+ identity: s.identity,
21
+ pid: s.pid,
22
+ startedAt: s.startedAt,
23
+ idleMs: s.idleMs,
24
+ transport: s.transport ?? null,
25
+ version: s.version,
26
+ };
27
+ }
28
+ function checkId(c, id, sub) {
29
+ if (!id)
30
+ return fail(`background ${sub} needs an identity id (for example: ${c.names.browser} background ${sub} school)`);
31
+ try {
32
+ c.api.assertIdentityId(id);
33
+ }
34
+ catch (err) {
35
+ return fail(err.message);
36
+ }
37
+ return id;
38
+ }
39
+ function status(c, args, io) {
40
+ const p = parseFlags(args, JSON_FLAG, 1);
41
+ const given = p.positionals[0];
42
+ const ids = given ? [checkId(c, given, "status")] : c.api.listIdentities(io.env).map((i) => i.id);
43
+ const running = ids.flatMap((id) => {
44
+ const s = c.api.backgroundStatus(id, { env: io.env });
45
+ return s ? [s] : [];
46
+ });
47
+ if (bool(p, "json")) {
48
+ emit(io, p, BACKGROUND_JSON, running.map(row));
49
+ return 0;
50
+ }
51
+ if (!running.length) {
52
+ io.out(given
53
+ ? `No background server of "${given}" runs. ${c.names.browser} do ${given} <action> starts one.`
54
+ : `No background server runs. ${c.names.browser} do <id> <action> starts one.`);
55
+ return 0;
56
+ }
57
+ const width = Math.max(...running.map((s) => s.identity.length));
58
+ for (const s of running)
59
+ io.out(`${s.identity.padEnd(width)} pid ${s.pid} since ${s.startedAt} idle exit ${duration(s.idleMs)} ${s.transport ?? "starting"}`);
60
+ return 0;
61
+ }
62
+ const START_FLAGS = { idle: { type: "string" }, headless: { type: "boolean" } };
63
+ async function start(c, args, io) {
64
+ const p = parseFlags(args, START_FLAGS, 1);
65
+ const id = checkId(c, p.positionals[0], "start");
66
+ if (!c.api.identityExists(id, io.env))
67
+ return fail(`identity "${id}" does not exist (${c.names.browser} add ${id})`);
68
+ const idle = str(p, "idle");
69
+ const extra = [
70
+ ...(idle !== undefined ? ["--background-idle", idle] : []),
71
+ ...(bool(p, "headless") ? ["--headless"] : []),
72
+ ];
73
+ let started;
74
+ try {
75
+ started = await c.api.startBackground(id, { env: io.env, args: extra });
76
+ }
77
+ catch (err) {
78
+ return fail(err.message);
79
+ }
80
+ const { state } = started;
81
+ io.out(started.started
82
+ ? `started the background server of "${id}" (pid ${state.pid}); it exits after ${duration(state.idleMs)} without a request`
83
+ : `the background server of "${id}" already runs (pid ${state.pid}, since ${state.startedAt})`);
84
+ return 0;
85
+ }
86
+ async function stop(c, args, io) {
87
+ const p = parseFlags(args, {}, 1);
88
+ const id = checkId(c, p.positionals[0], "stop");
89
+ const pid = c.api.backgroundStatus(id, { env: io.env })?.pid;
90
+ if (!(await c.api.stopBackground(id, { env: io.env }))) {
91
+ io.out(`no background server of "${id}" runs`);
92
+ return 0;
93
+ }
94
+ io.out(`stopped the background server of "${id}"${pid ? ` (pid ${pid})` : ""} and its Chrome`);
95
+ return 0;
96
+ }
97
+ const BACKGROUND_FOOTER = `The background server of an identity is the turno-browser-mcp that \`do\` starts to reach the
98
+ identity's browser from the shell, on a socket in a folder only you can enter. While it runs it
99
+ alone drives the identity's browser: an agent's server for the same identity answers with an
100
+ error that names it. It exits after 15 minutes without a request (start --idle, or
101
+ TURNO_BROWSER_BACKGROUND_IDLE), and stop closes its Chrome first.`;
102
+ /** The `background` group. */
103
+ export function backgroundCommand(c) {
104
+ const b = c.names.browser;
105
+ const subs = {
106
+ status: {
107
+ summary: "which identities have a background server running",
108
+ synopsis: "[<id>] [--json]",
109
+ flags: ["--json"],
110
+ json: BACKGROUND_JSON,
111
+ run: async (args, io) => status(c, args, io),
112
+ },
113
+ start: {
114
+ summary: "start an identity's background server ahead of the first do",
115
+ synopsis: "<id> [--idle <duration>] [--headless]",
116
+ flags: ["--idle", "--headless"],
117
+ run: (args, io) => start(c, args, io),
118
+ },
119
+ stop: {
120
+ summary: "stop an identity's background server and its Chrome",
121
+ synopsis: "<id>",
122
+ run: (args, io) => stop(c, args, io),
123
+ },
124
+ };
125
+ return group(`${c.names.subject}background`, "the background server do uses", subs, {
126
+ fallback: "status",
127
+ footer: BACKGROUND_FOOTER,
128
+ prefix: `${b} background`,
129
+ examples: [`${b} background status`, `${b} background start school --idle 30m`, `${b} background stop school`],
130
+ });
131
+ }
132
+ //# sourceMappingURL=background.js.map
@@ -0,0 +1,16 @@
1
+ import { type Command, type Io, type Sub } from "turno-core/cli";
2
+ import { type BrowserCliHost, type CliDeps } from "./context.js";
3
+ /** The identity commands for one host. */
4
+ export interface BrowserCli {
5
+ /** Every subcommand as one group, typed as `names.browser <sub>`. */
6
+ command: Command;
7
+ /** Each subcommand on its own, for a host that lists some of them under another command. */
8
+ subs: Record<string, Sub>;
9
+ /** Run one subcommand (`add`, `show`...) with its arguments. */
10
+ run(sub: string, args: string[], io: Io): Promise<number>;
11
+ }
12
+ /**
13
+ * The identity commands, named and wired by `host`. turno-cli calls it through the typed api
14
+ * (`api.cli`) with its own host; the `turno-browser` program with `standaloneHost()`.
15
+ */
16
+ export declare function browserCli(host: BrowserCliHost, deps: CliDeps): BrowserCli;