opendevbrowser 0.0.15 → 0.0.16

package/skills/opendevbrowser-best-practices/artifacts/command-channel-reference.md

@@ -0,0 +1,95 @@
+# Command and Channel Reference
+
+## Purpose
+
+Provide a compact, operationally useful map of OpenDevBrowser command surfaces and relay channels for parity checks.
+
+## Current coverage snapshot
+
+- CLI commands: `55`
+- Plugin tools: `48`
+- `/ops` command names: `38`
+- Legacy `/cdp` relay: generic CDP forwarding (method-level)
+
+Canonical exhaustive reference: `docs/SURFACE_REFERENCE.md`.
+CLI help mirror: `npx opendevbrowser --help` (surfaces CLI + tools + `/ops` + `/cdp` controls).
+
+## Agent skill-sync coverage
+
+Skill-pack installation/discovery is synchronized for:
+- `opencode`: `~/.config/opencode/skill` and `./.opencode/skill`
+- `codex`: `$CODEX_HOME/skills` (fallback `~/.codex/skills`) and `./.codex/skills`
+- `claudecode`: `$CLAUDECODE_HOME/skills` or `$CLAUDE_HOME/skills` (fallback `~/.claude/skills`) and `./.claude/skills`
+- `ampcli`: `$AMPCLI_HOME/skills` or `$AMP_CLI_HOME/skills` or `$AMP_HOME/skills` (fallback `~/.amp/skills`) and `./.amp/skills`
+
+Legacy aliases `claude` and `amp` remain present in installer target metadata for compatibility.
+
+## CLI surface categories
+
+- Install/runtime: install, update, uninstall, help, version, serve, daemon, native, run
+- Session/connection: launch, connect, disconnect, status, cookie-import, cookie-list
+- Navigation: goto, wait, snapshot
+- Interaction: click, hover, press, check, uncheck, type, select, scroll, scroll-into-view
+- Targets/pages: targets-list, target-use, target-new, target-close, page, pages, page-close
+- DOM: dom-html, dom-text, dom-attr, dom-value, dom-visible, dom-enabled, dom-checked
+- Export/diagnostics/macro/annotation/power: clone-page, clone-component, perf, screenshot, console-poll, network-poll, debug-trace-snapshot, macro-resolve, annotate, rpc
+
+## Tool surface categories
+
+- Runtime parity tools map to the CLI runtime categories.
+- Tool-only: `opendevbrowser_prompting_guide`, `opendevbrowser_skill_list`, `opendevbrowser_skill_load`.
+- CLI-only: `rpc`.
+
+## Relay channels
+
+### `/ops` (default)
+
+Namespace groups:
+- `session.*`
+- `storage.*`
+- `targets.*`
+- `page.*`
+- `nav.*`
+- `interact.*`
+- `dom.*`
+- `export.*`
+- `devtools.*`
+
+Handshake/liveness envelope types:
+- `ops_hello`, `ops_hello_ack`
+- `ops_ping`, `ops_pong`
+- `ops_request`, `ops_response`, `ops_error`
+- `ops_event`, `ops_chunk`
+
+Concurrency policy:
+- `/ops` supports multiple clients and multiple sessions.
+- Reliable parallel execution is session-scoped (`session-per-worker`).
+- Avoid concurrent independent streams that switch targets inside one session (`targets.use` races can cross-wire active target state).
+
+### `/cdp` (legacy)
+
+- Opt-in via `--extension-legacy`.
+- Forwards raw CDP commands through relay command envelopes (`id`, `method`, `params`, optional `sessionId`).
+- Use for compatibility-specific paths only.
+- Treat as a legacy/single-writer path; do not use as the primary route for concurrent automation.
+
+## Mode and flag checkpoints
+
+- Managed: `launch --no-extension`
+- Extension default: `launch` or relay-normalized `connect`
+- Extension legacy: `launch --extension-legacy` or `connect --extension-legacy`
+- Direct CDP: `connect --ws-endpoint ...` or `connect --host ... --cdp-port ...`
+
+Required readiness/status checks:
+- `extensionConnected`
+- `extensionHandshakeComplete`
+- `opsConnected`
+- `cdpConnected`
+- `pairingRequired`
+
+## Fast verification commands
+
+```bash
+npm run test -- tests/parity-matrix.test.ts
+./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh
+```

package/skills/opendevbrowser-best-practices/artifacts/debug-trace-playbook.md

