[williamloo-scale]

Stacked on #427.

agentenv_protocol.website: the easy path to a synthetic website that follows website/v1 (urn:agentenv:website/v1).

@environment_card(name="notes")
@website(domains=["notes.test"], static="web/dist")
class Notes(WebsiteEnvironment):
    @get_data
    def export(self) -> list:
        return [DataPart(data={"notes": self.db.all_notes()})]

    @api.get("/api/notes")
    def list_notes(self, ctx: ApiContext) -> list:
        return self.db.notes(owner=ctx.user)

• @api.get/post/put/patch/delete(path, name=, roles=, status=): path, query and body are bound from type hints, errors are exceptions mapped to statuses, and an OpenAPI 3.1 document is generated.
• ApiContext: the signed-in user (else the acting user, so the agent starts signed in), the caller's role, and the public URL from X-Forwarded-Host/-Proto.
• Roles: the gateway forwards whatever AgentEnv-Role a browser sends, so a site believes a non-default role only when the request also carries AgentEnv-Role-Key equal to the site's WEBSITE_ROLE_KEY (compared in constant time). Every other caller, and every caller of a site with no key set, is default, so roles= routes are closed until a key is set.
• Serves the built pages with an index.html fallback, the data plane and a card declaring website/v1 with its routes and openapi/ready/session operations.
• Readiness is website/v1's ready alone, as a computer app's is computer-app/v1's: @ready_check methods run at once, each within 10 s, a plain def in a worker thread and one call at a time, each problem saying what the check returned, raised or how long it ran. The answer carries waited_s and the timeout_s from @website(ready_timeout_s=...) (300 s by default), which is how long a deploy waits for the site. There is no health= path; a server whose card has no ready is still read at its health path, which is deprecated. /agentenv… routes are matched before the site's own.
• self.now() reads the universe clock (clock/v1 sync_time), read once per request from the gateway as MCP servers read it, so a frozen clock is exactly frozen. An unarmed clock is wall time, and an unreachable one answers 503, except on the data plane and the card. An empty env_get_time_url goes back to wall time. Every response carries X-Universe-Now; clock_patch=True patches the page's Date. sync_time also takes main's optional timezone (feat(sync_env_clock): an optional timezone reads virtual_time in the zone and tells every synced server (FD-5003) #442), which the site reads as self.timezone; now() stays UTC.
• A site keeps its own data, usually in its schema of the env's database (database_url), and serves it through the data plane's hooks (@reset_data, @add_data, @get_data) as any AgentEnvEnvironment does. The SDK has no store of its own. A site's data is read and written only through the data plane, and the SDK serves no /go and no website/v1 state op.
• Sessions: the signed agentenv_session cookie lasts its Max-Age (7 days), never an absolute Expires, so a browser on another clock judges it the same. A deploy gives each site its own WEBSITE_SESSION_SECRET, so sessions outlive a restart or a snapshot reload; a site run without one (local serve()) draws its own. website/v1's session {user?} answers a storage state, {cookies, local_storage}, each cookie with max_age.
• Plain def @api handlers run in a worker thread, as FastAPI's do. A route whose type hints can't be resolved fails the app's build, and session cookies go on successful answers only. The static fallback never serves a dot-named path.
• website_state_verifier, which feat(website): a website env is one server image, checked at its health path (FD-4683) #390 merged and which read a site's /go?sid=, is removed. Grading a website from data/get against the task's initial state moves to agentenvhub-sdk's cua_gym_verifier, a separate PR in scaleapi2.
• python -m agentenv_protocol.website.conformance URL checks any server over HTTP: card, any host name, health, universe time, data plane, clock, forwarded headers, cookies. It sends nothing to a server other than the one under check, and its clock check syncs the server back to wall time at the end. A cookie with an absolute Expires and no Max-Age warns without failing the run.

Breaking

• website_state_verifier (from feat(website): a website env is one server image, checked at its health path (FD-4683) #390, released in v0.9.1429–1431) is removed. No stored AgentEnvHub task uses it: 0 of 589,350 synced tasks on Nov 4.

Known gaps

Each is fixed later in the stack, as noted.

• Roles are authenticated only inside SDK sites: nothing sets WEBSITE_ROLE_KEY on a deployed site yet, and the gateway still trusts AgentEnv-Role on MCP calls, non-SDK sites and website trigger attribution. A per-deploy key in the gateway is the full fix (feat(gateway): a keyed deploy's role key, forwarded headers, and triggers by route (FD-4683) #443, opt-in with keyed_roles).
• The gateway sends no X-Forwarded-*, so behind it sites must use relative URLs (feat(gateway): a keyed deploy's role key, forwarded headers, and triggers by route (FD-4683) #443).
• SDK sites in one multi env share the session cookie name (feat(website): a session cookie per site, the clock's rate, conformance levels and models= (FD-4683) #444).
• Conformance requires X-Universe-Now and a filled-in card, stricter than a non-SDK server may be (feat(website): a session cookie per site, the clock's rate, conformance levels and models= (FD-4683) #444 splits required from recommended).

Test

packages/agentenv-protocol/tests: 1,121 passed after the readiness edits (b5dbda6), with the provider and env unit tests; lint clean. Full unit suite on CI. Before them: unit suite and protocol tests 12,659 passed.
End to end on a local Docker gateway (f22dff3): an SDK site sharing the name slack with an MCP server, beside the website browser. The deploy waited on ready (waited_s 21.4, timeout_s 120) and never read a health path; the compose carries a 64-hex WEBSITE_SESSION_SECRET, masked in the log. Conformance passed 8/8 through /svc/slack/. After sync_env_clock a frozen clock read exactly frozen, and a set-time showed on the next answer with no re-sync. The session cookie has Max-Age=604800 and no Expires, and a signed-in cookie still read as its user after a snapshot reload recreated the site's container. The universe's slack loaded into the MCP server.
packages/agentenv-protocol/tests: 946 passed; the website tests (59, with the Notes ones) pass after the role-key fix. Deployed locally behind the gateway, a spoofed AgentEnv-Role: admin now gets 403 on both /website/ and /svc/ (200 before).

🤖 Generated with Claude Code

Confidence Score: 5/5

The latest change appears safe to merge; it makes the worker-thread test reliable without changing site behavior.

Summary

Adds WebsiteEnvironment with typed API routes, sessions, universe time, readiness checks, and an HTTP conformance checker.

• WebsiteEnvironment serves pages, typed routes, and AgentEnv data.
• A command checks whether a server follows the website/v1 contract.
• Deployments use a site's website/v1 readiness answer.
• Browser routes keep site data and AgentEnv endpoints private.
• Environment callers can tell websites and MCP servers apart.
• The website state verifier is removed from task grading.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Browser --> Gateway
  Gateway -->|Site requests| WebsiteEnvironment
  Framework -->|Data and control requests| WebsiteEnvironment
  WebsiteEnvironment --> API[Typed API handlers]
  WebsiteEnvironment --> Pages[Static pages or mounted app]
  WebsiteEnvironment --> Clock[Universe clock]
  Checker[Conformance checker] -->|HTTP checks| WebsiteEnvironment

Loading

_{Reviews (19) · Last reviewed commit: "test(website): compare a plain def route..." · Reviewed by Greptile}

[earakely-scale]

This is a huge red flag: it leaks CUA-Gym into agentenv-framework. /go?sid= is CUA-Gym's verifier endpoint, and this PR builds it into the SDK and the website/v1 contract rather than keeping it outside the framework:

• The SDK: agentenv_protocol.website defines and exports STATE_PATH = "/go" (environment.py:51, __init__.py:15). Every store-backed SDK site serves its state there (environment.py:173) and advertises it as website/v1's params.state.path (environment.py:198).
• Conformance: the checker reads state at params.state.path, else at /go (conformance.py:200-208), so it judges any server by CUA-Gym's convention.
• Verifier and gateway: website_state_verifier falls back to params.state.path, else /go?sid= (website_state_verifier.py:37, :279-283). The gateway's guard is built around params.state.path (gateway.py:1556). The /go fallback predates this PR, but this PR extends it.

website/v1's state op should be the only state contract: an SDK site answers its state only through it. Please drop /go and params.state.path from the SDK, the conformance check and website/v1. If CUA-Gym sites still need to be read at /go, that compatibility belongs in a CUA-Gym adapter outside the framework, not in agentenv_protocol or the core verifier.

[earakely-scale]

Following up on my /go comment: please remove CUA-Gym's verifier model from the framework altogether. That model is a site serving {initial_state, current_state, state_diff} per sid, and a verifier reading it. This goes further than my earlier note, so drop the website/v1 state op too, since it's the same model under another name. agentenv already has the primitives for this:

What the verifier needs	agentenv primitive
current state	the data plane's data/get, which SDK sites already serve from the same store (_store_get)
initial state	the universe the task loaded with data/add, or a snapshot_env taken before the agent starts
diff	computed once, in the verifier, from those two, the same for every env instead of each site writing its own (that also removes the store-id diff problem)
sid	not needed: each deploy gets its own site, and the SDK already ignores it
keeping state from the agent	the data plane is framework-only and already refused on the browsing route

Concretely:

• SDK: remove the /go route, STATE_PATH, params.state.path, the state op, and the store's site-side state and diff (Collections.state() / diff()). A site exposes its data through data/get only.
• Verifier: grade by reading data/get against the initial state, keeping the check model (path, op, value, reduce, weight). It then works for any env, MCP servers included, not only websites.
• Conformance and gateway: check data/get rather than /go or state. Drop the params.state.path reservation.
• Main: website_state_verifier as feat(website): a website env is one server image, checked at its health path (FD-4683) #390 merged it reads /go?sid=. Replace it with the above rather than extending it. CUA-Gym images that serve only /go get an adapter outside the framework.

[williamloo-scale]

Agreed, and done in this stack rather than deferred. /go?sid= and the per-site {initial_state, current_state, state_diff} model were CUA-Gym's, and they're gone from the framework:

• SDK: the /go route, STATE_PATH, params.state.path, the website/v1 state op and the store's initial/current/diff state are removed. A site exposes its data only through the data plane: data/get, data/add and data/reset. feat(website): a session cookie per site, the clock's rate, conformance levels and models= (FD-4683) #444's ?sid= sessions existed only for /go, so they're removed too.
• Verifier: website_state_verifier, which feat(website): a website env is one server image, checked at its health path (FD-4683) #390 merged and which read /go?sid=, is removed from the framework.
• Conformance: always checks the data/get round trip.
• Gateway: no longer reserves a state path, but still keeps the data plane, the card and every path the card advertises off a site's browsing route.
• Spec (feat(website): one spec declares a site, composes it and checks any server (FD-4683) #445): the [state] section is dropped.

Each PR removes what it had added, so the stack never introduces any of this. Grading a website now belongs outside the framework: cua_gym_verifier in agentenvhub-sdk, in a separate scaleapi2 PR. It reads data/get, diffs it against the task's initial state (the universe it loaded or a snapshot_env), and keeps the check model: path, op, value, reduce and weight.

[williamloo-scale]

@greptile-apps all three remaining review comments are fixed in d4efdbb, each with a test that fails without its fix:

• Partial HTML downloads change (environment.py): _Universe no longer injects the clock script into a partial answer. A 206, or any answer with Content-Range, passes through unchanged, so its bytes still match the promised range.
• Query lists lose item types (routes.py): a list[T] query parameter is documented as {"type": "array", "items": <T's schema>}, and it still binds as repeated values.
• Working clocks can fail (conformance.py): _clock() looks up sync_time by name instead of taking the first operation the card lists.

The full unit suite passes on this commit (12,908) and lint is clean. All three threads are replied to and resolved.

[greptile-apps]

Confirmed: all three findings are fixed in d4efdbbf and have regression coverage:

• Partial HTML downloads: _Universe skips clock-script injection for status 206 and responses with Content-Range; the test verifies a range response remains unchanged.
• Query-list item types: OpenAPI now includes the item schema for list query parameters, while binding still uses repeated query values; the test checks list[int] documentation and binding.
• Clock operation selection: the checker finds sync_time by name; the test passes when another clock operation is listed first.

These comments can remain resolved. I verified the code and tests in the commit; I did not independently run the suite.