Merge pull request #71 from homanp/feat/add-free-models-via-openrouter

feat: add support for free models via openrouter

Author: homanp

.env.example

@@ -2,6 +2,7 @@
 # You can also enter keys directly in the UI (BYOK).
 
 # --- AI Providers (pick one or more) ---
+OPENROUTER_API_KEY=            # shared starter key (set in Railway and local .env)
 ANTHROPIC_API_KEY=
 OPENAI_API_KEY=
 GOOGLE_GENERATIVE_AI_API_KEY=
@@ -18,6 +19,13 @@ CEREBRAS_API_KEY=
 MOONSHOT_API_KEY=
 ALIBABA_API_KEY=
 
+# Optional OpenRouter headers / guardrails
+OPENROUTER_APP_URL=            # optional HTTP-Referer header for OpenRouter
+OPENROUTER_APP_NAME=           # optional X-Title header for OpenRouter
+OPENROUTER_STARTER_DISABLED=0  # set to 1 to disable shared starter access
+OPENROUTER_STARTER_RATE_LIMIT=30
+OPENROUTER_STARTER_WINDOW_MS=60000
+
 # --- Share / Publish ---
 DURABLE_STREAM_BASE_URL=    # defaults to https://stream.tonbo.dev
 SHARE_ID_SECRET=            # secret for deriving stable share IDs

src/app/api/chat/route.ts

@@ -2,6 +2,8 @@ import { streamText, stepCountIs, tool } from "ai";
 import { createMCPClient } from "@ai-sdk/mcp";
 import { z } from "zod";
 import { createModel, isAnthropicModel } from "@/lib/create-model";
+import { DEFAULT_MODEL } from "@/lib/model-registry";
+import { OpenRouterAccessError, resolveOpenRouterApiKey } from "@/lib/openrouter";
 import type { CustomApiConfig } from "@/store/settings-store";
 import { Bash } from "just-bash";
 import { createBashTool } from "bash-tool";
@@ -17,7 +19,6 @@ import {
 } from "@/db/widgets";
 import { webSearch, type SearchProvider } from "@/lib/web-search";
 import { scanUrls } from "@/lib/brin";
-import { nanoid } from "nanoid";
 import { maybeCreateTraceRecorder, publishDashboardStateForWidgetIfShared } from "@/lib/share-recorder";
 import type { SharedChatMessage } from "@/lib/share-types";
 