@@ -0,0 +1,36 @@
+# Debug Trace Playbook
+
+## Purpose
+
+Run a repeatable debug pass and capture enough evidence to diagnose regressions quickly.
+
+## Minimum Trace Bundle
+
+- `requestId` and `sessionId`
+- snapshot output before and after key actions
+- console stream (`opendevbrowser_console_poll`)
+- network stream (`opendevbrowser_network_poll`)
+- screenshot evidence (`opendevbrowser_screenshot`)
+
+## Workflow
+
+1. Launch/connect and record `sessionId`.
+2. Reproduce issue with the smallest action sequence.
+3. Capture snapshot + console + network + screenshot at failure point.
+4. Normalize findings by `requestId` and timestamp.
+5. Re-run once in another mode (`managed` vs `extension` vs `cdpConnect`) to detect mode-specific drift.
+
+## Command Skeleton
+
+```text
+opendevbrowser_snapshot sessionId="<session-id>" format="outline"
+opendevbrowser_console_poll sessionId="<session-id>" max=100
+opendevbrowser_network_poll sessionId="<session-id>" max=100
+opendevbrowser_screenshot sessionId="<session-id>"
+```
+
+## Triage Rules
+
+- If refs fail: re-snapshot and retry one time.
+- If repeated 403/429: pause and apply cooldown/retry policy.
+- If failure reproduces in only one mode: mark as parity defect and gate release.

package/skills/opendevbrowser-best-practices/artifacts/fingerprint-tiers.md

@@ -0,0 +1,36 @@
+# Fingerprint Tiers
+
+## Purpose
+
+Choose the lowest hardening tier that keeps runs reliable; avoid unnecessary complexity.
+
+## Tiers
+
+### Tier 0 — Baseline
+
+- Default runtime behavior.
+- Use for internal pages and low-friction targets.
+
+### Tier 1 — Coherence Profile (default recommendation)
+
+- Consistent profile/session reuse.
+- Stable launch flags and deterministic workflow ordering.
+- Best default for most production automation.
+
+### Tier 2 — Runtime Hardening
+
+- Add stricter runtime controls (timeouts, retries, pacing discipline).
+- Use when targets show intermittent anti-bot or high flakiness.
+
+### Tier 3 — Adaptive Hardening (optional track)
+
+- Dynamic policy adjustments and canary validation loops.
+- Use only when Tier 1/2 cannot achieve target reliability.
+- Treat as opt-in track, not baseline release requirement.
+
+## Selection Heuristic
+
+1. Start Tier 0 for local validation.
+2. Promote to Tier 1 for shared/CI workflows.
+3. Use Tier 2 when failures are environment-dependent.
+4. Use Tier 3 only for sustained high-friction environments.

package/skills/opendevbrowser-best-practices/artifacts/macro-workflows.md

@@ -0,0 +1,43 @@
+# Macro Workflows
+
+## Purpose
+
+Define concise macro entrypoints that expand into repeatable provider workflows.
+
+## Macro Contract
+
+Each macro should declare:
+
+- `macro`: stable name
+- `provider`: `web|community|social`
+- `mode`: `managed|extension|cdpConnect`
+- `policyMode`: `read|write`
+- `requestId`: required correlation id
+
+## Recommended Macros
+
+### `provider.search`
+
+- Expands to launch/connect + goto + wait + snapshot + extract + network poll.
+- Output: normalized result set with provenance fields.
+
+### `provider.crawl`
+
+- Expands to bounded multipage loop (queue + dedupe + depth/page limits).
+- Output: `records[]`, `visited[]`, and crawl stats.
+
+### `qa.debug`
+
+- Expands to snapshot + console poll + network poll + screenshot.
+- Output: trace bundle for triage.
+
+### `safe.post`
+
+- Expands to notice + preview + explicit confirmation + single write action.
+- Output: write result and audit metadata.
+
+## Expansion Rules
+
+- Keep expansions deterministic and minimal.
+- Emit provenance metadata (`macro`, `resolvedQuery`, `provider`, `mode`).
+- Never hide write actions behind implicit macro behavior.

package/skills/opendevbrowser-best-practices/artifacts/parity-gates.md

