turno-browser 0.3.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 (94) hide show
  1. package/CHANGELOG.md +98 -0
  2. package/README.md +32 -3
  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 +29 -2
  8. package/dist/api.js +29 -2
  9. package/dist/argv.d.ts +16 -2
  10. package/dist/argv.js +100 -3
  11. package/dist/batch.d.ts +5 -0
  12. package/dist/batch.js +3 -3
  13. package/dist/bin/mcp.js +58 -1
  14. package/dist/captcha.d.ts +77 -0
  15. package/dist/captcha.js +333 -0
  16. package/dist/cdp-relay.d.ts +20 -0
  17. package/dist/cdp-relay.js +101 -0
  18. package/dist/chrome-features.d.ts +23 -0
  19. package/dist/chrome-features.js +44 -0
  20. package/dist/diagnose.d.ts +7 -0
  21. package/dist/diagnose.js +61 -6
  22. package/dist/doctor.d.ts +37 -3
  23. package/dist/doctor.js +230 -5
  24. package/dist/engine-attach.d.ts +27 -0
  25. package/dist/engine-attach.js +165 -0
  26. package/dist/engine-camoufox.d.ts +32 -0
  27. package/dist/engine-camoufox.js +270 -0
  28. package/dist/engine-lightpanda.d.ts +72 -0
  29. package/dist/engine-lightpanda.js +292 -0
  30. package/dist/engine.d.ts +63 -11
  31. package/dist/engine.js +104 -28
  32. package/dist/flows.d.ts +127 -0
  33. package/dist/flows.js +294 -0
  34. package/dist/governor.d.ts +42 -7
  35. package/dist/governor.js +82 -32
  36. package/dist/host.d.ts +17 -2
  37. package/dist/host.js +618 -41
  38. package/dist/human-input.d.ts +84 -0
  39. package/dist/human-input.js +443 -0
  40. package/dist/humanize.d.ts +123 -0
  41. package/dist/humanize.js +241 -0
  42. package/dist/identities.js +2 -0
  43. package/dist/idle-timer.d.ts +12 -0
  44. package/dist/idle-timer.js +25 -0
  45. package/dist/index.d.ts +8 -3
  46. package/dist/index.js +5 -1
  47. package/dist/lifecycle.d.ts +9 -1
  48. package/dist/lifecycle.js +9 -1
  49. package/dist/live-client.d.ts +22 -0
  50. package/dist/live-client.js +93 -0
  51. package/dist/live-page.d.ts +11 -0
  52. package/dist/live-page.js +143 -0
  53. package/dist/live-server.d.ts +173 -0
  54. package/dist/live-server.js +640 -0
  55. package/dist/live.d.ts +120 -0
  56. package/dist/live.js +203 -0
  57. package/dist/login-tool.d.ts +13 -0
  58. package/dist/login-tool.js +5 -1
  59. package/dist/login.d.ts +4 -1
  60. package/dist/login.js +11 -2
  61. package/dist/network-chrome.d.ts +74 -0
  62. package/dist/network-chrome.js +178 -0
  63. package/dist/network.d.ts +125 -0
  64. package/dist/network.js +263 -0
  65. package/dist/opt-in-settings.d.ts +69 -0
  66. package/dist/opt-in-settings.js +151 -0
  67. package/dist/recorder.d.ts +88 -0
  68. package/dist/recorder.js +538 -0
  69. package/dist/recordings.d.ts +116 -0
  70. package/dist/recordings.js +474 -0
  71. package/dist/redact.d.ts +7 -0
  72. package/dist/redact.js +18 -0
  73. package/dist/replay.d.ts +20 -0
  74. package/dist/replay.js +382 -0
  75. package/dist/reputation.d.ts +24 -2
  76. package/dist/reputation.js +63 -17
  77. package/dist/session-export.js +1 -1
  78. package/dist/session.d.ts +10 -2
  79. package/dist/session.js +10 -2
  80. package/dist/settings.d.ts +104 -2
  81. package/dist/settings.js +204 -6
  82. package/dist/sharing.d.ts +96 -0
  83. package/dist/sharing.js +269 -0
  84. package/dist/snippet.d.ts +8 -2
  85. package/dist/snippet.js +10 -4
  86. package/dist/tab-locks.d.ts +63 -0
  87. package/dist/tab-locks.js +179 -0
  88. package/dist/tools.d.ts +38 -0
  89. package/dist/tools.js +20 -1
  90. package/dist/tuning.d.ts +14 -0
  91. package/dist/tuning.js +9 -0
  92. package/dist/upstream.d.ts +11 -0
  93. package/npm-shrinkwrap.json +2 -2
  94. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,103 @@
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
+
3
101
  ## 0.3.0
