Instructions
CLAUDE.md
CLAUDE.md#
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
What this project is#
A Cloudflare Workers service giving AI agents live access to model schemas:
per-endpoint request/response JSON Schemas and model metadata for 8 monitored
providers (OpenAI, Anthropic, Gemini, xAI Grok, ElevenLabs, OpenRouter, FAL,
BytePlus),
with a D1 read session on public GETs (replicas after #554's US
primary has read_replication.mode: auto; the session still hits the
primary until then), Workers Cache on the CachedReads entrypoint
(max-age matched to the 15-minute poll; versioned schemas cached for a
year; purged after an admin write), and cron-driven auto-refresh.
KV remains for rate-limit counters and docs caches. Design ported from
TanStack AI PR #622 (@tanstack/ai-schemas), minus codegen — schemas are
extracted/bundled at runtime and served over HTTP/MCP.
The service is live at https://modelschemas.openstory.workers.dev. 0.1.0
is on npm (@modelschemas/* plus unscoped modelschemas). Further
versions: OIDC npm stage publish via .github/workflows/publish.yml —
README "Releasing on npm".
PLAN.md is a historical build log, not the backlog. Open it for a
gotcha or decision from phases 0–18. New work is GitHub issues. This file
is the live map.
Commands#
pnpm is the package manager (packages/*, examples/*). Scripts run on Node 24 or newer (engines.node).
pnpm install # install + link workspace packages
pnpm run dev # local D1 migrate, then dev server on http://localhost:3100
pnpm run test # vitest, unit + workers projects
pnpm run test src/path/to/file.test.ts # single test file
pnpm run lint # oxlint --type-aware (no-explicit-any + no-unsafe-* are errors)
pnpm run typecheck # tsc --noEmit (includes packages/*)
pnpm run format # oxfmt + oxlint --fix
pnpm run check # oxfmt --check
pnpm run build # production build (emits dist/server/wrangler.json)
pnpm run deploy # build + wrangler deploy
pnpm run npm:pack # pack public packages to dist/npm (no publish)
Database (drizzle-kit generates; wrangler applies):
pnpm run db:generate # generate migrations from src/db/schema.ts
pnpm run db:migrate # apply to wrangler's LOCAL D1
pnpm run db:migrate:remote # apply to remote D1
pnpm run seed # seed the 8 providers (--remote for prod)
Generated artifacts (committed; CI fails on drift):
pnpm run openapi:emit # src/server/openapi.ts → openapi.json
pnpm run generate:client # → packages/client/src/generated (hey-api)
pnpm run check:client # regenerate + git diff --exit-code (CI step)
pnpm run emit-skill # src/server/skill.ts → skill/modelschemas/SKILL.md
A PR that touches packages/* (including the generated client) needs a
changeset (pnpm exec changeset), or pnpm exec changeset --empty when nothing
ships; CI runs changeset status --since=origin/main on PRs and fails
without one. openapi.json and SKILL.md are oxfmt-ignored (byte-stable
emitted artifacts). Lefthook pre-commit runs oxfmt/oxlint/typecheck — never
--no-verify. The cloudflare vite plugin is skipped under vitest;
Workers-binding tests (*.worker.test.ts) run in workerd via
@cloudflare/vitest-plugin (config: vitest.workers.config.ts,
migrations auto-applied via TEST_MIGRATIONS).
Local verification flows: pnpm run agent-roundtrip (agent-auth
register→execute), pnpm run client-smoke (typed client),
pnpm run cli -- <cmd> (CLI), pnpm run rederive -- <provider>
(re-derive schema content hashes from the upstream spec — no service/db;
shares classifyAndBundle with the sync engine), pnpm run gap:report -- --table
(per-provider score for the chat facts @tanstack/ai-models needs; one
/v1/models request; docs/source-silent/<provider>.md lists facts a provider does not
publish; --check exits 1 below --target). Admin sync:
curl -X POST localhost:3100/v1/admin/sync/openrouter -H "X-Admin-Key: $ADMIN_KEY".
Architecture#
TanStack Start (React 19, SSR) on Cloudflare Workers via the Cloudflare vite
plugin + wrangler.jsonc. Tailwind v4. Worker entry is src/worker.ts:
rate-limits /v1/*, delegates fetch to the Start handler, and runs the
crons (15-min models poll + webhook drain; daily spec sync sharded across
four 05:00–05:30 UTC firings — FAL alone in shard 0, the rest round-robin —
so each shard gets its own invocation budgets; see SPEC_SYNC_SHARD_CRONS;
FAL llms.txt rate-card extract hourly 06:00–11:00 UTC —
FAL_PRICING_EXTRACT_CRONS).
Request path: route files in src/routes/ (server handlers via
server.handlers) → service functions in src/server/ → drizzle/D1 +
KV. Bindings come from import { env, waitUntil } from 'cloudflare:workers' —
typed by the committed, wrangler-generated worker-configuration.d.ts
(pnpm run types regenerates it; rerun after changing wrangler.jsonc or
.env.local since secret names are typed into Env). Workers runtime types are
GLOBAL (KVNamespace, D1Database, …) — do not import from
@cloudflare/workers-types (removed; its types conflict with the generated
ones).
- BytePlus publishes no OpenAPI document (
/openapi.jsonis a catch-all 200-empty; the real ones sit behind the console's API Explorer login), so its Ark spec is GENERATED at sync time from BytePlus's official Go SDK:fetchSpecpullsservice/arkruntime/model/*.gofrom GitHub,go-struct-parser.tsturns thejson:"…"-tagged structs into schemas, andbyteplus-ark-build.tsmaps them onto paths and re-applies curated descriptions plus the few request fields the SDK omits.byteplus-spec.tsholds the hand-ported fallback used when that fetch/parse fails, and the Seed Speech document, which no SDK covers. The model catalog is live whenARK_API_KEYis set (ArkGET /models), with the embedded catalog filling the gaps that listing omits — Seed Speech and unlisted-but-served ids. - Gemini video (#658) is the Interactions API (
POST /v1beta/interactions), which the Discovery document lacks.gemini-video.tsbuilds one endpoint per video model at sync time: Google's Interactions OpenAPI request withmodelpinned andresponse_format.durationan enum from the model page'sOutput video 3s-15slimit. A page that states resolution, fps and a token rate instead (#697, Genie 4) is still video on the poll, and the spec sync names it as a real-time stream with no fixed-duration schema. A page that fails to fetch or parse rejects the video fetch, so the sync keeps the stored video endpoints. The endpoint id is the model id and the path is shared, soGET /v1/openapi/geminimerges them into one operation whose body is ananyOfof components taggedx-modelschemas-model(mergeModelBodies). The Models API lists these models like chat models: the poll calls a rowvideoonly when its docs page states that limit, and keeps the stored activity when the page is unread. Veo is shut down on this API (2026-10-22). - Ingest (
src/server/providers/+src/server/ingest/): per-providerProviderConfig(fetchSpec/listModels/classify) →bundle.tsextracts request/response schemas and inlines$refclosures under$defs→sync.tscontent-hash-diffs intoschema_versions+changes;poll-models.tsdiffs model lists. Keyed providers skip cleanly when the secret is absent.models.pricingis a RateCard or null: listings compile at write (src/server/rate-card.ts), and OpenAI/Anthropic/Gemini prices are parsed from their pricing pages (*-pricing.ts,openai-model-docs.ts) — every parser fail-closed, a page that parses nothing throws rather than nulling stored cards. A card is USD unless its price is wrapped as{ currency: ['CNY', expr] }(moonshotai-cn,minimax-cn): the wrapper is the one place a currency is stated, and it is not a core op so pre-currency evaluators refuse the card. Summaries and estimates name the currency; nothing converts or compares across currencies. A listing that omits a price keeps the stored card and logspricing_lost; any other omitted fact is written null once the usual fills are tried (the bound schema for capabilities and modalities, the provider table for the request map). An adapter that knows why says so inModelInfo.absent(FactAbsenceintypes.tshas the exact table):clearedwrites null quietly (Hugging Face hosts that stopped agreeing on a price),unavailablekeeps the stored value.clearedis only for a value the source visibly lacks: an unreadable shape throws, and the poller refuses a poll that would clear 5 or more stored prices and over half of the priced rows the provider lists (refusesPriceClears). A refused mass clear repeats every poll until the adapter or the bound changes, or the stale cards are nulled by hand in D1. Wrap a docs load intryDocs(model-facts.ts) so its throw marks rowsunavailable(...)and is reported asdocsFailuresinstead of failing the provider's poll; the listing itself is never wrapped. While a provider's docs keep failing,cache_metaholds onedocs-failing:<providerId>row saying since when (docs-failing.ts); a refused mass clear holds aprice-clears-refused:<providerId>row the same way.GET /v1/statusserves both per provider (docsFailing,priceClearsRefused), the home page marks the row, and neither changesstatus./v1/statusmodel counts are live rows only (counts.deprecatedholds the rest), andcompletenessthere is the gap-report score:src/lib/completeness.tsis the one scorer, shared withscripts/gap-report.ts; the Worker bundlesdocs/source-silent/*.md(source-silent.ts). The 15-minute cron scores once after the poll (recordCompleteness, onecache_metarow); requests only read it. BytePlus chat, Seedance, and Seedream cards come from its public ModelArk pricing doc (byteplus-pricing.ts; the console pricing view andarkcli pricingare login-gated). An id that page names nowhere iscleared(the "Retiring models" tables left it on 2026-11-12, #646); one it names but no table prices keeps its card. Seed Speech cards come from the voice billing pages (byteplus-speech-pricing.ts): Seed Audio bills the response'soriginal_durationand estimates it at the published 120 second maximum;seed-asris the "Audio File ASR Fast Mode" rate. FAL cards come fromextract-fal-pricing.ts:fal-unit-rate.tscompiles the common$X per <unit>sections with no model call, leftovers go to one extract model per distinct Pricing-section hash and are copied onto every row sharing it. A priced leftover must become a card (one repair turn, same model); a failed one rewinds the cursor so the next shard retries it once. The prompt states today's date: a promo that has ended is priced at the regular rate the section states (none stated:unverified, with the promo end, which the check verifies is past), and a card that arrives already expired is rejected into the repair turn (#552). The model call is TanStack AIchat()(@tanstack/ai-anthropicover@tanstack/ai-cloudflare'scloudflareBindingFetch) on theAIbinding through AI Gateway (gatewayChat, Unified Billing, gateway idAI_GATEWAY_ID, catalog idanthropic/claude-sonnet-5.5on the wire —GATEWAY_MODEL_IDS);scripts/compare-fal-extract-models.tsscores candidates through the same code with a stand-in binding, andpnpm run fal-extract-smoke --runs one extract through the REAL binding and gateway (Wrangler remote bindings need Node; oven-sh/bun#39247).models.reasoning({ mode, mandatory, efforts? }; mode is adaptive/budget/effort/toggle).mandatoryhas one meaning:truethe source STATES thinking cannot be turned off,falseit states it can (prose, or an off value in the model's OWN schema or level list),nullunstated — a shared schema or a list with nononestates nothing. Atoggleis never stored withnull. Full rules onModelReasoninginproviders/types.ts;reasoningViolationgates every poll write (keepValidReasoning: a bad object keeps the prior value and emitsingest_failed). Older adapters still infertrue(docs/api-changes.md lists them).models.reasoningandmodels.serverTools(provider tool type ids) come from docs: OpenAI and xAI model pages, Gemini model pages + thinking tables, the Anthropic Models API + thinking table; Anthropic tools and sampling support (temperature/top_p/top_k,falsewhere the migration guides say 400) are hand-written tables inanthropic-features.ts(re-verify on each Claude launch). - Stated facts (
settleStatedFactsinpoll-models.ts; contract in theFactAbsencecomment inproviders/types.ts):models.capabilitiesis a yes/no flag map (src/lib/capabilities.ts), a boolean map or null on every row. Adapters still emit the list of supported flags, plusunsupportedCapabilitiesfor a stated no;settleCapabilitiesis the one place they become the map, and it addsfalseforexactCapabilitiesrows from the flags that provider's exact rows list in the same poll. A provider's native listing object goes inproviderMetadata, never incapabilities(the gate refuses a non-flag value).models.releasedAtis the provider's own date (firstSeenAtstill folds it in), kept when a listing stops stating it.knowledgeCutoff(YYYY-MM[-DD]) andopenWeights+weightsUrlare null unless the provider states them. A stored row's firstreleasedAtorproviderMetadatais written with nomodel.updated. Migration0014is a drizzle custom migration that converted the stored lists. A fact the provider's docs do not state can still come from a live API check: one file per provider undersrc/server/providers/probes/, derivationprobe-verified, datedverifiedAt. The adapter binds that fact only for the exact model and route the record names. A record older than 90 days stays served;GET /v1/statuscounts it onstaleProbes. Re-run withpnpm run probe -- <provider> [--write](not CI, not the 15-minute poll). The script reads the provider key from the environment or Doppler and never prints it. - sameAs links (issue #199,
src/server/ingest/model-identity.ts): a reseller row links to the upstream row its own provider names — never inferred from a similar name alone, and never a copied fact. Adapters state the upstream withProviderConfig.upstreamModelIdentity(OpenRouter, Vercel, Azure, Perplexity'santhropic/-style ids — not OpenCode, whose AI SDK package column names the wire protocol, not the maker); polls store it as evidence (models.upstream_provider/upstream_raw_id/upstream_source), writing only what changed. Names gateways use for a provider (google→ gemini) are rows inprovider_model_namespaces, mirrored fromProviderConfig.modelNamespaceson each poll byensureProviderRow.reconcileSameAsruns once per poll run, across all providers, and resolves evidence tosame_as_model_id: exact id, then alias, then dots-as-hyphens; ambiguous or missing → null. Each link change emitsmodel.updated. The catalog serves the link, with the evidence asfactSources.sameAs, only while the row's current evidence still names that target. Cloudflare AI Gateway is held until it has its own listing. Migration0012is hand-written (in-placeALTER TABLE, no rebuild). - API (
src/routes/v1/): catalog and schema reads (getDb(env, { replica: true }), ETag/304 andpublic, max-ageviahttp-cache.ts),POST /v1/validate(@cfworker/json-schema),POST /v1/estimate(@modelschemas/rate-card), cursor-paginated/v1/changes, subscriptions. Errors are always{ error: { code, message } }with remediation hints. - Spec components from zod: the RateCard family (
packages/rate-card) andCompactPricing,PricingRange,ModelReasoning,ChatRequestMap(src/server/api-schemas.ts) are zod schemas with a.metaid; the TS types are inferred from them andopenapi.tswrites every id'd schema intocomponents.schemas. Change the zod schema, not a hand-written component (the rest ofopenapi.tsis still hand-written). A spec change to a served row needs theMODEL_ROW_SHAPEbump. - MCP (
src/server/mcp.ts, route/mcp): stateless streamable-HTTP JSON-RPC wrapping the same service functions. - Auth (
src/lib/auth.tsfactory → lazy runtime instance insrc/server/auth.ts; betterAuth CANNOT construct at module scope in workerd): better-auth + agent-auth (capabilities derived fromsrc/server/openapi.ts, admin ops excluded), api-key fallback, bearer.requireAgent(src/server/require-agent.ts) guards native routes; agent JWT jtis are single-use — mint per request. The plugin keeps seen jtis in an in-process cache (nosecondaryStorage), not in D1. Rate limiting (src/server/rate-limit.ts): KV fixed-window, 60/h anon-IP, 5k/h per verified credential. Workers Cache (theCachedReadsentrypoint insrc/worker.ts) serves catalog and schema GET hits without running the worker, so those hits are not counted, with or withoutAuthorization(the responses arepublic, which is Cloudflare's rule for caching an authenticated request). Only misses are counted. - Webhooks (
src/server/webhooks.ts): checkpointed fan-out ofchangesto subscriptions, HMAC-SHA256-signed delivery, exponential backoff, auto-pause after 8 failures; drained by the 15-min cron. Destination URLs are SSRF-guarded (public https only, no redirects). - DB (
src/db/schema.ts): better-auth tables + providers/provider_model_namespaces/models/ endpoints/schema_versions/changes + cache_meta/subscriptions/ webhook_deliveries. Epoch-second integers for our tables; ids are slugs (provider/pathfor endpoints,provider-rawid-slugfor models). - Workspace packages:
packages/client(@modelschemas/client, generated + hand-written auth entry),packages/codegen,packages/vite,packages/cli(modelschemasbin: login/whoami/models/schema/validate/estimate/changes/subscribe),packages/rate-card(@modelschemas/rate-card: pricing schema + evaluator + OpenRouter listing compiler; no Workers deps). Its./evaluatorentry (evaluateCard) imports no package. Every public package's npm tarball ispnpm run buildoutput (dist/JS + .d.ts);npm-packliftspublishConfigonto the packed manifest. The CLIbinisdist/index.js. MAJOR.MINOR equalsRATE_CARD_LANGUAGE(card.ts). The shared estimate cases (packages/rate-card/src/fixtures/estimate-cases.ts) run through the package, the packed tarball andPOST /v1/estimate. - Path aliases:
#/*and@/*→./src/*;.tsimport extensions allowed.src/routeTree.gen.tsis generated by the DEV SERVER (the pinnedtsrCLI emits an old format) — never edit by hand; bootpnpm run devafter adding routes, then typecheck. No tests undersrc/routes/(the router treats them as routes; a.claudehook blocks them) — test thesrc/server/src/libcode the route calls. - Env:
.env.localholdsBETTER_AUTH_SECRET,BETTER_AUTH_URL(http://localhost:3100 — JWT audiences are origin-bound),ADMIN_KEY, optional provider keys (pnpm run secrets:pullfrom Dopplerdev;DOPPLER_*is stripped). Prod:pnpm run secrets:pushorwrangler secret put. README has the full production-setup + runbook.
API map: GET /v1 (index) · /v1/status · /v1/providers[/{p}/models] ·
/v1/models[?activity,provider,capability,q,pricing] · /v1/models/{p}/{id} ·
/v1/schemas/{p}[/{activity}[/{endpointId}?kind,version]] ·
POST /v1/validate · POST /v1/estimate · /v1/changes · POST /v1/agents/register-key ·
/v1/agents/me · /v1/subscriptions · POST /v1/admin/sync/{p} · POST /v1/admin/extract/fal ·
/v1/admin/export · /openapi.json · /llms.txt · /skill · /docs · /mcp ·
/.well-known/agent-configuration.