feat(website): one spec declares a site, composes it and checks any server (FD-4683) by williamloo-scale · Pull Request #445 · scaleapi/agentenv-framework

williamloo-scale · 2026-11-02T19:10:18Z

Stacked on #444.

A website spec: one TOML file declares a site, composes from parts, and checks any server against it. Design: docs/website-spec.md.

agentenv_protocol.website.spec reads [site], [source], [data], [users], [roles], [routes.ops], [clock], [[uses]] and extends, with validation, overlays, composition, card params, from_card, from_environment, a JSON Schema and a CLI (validate, show, show --card).
A name table for a multi env: synthetic over live over the allowlist, two sites of one kind on a name refused.
@website(spec="website.toml"): the class is refused when its @api routes aren't the spec's, and its card is built from the spec. Notes now declares itself this way.
env.toml takes spec = "website.toml" or an inline [spec]; the env takes its name, health path and domains from it.
conformance --spec checks a server's card and routes against the spec; those checks are required.
Examples in examples/website/specs/: a replayed Slack overlay, an intranet, and an SSO component.

Live and replay sources, served_by and models = "mcp:..." are modelled in the spec but not deployable from env.toml yet.

Test

Unit suite: 12,793 passed (one GitHub-clone test from main, which hangs on the local machine on main too, deselected).

🤖 Generated with Claude Code

Confidence Score: 5/5

No new blocking issue was confirmed in the reviewed changes.

Summary

Adds one website spec that describes a site, combines components, and checks a running server.

Website specs describe sites and combine reusable parts.
SDK site classes can take their routes and card details from a spec.
Website environments can take their site details from a spec.
Conformance checks compare a running site with its spec.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  TOML[Website spec] --> Resolve[Merge overlays and components]
  Resolve --> Validate[Check the combined spec]
  Validate --> SDK[WebsiteEnvironment and card]
  Validate --> Env[WebsiteEnv name, health and domains]
  Validate --> Check[Check a running server]
  SDK --> Check

_{Reviews (17) · Last reviewed commit: "fix(website): an overlay on a spec read ..." · Reviewed by Greptile}

…v (FD-4683) This PR's change, rebased as one commit onto #445. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…erver (FD-4683) This PR's change, rebased as one commit onto #444. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…nds fields, and fails a cookie card for a spec without one (FD-4683) - A spec derived from a WebsiteEnvironment's decorators keeps each @api route's name as @api takes it; an authored spec's route names are still checked. - An extends whose uses or data.collections has the wrong type is a SpecError naming the field, not a TypeError. - The conformance spec check fails a card with a session cookie or path when the spec doesn't sign in by cookie. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…ma takes a route's method in either case (FD-4683) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…s in lower case and keeps the route names it serves (FD-4683) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…through data/get (FD-4683) - The spec has no `[state]` section (`read = "data_plane" | "go" | "diff"`, `path`), no `STATE_PATH` and no `state_path`; `to_card_extension`, `from_card`, `from_environment` and `problems_with_environment` carry no state. - The examples, the spec doc and conformance's spec check drop it too. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

… the spec no longer takes (FD-4683) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…e route names its server serves (FD-4683) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

williamloo-scale mentioned this pull request Nov 2, 2026

feat(website): the browser client, env website new and env website dev (FD-4683) #446

Open

williamloo-scale changed the title ~~website: one spec declares a site, composes it and checks any server (FD-4683)~~ feat(website): one spec declares a site, composes it and checks any server (FD-4683) Nov 3, 2026

williamloo-scale marked this pull request as ready for review November 3, 2026 00:24

williamloo-scale requested a review from a team as a code owner November 3, 2026 00:24