feat: add vitest-evals agent evals for Flue docs bot

[mvvmm]

Summary

Adds vitest-evals agent evals for the Flue docs bot, testing 5 reviewable agents (style-guide, conventions, spam-filter, reconcile, code-review) against the live Workers AI model.

Architecture:

• Eval routes mounted at /eval/agents/:name in app.ts, gated by DOCS_FLUE_ENABLE_EVAL_ROUTES=1 and DOCS_FLUE_INTERNAL_TOKEN. The Vite config injects these vars only when DOCS_FLUE_AGENT_EVALS=1 is set (by run-evals.ts), so eval routes are never live in production or normal dev.
• Custom createHarness adapter (evals/harness.ts) that POSTs { kind: "user", body, initialData } to the agent HTTP endpoint, polls ?view=history until the submission settles, then extracts useDataWriter structured output + tool-call transcript.
• 10 eval cases across 5 agents with synthetic initialData fixtures, asserting on structured output and submit_* tool calls.

Running locally:

pnpm run flue:evals

Starts the dev server, waits for /health, runs evals, tears down the server.

CI:
New evals job in flue-ci.yml — starts the dev server, runs evals, uploads vitest-results.json as an artifact. Skipped for fork PRs (needs DOCS_FLUE_INTERNAL_TOKEN and Workers AI access).

Docs:
Updated .flue/AGENTS.md with an "Agent Evals" section documenting the architecture, usage, CI integration, how to add new eval cases, and current coverage table.

Documentation checklist

• Is there a changelog entry (guidelines)? If you don't add one for something awesome and new (however small) — how will our customers find out? Changelogs are automatically posted to RSS feeds, the Discord, and X.

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
*	@cloudflare/product-owners
*.ts	@cloudflare/content-engineering, @kodster28
package.json	@cloudflare/content-engineering
/.github/	@cloudflare/content-engineering, @kodster28, @mvvmm, @colbywhite, @ahaywood, @MohamedH1998

[github-actions]

Preview URL: https://b69b9a2d.preview.developers.cloudflare.com
Preview Branch URL: https://flue-vitest-evals.preview.developers.cloudflare.com

[cloudflare-docs-bot]

Review

💡 1 suggestion found in commit b69b9a2.

👉 Fix in your agent 👈

Fix the following review findings in PR #32371 (https://github.com/cloudflare/cloudflare-docs/pull/32371).

Before making changes, review each finding and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g. the fix requires disproportionate effort for minimal benefit,
  or the finding is factually incorrect), explain why
- If you need clarification before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

After triaging, follow this order:
1. Post a comment on this PR for any findings you are skipping, with the finding ID and your reasoning.
2. Then commit the fixes for the legitimate findings.

The comment must come before the commit — the bot reads PR comments when a new
push triggers a review, so skip comments posted after the push will be missed.

---

## Code Review

### Suggestions (1)

#### CR-ad06158bb788 · Duplicated terminal predicate
- **File:** `.flue/evals/harness.ts` line 155
- **Issue:** The `findLast` predicate that checks `s.outcome === "completed" || "failed" || "aborted"` appears identically inside the polling loop (line 155) and again after the loop (line 175).
- **Fix:** Extract a helper such as `isTerminalSettlement(s)` and, where possible, reuse the terminal value discovered inside the loop instead of searching the settlements array a second time.

Code Review

This code review is in beta and may not always be helpful — use your judgment.

Suggestions (1)

File	Issue
.flue/evals/harness.ts line 155	Duplicated terminal predicate — The findLast predicate that checks s.outcome === "completed" || "failed" || "aborted" appears identically inside the polling loop (line 155) and again after the loop (line 175). Fix: Extract a helper such as isTerminalSettlement(s) and, where possible, reuse the terminal value discovered inside the loop instead of searching the settlements array a second time.

Conventions

_{No convention issues found.}

Style Guide Review

_{No style-guide issues found.}

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command	Description
/review	Runs a review now. Incremental if a prior review exists, full if not.
/full-review	Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
/ignore-review-limit	Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.
/disable-auto-review	Stops automatic reviews from triggering on future pushes to this PR. Codeowners can still run /review or /full-review manually.
/rebase	Rebases the PR branch against production. On conflict, attempts to resolve automatically using AI. Stops with an explanation if confidence is not high enough.

[mvvmm]

Skipping CR-ab634caeb00b — Internal token stored as plaintext var

The DOCS_FLUE_INTERNAL_TOKEN is only injected into Worker vars when DOCS_FLUE_AGENT_EVALS=1 is set, which is exclusively set by run-evals.ts in CI. The generated .flue-vite.wrangler.jsonc is gitignored and the Worker is never deployed with this config — it only exists on the ephemeral CI runner. Using .dev.vars was the alternative (tried and reverted), but the vars approach is cleaner and the risk is minimal given the dev-only gating.

[mvvmm]

Already-fixed findings re-reported from stale snapshot

The following findings were addressed in commit bab33d6319 (pushed before this review ran). The bot appears to have reviewed a snapshot from before that commit.

• CR-05e7a2d07fd4 — Signal handlers now call process.exit(130/143) (.flue/bin/run-evals.ts:88-93)
• CR-23f106b05580 — Exit handler resolves 128 on signal, code ?? 1 otherwise (.flue/bin/run-evals.ts:103-106)
• CR-97bd650c24de — server.on("error", ...) added (.flue/bin/run-evals.ts:96-99)
• CR-87ca8a89dd92 — PR template provided, assertions filtered to title/description findings (.flue/evals/conventions.eval.ts:51-68)
• CR-b636760451a7 — upload-artifact pinned to SHA ea165f8d65b6e75b540449e92b4886f43607fa02 (.github/workflows/flue-ci.yml:120)
• CR-403793fb5932 — await removed from spawn() (.flue/bin/run-evals.ts:101)
• CR-4d234e71f0a4 — .flue/vitest-results.json added to .gitignore