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
@@ -0,0 +1,143 @@
1
+ /**
2
+ * The live view page: one HTML document with its style and script inline, allowed by a nonce
3
+ * in the Content-Security-Policy. It reads the server's events (`/events`: the state and the
4
+ * frames of the tab it shows), and posts Pause, Resume, the tab to show and, while the agent is
5
+ * paused, the user's clicks, keys and scrolls. Text from pages (titles, URLs) only ever goes into
6
+ * `textContent`, never into HTML.
7
+ */
8
+ const STYLE = `
9
+ :root { color-scheme: light dark; --bg: #f6f6f4; --fg: #1c1c1a; --muted: #6b6b66; --line: #d9d9d4; --accent: #2b5fd9; --warn: #b4561a; }
10
+ @media (prefers-color-scheme: dark) { :root { --bg: #151514; --fg: #ecece8; --muted: #9a9a94; --line: #34342f; --accent: #7aa2ff; --warn: #f0a060; } }
11
+ * { box-sizing: border-box; }
12
+ body { margin: 0; font: 14px/1.4 system-ui, sans-serif; background: var(--bg); color: var(--fg); }
13
+ header { display: flex; flex-wrap: wrap; gap: 8px 12px; align-items: center; padding: 10px 16px; border-bottom: 1px solid var(--line); }
14
+ header strong { font-weight: 600; }
15
+ #status { color: var(--muted); flex: 1 1 200px; }
16
+ #status.paused { color: var(--warn); }
17
+ button { font: inherit; padding: 4px 12px; border: 1px solid var(--line); border-radius: 6px; background: transparent; color: var(--fg); cursor: pointer; }
18
+ button:disabled { opacity: .4; cursor: default; }
19
+ button.on { border-color: var(--accent); color: var(--accent); }
20
+ nav { display: flex; flex-wrap: wrap; gap: 6px; padding: 8px 16px; border-bottom: 1px solid var(--line); }
21
+ nav button { max-width: 280px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 13px; }
22
+ main { padding: 12px 16px; }
23
+ #notice { color: var(--warn); margin-bottom: 8px; min-height: 1.4em; }
24
+ #frame { display: block; max-width: 100%; height: auto; border: 1px solid var(--line); outline: none; }
25
+ #frame:focus { border-color: var(--accent); }
26
+ #frame:not([src]) { display: none; }
27
+ footer { padding: 0 16px 16px; color: var(--muted); font-size: 13px; }
28
+ `;
29
+ const SCRIPT = `
30
+ const $ = (id) => document.getElementById(id);
31
+ const frame = $("frame");
32
+ let state = null;
33
+ let size = { w: 0, h: 0 };
34
+ function note(text) { $("notice").textContent = text || ""; }
35
+ async function post(path, body) {
36
+ try {
37
+ const res = await fetch(path, { method: "POST", headers: { "content-type": "application/json", "x-turno-live": "1" }, body: JSON.stringify(body || {}) });
38
+ const data = await res.json();
39
+ if (data.error) note(data.error);
40
+ else if (data.identity) render(data);
41
+ } catch (error) { note(String(error)); }
42
+ }
43
+ function render(s) {
44
+ state = s;
45
+ $("id").textContent = s.identity;
46
+ const status = $("status");
47
+ status.className = s.paused ? "paused" : "";
48
+ status.textContent = s.paused
49
+ ? "Paused (" + s.paused.by + "). " + (s.waiting ? s.waiting + " agent call" + (s.waiting === 1 ? " is" : "s are") + " waiting. " : "") + (s.busy ? "A call that started before the pause is still running." : "You have the controls.")
50
+ : (s.busy ? "The agent is working." : "The agent is idle.") + (s.browser ? "" : " The browser is not running.");
51
+ $("pause").disabled = !!s.paused;
52
+ $("resume").disabled = !s.paused;
53
+ const tabs = $("tabs");
54
+ tabs.replaceChildren();
55
+ const follow = document.createElement("button");
56
+ follow.textContent = "Follow the agent";
57
+ follow.className = s.pinned ? "" : "on";
58
+ follow.onclick = () => post("/follow", { tab: null });
59
+ tabs.append(follow);
60
+ for (const t of s.tabs) {
61
+ const b = document.createElement("button");
62
+ b.textContent = (t.session ? "[" + t.session + "] " : "") + (t.title || t.url || "(blank)");
63
+ b.title = t.url;
64
+ b.className = t.id === s.showing ? "on" : "";
65
+ b.onclick = () => post("/follow", { tab: t.id });
66
+ tabs.append(b);
67
+ }
68
+ let why = "";
69
+ if (!s.view.available) why = s.view.reason;
70
+ else if (s.hidden) why = "Hidden: this page holds a vault or sensitive value. It shows again after the page navigates.";
71
+ else if (!s.browser) why = "Nothing to show until the agent opens the browser.";
72
+ if (why) frame.removeAttribute("src");
73
+ note(why);
74
+ $("help").textContent = s.view.available
75
+ ? (s.paused ? "Click, scroll and type on the picture to act on the page. Resume when you are done; the agent is told what changed." : "Pause to take the controls: the agent's next call waits until you resume (up to " + Math.round(s.wait / 1000) + " s per call).")
76
+ : "Pause and resume still work: the agent's next call waits until you resume.";
77
+ }
78
+ const events = new EventSource("/events");
79
+ events.addEventListener("state", (e) => render(JSON.parse(e.data)));
80
+ events.addEventListener("frame", (e) => {
81
+ const f = JSON.parse(e.data);
82
+ if (!state || !state.view.available || state.hidden) return;
83
+ size = { w: f.w, h: f.h };
84
+ frame.src = "data:image/jpeg;base64," + f.data;
85
+ });
86
+ events.onerror = () => { $("status").textContent = "Disconnected: the server stopped or restarted. Open the view again with turno browser live."; };
87
+ $("pause").onclick = () => post("/pause");
88
+ $("resume").onclick = () => post("/resume");
89
+ function point(e) {
90
+ const r = frame.getBoundingClientRect();
91
+ return { x: Math.round(((e.clientX - r.left) * size.w) / r.width), y: Math.round(((e.clientY - r.top) * size.h) / r.height) };
92
+ }
93
+ function canAct() {
94
+ if (state && state.paused) return true;
95
+ note("Pause first: your input goes to the page only while the agent waits.");
96
+ return false;
97
+ }
98
+ frame.addEventListener("click", (e) => { frame.focus(); if (canAct()) post("/input", { type: "click", ...point(e) }); });
99
+ frame.addEventListener("dblclick", (e) => { if (canAct()) post("/input", { type: "dblclick", ...point(e) }); });
100
+ let wheel = null;
101
+ frame.addEventListener("wheel", (e) => {
102
+ if (!state || !state.paused) return;
103
+ e.preventDefault();
104
+ if (wheel) { wheel.dx += e.deltaX; wheel.dy += e.deltaY; return; }
105
+ wheel = { type: "wheel", ...point(e), dx: e.deltaX, dy: e.deltaY };
106
+ setTimeout(() => { const w = wheel; wheel = null; post("/input", { ...w, dx: Math.round(w.dx), dy: Math.round(w.dy) }); }, 80);
107
+ }, { passive: false });
108
+ const KEYS = new Set(["Enter", "Backspace", "Tab", "Escape", "Delete", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Home", "End", "PageUp", "PageDown"]);
109
+ frame.addEventListener("keydown", (e) => {
110
+ if (!state || !state.paused || e.metaKey || e.ctrlKey || e.altKey) return;
111
+ if (e.key.length === 1) { e.preventDefault(); post("/input", { type: "text", text: e.key }); }
112
+ else if (KEYS.has(e.key)) { e.preventDefault(); post("/input", { type: "key", key: e.key }); }
113
+ });
114
+ `;
115
+ /** The page, with the nonce the response's Content-Security-Policy allows. */
116
+ export function livePage(nonce) {
117
+ return `<!doctype html>
118
+ <html lang="en">
119
+ <head>
120
+ <meta charset="utf-8">
121
+ <meta name="viewport" content="width=device-width, initial-scale=1">
122
+ <meta name="referrer" content="no-referrer">
123
+ <title>turno live view</title>
124
+ <style nonce="${nonce}">${STYLE}</style>
125
+ </head>
126
+ <body>
127
+ <header><strong>turno live</strong><span id="id"></span><span id="status">Connecting...</span><button id="pause" type="button">Pause</button><button id="resume" type="button" disabled>Resume</button></header>
128
+ <nav id="tabs" aria-label="Tabs"></nav>
129
+ <main><div id="notice" role="status"></div><img id="frame" alt="The agent's tab" tabindex="0"></main>
130
+ <footer id="help"></footer>
131
+ <script nonce="${nonce}">${SCRIPT}</script>
132
+ </body>
133
+ </html>
134
+ `;
135
+ }
136
+ /** What a browser without the view's cookie sees. */
137
+ export function deniedPage(identity) {
138
+ return `<!doctype html>
139
+ <html lang="en"><head><meta charset="utf-8"><title>turno live view</title></head>
140
+ <body><p>This live view needs a fresh link. Run <code>turno browser live ${identity}</code>: it opens one that works once.</p></body></html>
141
+ `;
142
+ }
143
+ //# sourceMappingURL=live-page.js.map
@@ -0,0 +1,173 @@
1
+ import type { BrowserContext, Page } from "patchright-core";
2
+ import type { IdentityRef } from "./engine.js";
3
+ import { type LivePolicy, PauseGate, type TabState } from "./live.js";
4
+ import type { Redactor, VaultGuard } from "./redact.js";
5
+ /**
6
+ * The live view server of one turno-browser-mcp process, when identity.json `live.enabled` or
7
+ * `--live` turns it on (off by default).
8
+ *
9
+ * - The view is served on 127.0.0.1 only, on a random port, and only to a browser that holds
10
+ * this process's cookie: a random token made at start, never written to disk or logged. A
11
+ * browser gets the cookie from a link `turno browser live <id>` opens, whose code works once
12
+ * and for two minutes. Every request must name the server by its loopback Host (DNS
13
+ * rebinding), and every POST must come from the view's own origin with its header.
14
+ * - `turno browser live|pause|resume` talk to the server over a Unix socket in a private
15
+ * folder (mode 700, socket 600): the file system is the access check there. Where to find
16
+ * both is in `<state>/browser/identities/<id>/live.json`, without any secret.
17
+ * - The picture is a CDP screencast of one tab (the one the agent used last, or the one the
18
+ * user picked), taken only while a view is open. A frame of a page that holds a vault or
19
+ * sensitive value (the vault guard: a `browser_login` fill, a password typed) is never sent;
20
+ * the view says the page is hidden until it navigates.
21
+ * - While the agent is paused, the user's clicks, keys and scrolls on the picture go to that
22
+ * tab through Playwright's mouse and keyboard. Never while an agent call runs, and never to a
23
+ * hidden page. Input is not logged anywhere.
24
+ */
25
+ /** The running browser, as the host gives it to the live server. */
26
+ export interface LiveBrowser {
27
+ context: BrowserContext;
28
+ engine: string;
29
+ /** Attach mode: only the agent's own tabs are listed, and nothing is brought to the front. */
30
+ userBrowser: boolean;
31
+ /** The session that holds a page (`"sharing": "tabs"`), for the tab list. */
32
+ owner?(page: Page): string | undefined;
33
+ /** The URL a page shows, or will load again when the tab governor parked it. */
34
+ urlOf?(page: Page): string;
35
+ /** The user takes over: hold the idle limit and the tab governor, save the trace. */
36
+ onPause?(): Promise<void>;
37
+ /** The user gave the browser back. */
38
+ onResume?(): void;
39
+ }
40
+ /** What `/state` returns: the view, the pause and the tabs, as the CLI and the page show them. */
41
+ export interface LiveStatus {
42
+ identity: string;
43
+ pid: number;
44
+ port: number;
45
+ started: string;
46
+ paused: {
47
+ since: string;
48
+ by: string;
49
+ } | null;
50
+ /** Agent calls waiting for the user. */
51
+ waiting: number;
52
+ /** Agent calls running now. */
53
+ busy: number;
54
+ /** How long one call waits for the user, in milliseconds. */
55
+ wait: number;
56
+ /** True when a browser runs. */
57
+ browser: boolean;
58
+ engine: string | null;
59
+ view: {
60
+ available: boolean;
61
+ reason?: string;
62
+ headless: boolean;
63
+ };
64
+ /** The tab the view shows, by id; null when none. */
65
+ showing: number | null;
66
+ /** True when the user picked the tab, false when the view follows the agent. */
67
+ pinned: boolean;
68
+ /** True when the shown tab holds a vault or sensitive value, so no frame of it is sent. */
69
+ hidden: boolean;
70
+ /** Viewers connected now. */
71
+ viewers: number;
72
+ tabs: {
73
+ id: number;
74
+ url: string;
75
+ title: string;
76
+ session?: string;
77
+ }[];
78
+ }
79
+ export interface LiveServerOptions {
80
+ identity: IdentityRef;
81
+ policy: LivePolicy;
82
+ guard: VaultGuard;
83
+ redactor: Redactor;
84
+ headless: boolean;
85
+ /** Why the engine shows no pixels; `engine` is the running one, undefined before a launch. */
86
+ viewRefusal(engine: string | undefined): string | undefined;
87
+ /** A line for stderr (the server's log); never a token or a code. */
88
+ log?(line: string): void;
89
+ }
90
+ export declare class LiveServer {
91
+ private readonly o;
92
+ readonly gate: PauseGate;
93
+ private browser;
94
+ /** The browser `onPause` was called for, so `onResume` goes to the same one. */
95
+ private heldBrowser;
96
+ private readonly lastBySession;
97
+ private last;
98
+ private pinned;
99
+ private busy;
100
+ private readonly ids;
101
+ private nextId;
102
+ private readonly viewers;
103
+ private cast;
104
+ private casting;
105
+ private hidden;
106
+ private readonly token;
107
+ private readonly codes;
108
+ private tcp;
109
+ private unix;
110
+ private port;
111
+ private socketDir;
112
+ private started;
113
+ private queued;
114
+ private heartbeat;
115
+ private closed;
116
+ private readonly onExit;
117
+ constructor(o: LiveServerOptions);
118
+ get paused(): boolean;
119
+ get waitMs(): number;
120
+ /** The control socket path (tests). */
121
+ get socket(): string | undefined;
122
+ private get cookieName();
123
+ private starting;
124
+ /** Listens on the socket and on 127.0.0.1, and writes live.json (once). */
125
+ start(): Promise<void>;
126
+ private listenAll;
127
+ private cleanupFiles;
128
+ close(): Promise<void>;
129
+ /** A browser launched; returns what to call when it goes away. */
130
+ bind(browser: LiveBrowser): () => void;
131
+ /** The page a call of `session` worked on; the view follows the latest one. */
132
+ follow(session: string, page: Page | undefined): void;
133
+ /** The page the last call of `session` worked on (it may have closed since). */
134
+ lastPage(session: string): Page | undefined;
135
+ /** An agent call starts; returns what to call when it ends. */
136
+ begin(): () => void;
137
+ /** A vault or sensitive value is about to go into `page`: the view stops showing it now. */
138
+ hide(page: Page | undefined): void;
139
+ /** The id the view and the note give a tab. */
140
+ idOf(page: Page): number;
141
+ /** The agent's pages: every page, or in attach mode only those the agent worked on. */
142
+ private pages;
143
+ private urlOf;
144
+ /** The tabs now, as the note compares them. */
145
+ tabStates(): Promise<TabState[]>;
146
+ /** Pauses the agent. `front`: bring the shown tab to the front of a headed window. */
147
+ pause(by: string, front?: boolean): Promise<boolean>;
148
+ resume(): boolean;
149
+ /** The tab the view shows: the one picked, else the agent's latest, else the first. */
150
+ private target;
151
+ private refusal;
152
+ status(): LiveStatus;
153
+ /** The status with tab titles (they need a round trip to each page). */
154
+ private fullStatus;
155
+ private pushState;
156
+ private broadcast;
157
+ /** Starts or moves the screencast to the tab the view should show, or stops it. */
158
+ private retarget;
159
+ private doRetarget;
160
+ private hostOk;
161
+ private originOk;
162
+ private cookieOk;
163
+ /** A one-time code for a link (socket only). */
164
+ private issueCode;
165
+ private takeCode;
166
+ private send;
167
+ private json;
168
+ private handle;
169
+ private events;
170
+ /** Why input from the view cannot go to the page now. */
171
+ private inputRefusal;
172
+ private input;
173
+ }