feat(stats): add canonical redirects and agent-readable data formats

Author: adamdotdevin

packages/console/app/src/lib/content-negotiation.ts

@@ -0,0 +1,13 @@
+// Shared by the console proxy and the stats app so both agree on which requests get Markdown.
+export function prefersMarkdown(accept: string | null | undefined) {
+  if (!accept) return false
+  const weights = new Map(
+    accept.split(",").map((part) => {
+      const fields = part.split(";").map((value) => value.trim().toLowerCase())
+      const quality = fields.slice(1).find((field) => field.startsWith("q="))
+      return [fields[0] ?? "", quality ? Number(quality.slice(2)) : 1] as const
+    }),
+  )
+  const markdown = Math.max(weights.get("text/markdown") ?? 0, weights.get("text/x-markdown") ?? 0)
+  return markdown > 0 && markdown >= (weights.get("text/html") ?? 0)
+}

packages/console/app/src/lib/stats-proxy.ts

@@ -1,5 +1,6 @@
 import type { APIEvent } from "@solidjs/start/server"
 import { Resource, waitUntil } from "@opencode-ai/console-resource"
+import { prefersMarkdown } from "~/lib/content-negotiation"
 import { LOCALE_HEADER, cookie, localeFromRequest, route, tag } from "~/lib/language"
 
 const dataPath = "/data"
@@ -40,16 +41,20 @@ export async function statsProxy(evt: APIEvent) {
     method: req.method,
     headers: requestHeaders,
     body: req.body,
+    // Pass canonical redirects from the stats app to the client instead of following them here.
+    redirect: "manual",
   })
 
+  const location = response.headers.get("location")
+  if (location) return withPublicLocation(response, new URL(location, targetUrl), targetUrl)
   if (!response.headers.get("content-type")?.includes("text/html")) return response
 
   const headers = new Headers(response.headers)
   headers.delete("content-encoding")
   headers.delete("content-length")
   headers.delete("etag")
   headers.delete("set-cookie")
-  appendVary(headers, "Accept-Language", "Cookie", LOCALE_HEADER)
+  appendVary(headers, "Accept", "Accept-Language", "Cookie", LOCALE_HEADER)
 
   const result = new Response(rewriteStatsHtml(await response.text()), {
     status: response.status,
@@ -73,6 +78,14 @@ export function statsRedirect(evt: APIEvent) {
   })
 }
 
+// A redirect to the stats origin itself would send clients past the proxy, so keep only the path.
+function withPublicLocation(response: Response, location: URL, upstream: URL) {
+  if (location.origin !== upstream.origin) return response
+  const headers = new Headers(response.headers)
+  headers.set("location", `${location.pathname}${location.search}${location.hash}`)
+  return new Response(response.body, { status: response.status, statusText: response.statusText, headers })
+}
+
 function rewriteStatsHtml(html: string) {
   return html.replaceAll('"/_build/', `"${dataPath}/_build/`).replaceAll("'/_build/", `'${dataPath}/_build/`)
 }
@@ -120,7 +133,7 @@ function redirectToLocalizedData(request: Request, url: URL, locale: ReturnType<
     Location: next.toString(),
   })
   headers.append("set-cookie", cookie(locale))
