PR Summary

What problems was I solving

This PR introduces the first end-to-end field-agent website validation demo. It moves field-agent page-context generation out of page-analytics-service and into webpage-context-service, adds a durable lifecycle for generating per-page validation/highlight scripts, and exposes a management UI status query so the team can observe progress.

What user-facing changes did I ship

For configured customer sites, the field-agent visitor-analytics module now injects a /t/:tenantId/va/page.js validation script that draws an overlay on components and action targets detected on the public page. The management console gains a fieldAgentExtractionStatus query to poll generation progress (pending/running/completed/failed). These changes are limited to the field-agent demo flow and do not alter existing analytics behavior.

How I implemented it

The implementation adds a new field_agent_extractions table and repository, deterministic DOM canonicalisation via Stagehand over a Kernel browser (using a newly exposed CDP session in browser-runtime), Effect-based app orchestration, and a Temporal workflow that validates the URL, observes the page, persists a component snapshot and canonical targets, and uploads a generated overlay script. The field-agent-gateway-service adds the /va/page.js redirect endpoint; web-service serves uploaded scripts from the file service; and management-gateway-service exposes the status query.

Description for the changelog

Adds the field-agent website validation demo by moving page-context generation into webpage-context-service, introducing a persisted extraction lifecycle, deterministic DOM-based canonicalisation, a Stagehand-driven browser adapter, and a generated validation overlay script served via the field-agent gateway. Also adds a management GraphQL extraction-status query and a local demo script for end-to-end testing.

Webpage Context Service: Field Agent Database Layer

high11 files
Adds the `field_agent_extractions` table and repository to persist field-agent validation-script generation lifecycle state.

Service Application Build Config for Stagehand

high1 file
Adjusts the service-application build so the Stagehand dependency is bundled/resolved correctly for the new field-agent runtime.

Infrastructure: Caddy Frontend Routing

high1 file
Updates Caddy frontend comments and hard-404 body for the `/t/*/va/*` field-agent gateway route.

Webpage Context Service: Field Agent API Contract

medium2 files
Extends the WebpageContextService RPC contract with three new field-agent validation-script methods and branded types.

Browser Runtime: Kernel CDP Session Exposure

medium7 files
Exposes Kernel's CDP WebSocket endpoint so Stagehand can connect to a managed browser session.

Webpage Context Service: Field Agent Core Derivation Logic

medium12 files
Implements the deterministic webpage canonicalisation, snapshot derivation, script building, and URL policy logic for field-agent.

Webpage Context Service: Field Agent App Layer

medium7 files
Wires the field-agent extraction use cases: start generation, check status, and resolve scripts for a page URL.

Webpage Context Service: Field Agent Browser/Stagehand Adapters

medium9 files
Provides the Stagehand+Kernel browser adapter and deterministic DOM operations for canonical page observation.

Webpage Context Service: Field Agent Temporal Workflow

medium6 files
Adds a Temporal workflow that durably orchestrates validation-script generation activities.

Webpage Context Service: Field Agent Implementation Wiring

medium4 files
Plugs field-agent activities, workflow starter, configuration, and RPC handlers into the WebpageContextService implementation.

Field Agent Gateway Service: Validation Script HTTP Endpoint

medium6 files
Adds `/t/:tenantId/va/page.js` to the field-agent gateway, redirecting to a generated validation script or triggering generation.

Field Agent Gateway Service: Validation Script Use Case & Ports

medium8 files
Defines the gateway's validation-script provider port and the use case that decides whether to redirect, wait, or start generation.

Web Service: Validation Script Serving Middleware

medium3 files
Adds a public Connect middleware that streams uploaded field-agent validation scripts from the file service.

Management Gateway Service: Extraction Status GraphQL

medium5 files
Adds a `fieldAgentExtractionStatus` GraphQL query that proxies to the webpage-context service.

Field Agent UI: Validation Script Injection

medium2 files
Injects a per-tenant validation-script tag before booting visitor analytics, and reloads on SPA URL changes.

Page UI: Analytics Derivation Contract v33

medium2 files
Bumps the analytics derivation contract to v33 and lists the new field-agent core files as derivation-critical.

Root Package & Monorepo Config Changes

medium5 files
Moves Stagehand to runtime dependencies, adds optional canvas dependency, disables Nx analytics, and regenerates path/typecheck manifests.

Management UI: Extraction Status Operation

low2 files
Adds the generated GraphQL operation and TypeScript contract for polling field-agent extraction status.

Page Analytics Service: Field-Agent Cleanup & Design Docs

low7 files
Adds design docs for the field-agent slice move and performs minor import/style cleanup in page analytics.

External Actor Gateway Service: Whitespace-only Cleanup

low2 files
No functional change; adds/removes blank lines only.

Local Development & Demo Tooling

low2 files
Adds a local demo script for field-agent website validation and updates the page-analytics DB reset helper.