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.
Files changed (70) hide show
  1. package/CHANGELOG.md +24 -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/context.d.ts +75 -0
  18. package/dist/cli/context.js +44 -0
  19. package/dist/cli/do-background.d.ts +27 -0
  20. package/dist/cli/do-background.js +212 -0
  21. package/dist/cli/do.d.ts +85 -0
  22. package/dist/cli/do.js +558 -0
  23. package/dist/cli/flows.d.ts +28 -0
  24. package/dist/cli/flows.js +303 -0
  25. package/dist/cli/identity.d.ts +37 -0
  26. package/dist/cli/identity.js +906 -0
  27. package/dist/cli/live.d.ts +7 -0
  28. package/dist/cli/live.js +99 -0
  29. package/dist/cli/main.d.ts +16 -0
  30. package/dist/cli/main.js +171 -0
  31. package/dist/cli/secret.d.ts +4 -0
  32. package/dist/cli/secret.js +151 -0
  33. package/dist/cli/session.d.ts +6 -0
  34. package/dist/cli/session.js +106 -0
  35. package/dist/cli/setup.d.ts +7 -0
  36. package/dist/cli/setup.js +180 -0
  37. package/dist/cli/vault.d.ts +5 -0
  38. package/dist/cli/vault.js +192 -0
  39. package/dist/client.d.ts +82 -0
  40. package/dist/client.js +303 -0
  41. package/dist/doctor.js +34 -1
  42. package/dist/engine-camoufox.js +5 -4
  43. package/dist/engine-lightpanda.js +3 -2
  44. package/dist/engine.js +2 -1
  45. package/dist/health.js +2 -1
  46. package/dist/host.d.ts +21 -0
  47. package/dist/host.js +75 -15
  48. package/dist/human-input.js +7 -2
  49. package/dist/identities.js +2 -1
  50. package/dist/index.d.ts +5 -1
  51. package/dist/index.js +2 -0
  52. package/dist/lifecycle.d.ts +2 -0
  53. package/dist/lifecycle.js +2 -1
  54. package/dist/live-client.js +8 -6
  55. package/dist/live-page.d.ts +0 -7
  56. package/dist/live-page.js +3 -2
  57. package/dist/live-server.js +6 -3
  58. package/dist/live.js +2 -1
  59. package/dist/login-tool.js +3 -2
  60. package/dist/login.js +2 -1
  61. package/dist/names.d.ts +28 -0
  62. package/dist/names.js +25 -0
  63. package/dist/network.d.ts +1 -1
  64. package/dist/network.js +4 -3
  65. package/dist/opt-in-settings.js +3 -2
  66. package/dist/replay.js +4 -3
  67. package/dist/runtime-lock.js +3 -2
  68. package/dist/vault.js +5 -4
  69. package/npm-shrinkwrap.json +6 -5
  70. 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 that is already the right you.** An MCP server that lets a coding agent drive your