-  appendVary(headers, "Accept-Language", "Cookie", LOCALE_HEADER)
+  appendVary(headers, "Accept", "Accept-Language", "Cookie", LOCALE_HEADER)
 
   return new Response(null, {
     status: 308,
@@ -130,6 +143,8 @@ function redirectToLocalizedData(request: Request, url: URL, locale: ReturnType<
 
 function acceptsHtml(request: Request) {
   const accept = request.headers.get("accept")
+  // The stats app answers Markdown requests itself, so keep them out of the HTML cache and locale redirect.
+  if (prefersMarkdown(accept)) return false
   return !accept || accept.includes("text/html") || accept.includes("*/*")
 }
 
@@ -140,7 +155,10 @@ function isDataBypassPath(pathname: string) {
     pathname.startsWith(`${dataPath}/_server`) ||
     pathname === `${dataPath}/banner.jpg` ||
     pathname === `${dataPath}/banner.png` ||
-    pathname === `${dataPath}/sitemap.xml`
+    pathname === `${dataPath}/sitemap.xml` ||
+    pathname.endsWith("/llms.txt") ||
+    pathname.endsWith(".md") ||
+    pathname.endsWith(".json")
   )
 }
 

packages/opencode/test/cli/run/run-process.test.ts

@@ -67,7 +67,8 @@ describe("opencode run (non-interactive subprocess)", () => {
   // makes the SDK call surface an error promptly so the process exits nonzero.
   // We assert nonzero exit AND wall-clock under the harness timeout — a hang
   // would expire the timeout and produce a different (signal-killed) failure.
-  cliIt.concurrent(
+  // Keep competing CLI startups out of this wall-clock assertion on busy CI runners.
+  cliIt.live(
     "exits nonzero promptly when the model is unknown (regression for #27371)",
     ({ opencode }) =>
       Effect.gen(function* () {

packages/stats/app/src/component/agent-meta.tsx

@@ -0,0 +1,40 @@
+import { Link } from "@solidjs/meta"
+import { Show } from "solid-js"
+import { getRequestEvent } from "solid-js/web"
+import { jsonUrl, markdownUrl } from "../lib/language"
+
+export function JsonLd(props: { data: object }) {
+  // Escape "<" so values from the catalog can never close the script element.
+  return <script type="application/ld+json" innerHTML={JSON.stringify(props.data).replaceAll("<", "\\u003c")} />
+}
+
+export function FormatLinks(props: { path: string; json?: boolean }) {
+  return (
+    <>
+      <Link rel="alternate" type="text/markdown" href={markdownUrl(props.path)} />
+      <Show when={props.json !== false}>
+        <Link rel="alternate" type="application/json" href={jsonUrl(props.path)} />
+      </Show>
+    </>
+  )
+}
+
+export function LastModified(props: { value: string | null | undefined }) {
+  const event = getRequestEvent()
+  if (event && props.value) event.response.headers.set("Last-Modified", new Date(props.value).toUTCString())
+  return null
+}
+
+export function breadcrumbList(items: { name: string; url: string }[]) {
+  return {
+    "@type": "BreadcrumbList",
+    itemListElement: items.map((item, index) => ({
+      "@type": "ListItem",
+      position: index + 1,
+      name: item.name,
+      item: item.url,
+    })),
+  }
+}
+
+export const openCodeOrganization = { "@type": "Organization", name: "OpenCode", url: "https://opencode.ai" }

packages/stats/app/src/component/chart-data-table.tsx

@@ -0,0 +1,28 @@
+import { For } from "solid-js"
+
+// Text equivalent of a chart for screen readers and text-only clients. The wrapper hides it because tables
+// treat height as a minimum and would grow to fit their rows.
+export function ChartDataTable(props: { caption: string; headers: string[]; rows: (string | number)[][] }) {
+  return (
+    <div data-slot="visually-hidden">
+      <table>
+        <caption>{props.caption}</caption>
+        <thead>
+          <tr>
+            <For each={props.headers}>{(header) => <th scope="col">{header}</th>}</For>
+          </tr>
+        </thead>
+        <tbody>
+          <For each={props.rows}>
+            {(row) => (
+              <tr>
+                <th scope="row">{row[0]}</th>
+                <For each={row.slice(1)}>{(cell) => <td>{cell}</td>}</For>
+              </tr>
+            )}
+          </For>
+        </tbody>
+      </table>
+    </div>
+  )
+}

packages/stats/app/src/component/model-compare-detail.tsx

@@ -20,6 +20,7 @@ import {
 } from "../routes/compare-cards"
 import { ComparisonRadar } from "../routes/compare-radar"
 import {
+  catalogLabPath,
   catalogSlug,
   findModelCatalogEntry,
   formatCatalogLabName,
@@ -48,6 +49,7 @@ import {
 } from "../lib/comparison-pages"
 import { baseUrl } from "../lib/language"
 import { runStatsEffect } from "../stats-runtime"
+import { breadcrumbList, FormatLinks, JsonLd } from "./agent-meta"
 import { NotFoundMeta } from "./not-found-meta"
 
 const compareHeaderLinks: readonly HeaderLink[] = [
@@ -62,6 +64,7 @@ const compareFooterLinks: readonly HeaderLink[] = [
   { href: `${import.meta.env.BASE_URL}compare`, label: "Model Compare" },
   { href: `${import.meta.env.BASE_URL}#top-models`, label: "Top Models" },
   { href: `${import.meta.env.BASE_URL}#token-cost`, label: "Token Cost" },
+  { href: `${import.meta.env.BASE_URL}#methodology`, label: "Methodology" },
 ]
 const heroLabs = [
   { lab: "deepseek", label: "DeepSeek" },
@@ -204,21 +207,24 @@ export default function ModelCompareDetailPage(props: ModelCompareDetailPageProp
   const syncComparisonScroll = (source: HTMLDivElement, target: HTMLDivElement | undefined) => {
     if (target && target.scrollLeft !== source.scrollLeft) target.scrollLeft = source.scrollLeft
   }
-  const structuredData = createMemo(() =>
-    JSON.stringify({
-      "@context": "https://schema.org",
-      "@type": "WebPage",
-      name: title(),
-      description: description(),
-      url: canonicalUrl(),
-      about: models().map((model) => ({
-        "@type": "SoftwareApplication",
-        name: model.name,
-        applicationCategory: "AI model",
-        ...(model.labName ? { provider: model.labName } : {}),
-      })),
-    }),
-  )
+  const structuredData = createMemo(() => ({
+    "@context": "https://schema.org",
+    "@type": "WebPage",
+    name: title(),
+    description: description(),
+    url: canonicalUrl(),
+    about: models().map((model) => ({
+      "@type": "SoftwareApplication",
+      name: model.name,
+      applicationCategory: "AI model",
+      ...(model.labName ? { provider: model.labName } : {}),
+    })),
+    breadcrumb: breadcrumbList([
+      { name: "Data", url: new URL("/data/", baseUrl).toString() },
+      { name: "Compare", url: new URL("/data/compare", baseUrl).toString() },
+      { name: `${models()[0].name} vs ${models()[1].name}`, url: canonicalUrl() },
+    ]),
+  }))
   const updateThemePreference = (preference: ThemePreference) => {
     applyThemePreference(preference)
     setThemePreference(preference)
@@ -256,7 +262,8 @@ export default function ModelCompareDetailPage(props: ModelCompareDetailPageProp
           <Meta name="twitter:card" content="summary" />
           <Meta name="twitter:title" content={title()} />
           <Meta name="twitter:description" content={description()} />
-          <script type="application/ld+json">{structuredData()}</script>
+          <FormatLinks path={canonicalPath()} json={false} />
+          <JsonLd data={structuredData()} />
         </Show>
       </Show>
       <Header
@@ -348,9 +355,8 @@ function ComparisonHero(props: {
       </nav>
       <div data-slot="compare-detail-hero-grid">
         <h1 aria-label={`Compare ${props.models.map((model) => model.name).join(", ")}`}>
-          <span>Compare</span>
-          <HeroModelStack />
-          <span>AI models</span>
+          <span>Compare</span> <HeroModelStack /> <span>AI models</span>
+          <span data-slot="visually-hidden">: {props.models.map((model) => model.name).join(" vs ")}</span>
         </h1>
         <div data-slot="compare-detail-actions">
           <button
@@ -1033,7 +1039,7 @@ function comparisonModelLabel(model: ComparisonModel) {
 
 function providerDetailCell(model: ComparisonModel): ComparisonDetailCell {
   if (!model.labName) return textCell("")
-  return linkedTextCell(model.stats?.author ?? model.labName ?? "", labHref(model.lab))
+  return linkedTextCell(model.stats?.author ?? model.labName ?? "", catalogLabPath(model.lab))
 }
 
 function textCell(value: string): ComparisonDetailCell {
@@ -1080,10 +1086,6 @@ function tokenCell(value: number | undefined, trend: number | undefined): Compar
   return { value: formatTokens(value), score: value, trend }
 }
 
-function labHref(lab: string) {
-  return `${import.meta.env.BASE_URL}${catalogSlug(lab)}`
-}
-
 function modelSearchText(model: ModelCatalogEntry) {
   return `${model.name} ${formatCatalogLabName(model.lab)} ${model.id}`.toLowerCase()
 }

packages/stats/app/src/context/i18n.tsx

@@ -1,26 +1,15 @@
-import { createMemo } from "solid-js"
 import { createSimpleContext } from "@opencode-ai/ui/context"
-import { dict, type Key } from "../i18n"
+import { translate, type Key } from "../i18n"
 import { useLanguage } from "./language"
 
-function resolve(text: string, params?: Record<string, string | number>) {
-  if (!params) return text
-  return text.replace(/\{\{(\w+)\}\}/g, (raw, key) => {
-    const value = params[key]
-    if (value === undefined || value === null) return raw
-    return String(value)
-  })
-}
-
 export const { use: useI18n, provider: I18nProvider } = createSimpleContext({
   name: "StatsI18n",
   init: () => {
     const language = useLanguage()
-    const dictionary = createMemo(() => dict(language.locale()))
 
     return {
       t(key: Key, params?: Record<string, string | number>) {
-        return resolve(dictionary()[key], params)
+        return translate(language.locale(), key, params)
       },
     }
   },

packages/stats/app/src/i18n.ts

@@ -98,10 +98,14 @@ const en = {
   "chart.leaderboardAria": "Model token leaderboard",
   "chart.scrollableLeaderboardAria": "Scrollable model token leaderboard",
   "chart.byAuthor": "by {{author}}",
+  "chart.vsPreviousWeek": "vs previous week",
+  "chart.date": "Date",
   "home.updated": "Updated",
   "home.noRows": "No rows yet",
   "home.justNow": "just now",
   "home.heroCopy": "See which models are winning real usage, how the mix is shifting, and what that means for cost.",
+  "home.summary":
+    "As of {{date}}, {{first}} led OpenCode usage over the past 7 days with {{firstTokens}} tokens, followed by {{second}} ({{secondTokens}}) and {{third}} ({{thirdTokens}}).",
   "home.loadingTitle": "Loading data",
   "home.loadingDescription": "Reading model aggregates.",
   "home.usageTitle": "Usage",
@@ -147,6 +151,8 @@ const en = {
   "lab.title": "{{lab}} AI Model Usage & Rankings | OpenCode Data",
   "lab.description":
     "Compare {{lab}} models used in OpenCode, including token usage, model rankings, context windows, release dates, costs, and model-specific data.",
+  "lab.summary":
+    "{{lab}} models processed {{tokens}} tokens across OpenCode over the past two months, {{share}} of all usage. {{model}} was the most-used {{lab}} model.",
   "lab.loadingTitle": "Model Lab",
   "lab.loadingDescription": "Reading model availability and recent OpenCode usage.",
   "lab.notFound": "No models matched this lab.",
@@ -173,6 +179,10 @@ const en = {
   "model.title": "{{model}} Usage, Cost & Rank | OpenCode Data",
   "model.description":
     "View {{model}} OpenCode usage data, including token volume, weekly rank, token mix, costs, cache ratio, sessions, geo breakdowns, and peer models.",
+  "model.summary":
+    "{{model}} ranked #{{rank}} by tokens across OpenCode last week, with {{share}} of tokens over the past two months.",
+  "model.summaryUnranked": "{{model}} had {{share}} of tokens across OpenCode over the past two months.",
+  "model.summaryPrice": "{{model}} costs {{input}} per 1M input tokens and {{output}} per 1M output tokens.",
   "model.loadingTitle": "Model Data",
   "model.loadingDescription": "Reading model aggregates.",
   "model.loadingProfile": "Reading the model profile.",
@@ -246,6 +256,21 @@ const en = {
   "model.pdf": "PDF",
   "format.users": "users",
   "format.tokens": "tokens",
+  "methodology.title": "Methodology",
+  "methodology.description": "How this data is collected.",
+  "methodology.updatesLabel": "Updates",
+  "methodology.updates": "Aggregated every hour. Days and weeks use UTC.",
+  "methodology.tokensLabel": "Tokens",
+  "methodology.tokens": "Input, output, reasoning, and cached tokens for each request.",
+  "methodology.usersLabel": "Users and sessions",
+  "methodology.users": "Approximate counts of distinct users and OpenCode sessions.",
+  "methodology.costLabel": "Cost",
+  "methodology.cost":
+    "Session cost is the average cost per OpenCode session. Token prices are list prices from the OpenCode model catalog.",
+  "methodology.retentionLabel": "Retention",
+  "methodology.retention": "The share of a model's users in one week who use it again the next week.",
+  "methodology.citeLabel": "Citation",
+  "methodology.cite": "Cite OpenCode Data (opencode.ai/data) with the update time shown at the top of the page.",
 } as const
 
 export type Key = keyof typeof en
@@ -275,3 +300,13 @@ const dictionaries = {
 export function dict(locale: Locale) {
   return dictionaries[locale]
 }
+
+export function translate(locale: Locale, key: Key, params?: Record<string, string | number>) {
+  const text = dictionaries[locale][key]
+  if (!params) return text
+  return text.replace(/\{\{(\w+)\}\}/g, (raw, key) => {
+    const value = params[key]
+    if (value === undefined || value === null) return raw
+    return String(value)
+  })
+}