@phren/cli 0.3.71 → 0.3.73

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 (164) hide show
  1. package/dist/bridge/agent-hooks.js +11 -1
  2. package/dist/bridge/browser-env.d.ts +5 -0
  3. package/dist/bridge/browser-env.js +110 -0
  4. package/dist/bridge/browser-protocol.d.ts +120 -0
  5. package/dist/bridge/browser-protocol.js +70 -0
  6. package/dist/bridge/browser-recordings.d.ts +63 -0
  7. package/dist/bridge/browser-recordings.js +148 -0
  8. package/dist/bridge/browser-registry.d.ts +64 -0
  9. package/dist/bridge/browser-registry.js +262 -0
  10. package/dist/bridge/browser-routes.d.ts +4 -0
  11. package/dist/bridge/browser-routes.js +39 -0
  12. package/dist/bridge/browser-shim/phren-playwright.cjs +184 -0
  13. package/dist/bridge/browser-socket.d.ts +2 -0
  14. package/dist/bridge/browser-socket.js +10 -0
  15. package/dist/bridge/browser-stream.d.ts +3 -0
  16. package/dist/bridge/browser-stream.js +129 -0
  17. package/dist/bridge/browser-watch.d.ts +12 -0
  18. package/dist/bridge/browser-watch.js +83 -0
  19. package/dist/bridge/claude-account-setup.js +3 -1
  20. package/dist/bridge/claude-accounts.d.ts +5 -1
  21. package/dist/bridge/claude-accounts.js +36 -6
  22. package/dist/bridge/codex-servers.d.ts +2 -0
  23. package/dist/bridge/codex-servers.js +1 -1
  24. package/dist/bridge/command.js +24 -5
  25. package/dist/bridge/dispatch-clone.d.ts +33 -0
  26. package/dist/bridge/dispatch-clone.js +176 -0
  27. package/dist/bridge/dispatch-command.d.ts +14 -0
  28. package/dist/bridge/dispatch-command.js +98 -13
  29. package/dist/bridge/dispatch-idempotency.d.ts +85 -0
  30. package/dist/bridge/dispatch-idempotency.js +235 -0
  31. package/dist/bridge/dispatch-returns.d.ts +6 -0
  32. package/dist/bridge/dispatch-returns.js +131 -1
  33. package/dist/bridge/dispatch-wait.d.ts +32 -0
  34. package/dist/bridge/dispatch-wait.js +177 -0
  35. package/dist/bridge/dispatch.d.ts +78 -2
  36. package/dist/bridge/dispatch.js +841 -25
  37. package/dist/bridge/dream-schedule.d.ts +133 -0
  38. package/dist/bridge/dream-schedule.js +322 -0
  39. package/dist/bridge/fanouts.js +20 -3
  40. package/dist/bridge/files.d.ts +1 -1
  41. package/dist/bridge/git-credential.d.ts +44 -0
  42. package/dist/bridge/git-credential.js +113 -0
  43. package/dist/bridge/git-host-auth.d.ts +9 -1
  44. package/dist/bridge/git-host-auth.js +18 -5
  45. package/dist/bridge/git-host-gitboy.js +8 -1
  46. package/dist/bridge/git-hosts.d.ts +12 -1
  47. package/dist/bridge/git-publish.js +3 -2
  48. package/dist/bridge/herdr.d.ts +4 -0
  49. package/dist/bridge/herdr.js +44 -9
  50. package/dist/bridge/install.d.ts +1 -1
  51. package/dist/bridge/install.js +12 -4
  52. package/dist/bridge/launch-brief.d.ts +11 -0
  53. package/dist/bridge/launch-brief.js +22 -0
  54. package/dist/bridge/launch-worktree.d.ts +2 -0
  55. package/dist/bridge/launch-worktree.js +5 -1
  56. package/dist/bridge/pane-status.js +1 -1
  57. package/dist/bridge/protocol.d.ts +7 -0
  58. package/dist/bridge/schedule-watch.js +13 -2
  59. package/dist/bridge/server-launch.d.ts +2 -0
  60. package/dist/bridge/server-launch.js +251 -145
  61. package/dist/bridge/server-routes.d.ts +3 -0
  62. package/dist/bridge/server-routes.js +33 -17
  63. package/dist/bridge/server-stream.d.ts +4 -0
  64. package/dist/bridge/server-stream.js +24 -5
  65. package/dist/bridge/server.js +35 -4
  66. package/dist/bridge/session-move.d.ts +10 -4
  67. package/dist/bridge/session-move.js +65 -34
  68. package/dist/bridge/simulator-stream.d.ts +2 -0
  69. package/dist/bridge/simulator-stream.js +2 -0
  70. package/dist/bridge/status-line-fast.d.ts +9 -0
  71. package/dist/bridge/status-line-fast.js +56 -0
  72. package/dist/bridge/tab-activity.d.ts +2 -0
  73. package/dist/bridge/tab-activity.js +15 -2
  74. package/dist/bridge/task-routes.d.ts +20 -16
  75. package/dist/bridge/task-routes.js +1 -1
  76. package/dist/bridge/terminal-herdr.d.ts +5 -1
  77. package/dist/bridge/terminal-herdr.js +67 -2
  78. package/dist/bridge/terminal-tmux.d.ts +2 -0
  79. package/dist/bridge/terminal-tmux.js +29 -7
  80. package/dist/bridge/terminal.d.ts +5 -1
  81. package/dist/bridge/transcript-claude.js +192 -112
  82. package/dist/bridge/transcript-preview.d.ts +2 -1
  83. package/dist/bridge/transcript-preview.js +85 -3
  84. package/dist/bridge/transcripts.js +17 -11
  85. package/dist/bridge/turn-records.js +16 -4
  86. package/dist/bridge/usage.d.ts +7 -1
  87. package/dist/bridge/usage.js +47 -31
  88. package/dist/bridge/worker-close.d.ts +15 -0
  89. package/dist/bridge/worker-close.js +304 -3
  90. package/dist/bridge/worker-identity.d.ts +51 -0
  91. package/dist/bridge/worker-identity.js +289 -0
  92. package/dist/bridge/worker-reports.js +15 -3
  93. package/dist/bridge-hook.mjs +39990 -36152
  94. package/dist/capabilities/mcp.js +1 -1
  95. package/dist/cli/browser-hint.d.ts +2 -0
  96. package/dist/cli/browser-hint.js +21 -0
  97. package/dist/cli/config-dreaming.d.ts +7 -0
  98. package/dist/cli/config-dreaming.js +72 -0
  99. package/dist/cli/config.js +6 -0
  100. package/dist/cli/dream.d.ts +59 -0
  101. package/dist/cli/dream.js +315 -0
  102. package/dist/cli/hooks-context.d.ts +2 -2
  103. package/dist/cli/hooks-context.js +3 -3
  104. package/dist/cli/hooks.js +20 -11
  105. package/dist/cli/namespaces-tasks.js +14 -0
  106. package/dist/cli-registry.js +28 -3
  107. package/dist/config/dreaming.d.ts +82 -0
  108. package/dist/config/dreaming.js +195 -0
  109. package/dist/config/resolve.js +11 -0
  110. package/dist/config/schema.d.ts +4 -4
  111. package/dist/config/schema.js +157 -1
  112. package/dist/content/citation-freshness.js +6 -0
  113. package/dist/content/learning.d.ts +1 -0
  114. package/dist/content/learning.js +2 -0
  115. package/dist/data/access.d.ts +1 -1
  116. package/dist/data/access.js +3 -1
  117. package/dist/data/task-contract.d.ts +5 -4
  118. package/dist/data/tasks.d.ts +5 -0
  119. package/dist/data/tasks.js +28 -2
  120. package/dist/dream/apply.d.ts +69 -0
  121. package/dist/dream/apply.js +372 -0
  122. package/dist/dream/budget.d.ts +78 -0
  123. package/dist/dream/budget.js +180 -0
  124. package/dist/dream/collect.d.ts +86 -0
  125. package/dist/dream/collect.js +449 -0
  126. package/dist/dream/eval/dream-adapter.d.ts +16 -0
  127. package/dist/dream/eval/dream-adapter.js +21 -0
  128. package/dist/dream/eval/fixture.d.ts +53 -0
  129. package/dist/dream/eval/fixture.js +172 -0
  130. package/dist/dream/eval/index.d.ts +40 -0
  131. package/dist/dream/eval/index.js +78 -0
  132. package/dist/dream/eval/score.d.ts +34 -0
  133. package/dist/dream/eval/score.js +99 -0
  134. package/dist/dream/eval/scripted-model.d.ts +19 -0
  135. package/dist/dream/eval/scripted-model.js +70 -0
  136. package/dist/dream/pages.d.ts +68 -0
  137. package/dist/dream/pages.js +220 -0
  138. package/dist/dream/privacy.d.ts +3 -0
  139. package/dist/dream/privacy.js +18 -0
  140. package/dist/dream/prompt.d.ts +13 -0
  141. package/dist/dream/prompt.js +84 -0
  142. package/dist/dream/run.d.ts +98 -0
  143. package/dist/dream/run.js +317 -0
  144. package/dist/dream/types.d.ts +74 -0
  145. package/dist/dream/types.js +4 -0
  146. package/dist/finding/lifecycle.d.ts +2 -2
  147. package/dist/finding/lifecycle.js +5 -2
  148. package/dist/finding/versions.d.ts +4 -0
  149. package/dist/finding/versions.js +28 -0
  150. package/dist/index.js +1 -0
  151. package/dist/modules/registry.js +10 -8
  152. package/dist/project-config.d.ts +3 -0
  153. package/dist/task/merge-links.d.ts +38 -0
  154. package/dist/task/merge-links.js +45 -0
  155. package/dist/task/reconcile.d.ts +39 -0
  156. package/dist/task/reconcile.js +201 -0
  157. package/dist/task/report-links.d.ts +10 -0
  158. package/dist/task/report-links.js +47 -0
  159. package/dist/tools/config.js +46 -4
  160. package/dist/tools/dispatch.js +2 -1
  161. package/dist/tools/dream.d.ts +3 -0
  162. package/dist/tools/dream.js +123 -0
  163. package/dist/tools/tasks.js +4 -1
  164. package/package.json +1 -1
