turno-browser 0.3.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 (131) hide show
  1. package/CHANGELOG.md +122 -0
  2. package/README.md +95 -123
  3. package/dist/act-model.d.ts +85 -0
  4. package/dist/act-model.js +117 -0
  5. package/dist/act.d.ts +37 -0
  6. package/dist/act.js +600 -0
  7. package/dist/api.d.ts +90 -2
  8. package/dist/api.js +41 -4
  9. package/dist/argv.d.ts +16 -2
  10. package/dist/argv.js +100 -3
  11. package/dist/background-state.d.ts +54 -0
  12. package/dist/background-state.js +97 -0
  13. package/dist/background.d.ts +69 -0
  14. package/dist/background.js +458 -0
  15. package/dist/batch.d.ts +5 -0
  16. package/dist/batch.js +3 -3
  17. package/dist/bin/mcp.js +103 -6
  18. package/dist/captcha.d.ts +77 -0
  19. package/dist/captcha.js +334 -0
  20. package/dist/cdp-relay.d.ts +20 -0
  21. package/dist/cdp-relay.js +101 -0
  22. package/dist/chrome-features.d.ts +23 -0
  23. package/dist/chrome-features.js +44 -0
  24. package/dist/cli/background.d.ts +11 -0
  25. package/dist/cli/background.js +132 -0
  26. package/dist/cli/commands.d.ts +16 -0
  27. package/dist/cli/commands.js +515 -0
  28. package/dist/cli/context.d.ts +75 -0
  29. package/dist/cli/context.js +44 -0
  30. package/dist/cli/do-background.d.ts +27 -0
  31. package/dist/cli/do-background.js +212 -0
  32. package/dist/cli/do.d.ts +85 -0
  33. package/dist/cli/do.js +558 -0
  34. package/dist/cli/flows.d.ts +28 -0
  35. package/dist/cli/flows.js +303 -0
  36. package/dist/cli/identity.d.ts +37 -0
  37. package/dist/cli/identity.js +906 -0
  38. package/dist/cli/live.d.ts +7 -0
  39. package/dist/cli/live.js +99 -0
  40. package/dist/cli/main.d.ts +16 -0
  41. package/dist/cli/main.js +171 -0
  42. package/dist/cli/secret.d.ts +4 -0
  43. package/dist/cli/secret.js +151 -0
  44. package/dist/cli/session.d.ts +6 -0
  45. package/dist/cli/session.js +106 -0
  46. package/dist/cli/setup.d.ts +7 -0
  47. package/dist/cli/setup.js +180 -0
  48. package/dist/cli/vault.d.ts +5 -0
  49. package/dist/cli/vault.js +192 -0
  50. package/dist/client.d.ts +82 -0
  51. package/dist/client.js +303 -0
  52. package/dist/diagnose.d.ts +7 -0
  53. package/dist/diagnose.js +61 -6
  54. package/dist/doctor.d.ts +37 -3
  55. package/dist/doctor.js +264 -6
  56. package/dist/engine-attach.d.ts +27 -0
  57. package/dist/engine-attach.js +165 -0
  58. package/dist/engine-camoufox.d.ts +32 -0
  59. package/dist/engine-camoufox.js +271 -0
  60. package/dist/engine-lightpanda.d.ts +72 -0
  61. package/dist/engine-lightpanda.js +293 -0
  62. package/dist/engine.d.ts +63 -11
  63. package/dist/engine.js +106 -29
  64. package/dist/flows.d.ts +127 -0
  65. package/dist/flows.js +294 -0
  66. package/dist/governor.d.ts +42 -7
  67. package/dist/governor.js +82 -32
  68. package/dist/health.js +2 -1
  69. package/dist/host.d.ts +38 -2
  70. package/dist/host.js +689 -52
  71. package/dist/human-input.d.ts +84 -0
  72. package/dist/human-input.js +448 -0
  73. package/dist/humanize.d.ts +123 -0
  74. package/dist/humanize.js +241 -0
  75. package/dist/identities.js +4 -1
  76. package/dist/idle-timer.d.ts +12 -0
  77. package/dist/idle-timer.js +25 -0
  78. package/dist/index.d.ts +13 -4
  79. package/dist/index.js +7 -1
  80. package/dist/lifecycle.d.ts +11 -1
  81. package/dist/lifecycle.js +11 -2
  82. package/dist/live-client.d.ts +22 -0
  83. package/dist/live-client.js +95 -0
  84. package/dist/live-page.d.ts +4 -0
  85. package/dist/live-page.js +144 -0
  86. package/dist/live-server.d.ts +173 -0
  87. package/dist/live-server.js +643 -0
  88. package/dist/live.d.ts +120 -0
  89. package/dist/live.js +204 -0
  90. package/dist/login-tool.d.ts +13 -0
  91. package/dist/login-tool.js +8 -3
  92. package/dist/login.d.ts +4 -1
  93. package/dist/login.js +12 -2
  94. package/dist/names.d.ts +28 -0
  95. package/dist/names.js +25 -0
  96. package/dist/network-chrome.d.ts +74 -0
  97. package/dist/network-chrome.js +178 -0
  98. package/dist/network.d.ts +125 -0
  99. package/dist/network.js +264 -0
  100. package/dist/opt-in-settings.d.ts +69 -0
  101. package/dist/opt-in-settings.js +152 -0
  102. package/dist/recorder.d.ts +88 -0
  103. package/dist/recorder.js +538 -0
  104. package/dist/recordings.d.ts +116 -0
  105. package/dist/recordings.js +474 -0
  106. package/dist/redact.d.ts +7 -0
  107. package/dist/redact.js +18 -0
  108. package/dist/replay.d.ts +20 -0
  109. package/dist/replay.js +383 -0
  110. package/dist/reputation.d.ts +24 -2
  111. package/dist/reputation.js +63 -17
  112. package/dist/runtime-lock.js +3 -2
  113. package/dist/session-export.js +1 -1
  114. package/dist/session.d.ts +10 -2
  115. package/dist/session.js +10 -2
  116. package/dist/settings.d.ts +104 -2
  117. package/dist/settings.js +204 -6
  118. package/dist/sharing.d.ts +96 -0
  119. package/dist/sharing.js +269 -0
  120. package/dist/snippet.d.ts +8 -2
  121. package/dist/snippet.js +10 -4
  122. package/dist/tab-locks.d.ts +63 -0
  123. package/dist/tab-locks.js +179 -0
  124. package/dist/tools.d.ts +38 -0
  125. package/dist/tools.js +20 -1
  126. package/dist/tuning.d.ts +14 -0
  127. package/dist/tuning.js +9 -0
  128. package/dist/upstream.d.ts +11 -0
  129. package/dist/vault.js +5 -4
  130. package/npm-shrinkwrap.json +6 -5
  131. package/package.json +13 -7
