turno-browser 0.2.0 → 0.4.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 (121) hide show
  1. package/CHANGELOG.md +228 -0
  2. package/README.md +205 -16
  3. package/dist/act-model.d.ts +85 -0
  4. package/dist/act-model.js +116 -0
  5. package/dist/act.d.ts +37 -0
  6. package/dist/act.js +599 -0
  7. package/dist/api.d.ts +96 -0
  8. package/dist/api.js +88 -0
  9. package/dist/argv.d.ts +55 -3
  10. package/dist/argv.js +190 -10
  11. package/dist/batch.d.ts +19 -0
  12. package/dist/batch.js +148 -0
  13. package/dist/bench.d.ts +1 -1
  14. package/dist/bench.js +21 -5
  15. package/dist/bin/mcp.js +108 -12
  16. package/dist/captcha.d.ts +77 -0
  17. package/dist/captcha.js +333 -0
  18. package/dist/cdp-relay.d.ts +20 -0
  19. package/dist/cdp-relay.js +101 -0
  20. package/dist/chrome-features.d.ts +23 -0
  21. package/dist/chrome-features.js +44 -0
  22. package/dist/detectors.d.ts +11 -0
  23. package/dist/detectors.js +46 -4
  24. package/dist/diagnose.d.ts +45 -0
  25. package/dist/diagnose.js +326 -0
  26. package/dist/doctor.d.ts +85 -0
  27. package/dist/doctor.js +556 -0
  28. package/dist/engine-attach.d.ts +27 -0
  29. package/dist/engine-attach.js +165 -0
  30. package/dist/engine-camoufox.d.ts +32 -0
  31. package/dist/engine-camoufox.js +270 -0
  32. package/dist/engine-lightpanda.d.ts +72 -0
  33. package/dist/engine-lightpanda.js +292 -0
  34. package/dist/engine.d.ts +119 -0
  35. package/dist/engine.js +355 -0
  36. package/dist/flows.d.ts +127 -0
  37. package/dist/flows.js +294 -0
  38. package/dist/governor.d.ts +119 -0
  39. package/dist/governor.js +325 -0
  40. package/dist/health.d.ts +60 -0
  41. package/dist/health.js +86 -0
  42. package/dist/host.d.ts +95 -0
  43. package/dist/host.js +1181 -0
  44. package/dist/human-input.d.ts +84 -0
  45. package/dist/human-input.js +443 -0
  46. package/dist/humanize.d.ts +123 -0
  47. package/dist/humanize.js +241 -0
  48. package/dist/identities.d.ts +23 -10
  49. package/dist/identities.js +45 -37
  50. package/dist/idle-timer.d.ts +12 -0
  51. package/dist/idle-timer.js +25 -0
  52. package/dist/ids.d.ts +9 -0
  53. package/dist/ids.js +34 -0
  54. package/dist/index.d.ts +21 -6
  55. package/dist/index.js +19 -18
  56. package/dist/lifecycle.d.ts +99 -0
  57. package/dist/lifecycle.js +172 -0
  58. package/dist/live-client.d.ts +22 -0
  59. package/dist/live-client.js +93 -0
  60. package/dist/live-page.d.ts +11 -0
  61. package/dist/live-page.js +143 -0
  62. package/dist/live-server.d.ts +173 -0
  63. package/dist/live-server.js +640 -0
  64. package/dist/live.d.ts +120 -0
  65. package/dist/live.js +203 -0
  66. package/dist/login-tool.d.ts +45 -0
  67. package/dist/login-tool.js +233 -0
  68. package/dist/login.d.ts +8 -3
  69. package/dist/login.js +65 -26
  70. package/dist/network-chrome.d.ts +74 -0
  71. package/dist/network-chrome.js +178 -0
  72. package/dist/network.d.ts +125 -0
  73. package/dist/network.js +263 -0
  74. package/dist/opt-in-settings.d.ts +69 -0
  75. package/dist/opt-in-settings.js +151 -0
  76. package/dist/patchright.d.ts +4 -2
  77. package/dist/patchright.js +4 -2
  78. package/dist/recorder.d.ts +88 -0
  79. package/dist/recorder.js +538 -0
  80. package/dist/recordings.d.ts +116 -0
  81. package/dist/recordings.js +474 -0
  82. package/dist/redact.d.ts +34 -0
  83. package/dist/redact.js +135 -0
  84. package/dist/replay.d.ts +20 -0
  85. package/dist/replay.js +382 -0
  86. package/dist/reputation.d.ts +89 -0
  87. package/dist/reputation.js +203 -0
  88. package/dist/resources.d.ts +76 -0
  89. package/dist/resources.js +341 -0
  90. package/dist/runtime-lock.d.ts +59 -0
  91. package/dist/runtime-lock.js +131 -0
  92. package/dist/sealed.d.ts +8 -0
  93. package/dist/sealed.js +96 -0
  94. package/dist/session-export.d.ts +67 -0
  95. package/dist/session-export.js +194 -0
  96. package/dist/session.d.ts +20 -0
  97. package/dist/session.js +30 -0
  98. package/dist/settings.d.ts +246 -0
  99. package/dist/settings.js +530 -0
  100. package/dist/sharing.d.ts +96 -0
  101. package/dist/sharing.js +269 -0
  102. package/dist/snippet.d.ts +8 -0
  103. package/dist/snippet.js +22 -0
  104. package/dist/tab-locks.d.ts +63 -0
  105. package/dist/tab-locks.js +179 -0
  106. package/dist/tools.d.ts +111 -0
  107. package/dist/tools.js +59 -0
  108. package/dist/totp.d.ts +32 -0
  109. package/dist/totp.js +82 -0
  110. package/dist/tuning.d.ts +76 -0
  111. package/dist/tuning.js +69 -0
  112. package/dist/units.d.ts +8 -0
  113. package/dist/units.js +20 -0
  114. package/dist/upstream.d.ts +243 -0
  115. package/dist/upstream.js +46 -0
  116. package/dist/vault.d.ts +91 -0
  117. package/dist/vault.js +273 -0
  118. package/npm-shrinkwrap.json +1074 -3
  119. package/package.json +5 -4
  120. package/dist/paths.d.ts +0 -17
  121. package/dist/paths.js +0 -17
