@stablekernel/opencode-bifrost 0.2.1 → 0.2.3-rc.1

package/README.md

@@ -11,6 +11,35 @@ OpenCode plugin that routes model traffic through a [Bifrost](https://docs.getbi
 
 No secret is held by the plugin; the key is read at runtime.
 
+## Datasheet supplement (off by default)
+
+Wildcard-provider models — e.g. a fresh Fireworks launch that the CLI's
+models.dev source has not cataloged yet — never reach `gateway-cli models`,
+so they cannot be listed here either. When configured, this plugin also reads
+the datasheet feed Bifrost itself syncs from and appends the wildcard-provider
+ids the CLI list lacks; CLI-listed ids always win. The supplement applies to
+the single `bifrost` provider.
+
+Activation (first wins):
+
+1. env `GATEWAY_DATASHEET_URL`
+2. `~/.config/bifrost/datasheet.json` — `{"url": "..."}`
+3. `<project>/.gateway/datasheet.json` — same shape
+
+The URL must be `https://`; a source with anything else is treated as absent.
+
+Behavior: the feed is fetched once per hour and cached under
+`~/.cache/opencode/datasheet-cache.json` (or `$XDG_CACHE_HOME`), with a 3s
+hard timeout and a stale-cache fallback on failure. A failed first fetch
+also triggers a background cache fill, so a slow or cold feed costs one
+session rather than every start. Unconfigured or unreachable, the
+supplement is silently skipped — startup never blocks on it.
+
+Provenance: supplement-only models are tagged `limits_source: "datasheet"`
+and `cost_source: "datasheet"` in the `gateway-cli models` payload they ride
+in. The tags stop there — opencode's config schema has no provenance field,
+so they are not forwarded into the emitted `opencode.json`.
+
 ## Requirements
 
 - `gateway-cli` on `PATH` (or the `GATEWAY_CLI_BIN` env var pointing at it), connected once with `gateway-cli connect`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stablekernel/opencode-bifrost",
-  "version": "0.2.1",
+  "version": "0.2.3-rc.1",
   "description": "OpenCode plugin that routes models through the Bifrost gateway, resolving per-project virtual keys via gateway-cli.",
   "type": "module",
   "main": "src/index.ts",

package/src/datasheet.test.ts

@@ -0,0 +1,300 @@
+import { describe, expect, test } from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  type FetchLike,
+  type SupplementalModel,
+  datasheetUrl,
+  fetchDatasheet,
+  mergeModels,
+  parseDatasheet,
+} from "./datasheet.js";
+import { toConfigModels, type CliModels } from "./index.js";
+
+const glmFlash = {
+  provider: "fireworks_ai",
+  mode: "chat",
+  base_model: "glm-5.3-flash",
+  context_length: 1048576,
+  max_input_tokens: 1048576,
+  max_output_tokens: 131072,
+  input_cost_per_token: 0.00000015,
+  cache_read_input_token_cost: 0.000000029,
+  output_cost_per_token: 0.0000005,
+  supports_reasoning: true,
+};
+
+describe("parseDatasheet", () => {
+  test("maps a fireworks_ai chat entry, converting per-token to per-million", () => {
+    const out = parseDatasheet({
+      "fireworks_ai/accounts/fireworks/models/glm-5p3-flash": glmFlash,
+    });
+    expect(out).toHaveLength(1);
+    expect(out[0]).toEqual({
+      id: "accounts/fireworks/models/glm-5p3-flash",
+      name: "glm-5.3-flash",
+      context_window: 1048576,
+      max_output_tokens: 131072,
+      limits_source: "datasheet",
+      cost_source: "datasheet",
+      cost: {
+        input: 0.15,
+        output: 0.5,
+        cache_read: 0.029,
+        cache_write: 0,
+      },
+      reasoning: true,
+    } satisfies SupplementalModel);
+  });
+
+  test("drops non-chat entries, unknown providers, and rows without limits", () => {
+    const out = parseDatasheet({
+      "fireworks_ai/accounts/fireworks/models/qwen3-embedding-8b": {
+        ...glmFlash,
+        mode: "embedding",
+      },
+      "other_provider/some/model": glmFlash,
+      "fireworks_ai/accounts/fireworks/models/no-limits": {
+        ...glmFlash,
+        context_length: undefined,
+      },
+      "fireworks_ai/accounts/fireworks/models/no-max-out": {
+        ...glmFlash,
+        max_output_tokens: undefined,
+      },
+    });
+    expect(out).toEqual([]);
+  });
+
+  test("unpriced entry omits cost entirely and falls back to slug name", () => {
+    const out = parseDatasheet({
+      "fireworks_ai/accounts/fireworks/models/glm-5p3-flash": {
+        mode: "chat",
+        context_length: 1000,
+        max_output_tokens: 100,
+      },
+    });
+    expect(out[0]?.name).toBe("glm-5p3-flash");
+    expect(out[0]?.cost).toBeUndefined();
+    expect(out[0]?.cost_source).toBeUndefined();
+  });
+});
+
+describe("mergeModels", () => {
+  test("appends ids the CLI list lacks; CLI entry wins on collision", () => {
+    // mergeModels is generic over {id: string}: dedup is by id only, so the
+    // test uses plain {id, name} literals rather than full model shapes.
+    const cli = [
+      { id: "a", name: "A" },
+      { id: "b", name: "B" },
+    ];
+    const extra = [
+      { id: "b", name: "B-datasheet" },
+      { id: "c", name: "C" },
+    ];
+    expect(mergeModels(cli, extra)).toEqual([
+      { id: "a", name: "A" },
+      { id: "b", name: "B" },
+      { id: "c", name: "C" },
+    ]);
+  });
+});
+
+describe("datasheetUrl", () => {
+  const tmp = mkdtempSync(join(tmpdir(), "gw-ds-"));
+  const proj = join(tmp, "proj");
+  const home = join(tmp, "home");
+  mkdirSync(join(proj, ".gateway"), { recursive: true });
+  mkdirSync(join(home, ".config", "bifrost"), { recursive: true });
+
+  test("env var wins over files", () => {
+    expect(datasheetUrl("https://env/datasheet", home, proj)).toBe(
+      "https://env/datasheet",
+    );
+  });
+
+  test("user file beats project file", () => {
+    writeFileSync(
+      join(home, ".config", "bifrost", "datasheet.json"),
+      `{"url": "https://user/datasheet"}`,
+    );
+    writeFileSync(
+      join(proj, ".gateway", "datasheet.json"),
+      `{"url": "https://proj/datasheet"}`,
+    );
+    expect(datasheetUrl(undefined, home, proj)).toBe("https://user/datasheet");
+  });
+
+  test("project file used when user-level absent; null when neither", () => {
+    // Self-seeded: does not depend on files written by earlier tests.
+    writeFileSync(
+      join(proj, ".gateway", "datasheet.json"),
+      `{"url": "https://proj/datasheet"}`,
+    );
+    // a home with no datasheet.json falls through to the project file
+    const homeEmpty = join(tmp, "home-empty");
+    mkdirSync(homeEmpty, { recursive: true });
+    expect(datasheetUrl(undefined, homeEmpty, proj)).toBe(
+      "https://proj/datasheet",
+    );
+    expect(datasheetUrl(undefined, homeEmpty, join(tmp, "other"))).toBeNull();
+  });
+
+  test("non-https URLs are treated as absent and fall through", () => {
+    // Feeds steer local model listings, so every source must be TLS: an
+    // http:// project file is skipped, and with nothing else yielding a
+    // URL the result is null.
+    const projHttp = join(tmp, "proj-http");
+    mkdirSync(join(projHttp, ".gateway"), { recursive: true });
+    writeFileSync(
+      join(projHttp, ".gateway", "datasheet.json"),
+      `{"url": "http://insecure/datasheet"}`,
+    );
+    const homeEmpty = join(tmp, "home-empty-http");
+    mkdirSync(homeEmpty, { recursive: true });
+    expect(datasheetUrl(undefined, homeEmpty, projHttp)).toBeNull();
+    // A non-TLS env override likewise falls through to an https file.
+    writeFileSync(
+      join(projHttp, ".gateway", "datasheet.json"),
+      `{"url": "https://proj/datasheet"}`,
+    );
+    expect(
+      datasheetUrl("http://insecure-env/datasheet", homeEmpty, projHttp),
+    ).toBe("https://proj/datasheet");
+  });
+});
+
+describe("fetchDatasheet", () => {
+  const tmp = mkdtempSync(join(tmpdir(), "gw-ds-cache-"));
+  // Each test gets its own cache file so results never depend on run order.
+  const cachePath = (name: string) => join(tmp, `${name}.json`);
+  const ok: FetchLike = async () => ({
+    ok: true,
+    json: async () => ({
+      "fireworks_ai/accounts/fireworks/models/glm-5p3-flash": glmFlash,
+    }),
+  });
+  const fail: FetchLike = async () => ({ ok: false, json: async () => ({}) });
+
+  test("fetches, returns parsed body, writes cache", async () => {
+    const body = await fetchDatasheet(
+      "https://feed/datasheet",
+      cachePath("t1"),
+      ok,
+      1000,
+    );
+    expect(
+      body?.["fireworks_ai/accounts/fireworks/models/glm-5p3-flash"],
+    ).toBeDefined();
+    const cached = JSON.parse(readFileSync(cachePath("t1"), "utf8"));
+    expect(cached.fetchedAt).toBe(1000);
+  });
+
+  test("fresh cache short-circuits the fetch", async () => {
+    // Seed a cache first so the counting call below has something to hit.
+    await fetchDatasheet("https://feed/datasheet", cachePath("t2"), ok, 1000);
+    let called = 0;
+    const counting: FetchLike = async () => {
+      called++;
+      return ok("u");
+    };
+    await fetchDatasheet(
+      "https://feed/datasheet",
+      cachePath("t2"),
+      counting,
+      1000 + 1000,
+    );
+    expect(called).toBe(0);
+  });
+
+  test("expired cache refetches; fetch failure falls back to stale cache", async () => {
+    await fetchDatasheet("https://feed/datasheet", cachePath("t3"), ok, 1000);
+    const body = await fetchDatasheet(
+      "https://feed/datasheet",
+      cachePath("t3"),
+      fail,
+      1000 + 3_600_000 + 1,
+    );
+    expect(
+      body?.["fireworks_ai/accounts/fireworks/models/glm-5p3-flash"],
+    ).toBeDefined();
+  });
+
+  test("fetch failure with no cache returns null", async () => {
+    expect(
+      await fetchDatasheet(
+        "https://feed/datasheet",
+        cachePath("absent"),
+        fail,
+        1000,
+      ),
+    ).toBeNull();
+  });
+
+  test("failed fetch with no cache backfills the cache in the background", async () => {
+    const path = cachePath("backfill");
+    let calls = 0;
+    const flaky: FetchLike = async () => {
+      calls++;
+      if (calls === 1) throw new Error("cold start");
+      return {
+        ok: true,
+        json: async () => ({
+          "fireworks_ai/accounts/fireworks/models/glm-5p3-flash": glmFlash,
+        }),
+      };
+    };
+    const first = await fetchDatasheet(
+      "https://feed/datasheet",
+      path,
+      flaky,
+      1000,
+    );
+    expect(first).toBeNull(); // this session skips the supplement
+    // the detached backfill (call 2) lands the cache for the next session
+    const deadline = Date.now() + 2000;
+    while (Date.now() < deadline) {
+      if (existsSync(path)) break;
+      await new Promise((r) => setTimeout(r, 25));
+    }
+    expect(calls).toBe(2);
+    const doc = JSON.parse(readFileSync(path, "utf8")) as {
+      fetchedAt: number;
+    };
+    expect(doc.fetchedAt).toBeGreaterThan(1000);
+  });
+});
+
+describe("end-to-end: CLI payload + datasheet extra -> opencode config models", () => {
+  test("supplemented id reaches the provider config with datasheet limits", () => {
+    const cliPayload: CliModels = {
+      models: [
+        {
+          id: "accounts/fireworks/models/glm-5p2",
+          name: "GLM 5.2",
+          context_window: 200000,
+          max_output_tokens: 32768,
+          limits_source: "gateway",
+        },
+      ],
+    };
+    const extra = parseDatasheet({
+      "fireworks_ai/accounts/fireworks/models/glm-5p3-flash": glmFlash,
+    });
+    const merged = mergeModels(cliPayload.models ?? [], extra);
+    const cfg = toConfigModels({ models: merged }, undefined);
+    const flash = cfg["accounts/fireworks/models/glm-5p3-flash"];
+    expect(flash).toBeDefined();
+    expect(flash?.limit?.context).toBe(1048576);
+    expect(flash?.limit?.output).toBe(131072);
+    // CLI-listed model survives the merge untouched
+    expect(cfg["accounts/fireworks/models/glm-5p2"]).toBeDefined();
+  });
+});

