@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
package/README.md CHANGED
@@ -363,3 +363,81 @@ See the comments above `contentDigest()`, `planRelease()` and `release()` in
363
363
  concurrent runs are kept from publishing the same version.
364
364
 
365
365
  Licensed under the MIT License. See [LICENSE](./LICENSE).
366
+
367
+ ### Local server previews
368
+
369
+ A chat on a desktop or self-hosted runner uses headless Chromium on that runner
370
+ for local previews. Each chat has a separate profile. It sends frames through
371
+ the existing authenticated chat browser connection. No dev-server port is
372
+ published to the internet.
373
+
374
+ Install Google Chrome or Chromium, or install the matching Playwright browser:
375
+
376
+ ```sh
377
+ npx --yes playwright-core@1.63.0 install chromium
378
+ ```
379
+
380
+ Update the harness after this change is released, then send the chat a message.
381
+ Ask the agent to start its dev server and call `browser_preview_local` with its
382
+ port. The tool opens `http://127.0.0.1:<port>/` in the chat browser. The tab shows
383
+ the source machine and port. Do not try LAN IPs or use a public server binding.
384
+
385
+ The preview permits one explicit HTTP port per chat, from 1024 to 65535. It
386
+ refuses harness and platform service ports. A new grant replaces the old port.
387
+ It refuses other ports, LAN hosts, public sites, file URLs, and HTTPS targets.
388
+ Local assets and WebSocket reloads can use the selected port. External assets
389
+ and separate API ports need a dev-server proxy on that port. File transfer and
390
+ recording export are not available for local previews. Cloud browsers keep the
391
+ existing sandbox path.
392
+
393
+ The signed grant names one tenant, runner, and chat. The API checks it each 15
394
+ seconds. The harness checks it each 20 seconds. The harness closes the preview
395
+ when access ends, or after one minute without the API. Tokens expire after two
396
+ minutes and refresh while the chat is idle. Closing a browser clears its port
397
+ grant. One harness permits at most six local Chromium instances. Harness
398
+ shutdown closes all its previews. The browser uses the normal OS user and
399
+ Chromium sandbox. It does not use the user's browser profile.
400
+
401
+ This feature needs an API/UI release and a new `@peakflo/agent-harness` release.
402
+ No database migration is needed. The image-input guard requires snapshot
403
+ version 0.15.1 because shared broker files changed. The normal release pipeline
404
+ builds it after an owner merge. Local previews use the harness copy of the broker.
405
+ An older harness
406
+ gets an update message. For now, open the local URL in your own browser on the
407
+ runner. Or start the agent and server in Cloud runtime.
408
+
409
+ Local checks (build the harness first):
410
+
411
+ ```sh
412
+ node packages/agent-harness/scripts/local-browser-smoke.mjs
413
+ cd packages/workflow-api
414
+ LOCAL_BROWSER_E2E=1 CODING_AGENT_TEST_DATABASE_URL=postgresql://127.0.0.1:55473/local_browser_test \
415
+ pnpm test --runInBand src/services/coding-agents/browser/__tests__/local-runner.pg.test.ts
416
+ ```
417
+
418
+ The smoke check uses real Chromium and a local server. The API check uses a
419
+ separate harness client process, PostgreSQL, the real grant route, browser
420
+ socket, and browser tools. By default, these checks do not call a model backend. The extra
421
+ Chromium check runs only with `LOCAL_BROWSER_E2E=1`. API grant checks run in the
422
+ normal database test suite.
423
+
424
+ For the owner-like Claude Code check, also set `LOCAL_BROWSER_CLAUDE_E2E=1`.
425
+ It needs a signed-in `claude` CLI. It starts a test server through Bash, then
426
+ calls the preview and snapshot tools through a local authenticated MCP fixture.
427
+ The test keeps model output out of logs and checks the page marker. It removes
428
+ the server and temporary files when it finishes. It does not use a live tenant.
429
+
430
+ The agent's preview call authorizes page content from the selected port to be
431
+ sent to all users who can view that chat. The port grant is not proof that the
432
+ agent started that listener. It can select an existing local HTTP service,
433
+ except the blocked harness/platform ports. This uses the agent's existing
434
+ local-network authority: it can already read such a service through its shell
435
+ and return that content in the chat. There is no extra port-confirmation step.
436
+ Use the runner's existing permission mode and chat access controls for that
437
+ authority. The boundary here is the authenticated chat and explicit port grant,
438
+ not ownership of the listening process.
439
+
440
+ The local path supports macOS and Linux with the optional browser packages
441
+ installed. A system Chrome installation alone is insufficient when those
442
+ packages were omitted. Windows local previews are not supported in this release.
443
+ Bind the dev server to `127.0.0.1`; IPv6-only `::1` servers are not supported.