pi-agent-browser-native 0.9.9 → 0.9.10
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.
- package/CHANGELOG.md +13 -0
- package/dist/extensions/agent-browser/index.js +10 -10
- package/docs/ARCHITECTURE.md +6 -6
- package/docs/COMMAND_REFERENCE.md +1 -1
- package/docs/REFERENCE.md +3 -3
- package/docs/RELEASE.md +6 -6
- package/docs/REQUIREMENTS.md +3 -3
- package/docs/SESSION_STORAGE.md +1 -1
- package/docs/SUPPORT_MATRIX.md +21 -21
- package/docs/TOOL_CONTRACT.md +3 -3
- package/package.json +4 -7
- package/scripts/doctor.mjs +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,19 @@
|
|
|
2
2
|
|
|
3
3
|
## Unreleased
|
|
4
4
|
|
|
5
|
+
## 0.9.10 - 2026-11-02
|
|
6
|
+
|
|
7
|
+
<!-- npm-release:unreleased:start -->
|
|
8
|
+
<!-- npm-release:unreleased:end -->
|
|
9
|
+
|
|
10
|
+
- Raise the Pi floor to 1.5.0 (#347) ([5685a6d](https://github.com/fitchmultz/pi-agent-browser-native/commit/5685a6d53d0d6447d222f7e8210991234bde0071))
|
|
11
|
+
|
|
12
|
+
### What's Changed
|
|
13
|
+
|
|
14
|
+
- Raise the Pi floor to 1.5.0 by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/347
|
|
15
|
+
|
|
16
|
+
**Full Changelog**: https://github.com/fitchmultz/pi-agent-browser-native/compare/v0.9.9...v0.9.10
|
|
17
|
+
|
|
5
18
|
## 0.9.9 - 2026-11-02
|
|
6
19
|
|
|
7
20
|
<!-- npm-release:unreleased:start -->
|
|
@@ -35189,7 +35189,7 @@ function getLatestUserMessage(manager) {
|
|
|
35189
35189
|
import { Text as Text2 } from "@earendil-works/pi-tui";
|
|
35190
35190
|
|
|
35191
35191
|
// dist/extensions/agent-browser/lib/pi-tool-rendering.js
|
|
35192
|
-
import {
|
|
35192
|
+
import { Text, truncateToWidth } from "@earendil-works/pi-tui";
|
|
35193
35193
|
|
|
35194
35194
|
// dist/extensions/agent-browser/lib/input-modes/electron.js
|
|
35195
35195
|
init_parsing();
|
|
@@ -35472,12 +35472,9 @@ function colorizeToolOutputLines(outputText, theme, isError) {
|
|
|
35472
35472
|
return isError ? theme.fg("error", line) : theme.fg("toolOutput", line);
|
|
35473
35473
|
});
|
|
35474
35474
|
}
|
|
35475
|
-
function
|
|
35476
|
-
const
|
|
35477
|
-
|
|
35478
|
-
}
|
|
35479
|
-
function formatVisualTruncationNotice(remainingLines, totalLines, theme, width) {
|
|
35480
|
-
const notice = `${theme.fg("muted", `... (${remainingLines} more lines, ${totalLines} total, `)}${formatExpandHint(theme)}${theme.fg("muted", ")")}`;
|
|
35475
|
+
function formatVisualTruncationNotice(hidden, expandKey, theme, width) {
|
|
35476
|
+
const expandHint = `${theme.fg("dim", expandKey)} ${theme.fg("muted", "to expand")}`;
|
|
35477
|
+
const notice = `${theme.fg("muted", `... (${hidden.remainingLines} more lines, ${hidden.totalLines} total, `)}${expandHint}${theme.fg("muted", ")")}`;
|
|
35481
35478
|
return truncateToWidth(notice, Math.max(0, width));
|
|
35482
35479
|
}
|
|
35483
35480
|
function compiledArgs(result) {
|
|
@@ -35647,11 +35644,14 @@ function finalizeAgentBrowserFailure(result, input) {
|
|
|
35647
35644
|
}
|
|
35648
35645
|
var AgentBrowserResultComponent = class {
|
|
35649
35646
|
expanded = false;
|
|
35647
|
+
expandKey = "";
|
|
35650
35648
|
theme;
|
|
35651
35649
|
text = new Text("", 0, 0);
|
|
35652
35650
|
value;
|
|
35653
35651
|
formatKey;
|
|
35654
|
-
setResult(result, options, theme,
|
|
35652
|
+
setResult(result, options, theme, context2) {
|
|
35653
|
+
const { isError } = context2;
|
|
35654
|
+
this.expandKey = context2.keyText("app.tools.expand");
|
|
35655
35655
|
const details = isRecord(result.details) ? result.details : void 0;
|
|
35656
35656
|
const key = [
|
|
35657
35657
|
getPrimaryTextContent(result),
|
|
@@ -35693,7 +35693,7 @@ var AgentBrowserResultComponent = class {
|
|
|
35693
35693
|
const hiddenLineCount = lines.length - TUI_COLLAPSED_OUTPUT_MAX_LINES;
|
|
35694
35694
|
return [
|
|
35695
35695
|
...lines.slice(0, TUI_COLLAPSED_OUTPUT_MAX_LINES),
|
|
35696
|
-
formatVisualTruncationNotice(hiddenLineCount, lines.length, theme, width)
|
|
35696
|
+
formatVisualTruncationNotice({ remainingLines: hiddenLineCount, totalLines: lines.length }, this.expandKey, theme, width)
|
|
35697
35697
|
];
|
|
35698
35698
|
}
|
|
35699
35699
|
invalidate() {
|
|
@@ -44688,7 +44688,7 @@ function executeCode(runtime, invocation) {
|
|
|
44688
44688
|
function registerBrowserTools(runtime) {
|
|
44689
44689
|
const renderResult = (result, options, theme, context2) => {
|
|
44690
44690
|
const component = context2.lastComponent instanceof AgentBrowserResultComponent ? context2.lastComponent : new AgentBrowserResultComponent();
|
|
44691
|
-
component.setResult(result, options, theme, context2
|
|
44691
|
+
component.setResult(result, options, theme, context2);
|
|
44692
44692
|
return component;
|
|
44693
44693
|
};
|
|
44694
44694
|
const renderers = {
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -36,7 +36,7 @@ Pi peers. GitHub/source installs retain the same `prepare` build.
|
|
|
36
36
|
|
|
37
37
|
`orchestration/batch-stdin.ts` owns exact native batch-option filtering and raw-argument-over-stdin selection. Indexed `--omit-command` receipts regain their original-plan command at the native observation boundary, before existing lifecycle, ref, artifact, and redaction reducers. Skipped empty stdin rows retain their native indexes; prepared artifact requests use compact returned-row positions. Recording recovery uses those compact positions for artifact attribution and later-recording actions, preserving unrelated step evidence. Presentation uses index-only public receipts and spills. Canonical finish events retain already-redacted attribution before `BrowserCommandResult.complete` removes reconstructed commands from public per-step details; there is no second replay cache.
|
|
38
38
|
|
|
39
|
-
`agent_browser_tools` inventories/enables five flat specialized tools: action, QA, Electron, UI source, and network source. `lib/tool-surface.ts` registers them once and adds them through Pi's native active-tool API, preserving unrelated tools, explicit host selections, and native selected-tool history. The five advanced direct tools use native `defaultActive: false`, not deferred registration.
|
|
39
|
+
`agent_browser_tools` inventories/enables five flat specialized tools: action, QA, Electron, UI source, and network source. `lib/tool-surface.ts` registers them once and adds them through Pi's native active-tool API, preserving unrelated tools, explicit host selections, and native selected-tool history. The five advanced direct tools use native `defaultActive: false`, not deferred registration. Pi restores transcript-enabled advanced tools natively when resuming default-tool sessions; a narrow additive fallback covers `--no-builtin-tools` resumes, which skip native restoration. It does not deactivate explicit/defaultTools selections or widen filtered catalogs/CLI allowlists; loader, tree and reload retain native selection semantics. It owns no parallel activation journal. QA verdicts, unique accessible select, host Electron lifecycle, and bounded source scans remain specialized capabilities rather than being reduced to raw-command approximations. The former public job DSL and isolated script route are removed.
|
|
40
40
|
|
|
41
41
|
Optional `agent_browser_web_search` remains separately credential/config gated and independent of browser state.
|
|
42
42
|
|
|
@@ -77,7 +77,7 @@ All participating Pi processes must restart with the updated package; `/reload`
|
|
|
77
77
|
|
|
78
78
|
`lib/browser-transcript.ts` defines one canonical `data.event` format and optional once-stored `data.snapshot`. Direct, advanced, code and Electron host operations record begin/finish receipts before dispatch and after observed effects, using outer tool-call ID plus inner index and a unique operation ID. The shared page reducer retains an inaccessible candidate during unresolved work and requires explicit reuse/replace/invalidate/unknown disposition. Ordinary results omit unchanged maps and unrelated artifact receipts; journal events carry redacted artifact-row changes in commit order. Final rendering queues actual spill writes and manifest publication, allowing unrelated small observations to finish while another namespace holds its artifact/lifecycle operation. `lib/orchestration/browser-run/artifact-merge.ts` preserves concurrent three-way manifest updates and recording lifecycle order. Native lifecycle evidence is retained before presentation/export. Failed begin blocks dispatch; failed finish stops dependent work and requires inspection without mutation replay. A named persistent journal requires actual publication even before Pi's first conversation. Disabled/no-file sessions use the native current in-memory ancestry for direct browser work without claiming durability; code still requires a published intent journal. Observation-only artifact receipts are optional without a published journal, so sessionless local results retain complete redacted private spills and selected files. Code lifecycle joins include outer finalization, and the shared generation guard keeps prior-branch observation spills process-private and prevents their artifact publication onto the new branch. JavaScript variables are never persisted.
|
|
79
79
|
|
|
80
|
-
`lib/browser-journal.ts` token-projects published envelopes and ancestry through public Pi file/header/leaf APIs, loading only winning snapshot definitions. Replay retains one structural prefix per native manager/header and published file identity, reusing unchanged metadata or validating only appended bytes. Rotation, truncation, native reseed, same-size timestamp changes and failures fall back to full validation. Selected event and winning snapshot bodies are reread; this append-only index is neither a ref cache nor a replacement for publication receipts. It captures the selected leaf before asynchronous reads and validates that same branch through public `getEntry()` ancestry on both hosts. Capture-local admission reuses a validated append-only prefix while checking endpoint identity/parent and new suffixes; publication/durability checks remain independent. Startup/tree restoration uses one queued captured replay for branch state and cleanup leases, with one per-session launch-configuration fold. Stock official
|
|
80
|
+
`lib/browser-journal.ts` token-projects published envelopes and ancestry through public Pi file/header/leaf APIs, loading only winning snapshot definitions. Replay retains one structural prefix per native manager/header and published file identity, reusing unchanged metadata or validating only appended bytes. Rotation, truncation, native reseed, same-size timestamp changes and failures fall back to full validation. Selected event and winning snapshot bodies are reread; this append-only index is neither a ref cache nor a replacement for publication receipts. It captures the selected leaf before asynchronous reads and validates that same branch through public `getEntry()` ancestry on both hosts. Capture-local admission reuses a validated append-only prefix while checking endpoint identity/parent and new suffixes; publication/durability checks remain independent. Startup/tree restoration uses one queued captured replay for branch state and cleanup leases, with one per-session launch-configuration fold. Stock official Pi still eagerly loads native history before extension startup. `lib/browser-legacy-projection.ts` and its shared field projection normalize historical receipts read-only into this same canonical reducer at the journal boundary. Normal resume keeps the original bytes and locator; mixed-format ancestry, confirmation settings/provenance and cleanup ownership remain branch-relative. Non-winning legacy maps are discarded after each receipt. Native event validation cannot downgrade to the legacy path. `lib/browser-session-conversion.ts` reuses that decoder only when an operator explicitly requests a validated stopped separate archive copy. Native generation checks use PID/start and socket identity, never saved URL or delta revision alone. Filtered/helper captures share this check. Small owner-qualified launch receipts retain observed restore-key provenance; restart verifies the current native generation and key before treating that provenance as live. Full storage, migration and consumer-memory boundaries are documented in [`SESSION_STORAGE.md`](SESSION_STORAGE.md).
|
|
81
81
|
|
|
82
82
|
### Canonical observations and image geometry
|
|
83
83
|
|
|
@@ -115,7 +115,7 @@ Global/override package profile names with `policy: "always"` and executable def
|
|
|
115
115
|
|
|
116
116
|
### Prompt guidance budget
|
|
117
117
|
|
|
118
|
-
Use Pi-native `promptGuidelines`, tool declarations, and named `systemPromptOptions.sections` contributions. Do not return a replacement full system prompt from `before_agent_start`: it breaks additive declaration anchoring. Official Pi
|
|
118
|
+
Use Pi-native `promptGuidelines`, tool declarations, and named `systemPromptOptions.sections` contributions. Do not return a replacement full system prompt from `before_agent_start`: it breaks additive declaration anchoring. Official Pi and the fork use this same composition; hosted programmatic tool calling, async provider lifecycle, image-detail overrides, or model-specific payload edits are not package dependencies. Prefix stability is not proof of a cache hit.
|
|
119
119
|
|
|
120
120
|
Browser instructions come from one full source assembled from `lib/playbook.ts` and current trusted config. Shared rules and all advanced tool guidelines are delivered together, rather than maintaining a short eager summary beside a hidden manual. Managed hosts defer this full group; stock hosts receive it eagerly. Tool registrations retain concise descriptions and schemas without duplicate `promptGuidelines`.
|
|
121
121
|
|
|
@@ -136,7 +136,7 @@ The published package should load from the `pi` manifest in `package.json`.
|
|
|
136
136
|
Local checkout validation has two intentional modes:
|
|
137
137
|
|
|
138
138
|
- **Checkout-only extension mode:** use explicit CLI loading such as `pi --approve --no-extensions -e .` from the intentionally trusted repository root. This disables automatic extension loading and avoids duplicate `agent_browser` registrations, but settings, configured package resolution, and other resource types remain active. Temporary `HOME` and `PI_CODING_AGENT_DIR` directories isolate test settings; `PI_OFFLINE=1` disables automatic startup network/update operations. Omit `--approve` only when testing Project Trust.
|
|
139
|
-
- **Configured-source lifecycle mode:** configure exactly one active checkout or package source in Pi settings and launch plain `pi` for manual validation, or run the automated harness that launches with `--approve`. This is the right mode for validating `/reload` and exact-session relaunch because those lifecycle checks exercise discovered/configured resources. Focused extension harness tests validate branch-backed `session_tree` rehydration and cleanup ownership. Before shipping, maintainers also run `npm run verify -- lifecycle` (same semantics under automation, using Pi
|
|
139
|
+
- **Configured-source lifecycle mode:** configure exactly one active checkout or package source in Pi settings and launch plain `pi` for manual validation, or run the automated harness that launches with `--approve`. This is the right mode for validating `/reload` and exact-session relaunch because those lifecycle checks exercise discovered/configured resources. Focused extension harness tests validate branch-backed `session_tree` rehydration and cleanup ownership. Before shipping, maintainers also run `npm run verify -- lifecycle` (same semantics under automation, using Pi's `--approve --session-id` to reopen the exact JSONL session) plus the live-site checks in [`RELEASE.md`](RELEASE.md#pre-release-checks); `npm publish` enforces `npm run verify -- release` via `prepublishOnly` unless scripts are skipped.
|
|
140
140
|
|
|
141
141
|
The repo should not add a repo-local `.pi/extensions/` autoload shim as the documented checkout path.
|
|
142
142
|
|
|
@@ -201,7 +201,7 @@ Ownership rule:
|
|
|
201
201
|
|
|
202
202
|
Practical policy:
|
|
203
203
|
|
|
204
|
-
- preserve the current branch-visible extension-managed session across `/reload`, exact-session relaunch, `/resume`, and Pi
|
|
204
|
+
- preserve the current branch-visible extension-managed session across `/reload`, exact-session relaunch, `/resume`, and Pi `session_tree` branch transitions so persisted sessions can keep following the live browser after lifecycle changes
|
|
205
205
|
- close the active extension-managed session when the originating `pi` process quits, while leaving explicit caller-provided sessions alone; a managed fork restart is not a quit (see below)
|
|
206
206
|
- after branch restore, use the existing locked daemon inspection to distinguish a confirmed inactive wrapper-owned daemon from a live, unknown, or unavailable one. For compatible automatic managed restore only, keep the pending reopen in ordered session page state and persist it as `sessionTabReopenPending`. Non-page calls such as `tab list` can start a daemon without fulfilling it; explicit HTTP reads leave the managed browser and pending reopen untouched, including across branch/reload replay. Before the first current-page operation (`get url`, history commands and relative `pushstate` included), reopen the complete recorded URL with native `open`, invalidate old refs with the existing `page-transition` state, and verify the actual tab. Explicit URL reads and all-read batches skip managed ownership changes and browser helpers entirely; native owns their HTTP fetch and validation. Native `open` resets frame scope. Consume the obligation on that attempt or an executed explicit context/navigation/close command, not an unreached batch row; a failed open does not permit repeated navigation of a now-live browser. After the reopen CLI starts, cancellation returns a structured `aborted` result through the ordinary result path with the exact namespace/session, consumed marker and ref invalidation; it does not throw away replay state or run later browser helpers. Cancellation before the CLI starts does not consume the pending reopen. Internal URLs retain their fragments while tab/ref comparisons remain fragment-insensitive and presentation keeps normal redaction. Older transcripts cannot recover a fragment they did not record. Caller-owned/attached browsers and restore-disabled sessions do not take this path; live wrong-tab recovery still only selects an existing target. Reopening reloads the URL, not unsaved forms, JavaScript memory, or history. There is no second restore store or lifecycle lock.
|
|
207
207
|
- set an idle timeout on extension-managed sessions as a backstop for abnormal exits or cleanup failures, and apply that same `AGENT_BROWSER_IDLE_TIMEOUT_MS` value to every subprocess targeting that owned session (including wrapper helper snapshots, tab lists, and navigation-summary reads); caller-owned sessions instead retain native config/environment idle policy because changing the launch environment between calls can make upstream restart the background browser, discard the active tab, and invalidate fresh refs
|
|
@@ -241,7 +241,7 @@ This is primarily about ownership clarity and avoiding surprise, not adding a he
|
|
|
241
241
|
|
|
242
242
|
Native Pi lifecycle callbacks and existing queues retain ownership-aware shutdown/reload/restart behavior. Shared root and caller-owned browsers are not closed on Pi quit; wrapper-owned managed/fresh and Electron resources keep UUID/branch-qualified cleanup. An ordinary session fork does not inherit its parent's cleanup rights. Close or clean up owned resources before disabling/removing the extension: native reload after removal has no browser handover guarantee. Forced concurrent SDK reload and recovery after failed off-branch cleanup are not fully qualified lifecycle guarantees.
|
|
243
243
|
|
|
244
|
-
Native close/save and explicit URL reopen remain the persistence path, not a live browser snapshot. Page JavaScript, unsaved forms, history, IndexedDB and live recordings are not serialized by this extension. Neither supported
|
|
244
|
+
Native close/save and explicit URL reopen remain the persistence path, not a live browser snapshot. Page JavaScript, unsaved forms, history, IndexedDB and live recordings are not serialized by this extension. Neither supported target uses Browser checkpoint or fork metadata/revision hooks; retained legacy journal decoding remains confined to stopped-copy conversion.
|
|
245
245
|
|
|
246
246
|
### Launch flags
|
|
247
247
|
|
|
@@ -11,7 +11,7 @@ Related docs:
|
|
|
11
11
|
|
|
12
12
|
## Purpose
|
|
13
13
|
|
|
14
|
-
Requires Pi 1.
|
|
14
|
+
Requires Pi 1.5.0 or newer; official and fork hosts are qualified independently.
|
|
15
15
|
|
|
16
16
|
Provide a local, repo-readable command reference for the native `agent_browser` tool.
|
|
17
17
|
|
package/docs/REFERENCE.md
CHANGED
|
@@ -8,7 +8,7 @@ It is for Pi users who want agents to browse sites, inspect pages, click through
|
|
|
8
8
|
|
|
9
9
|
## Pi release qualification
|
|
10
10
|
|
|
11
|
-
CI qualifies the latest stable official Pi and latest maintained fork `main`, resolving their version/commit once per run and retaining SDK/CLI identity evidence. Locked development dependencies are reproducible build snapshots, not qualification targets; runtime peers remain wildcard.
|
|
11
|
+
CI qualifies the latest stable official Pi and latest maintained fork `main`, resolving their version/commit once per run and retaining SDK/CLI identity evidence. Locked development dependencies are reproducible build snapshots, not qualification targets; runtime peers remain wildcard. `npm run check:compat` checks the installed candidate SDK/CLI identity, typechecks, runs the existing offline tests (including the native Pi pipeline with a controlled provider and fake browser), and tests a packed runtime-only installation through both the SDK and the actual bundled RPC CLI. It does not substitute a fork SDK while leaving official types or child CLI installed.
|
|
12
12
|
|
|
13
13
|
Run in an empty HOME with a **short** TMPDIR outside your real home. Long temporary paths can exceed macOS's 103-byte Unix socket limit; keep the fixture's socket safety checks intact. Native lifecycle controls, live upstream help sampling, lifecycle dogfood, and platform qualification remain the separate gates documented below. A Pi-only compatibility run uses no live browser profiles, credentials, or agent-browser fork, and does not certify those external integrations.
|
|
14
14
|
|
|
@@ -105,7 +105,7 @@ Artifact results show known requested paths separately from reported/resolved lo
|
|
|
105
105
|
|
|
106
106
|
## Fastest way to try it
|
|
107
107
|
|
|
108
|
-
Use Node 24.21.0 or newer and Pi 1.
|
|
108
|
+
Use Node 24.21.0 or newer and Pi 1.5.0 or newer. This package keeps optional Pi core imports as wildcard `peerDependencies` because Pi package docs require the host Pi install to provide those packages, retains a locked Pi development snapshot while qualifying the latest official/fork graphs, and makes Pi hosts below 1.5.0 a setup failure through `pi-agent-browser-doctor`. There are no compatibility shims for older Pi releases.
|
|
109
109
|
|
|
110
110
|
Install upstream `agent-browser` first and make sure it is on `PATH`:
|
|
111
111
|
|
|
@@ -792,7 +792,7 @@ Install upstream `agent-browser`, then install dependencies:
|
|
|
792
792
|
npm install
|
|
793
793
|
```
|
|
794
794
|
|
|
795
|
-
Use the npm version declared in `package.json` `packageManager` when refreshing `package-lock.json` so optional-platform lockfile metadata does not drift. Use Node 24.21.0 and Pi 1.
|
|
795
|
+
Use the npm version declared in `package.json` `packageManager` when refreshing `package-lock.json` so optional-platform lockfile metadata does not drift. Use Node 24.21.0 and Pi 1.5.0 or newer for lifecycle and interactive browser smokes; locked Pi devDependencies are reproducible build snapshots, not qualification targets. CI selects the once-resolved latest official graph for native lifecycle and package smoke, and independently qualifies the latest maintained fork. See [Environment and automation pitfalls](RELEASE.md#environment-and-automation-pitfalls) in `docs/RELEASE.md`.
|
|
796
796
|
|
|
797
797
|
Checkout-only extension smoke test:
|
|
798
798
|
|
package/docs/RELEASE.md
CHANGED
|
@@ -36,9 +36,9 @@ Linux/macOS, declared Node floors, official/fork host and consumer-artifact chec
|
|
|
36
36
|
|
|
37
37
|
Docs/workflow-only changes may reuse prior live/platform evidence when the complete compiled runtime, runtime dependencies and relevant tests are unchanged. Changed published files require a new retained tarball checked by `verify-package.mjs --smoke-pi`, including runtime-only SDK and actual CLI loading. Publish those exact checked bytes without repacking.
|
|
38
38
|
|
|
39
|
-
## Pi 1.0 upgrade and qualification
|
|
39
|
+
## Pi 1.5.0 upgrade and qualification
|
|
40
40
|
|
|
41
|
-
This contract requires Pi 1.
|
|
41
|
+
This contract requires Pi 1.5.0. Do not install or activate it in running pre-1.5 sessions; coordinate the runtime cutover and restart participating agents first. Keep runtime activation separate from isolated checkout/SDK qualification. Preserve auth/profile/state files, explicit artifacts and Pi journals when updating or rolling back; browser mutations are not reversible through a package rollback.
|
|
42
42
|
|
|
43
43
|
Qualify the exact official and fork host graphs independently, including SDK and actual CLI loading, explicit/defaultTools/loader/initial-resume/tree/reload selections, structured success/failure/redaction and unchanged JSON. Inspect regular and fullscreen native TUI results, including failures and images. Keep the existing 250 ms import/factory and 1,000 ms lock budgets; synthetic research timings are not final-source release evidence or universal performance guarantees. Apply normal required macOS/Linux release gates; Windows is separately labeled best-effort. Host identity and actual supported APIs, not a version label alone, determine qualification.
|
|
44
44
|
|
|
@@ -52,9 +52,9 @@ Rollback is package-level: restore the previously installed 0.6 package from you
|
|
|
52
52
|
|
|
53
53
|
### Changed-path qualification
|
|
54
54
|
|
|
55
|
-
The minimum Pi runtime is 1.
|
|
55
|
+
The minimum Pi runtime is 1.5.0, matching the native APIs the tool contract uses. Wildcard peers remain host-owned dependency declarations, not support for older runtimes.
|
|
56
56
|
|
|
57
|
-
Qualify official Pi
|
|
57
|
+
Qualify official Pi and the fork independently with the existing host/package/lifecycle infrastructure. Required evidence for the redesign includes compact schema and additive activation/history, native prompt sections, shared direct/code auth continuity, fresh JavaScript globals, selected real images and conservative geometry, visible handled failures/exact recovery, real cross-process helper/action and whole-cell ordering, cancellation/reaping, and ordered transition replay after interruption/branch changes. Retain native batch and advanced action/QA/Electron/source outcome coverage. Small synthetic timing comparisons are not universal performance claims or sandbox certification.
|
|
58
58
|
|
|
59
59
|
Routine GitHub PR and release-call checks include a nonblocking Windows build/import/process smoke; deep official/fork Windows qualification and its environment self-check are manual-only. Retain every failed attempt, including historical waived diagnostics, without claiming a Windows pass from an aggregate that ignored failures. These focused checks complement, rather than replace, the local release and publication gates.
|
|
60
60
|
|
|
@@ -139,7 +139,7 @@ Releases that change the Pi agent runtime also require interactive `tmux`-driven
|
|
|
139
139
|
|
|
140
140
|
When reviewing saved session JSONL after a failed smoke or QA reclassification, expect browser tool rows to carry `isError: true` whenever `details.resultCategory` is `failure`. The model-visible observation must also report failure. Canonical JSON stays parseable and unchanged. Final public results return `isError` directly, with a prose failure notice outside explicit JSON, so Pi's transcript matches the wrapper contract ([`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details)). Preserve a normal Pi session directory for those checks; avoiding `--no-session` keeps this evidence intact ([`AGENTS.md`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/AGENTS.md) preferred validation workflow).
|
|
141
141
|
|
|
142
|
-
The configured-source lifecycle regression harness is required before release because it launches an interactive Pi 1.
|
|
142
|
+
The configured-source lifecycle regression harness is required before release because it launches an interactive Pi 1.5.0+ process under `tmux` with `--approve` and validates `/reload`, full relaunch with the same exact `--session-id`, managed-session continuity, persisted artifacts, compiled-entrypoint pickup after process restart, and native returned-failure behavior. Branch-backed `session_tree` rehydration and cleanup ownership are validated by focused extension harness tests:
|
|
143
143
|
|
|
144
144
|
```bash
|
|
145
145
|
npm run verify -- lifecycle
|
|
@@ -341,7 +341,7 @@ The default unit suite also runs `agentBrowserExtension passes through core comm
|
|
|
341
341
|
|
|
342
342
|
### Native lifecycle qualification
|
|
343
343
|
|
|
344
|
-
[`test/agent-browser.native-lifecycle.test.mjs`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/test/agent-browser.native-lifecycle.test.mjs) is the model-free portable SDK lifecycle gate. It loads the compiled extension through real native resource discovery and executes browser tools against loopback fixtures. Qualify official and fork Pi
|
|
344
|
+
[`test/agent-browser.native-lifecycle.test.mjs`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/test/agent-browser.native-lifecycle.test.mjs) is the model-free portable SDK lifecycle gate. It loads the compiled extension through real native resource discovery and executes browser tools against loopback fixtures. Qualify official and fork Pi graphs independently: no removed fork-only APIs are required. It covers branch/reload continuity, detached and queued code cancellation/ordering, managed cleanup, caller-owned attachment and off-branch routing, failed journal-begin refusal during recording, and root save/reopen across fresh checkout/state-directory inodes. This is lifecycle evidence, not serialization of live page JavaScript, forms or recordings.
|
|
345
345
|
|
|
346
346
|
Run non-root with an isolated HOME/socket root and stock `agent-browser`, Chrome for Testing and ffmpeg, without personal profiles or inherited credentials/configuration. The browser directory must contain binaries, never a personal profile.
|
|
347
347
|
|
package/docs/REQUIREMENTS.md
CHANGED
|
@@ -16,7 +16,7 @@ Define the product requirements and constraints for `pi-agent-browser-native`.
|
|
|
16
16
|
## Runtime requirements
|
|
17
17
|
|
|
18
18
|
- Node.js 24.21.0 or newer.
|
|
19
|
-
- Pi 1.
|
|
19
|
+
- Pi 1.5.0 or newer.
|
|
20
20
|
- A separate stable `agent-browser` installation, version 0.35.0 or newer, available on `PATH`.
|
|
21
21
|
|
|
22
22
|
## Product requirements
|
|
@@ -73,7 +73,7 @@ Define the product requirements and constraints for `pi-agent-browser-native`.
|
|
|
73
73
|
|
|
74
74
|
- Keep the always-on interface compact: `agent_browser { args, stdin?, outputPath?, timeoutMs?, sessionMode? }`, strict-JSON `agent_browser_code { code, session?, namespace?, timeoutMs?, outputPath? }`, and `agent_browser_tools { enable? }`.
|
|
75
75
|
- Preserve the complete native command surface through one CLI executor. Native batch handles fixed sequences; code handles branches/loops/aggregation. Remove the redundant public job DSL and old isolated-script execution instead of carrying parallel legacy runtimes.
|
|
76
|
-
- Register advanced action, QA, Electron, UI-source, and network-source tools once with native `defaultActive: false`. Enable additively through Pi's native tool selection/history without removing unrelated tools. Preserve explicit/defaultTools selections, loader activation, initial resume, tree navigation and reload; retain only the additive fallback needed for
|
|
76
|
+
- Register advanced action, QA, Electron, UI-source, and network-source tools once with native `defaultActive: false`. Enable additively through Pi's native tool selection/history without removing unrelated tools. Preserve explicit/defaultTools selections, loader activation, initial resume, tree navigation and reload; retain only the additive fallback needed for `--no-builtin-tools` resumes, which skip native restoration. Use flat schemas and return executable next actions naming the actual tool.
|
|
77
77
|
- Preserve unique visible accessible dropdown selection, semantic/ref recovery, truthful QA verdicts (including ambiguous error-buffer residue), attached diagnostic preservation/defaults, Electron process/profile ownership, and bounded source scans. Raw diagnostic-read success is not a QA verdict, and source hints remain candidates rather than authoritative blame.
|
|
78
78
|
- Code runs in a fresh permissioned Node child with no host APIs/imports, null-prototype task globals, JSON-only bounded IPC, serial native calls, and explicit JSON/image output. Keep current source/output/call/deadline limits. Browser/authentication persists under existing native ownership and configuration; JavaScript variables do not. Allow ordinary native commands including batch/auth/profile/state/connect/close, but prevent changes to the fixed parent-selected identity and namespace-wide close within a cell.
|
|
79
79
|
- Hold a cooperating-process execution lock keyed by actual socket context, canonical namespace, and session across direct helper/action work or the entire code cell. Use ordered multi-identity acquisition for replacement/cleanup and a namespace barrier for direct close-all. This does not coordinate humans, third-party clients, or older versions, guarantee atomic browser actions, or provide rollback.
|
|
@@ -128,7 +128,7 @@ The design should comfortably support workflows such as:
|
|
|
128
128
|
## Implications for the implementation
|
|
129
129
|
|
|
130
130
|
- Package-manifest behavior matters more than repo-local development wiring.
|
|
131
|
-
- The extension uses native Pi tool registration/activation and named prompt sections rather than replacing the full system prompt. Require Pi 1.
|
|
131
|
+
- The extension uses native Pi tool registration/activation and named prompt sections rather than replacing the full system prompt. Require Pi 1.5.0 and qualify official and fork hosts independently. Retain the instruction-group collector when supported and identical full native prompt-section fallback otherwise; hosted provider orchestration is not required.
|
|
132
132
|
- The wrapper should stay thin, with upstream `agent-browser` remaining the source of truth for command semantics.
|
|
133
133
|
- Successful and failed tool outcomes should surface bounded machine-readable fields on Pi-facing `details` (`resultCategory`, `successCategory`, `failureCategory`, optional structured `nextActions`, optional `pageChangeSummary` with explicit observed-vs-dispatched evidence and per-step summaries on `batch`, optional `artifactVerification` with the same shape on successful `batchSteps[]` rows, optional `outputFile`, optional `timeoutPartialProgress`) so agents can branch without parsing prose; browser-bearing `nextActions` must preserve a known session identity so recovery cannot inspect an unrelated implicit session; stateful commands (`auth`, `cookies`, `storage`, `dialog`, `frame`, `state`) plus other structured diagnostics (for example `network`, `diff`, `trace`, `stream`, `dashboard`, `chat`) and `batch` should redact secret-bearing payloads in model-facing `details.data`, including the compact per-step `batch` roll-up on the parent result (full per-step payloads live on `batchSteps[]`). Dialog/prompt-related timeouts should be bounded with recovery `nextActions`; non-dialog timeouts should prefer best-effort per-step progress and retry payloads when a plan is available; no-op scrolls should expose no-movement state instead of only an upstream success boolean; explicit page/container scroll helpers should expose before/after movement evidence. The contract lives in [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details), enums and classifier precedence live in `extensions/agent-browser/lib/results/categories.ts` and `contracts.ts`, and presentation-time summaries, redaction, network request follow-ups, and artifact verification rollups are assembled in `extensions/agent-browser/lib/results/presentation.ts` (`buildPageChangeSummary`, command taxonomy predicates from `command-taxonomy.ts`, `redactPresentationData`, `buildArtifactVerificationSummary`, `buildBatchPresentation`).
|
|
134
134
|
- User-facing docs belong in `README.md` and the canonical published files under `docs/`.
|
package/docs/SESSION_STORAGE.md
CHANGED
|
@@ -16,7 +16,7 @@ A saved URL or map cannot prove the native browser survived. Reuse checks native
|
|
|
16
16
|
|
|
17
17
|
Replay locates the journal through Pi's public session file, UUID and selected leaf. It captures that leaf before asynchronous reads and uses the same boundary for file and public native ancestry validation, so concurrent appends cannot change the branch being replayed. It validates complete newline-terminated records. A record up to 1 MiB with nesting within 1024 levels and at most 64 Ki structural bytes (`{`, `[`, `,` or `:` outside strings) uses native JSON, which briefly holds that record's text and parsed value, a few MiB at most. Larger or denser records and any native rejection use the token projector with unpacked discarded strings, fed in the same 64 KiB chunks as file reads, so both paths accept the same records and report the same first error. A cold restore frames and validates the whole journal. Subsequent restores on the same native manager retain only complete-record structural metadata: an unchanged file reuses that index, and an append scans from the last complete record, including any previously incomplete tail. Locator/header-object changes, rotation, truncation, same-size timestamp changes and failed reads or replay discard the index and use the full validating scanner. The index follows Pi's documented append-only entry contract; native reseeding replaces its header object even when the UUID stays the same. External prefix rewrites must be reopened through Pi rather than disguised as appends to its live journal. This is not an adversarial file-integrity guarantee. Each restore still projects selected envelopes, follows ancestry and rereads winning snapshot bodies; it never caches refs or browser outcomes. An incomplete live tail remains uncommitted. Public `getEntry()` supplies structural ancestry checks on both supported hosts. Capture-local admission validates ancestry through the root, then reuses that append-only prefix after indexed endpoint identity/parent checks. New suffixes still reject missing/cyclic ancestry and unrelated branches; session/generation changes invalidate admission. Behind-host mutation of an old ancestor without native reseed/generation change is outside this append-only contract. Durable replay/append proofs remain independent: prefix reuse does not replace publication receipts or trust an unpublished selected leaf. No writable manager or private core storage is used.
|
|
18
18
|
|
|
19
|
-
Official Pi
|
|
19
|
+
Official Pi eagerly loads its own native journal before extension startup. This extension reduces browser write duplication and bounds extension recovery on that host; complete heap-independent host loading requires adoption of the native core repair. A caller-requested individual snapshot/result still must fit its consumer's memory. This is not an unlimited model-context or single-value API.
|
|
20
20
|
|
|
21
21
|
Artifact events persist row upserts/removals in journal order. The internal recent view defaults to 100 rows; it is separate from cumulative journal size and the independent recording reservation/tombstone journal. Artifact upserts are credential-redacted before persistence. Tool `details.artifactManifest` contains only changed or referenced receipts for that invocation, including evictions observed during that call. Retention summaries and close cleanup guidance can describe the internal recent view without copying it into every result.
|
|
22
22
|
|
package/docs/SUPPORT_MATRIX.md
CHANGED
|
@@ -31,23 +31,23 @@ When upstream ships a new `agent-browser` or the inventory changes:
|
|
|
31
31
|
|
|
32
32
|
Native text and artifact ownership: the registered artifact owner covers empty-row screenshot alignment, nonscreenshot placeholders and bail truncation; the upgrade owner covers one-copy failed explicit text. The text/presentation owners cover cookie/storage format redaction across content, details, complete spills and exports, effective raw/stdin batch intent and native JSON all-entry maps. Real-native cases exercise screenshot paths, explicit/shorthand sensitive-key storage reads, empty-name cookies and CLI true/false helper continuity over opposite env/config defaults. Debug false creates no native log with clean or opposite defaults; later calls retain native inheritance. Native unescaped multiline all-entry/raw-batch text retains the documented heuristic ceiling; structured JSON provides the unambiguous storage boundary.
|
|
33
33
|
|
|
34
|
-
The compact direct/code/loader surface replaces public multimode inputs while retaining native commands and advanced outcomes. This section describes the implementation contract; dated evidence below does not qualify
|
|
35
|
-
|
|
36
|
-
| Area | Contract and verification target
|
|
37
|
-
| ------------------------ |
|
|
38
|
-
| RQ-0064 fixed workflows | Public job DSL removed; native `batch --bail` preserves fixed ordering, waits, explicit assertions, paced keyboard/wait rows, and timeout partial progress. Code handles branches/loops.
|
|
39
|
-
| RQ-0065 QA | Flat `agent_browser_qa` preserves visible assertions, attached-buffer scope, diagnostic residue ambiguity, actionable/benign classification, and actual pass/fail. Fail-fast receipts separate failed checks from later `notRunChecks`; incomplete/timeout evidence stays unverified and execution counts without receipts remain unknown.
|
|
40
|
-
| RQ-0066 / RQ-0067 source | Flat source/network tools retain bounded host scans and candidates-only semantics even in browser-only hosts.
|
|
41
|
-
| RQ-0068 recipes | No recipe registry, persistent JavaScript, second driver, or interpreter dependency.
|
|
42
|
-
| RQ-0072 refs | Page-scoped ref checks scan effective raw/stdin batch plans through every snapshot. A snapshot clears the invalidation latch, but a later page-changing step sets it again even when no refs precede that snapshot; later guarded ref use fails before spawn unless another snapshot intervenes. Same-snapshot fill and role-checked form-control exceptions remain. [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details), `test/agent-browser.extension-ref-guards.test.ts` own this contract.
|
|
43
|
-
| Native indexed batches | Exact `--omit-command` preserves index-only public receipts and spills with ordinary credential/error redaction, ordered close/reopen/ref state, and artifact verification. Original native indexes include skipped empty stdin rows; artifact requests and recording-recovery merges use compact returned-row positions, retaining unrelated artifacts and later-recording actions. Recording `outputPath` receipts use redacted internal attribution; every returned result, including unconfirmed finishes, omits step commands. Raw argv still overrides stdin. `test/agent-browser.batch-fidelity.test.ts` owns live direct/code/input/lifecycle/artifact proof on natives with `--omit-command` (0.40.0+; older supported natives skip that case); `test/agent-browser.presentation-diagnostics.test.ts` owns full-spill redaction; `test/agent-browser.storage-recovery.test.ts` owns unconfirmed-finish omission.
|
|
44
|
-
| RQ-0096 Electron | Flat lifecycle tool preserves app/process/profile ownership and cancellation; native browser/code operations reuse its returned session. CDP readiness/liveness requires a nonempty Browser/browser string. Restored cleanup requires the launch-time process start identity and fails closed without a match. Managed fork restart dispositions `handoff`/`provisional` keep active branch-visible launches, profiles, and managed sessions for the replacement worker; `release` and absent dispositions clean as quit ([`ELECTRON.md`](ELECTRON.md)).
|
|
45
|
-
| RQ-0142 code | Fresh permissioned Node child over persistent parent-selected browser; explicit JSON/current-cell image output, visible failures/counts, ordinary auth/config/environment, ordered Pi intent/completion transitions, child cancellation/reaping, no legacy public execution.
|
|
46
|
-
| Hotpath boundaries | Unrelated tools/harmless Bash return before prompt policy. Latest raw user intent is seeded on start/tree, updated by `message_end` and refreshed after native content replacement. Captured admission uses a validated append-only prefix; one queued replay restores branch/lease state and folds per-session launch settings once. Per-row renderer memoization skips unchanged formatting. No broad config/trust/history cache, new wait/timer or budget increase.
|
|
47
|
-
| Shared ordering | Actual socket/namespace/session lock spans helper/action or entire cell; sorted identity sets for replacement/cleanup and namespace barrier for direct close-all. Requires every participating Pi to run the updated package; no human/third-party/older-version guarantee or transaction.
|
|
48
|
-
| Lightpanda engine | Chrome remains default; separately installed Lightpanda is opt-in. `--engine` uses existing managed fresh-launch recovery; effective CLI/env/config Lightpanda omits wrapper Chrome profile/executable defaults while preserving native choices. Positively identified images are text-rendered with unknown geometry, not visual/coordinate parity. No automatic fallback. `test/agent-browser.runtime.test.ts`, `test/agent-browser.shared-defaults.test.ts`, and `test/agent-browser.screenshot-geometry.test.ts` own the regressions; [limits](COMMAND_REFERENCE.md#lightpanda-engine).
|
|
49
|
-
| Observation and geometry | Canonical bounded JSON/prose/code/native `structuredContent` observations expose exact recovery and receipts, with native namespace/output-schema metadata and canonical returned `isError`; complete observation spills preserve large output. Image dimensions/CSS viewport/DPR/crop/scroll/frame evidence is measured or explicitly unknown; no viewport-coordinate assumptions for full-page/element images.
|
|
50
|
-
| Pi integration | Pi 1.0 floor with independently qualified official/fork graphs. Five advanced direct tools use native `defaultActive: false`; a narrow additive
|
|
34
|
+
The compact direct/code/loader surface replaces public multimode inputs while retaining native commands and advanced outcomes. This section describes the implementation contract; dated evidence below does not qualify the current code.
|
|
35
|
+
|
|
36
|
+
| Area | Contract and verification target |
|
|
37
|
+
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
38
|
+
| RQ-0064 fixed workflows | Public job DSL removed; native `batch --bail` preserves fixed ordering, waits, explicit assertions, paced keyboard/wait rows, and timeout partial progress. Code handles branches/loops. |
|
|
39
|
+
| RQ-0065 QA | Flat `agent_browser_qa` preserves visible assertions, attached-buffer scope, diagnostic residue ambiguity, actionable/benign classification, and actual pass/fail. Fail-fast receipts separate failed checks from later `notRunChecks`; incomplete/timeout evidence stays unverified and execution counts without receipts remain unknown. |
|
|
40
|
+
| RQ-0066 / RQ-0067 source | Flat source/network tools retain bounded host scans and candidates-only semantics even in browser-only hosts. |
|
|
41
|
+
| RQ-0068 recipes | No recipe registry, persistent JavaScript, second driver, or interpreter dependency. |
|
|
42
|
+
| RQ-0072 refs | Page-scoped ref checks scan effective raw/stdin batch plans through every snapshot. A snapshot clears the invalidation latch, but a later page-changing step sets it again even when no refs precede that snapshot; later guarded ref use fails before spawn unless another snapshot intervenes. Same-snapshot fill and role-checked form-control exceptions remain. [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details), `test/agent-browser.extension-ref-guards.test.ts` own this contract. |
|
|
43
|
+
| Native indexed batches | Exact `--omit-command` preserves index-only public receipts and spills with ordinary credential/error redaction, ordered close/reopen/ref state, and artifact verification. Original native indexes include skipped empty stdin rows; artifact requests and recording-recovery merges use compact returned-row positions, retaining unrelated artifacts and later-recording actions. Recording `outputPath` receipts use redacted internal attribution; every returned result, including unconfirmed finishes, omits step commands. Raw argv still overrides stdin. `test/agent-browser.batch-fidelity.test.ts` owns live direct/code/input/lifecycle/artifact proof on natives with `--omit-command` (0.40.0+; older supported natives skip that case); `test/agent-browser.presentation-diagnostics.test.ts` owns full-spill redaction; `test/agent-browser.storage-recovery.test.ts` owns unconfirmed-finish omission. |
|
|
44
|
+
| RQ-0096 Electron | Flat lifecycle tool preserves app/process/profile ownership and cancellation; native browser/code operations reuse its returned session. CDP readiness/liveness requires a nonempty Browser/browser string. Restored cleanup requires the launch-time process start identity and fails closed without a match. Managed fork restart dispositions `handoff`/`provisional` keep active branch-visible launches, profiles, and managed sessions for the replacement worker; `release` and absent dispositions clean as quit ([`ELECTRON.md`](ELECTRON.md)). |
|
|
45
|
+
| RQ-0142 code | Fresh permissioned Node child over persistent parent-selected browser; explicit JSON/current-cell image output, visible failures/counts, ordinary auth/config/environment, ordered Pi intent/completion transitions, child cancellation/reaping, no legacy public execution. |
|
|
46
|
+
| Hotpath boundaries | Unrelated tools/harmless Bash return before prompt policy. Latest raw user intent is seeded on start/tree, updated by `message_end` and refreshed after native content replacement. Captured admission uses a validated append-only prefix; one queued replay restores branch/lease state and folds per-session launch settings once. Per-row renderer memoization skips unchanged formatting. No broad config/trust/history cache, new wait/timer or budget increase. |
|
|
47
|
+
| Shared ordering | Actual socket/namespace/session lock spans helper/action or entire cell; sorted identity sets for replacement/cleanup and namespace barrier for direct close-all. Requires every participating Pi to run the updated package; no human/third-party/older-version guarantee or transaction. |
|
|
48
|
+
| Lightpanda engine | Chrome remains default; separately installed Lightpanda is opt-in. `--engine` uses existing managed fresh-launch recovery; effective CLI/env/config Lightpanda omits wrapper Chrome profile/executable defaults while preserving native choices. Positively identified images are text-rendered with unknown geometry, not visual/coordinate parity. No automatic fallback. `test/agent-browser.runtime.test.ts`, `test/agent-browser.shared-defaults.test.ts`, and `test/agent-browser.screenshot-geometry.test.ts` own the regressions; [limits](COMMAND_REFERENCE.md#lightpanda-engine). |
|
|
49
|
+
| Observation and geometry | Canonical bounded JSON/prose/code/native `structuredContent` observations expose exact recovery and receipts, with native namespace/output-schema metadata and canonical returned `isError`; complete observation spills preserve large output. Image dimensions/CSS viewport/DPR/crop/scroll/frame evidence is measured or explicitly unknown; no viewport-coordinate assumptions for full-page/element images. |
|
|
50
|
+
| Pi integration | Pi 1.5.0 floor with independently qualified official/fork graphs. Five advanced direct tools use native `defaultActive: false`; Pi restores transcript selections natively in default-tool sessions, and a narrow additive fallback covers `--no-builtin-tools` resumes without overriding explicit/defaultTools/filtered host selection. Loader/tree/reload retain native history; public `pi:instruction-groups` registration supplies one full `browser` instruction source. Managed hosts own deferred delivery; unmanaged/stock hosts receive identical full eager guidance even for generic prompts. No permission widening or legacy discovery metadata. `test/agent-browser.discovery.test.ts` covers full-text parity, dynamic ownership, and startup/late registration; tool-surface tests preserve host selections, with pipeline coverage in `test/agent-browser.pi-pipeline.test.ts`. No checkpoint or fork metadata/revision APIs, provider payload edits or image-detail overrides. |
|
|
51
51
|
|
|
52
52
|
See [migration](TOOL_CONTRACT.md#07-migration), [canonical observations](TOOL_CONTRACT.md#canonical-observation), and [release qualification/rollback](RELEASE.md#07-upgrade-and-rollback). Routine GitHub Actions runs official/fork Linux compatibility, a macOS packed-Pi smoke, Native lifecycle Linux, and one nonblocking latest-official native-Windows build/import/process smoke on PRs to `main`. Native Windows is best-effort. Its broader official/fork environment/full-contract/Git/npm-consumer qualification is manual-only, with real failures and artifacts retained. Release/platform evidence and review remain separate from these focused checks.
|
|
53
53
|
|
|
@@ -99,7 +99,7 @@ Current summary:
|
|
|
99
99
|
| RQ-0153 | Browser storage retains native JSONL authority, once-stored ancestral ref definitions, small correlated begin/finish events, explicit uncertainty/reuse and native-generation validation, invocation-only artifact receipts and ordered row changes. Failed persistence never retries effects; ordinary forks retain facts without acquiring parent cleanup rights. Read-only token replay automatically normalizes historical receipts through the same canonical reducer at the unchanged locator/bytes, retaining mixed-format ancestry, confirmation settings/provenance and cleanup ownership. Optional stopped separate-copy conversion reuses that decoder. | [`docs/SESSION_STORAGE.md`](SESSION_STORAGE.md), `lib/browser-transcript.ts`, `lib/browser-journal.ts`, `lib/browser-session-conversion.ts`, `test/agent-browser.storage-growth.test.ts`, `test/agent-browser.storage-recovery.test.ts`, existing script/ref/confirmation/Electron lifecycle tests |
|
|
100
100
|
| RQ-0152 | Agent feedback closes recovery and evidence gaps without a new runtime layer: unknown-target timeouts return a visibly executable `get url` → `snapshot -i` fail-fast action while dialog recovery remains allowed; successful tab creation/selection/close, including dispatched batch rows, live-verifies URL/fresh titles and retains new, selected, and post-close blank tabs; compacted direct or batched `outputPath` writes use only full command-redacted live wrapper spills and fail rather than save metadata; explicit URL reads/all-read batches avoid browser helpers and managed replacement, while proven native read confirmations preserve exact session routing and capability-gated browser independence; single session-info preflights distinguish daemon/browser/native/Pi ownership; native recording receipts expose capture versus encoded measurements and survive failure/timeout exports, with bounded identity-matched recovery and no file-only success; direct or batched first/fresh local headed launches expose an unverified `browserWindow` handoff while attachments do not; snapshot spills and SAML/OAuth URL values are redacted at model/persistence boundaries; unsupported direct/batch `scrollintoview text=...` fails before upstream false success with visible native recovery payloads while help passes through; and web search sends Exa primary/version guidance, removes exact normalized-URL duplicates without overfetch, and labels provider page dates without claiming crawl/version proof. | [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md), [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md), [`docs/ARCHITECTURE.md`](ARCHITECTURE.md), `test/agent-browser.extension-errors-artifacts.test.ts`, `test/agent-browser.extension-tabs.test.ts`, `test/agent-browser.extension-validation.test.ts`, `test/agent-browser.page-target-validation.test.ts`, `test/agent-browser.runtime.test.ts`, `test/agent-browser.snapshot-presentation.test.ts`, `test/agent-browser.web-search.test.ts`, `test/agent-browser.real-upstream-contract.test.ts` |
|
|
101
101
|
|
|
102
|
-
Browser journal storage (RQ-0153) uses one canonical small event/reducer, once-stored complete captures and journal-ordered artifact changes. Incomparable persisted process-start formats invalidate refs without reopening a live same-PID/socket managed page; the activation regression and proven-replacement controls live in `test/agent-browser.storage-recovery.test.ts`. `test/agent-browser.incremental-replay.test.ts` exercises real native SDK appends/tree selection and measures actual file-read bytes, with full-scan fallback for changed locators, native reseeds, rotation, truncation and same-size edits; torn publication and genuine file errors remain failures rather than cached success. Only structural metadata is reused, not selected ref definitions. `test/agent-browser.storage-growth.test.ts` protects the incident-sized map and ordinary-code growth; `test/agent-browser.storage-recovery.test.ts` covers actual append-fault dispatch counts, concurrent publication during captured-branch replay, unpublished selected-leaf refusal, unknown prefixes, same-URL generation replacement, branch conversion and strict token validation. Existing tab/ref, read-confirmation, recording, artifact and Electron lifecycle suites retain their contracts. The opt-in `test/helpers/large-browser-journal.mjs` exercises a >1 GiB original with a giant ignored value under a constrained V8 heap; it reports actual RSS separately. Official and fork load/restart qualification remains independent, and stock official
|
|
102
|
+
Browser journal storage (RQ-0153) uses one canonical small event/reducer, once-stored complete captures and journal-ordered artifact changes. Incomparable persisted process-start formats invalidate refs without reopening a live same-PID/socket managed page; the activation regression and proven-replacement controls live in `test/agent-browser.storage-recovery.test.ts`. `test/agent-browser.incremental-replay.test.ts` exercises real native SDK appends/tree selection and measures actual file-read bytes, with full-scan fallback for changed locators, native reseeds, rotation, truncation and same-size edits; torn publication and genuine file errors remain failures rather than cached success. Only structural metadata is reused, not selected ref definitions. `test/agent-browser.storage-growth.test.ts` protects the incident-sized map and ordinary-code growth; `test/agent-browser.storage-recovery.test.ts` covers actual append-fault dispatch counts, concurrent publication during captured-branch replay, unpublished selected-leaf refusal, unknown prefixes, same-URL generation replacement, branch conversion and strict token validation. Existing tab/ref, read-confirmation, recording, artifact and Electron lifecycle suites retain their contracts. The opt-in `test/helpers/large-browser-journal.mjs` exercises a >1 GiB original with a giant ignored value under a constrained V8 heap; it reports actual RSS separately. Official and fork load/restart qualification remains independent, and stock official Pi's native eager loader is not repaired by the extension alone. Ordinary legacy resume preserves the original locator and bytes; optional archive conversion is offline and source-retaining. The shared harness retains raw legacy fixtures so resume suites exercise runtime normalization, not pre-converted journals. See [`SESSION_STORAGE.md`](SESSION_STORAGE.md).
|
|
103
103
|
|
|
104
104
|
QA truthfulness (#121, RQ-0145) is covered by the registered-tool controls in `test/agent-browser.extension-input-modes.test.ts` and the strict `contract suite matches QA non-pass after same-URL error-buffer rollover` case in `test/agent-browser.real-upstream-contract.test.ts`. The real fixture fills the native error FIFO with identical rows, then verifies that a new document actually throws again at the same URL and that QA is always non-pass. Matched rows fail as an unverified check, not an application-error assertion. Empty/cleared and explicit `checkErrors: false` controls preserve valid passes; the wrapper does not fix upstream `errors --clear` or accept a warning-only pass as resolution.
|
|
105
105
|
|
|
@@ -151,11 +151,11 @@ scaling profiles remain separate from real-browser latency and host qualificatio
|
|
|
151
151
|
|
|
152
152
|
**0.38.1 PR evidence (2026-09-17, local macOS):** the full unit/fake suite passed 1,146 tests with 27 opt-in skips; the final review fixes then passed typecheck and 64 affected tests. Generated docs, live command-reference sampling, and the 132-file packaged Pi smoke passed. The real-upstream contract and 75 native batch/fidelity checks passed, as did all eight deterministic dogfood flows. Interactive compiled-checkout Pi smoke covered example.com and react.dev, delta/ref follow-ups, conditional screenshots, and a recording batch whose persisted result had two verified artifacts and no pending artifacts. Separate native probes confirmed helper-consumed WebMCP catalog updates remain visible. These checks do not qualify release-only platform/lifecycle gates; the hosted native-Windows result is recorded on the PR.
|
|
153
153
|
|
|
154
|
-
Re-run the gates below before each release. Dated outcomes in this table are historical evidence for their named source/version, not qualification of the current
|
|
154
|
+
Re-run the gates below before each release. Dated outcomes in this table are historical evidence for their named source/version, not qualification of the current implementation. The earlier 0.36.0 rebaseline passed local pre-PR, real-upstream and deterministic dogfood on 2026-09-01; the 0.35.0 floor was last validated locally on 2026-08-26. The historical 0.38.1 PR qualification used local macOS and the hosted native-Windows gate. Current explicit owner waivers take precedence; neither historical passes nor failures qualify the new candidate. Release-only cross-platform/model/lifecycle and publication gates remain separate.
|
|
155
155
|
|
|
156
156
|
| Gate | Evidence | Status |
|
|
157
157
|
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
158
|
-
| Native lifecycle Linux | Portable public SDK/native-browser lifecycle gate covers branch/reload, ordered code cancellation, ownership/routing, journal-begin failure and root save/reopen; see [native qualification](RELEASE.md#native-lifecycle-qualification). | Requalify the exact final source and host graph; no
|
|
158
|
+
| Native lifecycle Linux | Portable public SDK/native-browser lifecycle gate covers branch/reload, ordered code cancellation, ownership/routing, journal-begin failure and root save/reopen; see [native qualification](RELEASE.md#native-lifecycle-qualification). | Requalify the exact final source and host graph; no current candidate pass is claimed by historical evidence below. |
|
|
159
159
|
| Default local gate | `npm run verify` checks generated playbook drift, clean-builds generated `dist/`, runs `tsc --noEmit`, unit/fake tests, generated command-reference blocks, and live command-reference sampling. | **Earlier 0.36.0:** pass on 2026-09-01; 779 tests passed, two opt-in real-upstream tests skipped, and build/typecheck/docs/live command-reference gates passed. |
|
|
160
160
|
| Pre-PR local gate | `npm run verify -- pre-pr` composes the default gate with package-content verification. Use before larger local handoffs or PR-ready claims when lifecycle/platform/live dogfood cost is not warranted. | **Earlier 0.36.0 / package 0.6.2:** pass on 2026-09-01; 779 tests passed, two opt-in tests skipped, and the 127-file tarball verified. |
|
|
161
161
|
| Windows argument transport (#102/#131/#141) | `test/agent-browser.windows-argv.test.ts` exercises actual host argv, empty values, quotes, Unicode/spaces, stdin, custom shims and failure outcomes. `test/agent-browser.windows-stock-launcher.test.ts` covers the recognized global npm CMD template's direct-native path, command selection, fallback, literal LF/CRLF and cancellation. Custom or unrecognized batch launchers retain their existing newline limitation. POSIX keeps Node `spawn`. | Native Windows focused qualification on 2026-09-21 passed all seven stock-launcher controls, all 29 Chromium cases and 33 process/argv cases (two existing platform skips). Actual upstream Rust received all 12 expected operands; the original CMD path lost all four newline-bearing operands. These focused results do not replace full-suite, managed-browser, package or release gates. |
|
|
@@ -170,7 +170,7 @@ Re-run the gates below before each release. Dated outcomes in this table are his
|
|
|
170
170
|
| Configured-source lifecycle | `npm run verify -- lifecycle` (`scripts/verify-lifecycle.mjs`) drives `/reload`, closes and relaunches Pi with the same exact `--session-id`, checks the JSONL session header id, session continuity, slash-command sentinel tokens (`v1` before reload and `v2` after full relaunch), persisted spill reachability, and native returned failure status and JSON preservation for a QA reclassification with a fake upstream on `PATH`. Default Pi model is `zai/glm-5.2`; default per-step wait is **180000 ms** (`DEFAULT_TIMEOUT_MS`); override model with `--model <id>` and waits with `--timeout-ms <ms>`. Passthrough flags in [`scripts/project.mjs`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/scripts/project.mjs): `--keep-artifacts`, `--model`, `--verbose`, and `--timeout-ms` plus a value (for example `npm run verify -- lifecycle --model openai-codex/gpt-5.5:minimal --keep-artifacts --verbose --timeout-ms 600000`). | **Pi 0.84.4 on 2026-09-01:** pass; `/reload`, exact-session relaunch, managed continuity, persisted spill reachability, and Pi failure status all verified. |
|
|
171
171
|
| Quick isolated Pi smoke | `pi --approve --no-extensions --no-skills -e .` from trusted repo root; checkout-native browser tools only. | **Earlier 0.36.0 / package 0.6.2 / Pi 0.84.4:** isolated checkout tmux smoke passed on 2026-09-01; native `agent_browser` completed version, localhost open, WebMCP list/invoke, visible-text verification, and close. |
|
|
172
172
|
|
|
173
|
-
Runtime floor note: package metadata requires Node 24.21.0 or newer, keeps optional Pi core package peer ranges wildcard per installed Pi package docs, keeps direct Pi development dependencies locked as reproducible snapshots while qualification resolves the latest stable official Pi and maintained fork main independently, and makes `pi --version` below 1.
|
|
173
|
+
Runtime floor note: package metadata requires Node 24.21.0 or newer, keeps optional Pi core package peer ranges wildcard per installed Pi package docs, keeps direct Pi development dependencies locked as reproducible snapshots while qualification resolves the latest stable official Pi and maintained fork main independently, and makes `pi --version` below 1.5.0 a setup failure through `pi-agent-browser-doctor` / `npm run doctor`. The Pi floor follows the native tool-history/prompt APIs and includes no older-host compatibility shim.
|
|
174
174
|
|
|
175
175
|
## Baseline checklist by inventory section
|
|
176
176
|
|
package/docs/TOOL_CONTRACT.md
CHANGED
|
@@ -17,9 +17,9 @@ The extension synchronously registers a `browser` instruction group through the
|
|
|
17
17
|
|
|
18
18
|
Group enablement reveals selected declarations and instructions, not callable permissions. `agent_browser_tools` remains the separate advanced-tool activation path. Existing host selections, exclusions, namespaces, and restored tool history are unchanged.
|
|
19
19
|
|
|
20
|
-
Pi 1.
|
|
20
|
+
Pi 1.5.0 or newer is required; official and fork qualification is independent. Five specialized direct tools declare native `defaultActive: false`: `agent_browser_action`, `agent_browser_qa`, `agent_browser_electron`, `agent_browser_source`, and `agent_browser_network_source`. They require activation unless selected by the host; they are not deferred tools. Explicit CLI allowlists, SDK selections/defaultTools, loader activation, restored tool history, tree navigation and reload are respected. Omit CLI `--tools` for lazy activation, or include every desired advanced tool in its allowlist; the loader reports excluded tools as unavailable rather than bypassing host selection.
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
On resume, Pi restores the transcript's tool loadout natively in default-tool sessions. Sessions started with `--no-builtin-tools` (SDK `noTools: "builtin"`) skip that restoration, so the extension retains a narrow additive resume fallback for available advanced tools; it never deactivates host-selected tools or bypasses an explicit allowlist/filtered catalog. Remove that fallback when Pi restores that mode natively.
|
|
23
23
|
|
|
24
24
|
## Why this tool shape
|
|
25
25
|
|
|
@@ -658,7 +658,7 @@ These categories are intentionally bounded and stable so agents can branch on th
|
|
|
658
658
|
|
|
659
659
|
For argv-supplied `--allowed-domains`, the wrapper treats domain containment as launch-scoped. Upstream owns request, worker, popup, and WebRTC containment plus incompatible-mode rejection; the wrapper passes the setting and upstream result through unchanged.
|
|
660
660
|
|
|
661
|
-
Final public results return canonical `isError: true` when `resultCategory` is `failure`; Pi
|
|
661
|
+
Final public results return canonical `isError: true` when `resultCategory` is `failure`; Pi honors that return without a `tool_result` repair hook. For normal prose, finalization appends `Result category: failure; failureCategory: …; Pi tool isError: true.` to model-visible text. Explicit parseable JSON remains unchanged, including code JSON and preparation failures; invalid/non-JSON text retains the notice. The TUI also shows the category at the top of failed rendered results so collapsed rows keep the outcome visible. Shared finalization lives in `lib/native-output.ts` and `finalizeAgentBrowserFailure` in `lib/pi-tool-rendering.ts`. This keeps transcript, UI and structured outcomes aligned after wrapper-side reclassification such as `qa-failure` or `artifact-missing`.
|
|
662
662
|
|
|
663
663
|
For `batch`, top-level `details` still carries `resultCategory` plus `successCategory` or `failureCategory` for the **aggregate** tool outcome: if any step fails, the overall result is a failure (`resultCategory: "failure"`) even when later steps succeed—inspect `batchSteps[]` for per-step outcomes. Each `batchSteps[]` entry includes its own `resultCategory` and either `successCategory` or `failureCategory` for that step. When upstream reports it, successful and failed rows also expose a dedicated `lifecycle` field containing only the bounded `effectiveLaunch.browserLaunched` boolean; on failed rows this preserves launch evidence even though the ordinary result payload is omitted. Live state and transcript replay use that evidence to distinguish a terminal nested close from a post-close browser launch. `batchFailure.failedStep` duplicates the first failing step’s details, including its `failureCategory`, bounded lifecycle evidence, and any `nextActions`.
|
|
664
664
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-agent-browser-native",
|
|
3
|
-
"version": "0.9.
|
|
3
|
+
"version": "0.9.10",
|
|
4
4
|
"description": "pi extension that exposes agent-browser as a native tool for browser automation",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"author": "Mitch Fultz (https://github.com/fitchmultz)",
|
|
@@ -84,9 +84,9 @@
|
|
|
84
84
|
"typebox": "*"
|
|
85
85
|
},
|
|
86
86
|
"devDependencies": {
|
|
87
|
-
"@earendil-works/pi-ai": "1.0
|
|
88
|
-
"@earendil-works/pi-coding-agent": "1.0
|
|
89
|
-
"@earendil-works/pi-tui": "1.0
|
|
87
|
+
"@earendil-works/pi-ai": "1.5.0",
|
|
88
|
+
"@earendil-works/pi-coding-agent": "1.5.0",
|
|
89
|
+
"@earendil-works/pi-tui": "1.5.0",
|
|
90
90
|
"@types/cross-spawn": "6.0.6",
|
|
91
91
|
"@types/node": "24.19.1",
|
|
92
92
|
"@types/which": "2.0.2",
|
|
@@ -153,8 +153,5 @@
|
|
|
153
153
|
"stream-json": "3.7.0",
|
|
154
154
|
"strip-json-comments": "5.0.3",
|
|
155
155
|
"which": "2.0.2"
|
|
156
|
-
},
|
|
157
|
-
"overrides": {
|
|
158
|
-
"undici": "8.12.3"
|
|
159
156
|
}
|
|
160
157
|
}
|
package/scripts/doctor.mjs
CHANGED
|
@@ -26,7 +26,7 @@ import {
|
|
|
26
26
|
|
|
27
27
|
const execFile = promisify(execFileCallback);
|
|
28
28
|
const RECOMMENDED_VERSION = TARGET_AGENT_BROWSER_VERSION;
|
|
29
|
-
export const MINIMUM_PI_VERSION = "1.
|
|
29
|
+
export const MINIMUM_PI_VERSION = "1.5.0";
|
|
30
30
|
const DEFAULT_AGENT_DIR = resolve(homedir(), ".pi/agent");
|
|
31
31
|
|
|
32
32
|
/** @typedef {{readonly status: "pass" | "warn" | "fail", readonly title: string, readonly lines: readonly string[], readonly warnings?: readonly string[]}} DoctorCheck */
|