package/CHANGELOG.md CHANGED
@@ -1,5 +1,127 @@
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
+
27
+ ## 0.4.0
28
+
29
+ ### Minor Changes
30
+
31
+ - 50facc9: Record and replay. `browser_record` saves an agent's actions on an identity as a named flow, each
32
+ element kept four ways (Playwright's locator, role and name, text, CSS path) and typed text as
33
+ parameters; passwords, one-time codes and values marked sensitive are never saved, and a vault
34
+ sign-in is kept as `browser_login` with the site name. `browser_replay` runs a flow with
35
+ parameters (`keychain:<item>` reads one from the secret store) and, when a step no longer fits,
36
+ stops with a report the agent can continue from; `browser_flows` lists them. Opt-in per identity
37
+ (`record` in identity.json, `turno browser record <id>`): every session as a flow, Playwright
38
+ traces and a screenshot per action under a size cap, with the trace stopped around sign-ins.
39
+ New commands `turno browser flows|replay|record|traces`; `traces --open` uses the trace viewer
40
+ bundled with patchright-core.
41
+ With `"sharing": "tabs"` a recording holds only the session that started it and replay runs in
42
+ that session's tabs; traces and screenshots are refused in attach mode and in read mode.
43
+ - e94a153: Natural language actions and captcha solving for browser identities, both not recommended and off by default.
44
+
45
+ - `turno identity set browser:<id> --act` lists `browser_act` (an instruction carried out one stock browser action at a time, every step shown), `browser_extract` (data off the page as JSON) and `browser_observe` (proposed calls, not run). The model is your client's, through MCP sampling, or a chat completions API you name with `--act-provider chat-completions --act-endpoint <url> --act-model <name> --act-key keychain:<item>`. The model sees the instruction and a snapshot of the current tab with vault values and password, one-time code and card fields hidden; it can only click, type, select, press keys, hover, drag, wait and go back on that tab; steps, tokens and time are capped per call (`--act-max-steps`, `--act-max-tokens`, `--act-timeout`). A recorded flow keeps the stock steps it chose, never the instruction or the page.
46
+ - `--captcha-provider task-api --captcha-endpoint <url> --captcha-key keychain:<item>` lists `browser_solve_captcha`, which sends a reCAPTCHA v2, hCaptcha or Turnstile widget and the page address to that solver service and puts the token into the page. The service sees the page, and solving a site's captchas by machine may break its terms: it is meant for your own accounts. Every attempt is a line in the identity's reputation log, and `turno browser reputation` shows a `solved` column once a solver answered. Read mode refuses it.
47
+ - Keys are only `keychain:` references read from the secret store at use time, refused as literal values without being echoed, and hidden from every result.
48
+ - identity.json format 8 (`act`, `captcha`); turno-browser API 1.7, which turno-cli now requires.
49
+ - dcc2b97: Two opt-in engines for browser identities and servers, both off by default.
50
+
51
+ Read mode runs an identity (or one server) on Lightpanda instead of Chrome, for reading pages
52
+ with a fraction of the memory: `turno browser set <id> --engine lightpanda`, or
53
+ `turno-browser-mcp --engine lightpanda`. turno never downloads Lightpanda; it runs the
54
+ `lightpanda` on your PATH (or at `TURNO_LIGHTPANDA_PATH`), on a private Unix socket with
55
+ Lightpanda's telemetry off. The tools that work there run; the others (screenshots, dialogs,
56
+ drag and drop, uploads, `browser_login`) are refused with the reason before they reach the
57
+ browser. An identity in read mode keeps its own cookie jar, apart from its Chrome profile.
58
+
59
+ Attach mode connects to the Chrome you already have open, so the agent works in your signed-in
60
+ browser: `turno browser set <id> --attach auto` (after you turn on remote debugging at
61
+ chrome://inspect/#remote-debugging, Chrome 144 or newer), a Chrome user data folder, or a
62
+ loopback endpoint; `turno-browser-mcp --attach <target>` for one server. Chrome asks you to allow
63
+ each connection. turno works in a tab of its own, closes only the tabs it opened (on
64
+ `browser_close`, at the end of the session and at the idle limit) and never closes Chrome; the
65
+ tab governor leaves your tabs alone, and `browser_run_code_unsafe` is refused.
66
+
67
+ `turno browser doctor` gains an Engines section (Lightpanda found or how to install it, a
68
+ Lightpanda left running, which `--fix` stops) and checks each identity's attach target without
69
+ connecting. identity.json is now format 6 (`engine`, `attach`), and the turno-browser API is 1.5.
70
+
71
+ Read mode works with `"sharing": "tabs"`. Two pairs are refused with the reason, in identity.json
72
+ and from server flags: attach mode with `"sharing": "tabs"` (turno keeps one agent's tabs apart
73
+ from yours in your Chrome, not several sessions apart), and read mode with `humanize` (Lightpanda
74
+ lays out no page, so there is no pointer path to play). Attach mode works with `humanize`.
75
+ - 4814fb8: Human-like input for browser identities, off by default. `turno identity set browser:<id> --humanize light|full|adaptive` (or `turno-browser-mcp --humanize <level>`, which wins) makes the stock click, hover, type, fill form, select, drag, press key and coordinate tools, and `browser_batch`, move the pointer along a curve from where it last was to a point inside the target, hold the button for tens of milliseconds and type short text key by key with per-key delays. `full` adds a move time that follows distance and target size, overshoot and correction, a reading pause on a new page, longer gaps between words and wheel scrolling; `adaptive` is `light`, and `full` on a site where the identity met a challenge page. Tool names, arguments and results do not change. The setting is the `humanize` key of identity.json (format 4, with an optional `seed`), and turno-cli needs turno-browser API 1.3 for it.
76
+ - 6698608: Live view and take-over for browser identities, off by default. `turno browser set <id> --live true` (or `turno-browser-mcp --live`) serves a view of the agent's tab on 127.0.0.1 with a per-server token; `turno browser live <id>` opens it through a link that works once and is never printed. `turno browser pause <id>` (or Pause in the view) holds the agent's next call, up to `live.wait` (2 minutes by default), while you act in the window or through the view; `turno browser resume <id>` lets it go, and each held call is told what changed (URL, title, tabs, your input) and a call that would act on stale refs is not run: it returns an error with a fresh snapshot. The natural language and captcha tools are held too, and a `browser_act` run stops at its next step. A page that holds a vault value or a password is never shown, including a sign-in typed key by key with humanize. Read mode and attach mode refuse the view and keep pause and resume. turno-browser API 1.9, identity.json format 10.
77
+ - c716051: Opt-in network and user agent settings, and a Camoufox engine, all off by default and not
78
+ recommended for your own accounts. identity.json format 11 adds `userAgent` and `proxy`, and the
79
+ `engine` key takes `"camoufox"` (also format 11); API_VERSION is 1.10 and turno-cli needs it.
80
+ `"userAgent": "coherent"` takes no typed value: a headless Chrome gets the user agent a headed one
81
+ of the same version sends, with its real client hints metadata, and a launch check refuses any
82
+ contradiction between the user agent, client hints, platform, headers, languages and time zone.
83
+ `proxy` sends the identity's traffic (sign-ins included) through an http, https or SOCKS proxy,
84
+ with its password only from the secret store, hidden from every tool result, and WebRTC limited
85
+ to the proxy. `--engine camoufox` runs an identity on an installed Camoufox through stock
86
+ playwright-core, with its own Firefox profile; turno never downloads it, and every stock tool but
87
+ `browser_run_code_unsafe` runs, as do natural language actions, `browser_login` and
88
+ `turno browser do`. Captcha solving is refused with it, and the live view shows no picture there
89
+ (pause and resume work). The act model's prompt and the live view's tab list hide the proxy
90
+ credentials. New flags on `turno identity set` (`--user-agent`,
91
+ `--proxy-server`, `--proxy-username`, `--proxy-password`, `--no-proxy`), doctor checks for
92
+ Camoufox and the proxy credentials, and fingerprint bench checks that compare headers and a
93
+ worker with the page.
94
+ - 4b9556f: Several agent sessions can now share one browser identity, each in its own tabs. Turn it on per identity with `"sharing": "tabs"` in identity.json (`turno identity set browser:<id> --sharing tabs`, or the server's `--sharing tabs`) and serve the identity with `exclusive = false` in mcp.toml; the default stays one session at a time. Each session gets its own current tab and holds the tabs it works on: another session's call on one of them waits up to 10 seconds and then fails with a message that names the holder. A session lets go of its tabs when it ends (mcpd now tells servers that declare the `io.turno/sessions` capability), when a tab closes, or after 5 minutes without a call. `browser_close` closes only the calling session's tabs, tab lists mark the tabs other sessions hold, and the tab governor's cap counts each session's tabs apart. `turno identity add browser:<id> --sharing tabs` prints the matching mcp.toml block. turno-browser's API version is now 1.4.
95
+ - 3bd7bc2: Follow-ups for browser identities.
96
+
97
+ A tool call no longer starts while the tab governor is still closing a popup or a parked tab, so
98
+ the call cannot fail with "Target page, context or browser has been closed". A Chrome that does
99
+ not stop after SIGKILL gets 5 seconds instead of 2 before turno calls it a survivor.
100
+
101
+ A server in read mode stops a Lightpanda that a killed server left running on the same cookie jar
102
+ when it starts, and removes its socket folder.
103
+
104
+ `turno browser doctor` warns when an identity that serves one session at a time
105
+ (`"sharing": "session"`) is served by an mcp.toml server with `exclusive = false`, and says how to
106
+ switch it to `"sharing": "tabs"`.
107
+
108
+ The tab lock wait (10 seconds) and the idle release (5 minutes) of `"sharing": "tabs"` can be set
109
+ per identity: `"tabLocks": { "wait": "30s", "release": "10m" }` in identity.json, or
110
+ `turno browser set <id> --tab-lock-wait 30s --tab-lock-release 10m`. identity.json is now format
111
+ 9 and the turno-browser API is 1.8.
112
+
113
+ The `light` humanize level moves the pointer on a visible arc (some 4 to 8% longer than the
114
+ straight line) instead of an almost straight path. With humanize on, `browser_login` clicks into
115
+ each field and types the value key by key; the keys go to Chrome only, never to a result, a
116
+ recording or a log.
117
+
118
+ When another element covers the target of a click, hover, type, select or drag before the call,
119
+ and still covers it 300 ms later, the error names that element at once instead of after the 5
120
+ second action timeout.
121
+
122
+ Chrome keeps its third-party storage partitioning on, as a person's Chrome does: Playwright turns
123
+ it off, and turno now passes Playwright's list of disabled features without it.
124
+
3
125
  ## 0.3.0
4
126
 
5
127
  ### 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,24 +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
+
29
44
  | | |
30
45
  |---|---|
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
- | [Blocking and cache](#lighter-pages) | opt-in: block trackers, images, media or fonts; cache static resources on disk |
37
- | [Health and reputation](#know-when-something-is-wrong) | a signed-out identity says so, and each site's challenges are counted |
38
- | [`turno browser doctor`](#know-when-something-is-wrong) | checks Chrome and every identity, with a fix for each problem |
39
-
40
- It serves the Playwright MCP tools and flags (`browser_navigate`, `browser_click`,
41
- `browser_snapshot` and the rest), run on Patchright, a Playwright fork that drives Chrome without
42
- the automation flags Playwright adds. Defaults: headed, the installed Chrome, a persistent
43
- profile per identity, no injected scripts. The browser a site sees is your own Chrome, signed in
44
- by you.
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
+
57
+ | | |
58
+ |---|---|
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.
45
91
 
46
92
  ## Identities
47
93
 
@@ -49,20 +95,15 @@ Each identity keeps, next to its profile, an `identity.json` with what should no
49
95
  sessions: time zone, languages, locale, region, and an optional session health check.
50
96
 
51
97
  ```sh
52
- turno identity add browser:school --languages es-ES,es,en # pinned to this time zone
53
- turno identity set browser:school --health-url https://mail.example.com/ --health-text Inbox
54
- 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
55
101
  ```
56
102
 
57
- - **Applied at every Chrome start.** Languages go to Chrome's own `--accept-lang` (so the
58
- Accept-Language header and `navigator.languages` match), the locale to `--lang`, and the time
59
- zone is emulated only when it differs from the machine's. An identity made at home keeps that
60
- zone on a trip.
61
- - **One Chrome per identity.** While a server drives an identity's Chrome it holds a lock; a
62
- second server gets a message naming that process and how to stop it, instead of "Browser is
63
- already in use".
64
- - **Through the gateway.** `turno identity add` prints the `mcp.toml` block: a `shared`,
65
- `exclusive` server, so one session uses the identity at a time and mcpd stops it when idle.
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.
66
107
 
67
108
  ## Credential vault
68
109
 
@@ -71,39 +112,20 @@ An identity can keep a username, a password and a TOTP secret per site in the OS
71
112
  into that site's sign-in page:
72
113
 
73
114
  ```sh
74
- turno browser vault add school mail --url https://mail.example.com/login --username alice --totp
75
- turno browser vault list school
76
- 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
77
117
  ```
78
118
 
79
- - **Bound to the site.** The tool fills only when the page is on an origin given with `--url`
80
- (https, or http on localhost), and only into frames of those origins.
81
- - **Never in a result.** Once a value was filled, every result and error passes through a
82
- redactor: snapshots, network requests and console messages show `[vault: ...]`.
83
- `browser_evaluate` and `browser_run_code_unsafe` are refused on a filled page until it
84
- navigates, and `browser_run_code_unsafe` is refused for identities with a vault.
85
- - **One-time codes.** TOTP follows RFC 6238 (SHA1, SHA256, SHA512, 6 to 8 digits), from a base32
86
- 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`.
87
125
 
88
126
  The threat model is in
89
127
  [SECURITY.md](https://github.com/wimo-dev/turno/blob/main/SECURITY.md#the-credential-vault).
90
128
 
91
- ## Move a session
92
-
93
- ```sh
94
- turno browser export school --out school.session --expires 2d # asks for a passphrase twice
95
- turno browser import school.session --as school-laptop
96
- ```
97
-
98
- The file holds the identity's cookies, localStorage and IndexedDB, encrypted with the passphrase
99
- (scrypt and AES-256-GCM), and is refused after its expiry (7 days by default, at most 90). It
100
- never holds vault credentials. Importing into an existing identity replaces its session and asks
101
- first.
102
-
103
- `"keychain": "system"` in `identity.json` makes Chrome encrypt the profile's cookies with the OS
104
- keychain's key instead of Playwright's fixed mock key, so a copy of the profile folder does not
105
- hand over the sessions. Changing it signs the identity out: export first and import after.
106
-
107
129
  ## A browser that cleans up
108
130
 
109
131
  | What | Default |
@@ -112,82 +134,32 @@ hand over the sessions. Changing it signs the identity out: export first and imp
112
134
  | Popups that open while no tool call runs | closed; a window the agent's own click opened stays |
113
135
  | A page unused for 5 minutes | parked on `about:blank`; it loads again when the agent uses it |
114
136
  | A page unused for 15 minutes | closed |
115
- | Chrome with no tool call for 15 minutes | closed, headed too; the next call opens it with the same profile |
116
-
117
- ```sh
118
- turno identity set browser:school --tabs-max 4 --tabs-popups keep --tabs-park 2m --tabs-close 0
119
- ```
120
-
121
- - What was closed or parked is listed at the end of the next tool result.
122
- - When the client closes stdin or the server gets SIGTERM, Chrome closes within about 2.5
123
- seconds, forcefully if it does not answer. A Chrome that an earlier, killed run left open on the
124
- same profile is closed when the identity starts again; one that another live process drives is
125
- left alone.
126
- - `TURNO_BROWSER_IDLE` changes the idle limit (`"10m"`, `"90s"`, `"0"` keeps Chrome open);
127
- `--idle-timeout <ms>` or a `--config` file of your own take precedence.
128
- - Through mcpd, stopping the server closes its stdin and waits 5 seconds before SIGTERM
129
- (`stop_grace`), so Chrome writes its profile on its own.
130
-
131
- ## Faster actions
132
-
133
- - **`browser_batch`** runs up to 20 browser actions in order in one call, checks every action's
134
- arguments before running any, stops at the first failure and returns one line per action,
135
- plus one snapshot at the end when asked. A form filled in one call costs the agent one round
136
- trip instead of one per field.
137
- - **Errors that help.** A click, hover, type, select or drag that times out because of the page
138
- says which element covers the target (a cookie banner, a dialog) with its buttons, or that the
139
- target is hidden, disabled, read-only or gone, and suggests the next step.
140
- - **A shorter wait.** Playwright waits 500 ms after each action; `"settle": "100ms"` in
141
- `identity.json` (`turno identity set browser:school --settle 100ms`) shortens it.
142
-
143
- ## Lighter pages
144
-
145
- 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 |
146
138
 
147
139
  ```sh
148
- turno identity set browser:school --block-trackers true --block-types image,font --cache-max-size 100MB
149
- 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
150
141
  ```
151
142
 
152
- - **Blocking**: a short built-in list of ad and analytics hosts (`trackers`), resource types
153
- (`image`, `media`, `font`) and your own patterns (a host name or a URL with `*`). The page
154
- itself is never blocked.
155
- - **Cache**: images, fonts, stylesheets and scripts on disk for that identity only, following
156
- `Cache-Control`, never a response with `Set-Cookie` or a request with `Authorization`.
157
-
158
- ## Know when something is wrong
159
-
160
- - **Signed out.** With a health check (a URL and a text or selector), each Chrome start opens
161
- the page and looks for it. When it is missing the identity is marked NEEDS_AUTH and tool calls
162
- fail with a message asking for `turno browser login <id>`.
163
- - **Reputation.** Every captcha, "verify it's you" or block page is one line in the identity's
164
- state folder, with the host name only (no path, no page content).
165
- `turno browser reputation [<id>]` shows counts per site and their trend.
166
- - **Doctor.** `turno browser doctor [--fix] [--json]` checks Chrome and its version, a test
167
- 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.
168
145
 
169
- ## Run it directly
146
+ ## Move a session
170
147
 
171
148
  ```sh
172
- turno-browser-mcp --identity school
173
- 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
174
151
  ```
175
152
 
176
- It serves over stdio. `--port` or `--host` with `--identity` would serve a signed-in browser over
177
- HTTP, so it needs `--allow-http-identity` and then listens on 127.0.0.1 only. The server's flags
178
- win over `identity.json`.
179
-
180
- More: [Browser identities](https://turno.wimo.dev/docs/concepts/browser-identities),
181
- [`turno browser`](https://turno.wimo.dev/docs/reference/cli/browser), the guide
182
- [Let an agent use my signed-in browser](https://turno.wimo.dev/docs/guides/signed-in-browser), and
183
- 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.
184
156
 
185
157
  ## Acceptable use
186
158
 
187
159
  Use it with your own accounts, on sites whose terms allow automated access by you, and at a
188
- human pace. Do not use it to get around access controls, paywalls, CAPTCHAs or rate limits, to
189
- scrape at scale, or to access accounts that are not yours. You are responsible for how you use
190
- it. The software is provided "as is", without warranty (Apache License 2.0).
160
+ human pace. Do not use it to get around access controls, paywalls or rate limits, to scrape at
161
+ scale, or to access accounts that are not yours. Captcha solving is off unless you turn it on, and
162
+ then it is for your own accounts only. You are responsible for how you use it. The software is provided "as is", without warranty (Apache License 2.0).
191
163
 
192
164
  ## License
193
165
 
@@ -0,0 +1,85 @@
1
+ import { type SecretStore } from "turno-core/secrets";
2
+ import type { ActSettings } from "./opt-in-settings.js";
3
+ import type { Redactor } from "./redact.js";
4
+ /**
5
+ * The model behind `browser_act`, `browser_extract` and `browser_observe`, kept small and
6
+ * provider-neutral: one interface and two adapters.
7
+ *
8
+ * - `samplingModel`: MCP sampling. The agent's own client answers with a model it chooses and
9
+ * the user approves there; turno holds no key. Used first when the client offers it.
10
+ * - `chatCompletionsModel`: an HTTP API in the widely implemented chat completions shape
11
+ * (`POST <endpoint>/chat/completions`), which hosted providers and local model servers alike
12
+ * speak. The user names the endpoint and the model; the key, when there is one, comes from
13
+ * the secret store through a `keychain:` reference and joins the redactor before the first
14
+ * request, so an error that echoes it never shows it.
15
+ *
16
+ * Neither adapter sees a tool argument: what they send is built by `act.ts` from the
17
+ * instruction and a redacted snapshot.
18
+ */
19
+ interface ModelMessage {
20
+ role: "user" | "assistant";
21
+ text: string;
22
+ }
23
+ export interface ModelRequest {
24
+ system: string;
25
+ messages: ModelMessage[];
26
+ /** Most tokens the reply may use. */
27
+ maxTokens: number;
28
+ signal?: AbortSignal;
29
+ }
30
+ interface ModelReply {
31
+ text: string;
32
+ /** Tokens the provider counted, when it says; otherwise the caller estimates. */
33
+ usage?: {
34
+ input: number;
35
+ output: number;
36
+ };
37
+ }
38
+ export interface ActModel {
39
+ /** How the result names it: "MCP sampling", "chat-completions example-model at models.example.com". */
40
+ readonly label: string;
41
+ complete(request: ModelRequest): Promise<ModelReply>;
42
+ }
43
+ /** What the host passes for MCP sampling: `server.createMessage`, routed to the calling session. */
44
+ export type Sampler = (request: {
45
+ systemPrompt: string;
46
+ messages: {
47
+ role: "user" | "assistant";
48
+ content: {
49
+ type: "text";
50
+ text: string;
51
+ };
52
+ }[];
53
+ maxTokens: number;
54
+ }, signal?: AbortSignal) => Promise<{
55
+ text: string;
56
+ model?: string;
57
+ }>;
58
+ /** A rough token count for budgets when a provider does not report one: 4 characters a token. */
59
+ export declare function estimateTokens(text: string): number;
60
+ export declare class ModelError extends Error {
61
+ constructor(message: string);
62
+ }
63
+ export declare function samplingModel(sample: Sampler): ActModel;
64
+ type Fetch = typeof fetch;
65
+ export declare function chatCompletionsModel(options: {
66
+ endpoint: string;
67
+ model: string;
68
+ key?: string;
69
+ fetch?: Fetch;
70
+ }): ActModel;
71
+ /**
72
+ * The model for one call: MCP sampling when the identity allows it and the client offers it,
73
+ * else the configured provider with its key from the secret store. The error says what to set
74
+ * when neither is there.
75
+ */
76
+ export declare function resolveModel(options: {
77
+ settings: ActSettings;
78
+ sample?: Sampler;
79
+ store?: SecretStore;
80
+ env: NodeJS.ProcessEnv;
81
+ redactor: Redactor;
82
+ fetch?: Fetch;
83
+ id: string;
84
+ }): Promise<ActModel>;
85
+ export {};
@@ -0,0 +1,117 @@
1
+ import { secretStore } from "turno-core/secrets";
2
+ import { names } from "./names.js";
3
+ /** A rough token count for budgets when a provider does not report one: 4 characters a token. */
4
+ export function estimateTokens(text) {
5
+ return Math.ceil(text.length / 4);
6
+ }
7
+ export class ModelError extends Error {
8
+ constructor(message) {
9
+ super(message);
10
+ this.name = "ModelError";
11
+ }
12
+ }
13
+ export function samplingModel(sample) {
14
+ return {
15
+ label: "MCP sampling (your client's model)",
16
+ async complete(request) {
17
+ const reply = await sample({
18
+ systemPrompt: request.system,
19
+ messages: request.messages.map((m) => ({ role: m.role, content: { type: "text", text: m.text } })),
20
+ maxTokens: request.maxTokens,
21
+ }, request.signal);
22
+ return { text: reply.text };
23
+ },
24
+ };
25
+ }
26
+ /** Longest provider error body kept in a message. */
27
+ const ERROR_CHARS = 300;
28
+ export function chatCompletionsModel(options) {
29
+ const url = `${options.endpoint.replace(/\/+$/, "")}/chat/completions`;
30
+ const host = new URL(options.endpoint).host;
31
+ const doFetch = options.fetch ?? fetch;
32
+ return {
33
+ label: `chat-completions ${options.model} at ${host}`,
34
+ async complete(request) {
35
+ const body = {
36
+ model: options.model,
37
+ messages: [
38
+ { role: "system", content: request.system },
39
+ ...request.messages.map((m) => ({ role: m.role, content: m.text })),
40
+ ],
41
+ max_tokens: request.maxTokens,
42
+ temperature: 0,
43
+ };
44
+ let res;
45
+ try {
46
+ res = await doFetch(url, {
47
+ method: "POST",
48
+ headers: {
49
+ "content-type": "application/json",
50
+ ...(options.key ? { authorization: `Bearer ${options.key}` } : {}),
51
+ },
52
+ body: JSON.stringify(body),
53
+ ...(request.signal ? { signal: request.signal } : {}),
54
+ });
55
+ }
56
+ catch (error) {
57
+ if (request.signal?.aborted)
58
+ throw new ModelError("the model did not answer in time");
59
+ throw new ModelError(`cannot reach ${host}: ${error.message}`);
60
+ }
61
+ const text = await res.text().catch(() => "");
62
+ if (!res.ok) {
63
+ const detail = text.replace(/\s+/g, " ").slice(0, ERROR_CHARS);
64
+ throw new ModelError(`${host} answered ${res.status}${detail ? `: ${detail}` : ""}`);
65
+ }
66
+ let parsed;
67
+ try {
68
+ parsed = JSON.parse(text);
69
+ }
70
+ catch {
71
+ throw new ModelError(`${host} did not answer with JSON`);
72
+ }
73
+ const content = parsed.choices?.[0]?.message?.content;
74
+ if (typeof content !== "string")
75
+ throw new ModelError(`${host} answered without a message`);
76
+ const input = parsed.usage?.prompt_tokens;
77
+ const output = parsed.usage?.completion_tokens;
78
+ return {
79
+ text: content,
80
+ ...(typeof input === "number" && typeof output === "number" ? { usage: { input, output } } : {}),
81
+ };
82
+ },
83
+ };
84
+ }
85
+ /**
86
+ * The model for one call: MCP sampling when the identity allows it and the client offers it,
87
+ * else the configured provider with its key from the secret store. The error says what to set
88
+ * when neither is there.
89
+ */
90
+ export async function resolveModel(options) {
91
+ const { settings, sample, redactor } = options;
92
+ if (settings.sampling !== false && sample)
93
+ return samplingModel(sample);
94
+ if (!settings.provider || !settings.endpoint || !settings.model) {
95
+ throw new ModelError(settings.sampling === false
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>]`);
98
+ }
99
+ let key;
100
+ if (settings.key) {
101
+ const item = settings.key.slice("keychain:".length);
102
+ const store = options.store ?? secretStore(options.env);
103
+ if (!store)
104
+ throw new ModelError(`act.key names ${settings.key}, but this machine has no secret store`);
105
+ key = await store.get(item).catch(() => undefined);
106
+ if (key === undefined)
107
+ throw new ModelError(`the secret store has no item "${item}" for act.key (store it with: ${names().secretSet(item)})`);
108
+ redactor.add(key, "act model key");
109
+ }
110
+ return chatCompletionsModel({
111
+ endpoint: settings.endpoint,
112
+ model: settings.model,
113
+ ...(key ? { key } : {}),
114
+ ...(options.fetch ? { fetch: options.fetch } : {}),
115
+ });
116
+ }
117
+ //# sourceMappingURL=act-model.js.map