@@ -0,0 +1,36 @@
+# Parity Gates
+
+## Purpose
+
+Define hard pass/fail gates so CLI, tool, and runtime surfaces stay aligned.
+
+## Parity Matrix
+
+| Area | Modes | Surfaces | Gate |
+|---|---|---|---|
+| Session lifecycle | managed, extension, cdpConnect | CLI + tools + runtime | `launch/connect/disconnect/status` parity |
+| Navigation + refs loop | managed, extension, cdpConnect | CLI + tools + runtime | `goto/wait/snapshot` parity |
+| Interaction | managed, extension, cdpConnect | CLI + tools + runtime | click/type/select/scroll/press/check/uncheck parity |
+| Targets + pages | managed, extension, cdpConnect | CLI + tools + runtime | target/page command parity |
+| DOM + diagnostics + export | managed, extension, cdpConnect | CLI + tools + runtime | dom/perf/screenshot/console/network/clone parity |
+| Relay channels | extension (default) + extension-legacy | `/ops` + `/cdp` | `/ops` namespace coverage + `/cdp` envelope compatibility |
+
+## Surface Rules
+
+- `rpc` is intentionally CLI-only (internal and unsafe).
+- `opendevbrowser_prompting_guide`, `opendevbrowser_skill_list`, and `opendevbrowser_skill_load` are intentionally tool-only.
+- Any new stable CLI runtime command must add a matching tool unless explicitly documented as CLI-only.
+- Surface counts and command inventories are verified against `docs/SURFACE_REFERENCE.md`.
+
+## Gate Commands
+
+```bash
+npm run test -- tests/parity-matrix.test.ts
+npm run test -- tests/tools.test.ts tests/daemon-command.test.ts
+npm run test -- tests/providers-performance-gate.test.ts
+```
+
+## Release Requirement
+
+Ship only when parity tests pass and docs (`README.md`, `docs/CLI.md`, `docs/ARCHITECTURE.md`, `docs/SURFACE_REFERENCE.md`) reflect the same surface map.
+Use `docs/RELEASE_PARITY_CHECKLIST.md` as the release gate source of truth.

package/skills/opendevbrowser-best-practices/artifacts/provider-workflows.md

@@ -0,0 +1,89 @@
+# Provider Workflows
+
+## Purpose
+
+Codify minimal, repeatable workflows for provider-native automation.
+
+## Inputs
+
+- `sessionMode`: `managed|extension|cdpConnect`
+- `provider`: `web|community|social`
+- `requestId`: unique per workflow run
+- `policyMode`: `read` (default) or `write` (explicit/manual opt-in only)
+
+## Workflow A: Provider Search
+
+1. Launch/connect mode.
+2. Navigate to provider query URL.
+3. Wait for load (`networkidle` preferred).
+4. Snapshot actionables.
+5. Extract result units with refs.
+6. Poll network for request health.
+7. Emit normalized records.
+
+Expected output:
+- `items[]` with `title/url/snippet/source/ts/requestId`
+
+## Workflow B: Provider Fetch
+
+1. Launch/connect mode.
+2. Goto target URL/entity endpoint.
+3. Wait and snapshot.
+4. Extract typed fields.
+5. Poll console/network for anomalies.
+
+Expected output:
+- one normalized entity record + diagnostics metadata
+
+## Workflow C: Multipage Crawl
+
+1. Seed queue with initial URL list.
+2. Process one URL at a time:
+- goto
+- wait
+- snapshot
+- extract
+- collect outgoing links
+3. Canonicalize/dedupe links.
+4. Enqueue until `maxDepth|maxPages` reached.
+5. Persist records with page provenance.
+
+Expected output:
+- `records[]`
+- `visited[]`
+- `frontierStats`
+
+## Workflow D: Social Read-Only Validation (Default)
+
+1. Display read-only policy notice.
+2. Navigate to social target and execute search/read probes only.
+3. Capture `debug-trace-snapshot` + `network-poll`.
+4. Record auth/blocker diagnostics and provider health.
+
+Expected output:
+- `readResult` + `authBlockerDiagnostics`
+
+## Workflow E: Parallel Multipage (Reliable As-Is)
+
+1. Build a bounded frontier/queue in host logic.
+2. Allocate one session per worker (`session-1`, `session-2`, ...).
+3. In each worker session, process URLs serially:
+- goto
+- wait
+- snapshot
+- extract
+- emit records with `sessionId` + page provenance
+4. Never interleave competing `target-use` streams inside a single session.
+5. For managed persistent profiles, assign a unique profile path per worker session.
+6. Merge worker outputs deterministically (stable sort + dedupe key).
+
+Expected output:
+- `records[]` merged across workers
+- `workerStats[]` with `{ sessionId, processed, failures }`
+- `frontierStats` and checkpoint state
+
+## Failure Policy
+
+- stale refs: re-snapshot and retry once
+- repeated 403/429: stop and cooldown
+- inconsistent mode behavior: flag parity failure

package/skills/opendevbrowser-best-practices/assets/templates/cdp-forward-envelope.json

