@phren/cli 0.2.10 → 0.2.12

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 (52) hide show
  1. package/README.md +3 -0
  2. package/dist/bridge/activity.d.ts +8 -0
  3. package/dist/bridge/activity.js +43 -0
  4. package/dist/bridge/agent-hooks.d.ts +15 -0
  5. package/dist/bridge/agent-hooks.js +160 -0
  6. package/dist/bridge/command.d.ts +1 -0
  7. package/dist/bridge/command.js +42 -0
  8. package/dist/bridge/herdr.d.ts +12 -0
  9. package/dist/bridge/herdr.js +147 -0
  10. package/dist/bridge/hook-main.d.ts +1 -0
  11. package/dist/bridge/hook-main.js +7 -0
  12. package/dist/bridge/install.d.ts +15 -0
  13. package/dist/bridge/install.js +264 -0
  14. package/dist/bridge/projects.d.ts +10 -0
  15. package/dist/bridge/projects.js +89 -0
  16. package/dist/bridge/protocol.d.ts +35 -0
  17. package/dist/bridge/protocol.js +34 -0
  18. package/dist/bridge/server.d.ts +16 -0
  19. package/dist/bridge/server.js +291 -0
  20. package/dist/bridge/transcripts.d.ts +30 -0
  21. package/dist/bridge/transcripts.js +177 -0
  22. package/dist/bridge/transport.d.ts +4 -0
  23. package/dist/bridge/transport.js +64 -0
  24. package/dist/bridge/uploads.d.ts +2 -0
  25. package/dist/bridge/uploads.js +45 -0
  26. package/dist/bridge-hook.mjs +22571 -0
  27. package/dist/cli/config.js +27 -0
  28. package/dist/cli/namespaces-skills.js +2 -2
  29. package/dist/cli/session-git.d.ts +6 -0
  30. package/dist/cli/session-git.js +26 -0
  31. package/dist/cli/session-start.js +3 -3
  32. package/dist/cli/session-stop.js +54 -52
  33. package/dist/cli-registry.d.ts +1 -1
  34. package/dist/cli-registry.js +11 -0
  35. package/dist/generated/memory-ui-graph.browser.js +86 -86
  36. package/dist/governance/locks.d.ts +2 -0
  37. package/dist/governance/locks.js +45 -0
  38. package/dist/index.js +38 -2
  39. package/dist/init/preferences.d.ts +2 -0
  40. package/dist/link/refresh.d.ts +1 -0
  41. package/dist/link/refresh.js +47 -0
  42. package/dist/memory-ui-graph.runtime.js +86 -86
  43. package/dist/shared/index.d.ts +3 -1
  44. package/dist/shared/index.js +3 -2
  45. package/dist/skill/state.d.ts +10 -0
  46. package/dist/skill/state.js +41 -17
  47. package/dist/sync/pull.d.ts +29 -0
  48. package/dist/sync/pull.js +225 -0
  49. package/dist/tools/finding.js +4 -2
  50. package/dist/tools/skills.js +3 -3
  51. package/dist/ui/server.js +1 -1
  52. package/package.json +3 -1