package/CHANGELOG.md CHANGED
@@ -1,5 +1,233 @@
1
1
  # turno-browser
2
2
 
3
+ ## 0.4.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 50facc9: Record and replay. `browser_record` saves an agent's actions on an identity as a named flow, each
8
+ element kept four ways (Playwright's locator, role and name, text, CSS path) and typed text as
9
+ parameters; passwords, one-time codes and values marked sensitive are never saved, and a vault
10
+ sign-in is kept as `browser_login` with the site name. `browser_replay` runs a flow with
11
+ parameters (`keychain:<item>` reads one from the secret store) and, when a step no longer fits,
12
+ stops with a report the agent can continue from; `browser_flows` lists them. Opt-in per identity
13
+ (`record` in identity.json, `turno browser record <id>`): every session as a flow, Playwright
14
+ traces and a screenshot per action under a size cap, with the trace stopped around sign-ins.
15
+ New commands `turno browser flows|replay|record|traces`; `traces --open` uses the trace viewer
16
+ bundled with patchright-core.
17
+ With `"sharing": "tabs"` a recording holds only the session that started it and replay runs in
18
+ that session's tabs; traces and screenshots are refused in attach mode and in read mode.
19
+ - e94a153: Natural language actions and captcha solving for browser identities, both not recommended and off by default.
20
+
21
+ - `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.
22
+ - `--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.
23
+ - 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.
24
+ - identity.json format 8 (`act`, `captcha`); turno-browser API 1.7, which turno-cli now requires.
25
+ - dcc2b97: Two opt-in engines for browser identities and servers, both off by default.
26
+
27
+ Read mode runs an identity (or one server) on Lightpanda instead of Chrome, for reading pages
28
+ with a fraction of the memory: `turno browser set <id> --engine lightpanda`, or
29
+ `turno-browser-mcp --engine lightpanda`. turno never downloads Lightpanda; it runs the
30
+ `lightpanda` on your PATH (or at `TURNO_LIGHTPANDA_PATH`), on a private Unix socket with
31
+ Lightpanda's telemetry off. The tools that work there run; the others (screenshots, dialogs,
32
+ drag and drop, uploads, `browser_login`) are refused with the reason before they reach the
33
+ browser. An identity in read mode keeps its own cookie jar, apart from its Chrome profile.
34
+
35
+ Attach mode connects to the Chrome you already have open, so the agent works in your signed-in
36
+ browser: `turno browser set <id> --attach auto` (after you turn on remote debugging at
37
+ chrome://inspect/#remote-debugging, Chrome 144 or newer), a Chrome user data folder, or a
38
+ loopback endpoint; `turno-browser-mcp --attach <target>` for one server. Chrome asks you to allow
39
+ each connection. turno works in a tab of its own, closes only the tabs it opened (on
40
+ `browser_close`, at the end of the session and at the idle limit) and never closes Chrome; the
41
+ tab governor leaves your tabs alone, and `browser_run_code_unsafe` is refused.
42
+
43
+ `turno browser doctor` gains an Engines section (Lightpanda found or how to install it, a
44
+ Lightpanda left running, which `--fix` stops) and checks each identity's attach target without
45
+ connecting. identity.json is now format 6 (`engine`, `attach`), and the turno-browser API is 1.5.
46
+
47
+ Read mode works with `"sharing": "tabs"`. Two pairs are refused with the reason, in identity.json
48
+ and from server flags: attach mode with `"sharing": "tabs"` (turno keeps one agent's tabs apart
49
+ from yours in your Chrome, not several sessions apart), and read mode with `humanize` (Lightpanda
50
+ lays out no page, so there is no pointer path to play). Attach mode works with `humanize`.
51
+ - 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.
52
+ - 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.
53
+ - c716051: Opt-in network and user agent settings, and a Camoufox engine, all off by default and not
54
+ recommended for your own accounts. identity.json format 11 adds `userAgent` and `proxy`, and the
55
+ `engine` key takes `"camoufox"` (also format 11); API_VERSION is 1.10 and turno-cli needs it.
56
+ `"userAgent": "coherent"` takes no typed value: a headless Chrome gets the user agent a headed one
57
+ of the same version sends, with its real client hints metadata, and a launch check refuses any
58
+ contradiction between the user agent, client hints, platform, headers, languages and time zone.
59
+ `proxy` sends the identity's traffic (sign-ins included) through an http, https or SOCKS proxy,
60
+ with its password only from the secret store, hidden from every tool result, and WebRTC limited
61
+ to the proxy. `--engine camoufox` runs an identity on an installed Camoufox through stock
62
+ playwright-core, with its own Firefox profile; turno never downloads it, and every stock tool but
63
+ `browser_run_code_unsafe` runs, as do natural language actions, `browser_login` and
64
+ `turno browser do`. Captcha solving is refused with it, and the live view shows no picture there
65
+ (pause and resume work). The act model's prompt and the live view's tab list hide the proxy
66
+ credentials. New flags on `turno identity set` (`--user-agent`,
67
+ `--proxy-server`, `--proxy-username`, `--proxy-password`, `--no-proxy`), doctor checks for
68
+ Camoufox and the proxy credentials, and fingerprint bench checks that compare headers and a
69
+ worker with the page.
70
+ - 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.
71
+ - 3bd7bc2: Follow-ups for browser identities.
72
+
73
+ A tool call no longer starts while the tab governor is still closing a popup or a parked tab, so
74
+ the call cannot fail with "Target page, context or browser has been closed". A Chrome that does
75
+ not stop after SIGKILL gets 5 seconds instead of 2 before turno calls it a survivor.
76
+
77
+ A server in read mode stops a Lightpanda that a killed server left running on the same cookie jar
78
+ when it starts, and removes its socket folder.
79
+
80
+ `turno browser doctor` warns when an identity that serves one session at a time
81
+ (`"sharing": "session"`) is served by an mcp.toml server with `exclusive = false`, and says how to
82
+ switch it to `"sharing": "tabs"`.
83
+
84
+ The tab lock wait (10 seconds) and the idle release (5 minutes) of `"sharing": "tabs"` can be set
85
+ per identity: `"tabLocks": { "wait": "30s", "release": "10m" }` in identity.json, or
86
+ `turno browser set <id> --tab-lock-wait 30s --tab-lock-release 10m`. identity.json is now format
87
+ 9 and the turno-browser API is 1.8.
88
+
89
+ The `light` humanize level moves the pointer on a visible arc (some 4 to 8% longer than the
90
+ straight line) instead of an almost straight path. With humanize on, `browser_login` clicks into
91
+ each field and types the value key by key; the keys go to Chrome only, never to a result, a
92
+ recording or a log.
93
+
94
+ When another element covers the target of a click, hover, type, select or drag before the call,
95
+ and still covers it 300 ms later, the error names that element at once instead of after the 5
96
+ second action timeout.
97
+
98
+ Chrome keeps its third-party storage partitioning on, as a person's Chrome does: Playwright turns
99
+ it off, and turno now passes Playwright's list of disabled features without it.
100
+
101
+ ## 0.3.0
102
+
103
+ ### Minor Changes
104
+
105
+ - e806948: `browser_batch`, useful action errors and the settle setting:
106
+
107
+ - New tool `browser_batch`: runs up to 20 stock browser actions in order in one call, checks
108
+ every action's arguments before running any, stops at the first failure, and returns one line
109
+ per action and one snapshot at the end only when `snapshot` is true.
110
+ - A `browser_click`, `browser_hover`, `browser_type`, `browser_select_option` or `browser_drag`
111
+ that times out because of the element now says which element covers the target (role, name,
112
+ a short selector and its buttons), or that the target is hidden (and by what), disabled,
113
+ read-only or gone, and suggests the next step. Tool names and schemas are unchanged.
114
+ - identity.json `settle` (like `"100ms"`) sets the wait after each action, Playwright's 500 ms
115
+ by default; `--timeout-settle` still wins. In a local benchmark of 8 calls it cut the wall
116
+ time of a form fill from about 1.8 s to 0.6 s.
117
+ - cc6b5b2: Browser identity module:
118
+
119
+ - `identity.json` next to each identity's profile keeps its time zone, languages, locale and
120
+ region fixed; Chrome gets them at every start (`--accept-lang`, `--lang`, and the time zone
121
+ when it differs from the machine's). `turno identity add browser:<id>` pins a new identity to
122
+ the current time zone and takes `--timezone`, `--locale`, `--languages`, `--region` and a
123
+ health check; `turno identity show` and `turno identity set` read and change it
124
+ (`turno browser show/set <id>` too). Without the file nothing changes.
125
+ - A runtime lock (`{ nodePid, chromePid, pgid, startedAt }`) while an identity's Chrome runs: a
126
+ second session gets a message naming the process and how to stop it instead of "Browser is
127
+ already in use".
128
+ - An optional session health check (a URL and a text or selector) marks a signed-out identity
129
+ NEEDS_AUTH; tool calls then fail with a message that asks for `turno browser login <id>`.
130
+ - Each captcha, "verify it's you" or block page an identity meets is logged per site (host name
131
+ only); `turno browser reputation [<id>] [--json]` shows counts and trend.
132
+ - `turno browser doctor [--fix] [--no-launch] [--json]`: Chrome and its version, a smoke launch,
133
+ the desktop session, and per identity its settings, lock, sign-in and recent challenges, with
134
+ a fix for each problem.
135
+ - mcpd: `stop_grace` per server in `mcp.toml`, the wait between closing stdin and SIGTERM;
136
+ 5 seconds by default for turno-browser-mcp, the SDK's 2 seconds for every other server.
137
+ - 7779c38: Opt-in resource blocking and resource cache per identity, both off by default:
138
+
139
+ - identity.json `block`: `trackers` (a built-in list of ad and analytics hosts), `types`
140
+ (`image`, `media`, `font`) and `patterns` (host names or URL globs). The page itself is never
141
+ blocked.
142
+ - identity.json `cache`: keeps images, fonts, stylesheets and scripts on disk for that identity
143
+ only (`maxSize`, default 100MB, least recently used first), following `Cache-Control`, never
144
+ storing a response with `Set-Cookie` or a request with `Authorization`. Misses still go out
145
+ through Chrome; hits are served from disk.
146
+ - 59309b5: `turno browser export <id> --out <file>` and `turno browser import <file> [--as <id>]` move an
147
+ identity's cookies, localStorage and IndexedDB as one file encrypted with a passphrase (scrypt
148
+ and AES-256-GCM), refused after its expiry and never holding vault credentials.
149
+ `"keychain": "system"` in identity.json makes Chrome encrypt an identity's cookies with the OS
150
+ keychain instead of Playwright's fixed mock key; the default is unchanged.
151
+ turno-browser's API is now 1.2, which this turno requires.
152
+ - 85d9bff: Tab governor:
153
+
154
+ - At most 8 pages stay open per session's browser; past that the least recently used one
155
+ closes (never the agent's current tab). Popups that open while no tool call runs, such as a
156
+ pop-under a page opens seconds after a click, are closed; a window the agent's own click opened
157
+ stays.
158
+ - A page unused for 5 minutes is parked on about:blank and stops running; the next call that uses
159
+ it loads its page again. After 15 minutes unused it closes. The next tool result lists what was
160
+ closed or parked, and tab lists mark parked tabs.
161
+ - identity.json (format 2) takes `tabs` (`max`, `popups`, `park`, `close`) and
162
+ `backgroundThrottling`; `turno-browser-mcp` takes `--max-tabs`, `--popups`, `--park-after`,
163
+ `--close-after` and `--background-throttling`, which win over the file.
164
+ - Background tabs keep running at full speed by default, as before: measured, dropping
165
+ Playwright's switches alone has no effect while focus emulation is on, and turning both off
166
+ stalls actions on a tab that is not in front. `backgroundThrottling` turns both off and brings
167
+ the agent's tab to the front before each call.
168
+ - 50dd77c: Credential vault for browser identities: `turno browser vault add|list|remove|submit`
169
+ stores a username, a password and an optional TOTP secret per site in the OS secret store, and
170
+ the new `browser_login` tool fills them into the site's sign-in page without the agent ever
171
+ seeing them. Results and errors are redacted, values are bound to the site's origins, and the
172
+ form is submitted only when the identity opts in. turno-browser's API is now 1.1, which this
173
+ turno requires.
174
+ - fa324c0: Cross-package contracts:
175
+
176
+ - turno-browser exports its public API as a typed `api` object with `API_VERSION` (1.0).
177
+ turno-cli checks it when it loads the package: a turno-browser that is too old (0.2 and older
178
+ have no `API_VERSION`) or too new stops `turno browser` and `turno identity browser:<id>`
179
+ with one line naming what to update, instead of failing later.
180
+ - mcpd sends every `tools/call`, from 2025-11-25 sessions and 2026-07-28 requests alike,
181
+ through one call middleware: the profile's tool filter, then the call log, then the session id.
182
+ Refusals and call log records are unchanged.
183
+ - Each relayed `tools/call` carries `_meta["io.turno/session"]`, an opaque id that is stable for
184
+ one agent session and different for every other. turno-browser-mcp hands it to its own tools
185
+ (`session` in their context); the Playwright tools are unaffected.
186
+ - 5b46749: Browser lifecycle:
187
+
188
+ - `turno-browser-mcp` passes a generated Playwright MCP `--config` that closes Chrome after 15
189
+ minutes without a tool call, headed too; the next call opens it again with the same profile.
190
+ `TURNO_BROWSER_IDLE` changes the limit (`"10m"`, `"0"` keeps Chrome open); `--idle-timeout`
191
+ and a `--config` of your own still win. Flags and tool names are unchanged.
192
+ - On start it closes a Chrome that an earlier, killed run left open on the same profile (only
193
+ a Chrome browser process for exactly that profile whose parent is gone), and on stdin close,
194
+ SIGTERM or SIGHUP it closes Chrome within about 2.5 seconds, forcefully if needed.
195
+ - mcpd stops a quiet `session` server under critical memory pressure even while its session
196
+ lives; the next call starts it again. `turno mcp top` counts the process groups a server's
197
+ children lead, so a browser's helpers always count.
198
+ - Docs: one recommendation for browsers, a `shared` server with `exclusive = true` per identity
199
+ (the block `turno identity add` prints), instead of `scope = "session"`.
200
+ - 0537fc1: `turno-browser-mcp` is now the MCP server host instead of a wrapper that ran the Playwright MCP
201
+ program bundled in `patchright-core`. It launches Chrome itself through one engine
202
+ module, serves stdio with the MCP SDK, and runs every stock tool through upstream's tool
203
+ backend, so the 25 tool names and input schemas, every flag, `TURNO_BROWSER_IDLE`, the idle
204
+ close, the orphan sweep and the bounded shutdown work as before. `--port` keeps upstream's HTTP
205
+ server. `initialize` now reports `turno-browser` and its version. A registry for turno's own
206
+ tools is in place (no new tools yet). `@modelcontextprotocol/sdk` is now a dependency.
207
+
208
+ ### Patch Changes
209
+
210
+ - 01d17db: The idle limit no longer closes Chrome in the middle of a tool call. It counted from the start of
211
+ the last call, so a call that took longer than `TURNO_BROWSER_IDLE` (a slow page, a busy machine)
212
+ failed with "Target page, context or browser has been closed". It now stops while a call runs and
213
+ counts from the end of the last one.
214
+ - 2948759: The package homepage is now https://turno.wimo.dev.
215
+ - cf29953: The example time zone in the message for an invalid identity.json and in the help of
216
+ `turno identity` is now `Europe/Madrid`.
217
+ - 5566437: Every package has a README that tells the same story as the site. turno-cli's follows the
218
+ order of turno.wimo.dev and lists what the browser gained; turno-browser's is organized around
219
+ what the package does (identities, the credential vault, session export and import, tab limits,
220
+ `browser_batch`, blocking and cache, health and doctor); turno-core's says what the shared
221
+ package is for; turno-fonts' shows the status line and how `turno ui install` uses the font.
222
+ Each links to its page on turno.wimo.dev and to the releases.
223
+ - a0bfce8: New package `turno-core` with what turno-cli and turno-browser share: turno's paths, the secret
224
+ store (macOS Keychain, Linux Secret Service) and the process helpers. Both packages
225
+ now depend on it instead of keeping their own copies; behavior is unchanged.
226
+ - Updated dependencies [2948759]
227
+ - Updated dependencies [5566437]
228
+ - Updated dependencies [a0bfce8]
229
+ - turno-core@0.1.0
230
+
3
231
  ## 0.2.0
4
232
 
5
233
  ### Minor Changes
package/README.md CHANGED
@@ -1,33 +1,222 @@
1
1
  # turno-browser
2
2
 
3
- An MCP server that lets a coding agent drive your installed Google Chrome with a persistent
4
- profile per identity: you sign into a site once by hand, and the agent works in that same
5
- signed-in browser afterwards. It is the Playwright MCP program, run on Patchright (a Playwright
6
- fork that drives Chrome without the automation flags Playwright adds).
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.
7
6
 
8
- It is a separate package from [turno](https://www.npmjs.com/package/turno-cli), not installed
9
- with it; turno works without it.
7
+ ![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)
10
8
 
11
9
  ```sh
12
10
  npm install --global turno-browser
13
- turno identity add browser:school # prints the mcp.toml entry for this identity
11
+ turno identity add browser:school # a new identity, and its mcp.toml entry
14
12
  turno identity login browser:school # sign in by hand once; cookies persist
15
13
  ```
16
14
 
17
- Or run it directly as an MCP server: `turno-browser-mcp --identity school`. It serves over
18
- stdio; `--port` or `--host` with `--identity` would serve a signed-in browser over HTTP, so it
19
- needs `--allow-http-identity` and then listens on 127.0.0.1 only.
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).
17
+
18
+ ## Why
19
+
20
+ - **Your agent opens a browser that is not signed in.** Here each identity is a real Chrome
21
+ profile that keeps its cookies, so the agent starts where you left off.
22
+ - **A browser left open eats the machine.** Tabs are capped, parked and closed, Chrome closes
23
+ when nobody is using it, and it closes with the agent that started it.
24
+ - **Passwords should not pass through a model.** A vault in the OS secret store fills a sign-in
25
+ form without the agent ever seeing the values.
26
+
27
+ ## What you get
28
+
29
+ | | |
30
+ |---|---|
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.
49
+
50
+ ## Identities
51
+
52
+ Each identity keeps, next to its profile, an `identity.json` with what should not change between
53
+ sessions: time zone, languages, locale, region, and an optional session health check.
54
+
55
+ ```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
59
+ ```
60
+
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.
72
+
73
+ ## Credential vault
74
+
75
+ An identity can keep a username, a password and a TOTP secret per site in the OS secret store
76
+ (macOS Keychain, Linux Secret Service), never in a file. The `browser_login` tool fills them
77
+ into that site's sign-in page:
78
+
79
+ ```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)
83
+ ```
84
+
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.
93
+
94
+ The threat model is in
95
+ [SECURITY.md](https://github.com/wimo-dev/turno/blob/main/SECURITY.md#the-credential-vault).
96
+
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
+ ## A browser that cleans up
114
+
115
+ | What | Default |
116
+ |---|---|
117
+ | Pages open per session's browser | at most 8; past that the least recently used closes, never the agent's current tab |
118
+ | Popups that open while no tool call runs | closed; a window the agent's own click opened stays |
119
+ | A page unused for 5 minutes | parked on `about:blank`; it loads again when the agent uses it |
120
+ | 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:
175
+
176
+ ```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
179
+ ```
180
+
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.
197
+
198
+ ## Run it directly
199
+
200
+ ```sh
201
+ turno-browser-mcp --identity school
202
+ turno-browser-mcp --identity school --max-tabs 4 --popups keep --park-after 2m --close-after 0
203
+ ```
204
+
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`.
20
208
 
21
- Defaults: headed, the installed Chrome channel, a persistent user data dir per identity, no
22
- injected init scripts. The reasons, and what these settings do and do not change, are in
23
- [ADR 0005](https://github.com/wimo-dev/turno/blob/main/docs/decisions/0005-stealth-browser-defaults.md).
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).
24
213
 
25
214
  ## Acceptable use
26
215
 
27
216
  Use it with your own accounts, on sites whose terms allow automated access by you, and at a
28
- human pace. Do not use it to get around access controls, paywalls, CAPTCHAs or rate limits, to
29
- scrape at scale, or to access accounts that are not yours. You are responsible for how you use
30
- it. The software is provided "as is", without warranty (Apache License 2.0).
217
+ human pace. Do not use it to get around access controls, paywalls or rate limits, to scrape at
218
+ scale, or to access accounts that are not yours. Captcha solving is off unless you turn it on, and
219
+ 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).
31
220
 
32
221
  ## License
33
222
 
@@ -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 {};