Plan 002: Add the semantic web provider seam

Executor instructions: Follow this plan step by step. Run every verification command and confirm the expected result before moving to the next step. If anything in the "STOP conditions" section occurs, stop and report. When done, update the status row for this plan in plans/README.md.

Drift check (run first): git diff --stat f9a9662f0..HEAD -- src/daemon/request-platform-providers.ts src/daemon/request-router.ts src/core/interactors.ts src/core/interactor-types.ts src/platforms test/integration/provider-scenarios
If any in-scope file changed since this plan was written, compare the current state below against the live code before proceeding; on mismatch, stop and report.

Status

• Priority: P1
• Effort: M
• Risk: MED
• Depends on: plans/001-web-platform-vocabulary.md
• Category: direction
• Planned at: commit f9a9662f0, 2026-06-19
• Parent PRD: feat: support web automation through agent-browser #817
• Issue: feat: add semantic web provider seam #819

Why this matters

ADR 0001 says provider-backed integration scenarios should run the real daemon path and replace only external providers. Web support needs the same seam before a local agent-browser adapter is added, otherwise tests will either mock too high or bind CI to Chrome.

Current state

• src/daemon/request-platform-providers.ts has provider resolver slots for Android ADB, Apple runner/tool, Linux tool, app logs, and recording.
• Linux is the closest pattern: a semantic provider sits below the interactor and provider scenarios assert semantic calls, not raw host commands.
• src/core/interactors.ts switches on platform and dynamically imports platform interactors.
• src/core/interactor-types.ts defines the semantic operations used by dispatch.

Commands you will need

Scope

In scope

• A WebProvider interface with semantic operations for the first slice.
• Request-scoped provider resolver and wrapper for platform: web.
• createWebInteractor that delegates to the current scoped web provider.
• Clear unsupported-operation errors for interactor methods outside the first slice.
• Unit tests for provider scoping.

Out of scope

• Local agent-browser implementation.
• Provider-backed scenario world.
• Public command additions.
• Browser-specific features beyond first-slice operations.

Steps

Step 1: Define the web provider contract

Add a focused provider module under the web platform area. The contract should expose semantic operations: open URL/target, close session/target, capture snapshot, capture screenshot, click, fill, type text, scroll, and optionally read text if snapshot-based read is insufficient.

Verify: pnpm typecheck catches only expected missing provider wiring.

Step 2: Add request provider scoping

Add a web provider resolver to request platform providers, following the descriptor pattern used by Linux. Scope it only when the resolved request device is platform: web.

Verify: add/update request provider tests and run pnpm exec vitest run src/daemon/__tests__/request-platform-providers.test.ts.

Step 3: Add the web interactor

Add createWebInteractor and route platform: web from getInteractor. Implement only first-slice methods and return normalized AppError unsupported messages for the rest.

Verify: pnpm typecheck exits 0.

Step 4: Wire snapshot backend identity

Add a web snapshot backend label and make the provider snapshot result map to existing snapshot state fields.

Verify: pnpm exec vitest run src/core/__tests__/dispatch-target.test.ts exits 0, plus any new focused web interactor tests.

Test plan

• Unit test that web provider resolver scopes only for web devices.
• Unit test that createWebInteractor calls semantic provider methods for supported operations.
• Unit test that unsupported operations return stable UNSUPPORTED_OPERATION errors.

Done criteria

• A web provider contract exists.
• Request-scoped provider wiring exists.
• getInteractor supports web.
• Unsupported methods are explicit and normalized.
• Targeted tests pass.
• pnpm typecheck exits 0.
• pnpm format exits 0.

STOP conditions

• The provider contract starts mirroring raw agent-browser CLI arguments instead of semantic browser intent.
• The implementation requires changes to public command identity.
• Provider scoping needs global mutable state outside the existing scoped-provider pattern.

Maintenance notes

Keep the provider contract small. New browser capabilities should add semantic methods only when a user-facing command needs them.