4
102
 
5
103
  ### Minor Changes
package/README.md CHANGED
@@ -33,7 +33,11 @@ with it; turno works without it. The whole story is at [turno.wimo.dev](https://
33
33
  | [Session export and import](#move-a-session) | an identity's session as one encrypted file, for another machine |
34
34
  | [Tab limits](#a-browser-that-cleans-up) | at most 8 tabs, parked after 5 minutes unused, closed after 15 |
35
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 |
36
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 |
37
41
  | [Health and reputation](#know-when-something-is-wrong) | a signed-out identity says so, and each site's challenges are counted |
38
42
  | [`turno browser doctor`](#know-when-something-is-wrong) | checks Chrome and every identity, with a fix for each problem |
39
43
 
@@ -63,6 +67,8 @@ turno identity show browser:school
63
67
  already in use".
64
68
  - **Through the gateway.** `turno identity add` prints the `mcp.toml` block: a `shared`,
65
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.
66
72
 
67
73
  ## Credential vault
68
74
 
@@ -140,6 +146,29 @@ turno identity set browser:school --tabs-max 4 --tabs-popups keep --tabs-park 2m
140
146
  - **A shorter wait.** Playwright waits 500 ms after each action; `"settle": "100ms"` in
141
147
  `identity.json` (`turno identity set browser:school --settle 100ms`) shortens it.
142
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
+
143
172
  ## Lighter pages
144
173
 
145
174
  Both are off until an identity asks for them:
@@ -185,9 +214,9 @@ what each version added in [Releases](https://turno.wimo.dev/docs/releases).
185
214
  ## Acceptable use
186
215
 
187
216
  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).
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).
191
220
 
192
221
  ## License
193
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 {};
@@ -0,0 +1,116 @@
1
+ import { secretStore } from "turno-core/secrets";
2
+ /** A rough token count for budgets when a provider does not report one: 4 characters a token. */
3
+ export function estimateTokens(text) {
4
+ return Math.ceil(text.length / 4);
5
+ }
6
+ export class ModelError extends Error {
7
+ constructor(message) {
8
+ super(message);
9
+ this.name = "ModelError";
10
+ }
11
+ }
12
+ export function samplingModel(sample) {
13
+ return {
14
+ label: "MCP sampling (your client's model)",
15
+ async complete(request) {
16
+ const reply = await sample({
17
+ systemPrompt: request.system,
18
+ messages: request.messages.map((m) => ({ role: m.role, content: { type: "text", text: m.text } })),
19
+ maxTokens: request.maxTokens,
20
+ }, request.signal);
21
+ return { text: reply.text };
22
+ },
23
+ };
24
+ }
25
+ /** Longest provider error body kept in a message. */
26
+ const ERROR_CHARS = 300;
27
+ export function chatCompletionsModel(options) {
28
+ const url = `${options.endpoint.replace(/\/+$/, "")}/chat/completions`;
29
+ const host = new URL(options.endpoint).host;
30
+ const doFetch = options.fetch ?? fetch;
31
+ return {
32
+ label: `chat-completions ${options.model} at ${host}`,
33
+ async complete(request) {
34
+ const body = {
35
+ model: options.model,
36
+ messages: [
37
+ { role: "system", content: request.system },
38
+ ...request.messages.map((m) => ({ role: m.role, content: m.text })),
39
+ ],
40
+ max_tokens: request.maxTokens,
41
+ temperature: 0,
42
+ };
43
+ let res;
44
+ try {
45
+ res = await doFetch(url, {
46
+ method: "POST",
47
+ headers: {
48
+ "content-type": "application/json",
49
+ ...(options.key ? { authorization: `Bearer ${options.key}` } : {}),
50
+ },
51
+ body: JSON.stringify(body),
52
+ ...(request.signal ? { signal: request.signal } : {}),
53
+ });
54
+ }
55
+ catch (error) {
56
+ if (request.signal?.aborted)
57
+ throw new ModelError("the model did not answer in time");
58
+ throw new ModelError(`cannot reach ${host}: ${error.message}`);
59
+ }
60
+ const text = await res.text().catch(() => "");
61
+ if (!res.ok) {
62
+ const detail = text.replace(/\s+/g, " ").slice(0, ERROR_CHARS);
63
+ throw new ModelError(`${host} answered ${res.status}${detail ? `: ${detail}` : ""}`);
64
+ }
65
+ let parsed;
66
+ try {
67
+ parsed = JSON.parse(text);
68
+ }
69
+ catch {
70
+ throw new ModelError(`${host} did not answer with JSON`);
71
+ }
72
+ const content = parsed.choices?.[0]?.message?.content;
73
+ if (typeof content !== "string")
74
+ throw new ModelError(`${host} answered without a message`);
75
+ const input = parsed.usage?.prompt_tokens;
76
+ const output = parsed.usage?.completion_tokens;
77
+ return {
78
+ text: content,
79
+ ...(typeof input === "number" && typeof output === "number" ? { usage: { input, output } } : {}),
80
+ };
81
+ },
82
+ };
83
+ }
84
+ /**
85
+ * The model for one call: MCP sampling when the identity allows it and the client offers it,
86
+ * else the configured provider with its key from the secret store. The error says what to set
87
+ * when neither is there.
88
+ */
89
+ export async function resolveModel(options) {
90
+ const { settings, sample, redactor } = options;
91
+ if (settings.sampling !== false && sample)
92
+ return samplingModel(sample);
93
+ if (!settings.provider || !settings.endpoint || !settings.model) {
94
+ throw new ModelError(settings.sampling === false
95
+ ? `natural language actions of "${options.id}" have no provider (turno identity set browser:${options.id} --act-provider chat-completions --act-endpoint <url> --act-model <name>)`
96
+ : `this client does not offer MCP sampling and identity "${options.id}" names no provider: set one with turno identity set browser:${options.id} --act-provider chat-completions --act-endpoint <url> --act-model <name> [--act-key keychain:<item>]`);
97
+ }
98
+ let key;
99
+ if (settings.key) {
100
+ const item = settings.key.slice("keychain:".length);
101
+ const store = options.store ?? secretStore(options.env);
102
+ if (!store)
103
+ throw new ModelError(`act.key names ${settings.key}, but this machine has no secret store`);
104
+ key = await store.get(item).catch(() => undefined);
105
+ if (key === undefined)
106
+ throw new ModelError(`the secret store has no item "${item}" for act.key (store it with: turno secret set ${item})`);
107
+ redactor.add(key, "act model key");
108
+ }
109
+ return chatCompletionsModel({
110
+ endpoint: settings.endpoint,
111
+ model: settings.model,
112
+ ...(key ? { key } : {}),
113
+ ...(options.fetch ? { fetch: options.fetch } : {}),
114
+ });
115
+ }
116
+ //# sourceMappingURL=act-model.js.map
package/dist/act.d.ts ADDED
@@ -0,0 +1,37 @@
1
+ import type { StockAccess, TurnoTool } from "./tools.js";
2
+ /**
3
+ * Natural language actions, off by default (identity.json `act`): `browser_act` turns an
4
+ * instruction into stock tool calls, `browser_extract` reads data off the page, and
5
+ * `browser_observe` proposes the calls without running them. The model is the user's: MCP
6
+ * sampling when the client offers it, else the provider identity.json names (`act-model.ts`).
7
+ *
8
+ * What the model gets and what it can do is fixed here, not by the model:
9
+ *
10
+ * - The instruction and the current tab's accessibility snapshot, after the host's redactor:
11
+ * vault values never reach it, and before each snapshot the values of password, one-time
12
+ * code and card fields on the page join the redactor, so a sensitive field reads
13
+ * `[vault: sensitive value]`. An instruction that holds a redacted value is refused.
14
+ * - It answers with one stock call at a time, from `ACT_TOOLS` only: input on the current tab.
15
+ * It cannot navigate to a URL, open or close tabs, run script, upload files or call turno
16
+ * tools, so text on a page that tries to steer it can at worst click and type on that page.
17
+ * A call that would type into a password or one-time code field is refused.
18
+ * - Every call goes through the same path as the agent's own (`StockAccess.call`): the tab
19
+ * governor, human-like input, tab locks with `"sharing": "tabs"`, recordings. A recorded flow
20
+ * therefore holds the stock steps the model chose, never the instruction or the prompt.
21
+ * - Steps, tokens and time are bounded per call (`act.maxSteps`, `act.maxTokens`,
22
+ * `act.timeout`), and every step is listed in the result.
23
+ */
24
+ /** The stock tools a model may call: input on the current tab, nothing that leaves it. */
25
+ export declare const ACT_TOOLS: readonly string[];
26
+ /** The first JSON object in a reply, fences and chatter around it ignored. */
27
+ export declare function parseJsonReply(text: string): Record<string, unknown> | undefined;
28
+ /** A proposed call, checked against the allowed tools and the tool's own schema. */
29
+ export declare function checkCall(stock: Pick<StockAccess, "schemas" | "formatError">, tool: unknown, args: unknown): {
30
+ tool: string;
31
+ arguments: Record<string, unknown>;
32
+ } | {
33
+ error: string;
34
+ };
35
+ export declare function actTool(): TurnoTool;
36
+ export declare function extractTool(): TurnoTool;
37
+ export declare function observeTool(): TurnoTool;