pi-agent-browser-native 0.9.5 → 0.9.6

package/docs/TOOL_CONTRACT.md

@@ -339,9 +339,9 @@ Source runs in a fresh permissioned Node child with an empty child environment,
 
 `codeRun` reports `callCount`, `emitCount`, `failedCallCount`, `rejectedCallCount`, and timeout/abort flags. `codeSteps` retains bounded audit rows. Handled browser failures may coexist with successful source completion, but remain model-visible in `failures` with exact recovery evidence and in the failure count. A successful code result therefore does not assert that every inner command succeeded. Invalid inner input shapes make the outer result fail even if source handles their observations. Uncaught source exceptions use `script-error`; deadline and cancellation use `timeout` and `aborted`; output/bridge validation retains its specific failure.
 
-Direct browser use in a disabled/no-file Pi session (`--no-session`) records current in-memory state without claiming persistence. Code requires an actually published journal, and a named but not-yet-published persistent conversation refuses browser dispatch. Sessionless local inspections and browser-independent reads remain available without journal publication, including complete redacted private spills and selected output files; observation-only artifact receipts are optional until publication. Direct, code and Electron host operations use one canonical journal event/reducer. Begin/finish records correlate operation ID, outer tool-call ID and inner command index, preserving native effects before presentation/export. Complete snapshots are defined once; ordinary finishes explicitly reuse, replace, invalidate or keep refs unknown. An unfinished begin requires inspection and a new capture, without repeating the mutation. Failed finish publication reports `browserStatePersistence: "finish-unconfirmed"` and stops dependent code calls; failed begin reports `"begin-unconfirmed"` and prevents dispatch. These acknowledgments do not promise power-loss-atomic browser actions. See [session storage and conversion](SESSION_STORAGE.md).
+Direct browser use in a disabled/no-file Pi session (`--no-session`) records current in-memory state without claiming persistence. Code requires an actually published journal, and a named but not-yet-published persistent conversation refuses browser dispatch. Sessionless local inspections and browser-independent reads remain available without journal publication, including complete redacted private spills and selected output files; observation-only artifact receipts are optional until publication. Direct, code and Electron host operations use one canonical journal event/reducer. Begin/finish records correlate operation ID, outer tool-call ID and inner command index, preserving native effects before presentation/export. Complete snapshots are defined once; ordinary finishes explicitly reuse, replace, invalidate or keep refs unknown. An unfinished begin requires inspection and a new capture, without repeating the mutation. Failed finish publication reports `browserStatePersistence: "finish-unconfirmed"` and stops dependent code calls; failed begin reports `"begin-unconfirmed"` and prevents dispatch. These acknowledgments do not promise power-loss-atomic browser actions. Historical browser receipts resume automatically through the same canonical reducer at the unchanged native journal locator, without conversion or rewritten bytes. Native validation, generation checks and publication requirements still apply. See [session storage](SESSION_STORAGE.md).
 
-Abort, timeout, branch change, reload, and shutdown stop/reap the child, settle the active inner call and join outer observation finalization before releasing lifecycle coordination. A result from a prior branch retains its complete caller observation in a process-private spill without changing the newly selected branch's artifact state. They do not roll back browser actions or automatically close the selected browser. Existing ownership still controls later shutdown cleanup. The offline converter normalizes exact pre-0.7 isolated-session cleanup leases into owner-qualified canonical events; runtime only reads those canonical cleanup facts, without old public script execution.
+Abort, timeout, branch change, reload, and shutdown stop/reap the child, settle the active inner call and join outer observation finalization before releasing lifecycle coordination. A result from a prior branch retains its complete caller observation in a process-private spill without changing the newly selected branch's artifact state. They do not roll back browser actions or automatically close the selected browser. Existing ownership still controls later shutdown cleanup. The shared read-only decoder normalizes exact pre-0.7 isolated-session cleanup leases into owner-qualified canonical events for ordinary replay or optional archive conversion; runtime retains only those cleanup facts, without old public script execution.
 
 ### `agent_browser_action`
 