@@ -0,0 +1,11 @@
+{
+  "id": 1,
+  "method": "forwardCDPCommand",
+  "params": {
+    "method": "Runtime.evaluate",
+    "params": {
+      "expression": "document.title"
+    },
+    "sessionId": "optional-flat-session-id"
+  }
+}

package/skills/opendevbrowser-best-practices/assets/templates/mode-flag-matrix.json

@@ -0,0 +1,56 @@
+{
+  "schemaVersion": "1.0",
+  "modes": [
+    {
+      "name": "managed",
+      "launch": "npx opendevbrowser launch --no-extension",
+      "statusProbe": "npx opendevbrowser status --session-id <session-id>",
+      "requiredFlags": [
+        "--no-extension"
+      ],
+      "statusExpectations": {
+        "mode": "managed"
+      }
+    },
+    {
+      "name": "extension",
+      "launch": "npx opendevbrowser launch --extension-only --wait-for-extension",
+      "statusProbe": "npx opendevbrowser status --daemon",
+      "requiredFlags": [
+        "--extension-only",
+        "--wait-for-extension"
+      ],
+      "statusExpectations": {
+        "extensionConnected": true,
+        "extensionHandshakeComplete": true,
+        "opsConnected": true
+      }
+    },
+    {
+      "name": "extension-legacy",
+      "launch": "npx opendevbrowser launch --extension-only --extension-legacy --wait-for-extension",
+      "statusProbe": "npx opendevbrowser status --daemon",
+      "requiredFlags": [
+        "--extension-only",
+        "--extension-legacy",
+        "--wait-for-extension"
+      ],
+      "statusExpectations": {
+        "extensionConnected": true,
+        "extensionHandshakeComplete": true,
+        "cdpConnected": true
+      }
+    },
+    {
+      "name": "cdpConnect",
+      "connect": "npx opendevbrowser connect --ws-endpoint ws://127.0.0.1:9222/devtools/browser/<id>",
+      "statusProbe": "npx opendevbrowser status --session-id <session-id>",
+      "requiredFlags": [
+        "--ws-endpoint"
+      ],
+      "statusExpectations": {
+        "mode": "cdpConnect"
+      }
+    }
+  ]
+}

package/skills/opendevbrowser-best-practices/assets/templates/ops-request-envelope.json

@@ -0,0 +1,9 @@
+{
+  "type": "ops_request",
+  "requestId": "req-session-status-001",
+  "clientId": "ops-client-1",
+  "opsSessionId": "ops-session-123",
+  "leaseId": "lease-123",
+  "command": "session.status",
+  "payload": {}
+}

package/skills/opendevbrowser-best-practices/assets/templates/robustness-checklist.json

@@ -0,0 +1,79 @@
+{
+  "schemaVersion": "1.0",
+  "skill": "",
+  "run_id": "",
+  "issues": [
+    {
+      "id": "ISSUE-01",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-02",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-03",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-04",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-05",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-06",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-07",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-08",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-09",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-10",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-11",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-12",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    }
+  ]
+}

package/skills/opendevbrowser-best-practices/assets/templates/surface-audit-checklist.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": "1.0",
+  "expectedCounts": {
+    "cliCommands": 50,
+    "tools": 44,
+    "opsCommands": 36
+  },
+  "docsMustCover": [
+    "README.md",
+    "docs/CLI.md",
+    "docs/ARCHITECTURE.md",
+    "docs/SURFACE_REFERENCE.md",
+    "AGENTS.md",
+    "skills/opendevbrowser-best-practices/SKILL.md"
+  ],
+  "checks": [
+    "CLI command names documented by category",
+    "Tool names documented by category",
+    "Ops command namespaces documented",
+    "CDP envelope contract documented",
+    "Global and command-specific flags documented",
+    "Mode semantics documented"
+  ]
+}

package/skills/opendevbrowser-best-practices/scripts/odb-workflow.sh

