@stigmer/react 0.4.4 → 0.4.6

package/src/internal/__tests__/stream-controller.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { create } from "@bufbuild/protobuf";
 import {
   AgentExecutionSchema,
@@ -392,4 +392,50 @@ describe("StreamController", () => {
       expect(controller.state).toEqual({ stage: "idle" });
     });
   });
+
+  describe("default constructor (browser rAF binding)", () => {
+    let mockRaf: ReturnType<typeof vi.fn>;
+    let mockCaf: ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+      let nextId = 1;
+      mockRaf = vi.fn((cb: () => void) => {
+        const id = nextId++;
+        setTimeout(cb, 0);
+        return id;
+      });
+      mockCaf = vi.fn();
+
+      vi.stubGlobal("requestAnimationFrame", mockRaf);
+      vi.stubGlobal("cancelAnimationFrame", mockCaf);
+    });
+
+    afterEach(() => {
+      vi.unstubAllGlobals();
+    });
+
+    it("does not throw when using default scheduleFlush/cancelFlush", () => {
+      const defaultController = new StreamController(sink);
+      defaultController.start("exec-1");
+
+      expect(() => {
+        defaultController.handleSnapshot(
+          makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS),
+        );
+      }).not.toThrow();
+
+      expect(mockRaf).toHaveBeenCalledOnce();
+    });
+
+    it("delegates cancelFlush to cancelAnimationFrame", () => {
+      const defaultController = new StreamController(sink);
+      defaultController.start("exec-1");
+      defaultController.handleSnapshot(
+        makeSnapshot(ExecutionPhase.EXECUTION_IN_PROGRESS),
+      );
+      defaultController.reset();
+
+      expect(mockCaf).toHaveBeenCalledOnce();
+    });
+  });
 });

package/src/internal/stream-controller.ts