@@ -767,7 +767,7 @@ Additional structured fields can appear when relevant:
 - `electronGetTextScopeWarning` after a successful wrapper-tracked attached Electron `get text <selector>` (standalone or successful `batch`) when a broad non-ref CSS selector such as `body`, `html`, `main`, `div`, or `[role=application]` may read the whole app shell. Ordinary browser pages do not qualify without wrapper-owned Electron launch provenance. Shape: `{ selector, summary, electronContext: { launchId?, sessionName?, url? } }`; multiple batched diagnostics use `electronGetTextScopeWarnings`. Visible text appends `Broad Electron get text selector warning`, and next actions use `snapshot-for-electron-text-scope` ids with session-scoped `snapshot -i` payloads.
 - `evalStdinHint` after a successful `eval --stdin` when caller stdin (trimmed) looks function-shaped to the wrapper’s lightweight detector (in `extensions/agent-browser/lib/orchestration/browser-run/diagnostics.ts`: leading `function` / `async function`, parenthesized arrow `(…) =>`, or a concise `name =>` / `async name =>` form) **and** upstream JSON `data` is an object whose `result` field is a plain empty object (`{}`). Arrays such as `[]` do not qualify. It includes `reason` and `suggestion`; visible output appends `Eval stdin hint` with the same guidance. This is a heuristic for the common mistake of returning a function object instead of invoking it or passing a plain expression, not a JavaScript parser or proof that the page returned no useful data. Before this diagnostic path runs, the wrapper also recovers the common malformed native-tool call `args: ["eval", "--stdin", "..."]` with no top-level `stdin` by moving trailing `args` tokens after `--stdin` into the process stdin stream.
 - `evalResultWarning` after a successful `eval --stdin` when the current or prior page URL is `file:` (from navigation summary, session tab target, or persisted session page state), upstream JSON `data.result` is strictly `null`, and stdin is non-empty and not a trivial literal `null`/`undefined`. Fields: `reason`, `suggestion`. Visible output appends `Eval result warning` without failing the tool. Use snapshot -i, ref-based getters, screenshots, or http(s) fixtures when file:// null results are inconclusive.
