specpi 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.13.0 - 2026-09-05
+
+- Add bounded, best-effort sanitized browser exceptions, console errors, failed requests, and HTTP error diagnostics with explicit cursor/loss/clear semantics and ephemeral retention.
+- Add keyboard/chord input, native dropdown selection, and deadline-bounded page-condition waits; invalidate snapshot refs on application-driven navigation and preserve isolated cancellation cleanup.
+- Strictly type-check the browser extension against pinned development Pi, TypeBox, Node, and Playwright declarations without eagerly loading the browser runtime or changing production optional peers.
+- Add real registered-tool Chromium fixtures, repeatable responsive-site checks with fault-injection tests, and a shared CI browser gate required before Pages deployment. Preserve the pinned-Pi no-skips coverage gate.
+- Document privacy/testing contracts and an evidence-backed decision to retain project-native TypeScript semantic navigation rather than add an LSP tool now.
+
 ## 0.12.0 - 2026-09-05
 
 - Add experimental, opt-in delegation for independent reviews and selected-source analysis through native Pi sessions. The parent remains the sole writer; workers have no shell, edits, live web, nested delegation or ambient extensions.

package/README.md

@@ -24,17 +24,15 @@ SpecPi adds task contracts, workflow controls, and a local improvement loop to P
 
 Collection is disabled until explicitly enabled. Reports are sanitized, bounded, deduplicated by task, and never uploaded. Later evidence can reopen an item for review, but never restarts implementation automatically.
 
-Version `0.12.0` adds experimental native delegation and a new technical site. Task cards, verification receipts and human outcome assessments remain part of the single-agent workflow. See the [release notes](CHANGELOG.md) for the change list.
+Version `0.13.0` adds browser diagnostics, keyboard and native dropdown interactions, bounded condition waits, scoped TypeScript checking, and repeatable rendered-site tests. Experimental delegation, task cards, verification receipts and human outcome assessments remain part of the single-agent workflow. See the [release notes](CHANGELOG.md) for the change list.
 
 ## Optional delegation
 
-The native extension creates actual Pi `AgentSession` subagents while the parent remains the sole writer. Use normal `pi` startup and the existing SpecPi install/update lifecycle. Delegation starts disabled, with its tool schema absent from model requests; human `/delegate on` enables the displayed envelope and `/delegate off` revokes outstanding work. Delegation checks required public SDK capabilities rather than an exact Pi version list, so compatible Pi updates do not require a SpecPi release. The installer bootstrap remains pinned to 0.84.4, and runtime validation is recorded separately.
+One agent owns edits and verifies results. Experimental delegation adds up to two read-only Pi workers: `review` checks a frozen artifact; `scout` answers a focused question using selected sources. Workers cannot write, run shell commands, browse the web, or delegate further.
 
-Only `review` of a frozen artifact and `scout` analysis of a bounded evidence question are supported. Both can list, read and search exact selected text snapshots. Children have in-memory sessions and no ambient extensions, skills, AGENTS files, parent history, shell, writes, recursive delegation or live web access. Each receives assigned requirements and fixed constraints. There are at most two active workers, two jobs per batch, four batches and 32 SDK model invocations per Pi process. Reloads, session switches and off/on preserve counters; cancellation holds slots through SDK-visible stream/result and prompt settlement. Restart Pi to change the fixed working root or load a changed delegation runtime.
+Delegation is **off by default**. In Pi, use `/delegate on` to enable it, `/delegate status` to inspect work, and `/delegate off` to revoke it. Research informed the design; SpecPi quality, speed, and cost gains remain unmeasured.
 