@@ -0,0 +1,262 @@
1
+ import { EventEmitter } from "node:events";
2
+ import * as fs from "node:fs/promises";
3
+ import { createServer, connect } from "node:net";
4
+ import path from "node:path";
5
+ import { BrowserMessageReader, browserWire } from "./browser-protocol.js";
6
+ import { browserSocketPath } from "./browser-socket.js";
7
+ import { BrowserRecordings } from "./browser-recordings.js";
8
+ const MAX_INPUT_BACKLOG = 1024 * 1024;
9
+ export class BrowserRegistry extends EventEmitter {
10
+ root;
11
+ browsers = new Map();
12
+ owners = new Map();
13
+ controls = new Map();
14
+ asks = new Map();
15
+ frames = new Map();
16
+ server;
17
+ sockets = new Set();
18
+ timer;
19
+ recordings;
20
+ constructor(root) {
21
+ super();
22
+ this.root = root;
23
+ this.recordings = new BrowserRecordings(path.join(root, "browser-recordings"));
24
+ }
25
+ list(now = Date.now()) {
26
+ for (const [id, b] of this.browsers)
27
+ if (b.endedAt !== null && now - b.endedAt > 3_600_000)
28
+ this.browsers.delete(id);
29
+ return [...this.browsers.values()].reverse().sort((a, b) => Number(b.live) - Number(a.live) || b.startedAt - a.startedAt);
30
+ }
31
+ get(id) { return this.browsers.get(id); }
32
+ last(browser, page) { return this.frames.get(`${browser}/${page}`); }
33
+ accept(owner, message) {
34
+ const { data } = message, id = data.browserId;
35
+ if (message.type === 1) {
36
+ if (this.browsers.has(id))
37
+ throw new Error("Duplicate browser");
38
+ this.recordings.start(message.data);
39
+ this.owners.set(id, owner);
40
+ this.browsers.set(id, { id, session: message.data.session, cwd: message.data.cwd, engine: "chromium", headless: message.data.headless, startedAt: Date.now(), endedAt: null, live: true, pages: [], control: { held: false, since: null }, help: null });
41
+ }
42
+ else {
43
+ const browser = this.browsers.get(id);
44
+ if (!browser?.live || this.owners.get(id) !== owner)
45
+ throw new Error("Unknown browser");
46
+ if (message.type === 2) {
47
+ const p = message.data;
48
+ let page = browser.pages.find(page => page.id === p.pageId);
49
+ if (page && !page.live)
50
+ throw new Error("Closed page");
51
+ if (!page) {
52
+ page = { id: p.pageId, url: p.url, title: p.title, width: p.width, height: p.height, live: true };
53
+ browser.pages.push(page);
54
+ }
55
+ Object.assign(page, { url: p.url, title: p.title, width: p.width, height: p.height });
56
+ this.recordings.page(p);
57
+ }
58
+ else if (message.type === 3) {
59
+ const p = browser.pages.find(p => p.id === message.data.pageId && p.live);
60
+ if (!p)
61
+ throw new Error("Unknown page");
62
+ p.width = message.data.width;
63
+ p.height = message.data.height;
64
+ this.frames.set(`${id}/${p.id}`, message.jpeg);
65
+ this.recordings.frame(message.data, message.jpeg);
66
+ this.emit("frame", id, p.id, message.jpeg);
67
+ return;
68
+ }
69
+ else if (message.data.pageId) {
70
+ const p = browser.pages.find(p => p.id === message.data.pageId);
71
+ if (!p)
72
+ throw new Error("Unknown page");
73
+ p.live = false;
74
+ this.frames.delete(`${id}/${p.id}`);
75
+ }
76
+ else {
77
+ this.end(id);
78
+ return;
79
+ }
80
+ }
81
+ this.emit("change", id);
82
+ }
83
+ controlState(id, connection) {
84
+ const control = this.controls.get(id);
85
+ return { type: "control", holder: control ? control.holder === connection ? "you" : "other" : null, help: this.get(id)?.help ?? null };
86
+ }
87
+ take(id, holder) {
88
+ const browser = this.get(id);
89
+ if (!browser?.live)
90
+ return;
91
+ const ask = this.asks.get(id);
92
+ if (ask)
93
+ ask.taken = true;
94
+ const previous = this.controls.get(id);
95
+ if (previous?.holder === holder)
96
+ return;
97
+ if (previous) {
98
+ clearTimeout(previous.timer);
99
+ this.handoff(id, "release", "stolen");
100
+ }
101
+ const now = Date.now();
102
+ const control = { holder, since: now, lastInput: now, timer: setTimeout(() => this.release(id, holder, "idle"), 120_000) };
103
+ control.timer.unref();
104
+ this.controls.set(id, control);
105
+ browser.control = { held: true, since: now };
106
+ this.handoff(id, "take");
107
+ this.controlChanged(id);
108
+ }
109
+ release(id, holder, reason) {
110
+ const control = this.controls.get(id);
111
+ if (!control || control.holder !== holder)
112
+ return;
113
+ clearTimeout(control.timer);
114
+ this.controls.delete(id);
115
+ const browser = this.get(id);
116
+ if (browser)
117
+ browser.control = { held: false, since: null };
118
+ this.handoff(id, "release", reason);
119
+ if (this.asks.get(id)?.taken)
120
+ this.finishAsk(id, "done");
121
+ this.controlChanged(id);
122
+ }
123
+ input(id, holder, input) {
124
+ const control = this.controls.get(id);
125
+ if (!control || control.holder !== holder)
126
+ return false;
127
+ if (!this.get(id)?.pages.some(p => p.id === input.pageId && p.live))
128
+ return true;
129
+ control.lastInput = Date.now();
130
+ clearTimeout(control.timer);
131
+ control.timer = setTimeout(() => this.release(id, holder, "idle"), 120_000);
132
+ control.timer.unref();
133
+ const socket = this.owners.get(id);
134
+ try {
135
+ if (socket?.write && !socket.destroyed && socket.writableLength < MAX_INPUT_BACKLOG)
136
+ socket.write(browserWire(0x10, input));
137
+ }
138
+ catch { /* A disconnected producer cannot take down the Hook. */ }
139
+ return true;
140
+ }
141
+ handoff(id, kind, reason) {
142
+ try {
143
+ this.recordings.handoff(id, kind, reason);
144
+ }
145
+ catch { /* Control survives recording failures. */ }
146
+ }
147
+ controlChanged(id) { this.emit("control", id); this.emit("change", id); }
148
+ finishAsk(id, outcome) {
149
+ const ask = this.asks.get(id);
150
+ if (!ask)
151
+ return;
152
+ clearTimeout(ask.timer);
153
+ this.asks.delete(id);
154
+ const browser = this.get(id);
155
+ if (browser)
156
+ browser.help = null;
157
+ if (outcome && !ask.socket.destroyed)
158
+ ask.socket.end(browserWire(0x13, { outcome }));
159
+ this.controlChanged(id);
160
+ }
161
+ ask(socket, request) {
162
+ const live = this.list().filter(b => b.live);
163
+ const browser = request.browserId ? live.find(b => b.id === request.browserId) : live.find(b => request.session !== undefined && b.session === request.session) ?? live[0];
164
+ if (!browser) {
165
+ socket.end(browserWire(0x13, { outcome: "no-browser" }));
166
+ return;
167
+ }
168
+ this.finishAsk(browser.id, "timeout");
169
+ const timer = setTimeout(() => this.finishAsk(browser.id, "timeout"), (request.timeout ?? 900) * 1000);
170
+ timer.unref();
171
+ this.asks.set(browser.id, { socket, timer, taken: this.controls.has(browser.id) });
172
+ browser.help = { reason: request.reason, t: Date.now() };
173
+ socket.write(browserWire(0x12, { browserId: browser.id }));
174
+ this.handoff(browser.id, "help", request.reason);
175
+ this.controlChanged(browser.id);
176
+ }
177
+ disconnect(owner) { for (const [id, who] of this.owners)
178
+ if (who === owner)
179
+ this.end(id); }
180
+ end(id) {
181
+ const b = this.browsers.get(id);
182
+ if (!b?.live)
183
+ return;
184
+ // Settle help as ended before releasing control (which normally completes it).
185
+ this.finishAsk(id, "ended");
186
+ const control = this.controls.get(id);
187
+ if (control)
188
+ this.release(id, control.holder, "ended");
189
+ b.live = false;
190
+ b.endedAt = Date.now();
191
+ this.owners.delete(id);
192
+ for (const p of b.pages) {
193
+ p.live = false;
194
+ this.frames.delete(`${id}/${p.id}`);
195
+ }
196
+ try {
197
+ this.recordings.end(id);
198
+ }
199
+ catch { /* Preserve live lifecycle even if the disk failed. */ }
200
+ this.emit("change", id);
201
+ }
202
+ async start() {
203
+ this.recordings.recover();
204
+ this.recordings.retain();
205
+ const socketPath = browserSocketPath(this.root);
206
+ const old = process.platform === "win32" ? undefined : await fs.lstat(socketPath).catch(() => undefined);
207
+ if (old) {
208
+ if (!old.isSocket() || (process.getuid && old.uid !== process.getuid()))
209
+ throw new Error("Unexpected browser socket");
210
+ const live = await new Promise(resolve => { const s = connect(socketPath); s.once("connect", () => { s.destroy(); resolve(true); }); s.once("error", () => resolve(false)); s.setTimeout(500, () => { s.destroy(); resolve(true); }); });
211
+ if (live)
212
+ throw new Error("Browser socket already active");
213
+ await fs.unlink(socketPath);
214
+ }
215
+ this.server = createServer(socket => {
216
+ if (this.sockets.size >= 128) {
217
+ socket.destroy();
218
+ return;
219
+ }
220
+ this.sockets.add(socket);
221
+ const reader = new BrowserMessageReader();
222
+ let mode, asked = false;
223
+ socket.on("data", (chunk) => {
224
+ try {
225
+ for (const message of reader.push(chunk)) {
226
+ if (!mode)
227
+ mode = message.type === 5 ? "ask" : "browser";
228
+ if (mode === "ask") {
229
+ if (message.type !== 5 || asked)
230
+ throw new Error("Invalid ask connection");
231
+ asked = true;
232
+ this.ask(socket, message.data);
233
+ }
234
+ else if (message.type === 1 || message.type === 2 || message.type === 3 || message.type === 4)
235
+ this.accept(socket, message);
236
+ else
237
+ throw new Error("Invalid producer message");
238
+ }
239
+ }
240
+ catch {
241
+ socket.destroy();
242
+ }
243
+ });
244
+ socket.on("error", () => { });
245
+ socket.on("close", () => { this.sockets.delete(socket); for (const [id, ask] of this.asks)
246
+ if (ask.socket === socket)
247
+ this.finishAsk(id); this.disconnect(socket); });
248
+ });
249
+ await new Promise((resolve, reject) => { this.server.once("error", reject); this.server.listen(socketPath, resolve); });
250
+ if (process.platform !== "win32")
251
+ await fs.chmod(socketPath, 0o600);
252
+ this.timer = setInterval(() => { try {
253
+ this.recordings.retain();
254
+ this.list();
255
+ }
256
+ catch { /* disk unavailable */ } }, 3_600_000);
257
+ this.timer.unref();
258
+ }
259
+ close() { clearInterval(this.timer); for (const s of this.sockets)
260
+ s.destroy(); for (const id of this.owners.keys())
261
+ this.end(id); this.server?.close(); }
262
+ }
@@ -0,0 +1,4 @@
1
+ import type { ServerResponse } from "node:http";
2
+ import type { BrowserRegistry } from "./browser-registry.js";
3
+ /** Called only after the existing Hook route authorization. */
4
+ export declare function browserRoute(registry: BrowserRegistry | undefined, method: string, url: URL, response: ServerResponse): void;
@@ -0,0 +1,39 @@
1
+ import { BridgeError } from "./protocol.js";
2
+ import { browserId } from "./browser-recordings.js";
3
+ /** Called only after the existing Hook route authorization. */
4
+ export function browserRoute(registry, method, url, response) {
5
+ if (!registry)
6
+ throw new BridgeError(503, "Browser watching unavailable.");
7
+ let result;
8
+ const route = url.pathname;
9
+ if (method === "GET" && route === "/v1/browsers")
10
+ result = { browsers: registry.list() };
11
+ else if (method === "GET" && route === "/v1/browsers/recordings")
12
+ result = { recordings: registry.recordings.list() };
13
+ else {
14
+ const id = browserId(url.searchParams.get("id"));
15
+ if (method === "DELETE" && route === "/v1/browsers/recordings") {
16
+ registry.recordings.remove(id);
17
+ response.statusCode = 204;
18
+ response.end();
19
+ return;
20
+ }
21
+ if (method === "GET" && route === "/v1/browsers/recordings/index") {
22
+ const { meta, frames } = registry.recordings.index(id);
23
+ result = { meta, frames: frames.map(({ t, pageId, width, height }, n) => ({ n, t, pageId, width, height })) };
24
+ }
25
+ else if (method === "GET" && route === "/v1/browsers/recordings/frame") {
26
+ const n = url.searchParams.get("n");
27
+ if (n === null || !/^(0|[1-9][0-9]{0,9})$/.test(n))
28
+ throw new BridgeError(400, "Invalid frame number.");
29
+ const bytes = registry.recordings.frameAt(id, Number(n));
30
+ response.setHeader("Content-Type", "image/jpeg");
31
+ response.end(bytes);
32
+ return;
33
+ }
34
+ else
35
+ throw new BridgeError(404, "Browser route not found.");
36
+ }
37
+ response.setHeader("Content-Type", "application/json");
38
+ response.end(JSON.stringify(result));
39
+ }
@@ -0,0 +1,184 @@
1
+ 'use strict';
2
+ // This preload must remain optional, dependency-free, and invisible to its host.
3
+ const noop = async () => {};
4
+ module.exports.initPage = noop;
5
+ try {
6
+ const fs = require('node:fs');
7
+ const socketPath = process.env.PHREN_BROWSER_SOCKET;
8
+ if (process.env.PHREN_BROWSER_WATCH !== '0' && socketPath && (socketPath.startsWith('\\\\.\\pipe\\') || fs.existsSync(socketPath))) {
9
+ const Module = require('node:module');
10
+ const net = require('node:net');
11
+ const { randomUUID } = require('node:crypto');
12
+ const installed = Symbol.for('phren.playwright.preload');
13
+ if (!globalThis[installed]) {
14
+ const browsers = new WeakMap(), contexts = new WeakSet(), pages = new WeakSet(), wrapped = new WeakSet();
15
+ const safe = (fn) => (...args) => { try { Promise.resolve(fn(...args)).catch(() => {}); } catch {} };
16
+ const id = () => randomUUID();
17
+ function watchBrowser(browser, headless = false, playwright = '') {
18
+ if (!browser || browsers.has(browser)) return browsers.get(browser);
19
+ const state = { browserId: id(), socket: null, ended: false, ready: false, queued: [], inputs: new Map(), cleanup: new Set() };
20
+ browsers.set(browser, state);
21
+ const socket = net.createConnection(socketPath); state.socket = socket; socket.unref();
22
+ const stop = () => { if (state.ended) return; state.ended = true; for (const cleanup of state.cleanup) cleanup(); state.cleanup.clear(); socket.destroy(); };
23
+ state.stop = stop;
24
+ state.send = (type, data, jpeg) => {
25
+ try {
26
+ if (state.ended || socket.destroyed) return;
27
+ // Pages usually open before the socket connects: keep their announcements (not frames) until it does.
28
+ if (!state.ready) { if (type !== 3 && state.queued.length < 64) state.queued.push([type, data]); return; }
29
+ if (socket.writableLength > 4 * 1024 * 1024) { if (type !== 3) stop(); return; }
30
+ const json = Buffer.from(JSON.stringify({ browserId: state.browserId, ...data }));
31
+ const body = jpeg ? Buffer.concat([Buffer.from([type]), Buffer.alloc(4), json, jpeg]) : Buffer.concat([Buffer.from([type]), json]);
32
+ if (body.length > 4 * 1024 * 1024) return;
33
+ if (jpeg) body.writeUInt32BE(json.length, 1);
34
+ const head = Buffer.alloc(4); head.writeUInt32BE(body.length);
35
+ socket.write(Buffer.concat([head, body]));
36
+ } catch {}
37
+ };
38
+ // Bounded incremental reader: tolerate fragmented/coalesced frames and unknown types.
39
+ let incoming = Buffer.alloc(0);
40
+ socket.on('data', safe(chunk => {
41
+ while (chunk.length && !state.ended) {
42
+ const needed = incoming.length < 4 ? 4 : 4 + incoming.readUInt32BE(0);
43
+ const count = Math.min(chunk.length, needed - incoming.length);
44
+ incoming = Buffer.concat([incoming, chunk.subarray(0, count)]); chunk = chunk.subarray(count);
45
+ if (incoming.length < 4) continue;
46
+ const length = incoming.readUInt32BE(0);
47
+ if (length < 1 || length > 4 * 1024 * 1024) { stop(); return; }
48
+ if (incoming.length < length + 4) continue;
49
+ const body = incoming.subarray(4); incoming = Buffer.alloc(0);
50
+ if (body[0] !== 0x10) continue;
51
+ try {
52
+ const input = JSON.parse(body.subarray(1).toString('utf8'));
53
+ if (input.browserId === state.browserId) state.inputs.get(input.pageId)?.(input);
54
+ } catch {}
55
+ }
56
+ }));
57
+ socket.on('error', stop); socket.on('close', stop);
58
+ socket.on('connect', safe(async () => {
59
+ if (state.ended) return;
60
+ state.ready = true;
61
+ state.send(1, { v: 1, pid: process.pid, session: process.env.PHREN_BROWSER_SESSION || '', cwd: process.cwd(), engine: 'chromium', headless: !!headless, playwright });
62
+ const queued = state.queued; state.queued = [];
63
+ for (const [type, data] of queued) state.send(type, data);
64
+ }));
65
+ // Wrapped before the socket connects: browser.newPage() runs right after launch() and creates its context through this method.
66
+ for (const context of browser.contexts ? browser.contexts() : [browser]) watchContext(context, state);
67
+ if (typeof browser.newContext === 'function') {
68
+ const original = browser.newContext;
69
+ browser.newContext = async function (...args) { const context = await original.apply(this, args); safe(() => watchContext(context, state))(); return context; };
70
+ }
71
+ if (browser.on) browser.on(browser.contexts ? 'disconnected' : 'close', safe(() => { state.send(4, {}); stop(); }));
72
+ return state;
73
+ }
74
+ function watchContext(context, state) {
75
+ if (!context || contexts.has(context) || state.ended) return;
76
+ contexts.add(context);
77
+ const onPage = safe(page => watchPage(page, context, state));
78
+ context.on('page', onPage);
79
+ state.cleanup.add(() => { try { context.off('page', onPage); } catch {} });
80
+ for (const page of context.pages()) onPage(page);
81
+ }
82
+ async function watchPage(page, context, state) {
83
+ if (pages.has(page) || state.ended || typeof context.newCDPSession !== 'function') return;
84
+ pages.add(page);
85
+ const pageId = id(); let closed = false, timer, pending, last = 0, cdp, metadata, inputQueue = Promise.resolve(), queuedInputs = 0;
86
+ const send = async (method, params) => { try { if (!closed && !state.ended && cdp) await cdp.send(method, params); } catch {} };
87
+ const dimensions = () => { const v = page.viewportSize && page.viewportSize(); return { width: v?.width || 0, height: v?.height || 0 }; };
88
+ const keys = { Enter: ['Enter', 13], Backspace: ['Backspace', 8], Tab: ['Tab', 9], Escape: ['Escape', 27], ArrowUp: ['ArrowUp', 38], ArrowDown: ['ArrowDown', 40], ArrowLeft: ['ArrowLeft', 37], ArrowRight: ['ArrowRight', 39] };
89
+ const drive = async input => {
90
+ if (closed || state.ended || !cdp) return;
91
+ if (input.event === 'text') { if (typeof input.text === 'string' && input.text.length <= 1000) await send('Input.insertText', { text: input.text }); return; }
92
+ if (input.event === 'key') {
93
+ if (!Object.prototype.hasOwnProperty.call(keys, input.key)) return;
94
+ const [code, windowsVirtualKeyCode] = keys[input.key];
95
+ const key = { key: input.key, code, windowsVirtualKeyCode };
96
+ await send('Input.dispatchKeyEvent', { type: 'keyDown', ...key, ...(input.key === 'Enter' ? { text: '\r' } : {}) });
97
+ await send('Input.dispatchKeyEvent', { type: 'keyUp', ...key }); return;
98
+ }
99
+ if (!['click', 'wheel'].includes(input.event) || !Number.isFinite(input.x) || !Number.isFinite(input.y)) return;
100
+ const width = metadata?.deviceWidth, height = metadata?.deviceHeight;
101
+ if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return;
102
+ const point = { x: Math.max(0, Math.min(1, input.x)) * width, y: Math.max(0, Math.min(1, input.y)) * height };
103
+ if (input.event === 'wheel') {
104
+ if (!Number.isFinite(input.dx) || !Number.isFinite(input.dy) || !Number.isFinite(input.dx * width) || !Number.isFinite(input.dy * height)) return;
105
+ await send('Input.dispatchMouseEvent', { type: 'mouseWheel', ...point, deltaX: input.dx * width, deltaY: input.dy * height }); return;
106
+ }
107
+ await send('Input.dispatchMouseEvent', { type: 'mouseMoved', ...point });
108
+ await send('Input.dispatchMouseEvent', { type: 'mousePressed', ...point, button: 'left', clickCount: 1 });
109
+ await send('Input.dispatchMouseEvent', { type: 'mouseReleased', ...point, button: 'left', clickCount: 1 });
110
+ };
111
+ state.inputs.set(pageId, safe(input => {
112
+ if (queuedInputs >= 120) return;
113
+ queuedInputs++;
114
+ inputQueue = inputQueue.then(() => drive(input)).catch(() => {}).finally(() => { queuedInputs--; });
115
+ }));
116
+ let navigation = 0;
117
+ const announce = safe(async () => {
118
+ const n = ++navigation, url = page.url();
119
+ // Emit the page before CDP starts, even if title() is slow or the page is navigating.
120
+ state.send(2, { pageId, url, title: '', ...dimensions() });
121
+ const title = await page.title().catch(() => '');
122
+ if (!closed && n === navigation) state.send(2, { pageId, url, title, ...dimensions() });
123
+ });
124
+ const nav = safe(frame => { if (frame === page.mainFrame()) announce(); });
125
+ const flush = () => { timer = undefined; if (closed || state.ended || !pending) return; const event = pending; pending = undefined; last = Date.now(); state.send(3, { pageId, t: last, width: Math.round(event.metadata?.deviceWidth || dimensions().width), height: Math.round(event.metadata?.deviceHeight || dimensions().height) }, Buffer.from(event.data, 'base64')); };
126
+ const close = safe(() => {
127
+ if (closed) return; closed = true; state.inputs.delete(pageId); clearTimeout(timer); pending = undefined;
128
+ state.cleanup.delete(cleanup); state.send(4, { pageId }); page.off('framenavigated', nav); page.off('close', close); context.off('close', close);
129
+ if (cdp) { awaitStop(cdp); }
130
+ });
131
+ const cleanup = () => close(); state.cleanup.add(cleanup);
132
+ page.on('framenavigated', nav); page.on('close', close); context.on('close', close); announce();
133
+ // The 'page' event fires while newPage() is still setting the page up, and CDP then answers
134
+ // "Not attached to an active page"; retry briefly with a fresh session.
135
+ for (const delay of [0, 100, 250, 500, 1000, 2000]) {
136
+ if (delay) await new Promise(resolve => { const t = setTimeout(resolve, delay); t.unref?.(); });
137
+ if (closed || state.ended) return;
138
+ try {
139
+ cdp = await context.newCDPSession(page);
140
+ if (closed || state.ended) { awaitStop(cdp); return; }
141
+ cdp.on('Page.screencastFrame', safe(event => {
142
+ // CDP acknowledgements never wait for the Hook or phone.
143
+ Promise.resolve(cdp.send('Page.screencastFrameAck', { sessionId: event.sessionId })).catch(() => {});
144
+ if (closed || state.ended) return;
145
+ metadata = event.metadata; pending = event;
146
+ if (!timer) { const delay = Math.max(0, 100 - (Date.now() - last)); if (!delay) flush(); else { timer = setTimeout(safe(flush), delay); timer.unref?.(); } }
147
+ }));
148
+ await cdp.send('Page.startScreencast', { format: 'jpeg', quality: 60, maxWidth: 1280, maxHeight: 1280 });
149
+ return;
150
+ } catch { if (cdp) awaitStop(cdp); cdp = undefined; }
151
+ }
152
+ close();
153
+ }
154
+ function awaitStop(cdp) { try { Promise.resolve(cdp.send('Page.stopScreencast')).catch(() => {}); Promise.resolve(cdp.detach()).catch(() => {}); } catch {} }
155
+ function instrument(exports, parent) {
156
+ try {
157
+ const chromium = exports && exports.chromium;
158
+ if (!chromium || wrapped.has(chromium)) return;
159
+ wrapped.add(chromium);
160
+ let version = '';
161
+ try { version = load.call(Module, Module._resolveFilename('playwright-core/package.json', parent), parent).version || ''; } catch {}
162
+ for (const name of ['launch', 'launchPersistentContext', 'connectOverCDP']) {
163
+ const original = chromium[name]; if (typeof original !== 'function') continue;
164
+ chromium[name] = async function (...args) {
165
+ const result = await original.apply(this, args);
166
+ safe(() => watchBrowser(result, name === 'connectOverCDP' ? false : name === 'launchPersistentContext' ? args[1]?.headless !== false : args[0]?.headless !== false, version))();
167
+ return result;
168
+ };
169
+ }
170
+ } catch {}
171
+ }
172
+ const load = Module._load;
173
+ Module._load = function (...args) { const result = load.apply(this, args); try { if (/(?:playwright|playwright-core)/.test(String(args[0]))) instrument(result, args[1]); } catch {} return result; };
174
+ module.exports.initPage = async ({ page } = {}) => {
175
+ try {
176
+ if (!page) return;
177
+ const context = page.context(), browser = context.browser();
178
+ watchBrowser(browser || context);
179
+ } catch {}
180
+ };
181
+ globalThis[installed] = module.exports;
182
+ } else module.exports.initPage = globalThis[installed].initPage;
183
+ }
184
+ } catch { /* A preload must never break the program it observes. */ }
@@ -0,0 +1,2 @@
1
+ /** One endpoint per Hook root; Windows pipes live outside the filesystem. */
2
+ export declare function browserSocketPath(root?: string): string;
@@ -0,0 +1,10 @@
1
+ import { createHash } from "node:crypto";
2
+ import path from "node:path";
3
+ import { bridgeRoot } from "./protocol.js";
4
+ /** One endpoint per Hook root; Windows pipes live outside the filesystem. */
5
+ export function browserSocketPath(root = bridgeRoot()) {
6
+ if (process.platform !== "win32")
7
+ return path.join(root, "browser.sock");
8
+ const id = createHash("sha256").update(path.resolve(root).toLowerCase()).digest("hex");
9
+ return String.raw `\\.\pipe\phren-browser-${id}`;
10
+ }
@@ -0,0 +1,3 @@
1
+ import type { BrowserRegistry } from "./browser-registry.js";
2
+ import { type StreamClient } from "./simulator-stream.js";
3
+ export declare function streamBrowser(client: StreamClient, query: URLSearchParams, registry: BrowserRegistry): void;
@@ -0,0 +1,129 @@
1
+ import { browserId } from "./browser-recordings.js";
2
+ import { ACK_WINDOW, LatestFrame } from "./simulator-stream.js";
3
+ export function streamBrowser(client, query, registry) {
4
+ let id, explicit;
5
+ const ack = query.get("ack") === "1";
6
+ try {
7
+ id = browserId(query.get("browser"));
8
+ explicit = query.get("page");
9
+ if (explicit !== null)
10
+ browserId(explicit);
11
+ if (query.has("ack") && !["0", "1"].includes(query.get("ack")))
12
+ throw new Error("Invalid ack");
13
+ }
14
+ catch {
15
+ client.close(1008, "Invalid browser stream request");
16
+ return;
17
+ }
18
+ const browser = registry.get(id);
19
+ let page = explicit ? browser?.pages.find(p => p.id === explicit && p.live) : browser?.pages.filter(p => p.live).at(-1);
20
+ if (!browser?.live || (explicit && !page)) {
21
+ client.close(1008, "Browser or page unavailable");
22
+ return;
23
+ }
24
+ const latest = new LatestFrame((frame, done) => {
25
+ if (client.readyState !== 1) {
26
+ done(new Error("closed"));
27
+ return;
28
+ }
29
+ client.send(frame, { binary: true }, done);
30
+ }, { window: ack ? ACK_WINDOW : 1, acked: ack });
31
+ const connection = {};
32
+ let inputWindow = 0, inputCount = 0;
33
+ let closed = false;
34
+ const text = (value) => { if (client.readyState === 1)
35
+ client.send(JSON.stringify(value), { binary: false }); };
36
+ const end = () => { if (closed)
37
+ return; closed = true; latest.close(); registry.off("change", change); registry.off("frame", frame); registry.off("control", control); registry.release(id, connection, "disconnected"); };
38
+ const change = (changed) => {
39
+ if (changed !== id || closed)
40
+ return;
41
+ if (!browser.live) {
42
+ end();
43
+ client.close(1000, "Browser closed");
44
+ return;
45
+ }
46
+ const next = explicit ? browser.pages.find(p => p.id === explicit && p.live) : browser.pages.filter(p => p.live).at(-1);
47
+ if (!next) {
48
+ page = undefined;
49
+ latest.discardWaiting();
50
+ return;
51
+ }
52
+ if (next.id !== page?.id) {
53
+ // Keep the acknowledgement window across page switches; an ack may be for the old page.
54
+ latest.discardWaiting();
55
+ page = next;
56
+ text({ type: "page", page: next.id, url: next.url, title: next.title });
57
+ const last = registry.last(id, next.id);
58
+ if (last)
59
+ latest.offer(last);
60
+ }
61
+ else
62
+ text({ type: "page", page: next.id, url: next.url, title: next.title });
63
+ };
64
+ const control = (changed) => { if (changed === id && !closed)
65
+ text(registry.controlState(id, connection)); };
66
+ const frame = (browserId, pageId, jpeg) => { if (browserId === id && pageId === page?.id)
67
+ latest.offer(jpeg); };
68
+ registry.on("change", change);
69
+ registry.on("frame", frame);
70
+ registry.on("control", control);
71
+ client.once("close", end);
72
+ client.once("error", end);
73
+ client.on("message", (data, binary) => {
74
+ if (closed || binary || data.length > 16_384)
75
+ return;
76
+ try {
77
+ const message = JSON.parse(data.toString());
78
+ if (message.type === "ack") {
79
+ latest.ack();
80
+ return;
81
+ }
82
+ if (message.type === "control") {
83
+ if (message.action === "take")
84
+ registry.take(id, connection);
85
+ else if (message.action === "release")
86
+ registry.release(id, connection);
87
+ return;
88
+ }
89
+ if (message.type !== "input")
90
+ return;
91
+ if (registry.controlState(id, connection).holder !== "you") {
92
+ text({ type: "error", message: "Take control first" });
93
+ return;
94
+ }
95
+ const now = Date.now();
96
+ if (now - inputWindow >= 1000) {
97
+ inputWindow = now;
98
+ inputCount = 0;
99
+ }
100
+ if (++inputCount > 60 || !page)
101
+ return;
102
+ const finite = (n) => typeof n === "number" && Number.isFinite(n);
103
+ const clamp = (n) => Math.max(0, Math.min(1, n));
104
+ let event;
105
+ if (message.event === "click" || message.event === "wheel") {
106
+ if (!finite(message.x) || !finite(message.y))
107
+ return;
108
+ if (message.event === "wheel" && (!finite(message.dx) || !finite(message.dy)))
109
+ return;
110
+ event = { event: message.event, x: clamp(message.x), y: clamp(message.y), ...(message.event === "wheel" ? { dx: Math.max(-5, Math.min(5, message.dx)), dy: Math.max(-5, Math.min(5, message.dy)) } : {}) };
111
+ }
112
+ else if (message.event === "text" && typeof message.text === "string" && message.text.length <= 1000)
113
+ event = { event: "text", text: message.text };
114
+ else if (message.event === "key" && ["Enter", "Backspace", "Tab", "Escape", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"].includes(message.key))
115
+ event = { event: "key", key: message.key };
116
+ else
117
+ return;
118
+ registry.input(id, connection, { ...event, browserId: id, pageId: page.id });
119
+ }
120
+ catch { /* Ignore malformed phone messages. */ }
121
+ });
122
+ text({ type: "start", format: "jpeg", browser: id, page: page?.id ?? null, url: page?.url ?? "", title: page?.title ?? "", width: page?.width ?? 0, height: page?.height ?? 0, ack });
123
+ control(id);
124
+ if (page) {
125
+ const last = registry.last(id, page.id);
126
+ if (last)
127
+ latest.offer(last);
128
+ }
129
+ }
@@ -0,0 +1,12 @@
1
+ import type { BrowserWatch, Json } from "./protocol.js";
2
+ /** Successful Hook launches provide evidence without inspecting an environment. */
3
+ export declare function noteBrowserLaunch(pids: readonly number[], env: Record<string, string> | undefined, place?: {
4
+ server: string;
5
+ pane: Json;
6
+ }): void;
7
+ /** Never await process inspection on a session-list path. Only inspect the
8
+ * agent PID the caller already resolved; no ps subprocesses on macOS. */
9
+ export declare function browserWatch(pid: number | undefined): BrowserWatch;
10
+ /** A reported conversation can skip PID lookup. Reuse only this launch's
11
+ * terminal, harness and conversation; a replacement retires the evidence. */
12
+ export declare function paneBrowserWatch(server: string, pane: Json, session: string | undefined, pid?: number): BrowserWatch;