@peakflo/agent-harness 0.2.20-rc.1 → 0.2.20

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 (34) hide show
  1. package/README.md +78 -0
  2. package/dist/browser-broker/agent-actions.mjs +799 -0
  3. package/dist/browser-broker/browsers.mjs +1699 -0
  4. package/dist/browser-broker/credentials.mjs +211 -0
  5. package/dist/browser-broker/disk-guard.mjs +84 -0
  6. package/dist/browser-broker/egress.mjs +183 -0
  7. package/dist/browser-broker/input.mjs +270 -0
  8. package/dist/browser-broker/lease.mjs +547 -0
  9. package/dist/browser-broker/local-network.mjs +173 -0
  10. package/dist/browser-broker/local.mjs +158 -0
  11. package/dist/browser-broker/log.mjs +28 -0
  12. package/dist/browser-broker/network-policy.mjs +144 -0
  13. package/dist/browser-broker/os-users.mjs +493 -0
  14. package/dist/browser-broker/package.json +1 -0
  15. package/dist/browser-broker/protocol.mjs +321 -0
  16. package/dist/browser-broker/queue.mjs +37 -0
  17. package/dist/browser-broker/recorder-scripts.mjs +221 -0
  18. package/dist/browser-broker/recorder.mjs +438 -0
  19. package/dist/browser-broker/recording-store.mjs +493 -0
  20. package/dist/browser-broker/relay.mjs +399 -0
  21. package/dist/browser-broker/screencast.mjs +198 -0
  22. package/dist/browser-broker/state-store.mjs +112 -0
  23. package/dist/browser-broker/transfers.mjs +460 -0
  24. package/dist/control-plane.d.ts +6 -0
  25. package/dist/control-plane.js +10 -0
  26. package/dist/github-workspace.d.ts +2 -0
  27. package/dist/github-workspace.js +4 -0
  28. package/dist/harness.d.ts +1 -0
  29. package/dist/harness.js +24 -0
  30. package/dist/runtime/knowledge-tools.d.ts +1 -0
  31. package/dist/runtime/knowledge-tools.js +3 -0
  32. package/dist/runtime/local-browser.d.ts +33 -0
  33. package/dist/runtime/local-browser.js +135 -0
  34. package/package.json +5 -3