@@ -68,11 +68,11 @@ export class StreamController {
   constructor(
     sink: StreamControllerSink,
     scheduleFlush: (cb: () => void) => number = typeof requestAnimationFrame !== "undefined"
-      ? requestAnimationFrame
-      : (cb) => setTimeout(cb, 16) as unknown as number,
+      ? (cb: () => void) => requestAnimationFrame(cb)
+      : (cb: () => void) => setTimeout(cb, 16) as unknown as number,
     cancelFlush: (id: number) => void = typeof cancelAnimationFrame !== "undefined"
-      ? cancelAnimationFrame
-      : clearTimeout,
+      ? (id: number) => cancelAnimationFrame(id)
+      : (id: number) => clearTimeout(id),
   ) {
     this._sink = sink;
     this._scheduleFlush = scheduleFlush;

package/src/models/ModelRegistryContext.ts

@@ -0,0 +1,32 @@
+"use client";
+
+import { createContext, useContext } from "react";
+import type { ModelInfo } from "./registry";
+
+/** Internal state held by the model registry context provider. */
+export interface ModelRegistryState {
+  readonly models: readonly ModelInfo[];
+  readonly isLoading: boolean;
+  readonly error: Error | null;
+}
+
+/**
+ * React context that holds the model registry fetched from the public API.
+ *
+ * Populated by {@link StigmerProvider} on mount. Consumer hooks read from
+ * this context instead of a static JSON import, enabling always-fresh
+ * model data without npm package updates.
+ */
+export const ModelRegistryContext = createContext<ModelRegistryState>({
+  models: [],
+  isLoading: true,
+  error: null,
+});
+
+/**
+ * Internal hook to read the model registry from context.
+ * Throws if called outside a StigmerProvider.
+ */
+export function useModelRegistryContext(): ModelRegistryState {
+  return useContext(ModelRegistryContext);
+}

package/src/models/ModelSelector.tsx

@@ -122,7 +122,7 @@ export function ModelSelector({
     return HARNESS_OPTIONS.filter((h) => h === "native" || h === "cursor");
   }, [availableHarnesses]);
 
-  const selectedModel = (value ? getModel(value) : undefined) ?? defaultModel;
+  const selectedModel = (value ? getModel(value) : undefined) ?? defaultModel ?? undefined;
 
   const isSearching = searchQuery.length > 0;
   const lowerQuery = searchQuery.toLowerCase();
@@ -248,7 +248,7 @@ export function ModelSelector({
 
   const showShowAllButton = !isSearching && !showAll && featuredModels.length > 0 && featuredModels.length < models.length;
 
-  const triggerLabel = selectedModel.displayName;
+  const triggerLabel = selectedModel?.displayName ?? "Select model";
   const triggerHarness = !isHarnessLocked ? HARNESS_META[activeHarness].label : undefined;
 
   return (
@@ -393,7 +393,7 @@ export function ModelSelector({
                       <ModelRow
                         key={model.modelId}
                         model={model}
-                        isSelected={model.modelId === selectedModel.modelId}
+                        isSelected={model.modelId === selectedModel?.modelId}
                         showDescription={false}
                         showSpeedBadge={showSpeedBadge}
                         onClick={() => selectModel(model)}
@@ -406,7 +406,7 @@ export function ModelSelector({
                   <ModelRow
                     key={model.modelId}
                     model={model}
-                    isSelected={model.modelId === selectedModel.modelId}
+                    isSelected={model.modelId === selectedModel?.modelId}
                     isHighlighted={idx === highlightIdx}
                     showDescription={showDescriptions && !compact && !isSearching && !showAll}
                     showSpeedBadge={showSpeedBadge}

package/src/models/__tests__/useModelRegistry.test.tsx

@@ -1,45 +1,137 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi, beforeEach } from "vitest";
 import { renderHook } from "@testing-library/react";
+import { type ReactNode } from "react";
 import { useModelRegistry } from "../useModelRegistry";
 import {
-  MODEL_REGISTRY,
   DEFAULT_MODEL_ID,
   DEFAULT_CURSOR_MODEL_ID,
   DISABLED_PROVIDERS,
   modelKey,
+  parseRegistryJson,
 } from "../registry";
+import { ModelRegistryContext } from "../ModelRegistryContext";
+import type { ModelRegistryState } from "../ModelRegistryContext";
+import type { ModelInfo } from "../registry";
+
+/**
+ * Minimal inline registry data for tests. Mirrors the shape of the
+ * API response without depending on a static JSON file.
+ */
+const TEST_REGISTRY_JSON = {
+  models: [
+    {
+      id: "claude-sonnet-4.6",
+      displayName: "Claude Sonnet 4.6",
+      shortDescription: "Balanced capability",
+      speedTier: "fast",
+      provider: "anthropic",
+      harness: "native",
+      costTier: "standard",
+      featured: true,
+      pricing: { inputPricePerMillion: 3, outputPricePerMillion: 15, cacheWritePricePerMillion: 3.75, cacheReadPricePerMillion: 0.3 },
+    },
+    {
+      id: "claude-opus-4.6",
+      displayName: "Claude Opus 4.6",
+      shortDescription: "Complex reasoning",
+      speedTier: "slow",
+      provider: "anthropic",
+      harness: "native",
+      costTier: "premium",
+      featured: true,
+      pricing: { inputPricePerMillion: 5, outputPricePerMillion: 25, cacheWritePricePerMillion: 6.25, cacheReadPricePerMillion: 0.5 },
+    },
+    {
+      id: "gpt-4o",
+      displayName: "GPT-4o",
+      shortDescription: "Fast reasoning",
+      speedTier: "fast",
+      provider: "openai",
+      harness: "native",
+      costTier: "standard",
+      featured: true,
+      pricing: { inputPricePerMillion: 2.5, outputPricePerMillion: 10, cacheWritePricePerMillion: 2.5, cacheReadPricePerMillion: 1.25 },
+    },
+    {
+      id: "default",
+      displayName: "Cursor Auto",
+      shortDescription: "Automatic model selection",
+      speedTier: "fast",
+      provider: "cursor",
+      harness: "cursor",
+      costTier: "standard",
+      featured: true,
+      pricing: { inputPricePerMillion: 1.25, outputPricePerMillion: 6, cacheWritePricePerMillion: 1.25, cacheReadPricePerMillion: 0.25 },
+    },
+    {
+      id: "claude-4.6-sonnet",
+      displayName: "Claude 4.6 Sonnet",
+      shortDescription: "Balanced Cursor model",
+      speedTier: "fast",
+      provider: "anthropic",
+      harness: "cursor",
+      costTier: "standard",
+      featured: false,
+      pricing: { inputPricePerMillion: 3, outputPricePerMillion: 15, cacheWritePricePerMillion: 3.75, cacheReadPricePerMillion: 0.3 },
+    },
+    {
+      id: "ollama-local",
+      displayName: "Ollama Local",
+      shortDescription: "Local model",
+      speedTier: "fast",
+      provider: "ollama",
+      harness: "native",
+      costTier: "economy",
+      featured: false,
+      pricing: { inputPricePerMillion: 0, outputPricePerMillion: 0, cacheWritePricePerMillion: 0, cacheReadPricePerMillion: 0 },
+    },
+  ],
+};
+
+const TEST_MODELS: readonly ModelInfo[] = parseRegistryJson(TEST_REGISTRY_JSON);
+
+function createWrapper(models: readonly ModelInfo[] = TEST_MODELS) {
+  const state: ModelRegistryState = { models, isLoading: false, error: null };
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <ModelRegistryContext.Provider value={state}>
+        {children}
+      </ModelRegistryContext.Provider>
+    );
+  };
+}
 
 describe("useModelRegistry", () => {
   describe("unified mode (no harness)", () => {
     it("excludes DISABLED_PROVIDERS from models", () => {
-      const { result } = renderHook(() => useModelRegistry());
+      const { result } = renderHook(() => useModelRegistry(), { wrapper: createWrapper() });
       for (const model of result.current.models) {
         expect(DISABLED_PROVIDERS.has(model.provider)).toBe(false);
       }
     });
 
     it("includes models from both native and cursor harnesses", () => {
-      const { result } = renderHook(() => useModelRegistry());
+      const { result } = renderHook(() => useModelRegistry(), { wrapper: createWrapper() });
       const harnesses = new Set(result.current.models.map((m) => m.harness));
       expect(harnesses.has("native")).toBe(true);
       expect(harnesses.has("cursor")).toBe(true);
     });
 
-    it("includes all non-disabled models from MODEL_REGISTRY", () => {
-      const { result } = renderHook(() => useModelRegistry());
-      const expected = MODEL_REGISTRY.filter(
+    it("includes all non-disabled models", () => {
+      const { result } = renderHook(() => useModelRegistry(), { wrapper: createWrapper() });
+      const expected = TEST_MODELS.filter(
         (m) => !DISABLED_PROVIDERS.has(m.provider),
       );
       expect(result.current.models).toHaveLength(expected.length);
     });
 
     it("resolves defaultModel to DEFAULT_MODEL_ID", () => {
-      const { result } = renderHook(() => useModelRegistry());
-      expect(result.current.defaultModel.modelId).toBe(DEFAULT_MODEL_ID);
+      const { result } = renderHook(() => useModelRegistry(), { wrapper: createWrapper() });
+      expect(result.current.defaultModel!.modelId).toBe(DEFAULT_MODEL_ID);
     });
 
     it("groups models by provider in byProvider map", () => {
-      const { result } = renderHook(() => useModelRegistry());
+      const { result } = renderHook(() => useModelRegistry(), { wrapper: createWrapper() });
       for (const [provider, models] of result.current.byProvider) {
         for (const m of models) {
           expect(m.provider).toBe(provider);
@@ -48,21 +140,21 @@ describe("useModelRegistry", () => {
     });
 
     it("returns providers matching byProvider keys in order", () => {
-      const { result } = renderHook(() => useModelRegistry());
+      const { result } = renderHook(() => useModelRegistry(), { wrapper: createWrapper() });
       const fromMap = Array.from(result.current.byProvider.keys());
       expect(result.current.providers).toEqual(fromMap);
     });
 
     it("looks up enabled models by getModel", () => {
-      const { result } = renderHook(() => useModelRegistry());
+      const { result } = renderHook(() => useModelRegistry(), { wrapper: createWrapper() });
       const model = result.current.getModel(DEFAULT_MODEL_ID);
       expect(model).toBeDefined();
       expect(model!.modelId).toBe(DEFAULT_MODEL_ID);
     });
 
     it("returns undefined for disabled provider models via getModel", () => {
-      const { result } = renderHook(() => useModelRegistry());
-      const disabledModel = MODEL_REGISTRY.find((m) =>
+      const { result } = renderHook(() => useModelRegistry(), { wrapper: createWrapper() });
+      const disabledModel = TEST_MODELS.find((m) =>
         DISABLED_PROVIDERS.has(m.provider),
       );
       if (disabledModel) {
@@ -71,12 +163,12 @@ describe("useModelRegistry", () => {
     });
 
     it("returns undefined for unknown model IDs via getModel", () => {
-      const { result } = renderHook(() => useModelRegistry());
+      const { result } = renderHook(() => useModelRegistry(), { wrapper: createWrapper() });
       expect(result.current.getModel("nonexistent-model")).toBeUndefined();
     });
 
     it("returns featured models subset", () => {
-      const { result } = renderHook(() => useModelRegistry());
+      const { result } = renderHook(() => useModelRegistry(), { wrapper: createWrapper() });
       expect(result.current.featured.length).toBeGreaterThan(0);
       for (const model of result.current.featured) {
         expect(model.featured).toBe(true);
@@ -84,7 +176,7 @@ describe("useModelRegistry", () => {
     });
 
     it("featured models are a subset of all models", () => {
-      const { result } = renderHook(() => useModelRegistry());
+      const { result } = renderHook(() => useModelRegistry(), { wrapper: createWrapper() });
       const allKeys = new Set(
         result.current.models.map((m) => modelKey(m.harness, m.modelId)),
       );
@@ -94,7 +186,7 @@ describe("useModelRegistry", () => {
     });
 
     it("resolves models by compound key via getByKey", () => {
-      const { result } = renderHook(() => useModelRegistry());
+      const { result } = renderHook(() => useModelRegistry(), { wrapper: createWrapper() });
       const key = modelKey("native", DEFAULT_MODEL_ID);
       const model = result.current.getByKey(key);
       expect(model).toBeDefined();
@@ -103,7 +195,7 @@ describe("useModelRegistry", () => {
     });
 
     it("resolves cursor models by compound key via getByKey", () => {
-      const { result } = renderHook(() => useModelRegistry());
+      const { result } = renderHook(() => useModelRegistry(), { wrapper: createWrapper() });
       const key = modelKey("cursor", DEFAULT_CURSOR_MODEL_ID);
       const model = result.current.getByKey(key);
       expect(model).toBeDefined();
@@ -112,7 +204,7 @@ describe("useModelRegistry", () => {
     });
 
     it("returns undefined for unknown compound keys via getByKey", () => {
-      const { result } = renderHook(() => useModelRegistry());
+      const { result } = renderHook(() => useModelRegistry(), { wrapper: createWrapper() });
       expect(result.current.getByKey("native/nonexistent")).toBeUndefined();
     });
   });
@@ -121,7 +213,7 @@ describe("useModelRegistry", () => {
     it("shows only native-harness models", () => {
       const { result } = renderHook(() =>
         useModelRegistry({ harness: "native" }),
-      );
+      { wrapper: createWrapper() });
       for (const model of result.current.models) {
         expect(model.harness).toBe("native");
       }
@@ -130,7 +222,7 @@ describe("useModelRegistry", () => {
     it("excludes cursor-harness models", () => {
       const { result } = renderHook(() =>
         useModelRegistry({ harness: "native" }),
-      );
+      { wrapper: createWrapper() });
       const cursorModels = result.current.models.filter(
         (m) => m.harness === "cursor",
       );
@@ -140,10 +232,10 @@ describe("useModelRegistry", () => {
     it("resolves defaultModel to the first featured native model", () => {
       const { result } = renderHook(() =>
         useModelRegistry({ harness: "native" }),
-      );
+      { wrapper: createWrapper() });
       const featured = result.current.featured;
       expect(featured.length).toBeGreaterThan(0);
-      expect(result.current.defaultModel.modelId).toBe(featured[0].modelId);
+      expect(result.current.defaultModel!.modelId).toBe(featured[0].modelId);
     });
   });
 
@@ -151,7 +243,7 @@ describe("useModelRegistry", () => {
     it("shows only cursor-harness models", () => {
       const { result } = renderHook(() =>
         useModelRegistry({ harness: "cursor" }),
-      );
+      { wrapper: createWrapper() });
       for (const model of result.current.models) {
         expect(model.harness).toBe("cursor");
       }
@@ -160,26 +252,16 @@ describe("useModelRegistry", () => {
     it("includes cursor-harness models from multiple providers", () => {
       const { result } = renderHook(() =>
         useModelRegistry({ harness: "cursor" }),
-      );
+      { wrapper: createWrapper() });
       const providers = new Set(result.current.models.map((m) => m.provider));
       expect(providers.size).toBeGreaterThan(1);
     });
 
-    it("includes all cursor-harness models from MODEL_REGISTRY", () => {
-      const { result } = renderHook(() =>
-        useModelRegistry({ harness: "cursor" }),
-      );
-      const cursorModels = MODEL_REGISTRY.filter(
-        (m) => m.harness === "cursor",
-      );
-      expect(result.current.models).toHaveLength(cursorModels.length);
-    });
-
     it("resolves defaultModel to DEFAULT_CURSOR_MODEL_ID", () => {
       const { result } = renderHook(() =>
         useModelRegistry({ harness: "cursor" }),
-      );
-      expect(result.current.defaultModel.modelId).toBe(
+      { wrapper: createWrapper() });
+      expect(result.current.defaultModel!.modelId).toBe(
         DEFAULT_CURSOR_MODEL_ID,
       );
     });
@@ -187,7 +269,7 @@ describe("useModelRegistry", () => {
     it("looks up cursor models via getModel", () => {
       const { result } = renderHook(() =>
         useModelRegistry({ harness: "cursor" }),
-      );
+      { wrapper: createWrapper() });
       expect(
         result.current.getModel(DEFAULT_CURSOR_MODEL_ID),
       ).toBeDefined();
@@ -196,14 +278,41 @@ describe("useModelRegistry", () => {
     it("cannot look up native-only models via getModel", () => {
       const { result } = renderHook(() =>
         useModelRegistry({ harness: "cursor" }),
-      );
+      { wrapper: createWrapper() });
       expect(result.current.getModel(DEFAULT_MODEL_ID)).toBeUndefined();
     });
   });
 
+  describe("loading state", () => {
+    it("exposes isLoading from context", () => {
+      const loadingState: ModelRegistryState = { models: [], isLoading: true, error: null };
+      const wrapper = ({ children }: { children: ReactNode }) => (
+        <ModelRegistryContext.Provider value={loadingState}>
+          {children}
+        </ModelRegistryContext.Provider>
+      );
+      const { result } = renderHook(() => useModelRegistry(), { wrapper });
+      expect(result.current.isLoading).toBe(true);
+      expect(result.current.models).toHaveLength(0);
+    });
+
+    it("exposes error from context", () => {
+      const err = new Error("fetch failed");
+      const errorState: ModelRegistryState = { models: [], isLoading: false, error: err };
+      const wrapper = ({ children }: { children: ReactNode }) => (
+        <ModelRegistryContext.Provider value={errorState}>
+          {children}
+        </ModelRegistryContext.Provider>
+      );
+      const { result } = renderHook(() => useModelRegistry(), { wrapper });
+      expect(result.current.error).toBe(err);
+      expect(result.current.isLoading).toBe(false);
+    });
+  });
+
   describe("defaultModel fallback", () => {
     it("falls back to the first enabled model when default ID is missing", () => {
-      const { result } = renderHook(() => useModelRegistry());
+      const { result } = renderHook(() => useModelRegistry(), { wrapper: createWrapper() });
       expect(result.current.defaultModel).toBeDefined();
       expect(result.current.models).toContain(result.current.defaultModel);
     });

package/src/models/index.ts

@@ -1,8 +1,10 @@
-export { MODEL_REGISTRY, DEFAULT_MODEL_ID, DEFAULT_CURSOR_MODEL_ID, DISABLED_PROVIDERS, modelKey, parseModelKey, resolveDefaultModelId } from "./registry";
+export { DEFAULT_MODEL_ID, DEFAULT_CURSOR_MODEL_ID, DISABLED_PROVIDERS, modelKey, parseModelKey, resolveDefaultModelId, fetchModelRegistry, parseRegistryJson } from "./registry";
 export type { ParsedModelKey, DefaultModelResolution, DefaultModelSource } from "./registry";
 export type { ModelInfo, Provider, CostTier, SpeedTier } from "./registry";
 export { useModelRegistry } from "./useModelRegistry";
 export type { UseModelRegistryReturn, UseModelRegistryOptions } from "./useModelRegistry";
+export { ModelRegistryContext, useModelRegistryContext } from "./ModelRegistryContext";
+export type { ModelRegistryState } from "./ModelRegistryContext";
 export { ModelSelector } from "./ModelSelector";
 export type { ModelSelectorProps } from "./ModelSelector";
 export { HarnessSelector } from "./HarnessSelector";

package/src/models/registry.ts

@@ -1,15 +1,15 @@
 /**
  * Model registry — UI-relevant metadata for all platform-supported LLM models.
  *
- * Reads from the unified JSON registry at backend/libs/model-registry.json,
- * which is the single source of truth for model IDs, display names, pricing,
- * and cost tiers across all harnesses and runtimes.
+ * Fetches from the public model registry API endpoint at runtime and caches
+ * the result in the {@link StigmerProvider} context. This eliminates the
+ * static JSON file that previously shipped in the npm package.
  *
- * Update it with: @update-model-registry
+ * Platform consumers (React SDK, cursor-runner, graphton) all fetch from the
+ * same endpoint, each with their own local TTL cache.
  */
 
 import type { HarnessOption } from "./harness";
-import registryData from "../../data/model-registry.json";
 
 /**
  * Pricing bracket for a model.
@@ -33,7 +33,7 @@ export type SpeedTier = "fastest" | "fast" | "balanced" | "slow";
 /**
  * LLM provider identifier. Each provider maps to a distinct inference
  * backend (or intermediary, in the case of Cursor-served third-party
- * models). The {@link MODEL_REGISTRY} uses this for grouping in the
+ * models). The model registry uses this for grouping in the
  * "Show All" expanded view.
  */
 export type Provider =
@@ -48,7 +48,7 @@ export type Provider =
 /**
  * Providers whose models should be hidden from the UI.
  *
- * The model entries themselves stay in MODEL_REGISTRY so backend
+ * The model entries themselves stay in the registry so backend
  * compatibility is preserved. The useModelRegistry hook filters
  * them out before anything reaches a component.
  *
@@ -171,26 +171,47 @@ function isModelEntry(entry: RegistryJsonEntry): entry is Required<Pick<Registry
 }
 
 /**
- * Static catalog of all platform-supported LLM models, loaded from the
- * unified JSON registry.
+ * Parse raw registry JSON (from the API or a static file) into `ModelInfo[]`.
  *
- * {@link useModelRegistry} filters out disabled providers and provides
- * lookup helpers on top of this list.
+ * Expects the shape `{ models: RegistryJsonEntry[] }`. Filters out comment
+ * entries and invalid rows, then maps to the `ModelInfo` interface.
  */
-export const MODEL_REGISTRY: readonly ModelInfo[] = (
-  registryData.models as RegistryJsonEntry[]
-)
-  .filter(isModelEntry)
-  .map((m) => ({
-    modelId: m.id,
-    provider: m.provider as Provider,
-    displayName: m.displayName,
-    shortDescription: m.shortDescription ?? "",
-    speedTier: (VALID_SPEED_TIERS.has(m.speedTier ?? "") ? m.speedTier : "fast") as SpeedTier,
-    costTier: m.costTier as CostTier,
-    harness: m.harness as HarnessOption,
-    featured: m.featured ?? false,
-  }));
+export function parseRegistryJson(data: unknown): ModelInfo[] {
+  if (!data || typeof data !== "object") return [];
+  const models = (data as Record<string, unknown>).models;
+  if (!Array.isArray(models)) return [];
+
+  return (models as RegistryJsonEntry[])
+    .filter(isModelEntry)
+    .map((m) => ({
+      modelId: m.id,
+      provider: m.provider as Provider,
+      displayName: m.displayName,
+      shortDescription: m.shortDescription ?? "",
+      speedTier: (VALID_SPEED_TIERS.has(m.speedTier ?? "") ? m.speedTier : "fast") as SpeedTier,
+      costTier: m.costTier as CostTier,
+      harness: m.harness as HarnessOption,
+      featured: m.featured ?? false,
+    }));
+}
+
+/**
+ * Fetch the model registry from the authenticated API endpoint.
+ *
+ * @param apiUrl - Base URL of the Stigmer Cloud API (e.g. `https://api.stigmer.ai`)
+ * @param token - Bearer token for authentication (from `client.getAuthCredential()`)
+ * @returns Parsed `ModelInfo[]`.
+ */
+export async function fetchModelRegistry(apiUrl: string, token: string | null): Promise<ModelInfo[]> {
+  const headers: Record<string, string> = {};
+  if (token) {
+    headers["Authorization"] = `Bearer ${token}`;
+  }
+  const res = await fetch(`${apiUrl}/v1/proxy/model-registry`, { headers });
+  if (!res.ok) throw new Error(`Model registry fetch failed: ${res.status}`);
+  const data: unknown = await res.json();
+  return parseRegistryJson(data);
+}
 
 /**
  * Model ID used when no user preference is set (native harness).
@@ -236,6 +257,7 @@ export interface DefaultModelResolution {
  */
 export function resolveDefaultModelId(
   harness: HarnessOption,
+  models: readonly ModelInfo[],
   options?: {
     userPreference?: string;
     orgDefault?: string;
@@ -243,27 +265,27 @@ export function resolveDefaultModelId(
   },
 ): DefaultModelResolution {
   if (options?.userPreference) {
-    const model = MODEL_REGISTRY.find(
+    const model = models.find(
       (m) => m.harness === harness && m.modelId === options.userPreference,
     );
     if (model) return { modelId: model.modelId, source: "user_preference" };
   }
 
   if (options?.orgDefault) {
-    const model = MODEL_REGISTRY.find(
+    const model = models.find(
       (m) => m.harness === harness && m.modelId === options.orgDefault,
     );
     if (model) return { modelId: model.modelId, source: "org_default" };
   }
 
   if (options?.agentDefault) {
-    const model = MODEL_REGISTRY.find(
+    const model = models.find(
       (m) => m.harness === harness && m.modelId === options.agentDefault,
     );
     if (model) return { modelId: model.modelId, source: "agent_default" };
   }
 
-  const featured = MODEL_REGISTRY.find(
+  const featured = models.find(
     (m) => m.harness === harness && m.featured,
   );
   if (featured) return { modelId: featured.modelId, source: "harness_default" };
@@ -271,4 +293,3 @@ export function resolveDefaultModelId(
   const fallbackId = harness === "cursor" ? DEFAULT_CURSOR_MODEL_ID : DEFAULT_MODEL_ID;
   return { modelId: fallbackId, source: "platform_fallback" };
 }
-