turno-browser 0.4.0 → 0.5.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 +24 -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/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 +171 -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 +7 -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/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,29 @@
|
|
|
1
1
|
# turno-browser
|
|
2
2
|
|
|
3
|
+
## 0.5.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 44fb809: `turno-browser-mcp --identity <id> --background` serves an identity to the shell without turno: MCP over streamable HTTP on a Unix socket in a private folder of the identity's state (or 127.0.0.1 with a per-server token where a socket cannot be used), one Chrome shared by every connection with the identity's sharing rules, and an exit after 15 minutes without a request (`--background-idle`, `TURNO_BROWSER_BACKGROUND_IDLE`). While it runs it alone drives the identity's browser: a stdio server of the same identity refuses calls that need the browser with a message that names it, and it does not start while another process has the identity's Chrome open. The package exports a client for it (`startBackground`, `backgroundStatus`, `openBackgroundSession`, `stopBackground`), also in the typed api, now version 1.11. turno-cli now asks for turno-browser 1.11 or a later 1.x.
|
|
8
|
+
- df52afc: turno-browser has its own `turno-browser` command: add, list, show, set, login, vault, export, import, flows, replay, record, traces, live, pause, resume, doctor and reputation work without turno, with `--version` and a help grouped by section. `turno-browser add` prints how to connect an agent instead of an `mcp.toml` block, and `turno-browser do` says it needs turno for now. `turno browser ...` and the browser part of `turno identity ...` now run turno-browser's commands through its typed api (API_VERSION 1.12, new member `cli`) with the same flags, output and exit codes, so turno-cli needs turno-browser 1.12 or a later 1.x. turno-core gains `turno-core/cli`, the command line toolkit (arguments, output, styles, exit codes, command groups, hints, hidden input) that both programs share.
|
|
9
|
+
- e2b1779: `turno-browser do` works without turno: it starts the identity's background server on the first action, keeps one session per agent or shell between commands, and ends it with `end`, `close` or when that process exits. `turno browser do` keeps going through mcpd.
|
|
10
|
+
|
|
11
|
+
New `turno-browser` commands: `setup <claude-code|codex|cursor|copilot|gemini|json> [--identity <id>]` prints the MCP config that gives an agent an identity (it writes nothing; `--json` for scripts), `background status|start|stop` shows and controls the background servers, and `secret set|has|list|remove` stores the `keychain:<item>` secrets identity.json names, in the same store and items as `turno secret`.
|
|
12
|
+
|
|
13
|
+
Hints, errors and doctor fixes name the commands of the program you typed: `turno-browser ...` on its own (the MCP server's messages too), `turno browser ...` and `turno identity ... browser:<id>` inside turno. `turno-browser doctor` lists a running background server, and a stdio server refused by a background server names `turno-browser background stop <id>`.
|
|
14
|
+
|
|
15
|
+
turno-core exports the owner, name and lock of a shell session of browser commands (`turno-core/cli`), shared by `turno browser do` and `turno-browser do`.
|
|
16
|
+
|
|
17
|
+
The npm description, keywords and MCP Registry entry follow the new tagline. Wording: the help no longer labels the off-by-default settings (natural language actions, captcha solving, network and user agent, Camoufox) as "not recommended"; they stay off by default and the help still says what each one sends where.
|
|
18
|
+
|
|
19
|
+
### Patch Changes
|
|
20
|
+
|
|
21
|
+
- d97dbec: Human-like input no longer falls back to a plain fill or click on a busy machine: the steps before
|
|
22
|
+
an action (reading the field, aiming at the element) now wait up to 3 seconds for it instead of 1.
|
|
23
|
+
- Updated dependencies [df52afc]
|
|
24
|
+
- Updated dependencies [e2b1779]
|
|
25
|
+
- turno-core@0.2.0
|
|
26
|
+
|
|
3
27
|
## 0.4.0
|
|
4
28
|
|
|
5
29
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -1,19 +1,23 @@
|
|
|
1
1
|
# turno-browser
|
|
2
2
|
|
|
3
|
-
**A browser
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
**A browser your agents use with your accounts. It stays light on your machine, and the model
|
|
4
|
+
never sees your passwords.**
|
|
5
|
+
|
|
6
|
+
An MCP server that lets a coding agent drive the Google Chrome installed on your machine, with
|
|
7
|
+
one persistent profile per identity. You sign in to a site once, by hand, and the agent works in
|
|
8
|
+
that same signed-in browser afterwards.
|
|
6
9
|
|
|
7
10
|

|
|
8
11
|
|
|
9
12
|
```sh
|
|
10
13
|
npm install --global turno-browser
|
|
11
|
-
turno
|
|
12
|
-
turno
|
|
14
|
+
turno-browser add school # a new identity
|
|
15
|
+
turno-browser login school # sign in by hand once; cookies persist
|
|
16
|
+
turno-browser setup claude-code --identity school # prints how Claude Code gets it
|
|
13
17
|
```
|
|
14
18
|
|
|
15
|
-
|
|
16
|
-
|
|
19
|
+
The docs are at [turno.wimo.dev/docs/browser](https://turno.wimo.dev/docs/browser), starting with
|
|
20
|
+
[Get started](https://turno.wimo.dev/docs/browser/get-started).
|
|
17
21
|
|
|
18
22
|
## Why
|
|
19
23
|
|
|
@@ -24,28 +28,66 @@ with it; turno works without it. The whole story is at [turno.wimo.dev](https://
|
|
|
24
28
|
- **Passwords should not pass through a model.** A vault in the OS secret store fills a sign-in
|
|
25
29
|
form without the agent ever seeing the values.
|
|
26
30
|
|
|
31
|
+
## Where it sits
|
|
32
|
+
|
|
33
|
+
A driver moves the browser. turno-browser is the layer above it: it decides which browser that
|
|
34
|
+
is, whose session it carries, how long it stays open and what the model gets to see. It serves
|
|
35
|
+
the Playwright MCP tools and flags (`browser_navigate`, `browser_click`, `browser_snapshot` and
|
|
36
|
+
the rest) on your own Chrome, headed by default. It sits next to tools like browser-use,
|
|
37
|
+
Stagehand and Browserbase; [Browser tools compared](https://turno.wimo.dev/docs/browser/alternatives)
|
|
38
|
+
says when each one is the better choice.
|
|
39
|
+
|
|
27
40
|
## What you get
|
|
28
41
|
|
|
42
|
+
On from the start:
|
|
43
|
+
|
|
44
|
+
| | |
|
|
45
|
+
|---|---|
|
|
46
|
+
| [Identities](https://turno.wimo.dev/docs/browser/identities) | one Chrome profile per identity, with its time zone, languages and locale fixed |
|
|
47
|
+
| [Tab limits](https://turno.wimo.dev/docs/browser/tabs) | at most 8 pages, parked after 5 minutes unused, closed after 15; Chrome closes after 15 minutes without a call |
|
|
48
|
+
| [Credential vault](https://turno.wimo.dev/docs/browser/vault) | `browser_login` fills username, password and one-time code; the agent never sees them |
|
|
49
|
+
| [Session export and import](https://turno.wimo.dev/docs/browser/moving-a-session) | an identity's session as one encrypted file, for another machine |
|
|
50
|
+
| [`browser_batch`](https://turno.wimo.dev/docs/browser/actions) | up to 20 actions in one call, and errors that say what is in the way |
|
|
51
|
+
| [Flows](https://turno.wimo.dev/docs/browser/flows) | save what an agent did on a site once, and replay it with parameters |
|
|
52
|
+
| [From the shell](https://turno.wimo.dev/docs/browser/actions#from-the-shell) | `turno-browser do <id> open`, `snapshot`, `click`, `type`, `read`: the same browser and rules, as shell commands |
|
|
53
|
+
| [Health, reputation and doctor](https://turno.wimo.dev/docs/browser/identities#session-health) | a signed-out identity says so, each site's challenges are counted, and `doctor` checks Chrome and every identity |
|
|
54
|
+
|
|
55
|
+
Off until you turn it on, per identity:
|
|
56
|
+
|
|
29
57
|
| | |
|
|
30
58
|
|---|---|
|
|
31
|
-
| [
|
|
32
|
-
| [
|
|
33
|
-
| [
|
|
34
|
-
| [
|
|
35
|
-
| [
|
|
36
|
-
| [
|
|
37
|
-
| [
|
|
38
|
-
| [
|
|
39
|
-
| [
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
the
|
|
47
|
-
|
|
48
|
-
|
|
59
|
+
| [Several agents, one browser](https://turno.wimo.dev/docs/browser/sharing) | several agent sessions in one identity's Chrome, each in its own tabs |
|
|
60
|
+
| [Live view and take-over](https://turno.wimo.dev/docs/browser/live-view) | watch the agent's tab on 127.0.0.1, pause it, act, and resume; the agent is told what changed |
|
|
61
|
+
| [Recordings and traces](https://turno.wimo.dev/docs/browser/flows#recordings-and-traces) | every session as a flow, a Playwright trace and a screenshot per action |
|
|
62
|
+
| [Human-like input](https://turno.wimo.dev/docs/browser/actions#human-like-input) | the pointer moves along a curve and text is typed key by key |
|
|
63
|
+
| [Blocking and cache](https://turno.wimo.dev/docs/browser/network#blocking-and-the-resource-cache) | block trackers, images, media or fonts; cache static resources on disk |
|
|
64
|
+
| [User agent and proxy](https://turno.wimo.dev/docs/browser/network#network-and-user-agent) | a user agent built from your installed Chrome, and a proxy with its password in the secret store |
|
|
65
|
+
| [Engines](https://turno.wimo.dev/docs/browser/engines) | read mode on Lightpanda for reading pages with little memory, attach to the Chrome you have open, or Camoufox |
|
|
66
|
+
| [Natural language actions](https://turno.wimo.dev/docs/browser/natural-language-and-captchas#natural-language-actions) | `browser_act`, `browser_extract` and `browser_observe`, on a model you pick |
|
|
67
|
+
| [Captcha solving](https://turno.wimo.dev/docs/browser/natural-language-and-captchas#captcha-solving) | `browser_solve_captcha`, through a solver service you configure |
|
|
68
|
+
|
|
69
|
+
## On its own, or with turno
|
|
70
|
+
|
|
71
|
+
**On its own.** turno-browser is its own package: it does not need turno. `turno-browser setup
|
|
72
|
+
<agent>` prints the config for Claude Code, Codex, Cursor, Copilot or Gemini (or a generic JSON
|
|
73
|
+
entry), and writes nothing. The agent then runs `turno-browser-mcp --identity <id>` when it needs
|
|
74
|
+
the browser. From a terminal, `turno-browser do` reaches the same browser through a background
|
|
75
|
+
server it starts on demand:
|
|
76
|
+
|
|
77
|
+
```sh
|
|
78
|
+
turno-browser do school open https://example.com
|
|
79
|
+
turno-browser do school snapshot
|
|
80
|
+
turno-browser background stop school
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
**With [turno](https://www.npmjs.com/package/turno-cli).** turno's gateway runs one browser
|
|
84
|
+
server for every session of every agent and stops it when nobody uses it. `turno browser
|
|
85
|
+
<command>` and `turno identity ... browser:<id>` run the same commands and add what turno has,
|
|
86
|
+
like the `mcp.toml` block. See the guide
|
|
87
|
+
[Let an agent use my signed-in browser](https://turno.wimo.dev/docs/guides/signed-in-browser).
|
|
88
|
+
|
|
89
|
+
`turno-browser --help` lists every command by section, and the
|
|
90
|
+
[reference](https://turno.wimo.dev/docs/reference/turno-browser) has the help of each one.
|
|
49
91
|
|
|
50
92
|
## Identities
|
|
51
93
|
|
|
@@ -53,22 +95,15 @@ Each identity keeps, next to its profile, an `identity.json` with what should no
|
|
|
53
95
|
sessions: time zone, languages, locale, region, and an optional session health check.
|
|
54
96
|
|
|
55
97
|
```sh
|
|
56
|
-
turno
|
|
57
|
-
turno
|
|
58
|
-
turno
|
|
98
|
+
turno-browser add school --languages es-MX,es,en
|
|
99
|
+
turno-browser set school --health-url https://mail.example.com/ --health-text Inbox
|
|
100
|
+
turno-browser show school
|
|
59
101
|
```
|
|
60
102
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
- **One Chrome per identity.** While a server drives an identity's Chrome it holds a lock; a
|
|
66
|
-
second server gets a message naming that process and how to stop it, instead of "Browser is
|
|
67
|
-
already in use".
|
|
68
|
-
- **Through the gateway.** `turno identity add` prints the `mcp.toml` block: a `shared`,
|
|
69
|
-
`exclusive` server, so one session uses the identity at a time and mcpd stops it when idle.
|
|
70
|
-
With `"sharing": "tabs"` (`turno identity set browser:<id> --sharing tabs`, then
|
|
71
|
-
`exclusive = false`) several agent sessions use it at once, each in its own locked tabs.
|
|
103
|
+
The settings are applied at every Chrome start, and one Chrome runs per identity: a second
|
|
104
|
+
server gets a message that names the process holding it. With a health check, a signed-out
|
|
105
|
+
identity is marked `NEEDS_AUTH` and tool calls ask for `turno-browser login <id>` instead of
|
|
106
|
+
failing on a login page.
|
|
72
107
|
|
|
73
108
|
## Credential vault
|
|
74
109
|
|
|
@@ -77,39 +112,20 @@ An identity can keep a username, a password and a TOTP secret per site in the OS
|
|
|
77
112
|
into that site's sign-in page:
|
|
78
113
|
|
|
79
114
|
```sh
|
|
80
|
-
turno
|
|
81
|
-
turno
|
|
82
|
-
turno browser vault submit school auto # browser_login also submits (default: it only fills)
|
|
115
|
+
turno-browser vault add school mail --url https://mail.example.com/login --username alice --totp
|
|
116
|
+
turno-browser vault list school
|
|
83
117
|
```
|
|
84
118
|
|
|
85
|
-
- **Bound to the site.** The tool fills only when the page is on an origin given with `--url
|
|
86
|
-
|
|
87
|
-
- **Never in a result.** Once a value was filled, every result and error
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
- **One-time codes.** TOTP follows RFC 6238 (SHA1, SHA256, SHA512, 6 to 8 digits), from a base32
|
|
92
|
-
secret or the `otpauth://` URI of the QR code.
|
|
119
|
+
- **Bound to the site.** The tool fills only when the page is on an origin given with `--url`,
|
|
120
|
+
and only into frames of those origins.
|
|
121
|
+
- **Never in a result.** Once a value was filled, every result and error shows `[vault: ...]`
|
|
122
|
+
in its place: snapshots, network requests and console messages.
|
|
123
|
+
- **It does not submit.** The agent clicks the sign-in button, unless you run
|
|
124
|
+
`turno-browser vault submit school auto`.
|
|
93
125
|
|
|
94
126
|
The threat model is in
|
|
95
127
|
[SECURITY.md](https://github.com/wimo-dev/turno/blob/main/SECURITY.md#the-credential-vault).
|
|
96
128
|
|
|
97
|
-
## Move a session
|
|
98
|
-
|
|
99
|
-
```sh
|
|
100
|
-
turno browser export school --out school.session --expires 2d # asks for a passphrase twice
|
|
101
|
-
turno browser import school.session --as school-laptop
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
The file holds the identity's cookies, localStorage and IndexedDB, encrypted with the passphrase
|
|
105
|
-
(scrypt and AES-256-GCM), and is refused after its expiry (7 days by default, at most 90). It
|
|
106
|
-
never holds vault credentials. Importing into an existing identity replaces its session and asks
|
|
107
|
-
first.
|
|
108
|
-
|
|
109
|
-
`"keychain": "system"` in `identity.json` makes Chrome encrypt the profile's cookies with the OS
|
|
110
|
-
keychain's key instead of Playwright's fixed mock key, so a copy of the profile folder does not
|
|
111
|
-
hand over the sessions. Changing it signs the identity out: export first and import after.
|
|
112
|
-
|
|
113
129
|
## A browser that cleans up
|
|
114
130
|
|
|
115
131
|
| What | Default |
|
|
@@ -118,98 +134,25 @@ hand over the sessions. Changing it signs the identity out: export first and imp
|
|
|
118
134
|
| Popups that open while no tool call runs | closed; a window the agent's own click opened stays |
|
|
119
135
|
| A page unused for 5 minutes | parked on `about:blank`; it loads again when the agent uses it |
|
|
120
136
|
| A page unused for 15 minutes | closed |
|
|
121
|
-
| Chrome with no tool call for 15 minutes | closed
|
|
122
|
-
|
|
123
|
-
```sh
|
|
124
|
-
turno identity set browser:school --tabs-max 4 --tabs-popups keep --tabs-park 2m --tabs-close 0
|
|
125
|
-
```
|
|
126
|
-
|
|
127
|
-
- What was closed or parked is listed at the end of the next tool result.
|
|
128
|
-
- When the client closes stdin or the server gets SIGTERM, Chrome closes within about 2.5
|
|
129
|
-
seconds, forcefully if it does not answer. A Chrome that an earlier, killed run left open on the
|
|
130
|
-
same profile is closed when the identity starts again; one that another live process drives is
|
|
131
|
-
left alone.
|
|
132
|
-
- `TURNO_BROWSER_IDLE` changes the idle limit (`"10m"`, `"90s"`, `"0"` keeps Chrome open);
|
|
133
|
-
`--idle-timeout <ms>` or a `--config` file of your own take precedence.
|
|
134
|
-
- Through mcpd, stopping the server closes its stdin and waits 5 seconds before SIGTERM
|
|
135
|
-
(`stop_grace`), so Chrome writes its profile on its own.
|
|
136
|
-
|
|
137
|
-
## Faster actions
|
|
138
|
-
|
|
139
|
-
- **`browser_batch`** runs up to 20 browser actions in order in one call, checks every action's
|
|
140
|
-
arguments before running any, stops at the first failure and returns one line per action,
|
|
141
|
-
plus one snapshot at the end when asked. A form filled in one call costs the agent one round
|
|
142
|
-
trip instead of one per field.
|
|
143
|
-
- **Errors that help.** A click, hover, type, select or drag that times out because of the page
|
|
144
|
-
says which element covers the target (a cookie banner, a dialog) with its buttons, or that the
|
|
145
|
-
target is hidden, disabled, read-only or gone, and suggests the next step.
|
|
146
|
-
- **A shorter wait.** Playwright waits 500 ms after each action; `"settle": "100ms"` in
|
|
147
|
-
`identity.json` (`turno identity set browser:school --settle 100ms`) shortens it.
|
|
148
|
-
|
|
149
|
-
## Human-like input
|
|
150
|
-
|
|
151
|
-
Off by default. `turno identity set browser:school --humanize light` (or `full`, `adaptive`; the
|
|
152
|
-
server's `--humanize` wins) makes the stock tools move the pointer along a curve to a point inside
|
|
153
|
-
the target, hold the button for tens of milliseconds and type short text key by key; `full` adds
|
|
154
|
-
overshoot, reading pauses and wheel scrolling, and `adaptive` uses `full` only on sites that showed
|
|
155
|
-
a challenge page. Schemas and results stay the same; each click costs about 0.5 s (`light`) to
|
|
156
|
-
1 s (`full`). See [Human-like input](https://turno.wimo.dev/docs/concepts/browser-identities#human-like-input).
|
|
157
|
-
|
|
158
|
-
## Record and replay
|
|
159
|
-
|
|
160
|
-
- **Flows.** `browser_record` saves the actions of a session as a named flow, each element kept
|
|
161
|
-
four ways (Playwright's locator, role and name, text, CSS path); `browser_replay` runs it again
|
|
162
|
-
with parameters and, when a step no longer fits, stops with a report the agent can continue
|
|
163
|
-
from. `turno browser flows|replay <id>` does the same from a terminal.
|
|
164
|
-
- **No secrets in a flow.** Typed text is a parameter; a password, a one-time code or a value the
|
|
165
|
-
agent marks sensitive keeps no value, and a vault sign-in is the site name only. A sensitive
|
|
166
|
-
value at replay can be `keychain:<item>`, read from the secret store.
|
|
167
|
-
- **Recordings, opt-in.** `turno browser record <id> --flows --traces --screenshots` keeps every
|
|
168
|
-
session as a flow, a Playwright trace and a screenshot per action, under a size cap (200MB);
|
|
169
|
-
`turno browser traces <id> --open` shows a trace in the bundled viewer. The trace stops before
|
|
170
|
-
a sign-in and starts again after the page navigates, so no vault value is ever in one.
|
|
171
|
-
|
|
172
|
-
## Lighter pages
|
|
173
|
-
|
|
174
|
-
Both are off until an identity asks for them:
|
|
137
|
+
| Chrome with no tool call for 15 minutes | closed; the next call opens it with the same profile |
|
|
175
138
|
|
|
176
139
|
```sh
|
|
177
|
-
turno
|
|
178
|
-
turno identity set browser:school --no-block --no-cache # both off again
|
|
140
|
+
turno-browser set school --tabs-max 4 --tabs-popups keep --tabs-park 2m --tabs-close 0
|
|
179
141
|
```
|
|
180
142
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
itself is never blocked.
|
|
184
|
-
- **Cache**: images, fonts, stylesheets and scripts on disk for that identity only, following
|
|
185
|
-
`Cache-Control`, never a response with `Set-Cookie` or a request with `Authorization`.
|
|
186
|
-
|
|
187
|
-
## Know when something is wrong
|
|
188
|
-
|
|
189
|
-
- **Signed out.** With a health check (a URL and a text or selector), each Chrome start opens
|
|
190
|
-
the page and looks for it. When it is missing the identity is marked NEEDS_AUTH and tool calls
|
|
191
|
-
fail with a message asking for `turno browser login <id>`.
|
|
192
|
-
- **Reputation.** Every captcha, "verify it's you" or block page is one line in the identity's
|
|
193
|
-
state folder, with the host name only (no path, no page content).
|
|
194
|
-
`turno browser reputation [<id>]` shows counts per site and their trend.
|
|
195
|
-
- **Doctor.** `turno browser doctor [--fix] [--json]` checks Chrome and its version, a test
|
|
196
|
-
launch on a temporary profile, and each identity's settings, lock and sign-in.
|
|
143
|
+
What was closed or parked is listed at the end of the next tool result. When the agent that
|
|
144
|
+
started it exits, Chrome closes too.
|
|
197
145
|
|
|
198
|
-
##
|
|
146
|
+
## Move a session
|
|
199
147
|
|
|
200
148
|
```sh
|
|
201
|
-
turno-browser
|
|
202
|
-
turno-browser
|
|
149
|
+
turno-browser export school --out school.session --expires 2d # asks for a passphrase twice
|
|
150
|
+
turno-browser import school.session --as school-laptop
|
|
203
151
|
```
|
|
204
152
|
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
More: [Browser identities](https://turno.wimo.dev/docs/concepts/browser-identities),
|
|
210
|
-
[`turno browser`](https://turno.wimo.dev/docs/reference/cli/browser), the guide
|
|
211
|
-
[Let an agent use my signed-in browser](https://turno.wimo.dev/docs/guides/signed-in-browser), and
|
|
212
|
-
what each version added in [Releases](https://turno.wimo.dev/docs/releases).
|
|
153
|
+
The file holds the identity's cookies, localStorage and IndexedDB, encrypted with the passphrase
|
|
154
|
+
(scrypt and AES-256-GCM), and is refused after its expiry (7 days by default, at most 90). It
|
|
155
|
+
never holds vault credentials.
|
|
213
156
|
|
|
214
157
|
## Acceptable use
|
|
215
158
|
|
package/dist/act-model.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { secretStore } from "turno-core/secrets";
|
|
2
|
+
import { names } from "./names.js";
|
|
2
3
|
/** A rough token count for budgets when a provider does not report one: 4 characters a token. */
|
|
3
4
|
export function estimateTokens(text) {
|
|
4
5
|
return Math.ceil(text.length / 4);
|
|
@@ -92,8 +93,8 @@ export async function resolveModel(options) {
|
|
|
92
93
|
return samplingModel(sample);
|
|
93
94
|
if (!settings.provider || !settings.endpoint || !settings.model) {
|
|
94
95
|
throw new ModelError(settings.sampling === false
|
|
95
|
-
? `natural language actions of "${options.id}" have no provider (
|
|
96
|
-
: `this client does not offer MCP sampling and identity "${options.id}" names no provider: set one with
|
|
96
|
+
? `natural language actions of "${options.id}" have no provider (${names().identity("set", options.id)} --act-provider chat-completions --act-endpoint <url> --act-model <name>)`
|
|
97
|
+
: `this client does not offer MCP sampling and identity "${options.id}" names no provider: set one with ${names().identity("set", options.id)} --act-provider chat-completions --act-endpoint <url> --act-model <name> [--act-key keychain:<item>]`);
|
|
97
98
|
}
|
|
98
99
|
let key;
|
|
99
100
|
if (settings.key) {
|
|
@@ -103,7 +104,7 @@ export async function resolveModel(options) {
|
|
|
103
104
|
throw new ModelError(`act.key names ${settings.key}, but this machine has no secret store`);
|
|
104
105
|
key = await store.get(item).catch(() => undefined);
|
|
105
106
|
if (key === undefined)
|
|
106
|
-
throw new ModelError(`the secret store has no item "${item}" for act.key (store it with:
|
|
107
|
+
throw new ModelError(`the secret store has no item "${item}" for act.key (store it with: ${names().secretSet(item)})`);
|
|
107
108
|
redactor.add(key, "act model key");
|
|
108
109
|
}
|
|
109
110
|
return chatCompletionsModel({
|
package/dist/act.js
CHANGED
|
@@ -4,6 +4,7 @@ import { actBudget } from "./opt-in-settings.js";
|
|
|
4
4
|
import { SECRET_AUTOCOMPLETE, SECRET_NAME, secretValues } from "./recorder.js";
|
|
5
5
|
import { readIdentitySettings } from "./settings.js";
|
|
6
6
|
import { upstream } from "./upstream.js";
|
|
7
|
+
import { names } from "./names.js";
|
|
7
8
|
/**
|
|
8
9
|
* Natural language actions, off by default (identity.json `act`): `browser_act` turns an
|
|
9
10
|
* instruction into stock tool calls, `browser_extract` reads data off the page, and
|
|
@@ -238,7 +239,7 @@ async function prepare(ctx, tool, instruction) {
|
|
|
238
239
|
}
|
|
239
240
|
if (!settings)
|
|
240
241
|
return {
|
|
241
|
-
error: `natural language actions are off for identity "${identity.id}"; the person turns them on with
|
|
242
|
+
error: `natural language actions are off for identity "${identity.id}"; the person turns them on with ${names().identity("set", identity.id)} --act (MCP sampling) or --act-provider ..., then restarts the server`,
|
|
242
243
|
};
|
|
243
244
|
if (!instruction.trim())
|
|
244
245
|
return { error: "the instruction is empty" };
|
package/dist/api.d.ts
CHANGED
|
@@ -14,6 +14,8 @@ import { parseTotpSecret } from "./totp.js";
|
|
|
14
14
|
import { vaultAdd, vaultClear, vaultList, vaultRemove, vaultSetSubmit } from "./vault.js";
|
|
15
15
|
import { checkIdentitySettings, identitySettingsPath, writeIdentitySettings } from "./settings.js";
|
|
16
16
|
import { manifestSnippet } from "./snippet.js";
|
|
17
|
+
import { backgroundStatus, openBackgroundSession, startBackground, stopBackground } from "./client.js";
|
|
18
|
+
import { browserCli } from "./cli/commands.js";
|
|
17
19
|
/**
|
|
18
20
|
* The contract between turno-browser and turno-cli. turno-cli installs this package
|
|
19
21
|
* apart, types it with `import type` (erased at build, so the package stays optional) and,
|
|
@@ -28,7 +30,7 @@ import { manifestSnippet } from "./snippet.js";
|
|
|
28
30
|
*/
|
|
29
31
|
export declare const API_VERSION: Readonly<{
|
|
30
32
|
readonly major: 1;
|
|
31
|
-
readonly minor:
|
|
33
|
+
readonly minor: 12;
|
|
32
34
|
}>;
|
|
33
35
|
/** What `API_VERSION` looks like to a reader that does not know this package's version. */
|
|
34
36
|
export interface ApiVersion {
|
|
@@ -47,8 +49,61 @@ export interface ApiVersion {
|
|
|
47
49
|
* `runDoctor({ servers })`, the mcp.toml servers of each identity, (1.9) the `live` key of
|
|
48
50
|
* identity.json and the live view of a running server (status, pause, resume, a one-time link),
|
|
49
51
|
* and (1.10) the `userAgent` and `proxy` keys and the `"camoufox"` engine of identity.json, and
|
|
50
|
-
* the Camoufox and network checks of `runDoctor` (no new member: an older package refuses them)
|
|
52
|
+
* the Camoufox and network checks of `runDoctor` (no new member: an older package refuses them),
|
|
53
|
+
* and (1.11) the background server of an identity: start, status, stop, and its sessions.
|
|
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.
|
|
51
56
|
*/
|
|
57
|
+
declare const functions: {
|
|
58
|
+
ENGINES: readonly ["chrome-headed", "chrome-headless", "chrome-baseline", "firefox"];
|
|
59
|
+
engineId: typeof engineId;
|
|
60
|
+
listIdentities: typeof listIdentities;
|
|
61
|
+
addIdentity: typeof addIdentity;
|
|
62
|
+
removeIdentity: typeof removeIdentity;
|
|
63
|
+
identityExists: typeof identityExists;
|
|
64
|
+
identityDir: typeof identityDir;
|
|
65
|
+
identitySettingsPath: typeof identitySettingsPath;
|
|
66
|
+
isInUse: typeof isInUse;
|
|
67
|
+
inUseBy: typeof inUseBy;
|
|
68
|
+
assertIdentityId: typeof assertIdentityId;
|
|
69
|
+
manifestSnippet: typeof manifestSnippet;
|
|
70
|
+
loginIdentity: typeof loginIdentity;
|
|
71
|
+
checkIdentitySettings: typeof checkIdentitySettings;
|
|
72
|
+
writeIdentitySettings: typeof writeIdentitySettings;
|
|
73
|
+
readHealth: typeof readHealth;
|
|
74
|
+
runDoctor: typeof runDoctor;
|
|
75
|
+
reputationReport: typeof reputationReport;
|
|
76
|
+
runBench: typeof runBench;
|
|
77
|
+
formatBenchTable: typeof formatBenchTable;
|
|
78
|
+
vaultAdd: typeof vaultAdd;
|
|
79
|
+
vaultList: typeof vaultList;
|
|
80
|
+
vaultRemove: typeof vaultRemove;
|
|
81
|
+
vaultClear: typeof vaultClear;
|
|
82
|
+
vaultSetSubmit: typeof vaultSetSubmit;
|
|
83
|
+
parseTotpSecret: typeof parseTotpSecret;
|
|
84
|
+
exportSession: typeof exportSession;
|
|
85
|
+
readSessionExport: typeof readSessionExport;
|
|
86
|
+
importSession: typeof importSession;
|
|
87
|
+
flowsDir: typeof flowsDir;
|
|
88
|
+
listFlows: typeof listFlows;
|
|
89
|
+
readFlow: typeof readFlow;
|
|
90
|
+
removeFlow: typeof removeFlow;
|
|
91
|
+
replayFlow: typeof replayFlow;
|
|
92
|
+
listRecordings: typeof listRecordings;
|
|
93
|
+
recordingsDir: typeof recordingsDir;
|
|
94
|
+
traceViewerCommand: typeof traceViewerCommand;
|
|
95
|
+
openTraceViewer: typeof openTraceViewer;
|
|
96
|
+
liveStatus: typeof liveStatus;
|
|
97
|
+
livePause: typeof livePause;
|
|
98
|
+
liveResume: typeof liveResume;
|
|
99
|
+
liveLink: typeof liveLink;
|
|
100
|
+
startBackground: typeof startBackground;
|
|
101
|
+
backgroundStatus: typeof backgroundStatus;
|
|
102
|
+
stopBackground: typeof stopBackground;
|
|
103
|
+
openBackgroundSession: typeof openBackgroundSession;
|
|
104
|
+
};
|
|
105
|
+
/** The functions the identity commands call; tests of the commands pass fakes of them. */
|
|
106
|
+
export type BrowserFunctions = typeof functions;
|
|
52
107
|
export declare const api: Readonly<{
|
|
53
108
|
ENGINES: readonly ["chrome-headed", "chrome-headless", "chrome-baseline", "firefox"];
|
|
54
109
|
engineId: typeof engineId;
|
|
@@ -92,5 +147,11 @@ export declare const api: Readonly<{
|
|
|
92
147
|
livePause: typeof livePause;
|
|
93
148
|
liveResume: typeof liveResume;
|
|
94
149
|
liveLink: typeof liveLink;
|
|
150
|
+
startBackground: typeof startBackground;
|
|
151
|
+
backgroundStatus: typeof backgroundStatus;
|
|
152
|
+
stopBackground: typeof stopBackground;
|
|
153
|
+
openBackgroundSession: typeof openBackgroundSession;
|
|
154
|
+
cli: typeof browserCli;
|
|
95
155
|
}>;
|
|
96
156
|
export type BrowserApi = typeof api;
|
|
157
|
+
export {};
|
package/dist/api.js
CHANGED
|
@@ -14,6 +14,8 @@ import { parseTotpSecret } from "./totp.js";
|
|
|
14
14
|
import { vaultAdd, vaultClear, vaultList, vaultRemove, vaultSetSubmit } from "./vault.js";
|
|
15
15
|
import { checkIdentitySettings, identitySettingsPath, writeIdentitySettings } from "./settings.js";
|
|
16
16
|
import { manifestSnippet } from "./snippet.js";
|
|
17
|
+
import { backgroundStatus, openBackgroundSession, startBackground, stopBackground } from "./client.js";
|
|
18
|
+
import { browserCli } from "./cli/commands.js";
|
|
17
19
|
/**
|
|
18
20
|
* The contract between turno-browser and turno-cli. turno-cli installs this package
|
|
19
21
|
* apart, types it with `import type` (erased at build, so the package stays optional) and,
|
|
@@ -26,7 +28,7 @@ import { manifestSnippet } from "./snippet.js";
|
|
|
26
28
|
*
|
|
27
29
|
* `test/api.test.ts` lists the members, so a change here cannot ship without the version.
|
|
28
30
|
*/
|
|
29
|
-
export const API_VERSION = Object.freeze({ major: 1, minor:
|
|
31
|
+
export const API_VERSION = Object.freeze({ major: 1, minor: 12 });
|
|
30
32
|
/**
|
|
31
33
|
* The functions turno-cli calls: identities, their settings, login, doctor, reputation, bench
|
|
32
34
|
* (1.1) the credential vault, (1.2) session export and import, (1.3) the `humanize` key of
|
|
@@ -39,9 +41,12 @@ export const API_VERSION = Object.freeze({ major: 1, minor: 10 });
|
|
|
39
41
|
* `runDoctor({ servers })`, the mcp.toml servers of each identity, (1.9) the `live` key of
|
|
40
42
|
* identity.json and the live view of a running server (status, pause, resume, a one-time link),
|
|
41
43
|
* and (1.10) the `userAgent` and `proxy` keys and the `"camoufox"` engine of identity.json, and
|
|
42
|
-
* the Camoufox and network checks of `runDoctor` (no new member: an older package refuses them)
|
|
44
|
+
* the Camoufox and network checks of `runDoctor` (no new member: an older package refuses them),
|
|
45
|
+
* and (1.11) the background server of an identity: start, status, stop, and its sessions.
|
|
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.
|
|
43
48
|
*/
|
|
44
|
-
|
|
49
|
+
const functions = {
|
|
45
50
|
ENGINES,
|
|
46
51
|
engineId,
|
|
47
52
|
listIdentities,
|
|
@@ -84,5 +89,10 @@ export const api = Object.freeze({
|
|
|
84
89
|
livePause,
|
|
85
90
|
liveResume,
|
|
86
91
|
liveLink,
|
|
87
|
-
|
|
92
|
+
startBackground,
|
|
93
|
+
backgroundStatus,
|
|
94
|
+
stopBackground,
|
|
95
|
+
openBackgroundSession,
|
|
96
|
+
};
|
|
97
|
+
export const api = Object.freeze({ ...functions, cli: browserCli });
|
|
88
98
|
//# sourceMappingURL=api.js.map
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import type { IdentityRef } from "./engine.js";
|
|
2
|
+
/**
|
|
3
|
+
* Where the background server of an identity (`turno-browser-mcp --identity <id> --background`)
|
|
4
|
+
* says it runs, and the rule it keeps with the other servers of that identity.
|
|
5
|
+
*
|
|
6
|
+
* Everything lives in `<state>/browser/identities/<id>/background/`, a folder only the user can
|
|
7
|
+
* enter (0700): `server.json` (pid, address, version, mode 600), the Unix socket `sock`, or on a
|
|
8
|
+
* system without one, `token` (the per-server bearer token of the loopback port, mode 600), and
|
|
9
|
+
* `server.log`, where a server started by the client module writes its output.
|
|
10
|
+
*
|
|
11
|
+
* The rule: while a background server runs, it is the one owner of the identity's browser. A
|
|
12
|
+
* stdio server of the same identity refuses every call that would launch the browser, with a
|
|
13
|
+
* message that names the background server and how to stop it, and a background server does not
|
|
14
|
+
* start while another process holds the identity's runtime lock (its Chrome is open). Calls are
|
|
15
|
+
* never forwarded from one server to the other: either way there is one Chrome, never a wait.
|
|
16
|
+
*/
|
|
17
|
+
export interface BackgroundState {
|
|
18
|
+
v: 1;
|
|
19
|
+
pid: number;
|
|
20
|
+
identity: string;
|
|
21
|
+
/** turno-browser's version. */
|
|
22
|
+
version: string;
|
|
23
|
+
startedAt: string;
|
|
24
|
+
/** Exits after this long without a request; 0 never. */
|
|
25
|
+
idleMs: number;
|
|
26
|
+
/** Absent while the server starts; then where it listens. */
|
|
27
|
+
transport?: "socket" | "tcp";
|
|
28
|
+
/** `transport: "socket"`: the Unix socket. */
|
|
29
|
+
socket?: string;
|
|
30
|
+
/** `transport: "tcp"`: the loopback port, and the file that holds its bearer token. */
|
|
31
|
+
port?: number;
|
|
32
|
+
tokenFile?: string;
|
|
33
|
+
}
|
|
34
|
+
export declare function backgroundDir(id: string, env?: NodeJS.ProcessEnv): string;
|
|
35
|
+
export declare function backgroundStatePath(id: string, env?: NodeJS.ProcessEnv): string;
|
|
36
|
+
export declare function backgroundSocketPath(id: string, env?: NodeJS.ProcessEnv): string;
|
|
37
|
+
export declare function backgroundTokenPath(id: string, env?: NodeJS.ProcessEnv): string;
|
|
38
|
+
export declare function backgroundLogPath(id: string, env?: NodeJS.ProcessEnv): string;
|
|
39
|
+
/** The state file's content, undefined when there is none or it is not one. */
|
|
40
|
+
export declare function readBackgroundState(id: string, env?: NodeJS.ProcessEnv): BackgroundState | undefined;
|
|
41
|
+
/**
|
|
42
|
+
* True while the state's process runs and, when the process table can be read, is a background
|
|
43
|
+
* server (a pid the system gave to another program after a kill is not one).
|
|
44
|
+
*/
|
|
45
|
+
export declare function backgroundAlive(state: BackgroundState): boolean;
|
|
46
|
+
/** Removes what a background server that is gone left behind (state, socket, token). */
|
|
47
|
+
export declare function removeBackgroundFiles(id: string, env?: NodeJS.ProcessEnv): void;
|
|
48
|
+
/** The running background server of the identity, undefined when none runs (a stale state is removed). */
|
|
49
|
+
export declare function liveBackground(id: string, env?: NodeJS.ProcessEnv): BackgroundState | undefined;
|
|
50
|
+
/**
|
|
51
|
+
* Throws when another process runs the identity's background server: called before a server
|
|
52
|
+
* launches the identity's browser. The background server itself passes.
|
|
53
|
+
*/
|
|
54
|
+
export declare function refuseWhileBackground(identity: IdentityRef): void;
|