package/src/datasheet.ts

@@ -0,0 +1,280 @@
+/**
+ * Datasheet supplement: a second, faster id source for wildcard-provider
+ * models the CLI cannot list yet.
+ *
+ * The CLI sources Fireworks (wildcard-provider) ids from models.dev, which
+ * lags provider launches by days and is cached 24h. Bifrost itself syncs
+ * from the datasheet-proxy feed hourly, so a model merged there is routable —
+ * this module reads the same feed and merges the ids the CLI list lacks.
+ * The virtual key never passes through here: the feed is public.
+ *
+ * Off by default. Activated by (first wins; the URL must be https — any
+ * source yielding something else is treated as absent):
+ *   1. env GATEWAY_DATASHEET_URL
+ *   2. ~/.config/bifrost/datasheet.json  {"url": "<function-url>/datasheet"}
+ *   3. <project-root>/.gateway/datasheet.json
+ *
+ * Security note: entries only produce local picker listings and metadata;
+ * requests still go to the CLI-resolved (allowlisted) gateway origin. A
+ * hostile feed cannot redirect traffic or exfiltrate the key.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** One row of the datasheet feed (flat map keyed by "<provider>/<model-id>"). */
+export type DatasheetEntry = {
+  provider?: string;
+  mode?: string;
+  base_model?: string;
+  context_length?: number;
+  max_input_tokens?: number;
+  max_output_tokens?: number;
+  max_tokens?: number;
+  input_cost_per_token?: number;
+  output_cost_per_token?: number;
+  cache_read_input_token_cost?: number;
+  cache_write_input_token_cost?: number;
+  supports_reasoning?: boolean;
+};
+
+/** A model in the same shape `gateway-cli models` emits (structural subset). */
+export type SupplementalModel = {
+  id: string;
+  name: string;
+  context_window: number;
+  max_output_tokens: number;
+  limits_source: string;
+  cost_source?: string;
+  cost?: {
+    input: number;
+    output: number;
+    cache_read: number;
+    cache_write: number;
+  };
+  reasoning?: boolean;
+};
+
+/** Datasheet provider prefixes whose entries this module understands. */
+const PROVIDER_PREFIXES = ["fireworks_ai/"];
+
+/** How long a fetched feed is reused before refetching. */
+const DATASHEET_TTL_MS = 60 * 60 * 1000;
+
+/** Fetch hard timeout: the supplement must never block plugin init long. */
+const FETCH_TIMEOUT_MS = 3000;
+
+/** Budget for the background cache fill after a failed fetch: init is never
+ * blocked by it, so it can afford to outlast a cold feed start. */
+const BACKFILL_TIMEOUT_MS = 15_000;
+
+export type FetchLike = (
+  url: string,
+  init?: { signal?: AbortSignal },
+) => Promise<{ ok: boolean; status?: number; json(): Promise<unknown> }>;
+
+type CacheDoc = { fetchedAt: number; body: Record<string, DatasheetEntry> };
+
+/**
+ * Discover the feed URL: env, then user file, then project file. Only
+ * https:// URLs are honored; a source with anything else (including a
+ * non-TLS env override) falls through to the next candidate.
+ */
+export function datasheetUrl(
+  env: string | undefined,
+  home: string | undefined,
+  root: string,
+): string | null {
+  if (env && env.startsWith("https://")) return env;
+  const candidates = [
+    home ? join(home, ".config", "bifrost", "datasheet.json") : null,
+    join(root, ".gateway", "datasheet.json"),
+  ];
+  for (const p of candidates) {
+    if (!p) continue;
+    try {
+      const parsed = JSON.parse(readFileSync(p, "utf8")) as { url?: unknown };
+      if (
+        typeof parsed.url === "string" &&
+        parsed.url.startsWith("https://")
+      ) {
+        return parsed.url;
+      }
+    } catch {
+      // absent or malformed: try the next candidate
+    }
+  }
+  return null;
+}
+
+function readCache(path: string): CacheDoc | null {
+  try {
+    const doc = JSON.parse(readFileSync(path, "utf8")) as CacheDoc;
+    if (
+      typeof doc.fetchedAt === "number" &&
+      doc.body &&
+      typeof doc.body === "object"
+    ) {
+      return doc;
+    }
+  } catch {
+    // absent or malformed: treat as no cache
+  }
+  return null;
+}
+
+function writeCache(path: string, doc: CacheDoc): void {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(doc));
+  } catch {
+    // cache write failure is non-fatal: refetch next init
+  }
+}
+
+/**
+ * Default fetch adapter: narrows the platform Response to FetchLike's
+ * subset so callers can inject a mock without touching the global fetch.
+ */
+const defaultFetch: FetchLike = async (u, i) => {
+  const resp = await fetch(u, i);
+  return { ok: resp.ok, status: resp.status, json: () => resp.json() };
+};
+
+/**
+ * Fetch the feed, honoring a fresh cache. On fetch failure a stale cache is
+ * served; with no cache at all the result is null and the caller skips the
+ * supplement. Garbage responses (non-object JSON, HTTP error) are treated
+ * as fetch failures so they never poison the cache. A fetch failure with no
+ * cache also triggers an unawaited backfill fetch (15s budget) that only
+ * writes the cache, so a cold feed costs one session, not one per start.
+ */
+export async function fetchDatasheet(
+  url: string,
+  cachePath: string,
+  fetchImpl: FetchLike = defaultFetch,
+  now: number = Date.now(),
+): Promise<Record<string, DatasheetEntry> | null> {
+  const cached = readCache(cachePath);
+  if (cached && now - cached.fetchedAt < DATASHEET_TTL_MS) return cached.body;
+  try {
+    const resp = await fetchImpl(url, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+    const body = (await resp.json()) as Record<string, DatasheetEntry>;
+    if (!body || typeof body !== "object" || Array.isArray(body)) {
+      throw new Error("unexpected feed shape");
+    }
+    writeCache(cachePath, { fetchedAt: now, body });
+    return body;
+  } catch {
+    if (!cached) {
+      // Fire-and-forget warm fill: a slow feed (cold start) must not block
+      // plugin init, but the next session should find a warm cache. Never
+      // awaited; every failure path is swallowed (writeCache guards, and
+      // the .catch below covers the rest).
+      void fetchImpl(url, {
+        signal: AbortSignal.timeout(BACKFILL_TIMEOUT_MS),
+      })
+        .then(async (resp) => {
+          if (!resp.ok) return;
+          const body = (await resp.json()) as Record<string, DatasheetEntry>;
+          if (body && typeof body === "object" && !Array.isArray(body)) {
+            writeCache(cachePath, { fetchedAt: Date.now(), body });
+          }
+        })
+        .catch(() => {});
+    }
+    return cached?.body ?? null;
+  }
+}
+
+function perMillion(rate: number | undefined): number {
+  return typeof rate === "number" ? Math.round(rate * 1_000_000 * 1e8) / 1e8 : 0;
+}
+
+/**
+ * Turn feed rows into model entries. Keeps only chat-mode rows under a known
+ * provider prefix, requires usable limits, converts per-token rates to
+ * per-million (mirroring the CLI's perTokenToPerMTok).
+ */
+export function parseDatasheet(
+  body: Record<string, DatasheetEntry>,
+): SupplementalModel[] {
+  const out: SupplementalModel[] = [];
+  for (const [key, e] of Object.entries(body)) {
+    if (!e || typeof e !== "object" || e.mode !== "chat") continue;
+    const prefix = PROVIDER_PREFIXES.find((p) => key.startsWith(p));
+    if (!prefix) continue;
+    const id = key.slice(prefix.length);
+    if (!id) continue;
+    if (
+      typeof e.context_length !== "number" ||
+      typeof e.max_output_tokens !== "number"
+    ) {
+      continue;
+    }
+    const slug = id.split("/").pop() as string;
+    const priced =
+      typeof e.input_cost_per_token === "number" ||
+      typeof e.output_cost_per_token === "number";
+    out.push({
+      id,
+      name:
+        typeof e.base_model === "string" && e.base_model ? e.base_model : slug,
+      context_window: e.context_length,
+      max_output_tokens: e.max_output_tokens,
+      limits_source: "datasheet",
+      ...(priced
+        ? {
+            cost_source: "datasheet",
+            cost: {
+              input: perMillion(e.input_cost_per_token),
+              output: perMillion(e.output_cost_per_token),
+              cache_read: perMillion(e.cache_read_input_token_cost),
+              cache_write: perMillion(e.cache_write_input_token_cost),
+            },
+          }
+        : {}),
+      ...(e.supports_reasoning === true ? { reasoning: true } : {}),
+    });
+  }
+  return out;
+}
+
+/** Merge supplemented ids into the CLI list. The CLI entry wins on collision. */
+export function mergeModels<A extends { id: string }>(
+  cli: A[],
+  extra: A[],
+): A[] {
+  const seen = new Set(cli.map((m) => m.id));
+  return [...cli, ...extra.filter((m) => !seen.has(m.id))];
+}
+
+/**
+ * Entry point for the plugin: resolve the feed URL for this project, fetch
+ * (cached), and return supplementable models. Empty when the feature is off
+ * or the feed is unreachable and uncached — never throws, never blocks init
+ * beyond FETCH_TIMEOUT_MS.
+ *
+ * cacheDir may be any writable directory; the cache file is named
+ * datasheet-cache.json so it can never collide with a discovery config file.
+ */
+export async function datasheetSupplement(
+  root: string,
+  cacheDir: string,
+  fetchImpl?: FetchLike,
+): Promise<SupplementalModel[]> {
+  const url = datasheetUrl(
+    process.env.GATEWAY_DATASHEET_URL,
+    process.env.HOME,
+    root,
+  );
+  if (!url) return [];
+  const body = await fetchDatasheet(
+    url,
+    join(cacheDir, "datasheet-cache.json"),
+    fetchImpl,
+  );
+  return body ? parseDatasheet(body) : [];
+}

package/src/index.test.ts

@@ -1,10 +1,32 @@
-import { describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import {
   BifrostGateway,
+  type CliModel,
   isAllowedGatewayUrl,
+  isStale,
   toConfigModels,
 } from "./index.js";
 
+/** HOME as the suite found it, restored after each test. */
+const ORIGINAL_HOME = process.env.HOME;
+
+beforeEach(() => {
+  // The config-hook tests run the real datasheetSupplement. Keep it
+  // deterministic and machine-independent: drop the env override and point
+  // HOME at an empty temp dir, so neither ~/.config/bifrost/datasheet.json
+  // nor the real ~/.cache/opencode cache is read or written.
+  delete process.env.GATEWAY_DATASHEET_URL;
+  process.env.HOME = mkdtempSync(join(tmpdir(), "gw-oc-home-"));
+});
+
+afterEach(() => {
+  if (ORIGINAL_HOME === undefined) delete process.env.HOME;
+  else process.env.HOME = ORIGINAL_HOME;
+});
+
 const RESOLUTION = {
   env: "prod",
   root: "/repo",
@@ -16,26 +38,6 @@ const RESOLUTION = {
   headers: { "X-Org-Route": "prod" },
 };
 
-/** One model as `gateway-cli models` reports it. */
-type CliModel = {
-  id: string;
-  name: string;
-  context_window: number;
-  max_output_tokens: number;
-  cost?: {
-    input: number;
-    output: number;
-    cache_read: number;
-    cache_write: number;
-  };
-  limits_source: string;
-  cost_source?: string;
-  /** Reasoning capability and applicable efforts, from the catalog. */
-  reasoning?: boolean;
-  reasoning_efforts?: string[];
-  reasoning_budget_min?: number;
-};
-
 function cliPayload(models: CliModel[]): string {
   return JSON.stringify({
     wire: "openai-completions",
@@ -109,9 +111,33 @@ async function load(responses: Record<string, string>, calls: string[] = []) {
   return BifrostGateway({ directory: "/repo", $ } as never);
 }
 
+/** The per-model shape the config hook writes into `provider.<id>.models`. */
+type TestModel = {
+  name: string;
+  limit: { context: number; output: number };
+  /** Per-million-token rates; absent when nothing could price the model. */
+  cost?: {
+    input: number;
+    output: number;
+    cache_read: number;
+    cache_write: number;
+  };
+};
+
+/** One provider entry as the config hook writes it. */
+type TestProvider = {
+  npm?: string;
+  name?: string;
+  options: { baseURL?: string; headers?: Record<string, string> };
+  models: Record<string, TestModel>;
+};
+
+/** The opencode config object the plugin mutates, as tests read it back. */
+type TestConfig = { provider: Record<string, TestProvider> };
+
 async function applyConfig(responses: Record<string, string>, seed = {}) {
   const hooks = await load(responses);
-  const cfg: Record<string, any> = { ...seed };
+  const cfg = { ...seed } as TestConfig;
   await hooks.config!(cfg as never);
   return cfg;
 }
@@ -231,6 +257,58 @@ describe("config hook", () => {
   });
 });
 
+describe("datasheet supplement gate", () => {
+  const EXTRA_FLASH = {
+    id: "accounts/fireworks/models/glm-5p3-flash",
+    name: "glm-5p3-flash",
+    context_window: 1048576,
+    max_output_tokens: 131072,
+    limits_source: "datasheet",
+  };
+
+  test("appends supplement ids to the bifrost provider's models map", async () => {
+    // The module under test is statically imported at the top of this file,
+    // so register the ./datasheet.js mock and then re-import index.js fresh
+    // (cache-busted) — the plugin's datasheetSupplement/mergeModels bindings
+    // resolve to the mocks only in that new instance. mock.restore() in
+    // finally keeps every other test on the real module.
+    mock.module("./datasheet.js", () => ({
+      datasheetSupplement: async () => [EXTRA_FLASH],
+      // Same CLI-wins dedup as the real mergeModels, inlined to avoid a
+      // circular import of the module under mock.
+      mergeModels: (
+        cli: Array<{ id: string }>,
+        extra: Array<{ id: string }>,
+      ) => {
+        const seen = new Set(cli.map((m) => m.id));
+        return [...cli, ...extra.filter((m) => !seen.has(m.id))];
+      },
+    }));
+    try {
+      const mod = (await import(
+        `./index.js?${Math.random()}`
+      )) as typeof import("./index.js");
+      const hooks = await mod.BifrostGateway({
+        directory: "/repo",
+        $: fakeShell(OK_SHELL),
+      } as never);
+      const cfg = {} as TestConfig;
+      await hooks.config!(cfg as never);
+      const ids = Object.keys(cfg.provider.bifrost.models);
+      // The CLI's list survives; the supplemented id is appended alongside.
+      expect(ids).toContain("anthropic/claude-haiku-4-5-20251001");
+      expect(ids).toContain("bedrock/amazon.nova-lite-v1:0");
+      expect(ids).toContain(EXTRA_FLASH.id);
+      expect(cfg.provider.bifrost.models[EXTRA_FLASH.id].limit).toEqual({
+        context: 1048576,
+        output: 131072,
+      });
+    } finally {
+      mock.restore();
+    }
+  });
+});
+
 describe("unpriced models", () => {
   test("omits cost entirely rather than declaring zero", () => {
     // A zeroed rate card renders as free, which is worse than blank.
@@ -255,6 +333,20 @@ describe("unpriced models", () => {
   });
 });
 
+describe("disabled models", () => {
+  test("omits models the CLI marks disabled", () => {
+    const models = toConfigModels({
+      models: [{ ...NOVA, disabled: true }],
+    });
+    expect(models["bedrock/amazon.nova-lite-v1:0"]).toBeUndefined();
+  });
+
+  test("keeps models the CLI does not mark disabled", () => {
+    const models = toConfigModels({ models: [NOVA] });
+    expect(models["bedrock/amazon.nova-lite-v1:0"]).toBeDefined();
+  });
+});
+
 describe("reasoning", () => {
   /** A reasoning model with a discrete effort set, like Fireworks kimi-k3. */
   const REASONING: CliModel = {
@@ -354,10 +446,21 @@ describe("auth.loader", () => {
   test("falls back to the stored credential without gateway-cli", async () => {
     const hooks = await load({});
     const opts = await hooks.auth!.loader!(
-      async () => ({ type: "api", key: "stored-key" }) as never,
+      async () => ({ type: "api", key: "sk-bf-storedkey" }) as never,
       {} as never,
     );
-    expect(opts.apiKey).toBe("stored-key");
+    expect(opts.apiKey).toBe("sk-bf-storedkey");
+  });
+
+  test("ignores a stored credential that is not a Bifrost virtual key", async () => {
+    // OpenCode saves whatever the connect prompt collects without
+    // validation; the loader must not hand a stray key to the gateway.
+    const hooks = await load({});
+    const opts = await hooks.auth!.loader!(
+      async () => ({ type: "api", key: "sk-not-bifrost" }) as never,
+      {} as never,
+    );
+    expect(opts).toEqual({});
   });
 
   test("returns no options when there is no credential at all", async () => {
@@ -370,16 +473,18 @@ describe("auth.loader", () => {
 });
 
 describe("auth.methods", () => {
-  test("rejects a value that is not a Bifrost virtual key", async () => {
+  test("single prompt-less api method — OpenCode asks for the key itself", async () => {
+    // OpenCode (1.18.x) collects method `prompts`, then unconditionally
+    // prompts for the key a second time; api-method `authorize` never runs
+    // from the TUI and the CLI double-prompts too. Defining either made
+    // /connect ask for the virtual key twice.
     const hooks = await load(OK_SHELL);
     const method = hooks.auth!.methods[0] as any;
-    expect(await method.authorize({ key: "nope" })).toEqual({ type: "failed" });
-    expect(await method.authorize({ key: "sk-bf-good" })).toEqual({
-      type: "success",
-      key: "sk-bf-good",
-    });
-    expect(method.prompts[0].validate("nope")).toBeString();
-    expect(method.prompts[0].validate("sk-bf-good")).toBeUndefined();
+    expect(hooks.auth!.methods).toHaveLength(1);
+    expect(method.type).toBe("api");
+    expect(method.label).toContain("Bifrost Gateway");
+    expect(method.prompts).toBeUndefined();
+    expect(method.authorize).toBeUndefined();
   });
 });
 
@@ -394,3 +499,19 @@ describe("gateway URL allowlist", () => {
     expect(isAllowedGatewayUrl("not a url")).toBe(false);
   });
 });
+
+describe("stale-plugin notice", () => {
+  test("warns only when the registry is ahead", () => {
+    expect(isStale("0.1.0", "0.2.1")).toBe(true);
+    expect(isStale("0.2.0", "0.2.1")).toBe(true);
+    expect(isStale("0.2.1", "0.2.1")).toBe(false);
+    // A dev build ahead of the registry is not stale.
+    expect(isStale("0.3.0", "0.2.1")).toBe(false);
+    expect(isStale("0.2.2", "0.2.1")).toBe(false);
+  });
+
+  test("treats unparseable differences as stale rather than guessing", () => {
+    expect(isStale("dev", "0.2.1")).toBe(true);
+    expect(isStale("dev", "dev")).toBe(false);
+  });
+});

package/src/index.ts

@@ -1,4 +1,6 @@
 import type { Plugin } from "@opencode-ai/plugin";
+import { homedir } from "node:os";
+import { datasheetSupplement, mergeModels } from "./datasheet.js";
 
 /** Provider id registered with OpenCode. */
 const PROVIDER_ID = "bifrost";
@@ -33,6 +35,15 @@ type Resolution = {
   reasoning_effort?: string;
 };
 
+/** One entry in OpenCode's `provider` config map, as this plugin writes it. */
+type ProviderEntry = {
+  options?: Record<string, unknown>;
+  models?: Record<string, ConfigModel>;
+  // OpenCode's provider config carries more fields than this plugin sets;
+  // user overrides are preserved verbatim via the spread in the config hook.
+  [key: string]: unknown;
+};
+
 /** The model shape OpenCode reads from `provider.<id>.models`. */
 type ConfigModel = {
   name: string;
@@ -54,7 +65,7 @@ type ConfigModel = {
 };
 
 /** One model as reported by `gateway-cli models`. */
-type CliModel = {
+export type CliModel = {
   id: string;
   name: string;
   context_window: number;
@@ -67,13 +78,16 @@ type CliModel = {
   };
   limits_source: string;
   cost_source?: string;
+  /** True when the gateway lists the model but it rejects completion on
+   * this key (not entitled, needs provisioned throughput, retired). */
+  disabled?: boolean;
   /** Reasoning capability and applicable efforts, from the catalog. */
   reasoning?: boolean;
   reasoning_efforts?: string[];
   reasoning_budget_min?: number;
 };
 
-type CliModels = { models?: CliModel[] };
+export type CliModels = { models?: CliModel[] };
 
 /**
  * Bifrost gateway provider for OpenCode.
@@ -91,7 +105,136 @@ type CliModels = { models?: CliModel[] };
  * the picker. The v2 `provider.models` hook is not used because the v2
  * catalog is not active in this version.
  */
-export const BifrostGateway: Plugin = async ({ directory, $ }) => {
+/**
+ * How long a "plugin is current" answer is trusted before the registry is
+ * asked again. Kept on disk so the once-daily check costs nothing on the
+ * frequent path (every opencode startup constructs this plugin).
+ */
+const VERSION_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** npm registry endpoint for the published package's latest version. */
+const REGISTRY_URL =
+  "https://registry.npmjs.org/@stablekernel/opencode-bifrost/latest";
+
+/** The version of this build, read from the package's own package.json. */
+function ownVersion(): string | null {
+  try {
+    const pkg = require("../package.json") as { version?: string };
+    return pkg.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+type VersionCheckCache = { checkedAt: number; latest: string };
+
+/** opencode's plugin cache root; matches where the host itself caches. */
+function versionCheckPath(): string | null {
+  const home = process.env.HOME;
+  if (!home) return null;
+  const base = process.env.XDG_CACHE_HOME ?? `${home}/.cache`;
+  return `${base}/opencode/bifrost-version-check.json`;
+}
+
+/** Where the datasheet feed cache lives; same base as the version check. */
+function datasheetCacheDir(): string | null {
+  const home = process.env.HOME || homedir() || null;
+  const base = process.env.XDG_CACHE_HOME ?? (home ? `${home}/.cache` : null);
+  return base ? `${base}/opencode` : null;
+}
+
+/**
+ * The latest published version, from a fresh-enough cache file when present
+ * and the npm registry otherwise. Null means unknown — offline, timeout, or
+ * an unreadable cache — and never warns.
+ */
+async function latestPublishedVersion(): Promise<string | null> {
+  const path = versionCheckPath();
+  if (path) {
+    try {
+      const cached = JSON.parse(
+        await Bun.file(path).text(),
+      ) as VersionCheckCache;
+      if (
+        typeof cached.latest === "string" &&
+        Date.now() - cached.checkedAt < VERSION_CHECK_TTL_MS
+      ) {
+        return cached.latest;
+      }
+    } catch {
+      // Missing or corrupt cache: fall through to the registry.
+    }
+  }
+  let latest: string | null = null;
+  try {
+    const res = await fetch(REGISTRY_URL, {
+      signal: AbortSignal.timeout(1500),
+    });
+    if (res.ok) {
+      const body = (await res.json()) as { version?: string };
+      latest = typeof body.version === "string" ? body.version : null;
+    }
+  } catch {
+    return null; // offline or slow registry: stay silent
+  }
+  if (latest && path) {
+    try {
+      const { mkdirSync, writeFileSync } = await import("node:fs");
+      const { dirname } = await import("node:path");
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(
+        path,
+        JSON.stringify({
+          checkedAt: Date.now(),
+          latest,
+        } satisfies VersionCheckCache),
+      );
+    } catch {
+      // A failed cache write just means the next start asks again.
+    }
+  }
+  return latest;
+}
+
+/**
+ * Whether the installed build should warn about a newer release. Dev builds
+ * ahead of the registry (installed > latest) are not stale.
+ */
+export function isStale(installed: string, latest: string): boolean {
+  if (installed === latest) return false;
+  // Strict semver core only: parseInt would silently accept "0.3.0-dev" as
+  // 0.3.0 and misjudge the comparison. Odd shapes (prereleases, two-part
+  // versions) fall back to "warn on any difference" rather than a guess.
+  const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
+  const a = SEMVER.exec(installed);
+  const b = SEMVER.exec(latest);
+  if (!a || !b) return true;
+  for (let i = 1; i <= 3; i++) {
+    const av = Number(a[i]);
+    const bv = Number(b[i]);
+    if (bv > av) return true;
+    if (bv < av) return false;
+  }
+  return false;
+}
+
+/**
+ * Report a newer published plugin exactly once per version via the host's
+ * log. Fire-and-forget from the config hook: version drift must never block
+ * or fail provider registration.
+ */
+async function announceIfStale(log: (message: string) => void): Promise<void> {
+  const installed = ownVersion();
+  if (!installed) return;
+  const latest = await latestPublishedVersion();
+  if (!latest || !isStale(installed, latest)) return;
+  log(
+    `opencode-bifrost ${latest} is available (installed ${installed}). ` +
+      "Run `gateway-cli update` to refresh.",
+  );
+}
+
+export const BifrostGateway: Plugin = async ({ client, directory, $ }) => {
   async function cli(args: string[]): Promise<string | null> {
     try {
       const out = await $`${CLI} ${args}`.cwd(directory).quiet().text();
@@ -120,11 +263,20 @@ export const BifrostGateway: Plugin = async ({ directory, $ }) => {
 
   // Model discovery goes through the CLI, so the key is never needed here —
   // only auth.loader below, which must hand it to the SDK, sees it.
+  // The datasheet supplement adds wildcard-provider ids the CLI cannot list
+  // yet (feed Bifrost itself syncs from); CLI-listed ids always win.
+  // `directory` is the plugin's closure variable, not a parameter.
   async function listModels(): Promise<CliModels | null> {
     const raw = await cli(["models", "--wire=openai"]);
     if (!raw) return null;
     try {
-      return JSON.parse(raw) as CliModels;
+      const payload = JSON.parse(raw) as CliModels;
+      const cacheDir = datasheetCacheDir();
+      if (cacheDir) {
+        const extra = await datasheetSupplement(directory, cacheDir);
+        payload.models = mergeModels(payload.models ?? [], extra);
+      }
+      return payload;
     } catch {
       return null;
     }
@@ -136,11 +288,26 @@ export const BifrostGateway: Plugin = async ({ directory, $ }) => {
      * writes only to the in-memory config object.
      */
     config: async (cfg) => {
+      // Stale-plugin notice runs beside registration, never inside it.
+      void announceIfStale((message) => {
+        void client.app
+          .log({
+            body: {
+              service: "opencode-bifrost",
+              level: "warn",
+              message,
+            },
+          })
+          .catch(() => {});
+      }).catch(() => {});
+
       const info = await resolve();
       if (!info) return;
 
-      const providers = ((cfg as Record<string, any>).provider ??= {});
-      const existing = providers[PROVIDER_ID] ?? {};
+      const providers = ((
+        cfg as { provider?: Record<string, ProviderEntry> }
+      ).provider ??= {});
+      const existing: ProviderEntry = providers[PROVIDER_ID] ?? {};
       const models = toConfigModels(await listModels(), info.reasoning_effort);
 
       providers[PROVIDER_ID] = {
@@ -172,7 +339,14 @@ export const BifrostGateway: Plugin = async ({ directory, $ }) => {
         let apiKey = await readKey();
         if (!apiKey) {
           const stored = await getAuth().catch(() => undefined);
-          if (stored && stored.type === "api") apiKey = stored.key;
+          // OpenCode stores whatever was typed at the connect prompt with no
+          // validation; a stray non-Bifrost key must not reach the gateway.
+          if (
+            stored &&
+            stored.type === "api" &&
+            stored.key.startsWith("sk-bf-")
+          )
+            apiKey = stored.key;
         }
         if (!apiKey) return {};
         return {
@@ -188,24 +362,14 @@ export const BifrostGateway: Plugin = async ({ directory, $ }) => {
         {
           type: "api",
           label: "Bifrost Gateway (paste a virtual key from the dashboard)",
-          prompts: [
-            {
-              type: "text",
-              key: "key",
-              message: "Virtual key",
-              placeholder: "sk-bf-…",
-              validate: (value: string) =>
-                value.startsWith("sk-bf-")
-                  ? undefined
-                  : "Expected a Bifrost virtual key starting with sk-bf-",
-            },
-          ],
-          authorize: async (inputs?: Record<string, string>) => {
-            const key = inputs?.key?.trim();
-            if (!key || !key.startsWith("sk-bf-"))
-              return { type: "failed" as const };
-            return { type: "success" as const, key };
-          },
+          // No `prompts` and no `authorize`: OpenCode treats api-method
+          // prompts as extra metadata questions and then still asks for the
+          // key itself (dialog-provider.tsx renders PromptsMethod, then an
+          // unconditional ApiMethod prompt; the CLI adds its own password
+          // prompt before calling authorize with the prompt inputs only) —
+          // defining prompts made /connect ask for the key twice. The key is
+          // whatever the single prompt collects; a non-virtual-key value is
+          // rejected by the loader fallback below, not at login time.
         },
       ],
     },
@@ -226,6 +390,7 @@ export function toConfigModels(
   const out: Record<string, ConfigModel> = {};
   for (const m of payload?.models ?? []) {
     if (!m?.id) continue;
+    if (m.disabled) continue; // unavailable on this key: never offer it
     const efforts = m.reasoning_efforts ?? [];
     const entry: ConfigModel = {
       name: m.cost ? m.name : `${m.name}${UNPRICED_SUFFIX}`,