@@ -0,0 +1,144 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+print_help() {
+  cat <<'EOF'
+OpenDevBrowser workflow router
+
+Usage:
+  ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh <workflow>
+
+Workflows:
+  provider-search
+  provider-crawl
+  parallel-multipage-safe
+  qa-debug
+  social-readonly-check
+  parity-check
+  surface-audit
+  ops-channel-check
+  cdp-channel-check
+  mode-flag-matrix
+  robustness-audit
+  list
+EOF
+}
+
+workflow="${1:-list}"
+
+case "$workflow" in
+  list)
+    print_help
+    ;;
+  provider-search)
+    cat <<'EOF'
+opendevbrowser_launch noExtension=true
+opendevbrowser_goto sessionId="<session-id>" url="<provider-search-url>"
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
+opendevbrowser_network_poll sessionId="<session-id>" max=50
+EOF
+    ;;
+  provider-crawl)
+    cat <<'EOF'
+opendevbrowser_launch noExtension=true
+opendevbrowser_goto sessionId="<session-id>" url="<seed-url>"
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
+opendevbrowser_scroll sessionId="<session-id>" dy=1000
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+EOF
+    ;;
+  parallel-multipage-safe)
+    cat <<'EOF'
+# Reliable parallel pattern (as-is):
+# - Worker A owns session-a
+# - Worker B owns session-b
+# - Keep each session serial (snapshot -> action -> snapshot)
+# - Do NOT interleave independent target-use streams in one session
+# - Managed + persisted profiles: use unique profile paths per session
+
+opendevbrowser_launch noExtension=true
+opendevbrowser_launch noExtension=true
+
+# Worker A loop
+opendevbrowser_goto sessionId="<session-a>" url="<url-a1>"
+opendevbrowser_wait sessionId="<session-a>" until="networkidle"
+opendevbrowser_snapshot sessionId="<session-a>" format="actionables"
+
+# Worker B loop
+opendevbrowser_goto sessionId="<session-b>" url="<url-b1>"
+opendevbrowser_wait sessionId="<session-b>" until="networkidle"
+opendevbrowser_snapshot sessionId="<session-b>" format="actionables"
+EOF
+    ;;
+  qa-debug)
+    cat <<'EOF'
+opendevbrowser_snapshot sessionId="<session-id>" format="outline"
+opendevbrowser_console_poll sessionId="<session-id>" max=100
+opendevbrowser_network_poll sessionId="<session-id>" max=100
+opendevbrowser_screenshot sessionId="<session-id>"
+EOF
+    ;;
+  social-readonly-check)
+    cat <<'EOF'
+# Read-only social validation (default, no posting).
+opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
+opendevbrowser_debug_trace_snapshot sessionId="<session-id>" maxEvents=50
+opendevbrowser_network_poll sessionId="<session-id>" max=100
+EOF
+    ;;
+  parity-check)
+    cat <<'EOF'
+npm run test -- tests/parity-matrix.test.ts
+npm run test -- tests/tools.test.ts tests/daemon-commands.integration.test.ts
+./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh
+EOF
+    ;;
+  surface-audit)
+    cat <<'EOF'
+cat docs/SURFACE_REFERENCE.md
+cat skills/opendevbrowser-best-practices/artifacts/command-channel-reference.md
+cat skills/opendevbrowser-best-practices/assets/templates/surface-audit-checklist.json
+./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh
+EOF
+    ;;
+  ops-channel-check)
+    cat <<'EOF'
+npx opendevbrowser serve
+npx opendevbrowser launch --extension-only --wait-for-extension --output-format json
+npx opendevbrowser status --daemon --output-format json
+# Verify opsConnected=true and extensionHandshakeComplete=true
+cat skills/opendevbrowser-best-practices/assets/templates/ops-request-envelope.json
+EOF
+    ;;
+  cdp-channel-check)
+    cat <<'EOF'
+npx opendevbrowser serve
+npx opendevbrowser launch --extension-only --extension-legacy --wait-for-extension --output-format json
+npx opendevbrowser status --daemon --output-format json
+# Verify cdpConnected=true while legacy session is active
+cat skills/opendevbrowser-best-practices/assets/templates/cdp-forward-envelope.json
+EOF
+    ;;
+  mode-flag-matrix)
+    cat <<'EOF'
+cat skills/opendevbrowser-best-practices/assets/templates/mode-flag-matrix.json
+npx opendevbrowser launch --no-extension --output-format json
+npx opendevbrowser launch --extension-only --wait-for-extension --output-format json
+npx opendevbrowser launch --extension-only --extension-legacy --wait-for-extension --output-format json
+EOF
+    ;;
+  robustness-audit)
+    cat <<'EOF'
+cat skills/opendevbrowser-best-practices/artifacts/browser-agent-known-issues-matrix.md
+cat skills/opendevbrowser-best-practices/assets/templates/robustness-checklist.json
+./skills/opendevbrowser-best-practices/scripts/run-robustness-audit.sh
+EOF
+    ;;
+  *)
+    echo "Unknown workflow: $workflow" >&2
+    print_help
+    exit 2
+    ;;
+esac