@@ -0,0 +1,493 @@
1
+ /**
2
+ * Durable local recording files. A port of 20x src/main/browser-recording.ts
3
+ * (BrowserRecordingService) with the SAME files per recording:
4
+ *
5
+ * <root>/<chat>/<recordingId>/manifest.json atomically replaced (tmp + rename)
6
+ * <root>/<chat>/<recordingId>/steps.jsonl one step per line, appended
7
+ * <root>/<chat>/<recordingId>/sN.json one snapshot per file
8
+ *
9
+ * RECORDINGS NEVER LEAVE THE SANDBOX on their own (protocol v2). The API reads
10
+ * them through `recording_read` (20x result shapes) and, only for "Create
11
+ * workflow from this", asks `recording_files` for the exact paths and copies
12
+ * them through the Daytona toolbox.
13
+ *
14
+ * <chat> is the chat's browser Unix user name (pfb-<8 hex>), so a chat's
15
+ * recordings are one directory and every read is scoped by construction: the
16
+ * broker resolves <chat> from the sessionId the API took from the
17
+ * authenticated session, never from tool arguments.
18
+ *
19
+ * Differences from 20x, all deliberate:
20
+ * - Keyed by chat (20x: panelId); the manifest's panelId is always
21
+ * 'chat-browser' and taskIds stays [].
22
+ * - The second initial gap says typed text is recorded as [redacted].
23
+ * - A per-recording byte cap (BROWSER_RECORDING_BYTE_CAP) and a per-chat cap
24
+ * on retained bytes (BROWSER_CHAT_RECORDING_BYTE_CAP): start is refused
25
+ * with `storage_full`, a live recording is interrupted with the storage gap.
26
+ * - One sidecar that is NOT part of the 20x format and is never returned:
27
+ * meta.json ({ sessionId, startedByUserId }).
28
+ *
29
+ * Root is /var/pf/browser-recordings, root 0700; every directory below is
30
+ * root 0700 and every file root 0600. No browser user, and not pfharness, can
31
+ * read any of it.
32
+ */
33
+ import {
34
+ appendFileSync,
35
+ existsSync,
36
+ mkdirSync,
37
+ readFileSync,
38
+ readdirSync,
39
+ renameSync,
40
+ rmSync,
41
+ lstatSync,
42
+ writeFileSync,
43
+ chmodSync
44
+ } from 'node:fs';
45
+ import { join } from 'node:path';
46
+ import {
47
+ BROWSER_CHAT_RECORDING_BYTE_CAP,
48
+ BROWSER_PANEL_ID,
49
+ BROWSER_RECORDING_BYTE_CAP,
50
+ BROWSER_RECORDING_ID,
51
+ BROWSER_RECORDING_STEP_CAP,
52
+ BROWSER_SNAPSHOT_ID,
53
+ BrokerError,
54
+ GAP,
55
+ RECORDING_INITIAL_GAPS,
56
+ TOOL_ERRORS,
57
+ recordingUrl
58
+ } from './protocol.mjs';
59
+
60
+ export { recordingUrl };
61
+
62
+ const ID = BROWSER_RECORDING_ID;
63
+ const CHAT = /^[a-zA-Z0-9_-]{1,64}$/;
64
+ export const RECORDING_FILE_NAME =
65
+ /^(manifest\.json|steps\.jsonl|s[1-9][0-9]{0,5}\.json)$/;
66
+ export const DEFAULT_PAGE_LIMIT = 50;
67
+ export const MAX_PAGE_LIMIT = 100;
68
+
69
+ const notFound = () =>
70
+ new BrokerError('not_found', 'Browser recording not found');
71
+
72
+ /** Validate a page request (20x: offset >= 0, limit 1..100, default 50). */
73
+ export function page(offset, limit) {
74
+ const o = offset === undefined || offset === null ? 0 : offset;
75
+ const l = limit === undefined || limit === null ? DEFAULT_PAGE_LIMIT : limit;
76
+ if (
77
+ !Number.isSafeInteger(o) ||
78
+ o < 0 ||
79
+ !Number.isInteger(l) ||
80
+ l < 1 ||
81
+ l > MAX_PAGE_LIMIT
82
+ ) {
83
+ throw new BrokerError(
84
+ 'invalid_args',
85
+ 'Use a non-negative offset and limit from 1 to 100'
86
+ );
87
+ }
88
+ return { offset: o, limit: l };
89
+ }
90
+
91
+ function pageOf(rows, offset, limit) {
92
+ return {
93
+ items: rows.slice(offset, offset + limit),
94
+ total: rows.length,
95
+ nextOffset: offset + limit < rows.length ? offset + limit : null
96
+ };
97
+ }
98
+
99
+ /** Bytes of every regular file under `dir` (no symlinks followed). */
100
+ function treeBytes(dir) {
101
+ let total = 0;
102
+ let entries = [];
103
+ try {
104
+ entries = readdirSync(dir, { withFileTypes: true });
105
+ } catch {
106
+ return 0;
107
+ }
108
+ for (const entry of entries) {
109
+ const full = join(dir, entry.name);
110
+ if (entry.isDirectory()) total += treeBytes(full);
111
+ else if (entry.isFile()) {
112
+ try {
113
+ total += lstatSync(full).size;
114
+ } catch {
115
+ /* gone */
116
+ }
117
+ }
118
+ }
119
+ return total;
120
+ }
121
+
122
+ export class RecordingStore {
123
+ /** chat -> live manifest */
124
+ #active = new Map();
125
+ /** chat -> bytes of the live recording */
126
+ #recBytes = new Map();
127
+ /** chat -> retained bytes of the whole chat area (computed at start, then counted) */
128
+ #chatBytes = new Map();
129
+ /** chat -> last manifest started in this process (idempotent stop) */
130
+ #latest = new Map();
131
+ /** { chat, id } recovered from a crash by this process start. */
132
+ recovered = [];
133
+
134
+ constructor(
135
+ root,
136
+ {
137
+ byteCap = BROWSER_RECORDING_BYTE_CAP,
138
+ chatCap = BROWSER_CHAT_RECORDING_BYTE_CAP
139
+ } = {}
140
+ ) {
141
+ this.root = root;
142
+ this.byteCap = byteCap;
143
+ this.chatCap = chatCap;
144
+ mkdirSync(root, { recursive: true, mode: 0o700 });
145
+ chmodSync(root, 0o700);
146
+ for (const chat of this.#readdir(root)) {
147
+ if (!CHAT.test(chat)) continue;
148
+ for (const id of this.#readdir(join(root, chat))) {
149
+ if (!ID.test(id)) continue;
150
+ try {
151
+ const manifest = this.#load(chat, id);
152
+ if (manifest.status !== 'recording') continue;
153
+ // 20x crash recovery: the valid prefix, interrupted with a gap.
154
+ const rows = this.readRows(chat, id);
155
+ manifest.stepCount = rows.length;
156
+ manifest.snapshotCount = rows.filter(
157
+ (row) => !!row.snapshotId
158
+ ).length;
159
+ manifest.status = 'interrupted';
160
+ manifest.stoppedAt = new Date().toISOString();
161
+ if (!manifest.gaps.includes(GAP.appStopped))
162
+ manifest.gaps.push(GAP.appStopped);
163
+ this.#save(chat, manifest);
164
+ this.recovered.push({ chat, id });
165
+ } catch {
166
+ /* Ignore unrelated or incomplete directories. */
167
+ }
168
+ }
169
+ }
170
+ }
171
+
172
+ #readdir(dir) {
173
+ try {
174
+ return readdirSync(dir);
175
+ } catch {
176
+ return [];
177
+ }
178
+ }
179
+
180
+ #chatDir(chat) {
181
+ if (!CHAT.test(String(chat)))
182
+ throw new BrokerError('invalid_args', 'Invalid chat');
183
+ return join(this.root, chat);
184
+ }
185
+
186
+ #dir(chat, id) {
187
+ if (typeof id !== 'string' || !ID.test(id))
188
+ throw new BrokerError('invalid_args', 'Invalid recording ID');
189
+ return join(this.#chatDir(chat), id);
190
+ }
191
+
192
+ #load(chat, id) {
193
+ return JSON.parse(
194
+ readFileSync(join(this.#dir(chat, id), 'manifest.json'), 'utf8')
195
+ );
196
+ }
197
+
198
+ #save(chat, manifest) {
199
+ const dir = this.#dir(chat, manifest.id);
200
+ writeFileSync(join(dir, 'manifest.tmp'), JSON.stringify(manifest), {
201
+ mode: 0o600
202
+ });
203
+ renameSync(join(dir, 'manifest.tmp'), join(dir, 'manifest.json'));
204
+ }
205
+
206
+ /** The live manifest, else the file; not_found when the chat has no such recording. */
207
+ #manifest(chat, id) {
208
+ const live = this.#active.get(chat);
209
+ if (live && live.id === id) return live;
210
+ try {
211
+ return this.#load(chat, id);
212
+ } catch (error) {
213
+ if (error instanceof BrokerError) throw error;
214
+ throw notFound();
215
+ }
216
+ }
217
+
218
+ meta(chat, id) {
219
+ try {
220
+ return JSON.parse(
221
+ readFileSync(join(this.#dir(chat, id), 'meta.json'), 'utf8')
222
+ );
223
+ } catch {
224
+ return {};
225
+ }
226
+ }
227
+
228
+ status(chat) {
229
+ return this.#active.get(chat) ?? null;
230
+ }
231
+
232
+ last(chat) {
233
+ return this.#latest.get(chat) ?? null;
234
+ }
235
+
236
+ chatBytes(chat) {
237
+ if (!this.#chatBytes.has(chat))
238
+ this.#chatBytes.set(chat, treeBytes(this.#chatDir(chat)));
239
+ return this.#chatBytes.get(chat);
240
+ }
241
+
242
+ start(chat, id, title, { sessionId = null, startedByUserId = null } = {}) {
243
+ if (this.#active.has(chat))
244
+ throw new BrokerError('recording_active', TOOL_ERRORS.alreadyRecording);
245
+ const dir = this.#dir(chat, id);
246
+ // Fresh count: the chat area may have changed (wipe, another process).
247
+ this.#chatBytes.delete(chat);
248
+ if (this.chatBytes(chat) >= this.chatCap) {
249
+ throw new BrokerError(
250
+ 'storage_full',
251
+ 'This chat keeps too many recorded bytes to start another recording.'
252
+ );
253
+ }
254
+ const manifest = {
255
+ version: 1,
256
+ id,
257
+ panelId: BROWSER_PANEL_ID,
258
+ title: (typeof title === 'string' && title.trim()
259
+ ? title.trim()
260
+ : 'Browser recording'
261
+ ).slice(0, 160),
262
+ taskIds: [],
263
+ startedAt: new Date().toISOString(),
264
+ status: 'recording',
265
+ stepCount: 0,
266
+ snapshotCount: 0,
267
+ gaps: [...RECORDING_INITIAL_GAPS]
268
+ };
269
+ mkdirSync(this.#chatDir(chat), { recursive: true, mode: 0o700 });
270
+ mkdirSync(dir, { mode: 0o700 });
271
+ writeFileSync(
272
+ join(dir, 'meta.json'),
273
+ JSON.stringify({ sessionId, startedByUserId }),
274
+ { mode: 0o600 }
275
+ );
276
+ this.#save(chat, manifest);
277
+ this.#active.set(chat, manifest);
278
+ this.#latest.set(chat, manifest);
279
+ this.#recBytes.set(chat, 0);
280
+ return manifest;
281
+ }
282
+
283
+ /**
284
+ * Append one step (and optionally its snapshot). Returns false when the
285
+ * recording was interrupted by a cap instead of written.
286
+ */
287
+ append(chat, step, snapshot) {
288
+ const m = this.#active.get(chat);
289
+ if (!m) return false;
290
+ if (m.stepCount >= BROWSER_RECORDING_STEP_CAP) {
291
+ this.interrupt(chat, GAP.stepCap);
292
+ return false;
293
+ }
294
+ const row = {
295
+ ...step,
296
+ url: step.url ? recordingUrl(step.url) : undefined,
297
+ sequence: m.stepCount + 1,
298
+ at: new Date().toISOString()
299
+ };
300
+ let snapshotText = null;
301
+ if (snapshot) {
302
+ const id = `s${m.snapshotCount + 1}`;
303
+ snapshotText = JSON.stringify({
304
+ ...snapshot,
305
+ url: recordingUrl(snapshot.url),
306
+ id
307
+ });
308
+ row.snapshotId = id;
309
+ }
310
+ const line = JSON.stringify(row) + '\n';
311
+ const added =
312
+ Buffer.byteLength(line) +
313
+ (snapshotText ? Buffer.byteLength(snapshotText) : 0);
314
+ if (
315
+ (this.#recBytes.get(chat) ?? 0) + added > this.byteCap ||
316
+ this.chatBytes(chat) + added > this.chatCap
317
+ ) {
318
+ this.interrupt(chat, GAP.storageCap);
319
+ return false;
320
+ }
321
+ const dir = this.#dir(chat, m.id);
322
+ if (snapshotText) {
323
+ writeFileSync(join(dir, `${row.snapshotId}.json`), snapshotText, {
324
+ mode: 0o600
325
+ });
326
+ m.snapshotCount++;
327
+ }
328
+ appendFileSync(join(dir, 'steps.jsonl'), line, { mode: 0o600 });
329
+ m.stepCount++;
330
+ this.#recBytes.set(chat, (this.#recBytes.get(chat) ?? 0) + added);
331
+ this.#chatBytes.set(chat, this.chatBytes(chat) + added);
332
+ this.#save(chat, m);
333
+ return true;
334
+ }
335
+
336
+ gap(chat, message) {
337
+ const m = this.#active.get(chat);
338
+ if (m && !m.gaps.includes(message)) {
339
+ m.gaps.push(message);
340
+ this.#save(chat, m);
341
+ }
342
+ }
343
+
344
+ stop(chat, interrupted = false) {
345
+ const m = this.#active.get(chat);
346
+ if (!m) throw new BrokerError('not_recording', TOOL_ERRORS.notRecording);
347
+ m.status = interrupted ? 'interrupted' : 'saved';
348
+ m.stoppedAt = new Date().toISOString();
349
+ this.#save(chat, m);
350
+ this.#active.delete(chat);
351
+ return m;
352
+ }
353
+
354
+ interrupt(chat, message) {
355
+ const m = this.#active.get(chat);
356
+ if (!m) return null;
357
+ if (!m.gaps.includes(message)) m.gaps.push(message);
358
+ m.status = 'interrupted';
359
+ m.stoppedAt = new Date().toISOString();
360
+ this.#active.delete(chat);
361
+ try {
362
+ this.#save(chat, m);
363
+ } catch {
364
+ /* Keep the failure visible in memory when storage is unavailable. */
365
+ }
366
+ return m;
367
+ }
368
+
369
+ /* ------------------------------------------------------------------------ */
370
+ /* Reads (20x shapes), always scoped to one chat */
371
+ /* ------------------------------------------------------------------------ */
372
+
373
+ #all(chat) {
374
+ return this.#readdir(this.#chatDir(chat))
375
+ .filter((id) => ID.test(id))
376
+ .flatMap((id) => {
377
+ try {
378
+ return [this.#manifest(chat, id)];
379
+ } catch {
380
+ return [];
381
+ }
382
+ })
383
+ .sort((a, b) => b.startedAt.localeCompare(a.startedAt));
384
+ }
385
+
386
+ /** `{ recordings, total, nextOffset }`, newest first. */
387
+ list(chat, offset, limit) {
388
+ const p = page(offset, limit);
389
+ const { items, total, nextOffset } = pageOf(
390
+ this.#all(chat),
391
+ p.offset,
392
+ p.limit
393
+ );
394
+ return { recordings: items, total, nextOffset };
395
+ }
396
+
397
+ /** `{ recording: manifest }` */
398
+ get(chat, id) {
399
+ return { recording: this.#manifest(chat, id) };
400
+ }
401
+
402
+ /** 20x readRows: the valid prefix of steps.jsonl. */
403
+ readRows(chat, id) {
404
+ const file = join(this.#dir(chat, id), 'steps.jsonl');
405
+ const rows = [];
406
+ if (!existsSync(file)) return rows;
407
+ for (const line of readFileSync(file, 'utf8').split('\n')) {
408
+ if (!line) continue;
409
+ try {
410
+ const row = JSON.parse(line);
411
+ if (row.sequence !== rows.length + 1 || typeof row.action !== 'string')
412
+ break;
413
+ rows.push(row);
414
+ } catch {
415
+ break;
416
+ }
417
+ }
418
+ return rows;
419
+ }
420
+
421
+ /** `{ steps, total, nextOffset }` — also while the recording is live. */
422
+ steps(chat, id, offset, limit) {
423
+ const p = page(offset, limit);
424
+ this.#manifest(chat, id);
425
+ const { items, total, nextOffset } = pageOf(
426
+ this.readRows(chat, id),
427
+ p.offset,
428
+ p.limit
429
+ );
430
+ return { steps: items, total, nextOffset };
431
+ }
432
+
433
+ /** `{ snapshot }` */
434
+ snapshot(chat, id, snapshotId) {
435
+ this.#manifest(chat, id);
436
+ if (
437
+ typeof snapshotId !== 'string' ||
438
+ !BROWSER_SNAPSHOT_ID.test(snapshotId)
439
+ ) {
440
+ throw new BrokerError('invalid_args', 'Invalid snapshot ID');
441
+ }
442
+ try {
443
+ return {
444
+ snapshot: JSON.parse(
445
+ readFileSync(join(this.#dir(chat, id), `${snapshotId}.json`), 'utf8')
446
+ )
447
+ };
448
+ } catch {
449
+ throw new BrokerError(
450
+ 'not_found',
451
+ 'Browser recording snapshot not found'
452
+ );
453
+ }
454
+ }
455
+
456
+ /**
457
+ * The exact 20x files of a FINISHED recording, for a toolbox copy:
458
+ * `[{ name, path, size }]` (manifest.json, steps.jsonl, sN.json).
459
+ */
460
+ files(chat, id) {
461
+ const manifest = this.#manifest(chat, id);
462
+ if (manifest.status === 'recording') {
463
+ throw new BrokerError(
464
+ 'recording_active',
465
+ 'The recording is still running. Stop it first.'
466
+ );
467
+ }
468
+ const dir = this.#dir(chat, id);
469
+ const files = [];
470
+ for (const name of this.#readdir(dir)) {
471
+ if (!RECORDING_FILE_NAME.test(name)) continue;
472
+ const full = join(dir, name);
473
+ const stat = lstatSync(full);
474
+ if (!stat.isFile()) continue;
475
+ files.push({ name, path: full, size: stat.size });
476
+ }
477
+ const rank = (n) =>
478
+ n === 'manifest.json'
479
+ ? 0
480
+ : n === 'steps.jsonl'
481
+ ? 1
482
+ : 2 + Number(n.slice(1, -5));
483
+ return files.sort((a, b) => rank(a.name) - rank(b.name));
484
+ }
485
+
486
+ /** Delete every recording of a chat (close with wipe). */
487
+ removeChat(chat) {
488
+ if (this.#active.has(chat)) this.#active.delete(chat);
489
+ this.#latest.delete(chat);
490
+ this.#chatBytes.delete(chat);
491
+ rmSync(this.#chatDir(chat), { recursive: true, force: true });
492
+ }
493
+ }