4
- own Google Chrome, with one persistent profile per identity. You sign in to a site once, by hand,
5
- and the agent works in that same signed-in browser afterwards.
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
  ![Two accounts, each with its own Chrome profile, and a third identity an agent drives through the gateway](https://raw.githubusercontent.com/wimo-dev/turno/main/docs/assets/browser-identities.png)
8
11
 
9
12
  ```sh
10
13
  npm install --global turno-browser
11
- turno identity add browser:school # a new identity, and its mcp.toml entry
12
- turno identity login browser:school # sign in by hand once; cookies persist
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
- It is a separate package from [turno](https://www.npmjs.com/package/turno-cli), not installed
16
- with it; turno works without it. The whole story is at [turno.wimo.dev](https://turno.wimo.dev).
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
- | [Identities](#identities) | one Chrome profile per identity, with its time zone, languages and locale fixed |
32
- | [Credential vault](#credential-vault) | `browser_login` fills username, password and one-time code; the agent never sees them |
33
- | [Session export and import](#move-a-session) | an identity's session as one encrypted file, for another machine |
34
- | [Tab limits](#a-browser-that-cleans-up) | at most 8 tabs, parked after 5 minutes unused, closed after 15 |
35
- | [`browser_batch`](#faster-actions) | up to 20 actions in one call, and errors that say what is in the way |
36
- | [Record and replay](#record-and-replay) | save a flow once, replay it with parameters; recordings and traces, opt-in |
37
- | [Live view and take-over](https://turno.wimo.dev/docs/concepts/browser-identities#live-view-and-take-over) | opt-in: watch the agent's tab on 127.0.0.1, pause it, act, and resume; the agent is told what changed |
38
- | [Blocking and cache](#lighter-pages) | opt-in: block trackers, images, media or fonts; cache static resources on disk |
39
- | [Engines](https://turno.wimo.dev/docs/concepts/browser-identities#engines) | opt-in: read mode on Lightpanda for reading pages with little memory, attach to the Chrome you have open, or Camoufox (not recommended) |
40
- | [From the shell](https://turno.wimo.dev/docs/concepts/browser-identities#from-the-shell) | `turno browser do <id> open`, `snapshot`, `click`, `type`, `read`: the same browser and rules, as shell commands for coding agents |
41
- | [Health and reputation](#know-when-something-is-wrong) | a signed-out identity says so, and each site's challenges are counted |
42
- | [`turno browser doctor`](#know-when-something-is-wrong) | checks Chrome and every identity, with a fix for each problem |
43
-
44
- It serves the Playwright MCP tools and flags (`browser_navigate`, `browser_click`,
45
- `browser_snapshot` and the rest), run on Patchright, a Playwright fork that drives Chrome without
46
- the automation flags Playwright adds. Defaults: headed, the installed Chrome, a persistent
47
- profile per identity, no injected scripts. The browser a site sees is your own Chrome, signed in
48
- by you.
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 identity add browser:school --languages es-ES,es,en # pinned to this time zone
57
- turno identity set browser:school --health-url https://mail.example.com/ --health-text Inbox
58
- turno identity show browser:school
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
- - **Applied at every Chrome start.** Languages go to Chrome's own `--accept-lang` (so the
62
- Accept-Language header and `navigator.languages` match), the locale to `--lang`, and the time
63
- zone is emulated only when it differs from the machine's. An identity made at home keeps that
64
- zone on a trip.
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 browser vault add school mail --url https://mail.example.com/login --username alice --totp
81
- turno browser vault list school
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
- (https, or http on localhost), and only into frames of those origins.
87
- - **Never in a result.** Once a value was filled, every result and error passes through a
88
- redactor: snapshots, network requests and console messages show `[vault: ...]`.
89
- `browser_evaluate` and `browser_run_code_unsafe` are refused on a filled page until it
90
- navigates, and `browser_run_code_unsafe` is refused for identities with a vault.
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, headed too; the next call opens it with the same profile |
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 identity set browser:school --block-trackers true --block-types image,font --cache-max-size 100MB
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
- - **Blocking**: a short built-in list of ad and analytics hosts (`trackers`), resource types
182
- (`image`, `media`, `font`) and your own patterns (a host name or a URL with `*`). The page
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
- ## Run it directly
146
+ ## Move a session
199
147
 
200
148
  ```sh
201
- turno-browser-mcp --identity school
202
- turno-browser-mcp --identity school --max-tabs 4 --popups keep --park-after 2m --close-after 0
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
- It serves over stdio. `--port` or `--host` with `--identity` would serve a signed-in browser over
206
- HTTP, so it needs `--allow-http-identity` and then listens on 127.0.0.1 only. The server's flags
207
- win over `identity.json`.
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 (turno identity set browser:${options.id} --act-provider chat-completions --act-endpoint <url> --act-model <name>)`
96
- : `this client does not offer MCP sampling and identity "${options.id}" names no provider: set one with turno identity set browser:${options.id} --act-provider chat-completions --act-endpoint <url> --act-model <name> [--act-key keychain:<item>]`);
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: turno secret set ${item})`);
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 turno identity set browser:${identity.id} --act (MCP sampling) or --act-provider ..., then restarts the server`,
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: 10;
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: 10 });
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
- export const api = Object.freeze({
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;