Add WebMCP discovery and invocation API

[rgarcia]

Summary

• add GET /webmcp/tools and POST /webmcp/invoke so callers can discover and invoke native page tools without managing browser protocol events
• lazily reuse one browser-level connection and track every existing and newly opened tab, window, popup, and embedded frame
• expose frozen webmcp.listTools() and webmcp.invokeTool() helpers inside Playwright execution by routing through the same HTTP API
• extend the existing CDP client with opt-in event delivery and concurrent command routing, then layer the reusable browser-surface model and WebMCP registry on top
• return one flat tool snapshot with monotonic integer window, tab, and optional embedded-frame IDs while keeping raw protocol IDs internal
• invalidate stale registrations across committed navigation and closure, preserve completed responses during teardown, and report ambiguous outcomes without automatic retries
• validate invoke requests against the documented required fields, bounds, and unknown-property policy

Validation

• go vet ./...
• go test -race $(go list ./... | grep -v /e2e$)
• node --test runtime/*.test.ts
• focused lifecycle, navigation, shared-CDP transport, disconnect-ordering, and event-backpressure tests under repeated -race runs
• verified browser-wide discovery and invocation against live top-document, cross-origin iframe, and nested cross-origin iframe tools
• verified 20/20 fresh Playwright-connected OOPIF discovery/invocation cycles across process swaps
• re-verified the shared CDP transport at exact head ffa3dd0 in 10/10 fresh real-image cycles across top-level, same-origin, OOPIF, and nested-OOPIF tools through both Playwright helpers and HTTP
• verified duplicate-name routing, popup survival after opener closure, dynamic registrations, stale refs, concurrent invokes, timeout behavior, and provenance
• verified unresolved navigation returns outcome_unknown, completed-before-navigation results survive, and aborted navigation preserves the original registration
• verified malformed invoke requests return schema-compatible JSON errors

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 7f26744. Configure here.}

[sjmiller609]

applicable to users not using WebMCP

• Small fix: server/runtime/playwright-daemon.ts:309-314 — injecting webmcp as a function parameter breaks existing Playwright code declaring const webmcp, let webmcp, or class webmcp. it now fails with a syntax error. Seems unlikely but easy fix?

• Note: server/cmd/api/main.go:253-258 — custom strict error handlers apply globally. malformed requests to every existing endpoint change from plaintext errors to JSON, even when WebMCP is unused.

• Note: server/lib/cdpclient/cdpclient.go — the shared CDP transport was rewritten for all existing callers. Existing e2e tests look sufficient to cover this, keep in mind for the rollout.

only affects WebMCP users

• server/lib/browsersurface/frames.go:119-129 — a transient Page.enable or Page.getFrameTree failure leaves the session permanently uninitialized. tools remain missing until the CDP connection is recreated.

• server/cmd/api/api/webmcp.go:75-82 — the 1 MiB input limit is enforced only after the full body has been decoded and re-marshaled, so oversized requests can consume significant memory before rejection.