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], [state], [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

The changes since the previous review appear safe to merge.

Summary

Adds a shared website spec for declaring sites, composing components, building cards, and checking running servers.

Website authors can describe and compose sites with one TOML spec.
SDK website classes now take their card and seed settings from a checked spec.
Website bundles can take their name, health path, and domains from a spec.
The conformance checker can compare a running server with a website spec.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  TOML[Website TOML] --> Spec[Resolved website spec]
  Decorators[Existing decorators] --> Spec
  Card[Server card] --> Spec
  Spec --> SDK[SDK declaration and card]
  Spec --> Env[Website env settings]
  Spec --> Check[Server conformance checks]

_{Reviews (13) · Last reviewed commit: "fix(website): a spec derived from a site..." · 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>

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