-- `timeoutPartialProgress` after `runAgentBrowserProcess` reports `timedOut` (wrapper child-process watchdog) when best-effort recovery finds useful context. `summary` counts planned steps with unknown outcomes and observed declared artifact paths, plus whether page context came from live session reads or only from a planned URL. An existing file or matching URL is current-state evidence, not proof that any planned step ran. `steps` lists planned argv from the compiled QA batch plan (`compiledJob` remains its internal metadata name) or, when that object is absent, from the effective upstream `batch` source: raw argument command strings exclusively when present, otherwise JSON-array stdin, whether caller-authored or wrapper-generated by advanced source tools (1-based indices). Ignored stdin does not contribute recovery steps or artifact evidence. Generated QA rows may include `generatedFrom`. Each step has `status: "unknown"` and a `reason`: the watchdog fired before upstream reported its outcome. Multi-step timeouts do not identify a completed prefix, failed step, pending suffix, or retry position. For a single read-only or idempotent step such as a wait, snapshot, screenshot, navigation, or diagnostic, `retryStep.retry` and `retry-timeout-step` may offer a candidate after inspection; its outcome remains unknown. Each retry uses `args: ["batch"]` with `stdin` containing the original row, preserving native row operands instead of reinterpreting them as outer CLI globals. Otherwise, when the target is already verified, `inspect-current-page-after-timeout` (`snapshot -i`) lets the agent inspect state before deciding how to resume. When the target is unknown, every standalone snapshot action is removed and replaced by one executable `verify-page-target-after-timeout` action: a session-scoped `batch --bail` with stdin `[["get","url"],["snapshot","-i"]]`, so snapshot runs only after the wrapper's page-target guard is satisfied; visible failure text prints those redacted args and short stdin rather than pointing only to structured details. Dialog `status`, `accept`, and `dismiss` remain allowed while the target is unknown so timeout dialog recovery actions are executable. When a retryable step timed out during `sessionMode: "fresh"` and no live URL was recovered, `retry-timeout-step` uses top-level `sessionMode: "fresh"` instead of prefixing the abandoned generated session name. `currentPage` comes from session-scoped `get url` followed by `get title` when the session answers, otherwise a fallback URL may be inferred from the last `open` / `navigate` / `pushstate` step in the plan; `liveUrlRecovered` is true only when the wrapper recovered a live URL, so planned URLs are not treated as proof that the page actually opened. `artifacts` reports post-timeout path existence, not creation by this invocation or step completion. It covers declared output paths on `screenshot`, `pdf`, `download`, and `wait --download` steps (absolute path, existence, `state`, optional `sizeBytes`, `stepIndex`). It uses native operand positions, including literal dash-leading paths: first operand for `pdf`, second for `download`, and the next retained operand after the first timeout pair is removed for `wait --download` / `-d`. Visible text repeats the same block under `Timeout partial progress`, applying URL and path-segment redaction; the prose `Planned steps` list shows at most six steps, then an omitted-count line when the plan is longer. This is recovery evidence only; missing entries do not prove the upstream step never ran or that no other side effects occurred.
+- `timeoutPartialProgress` after `runAgentBrowserProcess` reports `timedOut` (wrapper child-process watchdog) when best-effort recovery finds useful context. `summary` counts planned steps with unknown outcomes and observed declared artifact paths, plus whether page context came from live session reads or only from a planned URL. An existing file or matching URL is current-state evidence, not proof that any planned step ran. `steps` lists planned argv from the compiled QA batch plan (`compiledJob` remains its internal metadata name) or, when that object is absent, from the effective upstream `batch` source: raw argument command strings exclusively when present, otherwise JSON-array stdin, whether caller-authored or wrapper-generated by advanced source tools (1-based indices). Ignored stdin does not contribute recovery steps or artifact evidence. Generated QA rows may include `generatedFrom`. Each step has `status: "unknown"` and a `reason`: the watchdog fired before upstream reported its outcome. Multi-step timeouts do not identify a completed prefix, failed step, pending suffix, or retry position. For a single read-only or idempotent step such as a wait, snapshot, screenshot, navigation, or diagnostic, `retryStep.retry` and `retry-timeout-step` may offer a candidate after inspection; its outcome remains unknown. Each retry uses `args: ["batch"]` with `stdin` containing the original row, preserving native row operands instead of reinterpreting them as outer CLI globals. Otherwise, when the target is already verified, `inspect-current-page-after-timeout` (`snapshot -i`) lets the agent inspect state before deciding how to resume. When the target is unknown, every standalone snapshot action is removed and replaced by one executable `verify-page-target-after-timeout` action: a session-scoped `batch --bail` with stdin `[["get","url"],["snapshot","-i"]]`, so snapshot runs only after the wrapper's page-target guard is satisfied; visible failure text prints those redacted args and short stdin rather than pointing only to structured details. Dialog `status`, `accept`, and `dismiss` remain allowed while the target is unknown so timeout dialog recovery actions are executable. When a retryable step timed out during `sessionMode: "fresh"` and no live URL was recovered, `retry-timeout-step` uses top-level `sessionMode: "fresh"` instead of prefixing the abandoned generated session name. `currentPage` comes from session-scoped `get url` followed by `get title` when the session answers, otherwise a fallback URL may be inferred from the last `open` / `navigate` / `pushstate` step in the plan; `liveUrlRecovered` is true only when the wrapper recovered a live URL, so planned URLs are not treated as proof that the page actually opened. `artifacts` reports post-timeout path existence, not creation by this invocation or step completion. Independent paths are sampled concurrently in plan order, each with up to three filesystem checks separated by 25 ms; page inspection starts after these retry windows settle. A file finishing after its own window may remain missing, even if a later page probe succeeds. It covers declared output paths on `screenshot`, `pdf`, `download`, and `wait --download` steps (absolute path, existence, `state`, optional `sizeBytes`, `stepIndex`). It uses native operand positions, including literal dash-leading paths: first operand for `pdf`, second for `download`, and the next retained operand after the first timeout pair is removed for `wait --download` / `-d`. Visible text repeats the same block under `Timeout partial progress`, applying URL and path-segment redaction; the prose `Planned steps` list shows at most six steps, then an omitted-count line when the plan is longer. This is recovery evidence only; missing entries do not prove the upstream step never ran or that no other side effects occurred.
 - `managedSessionHeadedAutosaveInterval` on active/current-after-failure wrapper-owned headed session rows, containing the canonical effective launch-time `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS` string (invalid or out-of-range explicit values resolve to upstream's `"30000"` default). It is `"0"` for the wrapper default and can hold an explicit interval such as `"1000"`; transcript replay and still-owned off-current helpers reapply the recorded value. It is omitted for sessionless, headless, caller-owned, abandoned, and closed calls. If a resumed Pi process explicitly requests a different value in either direction, non-close calls fail with close-plus-fresh recovery guidance while close still uses the recorded daemon value.
 - `managedSessionHeadedAutosaveDisabled: true` is the narrower compatibility marker that the targeted session uses the wrapper's default interval `0`, rather than an explicit caller interval. It accompanies `managedSessionHeadedAutosaveInterval: "0"` on active rows and remains omitted for explicitly configured autosave.
 - `managedSessionOutcome` after a managed-session plan reaches process execution (`buildManagedSessionOutcome` / `formatManagedSessionOutcomeText` in `extensions/agent-browser/lib/orchestration/browser-run/session-state.ts`). Populated when `buildExecutionPlan` injects an extension-managed implicit or fresh `--session`, and also when a successful explicit `--session <current-wrapper-managed-session> close` closes the current managed session. It remains omitted for unrelated explicit user-managed sessions and for sessionless inspection/local paths that skip injection. Successful nested-batch lifecycle rows are evaluated in order: a terminal close reports and replays `status: "closed"` even when aggregate artifact verification makes the tool result fail; a later lifecycle-proven browser launch (including a post-close `record stop`) keeps the session active, an explicitly non-launching diagnostic leaves it closed, and an unknown row stays conservatively active even when the failed batch was the first managed call. Fields: `status` (`created`, `replaced`, `unchanged`, `closed`, `preserved`, or `abandoned`), `sessionMode`, `attemptedSessionName`, `previousSessionName`, `currentSessionName`, optional `currentSessionNamespace`, optional `replacedSessionName`, optional `replacedSessionNamespace`, optional `replacedSessionClosed` (false means automatic close failed and the previous session remains wrapper-owned/restorable for explicit cleanup), `activeBefore`, `activeAfter`, `succeeded`, and `summary` (machine-oriented; may include generated session names). Use `currentSessionNamespace` with `currentSessionName` when following preserved-session recovery actions; retry-fresh actions stay in the attempted namespace. Model-visible echo: when `sessionMode` is `"fresh"` **and** `succeeded` is false, or when `replacedSessionClosed` is false after a replacement, the wrapper appends action-oriented `Managed session outcome` and `Recovery` lines without repeating generated session ids in visible prose; session names remain in `details.managedSessionOutcome`. Failed fresh launches may also append `details.nextActions` such as `run-agent-browser-doctor`, `verify-current-managed-session`, `snapshot-current-managed-session`, or `retry-fresh-managed-session`. When other trailing diagnostic prose is also emitted in the same result, that block is concatenated **after** semantic-action candidate lines, overlay/selector-visibility tails, eval hints/warnings, and `Timeout partial progress` (see `rawAppendedDiagnosticText` in `extensions/agent-browser/lib/orchestration/browser-run/final-result.ts`). For `"auto"` failures the same struct may appear on `details` without that extra line. When post-upstream analysis (for example **`qa`** preset failure) flips the overall tool result after a successful batch, or a fresh native batch opens the requested page and then a later step fails, the managed-session transition still reflects that the fresh browser became current. The visible recovery says the fresh launch became current and points to `failureCategory` / `qaPreset` / `batchFailure` for the post-launch failure instead of telling the agent that the old session was preserved.
@@ -941,7 +941,7 @@ For exact delayed-input behavior, build native rows instead of relying on unveri
 }
 ```
 
-Fixed waits are elapsed time, not postconditions. Preserve explicit URL/text waits, same-snapshot fill ordering, fresh refs after mutations, and partial-progress inspection. There is no legacy public script/job runtime. Exact isolated-script cleanup leases are normalized only by offline conversion so canonical replay can retire their recorded pre-upgrade resources. Saved auth and original Pi transcripts are not rewritten or deleted; [rollback](RELEASE.md#07-upgrade-and-rollback) changes the package version, not browser side effects.
+Fixed waits are elapsed time, not postconditions. Preserve explicit URL/text waits, same-snapshot fill ordering, fresh refs after mutations, and partial-progress inspection. There is no legacy public script/job runtime. Exact isolated-script cleanup leases are normalized during ordinary read-only replay so the canonical cleanup path can retire recorded pre-upgrade resources without acquiring a parent's cleanup rights on a fork. Optional separate-copy conversion uses the same decoder. Saved auth and original Pi transcripts are not rewritten or deleted; [rollback](RELEASE.md#07-upgrade-and-rollback) changes the package version, not browser side effects.
 
 ## Non-goals