High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: drop superseded browser-targets and e2e-smoke-share specs
Luigi Agosti93b0565461ee
diff --git a/docs/architecture/autosolver.md b/docs/architecture/autosolver.mdindex 1315d5e0..51563a9b 100644--- a/docs/architecture/autosolver.md+++ b/docs/architecture/autosolver.md@@ -1,4 +1,4 @@-# AutoSolver Architecture+# AutoSolver## Overviewdiff --git a/docs/architecture/browser-abstraction.md b/docs/architecture/browser-abstraction.mdindex c512569b..bb6ed3a4 100644--- a/docs/architecture/browser-abstraction.md+++ b/docs/architecture/browser-abstraction.md@@ -2,7 +2,6 @@Status: partially implemented (BridgeAPI encapsulation complete; browser registry extraction in progress)Owner: bridge-Related: [browser-targets.md](browser-targets.md)## Problemdiff --git a/docs/architecture/browser-targets.md b/docs/architecture/browser-targets.mddeleted file mode 100644index 300ea338..00000000--- a/docs/architecture/browser-targets.md+++ /dev/null@@ -1,341 +0,0 @@-# Browser Targets--> **Terminology note.** This document predates [`new-spec.md`](../../new-spec.md),-> which makes "browser" the only user-facing concept. Where this document says-> "browser target", read "browser". Internal code identifiers-> (`BrowserTargetConfig`, `TargetConfig`, etc.) are unchanged.--PinchTab currently treats the browser backend as a single global provider:-`browsers.default=chrome|cloak`. That works for first-class CloakBrowser support,-but it makes browser type mutually exclusive. The next architecture should let-one PinchTab server know about multiple browsers and select one per request,-per instance, or by fallback policy.--This spec uses "browser" to mean a named runnable browser backend such as-`chrome-local`, `cloak-us`, or `lightpanda-fast`. A browser has a provider type,-launch or attach settings, profile storage, capabilities, and health state.--## Goals--- Configure multiple browsers in one PinchTab config.-- Keep a default browser for existing clients.-- Let requests select a browser explicitly when they need one.-- Let PinchTab fall back to another configured browser when startup or- acquisition fails.-- Support multiple browsers of the same provider type.-- Support future provider types with different capability surfaces, including- lightweight browsers such as Lightpanda-style runtimes.-- Preserve the current Chrome behavior when no multi-browser config is present.--## Non-Goals--- Do not make PinchTab download third-party browser binaries at runtime.-- Do not silently move an existing tab from one browser to another.-- Do not fallback after a request has already performed page side effects unless- the request explicitly opts into retry semantics.-- Do not require every provider to support every endpoint.--## Configuration--Introduce named browsers under `browser.targets`. Keep current single-provider-fields as a compatibility shorthand that migrates to a browser named `default`.--Example:--```json-{- "browser": {- "defaultTarget": "chrome-local",- "fallbackOrder": ["cloak-primary"],- "targets": {- "chrome-local": {- "provider": "chrome",- "binary": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"- },- "cloak-primary": {- "provider": "cloak",- "binary": "/opt/cloakbrowser/chrome",- "cloak": {- "fingerprintSeed": "42069",- "platform": "linux",- "locale": "en-US",- "timezone": "UTC",- "disableDefaultStealthArgs": true- }- }- }- }-}-```--Rules:--- `browser.defaultTarget` is required once `browser.targets` is present.-- Browser names are stable API identifiers. They must be lowercase, URL-safe,- and not derived from binary paths.-- `browser.fallbackOrder` is optional. If absent, fallback is disabled unless a- request supplies an explicit fallback list. It must not repeat browsers or- include `browser.defaultTarget`.-- Current `browsers.default`, `browser.binary`, `browser.extraFlags`, and- `browser.cloak` remain valid and are interpreted as `browser.targets.default`- during config load.-- Provider-specific blocks live inside each browser definition, not globally.-- Profile directories are browser-scoped:- `profiles.baseDir/<browser-name>/<profile-name>`.--## Request Selection--Add a canonical request option named `browserTarget` (the field name references-the internal target concept but selects a browser by name).--Examples:--```http-POST /navigate-{- "url": "https://example.com",- "browserTarget": "cloak-primary"-}-```--```http-POST /instances/start-{- "browserTarget": "lightpanda-fast",- "mode": "headless"-}-```--Selection order:--1. If a request references an existing `tabId` or `instanceId`, the existing- instance's browser wins. A conflicting `browserTarget` is a `409`.-2. If `browserTarget` is present, resolve that named browser.-3. If a request supplies a provider type such as `browserProvider=cloak`, resolve- the configured default browser for that provider only when unambiguous.-4. Otherwise use `browser.defaultTarget`.-5. If acquisition fails and fallback is enabled, walk the request fallback list- first, then `browser.fallbackOrder`.--Surfaces:--- HTTP JSON bodies use `browserTarget`.-- HTTP query params may use `browserTarget` for GET-style endpoints.-- CLI can expose `--browser <name>` as the user-facing alias.-- MCP tools should expose `browserTarget` for explicitness.-- `/instances/start` should accept `browserTarget` because instances are the- natural browser-ownership boundary.--## Fallback--Fallback is only safe before a browser instance has performed request side-effects.--Fallback is allowed for:--- binary missing or not executable-- startup timeout-- CDP connect failure-- browser process exits during startup-- browser unhealthy or in cooldown-- browser lacks a required capability and the request allows capability fallback--Fallback is not allowed for:--- security policy denials-- IDPI or allowed-domain blocks-- auth/session failures-- existing `tabId` or `instanceId` requests-- action/navigation after the page has already changed state, unless a future- endpoint explicitly declares idempotent retry behavior--Request-level controls:--```json-{- "url": "https://example.com",- "browserTarget": "cloak-primary",- "fallbackTargets": ["chrome-local"],- "allowBrowserFallback": true-}-```--Response metadata should expose the actual browser used:--```json-{- "tabId": "...",- "url": "https://example.com",- "browserTarget": "chrome-local",- "browserProvider": "chrome",- "fallbackFrom": "cloak-primary",- "fallbackReason": "startup_timeout"-}-```--If fallback is disabled or exhausted, return a structured error:--```json-{- "code": "browser_target_unavailable",- "error": "browser cloak-primary failed to start",- "details": {- "browserTarget": "cloak-primary",- "browserProvider": "cloak",- "reason": "startup_timeout",- "fallbackTried": ["chrome-local"]- }-}-```--## Capabilities--Each provider adapter declares a capability set. PinchTab uses capabilities to-route requests to the right browser, decide fallback, and return clear-unsupported-operation errors.--Initial capability names:--- `cdp`-- `headless`-- `headed`-- `persistentProfiles`-- `extensions`-- `domSnapshot`-- `actions`-- `evaluate`-- `cookies`-- `screenshots`-- `pdf`-- `upload`-- `download`-- `networkIntercept`-- `emulation`-- `nativeStealth`-- `remoteAttach`--Capability resolution:--- Provider adapters expose default capabilities.-- Runtime probes can downgrade capabilities when a binary is missing a feature.-- Endpoint handlers declare required capabilities.-- If the selected browser lacks a required capability, return `409- browser_capability_unsupported` unless fallback is enabled and another browser- can satisfy the request.--This is what makes Lightpanda-style browsers viable. A lightweight browser can-be configured beside Chrome and CloakBrowser, but only endpoints backed by its-declared capabilities are routed to it. Missing features should be explicit,-not discovered as late CDP errors.--## Provider Adapter Contract--Introduce a provider registry instead of hard-coding `chrome|cloak` in launch-paths.--Adapter responsibilities:--- validate browser config-- resolve binary or remote endpoint-- report capabilities-- build launch args or remote attach config-- probe runtime health-- redact provider-specific secrets-- map provider-specific launch errors to normalized failure reasons--Sketch:--```go-type BrowserProvider interface {- Type() string- ValidateTarget(target BrowserTargetConfig) []error- Capabilities(target BrowserTargetConfig) CapabilitySet- BuildLaunchPlan(target BrowserTargetConfig, runtime RuntimeOptions) (LaunchPlan, error)- Probe(ctx context.Context, target BrowserTargetConfig) (ProbeResult, error)-}-```--The first implementation can keep Chrome and CloakBrowser on the existing-chromedp allocator path. Future non-Chromium providers can either implement a-CDP-compatible adapter or force a larger engine abstraction when CDP is not-enough.--## Instance Model--Instances become browser-bound:--- Every instance records `browserTarget` and `browserProvider`.-- `/instances` includes those fields.-- `/health` includes default browser health and degraded browser summaries.-- `/stealth/status` continues to report provider information for the active- instance, and should add `browserTarget`.-- Tab lifecycle, leases, locks, handoff, and active-tab routing remain- instance-scoped.--Auto-start behavior:--- `simple` strategy starts or reuses an instance for the selected browser.-- `always-on` starts one default instance per configured always-on browser.-- Allocation policy must never hand a request to an instance from a different- browser than the resolver selected.--## Security--Browser selection is not a security bypass.--- Existing auth, sessions, IDPI, allowed domains, and endpoint capability gates- still run after browser selection.-- Fallback must not bypass a security block. A blocked navigation should stay- blocked on every browser.-- Agent/session policy can later restrict allowed browsers per token or agent.-- Browser names should be logged in activity and audit trails.-- Provider-specific secrets, especially proxy credentials, must be redacted.-- Hosted third-party browsers require separate licensing and trust review- before being documented as supported.--## Migration--Phase 1 keeps behavior identical:--- Existing config without `browser.targets` produces one browser named `default`.-- Existing `browsers.default=chrome` remains the default.-- Existing tests for Chrome launch args stay unchanged.--Phase 2 adds named browser config and request selection:--- Add config structs, validation, JSON schema, editor get/set, and dashboard UI.-- Add `browserTarget` request parsing to `/navigate`, `/instances/start`, and- routes that can auto-acquire an instance.-- Add browser fields to instance metadata and health output.--Phase 3 adds fallback:--- Add startup failure classification.-- Add browser health/cooldown state.-- Add global and request-level fallback order.-- Add response metadata for fallback selection.--Phase 4 adds capability routing:--- Add provider capability declarations.-- Gate endpoint acquisition by required capabilities.-- Convert unsupported-provider failures into structured `409` responses.--Phase 5 adds future providers:--- Remote CDP-backed browsers.-- Lightpanda-style lightweight browsers with explicit partial capability support.-- Provider-specific E2E smoke lanes selected by capability rather than provider- name.--## Open Questions--- Should `browserProvider=cloak` be accepted on requests, or should all requests- use only browser names to avoid ambiguity?-- Should fallback be opt-in per request, globally configured, or both?-- Should browser-level security policy exist, or should security stay purely- instance/request scoped?-- Should CLI defaults be `--browser <name>` only, or should commands also- expose `--browser-provider <provider>`?-- How should browser health be surfaced in dashboard without encouraging users to- run every browser all the time?diff --git a/docs/architecture/e2e-smoke-share-infra.md b/docs/architecture/e2e-smoke-share-infra.mddeleted file mode 100644index dc0dc970..00000000--- a/docs/architecture/e2e-smoke-share-infra.md+++ /dev/null@@ -1,1016 +0,0 @@-# E2E And Smoke Shared Infrastructure--Status: draft--Date: 2026-05-17--## Scope--This spec proposes a shared infrastructure layer for PinchTab E2E tests and-smoke tests. The goal is to make new coverage mostly a matter of declaring-configuration and writing the scenario-specific behavior, while the runner owns-common setup, provider selection, compose services, generated configs, reports,-logs, artifacts, and skip policy.--This covers:--- compose-backed E2E scenarios under `tests/e2e/scenarios`-- host-side Docker smoke scripts under `scripts/docker-*-smoke.sh`-- local smoke routing through `scripts/dev-smoke.sh`-- provider-specific smoke runs for Chrome and CloakBrowser-- shared shell helpers under `scripts/lib/smoke-*.sh` and- `tests/e2e/helpers`-- Go runner code under `tests/tools/runner/internal/e2e`--It does not require rewriting every existing test immediately. The migration-should preserve today's scripts and move orchestration behind a compatible-catalog-driven runner in phases.--## Current Shape--PinchTab currently has two overlapping test orchestration systems.--The first is the Go E2E runner:--- entry point: `go run ./tests/tools/runner e2e ...`-- scenario files: `tests/e2e/scenarios/*/*.sh`-- scenario metadata: `tests/e2e/scenarios/manifest.json`-- compose stack: `tests/e2e/docker-compose-multi.yml`-- container executor: `tests/e2e/run.sh`-- runner implementation:- - `tests/tools/runner/internal/e2e/e2e.go`- - `tests/tools/runner/internal/e2e/runner.go`- - `tests/tools/runner/internal/e2e/provider.go`--The Go runner already handles suite expansion, scenario discovery, compose-startup, readiness checks, explicit scenario execution, dry-run output, logs,-and reports. It also has hardcoded host Docker smoke steps for some release-image and lifecycle checks.--The second is the local smoke shell layer:--- local entry point: `scripts/dev-smoke.sh`-- host smoke scripts:- - `scripts/docker-smoke.sh`- - `scripts/docker-chrome-cft-smoke.sh`- - `scripts/docker-port-conflict-smoke.sh`- - `scripts/docker-mcp-smoke.sh`- - `scripts/docker-browser-parity-smoke.sh`- - `scripts/docker-cdp-attach-smoke.sh`- - `scripts/docker-live-detection-smoke.sh`- - `scripts/docker-zombie-soak-smoke.sh`-- shared host smoke helpers:- - `scripts/lib/smoke-common.sh`- - `scripts/lib/smoke-config.sh`- - `scripts/lib/smoke-container.sh`- - `scripts/lib/smoke-health.sh`- - `scripts/lib/smoke-fixtures.sh`- - `scripts/lib/smoke-endpoints.sh`- - `scripts/lib/smoke-scenarios.sh`- - `scripts/lib/smoke-diagnostics.sh`- - `scripts/lib/smoke-assertions.sh`- - `scripts/lib/smoke-multi-target.sh`- - `scripts/lib/smoke-persistence.sh`--The shell layer is useful and pragmatic, but it has its own routing,-filtering, provider matrix, temporary config generation, artifact behavior,-and pass/fail reporting.--## Current Helper Roles--The host smoke helpers are already a partial shared infrastructure layer. The-problem is that they are only shared by shell scripts, while the Go runner has-its own planning and provider logic.--Current helper responsibilities:--- `scripts/lib/smoke-common.sh` provides base shell primitives: failure and- skip handling, command checks, free-port selection, authenticated API calls,- JSON assertions, screenshot assertions, and byte/file assertions.-- `scripts/lib/smoke-config.sh` writes temporary PinchTab config files for- Chrome, CloakBrowser, and multi-target smoke runs. It owns a second copy of- several provider defaults that also exist in the E2E runner.-- `scripts/lib/smoke-container.sh` centralizes Docker container startup and- cleanup helpers for host smokes.-- `scripts/lib/smoke-health.sh` waits for PinchTab and fixture services to- become reachable.-- `scripts/lib/smoke-fixtures.sh`, `smoke-endpoints.sh`,- `smoke-scenarios.sh`, `smoke-assertions.sh`, `smoke-multi-target.sh`, and- `smoke-persistence.sh` group repeated API flows and assertions for specific- smoke families.--The target design keeps these helpers useful for direct shell script execution,-but moves cross-cutting concerns that affect all tests into the runner:--- which tests are selected-- which provider matrix is expanded-- which configs are generated-- which resources are required or provided-- where logs and artifacts are stored-- how results are reported--## Existing Strengths To Keep--- The Go runner is a good central control point for suite selection,- filtering, reports, logs, compose lifecycle, and CI execution.-- `tests/e2e/run.sh` has a clean contract: it runs explicit scenario files- passed by the runner and reports structured `E2E_RESULT` lines.-- `tests/e2e/scenarios/manifest.json` already separates scenario metadata- from scenario code.-- The shell helper libraries hide many low-level details for host smokes:- port selection, API calls, health checks, generated configs, fixture- servers, screenshots, and diagnostics.-- Host smoke scripts are valuable because some checks need direct host access- to Docker, external browser containers, release images, or local binaries.--The target design should reuse these strengths instead of replacing them with a-large new framework.--## Problems--### Metadata Is Split Across Multiple Places--Scenario metadata lives in `tests/e2e/scenarios/manifest.json`.-Host Docker smoke steps are hardcoded in Go. Local smoke groups are hardcoded in-`scripts/dev-smoke.sh`. Provider-specific host smoke behavior is hardcoded in-individual scripts. Compose service requirements are partly in the manifest,-partly inferred from scenario names, and partly embedded in runner code.--This makes it hard to answer simple questions:--- What tests belong to `./dev smoke cdp-attach`?-- Which tests run for `--browser cloak`?-- Which tests require a release image?-- Which tests require a full PinchTab service versus a medium service?-- Which tests are CI-safe and which are local opt-in checks?--### Provider And Config Generation Is Duplicated--CloakBrowser config generation exists in more than one shape:--- `tests/tools/runner/internal/e2e/provider.go` rewrites E2E config files and- generates compose overrides for CloakBrowser.-- `scripts/lib/smoke-config.sh` generates provider configs for host smoke- scripts with embedded Python.-- individual smoke scripts still carry setup assumptions around browser binary- paths, DevTools ports, and Docker images.--The repeated logic increases the chance that Chrome and CloakBrowser coverage-diverges accidentally.--### Runner Behavior Is Not Uniform--Compose-backed E2E scenarios produce structured reports through the Go runner.-Host smoke scripts produce their own terminal output and artifact directories.-Some host smoke steps are visible to the Go runner, while others are only-reachable through `scripts/dev-smoke.sh`.--That split creates friction when a smoke failure needs to be compared with an-E2E failure, retried with a filter, or added to CI.--### Adding New Tests Requires Too Much Harness Knowledge--Adding a new test often requires knowing several unrelated details:--- which script entry point to use-- which helper file to source-- how to select `runner-api` versus `runner-cli`-- which compose service should be ready-- where to declare tags and services-- how to run the same case across Chrome and CloakBrowser-- how to emit results and collect artifacts-- whether to edit Go runner code, a shell router, or a manifest--The desired authoring model is:--1. declare what the test needs-2. write the scenario-specific actions and assertions-3. let the shared infrastructure handle the rest--## Goals--- Provide one catalog for E2E scenarios and smoke tests.-- Keep `./dev e2e`, `./dev smoke`, and CI behavior stable during migration.-- Let a new test be added with a scenario file plus a small metadata entry.-- Move provider, config, compose, readiness, report, log, artifact, and skip- behavior into shared runner infrastructure.-- Support both container E2E scenarios and host-side Docker smoke commands.-- Preserve shell as a valid scenario language where it is already working.-- Make Chrome/CloakBrowser provider matrix behavior declarative.-- Make dry-run output authoritative for what will run and why.-- Keep failure artifacts easy to find and consistently named.-- Avoid requiring Docker host access from container E2E scenarios.--## Non-Goals--- Do not rewrite all tests in Go.-- Do not remove host smoke scripts before their behavior is represented in the- runner catalog.-- Do not make every smoke test CI-blocking. Some checks should remain local or- scheduled only.-- Do not hide product-specific assertions behind a generic DSL so much that the- test intent becomes unclear.--## Target Architecture--Introduce a catalog-driven test runner that can plan and execute multiple test-kinds through the same suite/filter/provider/reporting path.--```mermaid-flowchart TD- D["./dev e2e / ./dev smoke / CI"] --> R["Go test runner"]- R --> C["Test catalog"]- R --> P["Provider profiles"]- R --> CFG["Config materializer"]- R --> X["Execution adapters"]-- X --> E["Container E2E scenario adapter"]- X --> H["Host command smoke adapter"]- X --> G["Generated config smoke adapter"]-- E --> COMPOSE["docker compose stack"]- H --> HOST["host Docker / local binary"]- G --> HOST-- R --> OUT["Unified logs, artifacts, reports"]-```--The Go runner remains the main orchestrator. Shell scripts remain executable-implementation units, but the runner owns selection, environment, dependency-resolution, reporting, and artifact conventions.--## Test Catalog--Add a machine-readable catalog under `tests/e2e/catalog/`.--Recommended initial files:--```text-tests/e2e/catalog/- suites.json- services.json- providers.json- tests.json-```--JSON is recommended for the first version because the repo already uses-`manifest.json`, Go support is standard, and migration can reuse existing-parsing patterns. YAML can be reconsidered later if comments and anchors become-important.--### Catalog Responsibilities--The catalog should declare:--- test id-- test kind-- suite membership-- tags-- provider matrix-- required commands-- required images-- required compose services-- readiness targets-- execution adapter-- command or scenario path-- environment variables-- timeout-- artifact policy-- CI policy-- skip policy--Example:--```json-{- "id": "infra.dashboard-smoke",- "kind": "e2e-scenario",- "path": "tests/e2e/scenarios/infra/dashboard-smoke.sh",- "suites": ["smoke", "smoke-infra"],- "helper": "base",- "services": ["pinchtab-full"],- "ready": ["pinchtab-full", "fixtures"],- "providers": ["chrome", "cloak"],- "tags": ["dashboard", "screencast", "isolation"],- "timeout": "60s",- "ci": true-}-```--Example host smoke:--```json-{- "id": "host.cdp-attach",- "kind": "host-command",- "command": ["bash", "scripts/docker-cdp-attach-smoke.sh", "${provider}"],- "suites": ["smoke", "smoke-host", "smoke-cdp"],- "providers": ["chrome", "cloak"],- "requires": ["docker", "pinchtab-binary"],- "provides": [],- "artifacts": {- "mode": "script-tempdir",- "env": "PINCHTAB_SMOKE_ARTIFACT_DIR"- },- "timeout": "120s",- "ci": false,- "skipPolicy": "skip-if-docker-unavailable"-}-```--Example release image dependency:--```json-{- "id": "host.release-image",- "kind": "host-command",- "command": ["bash", "scripts/docker-smoke.sh", "--build-only"],- "suites": ["smoke", "smoke-host", "smoke-orchestrator"],- "providers": ["chrome"],- "provides": ["release-image"],- "timeout": "180s",- "ci": true-}-```--## Suite Model--Suites should become catalog data instead of scattered conditionals.--Example:--```json-{- "suites": {- "basic": {- "include": [{"tier": "basic"}]- },- "extended": {- "include": [{"tier": "basic"}, {"tier": "extended"}]- },- "smoke": {- "include": [{"suite": "smoke"}]- },- "smoke-cdp": {- "include": [{"tag": "cdp"}]- }- }-}-```--The runner should still accept existing suite names:--- `basic`-- `extended`-- `smoke`-- `smoke-orchestrator`-- `smoke-security`-- `smoke-lifecycle`--New suites should be additive and should not require editing Go switch-statements unless a new execution adapter is needed.--## Execution Adapters--The runner needs a small set of adapter types.--### `e2e-scenario`--Runs a shell scenario inside the compose runner container through-`tests/e2e/run.sh`.--Inputs:--- scenario path-- helper-- required commands-- compose services-- readiness targets-- filter or test name-- provider profile--This adapter should keep the existing `E2E_RESULT` contract.--### `host-command`--Runs a host-side command from the repo root.--Inputs:--- command argv-- provider variable expansion-- environment variables-- timeout-- artifacts directory-- required commands-- required images--The runner should wrap the command and record:--- start time-- duration-- exit status-- stdout/stderr log path-- artifact path-- skip reason, when exit status maps to a skip--Host scripts do not need to emit `E2E_RESULT` on day one. The runner can treat-exit status as the result and still collect output consistently.--### `generated-config-host-command`--Runs a host command that needs a generated PinchTab config.--This can start as `host-command` plus a `configProfile` field. The runner-materializes config files before execution and passes paths through-environment variables.--Example:--```json-{- "id": "host.browser-parity.basic",- "kind": "host-command",- "command": ["bash", "scripts/docker-browser-parity-smoke.sh", "${provider}"],- "configProfile": "browser-parity",- "providers": ["chrome", "cloak"]-}-```--## Provider Profiles--Provider selection should be declared once in `tests/e2e/catalog/providers.json`.--Example:--```json-{- "providers": {- "chrome": {- "browserProvider": "chrome",- "binaryEnv": "PINCHTAB_CHROME_BINARY",- "dockerImage": "pinchtab-chrome-smoke:test"- },- "cloak": {- "browserProvider": "cloak",- "binary": "/opt/cloakbrowser/chrome",- "dockerImage": "pinchtab-cloakbrowser:test",- "cloak": {- "fingerprintSeed": "42069",- "platform": "linux",- "locale": "en-US",- "timezone": "UTC",- "disableDefaultStealthArgs": true- }- }- }-}-```--The runner should be the only place that knows how to turn a provider profile-into:--- generated config JSON-- compose override YAML-- host command environment-- provider matrix expansion-- provider-specific skip reasons--This should replace duplicated provider config generation in:--- `tests/tools/runner/internal/e2e/provider.go`-- `scripts/lib/smoke-config.sh`-- provider-specific blocks inside host smoke scripts--The migration does not need to delete those files immediately. First, the-runner can call the existing generators. Later, config generation should move-into one Go package with tests.--## Service Profiles--The current compose file has many PinchTab service variants. The catalog should-name those variants and their readiness behavior.--Example:--```json-{- "services": {- "pinchtab": {- "composeService": "pinchtab",- "ready": ["pinchtab"]- },- "pinchtab-full": {- "composeService": "pinchtab-full",- "ready": ["pinchtab-full"],- "configProfile": "full"- },- "pinchtab-medium": {- "composeService": "pinchtab-medium",- "ready": ["pinchtab-medium"],- "configProfile": "medium"- },- "fixtures": {- "composeService": "fixtures",- "ready": ["fixtures"]- }- }-}-```--The runner should resolve scenario `services` into compose services and-readiness targets. Scenario authors should not need to know whether a service-is started because of direct selection, a fixture dependency, or a provider-override.--## Config Profiles--Add a config materialization layer for test configs.--Inputs:--- base profile name, such as `default`, `secure`, `medium`, `full`, `lite`,- `bridge`, or `autoclose`-- provider profile, such as `chrome` or `cloak`-- temporary output directory-- fixture host-- token and server bind values-- optional feature overrides--Outputs:--- PinchTab config JSON-- compose override mount info-- host command environment variables--The immediate implementation can adapt existing config files under-`tests/e2e/config/`. The long-term implementation should generate configs from-typed Go structs or JSON templates so that Chrome and CloakBrowser variants are-consistent.--## Scenario Authoring Model--The short-term authoring model should remain shell-based:--1. create `tests/e2e/scenarios/<group>/<name>-<tier>.sh`-2. add a catalog entry only when defaults are not enough-3. write only the test-specific setup, actions, and assertions--The runner and executor should own:--- locating the scenario directory-- sourcing the selected helper-- waiting for services-- selecting provider config-- setting API base URLs-- collecting logs-- emitting result records--Current scenario boilerplate such as this should become unnecessary for new-files:--```bash-GROUP_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)-ROOT_DIR=$(cd "$GROUP_DIR/../.." && pwd)-source "$ROOT_DIR/helpers/base.sh"-```--New scenarios should be closer to:--```bash-start_test "dashboard: screencast injection stays isolated from main world"--tab_id=$(new_fixture_tab "/evaluate.html")-start_screencast "$tab_id"-assert_main_world_clean "$tab_id"--end_test-```--The exact helper names can evolve, but the design principle is that scenario-files should describe behavior, not runner setup.--## Host Smoke Authoring Model--Adding a new host smoke should not require editing `scripts/dev-smoke.sh` or a-Go switch.--Authoring steps:--1. create a focused shell script only if the smoke needs custom host behavior-2. add a `host-command` catalog entry-3. declare provider matrix, required images, timeout, CI policy, and artifacts-4. run `./dev smoke --dry-run <filter>` to verify selection--The script should receive a consistent environment:--- `PINCHTAB_SMOKE_PROVIDER`-- `PINCHTAB_SMOKE_ARTIFACT_DIR`-- `PINCHTAB_SMOKE_CONFIG`-- `PINCHTAB_SMOKE_TOKEN`-- `PINCHTAB_SMOKE_TIMEOUT`-- `PINCHTAB_SMOKE_FIXTURES_HOST`--Existing scripts can keep their current positional arguments while the runner-adds these environment variables.--## Reporting And Artifacts--The runner should produce one report model for all test kinds.--Each result should include:--- test id-- display name-- suite-- kind-- provider-- status: `pass`, `fail`, or `skip`-- duration-- command or scenario path-- log file-- artifact directory-- failure summary-- skip reason--For compose-backed E2E scenarios, keep parsing `E2E_RESULT`.-For host commands, wrap the process and synthesize equivalent result records.--Recommended artifact layout:--```text-tests/e2e/.artifacts/<run-id>/- report.json- report.txt- logs/- infra.dashboard-smoke.chrome.log- host.cdp-attach.cloak.log- artifacts/- infra.dashboard-smoke.chrome/- host.cdp-attach.cloak/-```--CI can upload the run directory as a single artifact. Local runs can print the-same path on failure.--## Filtering--Filtering should be consistent across E2E and smoke:--- by suite: `--suite smoke-cdp`-- by id substring: `--filter cdp-attach`-- by tag: `--tag cdp`-- by provider: `--browser chrome|cloak|all`-- by test block inside a scenario: current `--test` behavior--`--dry-run` should print:--- selected tests-- skipped tests and reasons-- provider expansion-- required services-- required images-- generated config profiles-- execution order--Dry-run should become the first debugging tool for "why did this run?" and-"why did this not run?"--## Dependency And Ordering Model--Replace hardcoded smoke step dependencies with catalog-level resources.--Examples:--- `release-image`-- `chrome-smoke-image`-- `cloak-smoke-image`-- `pinchtab-binary`-- `docker`-- `docker-compose`--Tests can `provide` and `require` resources. The runner should topologically-order selected tests when resource dependencies are inside the same run.--Example:--```json-{- "id": "host.chrome-cft-image",- "kind": "host-command",- "provides": ["chrome-smoke-image"]-}-```--```json-{- "id": "host.cdp-attach",- "kind": "host-command",- "requires": ["chrome-smoke-image"]-}-```--This keeps image build sequencing visible in the catalog instead of embedded in-runner conditionals.--## Compatibility Strategy--The first implementation should be additive.--Keep working:--- `./dev e2e`-- `./dev smoke`-- `go run ./tests/tools/runner e2e --suite ...`-- direct host smoke script execution, such as- `bash scripts/docker-cdp-attach-smoke.sh all`--Compatibility approach:--- generate initial catalog entries from current `manifest.json` plus the- hardcoded Go smoke steps-- let the runner understand both old manifest fields and new catalog fields-- have `scripts/dev-smoke.sh` delegate more work to the Go runner over time-- keep host smoke scripts callable directly while also making them catalog- entries-- only remove duplicate routing once the runner has equivalent coverage and CI- has proven it--## Implementation Plan--### Phase 1: Inventory And Catalog Skeleton--Deliverables:--- add `tests/e2e/catalog/tests.json`-- add `tests/e2e/catalog/suites.json`-- add `tests/e2e/catalog/providers.json`-- add `tests/e2e/catalog/services.json`-- add Go structs and parser tests for the catalog-- add a runner dry-run mode that prints catalog-resolved tests without changing- execution behavior--Work:--- import all current `tests/e2e/scenarios/manifest.json` entries-- represent hardcoded Docker smoke steps from `runner.go` as catalog entries-- represent local-only smoke scripts from `scripts/dev-smoke.sh` as catalog- entries marked `ci: false`-- add validation for duplicate ids, missing scenario files, unknown services,- unknown providers, and unknown suites--Validation:--- `go test ./tests/tools/runner/internal/e2e`-- compare old and new dry-run output for `basic`, `extended`, and `smoke`-- verify direct shell scripts still work--### Phase 2: Catalog-Backed E2E Planning--Deliverables:--- make suite expansion read from `suites.json`-- make scenario metadata read from the catalog-- keep `manifest.json` as a compatibility input or generated view-- make dry-run output show service and provider resolution--Work:--- replace filename/tier inference with catalog values where present-- keep current defaults for scenarios not yet cataloged-- add tests for suite filtering, tag filtering, provider expansion, and service- resolution--Validation:--- `go run ./tests/tools/runner e2e --suite basic --dry-run`-- `go run ./tests/tools/runner e2e --suite smoke --browser chrome --dry-run`-- existing E2E smoke scenarios still execute through `tests/e2e/run.sh`--### Phase 3: Move Host Smoke Steps Into The Catalog--Deliverables:--- implement `host-command` adapter-- move Go hardcoded Docker smoke steps to `tests/e2e/catalog/tests.json`-- wrap host command stdout/stderr into runner logs-- synthesize unified result records for host commands--Work:--- model `provides` and `requires` resources-- map existing skip behavior to explicit skip policies-- pass `PINCHTAB_SMOKE_ARTIFACT_DIR` to host commands-- keep the current scripts directly executable--Validation:--- run dry-run for smoke host suites-- run one passing host command through the runner-- run one intentionally filtered host command-- verify report output contains both E2E scenario and host command results--### Phase 4: Make `./dev smoke` A Thin Runner Wrapper--Deliverables:--- update `scripts/dev-smoke.sh` to delegate suite and filter resolution to the- Go runner-- preserve current user-facing commands and aliases-- remove duplicated provider/filter routing after parity is proven--Work:--- map `./dev smoke cdp-attach` to a catalog filter or suite-- map `./dev smoke live-detection` to catalog entries-- map `./dev smoke browser-parity` to catalog entries-- keep `ci`, `e2e`, and provider aliases stable--Validation:--- `./dev smoke --dry-run`-- `./dev smoke cdp-attach --browser=chrome`-- `./dev smoke ci --browser=all`-- compare selected tests with current behavior--### Phase 5: Consolidate Provider And Config Generation--Deliverables:--- create one Go config materializer for test configs-- move CloakBrowser provider override rules into provider profiles-- make compose and host smoke config generation use the same source-- add golden tests for generated Chrome and CloakBrowser configs--Work:--- adapt current `provider.go` logic into a reusable package-- adapt `scripts/lib/smoke-config.sh` to call generated config files or keep it- as a thin compatibility wrapper-- remove duplicated CloakBrowser settings from host smoke scripts-- ensure generated configs preserve current fixture mounts and extension mounts--Validation:--- `go test ./tests/tools/runner/internal/e2e`-- run Chrome and CloakBrowser dry-runs and inspect generated configs-- run provider-sensitive smokes:- - autosolver smoke- - dashboard smoke- - CDP attach smoke- - browser parity smoke--### Phase 6: Reduce Scenario Boilerplate--Deliverables:--- update `tests/e2e/run.sh` and helpers so new scenarios do not source helper- files manually-- add focused helper functions for common API, fixture, tab, screenshot,- screencast, autosolver, and dashboard operations-- document the new scenario authoring pattern in `tests/e2e/README.md`--Work:--- keep old scenarios compatible-- add a lint or validation check for unsupported scenario metadata-- migrate a few representative scenarios first:- - one API basic scenario- - one CLI scenario- - one infra smoke scenario- - one autosolver scenario--Validation:--- run migrated scenarios individually-- run `basic` and `smoke-infra` dry-runs-- verify `--test` block filtering still works--### Phase 7: Normalize Artifacts And Reports--Deliverables:--- create a run id and artifact root for every runner invocation-- write `report.json` and `report.txt`-- store per-test logs and artifact directories consistently-- print artifact paths on failure--Work:--- update host smoke scripts to respect `PINCHTAB_SMOKE_ARTIFACT_DIR`-- keep existing temp artifact retention behavior for direct script execution-- add report fields for provider, kind, suite, tags, and skip reason--Validation:--- run mixed smoke plan with at least one E2E scenario and one host command-- verify report includes both-- verify failure output points to useful logs--### Phase 8: Deprecate Duplicate Routing And Metadata--Deliverables:--- remove or shrink duplicate suite routing in `scripts/dev-smoke.sh`-- remove hardcoded host smoke step definitions from Go-- make `manifest.json` generated from catalog or delete it after migration-- document direct script entry points as compatibility/debug paths--Work:--- add deprecation comments where old paths remain-- update docs and CI commands to use catalog-backed suites-- make catalog validation part of normal Go tests--Validation:--- full E2E dry-run parity-- smoke CI run-- local opt-in smoke run for provider-sensitive checks--## Suggested Directory Layout--```text-tests/e2e/- catalog/- providers.json- services.json- suites.json- tests.json- config/- base profiles and templates- helpers/- base.sh- api.sh- cli.sh- browser.sh- dashboard.sh- autosolver.sh- scenarios/- api/- cli/- infra/- plugin/- .artifacts/--tests/tools/runner/internal/e2e/- catalog.go- catalog_test.go- planner.go- planner_test.go- adapter_e2e.go- adapter_host.go- config_materializer.go- config_materializer_test.go-```--The exact file split can change during implementation. The important boundary-is that catalog parsing, planning, execution adapters, provider materialization,-and report writing are separate concerns.--## Acceptance Criteria--The shared infrastructure is complete enough when:--- a new compose-backed E2E scenario can be added without editing Go code-- a new host smoke command can be added without editing Go code or- `scripts/dev-smoke.sh`-- `--dry-run` explains selected tests, provider expansion, services, and- dependency ordering-- Chrome and CloakBrowser provider behavior comes from one provider profile-- all smoke results appear in one report format-- artifacts are consistently stored and printed on failure-- existing direct script execution remains available for debugging-- CI can run the same catalog-backed smoke set as local `./dev smoke ci`--## Risks And Mitigations--- Risk: the catalog becomes another layer of indirection.- Mitigation: keep catalog entries small, validate them aggressively, and make- dry-run output readable.--- Risk: host smoke scripts have unique behavior that does not fit a generic- adapter.- Mitigation: keep `host-command` intentionally simple. The script can remain- custom while the runner standardizes selection, environment, logs, and- artifacts.--- Risk: provider config generation changes behavior.- Mitigation: add golden tests for generated configs and migrate provider- materialization after catalog planning is stable.--- Risk: migration disrupts CI.- Mitigation: make each phase additive, keep old entry points working, and- compare dry-run output before changing execution paths.--## Open Questions--- Should the catalog remain JSON, or should it move to YAML once the shape- stabilizes?-- Should `manifest.json` be replaced entirely, or generated from the catalog- for compatibility?-- Which host smoke scripts should be CI-blocking versus local opt-in?-- Should host smoke scripts standardize on `PINCHTAB_SMOKE_*` environment- variables before or after the runner wrapper lands?-- Should the config materializer live inside `tests/tools/runner/internal/e2e`- or under a reusable internal test package?diff --git a/docs/architecture/index.md b/docs/architecture/index.mdindex 1c7bcd11..80463e34 100644--- a/docs/architecture/index.md+++ b/docs/architecture/index.md@@ -24,8 +24,9 @@ The current managed implementation is bridge-backed. Any direct-CDP-only managedRelated architecture specs:-- [Browser Targets](./browser-targets.md): proposed multi-browser target model for- selecting Chrome, CloakBrowser, and future providers per request.+- [Browser Abstraction](./browser-abstraction.md): the multi-browser target model+ for selecting Chrome, CloakBrowser, and future providers per request (see the+ Target Architecture section).## System Overviewdiff --git a/docs/architecture/mcp.md b/docs/architecture/mcp.mdindex 969c7e04..c5282d2f 100644--- a/docs/architecture/mcp.md+++ b/docs/architecture/mcp.md@@ -1,4 +1,4 @@-# MCP Server Architecture+# MCP ServerThis page describes how the PinchTab MCP server is structured internally and how it integrates with the rest of the stack.diff --git a/docs/architecture/scheduler.md b/docs/architecture/scheduler.mdindex c64454a0..bac3785f 100644--- a/docs/architecture/scheduler.md+++ b/docs/architecture/scheduler.md@@ -1,4 +1,4 @@-# Scheduler Architecture+# SchedulerThis page describes how PinchTab's optional scheduler works internally.diff --git a/docs/deep-dive/benchmark.md b/docs/deep-dive/benchmark.mdindex af9fc76f..74cadad9 100644--- a/docs/deep-dive/benchmark.md+++ b/docs/deep-dive/benchmark.md@@ -1,4 +1,4 @@-# Benchmark: Deep Dive+# BenchmarkThis document compares two agent-driven browser surfaces — **PinchTab** and**agent-browser** — on a shared benchmark task set, driven through our APIdiff --git a/docs/deep-dive/lite-engin-prototype.md b/docs/deep-dive/lite-engin-prototype.mdindex 868e2294..0398e534 100644--- a/docs/deep-dive/lite-engin-prototype.md+++ b/docs/deep-dive/lite-engin-prototype.md@@ -1,4 +1,4 @@-# Lite Engine: Chrome-Free DOM Capture using Gost-DOM+# Lite Engine> **Deprecated:** This document describes the legacy engine model (`chrome`/`lite`/`auto`).> The engine has been replaced by the **browser provider** model. Use `browsers.default`diff --git a/docs/guides/remote-bridge-orchestrator.md b/docs/guides/remote-bridge-orchestrator.mdindex ac8dd38f..827c113e 100644--- a/docs/guides/remote-bridge-orchestrator.md+++ b/docs/guides/remote-bridge-orchestrator.md@@ -1,4 +1,4 @@-# Remote Bridge With Orchestrator+# Remote BridgeUse this guide when:diff --git a/docs/guides/tailscale-bridge-orchestrator.md b/docs/guides/tailscale-bridge-orchestrator.mdindex c8c44788..07ea03d3 100644--- a/docs/guides/tailscale-bridge-orchestrator.md+++ b/docs/guides/tailscale-bridge-orchestrator.md@@ -1,4 +1,4 @@-# A Tailscale Bridge Story: One Orchestrator, Remote Browsers+# One Orchestrator, Remote BrowsersThere is a simple distributed PinchTab shape that turns out to be very practical: