[MarkusNeusinger]

Summary

• Dark site, dark plot. This is the owner's decision of 2026-11-01, after user test E2 showed a bright plot card on the dark site. The first render of each plot version now uses the theme the site shows. The light and dark switch still renders the other theme in one click, and each version still takes one render.
• How the theme travels. The page sends its effective site theme with every turn as POST .../messages?theme=light|dark. system mode resolves before it is sent. The BFF validates the value and forwards it. The agents service keeps it on the request ledger, and pipeline.run_theme picks the run's theme in this order:
  1. The theme the root passed, which means the user asked for it in the chat.
  2. On a change, the asked theme of the version being changed (CodeVersion.theme_asked, which the change inherits).
  3. The site theme of the turn.
  4. Without a page (adk web, the evals, a BFF deployed earlier), the previous version's theme, else light. This is the old behaviour.
• Fan-out, prompt and mock. The fan-out's sessions use the same hook, so .plot_all() plots every library in the site theme. The root prompt and the tool description say what an omitted theme means now. The dev BFF mock follows the same rule.
• --theme dark for the eval matrix (agents/evals/matrix.py, 13 lines; the lead's ask). Every turn of the run sends the site theme, as the page does. The stamp records it as theme. The model-free preflight stays light, because it only checks the renderer.

Decisions (decide-and-document)

• Query parameter, not a body field. The BFF and the agents service both reject unknown body fields (extra="forbid"), and they deploy on separate triggers. A body field would make every turn a 422 whenever the page or the BFF deploys first. An unknown query parameter is ignored. Gemini Flash went through all six deploy orders: none fails, and the theme only takes effect once all three tiers are live. There is a precedent: GET .../artifacts?theme=.
• Switching the site theme mid-session changes no version already shown. The next version follows the site theme at the time of its request, as the lead suggested.
• A theme asked for in the chat holds for later changes of that plot, in both directions: dark on a light site, and light on a dark site. This keeps the old guarantee that "a dark plot the user asked for must not silently come back light". A new plot (.start_over()) follows the site theme again.
• The theme toggle is a view, not a choice. Looking at v1 in light does not make v2 light.
• Telemetry: no field carries the theme, so none is added.
• Exported code: no change. The export's run line already names the rendered theme, and the code's own default stays light.

Open points

• Dark first renders are not measured yet. The reviewer and the host gates are not calibrated on light renders only. reviewer.md takes one labelled render in either theme, and VQ-07 names both backgrounds. R1 to R3 and the G-probes are geometric or colour-share checks, and grounding reads the drawn texts. But every eval measurement so far renders light: ladder_lab, stress, score, and every committed matrix baseline. So the agent quality numbers say nothing yet about the dark first renders that dark-site users now get. This PR adds --theme dark to the matrix and runs no dark matrix. One dark smoke or full run, with --no-baseline, should happen before the public release.
• A kept first-plot request (keep_plot_request) carries no theme. "Make it dark" typed before .confirm() is lost on a light site, as before this change.

Plan

N/A (lead brief of 2026-11-01)

Test plan

• uv run ruff check ., uv run ruff format --check ., mypy api core agents: clean
• pytest tests/unit/agents tests/unit/api -n auto: 20,683 passed. One render-cancellation test flaked once under xdist and passed alone; it is unrelated.
• New tests:
  • run_theme precedence table.
  • Service flow:
    • a dark site gets a dark first plot, reviewed in dark;
    • a light site gets a light one;
    • a change follows the site switch;
    • an asked theme holds in both directions;
    • start over follows the site again;
    • the toggle does not decide the next version;
    • a turn without a site theme behaves as before;
    • an invalid theme is a 422.
  • BFF: the theme is forwarded as a query parameter, a turn without one forwards none, and an invalid value is a 422 with no upstream call.
  • Hook and fan-out: the turn's ?theme= follows the site theme at the start of the turn.
• App: yarn lint, fm:check, type-check, test (1,353 passed) and build.
• /verify-frontend with the BFF mock (Playwright, own tab), at both viewports:
  • Desktop, 1440 px: the dark site gets a dark v1 from one plot-dark.png, with no render call. The toggle to light renders on demand. After switching the site to light, the next change gets a light v2 (?theme=light; pixel #FAF8F1).
  • Mobile, 390 px: the dark site gives a dark first plot, and the light site gives a light one.
  • Console: only the known font CORS errors on a non-3000 port.
• One live check of the local agents service: Gemini 3.8 Flash on eu, fake renderer, about 322k tokens, roughly $0.5 at list price. create_plot on ?theme=dark gave plot-dark.png. "make the markers bigger" on ?theme=light gave plot-light.png, so the real root left theme out of the change.
• Gemini 3.8 Flash pre-check: "sound with changes", $0.15.
  • Applied: the mock now reads "light" as a request too, and three test gaps are closed (asked light on a dark site, start over, the toggle).
  • Not applied: a root eval asserting that theme stays out of refinements. The live check covered one case, and an eval case is out of scope.
• Copilot (one round): approval recommended, no inline threads. All three notes in its overview are applied: the mock picks the current library's latest version, the tool text names theme='light', and the route tables name the 422.
• Matrix flag: test_theme_dark_sends_the_site_theme_and_renders_dark, and the eval suite passes (429 tests). No live dark matrix was run.

https://claude.ai/code/session_01H7HSkGyea1k2v293XiAMo8

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

🟢 Approval recommended

The reviewed changes have no active blocking findings, with remaining feedback confined to documentation nits and a development-mock behavior concern.

No open issues 🎉

What changed in this PR

This pull request makes generated plots follow the site’s effective light or dark theme while preserving explicitly requested themes across refinements. Theme information is propagated from the frontend through the BFF to the agents service, with backward-compatible fallbacks for page-less callers.

Changes:

• Sends ?theme=light|dark with agent turns and fan-out requests.
• Adds theme precedence and persistence for new plots, refinements, toggles, and .start_over().
• Updates the mock, tests, documentation, prompts, schemas, ledger, and changelog.

File	Description	Review findings
tests/​unit/​api/​test_agent_router.py	Tests BFF theme forwarding, omission, and validation.	—
tests/​unit/​agents/​runtime/​test_service_flow.py	Covers site-theme rendering, requested-theme persistence, changes, toggles, and fallbacks.	—
tests/​unit/​agents/​runtime/​test_pipeline.py	Tests theme precedence.	—
docs/​reference/​api.md	Documents the messages endpoint’s optional theme query parameter.	—
docs/​concepts/​agent-network.md	Describes site-theme propagation and pipeline behavior.	—
changelog.d/​agent-plot-follows-site-theme.md	Adds the user-facing changelog entry.	—
app/​src/​sections/​agent-chat/​FanOut.test.tsx	Verifies fan-out turns use the page theme.	—
app/​src/​pages/​AgentChatPage.test.tsx	Updates request matching to tolerate query parameters.	—
app/​src/​lib/​agent.ts	Adds optional theme query construction for chat requests.	—
app/​src/​hooks/​useAgentSession.ts	Captures and sends the effective theme for each turn.	—
app/​src/​hooks/​useAgentSession.test.ts	Tests theme propagation and site-theme changes between turns.	—
app/​scripts/​agent-bff-mock.mjs	Mirrors site-theme handling and requested-theme precedence in the development mock.	Moderate: Refinements can inherit the previous library’s theme instead of the current library’s theme; select the newest version belonging to the active library.
api/​routers/​agent.py	Validates and forwards the theme query parameter to the agents service.	—
agents/​main.py	Accepts the theme query parameter and stores it on the request ledger.	Nit: Document the 422 response for invalid theme values to match the validation behavior and BFF documentation.
agents/​anyplot/​tools/​session.py	Updates the plot_pipeline tool description for omitted themes.	Nit: Document both theme='light' and theme='dark' as supported explicit values.
agents/​anyplot/​services.py	Records whether a version’s theme was explicitly requested.	—
agents/​anyplot/​schemas.py	Updates PipelineArgs theme documentation.	—
agents/​anyplot/​prompts/​root.md	Instructs the root agent on site themes and explicit light/dark requests.	—
agents/​anyplot/​plugins/​ledger.py	Adds the current site theme to request state.	—
agents/​anyplot/​pipeline.py	Implements theme precedence, persistence, rendering, and version storage.	Nit: Update the related agents/anyplot/agent.py module documentation to distinguish theme_asked from the current turn’s site theme.

_{Review effort: Lite}