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.
- package/CHANGELOG.md +45 -0
- package/README.md +92 -149
- package/dist/act-model.js +4 -3
- package/dist/act.js +2 -1
- package/dist/api.d.ts +63 -2
- package/dist/api.js +14 -4
- package/dist/background-state.d.ts +54 -0
- package/dist/background-state.js +97 -0
- package/dist/background.d.ts +69 -0
- package/dist/background.js +458 -0
- package/dist/bin/mcp.js +48 -8
- package/dist/captcha.js +3 -2
- package/dist/cli/background.d.ts +11 -0
- package/dist/cli/background.js +132 -0
- package/dist/cli/commands.d.ts +16 -0
- package/dist/cli/commands.js +515 -0
- package/dist/cli/completion.d.ts +11 -0
- package/dist/cli/completion.js +107 -0
- package/dist/cli/context.d.ts +75 -0
- package/dist/cli/context.js +44 -0
- package/dist/cli/do-background.d.ts +27 -0
- package/dist/cli/do-background.js +212 -0
- package/dist/cli/do.d.ts +85 -0
- package/dist/cli/do.js +558 -0
- package/dist/cli/flows.d.ts +28 -0
- package/dist/cli/flows.js +303 -0
- package/dist/cli/identity.d.ts +37 -0
- package/dist/cli/identity.js +906 -0
- package/dist/cli/live.d.ts +7 -0
- package/dist/cli/live.js +99 -0
- package/dist/cli/main.d.ts +16 -0
- package/dist/cli/main.js +194 -0
- package/dist/cli/secret.d.ts +4 -0
- package/dist/cli/secret.js +151 -0
- package/dist/cli/session.d.ts +6 -0
- package/dist/cli/session.js +106 -0
- package/dist/cli/setup.d.ts +13 -0
- package/dist/cli/setup.js +180 -0
- package/dist/cli/vault.d.ts +5 -0
- package/dist/cli/vault.js +192 -0
- package/dist/client.d.ts +82 -0
- package/dist/client.js +303 -0
- package/dist/doctor.js +34 -1
- package/dist/engine-camoufox.js +5 -4
- package/dist/engine-lightpanda.js +3 -2
- package/dist/engine.js +2 -1
- package/dist/health.js +2 -1
- package/dist/host.d.ts +21 -0
- package/dist/host.js +75 -15
- package/dist/human-input.js +7 -2
- package/dist/identities.js +2 -1
- package/dist/index.d.ts +5 -1
- package/dist/index.js +2 -0
- package/dist/lifecycle.d.ts +2 -0
- package/dist/lifecycle.js +2 -1
- package/dist/live-client.js +8 -6
- package/dist/live-page.d.ts +0 -7
- package/dist/live-page.js +3 -2
- package/dist/live-server.js +6 -3
- package/dist/live.js +2 -1
- package/dist/login-tool.js +3 -2
- package/dist/login.js +2 -1
- package/dist/names.d.ts +28 -0
- package/dist/names.js +25 -0
- package/dist/network.d.ts +1 -1
- package/dist/network.js +4 -3
- package/dist/opt-in-settings.js +3 -2
- package/dist/replay.js +4 -3
- package/dist/runtime-lock.js +3 -2
- package/dist/vault.js +5 -4
- package/npm-shrinkwrap.json +6 -5
- 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
|
|
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
|
-
|
|
57
|
-
playwright-core (turno
|
|
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
|
|
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
|
-
|
|
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
|
-
...(
|
|
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:
|
|
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 (
|
|
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;
|