-Pi owns the agent loop, authentication and OAuth. A fresh child `ModelRuntime` uses standard environment and `models.json` resolution; child transport/thinking budgets come from configured global settings, without project settings. Parent model/thinking are explicit with Pi clamping. Runtime-only authentication, selected extension-provider overrides, model-specific headers, startup proxy configuration and safe descriptor mismatches fail preflight without changing parent setup. Parent hooks, ephemeral settings and session affinity are not inherited. Each SDK invocation is admitted before dispatch; retries and compaction are disabled. SDK-visible streaming checks do not establish raw-transport, hidden-provider-attempt, invoice or memory caps, or prove remote execution has ended. Cost is unavailable. Research supports testing these purposes; no measured SpecPi quality, cost or speed advantage is claimed.
-
-See the [delegation guide](docs/delegation/README.md), [tool protocol](docs/delegation/protocol.md), [research](docs/delegation/research.md), and [evaluation plan](docs/delegation/evaluation.md) for setup, examples, boundaries and evidence.
+See [setup and limits](docs/delegation/README.md) or [how the research shaped the architecture](https://tannermidd.github.io/SpecPi/single-agent/).
 
 ## Install
 
@@ -57,14 +55,14 @@ specpi doctor
 Pin the reusable CLI when installing a reviewed release, or inspect its plan without retaining a global CLI installation:
 
 ```bash
-npm install --global specpi@0.12.0
-npx --package specpi@0.12.0 specpi plan
+npm install --global specpi@0.13.0
+npx --package specpi@0.13.0 specpi plan
 ```
 
 For a source-audited installation, clone the exact release:
 
 ```bash
-git clone --branch v0.12.0 --depth 1 https://github.com/TannerMidd/SpecPi.git
+git clone --branch v0.13.0 --depth 1 https://github.com/TannerMidd/SpecPi.git
 cd SpecPi
 ./specpi plan
 ./specpi install
@@ -122,7 +120,7 @@ Direct `pi install npm:specpi` loads extensions, skills, and themes only. It doe
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
 | `/spec`             | Replace normal chrome with a technical run panel, seal live reasoning, hold streaming prose until complete, and keep tools collapsed. |
 | `/guard`            | Deny confirmed host-wide destructive calls and request approval for bounded risk classes.                                             |
-| Browser tools       | Open an isolated Chromium context for rendered inspection and screenshots.                                                            |
+| Browser tools       | Inspect isolated Chromium, diagnose errors, exercise keyboard/select/wait flows, and capture screenshots.                              |
 | `specpi-spec` theme | Bring blueprint blue, technical greys, layered surfaces, and restrained semantic states into Pi.                                      |
 | `specpi` CLI        | Plan, install, update, verify, and uninstall managed state with backups and rollback.                                                 |
 
@@ -228,6 +226,10 @@ npm run format
 npm run check
 ```
 
-JavaScript and TypeScript use four-space indentation, explicit braced control flow, and one statement per line. The repository check enforces formatting, validates syntax, runs the Node test suite, executes registry-linked validators, and installs the exact npm tarball through an isolated lifecycle. Maintainers should follow [NPM_RELEASE.md](NPM_RELEASE.md) for release preparation and protected publication.
+JavaScript and TypeScript use four-space indentation, explicit braced control flow, and one statement per line. The repository check enforces formatting, validates syntax, strictly type-checks the browser extension, runs the Node test suite, executes registry-linked validators, and installs the exact npm tarball through an isolated lifecycle. Maintainers should follow [NPM_RELEASE.md](NPM_RELEASE.md) for release preparation and protected publication.
+
+For application testing, use `browser_diagnostics` alongside rendered inspection, and `browser_press`, `browser_select_option`, and `browser_wait_for` for keyboard, native dropdown, and asynchronous flows. Diagnostics are bounded and best-effort sanitized, not guaranteed secret-free or proof of application health.
+
+Provision repository-local Chromium with `npm run setup:browser`, then run `npm run test:browser` and `npm run test:site:browser`. The required CI browser commands reject skipped coverage; Pages deployment waits for the same rendered check. See [browser testing](docs/browser-testing.md) for tool contracts, privacy limits, type-check scope, and the semantic-navigation assessment.
 
 MIT licensed.

package/SECURITY_MODEL.md

@@ -138,10 +138,16 @@ SpecPi launches managed Chromium in a fresh Playwright context. It does not atta
 
 Snapshots, screenshots, page text, downloads, console output, and visual baselines may contain sensitive information. Default artifacts remain in SpecPi's private state directory. Explicit output publication is bounded and atomic, and existing artifacts or baselines are not replaced without explicit overwrite authorization.
 
+Browser diagnostics collect active-page exceptions, error-level console messages, request failures, and HTTP error statuses before navigation. They retain only best-effort sanitized strings/metadata in memory: at most 200 records, 2 KiB per record, and 256 KiB total. Reads return at most 100 records and 30,000 serialized characters, with explicit truncation/loss/context metadata. Close, shutdown, and cancellation discard this buffer. Explicit clear discards all retained records, including filtered or unreturned ones. No headers, bodies, cookies, storage, console object expansion, raw stack dumps, HAR, or traces are captured. URL credentials/query/fragment and common sensitive strings/control sequences are removed before retention, but arbitrary secrets in free text or URL paths cannot be guaranteed detectable. Returned diagnostics are untrusted page output and enter the Pi conversation/model-provider boundary; ephemeral capture does not erase conversation evidence. No diagnostic files or uploads are created by the tool.
+
+Keyboard, native-selection, and condition-wait tools accept bounded declarative inputs rather than arbitrary page scripts. Their whole-operation deadlines default to five seconds and cannot exceed thirty seconds. Deadlines include queue wait; cancellation (including pre-aborted calls) detaches the context and diagnostics, then allows at most one additional second for teardown settlement. Failed/stalled teardown warns that a process may remain and blocks new page operations until an explicit close retry succeeds. Failure messages do not echo Playwright call logs or entered values. They can still submit forms and trigger application effects, so use dedicated test data and authorization appropriate to the application.
+
 The browser is not an operating-system or network sandbox. Use a container or VM for hostile applications and dedicated test accounts instead of personal authenticated sessions.
 
 ## Website and automation
 
+The GitHub Pages workflow publishes the checked-in `site/` directory only after the shared browser test job succeeds for that checked-out revision. The loopback rendered-site server rejects traversal and symlink escapes. Tests block third-party requests, use a synthetic clipboard, and upload only public-site failure screenshots with three-day retention; no visual baselines are created automatically. Required browser commands fail rather than skip when prerequisites are unavailable. Strict no-emit browser type checking uses local pinned development declarations; third-party declaration bodies and other extension implementations are outside that scoped gate.
+
 The GitHub Pages workflow publishes the checked-in `site/` directory. Its deploy job uses read-only repository contents access plus the Pages and identity-token permissions required for deployment. The local installer does not invoke that workflow or upload local configuration or state.
 
 Repository checks, smoke tests, checksums, closed capability validators, and browser comparisons provide evidence for documented behavior. They reduce regression risk but do not prove the absence of vulnerabilities or establish cryptographic provenance for dependencies and releases.

package/THIRD_PARTY.md

@@ -33,7 +33,7 @@ The published `specpi` npm package declares the Pi host runtime modules its exte
 - `@earendil-works/pi-tui` — terminal component, key, and width primitives
 - `typebox` — the unscoped TypeBox package Pi bundles, used for tool input schemas
 
-They retain their own copyright and license terms. SpecPi never vendors, bundles, or installs them; the Pi host supplies them at extension load time through loader aliases. Pi disables peer resolution for managed package installs, so a peer range would not enforce the host version there. Marking the peers optional also keeps an ordinary npm CLI installation from adding a second copy beside or inside SpecPi. The full managed installation enforces its supported Pi floor through the installer's `MIN_PI_VERSION` compatibility check, and the limited direct Pi mode documents the same host prerequisite.
+They retain their own copyright and license terms. SpecPi never vendors, bundles, or installs them for end users; the Pi host supplies them at extension load time through loader aliases. Repository development additionally pins local copies for type checking and isolated test launches, as listed below. Pi disables peer resolution for managed package installs, so a peer range would not enforce the host version there. Marking the peers optional also keeps an ordinary npm CLI installation from adding a second copy beside or inside SpecPi. The full managed installation enforces its supported Pi floor through the installer's `MIN_PI_VERSION` compatibility check, and the limited direct Pi mode documents the same host prerequisite.
 
 SpecPi also installs these exact browser-runtime packages from the reviewed `browser-runtime/package-lock.json`:
 
@@ -52,7 +52,9 @@ Repository development uses these exact, project-local formatting and linting pa
 - `@typescript-eslint/parser@8.68.0` — MIT
 - `typescript@6.0.3` — Apache-2.0
 
-They are development-only dependencies, are not shipped by the SpecPi installer, and enforce the repository's JavaScript and TypeScript readability rules.
+They are development-only dependencies, are not shipped by the SpecPi installer, and enforce the repository's JavaScript and TypeScript readability rules. TypeScript also runs strict no-emit checking for the browser extension and a bounded semantic-navigation fixture.
+
+Browser type checking and registered-tool tests additionally use exact project-local development dependencies: `@earendil-works/pi-coding-agent@0.84.4`, `@earendil-works/pi-ai@0.84.4`, `@earendil-works/pi-tui@0.84.4` (MIT), `typebox@1.3.7` (MIT), `@types/node@22.20.1` (MIT), and `playwright@1.62.1` (Apache-2.0). These reuse the reviewed Pi/runtime versions, do not alter the optional production-peer contract, and are not bundled or installed by SpecPi. Direct development dependencies are pinned; this is not a claim that the development transitive graph is locked. The browser executable test runtime still uses the separately reviewed lockfile. `setup:browser` provisions only `.specpi-test/browser-runtime/`; its explicit `--with-deps` option invokes Playwright OS dependency setup on disposable Linux CI runners. No language-server executable or additional automation framework was added.
 
 The GitHub Pages site vendors the Latin subsets of IBM Plex Sans and IBM Plex Mono. Copyright © 2017 IBM Corp. with Reserved Font Name "Plex". The font files are distributed under the SIL Open Font License 1.1; the required license text is included at `site/fonts/LICENSE.txt`.
 

package/docs/browser-testing.md

@@ -0,0 +1,76 @@
+# Browser application testing
+
+## Agent workflow
+
+1. `browser_open` opens an HTTP(S) page in isolated Chromium; `browser_snapshot` exposes bounded rendered text and namespaced control references.
+2. Use click/fill and the tools below to exercise the application. Refresh snapshots after mutations or navigation (including application-initiated navigation). Targets use CSS, exact `text=`, or current snapshot refs; the first matching element is used.
+3. Inspect `browser_diagnostics` after navigation and interactions, wait for explicit expected states, and capture screenshots at relevant viewports. No errors alone does not establish correct behavior.
+4. `browser_close` discards the context and diagnostic buffer. No personal browser profile is attached.
+
+| Tool | Examples and limits |
+| --- | --- |
+| `browser_press` | `{ "key": "Tab" }`, `{ "target": "#search", "key": "Enter" }`, `{ "key": "Shift+Tab" }`. A single key/chord on the target or current focus, not a script or macro. |
+| `browser_select_option` | `{ "target": "#region", "options": [{ "label": "Europe" }] }`. Each of up to 50 options specifies exactly one value, label, or index. Multiple options require a native multiple select. Custom dropdowns use click/keyboard tools. |
+| `browser_wait_for` | `{ "condition": "text", "target": "#status", "text": "Saved" }`, `{ "condition": "hidden", "target": "#spinner" }`, or `{ "condition": "url", "url": "http://localhost:3000/done" }`. Element conditions: attached, detached, visible, hidden, or exact text. Text is treated literally, not as a regular expression. URL matching is exact after HTTP(S) normalization, not glob matching. |
+| `browser_diagnostics` | `{ "maxEntries": 50, "maxChars": 12000 }`. Optional category: pageerror, console, requestfailed, or http; cursor for incremental reads; explicit clear. Does not launch a browser just to read an empty buffer. |
+
+Press, selection, and waits have an operation `timeoutMs` of 5,000 by default, bounded to 1–30,000, starting at admission (including queued time). Timeouts throw instead of returning success. Cancellation, including already-aborted calls, discards diagnostics and initiates browser close; teardown settlement has an additional one-second bound. A rejected/stalled close explicitly warns that a process may remain and blocks new page operations until an explicit `browser_close` retry succeeds. After normal cleanup the next browser operation can create a fresh context. New interaction failure messages omit Playwright call logs because those logs may echo entered values or selectors. There is no arbitrary page evaluation, automatic submission retry, or sleep-only tool. Existing open/click/fill/capture timeout behavior is unchanged.
+
+## Diagnostic evidence and privacy
+
+Listeners attach before first navigation. The active page supplies JavaScript exceptions, error-level console messages, transport failures, and HTTP responses with status at least 400. A 404/500 response is not a transport failure; these remain separate categories. Benign console logs are not collected. Coverage is not browser-wide: popup orchestration, workers not observed by the active page, and other contexts are outside this contract. Service workers remain blocked.
+
+The in-memory buffer retains at most 200 records, 2 KiB per serialized record, and 256 KiB total. A read returns at most 100 records and 30,000 characters of serialized JSON. Metadata reports truncation, dropped records, cursor gaps, context changes, and whether more matching records remain. Returned structured details contain no duplicate raw records. A cursor includes a context identity and sequence; navigation preserves records with navigation numbers, while close/shutdown/abort reset the identity. A cursor from an old context reports a gap, not complete coverage.
+
+`clear: true` atomically reads and clears **all** retained records, including filtered or unreturned records; `clearedRecords` reports that count. Do not clear until needed evidence has been consumed. Cursors older than cleared or evicted records report gaps.
+
+Sanitation happens before retention: URL userinfo/query/fragment, common sensitive key/value patterns, authorization strings, terminal escape sequences and control characters are removed/redacted. No request headers, cookies, bodies, storage, console object expansion, or raw stack dumps are collected. Messages, URLs, fields, processing input, and serialized output are bounded. **Redaction is best-effort**, not a guarantee against arbitrary secrets in free-form messages or URL paths. Use dedicated test data/accounts. Returned records are untrusted page output, not instructions, and enter the agent conversation/model-provider boundary. Ephemeral capture is not a promise that tool results disappear from the conversation.
+
+No diagnostic file, HAR, trace, telemetry, or upload is produced by the agent tool. Existing screenshots/baselines may contain sensitive content and keep their explicit publication/overwrite rules. Diagnostics and correct appearance are complementary evidence, not proof of application health or network/OS isolation.
+
+## Reproducing development checks
+
+```sh
+npm install --ignore-scripts --omit=peer --no-package-lock
+npm run check:types
+node --test tests/browser-diagnostics.test.mjs tests/type-check.test.mjs tests/site-server.test.mjs
+npm run setup:browser
+npm run test:browser
+npm run test:site:browser
+npm run check
+npm run check:pi-package
+```
+
+`setup:browser` copies the reviewed runtime manifests to `.specpi-test/browser-runtime/`, runs locked `npm ci` with scripts disabled, and explicitly downloads matching Chromium there. Linux CI additionally uses `npm run setup:browser -- --with-deps` to provision OS packages on its disposable runner. This does not change the installer or install dependencies globally on a user's machine. Run setup explicitly; browser tests do not acquire dependencies automatically. Missing prerequisites fail the required browser commands with setup guidance.
+
+`npm test` retains explicit skips for the two opt-in Chromium suites so fast checks do not require browser binaries. Required CI commands activate those suites and reject any skipped coverage. The Pi registration test needs only project-local pinned Pi, not Chromium. `check:pi-package` reruns it through the separately provisioned pinned host and preserves its existing no-skips gate for selected Pi suites.
+
+### Scoped types
+
+`tsconfig.browser.json` checks exactly `extensions/browser/index.ts`, `diagnostics.ts`, `interactions.ts`, `lifecycle.ts`, and the `core.d.mts` boundary, with strict checking and no emit. It uses real pinned Pi, TypeBox, Playwright and Node declaration packages from development dependencies. Browser runtime imports remain lazy; Playwright imports in the extension are type-only. The `.mjs` image/runtime helper has narrow declarations backed by existing helper/runtime tests and an export-inventory regression; its JavaScript implementation is **not** fully type-checked. `skipLibCheck` skips third-party declarations, not first-party browser implementation errors. Other extensions remain syntax-checked, not advertised as type-checked. A negative fixture proves invalid key and Playwright API argument types fail without generated JavaScript.
+
+### Rendered site
+
+The committed loopback server serves only `site/` under `/SpecPi/`, on an ephemeral port, rejects traversal/symlink escapes, and is closed with the browser after tests. To inspect manually, run `node scripts/site-browser.mjs` and use the printed local URL; Ctrl+C closes the server.
+
+The rendered matrix covers the home, wiki, and architecture pages at 1440×900, 834×1112, and 390×844. It tests local navigation, keyboard skip links, guard/cycle tabs and their ARIA states, disclosures, copy success/failure with a synthetic clipboard, loaded images/fonts, horizontal overflow, and unexpected runtime/network errors. Remote requests are rejected. Controlled page-local fault injection demonstrates that runtime exceptions, broken interactions, and overflow fail the same assertions without committing broken site content.
+
+The shared browser workflow runs for CI and is a prerequisite of Pages deployment for the same revision. It uploads only public-site failure screenshots, retained for three days, from `.specpi-test/browser-artifacts/`. Tests never automatically create or replace visual baselines. A green DOM/interaction check is not a pixel-regression proof; screenshots still require visual review.
+
+### Capability-registry boundary
+
+The existing `local-browser-automation` registry entry and `browser-runtime-smoke` prove their historical rendering/image-comparison contract only. They are not expanded into claims that diagnostics or keyboard behavior have passed that closed validator. Browser diagnostics and interactions in SpecPi 0.13.0 are evidenced by dedicated registered-tool/Chromium tests and CI; no wishlist item is automatically selected or retired and no invented shipped version is entered in the registry.
+
+## Semantic navigation assessment (R6)
+
+**Decision: no new agent-facing semantic tool in this delivery.** Keep project-native compiler/tooling as the default and reassess after concrete larger-refactor friction.
+
+Run `node --test tests/semantic-navigation.test.mjs`. The existing pinned TypeScript language service resolves an aliased cross-file definition, finds four related symbol references while excluding a shadowed name, and reports diagnostic 2345 after an on-disk argument-type mutation. The fixture creates temporary source files, supplies an explicit language-service host, and disposes it afterward. No language server, plugin, project configuration script, or new executable dependency is loaded. Windows path normalization was necessary when comparing compiler-returned reference paths; the test retains that check.
+
+| Approach | Assessment |
+| --- | --- |
+| Project-native compiler and shell tools | Adequate baseline for this TypeScript fixture and the browser refactor. Text search is easy but cannot distinguish aliases/shadowing; compiler APIs can, at the cost of writing a small explicit host. No measured productivity improvement is claimed. |
+| Narrow TypeScript adapter | Could expose bounded path/line/column results and reuse this compiler if repeated refactor work justifies a maintained tool contract. Not justified by this small fixture alone. |
+| Broad LSP integration | Adds server acquisition/trust, process cleanup, language-specific configuration, and protocol complexity without evidence of a current need. Deferred, not implemented. |
+
+Any later adapter proposal must define supported languages/projects, on-disk versus unsaved buffers, canonical project-root and symlink boundaries, out-of-root declaration references, generated/vendor exclusions, result/time limits, cancellation/subprocess cleanup, and a no-auto-edit/no-auto-install policy. Definitions in dependencies may need an explicit read-only opt-in. Repository plugins/config scripts are executable trust boundaries, not automatically safe navigation inputs.

package/docs/delegation/README.md

@@ -1,6 +1,6 @@
 # Bounded delegation
 
-Status: experimental in SpecPi 0.12.0. Disabled by default.
+Status: experimental in SpecPi 0.13.0. Disabled by default.
 The package remains `specpi`; no separate npm package or background service is required.
 
 SpecPi keeps one agent responsible for changes and acceptance. This extension adds

package/extensions/browser/core.d.mts

@@ -0,0 +1,64 @@
+import type * as Playwright from "playwright";
+
+export type Viewport = { width: number; height: number };
+export type ViewportInput = { preset?: "desktop" | "tablet" | "mobile"; width?: number; height?: number };
+export type PngImage = Viewport & { data: Buffer };
+export type BrowserRuntime = {
+    playwright: typeof Playwright;
+    PNG: {
+        new (size: Viewport): PngImage;
+        sync: { read(data: Buffer): PngImage; write(image: PngImage): Buffer };
+    };
+    pixelmatch: (
+        a: Buffer,
+        b: Buffer,
+        output: Buffer,
+        width: number,
+        height: number,
+        options: { threshold: number },
+    ) => number;
+};
+export declare const MAX_CAPTURE_DIMENSION: number;
+export declare const MAX_CAPTURE_PIXELS: number;
+export declare const MAX_INLINE_IMAGE_BYTES: number;
+export declare const MAX_PNG_BYTES: number;
+export declare const VIEWPORT_PRESETS: Readonly<Record<"desktop" | "tablet" | "mobile", Viewport>>;
+export declare const DEFAULT_DIFF_THRESHOLD: number;
+export declare const DEFAULT_MAX_DIFF_PIXEL_RATIO: number;
+export declare const MAX_VIEWPORT_PIXELS: number;
+export declare function assertDistinctPaths(entries: Array<[string, string]>): void;
+export declare function assertPngResourceBounds(data: Buffer, label?: string): Viewport;
+export declare function readPngDimensions(data: Buffer, label?: string): Viewport;
+export declare function comparePngBuffers(
+    a: Buffer,
+    b: Buffer,
+    runtime: Pick<BrowserRuntime, "PNG" | "pixelmatch">,
+    options?: { threshold?: number; maxDiffPixelRatio?: number },
+): {
+    pass: boolean;
+    dimensionsMatch: boolean;
+    baseline: Viewport;
+    current: Viewport;
+    diffPixels: number;
+    diffPixelRatio: number;
+    diffBuffer: Buffer;
+    threshold: number;
+    maxDiffPixelRatio: number;
+};
+export declare function getAgentDir(extensionUrl: string): string;
+export declare function loadBrowserRuntime(runtimeDir: string): Promise<BrowserRuntime>;
+export declare function makeArtifactPath(
+    agentDir: string,
+    sessionId: string | undefined,
+    kind: string,
+    extension?: string,
+): string;
+export declare function sanitizeArtifactSegment(value: string): string;
+export declare function normalizeBrowserUrl(value: string): string;
+export declare function publishBuffer(
+    file: string,
+    data: Buffer,
+    options?: { overwrite?: boolean; signal?: AbortSignal },
+): Promise<void>;
+export declare function resolveUserPath(cwd: string, value: string, label?: string): string;
+export declare function resolveViewport(input?: ViewportInput): Viewport;

package/extensions/browser/diagnostics.ts

@@ -0,0 +1,275 @@
+import crypto from "node:crypto";
+import type { ConsoleMessage, Page, Request, Response } from "playwright";
+
+export const DIAGNOSTIC_CATEGORIES = ["pageerror", "console", "requestfailed", "http"] as const;
+export type DiagnosticCategory = (typeof DIAGNOSTIC_CATEGORIES)[number];
+export const MAX_DIAGNOSTIC_RECORDS = 200;
+export const MAX_DIAGNOSTIC_BYTES = 256 * 1024;
+export const MAX_RECORD_BYTES = 2048;
+
+export function boundedInteger(value: number | undefined, fallback: number, maximum: number, minimum = 1): number {
+    const result = value ?? fallback;
+    if (!Number.isInteger(result) || result < minimum || result > maximum) {
+        throw new Error(`Expected an integer from ${minimum} to ${maximum}.`);
+    }
+
+    return result;
+}
+
+function prefix(value: string, limit: number): string {
+    return value.slice(0, limit).toWellFormed();
+}
+
+function diagnosticUrl(value: string) {
+    try {
+        const url = new URL(value.slice(0, 16384));
+        if (url.protocol !== "http:" && url.protocol !== "https:") {
+            return { text: "[non-http location]", truncated: false };
+        }
+
+        url.username = "";
+        url.password = "";
+        url.search = "";
+        url.hash = "";
+
+        return { text: prefix(url.href, 300), truncated: value.length > 16384 || url.href.length > 300 };
+    } catch {
+        return { text: "[location omitted]", truncated: value.length > 16384 };
+    }
+}
+
+export function sanitizeUrl(value: string): string {
+    return diagnosticUrl(value).text;
+}
+
+/** Best effort only. Application messages and URL paths may contain arbitrary secrets. */
+function diagnosticText(value: string, limit = 700) {
+    // Bound processing as well as retention. Redact before taking the final display prefix.
+    let locationTruncated = false;
+    const sanitized = value
+        .slice(0, 16384)
+        .replace(/\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\|$)/gu, " ")
+        .replace(/\u001b\[[0-?]*[ -/]*[@-~]/gu, " ")
+        .replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/gu, " ")
+        .replace(/https?:\/\/[^\s<>"']+/giu, (url) => {
+            const location = diagnosticUrl(url);
+            locationTruncated ||= location.truncated;
+
+            return location.text;
+        })
+        .replace(/\b(?:bearer|basic)\s+[^\s,;]+/giu, "[authorization redacted]")
+        .replace(
+            /(["']?(?:password|passwd|secret|token|api[_-]?key|authorization|cookie|credential|access[_-]?key)["']?\s*[:=]\s*)(?:"[^"]*(?:"|$)|'[^']*(?:'|$)|[^\s,;]+)/giu,
+            "$1[redacted]",
+        );
+
+    return {
+        text: prefix(sanitized, limit),
+        truncated: value.length > 16384 || sanitized.length > limit || locationTruncated,
+    };
+}
+
+export function sanitizeDiagnostic(value: string, limit = 700): string {
+    return diagnosticText(value, limit).text;
+}
+
+type DiagnosticRecord = {
+    sequence: number;
+    navigation: number;
+    category: DiagnosticCategory;
+    message: string;
+    url: string;
+    method?: string;
+    status?: number;
+    resourceType?: string;
+    truncated: boolean;
+};
+export type DiagnosticQuery = {
+    maxEntries?: number;
+    maxChars?: number;
+    category?: DiagnosticCategory;
+    cursor?: string;
+    clear?: boolean;
+};
+
+export class BrowserDiagnostics {
+    private context = crypto.randomUUID();
+    private sequence = 0;
+    private navigation = 0;
+    private floor = 0;
+    private dropped = 0;
+    private bytes = 0;
+    private records: DiagnosticRecord[] = [];
+
+    reset(): void {
+        this.context = crypto.randomUUID();
+        this.sequence = 0;
+        this.navigation = 0;
+        this.floor = 0;
+        this.dropped = 0;
+        this.bytes = 0;
+        this.records = [];
+    }
+
+    navigated(): void {
+        this.navigation += 1;
+    }
+
+    record(
+        category: DiagnosticCategory,
+        message: string,
+        url = "",
+        extra: { method?: string; status?: number; resourceType?: string } = {},
+    ): void {
+        const clean = diagnosticText(message);
+        const location = url ? diagnosticUrl(url) : undefined;
+        const method = extra.method ? diagnosticText(extra.method, 20) : undefined;
+        const resourceType = extra.resourceType ? diagnosticText(extra.resourceType, 30) : undefined;
+        const entry: DiagnosticRecord = {
+            sequence: ++this.sequence,
+            navigation: this.navigation,
+            category,
+            message: clean.text,
+            url: location?.text ?? "",
+            method: method?.text,
+            status: extra.status,
+            resourceType: resourceType?.text,
+            truncated:
+                clean.truncated ||
+                location?.truncated === true ||
+                method?.truncated === true ||
+                resourceType?.truncated === true,
+        };
+        while (Buffer.byteLength(JSON.stringify(entry)) > MAX_RECORD_BYTES) {
+            entry.truncated = true;
+            if (entry.message.length) {
+                entry.message = prefix(entry.message, Math.floor(entry.message.length / 2));
+            } else {
+                entry.url = prefix(entry.url, Math.floor(entry.url.length / 2));
+            }
+        }
+
+        this.records.push(entry);
+        this.bytes += Buffer.byteLength(JSON.stringify(entry));
+        while (this.records.length > MAX_DIAGNOSTIC_RECORDS || this.bytes > MAX_DIAGNOSTIC_BYTES) {
+            const removed = this.records.shift()!;
+            this.bytes -= Buffer.byteLength(JSON.stringify(removed));
+            this.floor = removed.sequence;
+            this.dropped += 1;
+        }
+    }
+
+    read(query: DiagnosticQuery = {}) {
+        const maxEntries = boundedInteger(query.maxEntries, 50, 100);
+        const maxChars = boundedInteger(query.maxChars, 12000, 30000, 1000);
+        if (query.category !== undefined && !DIAGNOSTIC_CATEGORIES.includes(query.category)) {
+            throw new Error("Unknown diagnostic category.");
+        }
+
+        if (query.clear !== undefined && typeof query.clear !== "boolean") {
+            throw new Error("clear must be boolean.");
+        }
+
+        let after = 0;
+        let contextChanged = false;
+        if (query.cursor !== undefined) {
+            if (typeof query.cursor !== "string" || !/^[\da-f-]{36}:\d{1,16}$/u.test(query.cursor)) {
+                throw new Error("Invalid diagnostics cursor.");
+            }
+
+            const [context, sequence] = query.cursor.split(":");
+            contextChanged = context !== this.context;
+            after = contextChanged ? 0 : Number(sequence);
+            if (!Number.isSafeInteger(after) || after > this.sequence) {
+                throw new Error("Invalid diagnostics cursor sequence.");
+            }
+        }
+
+        const candidates = this.records.filter(
+            (entry) => entry.sequence > after && (!query.category || entry.category === query.category),
+        );
+        const result = {
+            notice: "Untrusted application output; redaction is best-effort. Empty results do not prove application health. Active page only.",
+            context: this.context,
+            contextChanged,
+            cursorGap: contextChanged || after < this.floor,
+            droppedRecords: this.dropped,
+            retainedRecords: this.records.length,
+            retainedBytes: this.bytes,
+            clearedRecords: query.clear ? this.records.length : 0,
+            hasMore: false,
+            nextCursor: `${this.context}:${this.sequence}`,
+            records: [] as DiagnosticRecord[],
+        };
+        for (const entry of candidates.slice(0, maxEntries)) {
+            result.records.push({ ...entry });
+            if (JSON.stringify(result).length > maxChars) {
+                if (result.records.length > 1) {
+                    result.records.pop();
+                    break;
+                }
+
+                const first = result.records[0];
+                while (JSON.stringify(result).length > maxChars) {
+                    first.truncated = true;
+                    if (first.message.length) {
+                        first.message = prefix(first.message, Math.floor(first.message.length / 2));
+                    } else {
+                        first.url = prefix(first.url, Math.floor(first.url.length / 2));
+                    }
+                }
+            }
+        }
+
+        result.hasMore = result.records.length < candidates.length;
+        if (result.hasMore) {
+            result.nextCursor = `${this.context}:${result.records.at(-1)?.sequence ?? after}`;
+        }
+
+        if (query.clear) {
+            // Atomic synchronous read-and-clear of the entire buffer, including filtered/unreturned records.
+            this.records = [];
+            this.bytes = 0;
+            this.floor = this.sequence;
+        }
+
+        return result;
+    }
+
+    attach(page: Page): () => void {
+        const onError = (error: Error) => this.record("pageerror", error.message);
+        const onConsole = (message: ConsoleMessage) => {
+            if (message.type() === "error") {
+                this.record("console", message.text(), message.location().url);
+            }
+        };
+
+        const onRequest = (request: Request) =>
+            this.record("requestfailed", request.failure()?.errorText ?? "Request failed", request.url(), {
+                method: request.method(),
+                resourceType: request.resourceType(),
+            });
+        const onResponse = (response: Response) => {
+            if (response.status() >= 400) {
+                const request = response.request();
+                this.record("http", `HTTP ${response.status()}`, response.url(), {
+                    status: response.status(),
+                    method: request.method(),
+                    resourceType: request.resourceType(),
+                });
+            }
+        };
+
+        page.on("pageerror", onError);
+        page.on("console", onConsole);
+        page.on("requestfailed", onRequest);
+        page.on("response", onResponse);
+
+        return () => {
+            page.off("pageerror", onError);
+            page.off("console", onConsole);
+            page.off("requestfailed", onRequest);
+            page.off("response", onResponse);
+        };
+    }
+}