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

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,438 @@
1
+ /**
2
+ * Step recording for one chat browser: 20x capture semantics on CDP.
3
+ *
4
+ * Human events come from the `pf-recorder` isolated world through the
5
+ * `__pfRecord` binding (see recorder-scripts.mjs) and are accepted ONLY while
6
+ * a person holds the applied lease; Playwright's agent input is also
7
+ * isTrusted, so without that rule agent clicks would be recorded twice, once
8
+ * as 'human'. Agent and browser steps are written by the broker itself.
9
+ *
10
+ * Steps are written to the chat's local, root-only 20x files
11
+ * (recording-store.mjs); nothing is uploaded. `onFinished` fires once per
12
+ * recording when it stops (saved or interrupted).
13
+ *
14
+ * `redact` (protocol v3) rewrites every row and snapshot before it is
15
+ * written: a value `fill_credential` typed must never reach a recording,
16
+ * even when the page shows it as text.
17
+ */
18
+ import { randomUUID } from 'node:crypto';
19
+ import { GAP } from './protocol.mjs';
20
+ import {
21
+ RECORDING_BINDING,
22
+ RECORDING_REMOVE_SCRIPT,
23
+ RECORDING_WORLD_NAME,
24
+ buildRecordingInstallScript,
25
+ buildRecordingSnapshotScript,
26
+ buildRecordingTargetScript,
27
+ parseRecordingMessage
28
+ } from './recorder-scripts.mjs';
29
+ import { log, errorText } from './log.mjs';
30
+
31
+ function withTimeout(promise, ms, fallback) {
32
+ let timer;
33
+ const timeout = new Promise((resolve) => {
34
+ timer = setTimeout(() => resolve(fallback), ms);
35
+ });
36
+ return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
37
+ }
38
+
39
+ /* -------------------------------------------------------------------------- */
40
+ /* Per-page capture */
41
+ /* -------------------------------------------------------------------------- */
42
+
43
+ class PageCapture {
44
+ constructor(page, cdp, onMessage, onDocument) {
45
+ this.page = page;
46
+ this.cdp = cdp;
47
+ this.contextId = null;
48
+ this.mainFrameId = null;
49
+ this.scriptId = null;
50
+ this.onMessage = onMessage;
51
+ this.onDocument = onDocument;
52
+ }
53
+
54
+ async install(nonce) {
55
+ const { cdp } = this;
56
+ const { frameTree } = await cdp.send('Page.getFrameTree');
57
+ this.mainFrameId = frameTree.frame.id;
58
+ cdp.on('Runtime.executionContextCreated', ({ context }) => {
59
+ if (
60
+ context.name === RECORDING_WORLD_NAME &&
61
+ context.auxData?.frameId === this.mainFrameId
62
+ ) {
63
+ this.contextId = context.id;
64
+ }
65
+ });
66
+ cdp.on('Runtime.executionContextDestroyed', ({ executionContextId }) => {
67
+ if (executionContextId === this.contextId) this.contextId = null;
68
+ });
69
+ cdp.on('Runtime.executionContextsCleared', () => {
70
+ this.contextId = null;
71
+ });
72
+ cdp.on('Runtime.bindingCalled', ({ name, payload }) => {
73
+ if (name === RECORDING_BINDING) this.onMessage(payload);
74
+ });
75
+ cdp.on('Page.domContentEventFired', () =>
76
+ this.onDocument('document-ready', this)
77
+ );
78
+ cdp.on('Page.navigatedWithinDocument', ({ frameId }) => {
79
+ if (frameId === this.mainFrameId) this.onDocument('navigation', this);
80
+ });
81
+ cdp.on('Page.frameNavigated', ({ frame }) => {
82
+ if (frame.id === this.mainFrameId && frame.unreachableUrl)
83
+ this.onDocument('navigation-failed', this);
84
+ });
85
+ await cdp.send('Page.enable');
86
+ await cdp.send('Runtime.enable');
87
+ await cdp.send('Runtime.addBinding', {
88
+ name: RECORDING_BINDING,
89
+ executionContextName: RECORDING_WORLD_NAME
90
+ });
91
+ const source = buildRecordingInstallScript(nonce);
92
+ // Future documents: the world and its listeners exist from document start.
93
+ const added = await cdp.send('Page.addScriptToEvaluateOnNewDocument', {
94
+ source,
95
+ worldName: RECORDING_WORLD_NAME,
96
+ runImmediately: true
97
+ });
98
+ this.scriptId = added.identifier;
99
+ // The current document: runImmediately may already have made the world.
100
+ await new Promise((resolve) => setTimeout(resolve, 50));
101
+ if (this.contextId !== null) {
102
+ const present = await this.evaluate(
103
+ 'typeof globalThis.__recordingCleanup === "function"',
104
+ 1000
105
+ );
106
+ if (present === true) return true;
107
+ }
108
+ const world = await cdp.send('Page.createIsolatedWorld', {
109
+ frameId: this.mainFrameId,
110
+ worldName: RECORDING_WORLD_NAME,
111
+ grantUniveralAccess: false
112
+ });
113
+ this.contextId = world.executionContextId;
114
+ return (await this.evaluate(source, 2000)) === true;
115
+ }
116
+
117
+ /** Evaluate in the recorder world; undefined on timeout or failure. */
118
+ async evaluate(expression, ms = 2000) {
119
+ if (this.contextId === null) return undefined;
120
+ try {
121
+ const result = await withTimeout(
122
+ this.cdp.send('Runtime.evaluate', {
123
+ expression,
124
+ contextId: this.contextId,
125
+ returnByValue: true,
126
+ awaitPromise: true
127
+ }),
128
+ ms,
129
+ null
130
+ );
131
+ if (!result || result.exceptionDetails) return undefined;
132
+ return result.result.value;
133
+ } catch {
134
+ return undefined;
135
+ }
136
+ }
137
+
138
+ async remove() {
139
+ await this.evaluate(RECORDING_REMOVE_SCRIPT, 2000);
140
+ if (this.scriptId) {
141
+ await this.cdp
142
+ .send('Page.removeScriptToEvaluateOnNewDocument', {
143
+ identifier: this.scriptId
144
+ })
145
+ .catch(() => undefined);
146
+ }
147
+ await this.cdp
148
+ .send('Runtime.removeBinding', { name: RECORDING_BINDING })
149
+ .catch(() => undefined);
150
+ await this.cdp.detach().catch(() => undefined);
151
+ }
152
+ }
153
+
154
+ /* -------------------------------------------------------------------------- */
155
+ /* Recorder */
156
+ /* -------------------------------------------------------------------------- */
157
+
158
+ export class Recorder {
159
+ #nonce = null;
160
+ #captures = new Map();
161
+ #queue = Promise.resolve();
162
+ #flushWaiter = null;
163
+ #recordingId = null;
164
+
165
+ /**
166
+ * @param {{ sessionId, chat, store, pages: () => Page[], activePage: () => Page,
167
+ * openCdp: (page) => Promise<CDPSession>, humanAllowed: () => boolean,
168
+ * redact?: (value) => unknown,
169
+ * onStep: () => void, onFinished: (manifest) => void }} deps
170
+ */
171
+ constructor(deps) {
172
+ this.deps = deps;
173
+ }
174
+
175
+ #redact(value) {
176
+ return value && this.deps.redact ? this.deps.redact(value) : value;
177
+ }
178
+
179
+ get recordingId() {
180
+ return this.#recordingId;
181
+ }
182
+
183
+ get recording() {
184
+ return this.#recordingId !== null;
185
+ }
186
+
187
+ async start(recordingId, title, startedByUserId = null) {
188
+ const manifest = this.deps.store.start(this.deps.chat, recordingId, title, {
189
+ sessionId: this.deps.sessionId,
190
+ startedByUserId
191
+ });
192
+ this.#recordingId = manifest.id;
193
+ this.#nonce = randomUUID();
194
+ for (const page of this.deps.pages()) await this.attach(page);
195
+ await this.recordStep({
196
+ source: 'browser',
197
+ action: 'recording-start',
198
+ snapshotPhase: 'initial'
199
+ });
200
+ log.info('recording started', {
201
+ sessionId: this.deps.sessionId,
202
+ recordingId: manifest.id
203
+ });
204
+ return manifest;
205
+ }
206
+
207
+ /** Install capture on a page (called for every page while recording). */
208
+ async attach(page) {
209
+ if (!this.#nonce || this.#captures.has(page)) return;
210
+ try {
211
+ const cdp = await this.deps.openCdp(page);
212
+ const capture = new PageCapture(
213
+ page,
214
+ cdp,
215
+ (payload) => this.#receive(payload),
216
+ (action, from) => this.#documentEvent(action, from)
217
+ );
218
+ this.#captures.set(page, capture);
219
+ page.once('close', () => this.#captures.delete(page));
220
+ const ok = await capture.install(this.#nonce);
221
+ if (!ok) this.deps.store.gap(this.deps.chat, GAP.captureStartFailed);
222
+ } catch (error) {
223
+ log.warn('recorder install failed', { error: errorText(error) });
224
+ this.deps.store.gap(this.deps.chat, GAP.captureStartFailed);
225
+ }
226
+ }
227
+
228
+ #documentEvent(action, capture) {
229
+ if (capture.page !== this.deps.activePage()) return;
230
+ if (action === 'document-ready') {
231
+ void this.recordStep({
232
+ source: 'browser',
233
+ action: 'document-ready',
234
+ snapshotPhase: 'document-ready'
235
+ });
236
+ } else if (action === 'navigation') {
237
+ void this.recordStep({
238
+ source: 'browser',
239
+ action: 'navigation',
240
+ snapshotPhase: 'after-action'
241
+ });
242
+ } else if (action === 'navigation-failed') {
243
+ void this.recordStep({
244
+ source: 'browser',
245
+ action: 'navigation-failed',
246
+ outcome: 'error',
247
+ snapshotPhase: 'after-action'
248
+ });
249
+ }
250
+ }
251
+
252
+ #receive(payload) {
253
+ if (!this.#nonce) return;
254
+ const parsed = parseRecordingMessage(payload, this.#nonce);
255
+ if (parsed?.foreign) return;
256
+ if (parsed === null) {
257
+ this.#safely(() => this.deps.store.gap(this.deps.chat, GAP.eventUnsaved));
258
+ return;
259
+ }
260
+ if (parsed.flush) {
261
+ this.#flushWaiter?.();
262
+ return;
263
+ }
264
+ // Deliberate difference 4: only while a person holds the lease.
265
+ if (!this.deps.humanAllowed()) return;
266
+ const recordingId = this.#recordingId;
267
+ this.#enqueue(async () => {
268
+ if (this.#recordingId !== recordingId) return;
269
+ this.deps.store.append(
270
+ this.deps.chat,
271
+ this.#redact(parsed.step),
272
+ this.#redact(parsed.snapshot)
273
+ );
274
+ this.#afterAppend();
275
+ });
276
+ }
277
+
278
+ #enqueue(job) {
279
+ this.#queue = this.#queue.then(job).catch((error) => {
280
+ log.warn('recording write failed', { error: errorText(error) });
281
+ this.interrupt(GAP.writeFailed);
282
+ });
283
+ return this.#queue;
284
+ }
285
+
286
+ #safely(fn) {
287
+ try {
288
+ fn();
289
+ } catch {
290
+ this.interrupt(GAP.writeFailed);
291
+ }
292
+ }
293
+
294
+ #afterAppend() {
295
+ this.deps.onStep?.();
296
+ if (!this.deps.store.status(this.deps.chat) && this.#recordingId) {
297
+ // A cap interrupted the recording inside append().
298
+ this.#finishLocal();
299
+ }
300
+ }
301
+
302
+ /** 20x recordStep: snapshot from the active page, then append. */
303
+ recordStep(step) {
304
+ if (!this.#recordingId) return Promise.resolve();
305
+ const recordingId = this.#recordingId;
306
+ return this.#enqueue(async () => {
307
+ if (this.#recordingId !== recordingId) return;
308
+ const page = this.deps.activePage();
309
+ const capture = page && this.#captures.get(page);
310
+ let snapshot;
311
+ let gap;
312
+ const value = capture
313
+ ? await capture.evaluate(buildRecordingSnapshotScript(), 2000)
314
+ : undefined;
315
+ if (value && typeof value === 'object') snapshot = value;
316
+ else
317
+ gap =
318
+ capture && capture.contextId !== null
319
+ ? GAP.snapshotTimeout
320
+ : GAP.snapshotUnavailable;
321
+ if (this.#recordingId !== recordingId) return;
322
+ let url = '';
323
+ try {
324
+ url = page?.url() ?? '';
325
+ } catch {
326
+ /* closed */
327
+ }
328
+ this.deps.store.append(
329
+ this.deps.chat,
330
+ this.#redact({ ...step, url }),
331
+ this.#redact(snapshot)
332
+ );
333
+ if (gap && this.deps.store.status(this.deps.chat)) {
334
+ this.deps.store.gap(this.deps.chat, gap);
335
+ }
336
+ this.#afterAppend();
337
+ });
338
+ }
339
+
340
+ /** 20x buildRecordingTargetScript, for agent action targets. */
341
+ async describeTarget(selector) {
342
+ const page = this.deps.activePage();
343
+ const capture = page && this.#captures.get(page);
344
+ if (!capture) return '[unknown target]';
345
+ const value = await capture.evaluate(
346
+ buildRecordingTargetScript(selector),
347
+ 2000
348
+ );
349
+ return typeof value === 'string' ? this.#redact(value) : '[unknown target]';
350
+ }
351
+
352
+ /**
353
+ * Flush a person's pending (debounced) input into the recording: the
354
+ * cleanup sends the pending event plus `recording-flush-complete`, then the
355
+ * listeners are installed again. Used on hand-back to the agent.
356
+ */
357
+ async flushHuman() {
358
+ if (!this.#recordingId) return;
359
+ const capture = this.#captures.get(this.deps.activePage());
360
+ if (!capture) return;
361
+ const flushed = new Promise((resolve) => {
362
+ this.#flushWaiter = resolve;
363
+ });
364
+ const removed = await capture.evaluate(RECORDING_REMOVE_SCRIPT, 2000);
365
+ if (removed) await withTimeout(flushed, 1000, false);
366
+ this.#flushWaiter = null;
367
+ await capture.evaluate(buildRecordingInstallScript(this.#nonce), 2000);
368
+ await this.#queue;
369
+ }
370
+
371
+ async stop({ browserAlive = true } = {}) {
372
+ if (!this.#recordingId) throw new Error('This browser is not recording');
373
+ const recordingId = this.#recordingId;
374
+ const capture = browserAlive
375
+ ? this.#captures.get(this.deps.activePage())
376
+ : null;
377
+ if (capture) {
378
+ const flushed = new Promise((resolve) => {
379
+ this.#flushWaiter = () => resolve(true);
380
+ });
381
+ const removed = await capture.evaluate(RECORDING_REMOVE_SCRIPT, 2000);
382
+ const confirmed = removed
383
+ ? await withTimeout(flushed, 1000, false)
384
+ : false;
385
+ if (!confirmed) this.deps.store.gap(this.deps.chat, GAP.flushUnconfirmed);
386
+ this.#flushWaiter = null;
387
+ } else {
388
+ this.deps.store.gap(this.deps.chat, GAP.finalUnavailable);
389
+ }
390
+ await this.#queue;
391
+ if (capture) {
392
+ await this.recordStep({
393
+ source: 'browser',
394
+ action: 'recording-stop',
395
+ snapshotPhase: 'final'
396
+ });
397
+ await this.#queue;
398
+ }
399
+ if (this.#recordingId !== recordingId) {
400
+ // Interrupted while stopping (a cap or a write failure).
401
+ return this.deps.store.get(this.deps.chat, recordingId).recording;
402
+ }
403
+ const manifest = this.deps.store.stop(this.deps.chat);
404
+ this.#finishLocal();
405
+ return manifest;
406
+ }
407
+
408
+ /** Stop without the final snapshot (browser closed, write failure, cap). */
409
+ interrupt(message) {
410
+ if (!this.#recordingId) return null;
411
+ const manifest = this.deps.store.interrupt(this.deps.chat, message) ?? null;
412
+ this.#finishLocal();
413
+ return manifest;
414
+ }
415
+
416
+ #finishLocal() {
417
+ const recordingId = this.#recordingId;
418
+ if (!recordingId) return;
419
+ this.#recordingId = null;
420
+ this.#nonce = null;
421
+ const captures = [...this.#captures.values()];
422
+ this.#captures.clear();
423
+ for (const capture of captures) void capture.remove();
424
+ let manifest = null;
425
+ try {
426
+ manifest = this.deps.store.get(this.deps.chat, recordingId).recording;
427
+ } catch {
428
+ /* storage unavailable */
429
+ }
430
+ this.deps.onFinished?.(
431
+ manifest ?? { id: recordingId, status: 'interrupted' }
432
+ );
433
+ log.info('recording stopped', {
434
+ sessionId: this.deps.sessionId,
435
+ recordingId
436
+ });
437
+ }
438
+ }