@@ -195,8 +196,21 @@ export async function POST(request: Request) {
   const traceRecorder = await maybeCreateTraceRecorder(widgetId).catch(() => null);
   traceRecorder?.startRun();
 
-  const selectedModel = modelStr ?? "anthropic:claude-sonnet-4-6";
+  const selectedModel = modelStr ?? DEFAULT_MODEL;
   const useAnthropic = isAnthropicModel(selectedModel);
+  let resolvedApiKey: string | undefined;
+
+  try {
+    resolvedApiKey = resolveOpenRouterApiKey(selectedModel, apiKey, request, {
+      route: "chat",
+      widgetId,
+    });
+  } catch (error) {
+    if (error instanceof OpenRouterAccessError) {
+      return Response.json({ error: error.message }, { status: error.status });
+    }
+    throw error;
+  }
 
   // Prepare custom API config if using a custom provider
   const customConfig: CustomApiConfig | undefined = customApi
@@ -360,7 +374,7 @@ export async function POST(request: Request) {
   }
 
   const result = streamText({
-    model: createModel(selectedModel, apiKey, customConfig),
+    model: createModel(selectedModel, resolvedApiKey, customConfig),
     system: SYSTEM_PROMPT,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     messages: messages as any,

src/app/api/generate-title/route.ts

@@ -1,5 +1,7 @@
 import { generateText } from "ai";
 import { createModel } from "@/lib/create-model";
+import { DEFAULT_MODEL } from "@/lib/model-registry";
+import { resolveOpenRouterApiKey } from "@/lib/openrouter";
 
 export async function POST(request: Request) {
   const { message, model, apiKey } = (await request.json()) as {
@@ -13,8 +15,13 @@ export async function POST(request: Request) {
   }
 
   try {
+    const selectedModel = model ?? DEFAULT_MODEL;
+    const resolvedApiKey = resolveOpenRouterApiKey(selectedModel, apiKey, request, {
+      route: "generate-title",
+    });
+
     const { text } = await generateText({
-      model: createModel(model ?? "anthropic:claude-haiku-4-5", apiKey),
+      model: createModel(selectedModel, resolvedApiKey),
       prompt: `Generate a short widget title (2-4 words max, no punctuation) for this request: "${message}". Reply with only the title, nothing else.`,
     });
 

src/app/page.tsx

@@ -1,11 +1,12 @@
-"use client";
-
 import { DashboardGrid } from "@/components/dashboard-grid";
 import { ChatSidebar } from "@/components/chat-sidebar";
 import { AddMenu } from "@/components/add-menu";
 import { DashboardPicker } from "@/components/dashboard-picker";
 import { ShareDashboardButton } from "@/components/share-dashboard-button";
 import { AppHeader } from "@/components/app-header";
+import { hasOpenRouterStarter } from "@/lib/openrouter";
+
+export const dynamic = "force-dynamic";
 
 export default function Home() {
   return (
@@ -18,7 +19,7 @@ export default function Home() {
         </AppHeader>
         <DashboardGrid />
       </div>
-      <ChatSidebar />
+      <ChatSidebar hasOpenRouterStarter={hasOpenRouterStarter()} />
     </div>
   );
 }

src/components/chat-sidebar.tsx

@@ -47,11 +47,13 @@ import { SearchProviderPicker } from "@/components/search-provider-picker";
 import { McpConfigDialog } from "@/components/mcp-config-dialog";
 import { CustomApiDialog } from "@/components/custom-api-dialog";
 import {
-  PROVIDERS,
+  getBuiltinProviders,
   parseModelString,
   createCustomProviderInfo,
   isCustomProvider,
   CUSTOM_PROVIDER_PREFIX,
+  OPENROUTER_PROVIDER_ID,
+  OPENROUTER_STARTER_MODELS,
 } from "@/lib/model-registry";
 import { Switch } from "@/components/ui/switch";
 
@@ -108,6 +110,7 @@ function KittLoader() {
 const abortControllers = new Map<string, AbortController>();
 const MAX_RETRIES = 2;
 const RETRY_DELAY_MS = 1500;
+const OPENROUTER_STARTER_MODEL_IDS = new Set(OPENROUTER_STARTER_MODELS.map((model) => model.id));
 
 function ReasoningBlock({
   text,
@@ -461,7 +464,7 @@ async function streamToWidget(
   }
 }
 
-function useModelSelector() {
+function useModelSelector({ hasOpenRouterStarter }: { hasOpenRouterStarter: boolean }) {
   const selectedModel = useSettingsStore((s) => s.selectedModel);
   const setModel = useSettingsStore((s) => s.setModel);
   const apiKeys = useSettingsStore((s) => s.apiKeys);
@@ -475,27 +478,43 @@ function useModelSelector() {
   const [customApiOpen, setCustomApiOpen] = useState(false);
 
   const { providerId, modelId } = parseModelString(selectedModel);
+  const hasOpenRouterByokKey = !!apiKeys[OPENROUTER_PROVIDER_ID];
 
   const allProviders = useMemo(() => {
+    const builtInProviders = getBuiltinProviders({
+      includeOpenRouterByokModels: hasOpenRouterByokKey,
+    });
     const customProviders = customApis
       .filter((c) => c.enabled)
       .map((c) => createCustomProviderInfo(c));
-    return [...PROVIDERS, ...customProviders];
-  }, [customApis]);
+    return [...builtInProviders, ...customProviders];
+  }, [customApis, hasOpenRouterByokKey]);
 
   const provider = allProviders.find((p) => p.id === providerId);
   const model = provider?.models.find((m) => m.id === modelId);
+  const isOpenRouterStarterModel = providerId === OPENROUTER_PROVIDER_ID
+    && OPENROUTER_STARTER_MODEL_IDS.has(modelId);
 
-  const hasKey = isCustomProvider(providerId)
+  const hasSavedKey = isCustomProvider(providerId)
     ? !!customApis.find((c) => `${CUSTOM_PROVIDER_PREFIX}${c.id}` === providerId)?.apiKey
     : !!apiKeys[providerId];
+  const hasStarterAccess = isOpenRouterStarterModel && hasOpenRouterStarter;
+  const hasAccess = hasSavedKey || hasStarterAccess;
+  const showOpenRouterStarterNotice = isOpenRouterStarterModel
+    && hasOpenRouterStarter
+    && !hasSavedKey
+    && !showKeyInput;
 
   const handleSelect = (newModel: string) => {
     setModel(newModel);
     setOpen(false);
-    const { providerId: pid } = parseModelString(newModel);
+    const { providerId: pid, modelId: nextModelId } = parseModelString(newModel);
+    const isStarterOpenRouterModel = pid === OPENROUTER_PROVIDER_ID
+      && OPENROUTER_STARTER_MODEL_IDS.has(nextModelId);
     if (isCustomProvider(pid)) {
       setShowKeyInput(false);
+    } else if (isStarterOpenRouterModel && hasOpenRouterStarter && !apiKeys[pid]) {
+      setShowKeyInput(false);
     } else if (!apiKeys[pid]) {
       setShowKeyInput(true);
     } else {
@@ -526,7 +545,7 @@ function useModelSelector() {
             <ModelSelectorLogo provider={providerId as "anthropic"} className="size-3.5" />
           )}
           <span>{model?.name ?? modelId}</span>
-          {!hasKey && !isCustomProvider(providerId) && (
+          {!hasAccess && !isCustomProvider(providerId) && (
             <span className="size-1.5 rounded-full bg-yellow-500/70 shrink-0" />
           )}
         </ModelSelectorTrigger>
@@ -549,6 +568,11 @@ function useModelSelector() {
                       <ModelSelectorLogo provider={p.id as "anthropic"} />
                     )}
                     <ModelSelectorName>{m.name}</ModelSelectorName>
+                    {p.id === OPENROUTER_PROVIDER_ID && OPENROUTER_STARTER_MODEL_IDS.has(m.id) && (
+                      <span className="shrink-0 border border-emerald-500/30 bg-emerald-500/10 px-1.5 py-0.5 text-[9px] uppercase tracking-wider text-emerald-300">
+                        Free
+                      </span>
+                    )}
                   </ModelSelectorItem>
                 ))}
               </ModelSelectorGroup>
@@ -595,30 +619,51 @@ function useModelSelector() {
     </>
   );
 
-  const keyInputEl = !isCustomProvider(providerId) && (showKeyInput || !hasKey) ? (
-    <div className="flex items-center gap-1.5">
-      <input
-        type="password"
-        value={keyInput}
-        onChange={(e) => setKeyInput(e.target.value)}
-        onKeyDown={(e) => e.key === "Enter" && handleSaveKey()}
-        placeholder={`${provider?.name ?? providerId} API key...`}
-        className="flex-1 bg-zinc-900 border border-zinc-800 text-xs px-2.5 py-1.5 text-zinc-300 placeholder:text-zinc-600 focus:outline-none focus:border-zinc-600"
-      />
-      <button
-        onClick={handleSaveKey}
-        className="px-2.5 py-1.5 text-xs uppercase tracking-wider bg-zinc-800 hover:bg-zinc-700 text-zinc-300 transition-colors"
-      >
-        Save
-      </button>
-    </div>
-  ) : null;
+  const shouldShowKeyInput = !isCustomProvider(providerId) && (showKeyInput || !hasAccess);
+
+  const keyInputEl = !isCustomProvider(providerId)
+    ? shouldShowKeyInput
+      ? (
+        <div className="flex items-center gap-1.5">
+          <input
+            type="password"
+            value={keyInput}
+            onChange={(e) => setKeyInput(e.target.value)}
+            onKeyDown={(e) => e.key === "Enter" && handleSaveKey()}
+            placeholder={`${provider?.name ?? providerId} API key...`}
+            className="flex-1 bg-zinc-900 border border-zinc-800 text-xs px-2.5 py-1.5 text-zinc-300 placeholder:text-zinc-600 focus:outline-none focus:border-zinc-600"
+          />
+          <button
+            onClick={handleSaveKey}
+            className="px-2.5 py-1.5 text-xs uppercase tracking-wider bg-zinc-800 hover:bg-zinc-700 text-zinc-300 transition-colors"
+          >
+            Save
+          </button>
+        </div>
+      )
+      : showOpenRouterStarterNotice
+        ? (
+          <div className="flex items-center justify-between gap-3 border border-zinc-800 bg-zinc-950 px-2.5 py-2 text-[11px] text-zinc-400">
+            <span>Starter OpenRouter models work out of the box. Add your own key to unlock frontier models.</span>
+            <button
+              type="button"
+              onClick={() => setShowKeyInput(true)}
+              className="shrink-0 px-2 py-1 text-[10px] uppercase tracking-wider bg-zinc-800 hover:bg-zinc-700 text-zinc-200 transition-colors"
+            >
+              Add key
+            </button>
+          </div>
+        )
+        : null
+    : null;
 
   return { trigger, keyInputEl };
 }
 
-export function ChatSidebar() {
-  const { trigger: modelTrigger, keyInputEl: modelKeyInput } = useModelSelector();
+export function ChatSidebar({ hasOpenRouterStarter = false }: { hasOpenRouterStarter?: boolean }) {
+  const { trigger: modelTrigger, keyInputEl: modelKeyInput } = useModelSelector({
+    hasOpenRouterStarter,
+  });
   const [mcpOpen, setMcpOpen] = useState(false);
   const mcpServers = useSettingsStore((s) => s.mcpServers);
   const enabledMcpCount = mcpServers.filter((s) => s.enabled).length;
@@ -643,10 +688,10 @@ export function ChatSidebar() {
     ? streamingWidgetIds.includes(activeWidgetId)
     : false;
 
-  const handleInterrupt = () => {
+  const handleInterrupt = useCallback(() => {
     if (!activeWidgetId) return;
     abortControllers.get(activeWidgetId)?.abort();
-  };
+  }, [activeWidgetId]);
 
   useEffect(() => {
     if (!isActiveStreaming) return;
@@ -655,7 +700,7 @@ export function ChatSidebar() {
     };
     document.addEventListener("keydown", onKey);
     return () => document.removeEventListener("keydown", onKey);
-  }, [isActiveStreaming, activeWidgetId]);
+  }, [handleInterrupt, isActiveStreaming]);
 
   const [input, setInput] = useState("");
   const [pendingFiles, setPendingFiles] = useState<PendingFile[]>([]);

src/lib/__tests__/create-model.test.ts

@@ -14,6 +14,7 @@ describe("isAnthropicModel", () => {
     expect(isAnthropicModel("openai:gpt-5.4")).toBe(false);
     expect(isAnthropicModel("google:gemini-2.5-pro")).toBe(false);
     expect(isAnthropicModel("xai:grok-3")).toBe(false);
+    expect(isAnthropicModel("openrouter:qwen/qwen3-coder:free")).toBe(false);
   });
 
   it("returns true for empty string (no colon)", () => {

src/lib/__tests__/model-registry.test.ts

@@ -4,6 +4,11 @@ import {
   ALL_MODELS,
   DEFAULT_MODEL,
   findProvider,
+  getBuiltinProviders,
+  OPENROUTER_BYOK_MODELS,
+  OPENROUTER_DEFAULT_STARTER_MODEL_ID,
+  OPENROUTER_PROVIDER_ID,
+  OPENROUTER_STARTER_MODELS,
   parseModelString,
 } from "@/lib/model-registry";
 
@@ -94,6 +99,49 @@ describe("PROVIDERS", () => {
     expect(modelIds.has("gpt-5.4-mini")).toBe(true);
     expect(modelIds.has("gpt-5.4-nano")).toBe(true);
   });
+
+  it("registers OpenRouter with starter and BYOK models", () => {
+    const openRouter = findProvider(OPENROUTER_PROVIDER_ID);
+    expect(openRouter).toBeDefined();
+
+    const modelIds = new Set(openRouter!.models.map((m) => m.id));
+    expect(modelIds.has("qwen/qwen3.6-plus-preview:free")).toBe(true);
+    expect(modelIds.has("nvidia/nemotron-3-super-120b-a12b:free")).toBe(true);
+    expect(modelIds.has("minimax/minimax-m2.5:free")).toBe(true);
+    expect(modelIds.has("qwen/qwen3-coder:free")).toBe(true);
+    expect(modelIds.has("z-ai/glm-4.5-air:free")).toBe(true);
+    expect(modelIds.has("anthropic/claude-sonnet-4.6")).toBe(true);
+  });
+});
+
+describe("getBuiltinProviders", () => {
+  it("limits OpenRouter to starter models without a BYOK key", () => {
+    const openRouter = getBuiltinProviders({
+      includeOpenRouterByokModels: false,
+    }).find((provider) => provider.id === OPENROUTER_PROVIDER_ID);
+
+    expect(openRouter).toBeDefined();
+    expect(openRouter!.models).toEqual(OPENROUTER_STARTER_MODELS);
+    expect(openRouter!.models.map((model) => model.id)).toEqual([
+      "qwen/qwen3.6-plus-preview:free",
+      "nvidia/nemotron-3-super-120b-a12b:free",
+      "minimax/minimax-m2.5:free",
+      "qwen/qwen3-coder:free",
+      "z-ai/glm-4.5-air:free",
+    ]);
+  });
+
+  it("includes the expanded OpenRouter catalog with a BYOK key", () => {
+    const openRouter = getBuiltinProviders({
+      includeOpenRouterByokModels: true,
+    }).find((provider) => provider.id === OPENROUTER_PROVIDER_ID);
+
+    expect(openRouter).toBeDefined();
+    expect(openRouter!.models).toEqual([
+      ...OPENROUTER_STARTER_MODELS,
+      ...OPENROUTER_BYOK_MODELS,
+    ]);
+  });
 });
 
 describe("ALL_MODELS", () => {
@@ -118,4 +166,8 @@ describe("DEFAULT_MODEL", () => {
     const model = provider!.models.find((m) => m.id === modelId);
     expect(model).toBeDefined();
   });
+
+  it("defaults new sessions to OpenRouter starter access", () => {
+    expect(DEFAULT_MODEL).toBe(`openrouter:${OPENROUTER_DEFAULT_STARTER_MODEL_ID}`);
+  });
 });