@@ -0,0 +1,291 @@
1
+ import { createServer } from "node:http";
2
+ import { chmod, mkdir, lstat, unlink, writeFile, readFile } from "node:fs/promises";
3
+ import { hostname } from "node:os";
4
+ import path from "node:path";
5
+ import { randomUUID } from "node:crypto";
6
+ import { WebSocketServer, WebSocket } from "ws";
7
+ import { z } from "zod";
8
+ import { ActivityJournal } from "./activity.js";
9
+ import { panes, rpc, servers, snapshot, trustedDirectory, validateTarget, workspaceSnapshot } from "./herdr.js";
10
+ import { BridgeError, bridgeRoot, MAX_FRAME, object, objects, PROTOCOL, serverName, socketPath, targetFromURL, targetSchema } from "./protocol.js";
11
+ import { repositoryDiff, webServers } from "./projects.js";
12
+ import { historicalImage, TranscriptReader, transcriptPath } from "./transcripts.js";
13
+ import { AgentHooks } from "./agent-hooks.js";
14
+ import { saveUpload } from "./uploads.js";
15
+ export const capabilities = { transcript: true, progress: true, images: true, prompt: true, stop: true,
16
+ terminal: "ssh-pty", herdr: true, diff: true, webServers: true, activity: true,
17
+ approvals: true, questions: false, providers: ["codex", "claude", "copilot"] };
18
+ async function body(request) {
19
+ let size = 0;
20
+ const chunks = [];
21
+ for await (const chunk of request) {
22
+ size += chunk.length;
23
+ if (size > 11_500_000)
24
+ throw new BridgeError(413, "Request is too large.");
25
+ chunks.push(chunk);
26
+ }
27
+ return object(JSON.parse(Buffer.concat(chunks).toString() || "{}"));
28
+ }
29
+ function selectedServer(url) {
30
+ const mux = url.searchParams.get("mux");
31
+ if (mux && !mux.startsWith("herdr:"))
32
+ throw new BridgeError(400, "Select a Herdr server.");
33
+ return serverName.parse(url.searchParams.get("server") || mux?.slice(6) || "default");
34
+ }
35
+ function send(socket, frame) {
36
+ if (socket.readyState !== WebSocket.OPEN)
37
+ return;
38
+ const data = JSON.stringify(frame);
39
+ if (Buffer.byteLength(data) > MAX_FRAME || socket.bufferedAmount > MAX_FRAME) {
40
+ socket.close(1009, "Reconnect to resume the conversation");
41
+ return;
42
+ }
43
+ socket.send(data);
44
+ }
45
+ export async function serve(version) {
46
+ const root = bridgeRoot();
47
+ await mkdir(root, { recursive: true, mode: 0o700 });
48
+ await chmod(root, 0o700);
49
+ let computerID;
50
+ const identityFile = path.join(root, "computer-id");
51
+ try {
52
+ computerID = (await readFile(identityFile, "utf8")).trim();
53
+ }
54
+ catch {
55
+ computerID = randomUUID();
56
+ await writeFile(identityFile, computerID, { flag: "wx", mode: 0o600 });
57
+ }
58
+ const journal = new ActivityJournal();
59
+ const agentHooks = new AgentHooks();
60
+ const info = { product: "phren-hook", protocol: PROTOCOL, version, computer: { id: computerID, name: hostname() }, capabilities };
61
+ const old = await lstat(socketPath()).catch(() => null);
62
+ if (old) {
63
+ if (!old.isSocket() || (process.getuid && old.uid !== process.getuid()))
64
+ throw new Error("Refusing to replace an unexpected hook socket.");
65
+ // The service manager owns process lifetime. Only remove a stale socket.
66
+ const { connect } = await import("node:net");
67
+ const live = await new Promise(resolve => { const s = connect(socketPath()); s.on("connect", () => { s.destroy(); resolve(true); }); s.on("error", () => resolve(false)); });
68
+ if (live)
69
+ throw new Error("Phren Hook is already running.");
70
+ await unlink(socketPath());
71
+ }
72
+ const http = createServer(async (request, response) => {
73
+ response.setHeader("X-Phren-Protocol", String(PROTOCOL));
74
+ response.setHeader("Cache-Control", "no-store");
75
+ try {
76
+ const url = new URL(request.url || "/", "http://phren.local");
77
+ if (url.origin !== "http://phren.local")
78
+ throw new BridgeError(400, "Invalid request origin.");
79
+ let result;
80
+ if (request.method === "GET") {
81
+ switch (url.pathname) {
82
+ case "/v1/health":
83
+ result = info;
84
+ break;
85
+ case "/v1/muxes":
86
+ result = { muxes: await servers() };
87
+ break;
88
+ case "/v1/activity":
89
+ result = { events: await journal.recent() };
90
+ break;
91
+ case "/v1/web-servers":
92
+ result = { servers: await webServers() };
93
+ break;
94
+ case "/v1/workspaces": {
95
+ const server = selectedServer(url), s = await snapshot(server);
96
+ await journal.record(server, objects(s.panes));
97
+ result = { ...workspaceSnapshot(s), phren: info };
98
+ break;
99
+ }
100
+ case "/v1/workspaces/panes":
101
+ result = await panes(selectedServer(url), url.searchParams.get("groupId") || "", url.searchParams.get("childId") || "");
102
+ break;
103
+ case "/v1/transcripts/blob": {
104
+ const target = targetFromURL(url);
105
+ await validateTarget(target);
106
+ const bytes = await historicalImage(await transcriptPath(target.source, target.session), Number(url.searchParams.get("line")), Number(url.searchParams.get("block")), target.source);
107
+ response.setHeader("Content-Type", "application/octet-stream");
108
+ response.end(bytes);
109
+ return;
110
+ }
111
+ default: throw new BridgeError(404, "Unknown Phren Hook route.");
112
+ }
113
+ }
114
+ else if (request.method === "POST") {
115
+ const data = await body(request);
116
+ if (url.pathname.startsWith("/v1/workspaces/")) {
117
+ result = await workspaceAction(selectedServer(url), url.pathname.split("/").at(-1), data);
118
+ }
119
+ else {
120
+ const target = targetSchema.parse(data.target);
121
+ const pane = await validateTarget(target, ["/v1/prompt", "/v1/upload", "/v1/keys"].includes(url.pathname));
122
+ if (url.pathname === "/v1/prompt") {
123
+ const text = z.string().min(1).max(32768).refine(t => !/[\x00-\x08\x0b-\x1f\x7f]/.test(t)).parse(data.text);
124
+ await rpc(target.server, "agent.prompt", { target: target.pane, text });
125
+ result = { ok: true };
126
+ }
127
+ else if (url.pathname === "/v1/keys") {
128
+ if (JSON.stringify(data.keys) !== '["Escape"]' || pane.agent_status !== "working")
129
+ throw new BridgeError(409, "This agent is no longer working.");
130
+ await rpc(target.server, "agent.send_keys", { target: target.pane, keys: ["esc"] });
131
+ result = { ok: true };
132
+ }
133
+ else if (url.pathname === "/v1/upload") {
134
+ const name = z.string().regex(/^[A-Za-z0-9_.-]{1,200}\.(png|jpg|jpeg|gif|webp)$/i).parse(data.name);
135
+ const encoded = z.string().max(11_184_812).regex(/^[A-Za-z0-9+/]*={0,2}$/).parse(data.data);
136
+ const bytes = Buffer.from(encoded, "base64");
137
+ if (!bytes.length || bytes.length > MAX_FRAME)
138
+ throw new BridgeError(413, "The image is too large.");
139
+ result = { ok: true, path: await saveUpload(target.session, name, bytes) };
140
+ }
141
+ else if (url.pathname === "/v1/diff")
142
+ result = await repositoryDiff(await trustedDirectory(pane));
143
+ else if (url.pathname === "/v1/approvals/answer") {
144
+ await agentHooks.answer(target, z.string().uuid().parse(data.actionId), data.decision);
145
+ result = { ok: true };
146
+ }
147
+ else if (url.pathname === "/v1/questions/answer")
148
+ throw new BridgeError(409, "Answer this agent's request in the Phren terminal.");
149
+ else
150
+ throw new BridgeError(404, "Unknown Phren Hook route.");
151
+ }
152
+ }
153
+ else
154
+ throw new BridgeError(405, "Unsupported request method.");
155
+ const payload = JSON.stringify(result);
156
+ if (Buffer.byteLength(payload) > MAX_FRAME)
157
+ throw new BridgeError(413, "The response is too large.");
158
+ response.setHeader("Content-Type", "application/json");
159
+ response.end(payload);
160
+ }
161
+ catch (error) {
162
+ response.statusCode = error instanceof BridgeError ? error.status : error instanceof z.ZodError || error instanceof SyntaxError ? 400 : 503;
163
+ response.setHeader("Content-Type", "application/json");
164
+ response.end(JSON.stringify({ error: error instanceof BridgeError ? error.message : "Phren Hook could not complete this request. Run phren bridge doctor on the computer." }));
165
+ }
166
+ });
167
+ http.requestTimeout = 20_000;
168
+ http.headersTimeout = 10_000;
169
+ http.maxHeadersCount = 32;
170
+ const ws = new WebSocketServer({ noServer: true, maxPayload: 65_536, perMessageDeflate: false });
171
+ http.on("upgrade", (request, socket, head) => {
172
+ try {
173
+ const url = new URL(request.url || "/", "http://phren.local");
174
+ if (!["/v1/transcripts", "/v1/status"].includes(url.pathname) || url.origin !== "http://phren.local") {
175
+ socket.destroy();
176
+ return;
177
+ }
178
+ ws.handleUpgrade(request, socket, head, client => { void stream(client, url).catch(() => client.close(1011, "Conversation unavailable; refresh")); });
179
+ }
180
+ catch {
181
+ socket.destroy();
182
+ }
183
+ });
184
+ async function stream(client, url) {
185
+ const target = targetFromURL(url);
186
+ await validateTarget(target);
187
+ if (client.readyState !== WebSocket.OPEN)
188
+ return;
189
+ const unwatch = agentHooks.watch(target);
190
+ client.once("close", unwatch);
191
+ const reader = url.pathname === "/v1/transcripts" ? new TranscriptReader(await transcriptPath(target.source, target.session), target.source) : undefined;
192
+ let busy = false, closed = false, first = true;
193
+ client.on("close", () => { closed = true; clearInterval(timer); });
194
+ client.on("error", () => { closed = true; clearInterval(timer); });
195
+ const tick = async () => {
196
+ if (busy || closed)
197
+ return;
198
+ busy = true;
199
+ try {
200
+ const pane = await validateTarget(target);
201
+ if (reader) {
202
+ const page = await reader.read();
203
+ if (first || page.entries.length || page.reset)
204
+ send(client, { type: first || page.reset ? "backlog" : "append", source: target.source,
205
+ session: target.session, entries: page.entries, totalLines: page.totalLines, hasMore: page.hasMore });
206
+ }
207
+ else {
208
+ const pendingApproval = agentHooks.approval(target);
209
+ send(client, { agentStatus: { source: target.source, session: target.session,
210
+ status: pendingApproval ? "waiting" : pane.agent_status, pendingApproval, capabilities } });
211
+ }
212
+ first = false;
213
+ }
214
+ catch {
215
+ client.close(1011, "The conversation changed; refresh");
216
+ }
217
+ finally {
218
+ busy = false;
219
+ }
220
+ };
221
+ const timer = setInterval(() => { void tick(); }, reader ? 500 : 1500);
222
+ client.on("message", bytes => {
223
+ void (async () => {
224
+ const message = object(JSON.parse(bytes.toString()));
225
+ if (message.type !== "older" || !reader || busy)
226
+ return;
227
+ busy = true;
228
+ try {
229
+ await validateTarget(target);
230
+ const before = z.number().int().positive().parse(message.beforeLine);
231
+ const page = await new TranscriptReader(reader.file, target.source).read(before);
232
+ send(client, { type: "older", source: target.source, entries: page.entries, hasMore: page.hasMore, totalLines: page.totalLines });
233
+ }
234
+ finally {
235
+ busy = false;
236
+ }
237
+ })().catch(() => client.close(1008, "Invalid history request"));
238
+ });
239
+ await tick();
240
+ }
241
+ await new Promise((resolve, reject) => { http.once("error", reject); http.listen(socketPath(), () => resolve()); });
242
+ await chmod(socketPath(), 0o600);
243
+ await agentHooks.start();
244
+ let recording = false;
245
+ const activityTimer = setInterval(() => {
246
+ if (recording)
247
+ return;
248
+ recording = true;
249
+ void (async () => {
250
+ for (const server of await servers()) {
251
+ try {
252
+ await journal.record(String(server.session), objects((await snapshot(String(server.session))).panes));
253
+ }
254
+ catch { /* A disconnected computer keeps its previous local activity. */ }
255
+ }
256
+ })().finally(() => { recording = false; }).catch(() => { });
257
+ }, 5000);
258
+ await new Promise(resolve => {
259
+ const stop = () => { clearInterval(activityTimer); agentHooks.close(); ws.clients.forEach(c => c.terminate()); ws.close(); http.close(() => resolve()); http.closeAllConnections(); };
260
+ process.once("SIGTERM", stop);
261
+ process.once("SIGINT", stop);
262
+ });
263
+ await unlink(socketPath()).catch(() => { });
264
+ }
265
+ async function workspaceAction(server, operation, data) {
266
+ if (!["focus", "rename", "create", "close"].includes(operation))
267
+ throw new BridgeError(400, "Unsupported Herdr action.");
268
+ const s = await snapshot(server);
269
+ const workspace = typeof data.workspaceId === "string" ? data.workspaceId : undefined;
270
+ const tab = typeof data.tabId === "string" ? data.tabId : undefined;
271
+ const pane = typeof data.paneId === "string" ? data.paneId : undefined;
272
+ if (workspace && !objects(s.workspaces).some(w => w.workspace_id === workspace))
273
+ throw new BridgeError(409, "The workspace changed.");
274
+ if (tab && !objects(s.tabs).some(t => t.tab_id === tab && (!workspace || t.workspace_id === workspace)))
275
+ throw new BridgeError(409, "The tab changed.");
276
+ if (pane && !objects(s.panes).some(p => p.pane_id === pane && (!tab || p.tab_id === tab) && (!workspace || p.workspace_id === workspace)))
277
+ throw new BridgeError(409, "The pane changed.");
278
+ const label = data.label === undefined ? undefined : z.string().min(1).max(200).refine(t => !/[\x00-\x1f\x7f]/.test(t)).parse(data.label);
279
+ const cwd = data.cwd === undefined ? undefined : z.string().max(4096).refine(t => path.isAbsolute(t) && !/[\x00-\x1f\x7f]/.test(t)).parse(data.cwd);
280
+ if (operation === "create")
281
+ await rpc(server, workspace ? "tab.create" : "workspace.create", { workspace_id: workspace, label, cwd, focus: false, env: {} });
282
+ else if (!workspace && !tab && !pane)
283
+ throw new BridgeError(400, "Choose a Herdr destination.");
284
+ else if (pane && operation === "focus")
285
+ await rpc(server, "pane.focus", { pane_id: pane });
286
+ else if (pane)
287
+ throw new BridgeError(400, "This pane action is not available.");
288
+ else
289
+ await rpc(server, `${tab ? "tab" : "workspace"}.${operation}`, { ...(tab ? { tab_id: tab } : { workspace_id: workspace }), ...(label ? { label } : {}) });
290
+ return { ok: true };
291
+ }
@@ -0,0 +1,30 @@
1
+ import { type Json, type Provider } from "./protocol.js";
2
+ export interface Entry {
3
+ line: number;
4
+ raw: Json;
5
+ }
6
+ export declare function transcriptPath(source: Provider, session: string): Promise<string>;
7
+ /** Public conversation/tool events and real usage only. Never export private reasoning. */
8
+ export declare function visibleEvent(raw: Json, source: Provider): Json | undefined;
9
+ /** Append-only reader with bounded retained history. Incomplete rows wait for the next read. */
10
+ export declare class TranscriptReader {
11
+ readonly file: string;
12
+ readonly source: Provider;
13
+ private readonly imageLine?;
14
+ private offset;
15
+ private inode?;
16
+ private pending;
17
+ private pendingBytes;
18
+ private skippingRow;
19
+ private line;
20
+ private retained;
21
+ private retainedBytes;
22
+ constructor(file: string, source: Provider, imageLine?: number | undefined);
23
+ read(before?: number): Promise<{
24
+ entries: Entry[];
25
+ totalLines: number;
26
+ hasMore: boolean;
27
+ reset: boolean;
28
+ }>;
29
+ }
30
+ export declare function historicalImage(file: string, line: number, block: number, source: Provider): Promise<Buffer>;
@@ -0,0 +1,177 @@
1
+ import { open, realpath } from "node:fs/promises";
2
+ import { homedir } from "node:os";
3
+ import path from "node:path";
4
+ import { glob } from "glob";
5
+ import { BridgeError, object, objects } from "./protocol.js";
6
+ /** Preserve image block indexes without putting base64 payloads on the chat socket. */
7
+ function chatFrame(raw, source) {
8
+ const key = source === "codex" ? "payload" : "message";
9
+ const message = object(raw[key]);
10
+ if (!Array.isArray(message.content))
11
+ return raw;
12
+ return { ...raw, [key]: { ...message, content: message.content.map(value => {
13
+ const block = object(value);
14
+ return ["image", "input_image"].includes(String(block.type)) ? { type: block.type } : block;
15
+ }) } };
16
+ }
17
+ export async function transcriptPath(source, session) {
18
+ if (!/^[a-f0-9-]{36}$/i.test(session))
19
+ throw new BridgeError(400, "Invalid conversation identity.");
20
+ const base = source === "codex" ? path.join(process.env.CODEX_HOME || path.join(homedir(), ".codex"), "sessions")
21
+ : source === "claude" ? path.join(process.env.CLAUDE_CONFIG_DIR || path.join(homedir(), ".claude"), "projects")
22
+ : path.join(process.env.COPILOT_HOME || path.join(homedir(), ".copilot"), "session-state");
23
+ const root = await realpath(base);
24
+ const pattern = source === "codex" ? `*/*/*/rollout-*-${session}.jsonl` : source === "claude" ? `*/${session}.jsonl` : `${session}/events.jsonl`;
25
+ const matches = await glob(pattern, { cwd: root, absolute: true, follow: false });
26
+ if (matches.length !== 1)
27
+ throw new BridgeError(404, "The transcript is not available for this conversation.");
28
+ const file = await realpath(matches[0]);
29
+ if (!file.startsWith(root + path.sep))
30
+ throw new BridgeError(403, "The transcript points outside its agent folder.");
31
+ return file;
32
+ }
33
+ /** Public conversation/tool events and real usage only. Never export private reasoning. */
34
+ export function visibleEvent(raw, source) {
35
+ if (source === "codex") {
36
+ const p = object(raw.payload);
37
+ if (raw.type === "event_msg" && ["token_count", "task_started", "task_complete", "task_completed", "turn_aborted", "error"].includes(String(p.type)))
38
+ return raw;
39
+ if (raw.type !== "response_item")
40
+ return undefined;
41
+ if (p.type === "message" && ["user", "assistant"].includes(String(p.role)) && p.channel !== "analysis")
42
+ return raw;
43
+ if (["function_call", "custom_tool_call", "function_call_output", "custom_tool_call_output"].includes(String(p.type)))
44
+ return raw;
45
+ }
46
+ else if (source === "claude") {
47
+ if (raw.isMeta || raw.isSidechain || !["user", "assistant", "system"].includes(String(raw.type)))
48
+ return undefined;
49
+ const message = object(raw.message);
50
+ // Keep indexes for historical images while removing thinking contents.
51
+ if (typeof message.content === "string")
52
+ return raw;
53
+ if (Array.isArray(message.content))
54
+ return { ...raw, message: { ...message, content: objects(message.content).map(b => ["text", "image", "tool_use", "tool_result"].includes(String(b.type)) ? b : { type: "redacted" }) } };
55
+ }
56
+ else {
57
+ if (raw.agentId || raw.ephemeral || !["user.message", "assistant.message", "assistant.message_delta", "tool.execution_start", "tool.execution_complete", "assistant.turn_start", "assistant.turn_end", "session.idle", "session.error", "session.usage_info", "assistant.usage"].includes(String(raw.type)))
58
+ return undefined;
59
+ const data = object(raw.data);
60
+ // Copilot includes optional reasoning beside the public message in some
61
+ // versions. Export only the fields used by public text/tool/usage readers.
62
+ const allowed = ["content", "source", "messageId", "deltaContent", "toolName", "toolCallId", "arguments", "result", "error", "aborted", "inputTokens", "outputTokens", "cacheReadTokens"];
63
+ return { type: raw.type, timestamp: raw.timestamp, data: Object.fromEntries(Object.entries(data).filter(([key]) => allowed.includes(key))) };
64
+ }
65
+ return undefined;
66
+ }
67
+ /** Append-only reader with bounded retained history. Incomplete rows wait for the next read. */
68
+ export class TranscriptReader {
69
+ file;
70
+ source;
71
+ imageLine;
72
+ offset = 0;
73
+ inode;
74
+ pending = [];
75
+ pendingBytes = 0;
76
+ skippingRow = false;
77
+ line = 0;
78
+ retained = [];
79
+ retainedBytes = 0;
80
+ constructor(file, source, imageLine) {
81
+ this.file = file;
82
+ this.source = source;
83
+ this.imageLine = imageLine;
84
+ }
85
+ async read(before) {
86
+ const handle = await open(this.file, "r");
87
+ try {
88
+ const meta = await handle.stat();
89
+ if (!meta.isFile() || meta.size > 4_294_967_296)
90
+ throw new BridgeError(413, "This conversation exceeds the transcript limit.");
91
+ const reset = this.inode !== meta.ino || meta.size < this.offset;
92
+ if (reset) {
93
+ this.offset = 0;
94
+ this.line = 0;
95
+ this.pending = [];
96
+ this.pendingBytes = 0;
97
+ this.skippingRow = false;
98
+ this.retained = [];
99
+ this.retainedBytes = 0;
100
+ }
101
+ this.inode = meta.ino;
102
+ const start = this.line;
103
+ const buffer = Buffer.alloc(65_536);
104
+ while (this.offset < meta.size && (before === undefined || this.line < before)) {
105
+ const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, meta.size - this.offset), this.offset);
106
+ if (!bytesRead)
107
+ break;
108
+ this.offset += bytesRead;
109
+ let cursor = 0;
110
+ while (cursor < bytesRead) {
111
+ const newline = buffer.indexOf(10, cursor);
112
+ const complete = newline >= cursor && newline < bytesRead;
113
+ const end = complete ? newline : bytesRead;
114
+ this.pendingBytes += end - cursor;
115
+ if (this.pendingBytes > 67_108_864) {
116
+ this.skippingRow = true;
117
+ this.pending = [];
118
+ }
119
+ if (!this.skippingRow)
120
+ this.pending.push(Buffer.from(buffer.subarray(cursor, end)));
121
+ cursor = end + (complete ? 1 : 0);
122
+ if (!complete)
123
+ break;
124
+ const line = this.line++;
125
+ const row = this.skippingRow ? undefined : Buffer.concat(this.pending, this.pendingBytes);
126
+ this.pending = [];
127
+ this.pendingBytes = 0;
128
+ this.skippingRow = false;
129
+ if (!row || (before !== undefined && line >= before))
130
+ continue;
131
+ try {
132
+ const raw = visibleEvent(object(JSON.parse(row.toString())), this.source);
133
+ if (raw) {
134
+ const entry = { line, raw: this.imageLine === line ? raw : chatFrame(raw, this.source) };
135
+ const size = Buffer.byteLength(JSON.stringify(entry));
136
+ if (this.imageLine === line) {
137
+ this.retained = [entry];
138
+ this.retainedBytes = size;
139
+ }
140
+ else if (this.imageLine === undefined && size < 2_097_152) {
141
+ this.retained.push(entry);
142
+ this.retainedBytes += size;
143
+ while (this.retained.length > 200 || this.retainedBytes > 4_194_304)
144
+ this.retainedBytes -= Buffer.byteLength(JSON.stringify(this.retained.shift()));
145
+ }
146
+ }
147
+ }
148
+ catch { /* A malformed or oversized old row cannot block newer messages. */ }
149
+ }
150
+ }
151
+ const entries = reset || before !== undefined ? this.retained : this.retained.filter(e => e.line >= start);
152
+ return { entries, totalLines: this.line, hasMore: (this.retained[0]?.line ?? 0) > 0, reset };
153
+ }
154
+ finally {
155
+ await handle.close();
156
+ }
157
+ }
158
+ }
159
+ export async function historicalImage(file, line, block, source) {
160
+ if (!Number.isSafeInteger(line) || line < 0 || !Number.isSafeInteger(block) || block < 0 || block > 2000)
161
+ throw new BridgeError(400, "Invalid image reference.");
162
+ const reader = new TranscriptReader(file, source, line);
163
+ const page = await reader.read(line + 1);
164
+ const row = page.entries.find(e => e.line === line)?.raw;
165
+ if (!row)
166
+ throw new BridgeError(404, "This image is no longer in the transcript.");
167
+ const content = objects(source === "codex" ? object(row.payload).content : object(row.message).content);
168
+ const image = content[block];
169
+ const encoded = image?.image_url || object(image?.source).data;
170
+ const base64 = typeof encoded === "string" ? encoded.replace(/^data:image\/[a-z0-9.+-]+;base64,/i, "") : "";
171
+ if (!base64 || !/^[A-Za-z0-9+/=\s]+$/.test(base64) || base64.length > 11_184_812)
172
+ throw new BridgeError(404, "This image is not embedded in the transcript.");
173
+ const bytes = Buffer.from(base64, "base64");
174
+ if (bytes.length > 8_388_608)
175
+ throw new BridgeError(413, "This image is too large.");
176
+ return bytes;
177
+ }
@@ -0,0 +1,4 @@
1
+ import { type Json } from "./protocol.js";
2
+ export declare function health(): Promise<Json>;
3
+ /** The SSH key is forced to this allowlisted dispatcher. The supplied command is data, never a shell. */
4
+ export declare function dispatch(command: string): Promise<void>;
@@ -0,0 +1,64 @@
1
+ import { connect } from "node:net";
2
+ import { request } from "node:http";
3
+ import { spawn } from "node:child_process";
4
+ import { homedir } from "node:os";
5
+ import path from "node:path";
6
+ import { BridgeError, object, PROTOCOL, serverName, socketPath } from "./protocol.js";
7
+ import { rpc } from "./herdr.js";
8
+ export async function health() {
9
+ return new Promise((resolve, reject) => {
10
+ const req = request({ socketPath: socketPath(), path: "/v1/health", timeout: 2000 }, response => {
11
+ let data = "";
12
+ response.on("data", chunk => { data += chunk.toString(); if (data.length > 65_536)
13
+ req.destroy(new Error("Invalid helper status")); });
14
+ response.on("end", () => {
15
+ try {
16
+ const value = object(JSON.parse(data));
17
+ if (response.statusCode !== 200 || value.product !== "phren-hook" || value.protocol !== PROTOCOL)
18
+ throw new Error("Incompatible Phren Hook.");
19
+ resolve(value);
20
+ }
21
+ catch (error) {
22
+ reject(error);
23
+ }
24
+ });
25
+ response.on("error", reject);
26
+ });
27
+ req.on("error", reject);
28
+ req.on("timeout", () => req.destroy(new Error("Phren Hook did not answer.")));
29
+ req.end();
30
+ });
31
+ }
32
+ /** The SSH key is forced to this allowlisted dispatcher. The supplied command is data, never a shell. */
33
+ export async function dispatch(command) {
34
+ if (command === "phren-hook v1 pipe") {
35
+ await new Promise((resolve, reject) => {
36
+ const socket = connect(socketPath());
37
+ socket.on("connect", () => { process.stdin.pipe(socket); socket.pipe(process.stdout); });
38
+ socket.on("error", reject);
39
+ socket.on("close", () => { process.stdin.unpipe(socket); process.stdin.pause(); resolve(); });
40
+ process.stdin.once("end", () => socket.end());
41
+ process.stdout.once("error", () => socket.destroy());
42
+ });
43
+ return;
44
+ }
45
+ const terminal = /^phren-hook v1 terminal ([A-Za-z0-9_.-]{1,100})$/.exec(command);
46
+ if (!terminal)
47
+ throw new BridgeError(403, "This SSH key only permits Phren Hook and existing Herdr terminals.");
48
+ const server = serverName.parse(terminal[1]);
49
+ if (!process.stdin.isTTY || !process.stdout.isTTY)
50
+ throw new Error("Request an SSH terminal first.");
51
+ // Verify the named server exists; never create a workspace or an agent implicitly.
52
+ await rpc(server, "ping");
53
+ const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("HERDR_")));
54
+ env.PATH = [path.join(homedir(), ".local/bin"), "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"].join(":");
55
+ await new Promise((resolve, reject) => {
56
+ const child = spawn("herdr", ["session", "attach", server], { env, stdio: "inherit" });
57
+ child.once("error", reject);
58
+ child.once("exit", code => code === 0 ? resolve() : reject(new Error("The Herdr terminal disconnected.")));
59
+ const stop = () => child.kill("SIGHUP");
60
+ process.once("SIGHUP", stop);
61
+ process.once("SIGTERM", stop);
62
+ child.once("exit", () => { process.removeListener("SIGHUP", stop); process.removeListener("SIGTERM", stop); });
63
+ });
64
+ }
@@ -0,0 +1,2 @@
1
+ export declare function imageBytes(bytes: Buffer): boolean;
2
+ export declare function saveUpload(session: string, name: string, bytes: Buffer): Promise<string>;
@@ -0,0 +1,45 @@
1
+ import { mkdir, readdir, lstat, unlink, writeFile } from "node:fs/promises";
2
+ import path from "node:path";
3
+ import { randomUUID } from "node:crypto";
4
+ import { bridgeRoot, BridgeError, MAX_FRAME } from "./protocol.js";
5
+ export function imageBytes(bytes) {
6
+ return bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
7
+ || bytes.subarray(0, 3).equals(Buffer.from([255, 216, 255]))
8
+ || /^GIF8[79]a/.test(bytes.subarray(0, 6).toString())
9
+ || (bytes.subarray(0, 4).toString() === "RIFF" && bytes.subarray(8, 12).toString() === "WEBP");
10
+ }
11
+ let uploadQueue = Promise.resolve();
12
+ export async function saveUpload(session, name, bytes) {
13
+ if (!bytes.length || bytes.length > MAX_FRAME || !imageBytes(bytes))
14
+ throw new BridgeError(400, "Choose a PNG, JPEG, GIF, or WebP image.");
15
+ let saved = "";
16
+ const task = uploadQueue.catch(() => { }).then(async () => {
17
+ const root = path.join(bridgeRoot(), "uploads");
18
+ await mkdir(root, { recursive: true, mode: 0o700 });
19
+ let used = 0;
20
+ const directories = await readdir(root, { withFileTypes: true });
21
+ for (const dir of directories) {
22
+ if (!dir.isDirectory())
23
+ continue;
24
+ const folder = path.join(root, dir.name);
25
+ for (const entry of await readdir(folder, { withFileTypes: true })) {
26
+ if (!entry.isFile())
27
+ continue;
28
+ const file = path.join(folder, entry.name), metadata = await lstat(file);
29
+ if (Date.now() - metadata.mtimeMs > 14 * 86400_000)
30
+ await unlink(file);
31
+ else
32
+ used += metadata.size;
33
+ }
34
+ }
35
+ if (used + bytes.length > 268_435_456)
36
+ throw new BridgeError(413, "Phren's image storage is full. Remove older uploads on the computer.");
37
+ const folder = path.join(root, session);
38
+ await mkdir(folder, { recursive: true, mode: 0o700 });
39
+ saved = path.join(folder, `${randomUUID()}-${name}`);
40
+ await writeFile(saved, bytes, { flag: "wx", mode: 0o600 });
41
+ });
42
+ uploadQueue = task;
43
+ await task;
44
+ return saved;
45
+ }