* feat(model): optional per-stage LLM model routing (#745)
Add a config-only stage -> model map consulted during model resolution,
falling back to DEFAULT_MODEL when unset (zero behavior change unless opted in).
- lib/server/model-routes.ts: parse/validate/cache MODEL_ROUTES env JSON;
LLM_STAGES registry of routable stages; getStageModel(stage).
- resolveModel: resolution order x-model > stage route > DEFAULT_MODEL > builtin;
thread optional `stage` through resolveModelFromHeaders/FromRequest.
- Wire each route's resolveModel call site to its stage; classroom-generation
resolves generate-classroom and web-search-query-rewrite independently.
- .env.example: document MODEL_ROUTES; unit tests for both modules.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(model): address cross-review findings for per-stage routing (#745)
- classroom-generation: resolve the web-search-query-rewrite model lazily,
only when explicitly routed and inside the web-search branch, with try/catch
fallback to the classroom model. Fixes a regression where a misconfigured
optional route (keyless/invalid provider) threw and aborted ALL classroom
generation even with web search disabled; also avoids wasted resolution on the
common no-search path and preserves classroom-model inheritance when unrouted.
- resolve-model: type the stage param as LlmStage across resolveModel/
resolveModelFromHeaders/resolveModelFromRequest so a mistyped stage literal is
a compile error instead of silently falling through to DEFAULT_MODEL.
- model-routes: simplify the cache to a process singleton (matching
provider-config), dropping the raw-string-keyed cache and redundant STAGE_SET.
- .env.example: clarify x-model precedence and that a route to an unconfigured
provider fails at request time (no startup validation), like a bad DEFAULT_MODEL.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(model): stage route takes precedence over client x-model (#745)
Cross-review (codex P2 + Claude tracer) found that the browser UI always sends
its saved model as x-model, so the previous x-model > stage order made
MODEL_ROUTES inert for normal UI traffic on exactly the heavy stages the RFC
targets (scene-content, quiz, pbl-chat, chat). Flip resolution to
stage route > x-model > DEFAULT_MODEL: a configured route is the operator's
deliberate per-stage choice and wins, while unrouted stages still honor the
client's x-model. Update docs and tests accordingly.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* style(model): prettier-format changed files for #745 CI
Run the repo formatter (pnpm check / prettier) on the changed routes, the new
model-routes module, and the new tests so `prettier . --check` (CI) passes;
also correct a stale precedence comment in the resolve-model test.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(model): isolate routed model from client connection params (#745)
When a stage route overrides the client's x-model and points at a different
provider, the client-sent apiKey/baseUrl/providerType (for the client's model)
must not bleed onto the routed provider — otherwise a routed Anthropic model
would be constructed with the client's OpenAI providerType/key and fail. A
routed model now resolves its connection params purely from server config, as
if no x-model was sent. Unrouted stages still honor the client params. Adds
tests covering both the drop (routed) and keep (unrouted) cases.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(model): correct graceful-degradation comment in classroom (#745)
resolveModel does not throw on a missing key; clarify that a keyless route
surfaces later in callLLM (degraded by the outer try/catch), while only a
resolution-time failure is caught at the rewrite re-resolve. Comment-only.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(model): route scene-content per scene type (#745)
Extend MODEL_ROUTES with composite keys scene-content:<type> for the four core
scene types (slide/quiz/interactive/pbl). getStageModel now resolves composite
`a:b` stages most-specific-first, trimming `:` segments, so scene-content:<type>
falls back to the base scene-content route, then x-model, then DEFAULT_MODEL.
The scene-content route derives its stage from outline.type. Backward
compatible: with no composite key configured, behavior is unchanged.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(model): per-stage thinking effort + drop hardcoded gpt fallback (#745)
MODEL_ROUTES values may now be {model, effort} (not just a model string) to pin
the thinking effort per stage. Arbitration mirrors model routing: a routed stage
with effort set wins over the client's thinking (effort "none" disables); routed
with no effort uses the model's default and drops client thinking; unrouted
stages keep the client thinking. resolveModel is the single arbiter — body
thinking is threaded in via resolveModelFromRequest. classroom-generation passes
the resolved thinking into its callLLM calls so generate-classroom and
web-search-query-rewrite honor route effort too.
Also: removed the hardcoded `|| 'gpt-5.4-mini'` fallback in resolveModel — if no
model resolves (no route / x-model / DEFAULT_MODEL) it now throws instead of
silently picking a vendor default.
model-routes: getStageRoute returns {model, effort?}; getStageModel delegates to
it. Docs + tests updated.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* refactor(model): route value carries full ThinkingConfig (#745)
Per-stage routing accepts the full unified ThinkingConfig in the route value
({model, thinking:{mode,effort,level,enabled,budgetTokens,excludeReasoningOutput}})
instead of just an effort string. The route's thinking is passed through
resolveModel and normalized per the model's capability by callLLM, so
budgetTokens (qwen), level (Gemini), enabled/mode, etc. all work.
(qwen3.7-plus/max thinking capability now comes from upstream #753, so this no
longer registers them.)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(model): honor routed thinking for chat-adapter; doc fixes (#745)
Cross-review (codex P2 + Claude) found chat-adapter was the only routable stage
that ignored the route's thinking: it took the routed model but built its own
thinkingConfig from the request body, so operator-pinned thinking never applied
and client thinking still leaked onto a routed model. Now pass the client
thinking into resolveModel and use the resolved thinkingConfig (route-pinned for
a routed stage, client otherwise; defaults to disabled for low-latency chat).
Also: clarify DEFAULT_MODEL is now required for server-side stages (the
hardcoded gpt-5.4-mini fallback was removed → resolveModel throws if nothing
resolves), and fix a stale {model,effort}→{model,thinking} doc comment.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(prompts): declare whiteboard role prompt IDs + whiteboard-reference snippet
* feat(prompts): add whiteboard role template skeletons + reference snippet stub
* refactor(orchestration): move buildWhiteboardGuidelines to role-specific markdown templates
* docs(prompts): whiteboard guidelines now in markdown templates
* feat(prompts): whiteboard-reference canvas + JSON output sections
* feat(prompts): whiteboard-reference action schemas for text/shape/line
* feat(prompts): whiteboard-reference action schemas for latex/chart/table
* feat(prompts): whiteboard-reference action schemas for code/delete/clear/close
* feat(prompts): whiteboard-reference LaTeX JSON escape section
* feat(prompts): whiteboard-reference bounds + overlap section
* feat(prompts): whiteboard-reference font + latex height tables
* feat(prompts): whiteboard-reference pre-output checklist
* feat(prompts): expand teacher whiteboard template
* feat(prompts): expand assistant whiteboard template
* feat(prompts): expand student whiteboard template
* test(prompts): assert whiteboard-reference sections reach every role prompt
* tune(prompts): cap teacher element budget at 4/turn, encourage wb_clear on crowded board
* tune(prompts): simplify teacher template — single conservative rule + state-awareness emphasis
* tune(prompts): add LaTeX-height × text-fontSize pairing table for visual weight consistency
* feat(orchestration): preserve image parts from UIMessage to AI SDK ModelMessage
* feat(eval): attach prior-turn whiteboard screenshot as user message image part
Gated behind EVAL_ATTACH_PRIOR_SCREENSHOT=1 env. When on, captures a
screenshot after every turn (not just checkpoints) and attaches it as a
file part with mediaType:'image/png' on the next user message. Teacher
prompt gets a new 'Prior-state image' section telling the agent to
treat it as direct visual feedback.
* fix(orchestration): strip data: prefix before passing image to AI SDK
Vercel AI SDK's streamText/generateText treats ImagePart.image as a URL
to fetch when it's a string. data: URLs fail the http/https scheme check
and throw AI_DownloadError. Strip the data URL prefix and pass raw base64
with mediaType separately — AI SDK treats base64 strings as data content.
* refactor(whiteboard): add conflict summarizer, drop prior-screenshot feature
Eval across flash (image-on vs off × repeat-3) and pro (same) showed the
prior-screenshot image-input feature gives ~0 net benefit: +0.4 overall on
flash and −0.6 on pro. The image feedback loop's theoretical upside
(agent self-correcting from visual) didn't materialize — weak models
couldn't act on the image and strong models "found things to fix" and
over-corrected. Meanwhile programmatic geometry detection on the raw JSON
cleanly lifted overlap from 6.3 → 8.1 on flash.
So: remove the image-input plumbing, keep a programmatic equivalent.
## Removed (reverts 0e07e9e, b5675bc, image half of 097ec2f)
- lib/orchestration/ai-sdk-adapter.ts: revert multimodal content passthrough
- lib/orchestration/summarizers/message-converter.ts: revert image part
extraction; user content is back to string-only
- lib/orchestration/summarizers/conversation-summary.ts: revert multimodal
content flattening
- lib/orchestration/director-graph.ts: revert HumanMessage multimodal cast
- tests/orchestration/message-converter.test.ts: deleted (was purely
image-conversion tests)
- eval/whiteboard-layout/runner.ts: drop image attach, vision gate,
per-turn screenshot capture; revert to checkpoint-only capture
- Role templates (wb-teacher / wb-assistant / wb-student): strip
"Prior-state image" sections
## Added
- lib/orchestration/summarizers/whiteboard-conflicts.ts: pure geometry
detector. Computes bbox IoU, line segment vs bbox intersection, and
canvas edge clipping on the current whiteboard state. Renders a text
block for inclusion in the system prompt.
- lib/orchestration/summarizers/state-context.ts: wires the conflict
block in after the whiteboard element listing.
- Role templates: replace image-reading guidance with concise
"Layout conflicts" sections pointing at the computed list, with a
strong anti-action anchor so agents don't self-trigger wb_clear when
the list is empty.
## Eval instrumentation (orthogonal)
- EVAL_ENABLE_THINKING=1 opt-in to enable model thinking per-request.
app/api/chat/route.ts reads body.thinking; runner.ts forwards it.
Default chat path stays on enabled:false for latency.
- Per-turn wall-clock timing: eval/whiteboard-layout/{runner,reporter,
types}.ts capture and report mean/p50/p95/total turn latency.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* refactor(whiteboard): address code-review feedback
W1: drop stale "prior-state image" reference from conflict-block prose
(lib/orchestration/summarizers/whiteboard-conflicts.ts) — the image
feature was removed; the text now says "real visible problem on the
current board".
W3: type `thinking` on StatelessChatRequest instead of reading it through
a cast. `app/api/chat/route.ts` now accesses `body.thinking` directly;
frontend callers can discover the field via TS completion.
W4: unify canvas height constant to 563 (matching the actual rendered
pixel count from capture.ts). The geometry detector's
CANVAS_HEIGHT, the snippet's Dimensions / coordinate system /
layout-guide text, and examples all now agree.
N6: add tests/orchestration/whiteboard-conflicts.test.ts — 17 cases
covering empty input, bbox overlap threshold (30%, 50%, 100%, plus
10% sub-threshold), line-crosses-bbox (through, endpoint-inside,
path-above), canvas clipping on all 4 edges, exact-edge placement
(not reported), malformed elements (skipped not crashed), and
output format.
All 43 tests pass; tsc --noEmit clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* refactor(eval): finish canvas-height 563 unification
Second-pass code review caught one residual 562.5 in app/eval/whiteboard/page.tsx
that the first cleanup (commit 7a006bb) missed. The 0.5px disagreement was
harmless in practice (Playwright captures rounded to 563), but inconsistent
with the geometry detector and the prompt snippet now agreeing on 563.
All 43 tests pass; tsc clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore: prettier format whiteboard-conflicts.test + eval/runner
CI's `pnpm check` (prettier --check) caught two unformatted files:
- eval/whiteboard-layout/runner.ts
- tests/orchestration/whiteboard-conflicts.test.ts
Auto-fixed via `pnpm prettier --write`.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
- Make validateUrlForSSRF async; resolve hostnames via dns.promises.lookup
with { all: true, verbatim: true } and reject if any address is private
- Add isPrivateIP helper covering IPv4 private ranges, IPv6 loopback/ULA/
link-local, IPv4-mapped IPv6, deprecated fec0::/10 site-local, 6to4
tunnel (2002::/16), and Teredo tunnel (2001:0000::/32)
- Detect IP literals via net.isIP() and validate directly without DNS
- Fail closed on DNS resolution errors
- Propagate async to resolveModel, resolveModelFromHeaders, and all 20+
route-level callers; preserve existing production-only gating
- Add 14 unit tests covering public pass-through, private literals, DNS
rebinding, mixed DNS answers, tunnel addresses, and DNS failure
Closes#378
* feat: Ollama local LLM support
- Ollama as a built-in provider (OpenAI-compatible, no API key needed)
- 8 default models: llama3.3, llama3.2, qwen2.5, qwen2.5:32b, mistral, gemma3, deepseek-r1, phi4
- Keyless provider activation: providers with only a baseUrl (no API key) now activate correctly
- isProviderKeyRequired() helper for consistent key validation across routes
- i18n strings for Ollama (zh-CN + en-US) and missing Doubao strings
- SSRF guard documentation clarifying server-configured URLs bypass safely
Previously, clients could send `x-requires-api-key: false` (header) or
`requiresApiKey: false` (body) to skip API key validation for ANY provider,
including ones like OpenAI that require keys. This meant a client could
consume server-configured credentials without authorization.
Fix: the server now derives requiresApiKey exclusively from its own provider
registry. The client header and body field are removed from all server-side
parsing. For Ollama, the registry says `requiresApiKey: false` so it works
keyless. For OpenAI, the registry says `true` so the check is enforced
regardless of what a client sends.
* fix: address reviewer feedback on Ollama integration
- Fix env-var activation so OLLAMA_BASE_URL alone activates the provider
- Move SSRF bypass comment from ssrf-guard.ts to resolve-model.ts
- Add ollama and doubao provider names to i18n locale files
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Fixed issues from reviewer notes.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* style: format provider-config.ts with Prettier
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
* fix: add structured request context to all API error logs (#323)
Replace generic log.error messages across 23 API routes with structured, context-rich error logs that include provider, model, input summary, and other request parameters for faster incident triage.
- Hoist key request params above try blocks for catch-block access
- Add createLogger imports to routes that lacked logging
- Truncate user-controlled strings (query, requirement) to prevent log flooding
- No behavioral changes — purely observability improvement
Closes#323
* style: run prettier on all API routes
* chore: remove accidental server.log from tracking
* fix: use resolved API key in chat route instead of client-sent key (#220)
PR #114 refactored the chat route to use resolveModel() but replaced the
server-resolved API key with the raw client-sent body.apiKey for both the
401 check and the statelessGenerate call. This broke server-configured
providers (e.g. OPENAI_API_KEY env var) where the client sends no key.
- Add apiKey field to ResolvedModel interface so callers can access the
effective key after server-side fallback resolution
- Use the resolved apiKey for the 401 guard and pass it to statelessGenerate
Fixes#220
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: allow keyless providers (e.g. local Ollama) to bypass API key check
Add requiresApiKey !== false guard so providers that don't need an API
key are not rejected by the 401 check.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>