[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", health="/healthz", data="data/seed.json")
class Notes(WebsiteEnvironment):
    @api.get("/api/notes")
    def list_notes(self, ctx: ApiContext) -> list:
        return self.store.find("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 health path with @ready_check, the data plane and a card declaring website/v1 with its routes and openapi/session operations. /agentenv… routes are matched before the site's own.
• self.now() reads the universe clock (clock/v1 sync_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.
• Collections store: load, export, reset, initial/current/diff state and /go with no data hooks written.
• 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.

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, /go?sid=, 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, /go?sid=, the clock's rate, conformance levels and models= (FD-4683) #444 splits required from recommended).
• /go ignores sid (feat(website): a session cookie per site, /go?sid=, the clock's rate, conformance levels and models= (FD-4683) #444).

Test

Unit suite and protocol tests: 12,659 passed, lint clean.
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 PR appears safe to merge with two non-blocking contract issues.

Findings

1.  Bodyless responses promise JSON ▶
2.  Reserved paths serve site pages ▶

Fix with agent prompt

### Issue 1
packages/agentenv-protocol/src/agentenv_protocol/website/routes.py:337-340
`openapi()` advertises a JSON response body for a typed handler even when its declared status is `204` or `304`. But `endpoint()` drops that body. A delete route returning a model with `status=204` therefore publishes a response that clients cannot receive. Check `_has_body(route.status)` before adding response content.

```suggestion
        if _has_body(route.status) and _adapter(returns) is not None:
            media = {}
            operation["responses"][str(route.status)]["content"] = {"application/json": media}
            schemas.append((media, returns, "serialization"))
```

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

### Issue 2
packages/agentenv-protocol/src/agentenv_protocol/website/environment.py:171-173
A broad route such as `@api.get('/{rest:path}')` catches `/agentenv/anything` before `_Fallback` can reject it. Registered control routes remain protected, but unknown control paths become site pages instead of errors. Reject reserved request paths before calling site handlers, not only in the fallback.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds WebsiteEnvironment, typed API routes, signed sessions, a collection store, universe time, and an HTTP conformance checker.

• A declared website serves its pages and AgentEnv features from one app.
• Website API routes bind typed requests and return a matching OpenAPI document.
• A website follows the gateway clock and stamps its responses with that time.
• A command-line checker reports whether a server meets the website/v1 contract.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  Request[HTTP request] --> Middleware[Forwarded address and universe time]
  Middleware --> Control[Registered control routes]
  Control --> Builtins[Health, session and state routes]
  Builtins --> API[Site API routes]
  API --> Fallback[Static files, mounted app or page fallback]

Loading

_{Reviews (4) · Last reviewed commit: "Merge wloo/website-harness-gaps into wlo..." · Reviewed by Greptile}

[greptile-apps]

Bodyless responses promise JSON

openapi() advertises a JSON response body for a typed handler even when its declared status is 204 or 304. But endpoint() drops that body. A delete route returning a model with status=204 therefore publishes a response that clients cannot receive. Check _has_body(route.status) before adding response content.

Suggested change

	if _adapter(returns) is not None:
	media = {}
	operation["responses"][str(route.status)]["content"] = {"application/json": media}
	schemas.append((media, returns, "serialization"))
	if _has_body(route.status) and _adapter(returns) is not None:
	media = {}
	operation["responses"][str(route.status)]["content"] = {"application/json": media}
	schemas.append((media, returns, "serialization"))

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/agentenv-protocol/src/agentenv_protocol/website/routes.py
Line: 337-340

Comment:
**Bodyless responses promise JSON**

`openapi()` advertises a JSON response body for a typed handler even when its declared status is `204` or `304`. But `endpoint()` drops that body. A delete route returning a model with `status=204` therefore publishes a response that clients cannot receive. Check `_has_body(route.status)` before adding response content.

```suggestion
        if _has_body(route.status) and _adapter(returns) is not None:
            media = {}
            operation["responses"][str(route.status)]["content"] = {"application/json": media}
            schemas.append((media, returns, "serialization"))
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

Reserved paths serve site pages

A broad route such as @api.get('/{rest:path}') catches /agentenv/anything before _Fallback can reject it. Registered control routes remain protected, but unknown control paths become site pages instead of errors. Reject reserved request paths before calling site handlers, not only in the fallback.

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/agentenv-protocol/src/agentenv_protocol/website/environment.py
Line: 171-173

Comment:
**Reserved paths serve site pages**

A broad route such as `@api.get('/{rest:path}')` catches `/agentenv/anything` before `_Fallback` can reject it. Registered control routes remain protected, but unknown control paths become site pages instead of errors. Reject reserved request paths before calling site handlers, not only in the fallback.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.