refactor!(llm): Remove bootstrapper in favor of setup-provider

.codegraph/.gitignore

@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore

.github/workflows/deploy-docs.yml

@@ -5,9 +5,9 @@ on:
     branches:
       - master
     paths:
-      - 'web/docs/**'
-      - 'pnpm-lock.yaml'
-      - '.github/workflows/deploy-docs.yml'
+      - "web/docs/**"
+      - "pnpm-lock.yaml"
+      - ".github/workflows/deploy-docs.yml"
   workflow_dispatch:
 
 jobs:
@@ -28,7 +28,7 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 22
-          cache: 'pnpm'
+          cache: "pnpm"
 
       - name: Install Dependencies
         run: pnpm install --frozen-lockfile
@@ -41,4 +41,4 @@ jobs:
         with:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          workingDirectory: 'web/docs'
+          workingDirectory: "web/docs"

README.md

@@ -17,7 +17,7 @@
 The <b>world state lives outside the model</b>, characters act through <b>intents that get validated</b> and applied by engine code. Each character's knowledge, memory, and emotional state are subjective and partial by construction.
 
 <p align="center">
-  <img src="./web/docs/src/assets/img/puppet.webp" />
+  <img src="./web/docs/src/assets/img/puppet.webp" alt="This pixel-art style image, set against a black background with the title 'The Puppet Master Paradox' at the top, depicts two identical, stylized puppets with white, round heads and orange patterned bodies facing each other. Between them hovers a small, glowing, four-pointed star, while each puppet has an orange-outlined speech bubble above it: the left one states, 'Good evening. Welcome to my humble bakery!', and the right one replies, 'Nice to meet you Assassin Bob. Wait... wha-', concluding with a small white 'X' icon in the bottom right corner." />
 </p>
 
 Single-agent or single-context systems (AI Dungeon and its descendants) prompt one model to _be_ the world and everyone in it. That breaks in predictable ways over long sessions:
@@ -41,7 +41,7 @@ Omnia answers every one of these failures with the same move: **pull the thing t
 ## What this buys you
 
 <p align="center">
-  <img src="./web/docs/src/assets/img/features.webp" />
+  <img src="./web/docs/src/assets/img/features.webp" alt="This pixel-art image features a grid of six distinct panels, each with an orange-outlined, jagged border, illustrating different concepts: 'Emergent Deceit' shows a person hiding a sword behind their back while offering a rose to another person; 'Divergent Perceptions' depicts two figures sitting at a table with speech bubbles labeled 'A' and 'B'; 'Player Agnostic' shows three figures engaged in different activities—watering a plant, standing still, and juggling—under the plumbob symbol from the sims; 'State Validated Agency' displays a stylized symbol of a person partially inside a portal crossed out by a large red 'X'; 'Deterministic Time' shows four circular panels representing a day-night cycle connected by arrows and clock icons; and 'Bring Your Own Model' features a large, central omnia icon surrounded by various LLM model logos including chatgpt, mistral, deepseek, claude, etc****" />
 </p>
 
 The payoff is scenario complexity that **uni-agent systems structurally cannot represent, no matter how good the model gets**.

apps/gui/src/app/actions.ts

@@ -4,7 +4,14 @@ import path from "path";
 import fs from "fs";
 import { simulationManager } from "@/lib/simulation";
 import type { SimSnapshot } from "@/lib/simulation";
-import { ProviderManager, ModelProviderInstance, AVAILABLE_PROVIDERS, ModelProviderMeta } from "@omnia/llm";
+import {
+  ProviderManager,
+  ModelProviderInstance,
+  getAvailableProviders as listAvailableProviders,
+  ModelProviderMeta,
+  ModelLister,
+  ModelInfo,
+} from "@omnia/llm";
 
 function resolveScenarioPath(relative: string): string {
   const cwd = process.cwd();
@@ -25,8 +32,7 @@ function resolveScenarioPath(relative: string): string {
 }
 
 type ActionResult =
-  | { ok: true; snapshot: SimSnapshot }
-  | { ok: false; error: string };
+  { ok: true; snapshot: SimSnapshot } | { ok: false; error: string };
 
 export async function startSimulation(input: {
   scenario?: string;
@@ -168,8 +174,7 @@ export async function getConfigStatus(): Promise<{
 }
 
 export async function listSavedSimulations(): Promise<
-  | { ok: true; sessions: SimSnapshot[] }
-  | { ok: false; error: string }
+  { ok: true; sessions: SimSnapshot[] } | { ok: false; error: string }
 > {
   try {
     const sessions = simulationManager.listSavedSessions();
@@ -197,7 +202,9 @@ export async function resumeSimulation(simId: string): Promise<ActionResult> {
   }
 }
 
-export async function getScenarioEntities(scenarioPath: string): Promise<
+export async function getScenarioEntities(
+  scenarioPath: string,
+): Promise<
   | { ok: true; entities: { id: string; name: string }[] }
   | { ok: false; error: string }
 > {
@@ -207,10 +214,12 @@ export async function getScenarioEntities(scenarioPath: string): Promise<
       return { ok: false, error: `Scenario file not found: ${scenarioPath}` };
     }
     const content = JSON.parse(fs.readFileSync(resolved, "utf-8"));
-    const entities = (content.entities || []).map((e: { id: string; name?: string }) => ({
-      id: e.id,
-      name: e.name || e.id,
-    }));
+    const entities = (content.entities || []).map(
+      (e: { id: string; name?: string }) => ({
+        id: e.id,
+        name: e.name || e.id,
+      }),
+    );
     return { ok: true, entities };
   } catch (err) {
     return {
@@ -220,9 +229,9 @@ export async function getScenarioEntities(scenarioPath: string): Promise<
   }
 }
 
-export async function deleteSimulation(simId: string): Promise<
-  { ok: true } | { ok: false; error: string }
-> {
+export async function deleteSimulation(
+  simId: string,
+): Promise<{ ok: true } | { ok: false; error: string }> {
   try {
     simulationManager.deleteSession(simId);
     return { ok: true };
@@ -234,7 +243,9 @@ export async function deleteSimulation(simId: string): Promise<
   }
 }
 
-export async function listProviderInstances(): Promise<ModelProviderInstance[]> {
+export async function listProviderInstances(): Promise<
+  ModelProviderInstance[]
+> {
   return ProviderManager.list();
 }
 
@@ -245,8 +256,17 @@ export async function createProviderInstance(
   modelName?: string,
   type: "generative" | "embedding" = "generative",
   maxContext?: number,
+  endpointUrl?: string,
 ): Promise<ModelProviderInstance> {
-  return ProviderManager.create(name, providerName, apiKey, modelName, type, maxContext);
+  return ProviderManager.create(
+    name,
+    providerName,
+    apiKey,
+    modelName,
+    type,
+    maxContext,
+    endpointUrl,
+  );
 }
 
 export async function deleteProviderInstance(id: string): Promise<void> {
@@ -265,8 +285,18 @@ export async function updateProviderInstance(
   modelName?: string,
   type: "generative" | "embedding" = "generative",
   maxContext?: number,
+  endpointUrl?: string,
 ): Promise<void> {
-  ProviderManager.update(id, name, providerName, apiKey, modelName, type, maxContext);
+  ProviderManager.update(
+    id,
+    name,
+    providerName,
+    apiKey,
+    modelName,
+    type,
+    maxContext,
+    endpointUrl,
+  );
 }
 
 export async function getProviderMappings(): Promise<Record<string, string>> {
@@ -281,9 +311,40 @@ export async function setProviderMapping(
 }
 
 export async function getAvailableProviders(): Promise<ModelProviderMeta[]> {
-  return AVAILABLE_PROVIDERS;
+  return listAvailableProviders();
 }
 
-export async function regenerateEmbeddings(newProviderInstanceId?: string): Promise<void> {
+export async function regenerateEmbeddings(
+  newProviderInstanceId?: string,
+): Promise<void> {
   await simulationManager.regenerateAllEmbeddings(newProviderInstanceId);
 }
+
+/**
+ * Fetch available models for a provider given its credentials.
+ * Used when creating a new instance (before it's saved to the DB).
+ */
+export async function fetchAvailableModels(
+  providerName: string,
+  apiKey: string,
+  endpointUrl?: string,
+): Promise<ModelInfo[]> {
+  return ModelLister.listModels(providerName, apiKey, endpointUrl);
+}
+
+/**
+ * Fetch available models for an existing saved provider instance.
+ * The API key is retrieved from the DB server-side — never sent to the client.
+ */
+export async function fetchAvailableModelsForInstance(
+  instanceId: string,
+): Promise<ModelInfo[]> {
+  const instances = ProviderManager.list();
+  const inst = instances.find((i) => i.id === instanceId);
+  if (!inst) return [];
+  return ModelLister.listModels(
+    inst.providerName,
+    inst.apiKey,
+    inst.endpointUrl,
+  );
+}

apps/gui/src/app/builder/page.tsx

@@ -1,16 +1,5 @@
-"use client";
+import { BuilderView } from "@/components/builder/BuilderView";
 
 export default function BuilderPage() {
-  return (
-    <div className="flex-1 overflow-y-auto w-full">
-      <div className="mx-auto max-w-[800px] px-10 py-12">
-        <h1 className="mb-6 text-headline-lg text-primary animate-fade-in">Scenario Builder</h1>
-        <div className="border border-border/30 bg-card p-6 shadow-[2px_2px_0_0_var(--border)] min-h-[300px] flex flex-col items-center justify-center">
-          <p className="text-body-md text-muted-foreground font-mono text-center">
-            Scenario builder interface coming soon...
-          </p>
-        </div>
-      </div>
-    </div>
-  );
+  return <BuilderView />;
 }

apps/gui/src/app/page.tsx

@@ -1,5 +1,5 @@
-import { DashboardView } from "@/components/play/DashboardView";
+import { HomeView } from "@/components/home/HomeView";
 
 export default function Home() {
-  return <DashboardView />;
+  return <HomeView />;
 }

apps/gui/src/app/play/page.tsx

@@ -5,11 +5,13 @@ import { Suspense } from "react";
 
 export default function PlayPage() {
   return (
-    <Suspense fallback={
-      <div className="flex items-center justify-center min-h-[400px]">
-        <div className="animate-spin text-primary">Loading...</div>
-      </div>
-    }>
+    <Suspense
+      fallback={
+        <div className="flex items-center justify-center min-h-[400px]">
+          <div className="animate-spin text-primary">Loading...</div>
+        </div>
+      }
+    >
       <PlayView />
     </Suspense>
   );

apps/gui/src/components/builder/BuilderView.tsx

@@ -0,0 +1,18 @@
+"use client";
+
+export function BuilderView() {
+  return (
+    <div className="flex-1 overflow-y-auto w-full">
+      <div className="mx-auto max-w-[800px] px-10 py-12">
+        <h1 className="mb-6 text-headline-lg text-primary animate-fade-in">
+          Scenario Builder
+        </h1>
+        <div className="border border-border/30 bg-card p-6 shadow-[2px_2px_0_0_var(--border)] min-h-[300px] flex flex-col items-center justify-center">
+          <p className="text-body-md text-muted-foreground font-mono text-center">
+            Scenario builder interface coming soon...
+          </p>
+        </div>
+      </div>
+    </div>
+  );
+}

apps/gui/src/components/config/ConfigView.tsx

@@ -224,7 +224,8 @@ export function ConfigView() {
                           </SelectItem>
                           {instances
                             .filter(
-                              (inst) => (inst.type || "generative") === task.type,
+                              (inst) =>
+                                (inst.type || "generative") === task.type,
                             )
                             .map((inst) => (
                               <SelectItem key={inst.id} value={inst.id}>

apps/gui/src/components/config/ProviderInstancesConfig.tsx

@@ -1,14 +1,20 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import {
   createProviderInstance,
   updateProviderInstance,
   setActiveProviderInstance,
   regenerateEmbeddings,
   deleteProviderInstance,
+  fetchAvailableModels,
+  fetchAvailableModelsForInstance,
 } from "@/app/actions";
-import type { ModelProviderInstance, ModelProviderMeta } from "@omnia/llm";
+import type {
+  ModelInfo,
+  ModelProviderInstance,
+  ModelProviderMeta,
+} from "@omnia/llm";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
@@ -22,6 +28,14 @@ import {
   SelectTrigger,
   SelectValue,
 } from "@/components/ui/select";
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxList,
+} from "@/components/ui/combobox";
 import {
   Card,
   CardHeader,
@@ -38,6 +52,7 @@ import {
 } from "@/components/ui/item";
 import { Empty, EmptyTitle, EmptyDescription } from "@/components/ui/empty";
 import { cn } from "@/lib/utils";
+import { RefreshCwIcon } from "lucide-react";
 
 interface ProviderInstancesConfigProps {
   instances: ModelProviderInstance[];
@@ -64,9 +79,65 @@ export function ProviderInstancesConfig({
     "generative",
   );
   const [editMaxContext, setEditMaxContext] = useState<number>(32768);
+  const [editEndpointUrl, setEditEndpointUrl] = useState("");
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState("");
 
+  // Model listing state
+  const [availableModels, setAvailableModels] = useState<ModelInfo[]>([]);
+  const [modelsLoading, setModelsLoading] = useState(false);
+  const debounceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Fetch models for an existing saved instance
+  const fetchModelsForExistingInstance = async (instanceId: string) => {
+    setModelsLoading(true);
+    setAvailableModels([]);
+    try {
+      const models = await fetchAvailableModelsForInstance(instanceId);
+      setAvailableModels(models);
+    } catch {
+      setAvailableModels([]);
+    } finally {
+      setModelsLoading(false);
+    }
+  };
+
+  // Fetch models for a new instance (using live key/endpoint from form)
+  const fetchModelsForNewInstance = (
+    provider: string,
+    apiKey: string,
+    endpointUrl: string,
+  ) => {
+    if (debounceTimer.current) clearTimeout(debounceTimer.current);
+
+    const isOllama = provider === "ollama";
+    const hasCredentials = isOllama
+      ? endpointUrl.trim().length > 0
+      : apiKey.trim().length > 8; // don't spam API with partial keys
+
+    if (!hasCredentials) {
+      setAvailableModels([]);
+      return;
+    }
+
+    debounceTimer.current = setTimeout(async () => {
+      setModelsLoading(true);
+      setAvailableModels([]);
+      try {
+        const models = await fetchAvailableModels(
+          provider,
+          isOllama ? "none" : apiKey,
+          isOllama ? endpointUrl : undefined,
+        );
+        setAvailableModels(models);
+      } catch {
+        setAvailableModels([]);
+      } finally {
+        setModelsLoading(false);
+      }
+    }, 600);
+  };
+
   useEffect(() => {
     if (selectedInstanceId === null) {
       setEditName("");
@@ -76,6 +147,8 @@ export function ProviderInstancesConfig({
       setEditIsActive(false);
       setEditType("generative");
       setEditMaxContext(32768);
+      setEditEndpointUrl("");
+      setAvailableModels([]);
     } else if (selectedInstanceId === "new") {
       setEditName("");
       const defaultProvider = "google-genai";
@@ -86,6 +159,8 @@ export function ProviderInstancesConfig({
       setEditModel(pMeta?.defaultModel || "gemini-2.5-flash");
       setEditIsActive(false);
       setEditMaxContext(32768);
+      setEditEndpointUrl("");
+      setAvailableModels([]);
     } else {
       const inst = instances.find((i) => i.id === selectedInstanceId);
       if (inst) {
@@ -109,10 +184,22 @@ export function ProviderInstancesConfig({
             ? inst.maxContext
             : 32768,
         );
+        setEditEndpointUrl(inst.endpointUrl || "");
+        setAvailableModels([]);
+        // Auto-fetch models for existing instances
+        fetchModelsForExistingInstance(selectedInstanceId);
       }
     }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [selectedInstanceId, instances, availableProviders]);
 
+  // Re-fetch models when provider/key/endpoint changes on new instance form
+  useEffect(() => {
+    if (selectedInstanceId !== "new") return;
+    fetchModelsForNewInstance(editProvider, editKey, editEndpointUrl);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [editProvider, editKey, editEndpointUrl, selectedInstanceId]);
+
   const handleProviderChange = (providerId: string | null) => {
     if (!providerId) return;
     setEditProvider(providerId);
@@ -122,6 +209,7 @@ export function ProviderInstancesConfig({
         ? pMeta?.defaultEmbeddingModel || ""
         : pMeta?.defaultModel || "",
     );
+    setAvailableModels([]);
   };
 
   const handleTypeChange = (type: "generative" | "embedding") => {
@@ -134,6 +222,14 @@ export function ProviderInstancesConfig({
     );
   };
 
+  const handleRefreshModels = () => {
+    if (selectedInstanceId && selectedInstanceId !== "new") {
+      fetchModelsForExistingInstance(selectedInstanceId);
+    } else {
+      fetchModelsForNewInstance(editProvider, editKey, editEndpointUrl);
+    }
+  };
+
   const handleSave = async (e: React.FormEvent) => {
     e.preventDefault();
     if (!editName.trim()) {
@@ -149,7 +245,7 @@ export function ProviderInstancesConfig({
       let targetInstanceId = selectedInstanceId;
 
       if (selectedInstanceId === "new") {
-        if (!editKey.trim()) {
+        if (editProvider !== "ollama" && !editKey.trim()) {
           setError("API Key is required for new instances.");
           setLoading(false);
           return;
@@ -157,10 +253,13 @@ export function ProviderInstancesConfig({
         const created = await createProviderInstance(
           editName,
           editProvider,
-          editKey,
+          editProvider === "ollama" ? "none" : editKey,
           editModel || undefined,
           editType,
           editType === "generative" ? editMaxContext : 0,
+          editProvider === "ollama"
+            ? editEndpointUrl || "http://localhost:11434"
+            : undefined,
         );
         if (editIsActive) {
           await setActiveProviderInstance(created.id);
@@ -194,10 +293,13 @@ export function ProviderInstancesConfig({
           selectedInstanceId,
           editName,
           editProvider,
-          editKey || undefined,
+          editProvider === "ollama" ? "none" : editKey || undefined,
           editModel || undefined,
           editType,
           editType === "generative" ? editMaxContext : 0,
+          editProvider === "ollama"
+            ? editEndpointUrl || "http://localhost:11434"
+            : undefined,
         );
         if (editIsActive) {
           await setActiveProviderInstance(selectedInstanceId);
@@ -282,7 +384,9 @@ export function ProviderInstancesConfig({
                       <ItemDescription>{inst.providerName}</ItemDescription>
                       <div className="flex flex-row gap-1.5">
                         {inst.isActive && <Badge>Active</Badge>}
-                        <Badge variant="outline">{inst.type === "generative" ? "gen" : "embed"}</Badge>
+                        <Badge variant="outline">
+                          {inst.type === "generative" ? "gen" : "embed"}
+                        </Badge>
                       </div>
                     </ItemContent>
                   </Item>
@@ -334,11 +438,11 @@ export function ProviderInstancesConfig({
                       }
                       items={[
                         {
-                          label: "Generative (Text Completion)",
+                          label: "Generative (Text Generation)",
                           value: "generative",
                         },
                         {
-                          label: "Embedding (Vector generation)",
+                          label: "Embedding (Vector Embeddings)",
                           value: "embedding",
                         },
                       ]}
@@ -349,10 +453,10 @@ export function ProviderInstancesConfig({
                       <SelectContent>
                         <SelectGroup>
                           <SelectItem value="generative">
-                            Generative (Chat / Text Completion)
+                            Generative (Text Generation)
                           </SelectItem>
                           <SelectItem value="embedding">
-                            Embedding (Vector generation)
+                            Embedding (Vector Embeddings)
                           </SelectItem>
                         </SelectGroup>
                       </SelectContent>
@@ -396,30 +500,109 @@ export function ProviderInstancesConfig({
                   </span>
                 )}
 
-                <div className="flex flex-col gap-1.5">
-                  <Label htmlFor="formKey">API Key</Label>
-                  <Input
-                    id="formKey"
-                    type="password"
-                    value={editKey}
-                    onChange={(e) => setEditKey(e.target.value)}
-                    placeholder={
-                      selectedInstanceId === "new"
-                        ? "AIzaSy..."
-                        : "•••••••• (unchanged)"
-                    }
-                    required={selectedInstanceId === "new"}
-                  />
-                </div>
+                {editProvider !== "ollama" && (
+                  <div className="flex flex-col gap-1.5">
+                    <Label htmlFor="formKey">API Key</Label>
+                    <Input
+                      id="formKey"
+                      type="password"
+                      value={editKey}
+                      onChange={(e) => setEditKey(e.target.value)}
+                      placeholder={
+                        selectedInstanceId === "new"
+                          ? "AIzaSy..."
+                          : "•••••••• (unchanged)"
+                      }
+                      required={selectedInstanceId === "new"}
+                    />
+                  </div>
+                )}
+
+                {editProvider === "ollama" && (
+                  <div className="flex flex-col gap-1.5">
+                    <Label htmlFor="formEndpoint">Endpoint URL</Label>
+                    <Input
+                      id="formEndpoint"
+                      value={editEndpointUrl}
+                      onChange={(e) => setEditEndpointUrl(e.target.value)}
+                      placeholder="e.g. http://localhost:11434"
+                      required
+                    />
+                  </div>
+                )}
 
                 <div className="flex flex-col gap-1.5">
-                  <Label htmlFor="formModel">Model Name</Label>
-                  <Input
-                    id="formModel"
+                  <div className="flex items-center justify-between">
+                    <Label htmlFor="formModel">Model</Label>
+                    <button
+                      type="button"
+                      onClick={handleRefreshModels}
+                      disabled={modelsLoading}
+                      className="flex items-center gap-1 rounded px-1.5 py-0.5 text-xs text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:opacity-40"
+                      title="Refresh model list"
+                    >
+                      <RefreshCwIcon
+                        className={cn(
+                          "size-3",
+                          modelsLoading && "animate-spin",
+                        )}
+                      />
+                      {modelsLoading
+                        ? "Fetching…"
+                        : availableModels.length > 0
+                          ? `${availableModels.length} models`
+                          : "Fetch models"}
+                    </button>
+                  </div>
+                  <Combobox
                     value={editModel}
-                    onChange={(e) => setEditModel(e.target.value)}
-                    placeholder="e.g. gemini-2.5-flash, gemini-2.5-pro"
-                  />
+                    onValueChange={(v) => {
+                      if (v) setEditModel(v);
+                    }}
+                    items={availableModels.map((m) => m.id)}
+                  >
+                    <ComboboxInput
+                      id="formModel"
+                      placeholder={
+                        modelsLoading
+                          ? "Fetching models…"
+                          : availableModels.length > 0
+                            ? "Search or select a model…"
+                            : "e.g. gemini-2.5-flash"
+                      }
+                      disabled={modelsLoading}
+                      showClear={false}
+                      value={editModel}
+                      onChange={(e) =>
+                        setEditModel((e.target as HTMLInputElement).value)
+                      }
+                      className="w-full"
+                    />
+                    <ComboboxContent>
+                      <ComboboxEmpty>
+                        {modelsLoading
+                          ? "Fetching models…"
+                          : "No models found. Type a custom model name above."}
+                      </ComboboxEmpty>
+                      <ComboboxList>
+                        {(modelId: string) => {
+                          const model = availableModels.find(
+                            (m) => m.id === modelId,
+                          );
+                          return (
+                            <ComboboxItem key={modelId} value={modelId}>
+                              <span className="flex-1 truncate">{modelId}</span>
+                              {model?.ownedBy && (
+                                <span className="ml-2 shrink-0 text-xs text-muted-foreground">
+                                  {model.ownedBy}
+                                </span>
+                              )}
+                            </ComboboxItem>
+                          );
+                        }}
+                      </ComboboxList>
+                    </ComboboxContent>
+                  </Combobox>
                 </div>
 
                 {editType === "generative" && (

apps/gui/src/components/home/HomeView.tsx

@@ -34,7 +34,7 @@ import {
   SelectValue,
 } from "@/components/ui/select";
 
-export function DashboardView() {
+export function HomeView() {
   const router = useRouter();
   const [loading, setLoading] = useState(false);
   const [loadingData, setLoadingData] = useState(true);
@@ -44,7 +44,9 @@ export function DashboardView() {
   const [scenarios, setScenarios] = useState<
     { path: string; name: string; description: string }[]
   >([]);
-  const [, setProviderInstances] = useState<ModelProviderInstance[]>([]);
+  const [providerInstances, setProviderInstances] = useState<
+    ModelProviderInstance[]
+  >([]);
 
   // Modal State
   const [scenarioForModal, setScenarioForModal] = useState<{
@@ -203,6 +205,24 @@ export function DashboardView() {
             </div>
           )}
 
+          {providerInstances.length === 0 && !loadingData && (
+            <div className="mb-6 border border-yellow-500/30 bg-yellow-500/10 px-4 py-3 text-sm text-yellow-600 flex flex-col gap-2">
+              <span className="font-semibold flex items-center gap-1">
+                ⚠️ No LLM providers have been configured.
+              </span>
+              <span>
+                Please go to the{" "}
+                <Link
+                  href="/config"
+                  className="underline font-medium hover:text-yellow-700"
+                >
+                  Configuration
+                </Link>{" "}
+                page to set up at least one provider before running simulations.
+              </span>
+            </div>
+          )}
+
           {/* Simulations Section */}
           <section className="mb-10">
             <h2 className="text-headline-lg text-primary mb-6 animate-fade-in">
@@ -235,8 +255,16 @@ export function DashboardView() {
                 {savedSessions.map((s) => (
                   <div
                     key={s.id}
-                    onClick={() => handleResume(s.id)}
-                    className="flex-shrink-0 w-72 border border-border/30 bg-card p-5 cursor-pointer shadow-sm hover:-translate-y-0.5 hover:shadow-md active:translate-y-0 active:shadow-sm transition-all relative group"
+                    onClick={
+                      providerInstances.length === 0
+                        ? undefined
+                        : () => handleResume(s.id)
+                    }
+                    className={`flex-shrink-0 w-72 border border-border/30 bg-card p-5 shadow-sm transition-all relative group ${
+                      providerInstances.length === 0
+                        ? "opacity-50 cursor-not-allowed filter grayscale"
+                        : "cursor-pointer hover:-translate-y-0.5 hover:shadow-md active:translate-y-0 active:shadow-sm"
+                    }`}
                   >
                     <div className="flex flex-col gap-1 text-sm mb-4">
                       <strong className="text-body-md text-foreground block">
@@ -337,6 +365,7 @@ export function DashboardView() {
                     name={s.name}
                     description={s.description}
                     onClick={() => handleScenarioClick(s)}
+                    disabled={providerInstances.length === 0}
                   />
                 ))}
               </div>

apps/gui/src/components/play/PlayView.tsx

@@ -422,242 +422,247 @@ export function PlayView() {
                   </p>
                 </div>
               </div>
-            {/* Simulation Global Controls */}
-            <div className="flex gap-2 shrink-0">
-              {snapshot.status !== "done" && snapshot.status !== "error" && (
-                <>
-                  {snapshot.status === "running" &&
-                    (loading ? (
-                      <Button
-                        variant="secondary"
-                        size="sm"
-                        onClick={() => {
-                          pauseRequestedRef.current = true;
-                        }}
-                      >
-                        Pause
-                      </Button>
-                    ) : (
-                      <Button
-                        variant="secondary"
-                        size="sm"
-                        onClick={() => runSteps(snapshot.id)}
-                      >
-                        Resume
-                      </Button>
-                    ))}
-                  <Button
-                    variant="destructive"
-                    size="sm"
-                    onClick={() => {
-                      pauseRequestedRef.current = true;
-                      router.push("/");
-                    }}
-                  >
-                    Stop
-                  </Button>
-                </>
-              )}
-            </div>
-          </div>
-          <div className="flex items-center justify-between text-xs font-mono mt-1 pt-1.5 border-t border-border/10">
-            <span className="text-muted-foreground">
-              Status:{" "}
-              <span className="text-primary font-bold">
-                {getUnifiedStatus()}
-              </span>
-            </span>
-            <span className="text-muted-foreground">
-              Turn:{" "}
-              <span className="text-foreground font-bold">{snapshot.turn}</span>
-            </span>
-          </div>
-          {statusMessage() && (
-            <p className="text-xs font-medium text-primary mt-1 font-mono">
-              {loading && "⏳ "}
-              {statusMessage()}
-            </p>
-          )}
-        </header>
-
-        {/* Scrollable Center Viewport */}
-        <main className="flex-1 overflow-y-auto px-8 py-6">
-          {activeTab === "interact" ? (
-            <div className="flex flex-col gap-4 max-w-[800px] mx-auto pb-12">
-              {(() => {
-                const playerEntity = snapshot.entities.find((e) => e.isPlayer);
-                return snapshot.log.map((entry, i) => (
-                  <LogEntryCard
-                    key={i}
-                    entry={entry}
-                    onShowPrompt={setSelectedEntryForModal}
-                    isPlayerCard={entry.entityId === playerEntity?.id}
-                  />
-                ));
-              })()}
-              {loading && (
-                <div className="flex items-center gap-2 text-sm italic text-muted-foreground p-2 font-mono">
-                  <Spinner />
-                  {statusText || "Processing..."}
-                </div>
-              )}
-              <div ref={logEndRef} />
-            </div>
-          ) : (
-            <div className="max-w-[800px] mx-auto space-y-6 pb-12">
-              {/* Simulation Info */}
-              <div className="border border-border/30 bg-card p-6 shadow-[2px_2px_0_0_var(--border)]">
-                <h3 className="text-headline-sm text-primary mb-4 border-b border-dotted border-border/20 pb-2">
-                  Simulation Info
-                </h3>
-                <div className="grid grid-cols-1 md:grid-cols-2 gap-6 text-sm font-mono">
-                  <div className="flex flex-col gap-1 border-b border-border/10 pb-2">
-                    <span className="text-muted-foreground text-xs uppercase tracking-wider">
-                      Session ID
-                    </span>
-                    <span className="text-foreground font-bold break-all">
-                      {snapshot.id}
-                    </span>
-                  </div>
-                  <div className="flex flex-col gap-1 border-b border-border/10 pb-2">
-                    <span className="text-muted-foreground text-xs uppercase tracking-wider">
-                      Max Turns
-                    </span>
-                    <span className="text-foreground font-bold">
-                      {snapshot.maxTurns}
-                    </span>
-                  </div>
-                  <div className="flex flex-col gap-1 border-b border-border/10 pb-2">
-                    <span className="text-muted-foreground text-xs uppercase tracking-wider">
-                      Turn Count
-                    </span>
-                    <span className="text-foreground font-bold">
-                      {snapshot.turn}
-                    </span>
-                  </div>
-                  <div className="flex flex-col gap-1 border-b border-border/10 pb-2">
-                    <span className="text-muted-foreground text-xs uppercase tracking-wider">
-                      Entities Registered
-                    </span>
-                    <span className="text-foreground font-bold">
-                      {snapshot.entities.length}
-                    </span>
-                  </div>
-                </div>
-              </div>
-
-              {/* Entities Involved */}
-              <div className="border border-border/30 bg-card p-6 shadow-[2px_2px_0_0_var(--border)]">
-                <h3 className="text-headline-sm text-primary mb-4 border-b border-dotted border-border/20 pb-2">
-                  Entities Involved
-                </h3>
-                <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
-                  {snapshot.entities.map((ent) => (
-                    <div
-                      key={ent.id}
-                      className="border border-border/20 bg-secondary/20 p-4 shadow-[1px_1px_0_0_var(--border)] flex justify-between items-center"
-                    >
-                      <div>
-                        <strong className="text-sm text-foreground block font-head tracking-wide">
-                          {ent.name}
-                        </strong>
-                        <span className="text-xs text-muted-foreground font-mono block mt-1">
-                          ID: {ent.id}
-                        </span>
-                      </div>
-                      <div className="flex items-center gap-2">
-                        {ent.isPlayer ? (
-                          <span className="bg-primary/20 text-primary border border-primary/30 px-2 py-0.5 text-xs font-mono">
-                            PLAYER
-                          </span>
-                        ) : (
-                          <span className="bg-secondary/60 text-muted-foreground border border-border/20 px-2 py-0.5 text-xs font-mono">
-                            NPC
-                          </span>
-                        )}
-                      </div>
-                    </div>
-                  ))}
-                </div>
-              </div>
-            </div>
-          )}
-        </main>
-
-        {/* Sticky Chat / Interaction Input Footer */}
-        {activeTab === "interact" && (
-          <footer className="sticky bottom-0 bg-background/95 backdrop-blur-xs border-t border-dotted border-border/20 px-8 py-4 z-10 shrink-0">
-            <div className="max-w-[800px] mx-auto">
-              {snapshot.status === "waiting_player" &&
-              snapshot.waitingEntity ? (
-                <div className="border border-border/30 bg-card p-4 shadow-[2px_2px_0_0_var(--border)]">
-                  <details className="mb-3">
-                    <summary className="cursor-pointer text-sm font-medium font-head text-primary select-none outline-none">
-                      <strong>
-                        Your context as {snapshot.waitingEntity.name}
-                      </strong>
-                    </summary>
-                    <pre className="text-xs whitespace-pre-wrap bg-input border border-border/20 p-2 max-h-[150px] overflow-y-auto mt-2 font-mono">
-                      {snapshot.waitingEntity.userContext}
-                    </pre>
-                  </details>
-
-                  <form
-                    onSubmit={handleSubmitAction}
-                    className="flex flex-col gap-2"
-                  >
-                    <Textarea
-                      value={playerInput}
-                      onChange={(e) => setPlayerInput(e.target.value)}
-                      placeholder="Describe what your character does, says, or thinks..."
-                      rows={3}
-                      disabled={loading}
-                    />
+              {/* Simulation Global Controls */}
+              <div className="flex gap-2 shrink-0">
+                {snapshot.status !== "done" && snapshot.status !== "error" && (
+                  <>
+                    {snapshot.status === "running" &&
+                      (loading ? (
+                        <Button
+                          variant="secondary"
+                          size="sm"
+                          onClick={() => {
+                            pauseRequestedRef.current = true;
+                          }}
+                        >
+                          Pause
+                        </Button>
+                      ) : (
+                        <Button
+                          variant="secondary"
+                          size="sm"
+                          onClick={() => runSteps(snapshot.id)}
+                        >
+                          Resume
+                        </Button>
+                      ))}
                     <Button
-                      type="submit"
-                      disabled={loading || !playerInput.trim()}
+                      variant="destructive"
+                      size="sm"
+                      onClick={() => {
+                        pauseRequestedRef.current = true;
+                        router.push("/");
+                      }}
                     >
-                      {loading ? "Processing..." : "Submit Action"}
+                      Stop
                     </Button>
-                  </form>
-                </div>
-              ) : snapshot.status === "done" || snapshot.status === "error" ? (
-                <div className="flex justify-between items-center bg-card border border-border/30 p-4 shadow-[2px_2px_0_0_var(--border)]">
-                  <span className="text-sm font-mono text-muted-foreground">
-                    {snapshot.status === "error"
-                      ? "Simulation finished with an error."
-                      : "Simulation complete."}
-                  </span>
-                  <Button
-                    onClick={() => {
-                      router.push("/");
-                    }}
-                    size="sm"
-                  >
-                    {snapshot.status === "error"
-                      ? "Back to Dashboard"
-                      : "New Simulation"}
-                  </Button>
-                </div>
-              ) : null}
+                  </>
+                )}
+              </div>
             </div>
-          </footer>
+            <div className="flex items-center justify-between text-xs font-mono mt-1 pt-1.5 border-t border-border/10">
+              <span className="text-muted-foreground">
+                Status:{" "}
+                <span className="text-primary font-bold">
+                  {getUnifiedStatus()}
+                </span>
+              </span>
+              <span className="text-muted-foreground">
+                Turn:{" "}
+                <span className="text-foreground font-bold">
+                  {snapshot.turn}
+                </span>
+              </span>
+            </div>
+            {statusMessage() && (
+              <p className="text-xs font-medium text-primary mt-1 font-mono">
+                {loading && "⏳ "}
+                {statusMessage()}
+              </p>
+            )}
+          </header>
+
+          {/* Scrollable Center Viewport */}
+          <main className="flex-1 overflow-y-auto px-8 py-6">
+            {activeTab === "interact" ? (
+              <div className="flex flex-col gap-4 max-w-[800px] mx-auto pb-12">
+                {(() => {
+                  const playerEntity = snapshot.entities.find(
+                    (e) => e.isPlayer,
+                  );
+                  return snapshot.log.map((entry, i) => (
+                    <LogEntryCard
+                      key={i}
+                      entry={entry}
+                      onShowPrompt={setSelectedEntryForModal}
+                      isPlayerCard={entry.entityId === playerEntity?.id}
+                    />
+                  ));
+                })()}
+                {loading && (
+                  <div className="flex items-center gap-2 text-sm italic text-muted-foreground p-2 font-mono">
+                    <Spinner />
+                    {statusText || "Processing..."}
+                  </div>
+                )}
+                <div ref={logEndRef} />
+              </div>
+            ) : (
+              <div className="max-w-[800px] mx-auto space-y-6 pb-12">
+                {/* Simulation Info */}
+                <div className="border border-border/30 bg-card p-6 shadow-[2px_2px_0_0_var(--border)]">
+                  <h3 className="text-headline-sm text-primary mb-4 border-b border-dotted border-border/20 pb-2">
+                    Simulation Info
+                  </h3>
+                  <div className="grid grid-cols-1 md:grid-cols-2 gap-6 text-sm font-mono">
+                    <div className="flex flex-col gap-1 border-b border-border/10 pb-2">
+                      <span className="text-muted-foreground text-xs uppercase tracking-wider">
+                        Session ID
+                      </span>
+                      <span className="text-foreground font-bold break-all">
+                        {snapshot.id}
+                      </span>
+                    </div>
+                    <div className="flex flex-col gap-1 border-b border-border/10 pb-2">
+                      <span className="text-muted-foreground text-xs uppercase tracking-wider">
+                        Max Turns
+                      </span>
+                      <span className="text-foreground font-bold">
+                        {snapshot.maxTurns}
+                      </span>
+                    </div>
+                    <div className="flex flex-col gap-1 border-b border-border/10 pb-2">
+                      <span className="text-muted-foreground text-xs uppercase tracking-wider">
+                        Turn Count
+                      </span>
+                      <span className="text-foreground font-bold">
+                        {snapshot.turn}
+                      </span>
+                    </div>
+                    <div className="flex flex-col gap-1 border-b border-border/10 pb-2">
+                      <span className="text-muted-foreground text-xs uppercase tracking-wider">
+                        Entities Registered
+                      </span>
+                      <span className="text-foreground font-bold">
+                        {snapshot.entities.length}
+                      </span>
+                    </div>
+                  </div>
+                </div>
+
+                {/* Entities Involved */}
+                <div className="border border-border/30 bg-card p-6 shadow-[2px_2px_0_0_var(--border)]">
+                  <h3 className="text-headline-sm text-primary mb-4 border-b border-dotted border-border/20 pb-2">
+                    Entities Involved
+                  </h3>
+                  <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+                    {snapshot.entities.map((ent) => (
+                      <div
+                        key={ent.id}
+                        className="border border-border/20 bg-secondary/20 p-4 shadow-[1px_1px_0_0_var(--border)] flex justify-between items-center"
+                      >
+                        <div>
+                          <strong className="text-sm text-foreground block font-head tracking-wide">
+                            {ent.name}
+                          </strong>
+                          <span className="text-xs text-muted-foreground font-mono block mt-1">
+                            ID: {ent.id}
+                          </span>
+                        </div>
+                        <div className="flex items-center gap-2">
+                          {ent.isPlayer ? (
+                            <span className="bg-primary/20 text-primary border border-primary/30 px-2 py-0.5 text-xs font-mono">
+                              PLAYER
+                            </span>
+                          ) : (
+                            <span className="bg-secondary/60 text-muted-foreground border border-border/20 px-2 py-0.5 text-xs font-mono">
+                              NPC
+                            </span>
+                          )}
+                        </div>
+                      </div>
+                    ))}
+                  </div>
+                </div>
+              </div>
+            )}
+          </main>
+
+          {/* Sticky Chat / Interaction Input Footer */}
+          {activeTab === "interact" && (
+            <footer className="sticky bottom-0 bg-background/95 backdrop-blur-xs border-t border-dotted border-border/20 px-8 py-4 z-10 shrink-0">
+              <div className="max-w-[800px] mx-auto">
+                {snapshot.status === "waiting_player" &&
+                snapshot.waitingEntity ? (
+                  <div className="border border-border/30 bg-card p-4 shadow-[2px_2px_0_0_var(--border)]">
+                    <details className="mb-3">
+                      <summary className="cursor-pointer text-sm font-medium font-head text-primary select-none outline-none">
+                        <strong>
+                          Your context as {snapshot.waitingEntity.name}
+                        </strong>
+                      </summary>
+                      <pre className="text-xs whitespace-pre-wrap bg-input border border-border/20 p-2 max-h-[150px] overflow-y-auto mt-2 font-mono">
+                        {snapshot.waitingEntity.userContext}
+                      </pre>
+                    </details>
+
+                    <form
+                      onSubmit={handleSubmitAction}
+                      className="flex flex-col gap-2"
+                    >
+                      <Textarea
+                        value={playerInput}
+                        onChange={(e) => setPlayerInput(e.target.value)}
+                        placeholder="Describe what your character does, says, or thinks..."
+                        rows={3}
+                        disabled={loading}
+                      />
+                      <Button
+                        type="submit"
+                        disabled={loading || !playerInput.trim()}
+                      >
+                        {loading ? "Processing..." : "Submit Action"}
+                      </Button>
+                    </form>
+                  </div>
+                ) : snapshot.status === "done" ||
+                  snapshot.status === "error" ? (
+                  <div className="flex justify-between items-center bg-card border border-border/30 p-4 shadow-[2px_2px_0_0_var(--border)]">
+                    <span className="text-sm font-mono text-muted-foreground">
+                      {snapshot.status === "error"
+                        ? "Simulation finished with an error."
+                        : "Simulation complete."}
+                    </span>
+                    <Button
+                      onClick={() => {
+                        router.push("/");
+                      }}
+                      size="sm"
+                    >
+                      {snapshot.status === "error"
+                        ? "Back to Dashboard"
+                        : "New Simulation"}
+                    </Button>
+                  </div>
+                ) : null}
+              </div>
+            </footer>
+          )}
+        </div>
+
+        {error && !loading && (
+          <div className="fixed bottom-4 right-4 z-50 border border-destructive bg-destructive/90 text-destructive-foreground px-4 py-3 shadow-[3px_3px_0_0_var(--border)] text-sm">
+            {error}
+          </div>
+        )}
+
+        {selectedEntryForModal && (
+          <PromptModal
+            entry={selectedEntryForModal}
+            onClose={() => setSelectedEntryForModal(null)}
+          />
         )}
       </div>
-
-      {error && !loading && (
-        <div className="fixed bottom-4 right-4 z-50 border border-destructive bg-destructive/90 text-destructive-foreground px-4 py-3 shadow-[3px_3px_0_0_var(--border)] text-sm">
-          {error}
-        </div>
-      )}
-
-      {selectedEntryForModal && (
-        <PromptModal
-          entry={selectedEntryForModal}
-          onClose={() => setSelectedEntryForModal(null)}
-        />
-      )}
-    </div>
     </SidebarProvider>
   );
 }

apps/gui/src/components/play/PromptModal.tsx

@@ -53,8 +53,16 @@ export function PromptModal({ entry, onClose }: PromptModalProps) {
     const sections: { label: string; type: string; content: string }[] = [
       { label: "System Prompt", type: "system", content: systemPrompt },
       { label: "World Info", type: "world", content: worldStr },
-      { label: "Recent Events", type: "events", content: recentStr || "(No recent events.)" },
-      { label: "Long-Term Memories", type: "memories", content: ledgerStr || "(No long-term memories.)" },
+      {
+        label: "Recent Events",
+        type: "events",
+        content: recentStr || "(No recent events.)",
+      },
+      {
+        label: "Long-Term Memories",
+        type: "memories",
+        content: ledgerStr || "(No long-term memories.)",
+      },
     ];
 
     const totalLen = sections.reduce((sum, s) => sum + s.content.length, 0);

apps/gui/src/components/play/ScenarioCard.tsx

@@ -9,17 +9,39 @@ interface ScenarioCardProps {
   name: string;
   description: string;
   onClick: () => void;
+  disabled?: boolean;
 }
 
-export function ScenarioCard({ name, description, onClick }: ScenarioCardProps) {
+export function ScenarioCard({
+  name,
+  description,
+  onClick,
+  disabled,
+}: ScenarioCardProps) {
   return (
     <div
-      onClick={onClick}
-      className="flex-shrink-0 w-64 border border-border/30 bg-card p-5 cursor-pointer shadow-sm hover:-translate-y-0.5 hover:shadow-md active:translate-y-0 active:shadow-sm transition-all"
+      onClick={disabled ? undefined : onClick}
+      className={`flex-shrink-0 w-64 border border-border/30 bg-card p-5 shadow-sm transition-all ${
+        disabled
+          ? "opacity-50 cursor-not-allowed filter grayscale"
+          : "cursor-pointer hover:-translate-y-0.5 hover:shadow-md active:translate-y-0 active:shadow-sm"
+      }`}
     >
-      <strong className="text-body-md text-foreground block mb-2">{name}</strong>
-      <p className="text-xs text-muted-foreground leading-relaxed mb-1">{truncate(description, 80)}</p>
-      <span className="mt-4 flex items-center justify-center size-7 border border-primary bg-primary/10 text-primary font-mono text-sm font-bold">{'>'}</span>
+      <strong className="text-body-md text-foreground block mb-2">
+        {name}
+      </strong>
+      <p className="text-xs text-muted-foreground leading-relaxed mb-1">
+        {truncate(description, 80)}
+      </p>
+      <span
+        className={`mt-4 flex items-center justify-center size-7 border font-mono text-sm font-bold ${
+          disabled
+            ? "border-muted text-muted bg-muted/10"
+            : "border-primary bg-primary/10 text-primary"
+        }`}
+      >
+        {">"}
+      </span>
     </div>
   );
 }

apps/gui/src/components/ui/accordion.tsx

@@ -1,14 +1,14 @@
-"use client"
+"use client";
 
-import * as React from "react"
-import { ChevronDownIcon } from "lucide-react"
-import { Accordion as AccordionPrimitive } from "radix-ui"
+import * as React from "react";
+import { ChevronDownIcon } from "lucide-react";
+import { Accordion as AccordionPrimitive } from "radix-ui";
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
 // Smooth, premium easing for the open/close — fast out of the gate, gentle
 // settle. Shared by the panel height and the chevron so they move in lockstep.
-const EASE = "ease-[cubic-bezier(0.32,0.72,0,1)]"
+const EASE = "ease-[cubic-bezier(0.32,0.72,0,1)]";
 
 function Accordion({
   className,
@@ -20,7 +20,7 @@ function Accordion({
       className={cn("flex w-full flex-col gap-3", className)}
       {...props}
     />
-  )
+  );
 }
 
 function AccordionItem({
@@ -32,11 +32,11 @@ function AccordionItem({
       data-slot="accordion-item"
       className={cn(
         "overflow-hidden rounded border-2 bg-background text-foreground shadow-md transition-shadow duration-200 hover:shadow-sm data-[state=open]:shadow-sm",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function AccordionTrigger({
@@ -50,7 +50,7 @@ function AccordionTrigger({
         data-slot="accordion-trigger"
         className={cn(
           "flex flex-1 cursor-pointer items-center justify-between gap-4 px-4 py-3 text-left font-head transition-colors hover:bg-muted/50 data-[state=open]:bg-muted/40 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary [&[data-state=open]>svg]:rotate-180",
-          className
+          className,
         )}
         {...props}
       >
@@ -60,12 +60,12 @@ function AccordionTrigger({
           data-slot="accordion-trigger-icon"
           className={cn(
             "h-4 w-4 shrink-0 text-muted-foreground transition-transform duration-300",
-            EASE
+            EASE,
           )}
         />
       </AccordionPrimitive.Trigger>
     </AccordionPrimitive.Header>
-  )
+  );
 }
 
 function AccordionContent({
@@ -89,13 +89,13 @@ function AccordionContent({
           // Fade + nudge the content as the panel opens/closes, synced to the slide.
           "group-data-[state=closed]/panel:-translate-y-1 group-data-[state=closed]/panel:opacity-0",
           "[&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground [&_p:not(:last-child)]:mb-4",
-          className
+          className,
         )}
       >
         {children}
       </div>
     </AccordionPrimitive.Content>
-  )
+  );
 }
 
-export { Accordion, AccordionItem, AccordionTrigger, AccordionContent }
+export { Accordion, AccordionItem, AccordionTrigger, AccordionContent };

apps/gui/src/components/ui/badge.tsx

@@ -1,8 +1,8 @@
-import * as React from "react"
-import { cva, type VariantProps } from "class-variance-authority"
-import { Slot } from "radix-ui"
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { Slot } from "radix-ui";
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
 const badgeVariants = cva(
   "group/badge inline-flex h-5 w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded border px-2 py-0.5 text-xs font-head font-medium whitespace-nowrap transition-all focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 aria-invalid:border-destructive [&>svg]:pointer-events-none [&>svg]:size-3!",
@@ -24,8 +24,8 @@ const badgeVariants = cva(
     defaultVariants: {
       variant: "default",
     },
-  }
-)
+  },
+);
 
 function Badge({
   className,
@@ -34,7 +34,7 @@ function Badge({
   ...props
 }: React.ComponentProps<"span"> &
   VariantProps<typeof badgeVariants> & { asChild?: boolean }) {
-  const Comp = asChild ? Slot.Root : "span"
+  const Comp = asChild ? Slot.Root : "span";
 
   return (
     <Comp
@@ -43,7 +43,7 @@ function Badge({
       className={cn(badgeVariants({ variant }), className)}
       {...props}
     />
-  )
+  );
 }
 
-export { Badge, badgeVariants }
+export { Badge, badgeVariants };

apps/gui/src/components/ui/button.tsx

@@ -1,8 +1,8 @@
-import * as React from "react"
-import { Slot } from "@radix-ui/react-slot"
-import { cva, type VariantProps } from "class-variance-authority"
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
 const buttonVariants = cva(
   "inline-flex items-center justify-center gap-2 whitespace-nowrap text-sm font-medium border border-border/30 outline-none transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 shadow-sm active:translate-x-[1px] active:translate-y-[1px] active:shadow-xs focus-visible:ring-2 focus-visible:ring-ring",
@@ -12,11 +12,11 @@ const buttonVariants = cva(
         default: "bg-primary text-primary-foreground hover:bg-primary-hover",
         destructive:
           "bg-destructive text-destructive-foreground hover:bg-destructive/90",
-        outline:
-          "bg-background hover:bg-secondary",
+        outline: "bg-background hover:bg-secondary",
         secondary:
           "bg-secondary text-secondary-foreground hover:bg-secondary-foreground/10",
-        ghost: "border-transparent shadow-none active:translate-x-0 active:translate-y-0 active:shadow-none hover:bg-secondary",
+        ghost:
+          "border-transparent shadow-none active:translate-x-0 active:translate-y-0 active:shadow-none hover:bg-secondary",
         link: "border-transparent shadow-none active:translate-x-0 active:translate-y-0 active:shadow-none text-primary hover:underline",
       },
       size: {
@@ -30,27 +30,28 @@ const buttonVariants = cva(
       variant: "default",
       size: "default",
     },
-  }
-)
+  },
+);
 
 export interface ButtonProps
-  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+  extends
+    React.ButtonHTMLAttributes<HTMLButtonElement>,
     VariantProps<typeof buttonVariants> {
-  asChild?: boolean
+  asChild?: boolean;
 }
 
 const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
   ({ className, variant, size, asChild = false, ...props }, ref) => {
-    const Comp = asChild ? Slot : "button"
+    const Comp = asChild ? Slot : "button";
     return (
       <Comp
         className={cn(buttonVariants({ variant, size, className }))}
         ref={ref}
         {...props}
       />
-    )
-  }
-)
-Button.displayName = "Button"
+    );
+  },
+);
+Button.displayName = "Button";
 
-export { Button, buttonVariants }
+export { Button, buttonVariants };

apps/gui/src/components/ui/card.tsx

@@ -1,6 +1,6 @@
-import * as React from "react"
+import * as React from "react";
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
 function Card({
   className,
@@ -13,11 +13,11 @@ function Card({
       data-size={size}
       className={cn(
         "group/card flex flex-col gap-(--card-spacing) overflow-hidden border border-border/30 bg-card py-(--card-spacing) text-sm text-card-foreground shadow-[2px_2px_0_0_var(--border)] [--card-spacing:--spacing(4)] data-[size=sm]:[--card-spacing:--spacing(3)]",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
@@ -26,24 +26,21 @@ function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
       data-slot="card-header"
       className={cn(
         "group/card-header @container/card-header grid auto-rows-min items-start gap-1 px-(--card-spacing) has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] border-b border-dotted border-border/20 pb-4 mb-2",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
       data-slot="card-title"
-      className={cn(
-        "font-head text-headline-sm text-foreground",
-        className
-      )}
+      className={cn("font-head text-headline-sm text-foreground", className)}
       {...props}
     />
-  )
+  );
 }
 
 function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
@@ -53,7 +50,7 @@ function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
       className={cn("text-sm text-muted-foreground", className)}
       {...props}
     />
-  )
+  );
 }
 
 function CardAction({ className, ...props }: React.ComponentProps<"div">) {
@@ -62,11 +59,11 @@ function CardAction({ className, ...props }: React.ComponentProps<"div">) {
       data-slot="card-action"
       className={cn(
         "col-start-2 row-span-2 row-start-1 self-start justify-self-end",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function CardContent({ className, ...props }: React.ComponentProps<"div">) {
@@ -76,7 +73,7 @@ function CardContent({ className, ...props }: React.ComponentProps<"div">) {
       className={cn("px-(--card-spacing)", className)}
       {...props}
     />
-  )
+  );
 }
 
 function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
@@ -85,11 +82,11 @@ function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
       data-slot="card-footer"
       className={cn(
         "flex items-center border-t border-dotted border-border/20 bg-muted/30 px-(--card-spacing) pt-(--card-spacing)",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 export {
@@ -100,4 +97,4 @@ export {
   CardAction,
   CardDescription,
   CardContent,
-}
+};

apps/gui/src/components/ui/checkbox.tsx

@@ -1,10 +1,10 @@
-"use client"
+"use client";
 
-import * as React from "react"
-import { CheckIcon } from "lucide-react"
-import { Checkbox as CheckboxPrimitive } from "radix-ui"
+import * as React from "react";
+import { CheckIcon } from "lucide-react";
+import { Checkbox as CheckboxPrimitive } from "radix-ui";
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
 function Checkbox({
   className,
@@ -15,7 +15,7 @@ function Checkbox({
       data-slot="checkbox"
       className={cn(
         "peer relative flex size-5 shrink-0 items-center justify-center rounded border-2 bg-input shadow-sm transition-colors outline-none group-has-disabled/field:opacity-50 after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive data-checked:border-border data-checked:bg-primary data-checked:text-primary-foreground",
-        className
+        className,
       )}
       {...props}
     >
@@ -26,7 +26,7 @@ function Checkbox({
         <CheckIcon />
       </CheckboxPrimitive.Indicator>
     </CheckboxPrimitive.Root>
-  )
+  );
 }
 
-export { Checkbox }
+export { Checkbox };

apps/gui/src/components/ui/combobox.tsx

@@ -0,0 +1,300 @@
+"use client";
+
+import * as React from "react";
+import { Combobox as ComboboxPrimitive } from "@base-ui/react";
+import { CheckIcon, ChevronDownIcon, XIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+import { Button } from "@/components/ui/button";
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+} from "@/components/ui/input-group";
+
+const Combobox = ComboboxPrimitive.Root;
+
+function ComboboxValue({ ...props }: ComboboxPrimitive.Value.Props) {
+  return <ComboboxPrimitive.Value data-slot="combobox-value" {...props} />;
+}
+
+function ComboboxTrigger({
+  className,
+  children,
+  ...props
+}: ComboboxPrimitive.Trigger.Props) {
+  return (
+    <ComboboxPrimitive.Trigger
+      data-slot="combobox-trigger"
+      className={cn("[&_svg:not([class*='size-'])]:size-4", className)}
+      {...props}
+    >
+      {children}
+      <ChevronDownIcon className="pointer-events-none size-4 text-muted-foreground" />
+    </ComboboxPrimitive.Trigger>
+  );
+}
+
+function ComboboxClear({ className, ...props }: ComboboxPrimitive.Clear.Props) {
+  return (
+    <ComboboxPrimitive.Clear
+      data-slot="combobox-clear"
+      render={<InputGroupButton variant="ghost" size="icon-xs" />}
+      className={cn(className)}
+      {...props}
+    >
+      <XIcon className="pointer-events-none" />
+    </ComboboxPrimitive.Clear>
+  );
+}
+
+function ComboboxInput({
+  className,
+  children,
+  disabled = false,
+  showTrigger = true,
+  showClear = false,
+  ...props
+}: ComboboxPrimitive.Input.Props & {
+  showTrigger?: boolean;
+  showClear?: boolean;
+}) {
+  return (
+    <InputGroup className={cn("w-auto", className)}>
+      <ComboboxPrimitive.Input
+        render={<InputGroupInput disabled={disabled} />}
+        {...props}
+      />
+      <InputGroupAddon align="inline-end">
+        {showTrigger && (
+          <InputGroupButton
+            size="icon-xs"
+            variant="ghost"
+            render={<ComboboxTrigger />}
+            data-slot="input-group-button"
+            className="group-has-data-[slot=combobox-clear]/input-group:hidden data-pressed:bg-transparent"
+            disabled={disabled}
+          />
+        )}
+        {showClear && <ComboboxClear disabled={disabled} />}
+      </InputGroupAddon>
+      {children}
+    </InputGroup>
+  );
+}
+
+function ComboboxContent({
+  className,
+  side = "bottom",
+  sideOffset = 6,
+  align = "start",
+  alignOffset = 0,
+  anchor,
+  ...props
+}: ComboboxPrimitive.Popup.Props &
+  Pick<
+    ComboboxPrimitive.Positioner.Props,
+    "side" | "align" | "sideOffset" | "alignOffset" | "anchor"
+  >) {
+  return (
+    <ComboboxPrimitive.Portal>
+      <ComboboxPrimitive.Positioner
+        side={side}
+        sideOffset={sideOffset}
+        align={align}
+        alignOffset={alignOffset}
+        anchor={anchor}
+        className="isolate z-50"
+      >
+        <ComboboxPrimitive.Popup
+          data-slot="combobox-content"
+          data-chips={!!anchor}
+          className={cn(
+            "cn-menu-target cn-menu-translucent group/combobox-content relative max-h-(--available-height) w-(--anchor-width) max-w-(--available-width) min-w-[calc(var(--anchor-width)+var(--spacing-7,1.75rem))] origin-(--transform-origin) overflow-hidden rounded border-2 bg-popover text-popover-foreground shadow-md duration-100 data-[chips=true]:min-w-(--anchor-width) data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 *:data-[slot=input-group]:m-1 *:data-[slot=input-group]:mb-0 *:data-[slot=input-group]:h-8 *:data-[slot=input-group]:border-input/30 *:data-[slot=input-group]:bg-input/30 *:data-[slot=input-group]:shadow-none data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+            className,
+          )}
+          {...props}
+        />
+      </ComboboxPrimitive.Positioner>
+    </ComboboxPrimitive.Portal>
+  );
+}
+
+function ComboboxList({ className, ...props }: ComboboxPrimitive.List.Props) {
+  return (
+    <ComboboxPrimitive.List
+      data-slot="combobox-list"
+      className={cn(
+        "no-scrollbar max-h-72 scroll-py-1 overflow-y-auto overscroll-contain p-1 data-empty:p-0",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function ComboboxItem({
+  className,
+  children,
+  ...props
+}: ComboboxPrimitive.Item.Props) {
+  return (
+    <ComboboxPrimitive.Item
+      data-slot="combobox-item"
+      className={cn(
+        "relative flex w-full cursor-default items-center gap-2 rounded-sm py-1 pr-8 pl-1.5 text-sm outline-hidden select-none data-highlighted:bg-accent data-highlighted:text-accent-foreground not-data-[variant=destructive]:data-highlighted:**:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      <ComboboxPrimitive.ItemIndicator
+        render={
+          <span className="pointer-events-none absolute right-2 flex size-4 items-center justify-center" />
+        }
+      >
+        <CheckIcon className="pointer-events-none" />
+      </ComboboxPrimitive.ItemIndicator>
+    </ComboboxPrimitive.Item>
+  );
+}
+
+function ComboboxGroup({ className, ...props }: ComboboxPrimitive.Group.Props) {
+  return (
+    <ComboboxPrimitive.Group
+      data-slot="combobox-group"
+      className={cn(className)}
+      {...props}
+    />
+  );
+}
+
+function ComboboxLabel({
+  className,
+  ...props
+}: ComboboxPrimitive.GroupLabel.Props) {
+  return (
+    <ComboboxPrimitive.GroupLabel
+      data-slot="combobox-label"
+      className={cn("px-2 py-1.5 text-xs text-muted-foreground", className)}
+      {...props}
+    />
+  );
+}
+
+function ComboboxCollection({ ...props }: ComboboxPrimitive.Collection.Props) {
+  return (
+    <ComboboxPrimitive.Collection data-slot="combobox-collection" {...props} />
+  );
+}
+
+function ComboboxEmpty({ className, ...props }: ComboboxPrimitive.Empty.Props) {
+  return (
+    <ComboboxPrimitive.Empty
+      data-slot="combobox-empty"
+      className={cn(
+        "hidden w-full justify-center py-2 text-center text-sm text-muted-foreground group-data-empty/combobox-content:flex",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function ComboboxSeparator({
+  className,
+  ...props
+}: ComboboxPrimitive.Separator.Props) {
+  return (
+    <ComboboxPrimitive.Separator
+      data-slot="combobox-separator"
+      className={cn("-mx-1 my-1 h-px bg-border", className)}
+      {...props}
+    />
+  );
+}
+
+function ComboboxChips({
+  className,
+  ...props
+}: React.ComponentPropsWithRef<typeof ComboboxPrimitive.Chips> &
+  ComboboxPrimitive.Chips.Props) {
+  return (
+    <ComboboxPrimitive.Chips
+      data-slot="combobox-chips"
+      className={cn(
+        "flex min-h-8 flex-wrap items-center gap-1 rounded border-2 bg-input bg-clip-padding px-2.5 py-1 text-sm shadow-sm transition-colors focus-within:outline-2 focus-within:outline-offset-2 focus-within:outline-primary has-aria-invalid:border-destructive has-data-[slot=combobox-chip]:px-1",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function ComboboxChip({
+  className,
+  children,
+  showRemove = true,
+  ...props
+}: ComboboxPrimitive.Chip.Props & {
+  showRemove?: boolean;
+}) {
+  return (
+    <ComboboxPrimitive.Chip
+      data-slot="combobox-chip"
+      className={cn(
+        "flex h-[calc(var(--spacing,0.25rem)*5.25)] w-fit items-center justify-center gap-1 rounded-sm border-2 bg-muted px-1.5 text-xs font-medium whitespace-nowrap text-foreground has-disabled:pointer-events-none has-disabled:cursor-not-allowed has-disabled:opacity-50 has-data-[slot=combobox-chip-remove]:pr-0",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      {showRemove && (
+        <ComboboxPrimitive.ChipRemove
+          render={<InputGroupButton variant="ghost" size="icon-xs" />}
+          className="-ml-1 opacity-50 hover:opacity-100"
+          data-slot="combobox-chip-remove"
+        >
+          <XIcon className="pointer-events-none" />
+        </ComboboxPrimitive.ChipRemove>
+      )}
+    </ComboboxPrimitive.Chip>
+  );
+}
+
+function ComboboxChipsInput({
+  className,
+  ...props
+}: ComboboxPrimitive.Input.Props) {
+  return (
+    <ComboboxPrimitive.Input
+      data-slot="combobox-chip-input"
+      className={cn("min-w-16 flex-1 outline-none", className)}
+      {...props}
+    />
+  );
+}
+
+function useComboboxAnchor() {
+  return React.useRef<HTMLDivElement | null>(null);
+}
+
+export {
+  Combobox,
+  ComboboxInput,
+  ComboboxContent,
+  ComboboxList,
+  ComboboxItem,
+  ComboboxGroup,
+  ComboboxLabel,
+  ComboboxCollection,
+  ComboboxEmpty,
+  ComboboxSeparator,
+  ComboboxChips,
+  ComboboxChip,
+  ComboboxChipsInput,
+  ComboboxTrigger,
+  ComboboxValue,
+  useComboboxAnchor,
+};

apps/gui/src/components/ui/dialog.tsx

@@ -1,34 +1,34 @@
-"use client"
+"use client";
 
-import * as React from "react"
-import { XIcon } from "lucide-react"
-import { Dialog as DialogPrimitive } from "radix-ui"
+import * as React from "react";
+import { XIcon } from "lucide-react";
+import { Dialog as DialogPrimitive } from "radix-ui";
 
-import { cn } from "@/lib/utils"
-import { Button } from "@/components/ui/button"
+import { cn } from "@/lib/utils";
+import { Button } from "@/components/ui/button";
 
 function Dialog({
   ...props
 }: React.ComponentProps<typeof DialogPrimitive.Root>) {
-  return <DialogPrimitive.Root data-slot="dialog" {...props} />
+  return <DialogPrimitive.Root data-slot="dialog" {...props} />;
 }
 
 function DialogTrigger({
   ...props
 }: React.ComponentProps<typeof DialogPrimitive.Trigger>) {
-  return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />
+  return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />;
 }
 
 function DialogPortal({
   ...props
 }: React.ComponentProps<typeof DialogPrimitive.Portal>) {
-  return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />
+  return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />;
 }
 
 function DialogClose({
   ...props
 }: React.ComponentProps<typeof DialogPrimitive.Close>) {
-  return <DialogPrimitive.Close data-slot="dialog-close" {...props} />
+  return <DialogPrimitive.Close data-slot="dialog-close" {...props} />;
 }
 
 function DialogOverlay({
@@ -40,11 +40,11 @@ function DialogOverlay({
       data-slot="dialog-overlay"
       className={cn(
         "fixed inset-0 isolate z-50 bg-foreground/20 duration-100 supports-backdrop-filter:backdrop-blur-xs data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function DialogContent({
@@ -53,7 +53,7 @@ function DialogContent({
   showCloseButton = true,
   ...props
 }: React.ComponentProps<typeof DialogPrimitive.Content> & {
-  showCloseButton?: boolean
+  showCloseButton?: boolean;
 }) {
   return (
     <DialogPortal>
@@ -62,7 +62,7 @@ function DialogContent({
         data-slot="dialog-content"
         className={cn(
           "fixed top-1/2 left-1/2 z-50 grid w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 gap-4 rounded border-2 bg-popover p-4 text-sm text-popover-foreground shadow-md duration-100 outline-none sm:max-w-sm data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
-          className
+          className,
         )}
         {...props}
       >
@@ -81,7 +81,7 @@ function DialogContent({
         )}
       </DialogPrimitive.Content>
     </DialogPortal>
-  )
+  );
 }
 
 function DialogHeader({ className, ...props }: React.ComponentProps<"div">) {
@@ -91,7 +91,7 @@ function DialogHeader({ className, ...props }: React.ComponentProps<"div">) {
       className={cn("flex flex-col gap-2", className)}
       {...props}
     />
-  )
+  );
 }
 
 function DialogFooter({
@@ -100,14 +100,14 @@ function DialogFooter({
   children,
   ...props
 }: React.ComponentProps<"div"> & {
-  showCloseButton?: boolean
+  showCloseButton?: boolean;
 }) {
   return (
     <div
       data-slot="dialog-footer"
       className={cn(
         "-mx-4 -mb-4 flex flex-col-reverse gap-2 rounded-b-xl border-t-2 bg-muted/50 p-4 sm:flex-row sm:justify-end",
-        className
+        className,
       )}
       {...props}
     >
@@ -118,7 +118,7 @@ function DialogFooter({
         </DialogPrimitive.Close>
       )}
     </div>
-  )
+  );
 }
 
 function DialogTitle({
@@ -128,13 +128,10 @@ function DialogTitle({
   return (
     <DialogPrimitive.Title
       data-slot="dialog-title"
-      className={cn(
-        "font-head text-base leading-none font-medium",
-        className
-      )}
+      className={cn("font-head text-base leading-none font-medium", className)}
       {...props}
     />
-  )
+  );
 }
 
 function DialogDescription({
@@ -146,11 +143,11 @@ function DialogDescription({
       data-slot="dialog-description"
       className={cn(
         "text-sm text-muted-foreground *:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-foreground",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 export {
@@ -164,4 +161,4 @@ export {
   DialogPortal,
   DialogTitle,
   DialogTrigger,
-}
+};

apps/gui/src/components/ui/empty.tsx

@@ -1,6 +1,6 @@
-import { cva, type VariantProps } from "class-variance-authority"
+import { cva, type VariantProps } from "class-variance-authority";
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
 function Empty({ className, ...props }: React.ComponentProps<"div">) {
   return (
@@ -8,11 +8,11 @@ function Empty({ className, ...props }: React.ComponentProps<"div">) {
       data-slot="empty"
       className={cn(
         "flex w-full min-w-0 flex-1 flex-col items-center justify-center gap-4 rounded border-2 bg-card p-6 text-center text-balance",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function EmptyHeader({ className, ...props }: React.ComponentProps<"div">) {
@@ -22,7 +22,7 @@ function EmptyHeader({ className, ...props }: React.ComponentProps<"div">) {
       className={cn("flex max-w-sm flex-col items-center gap-2", className)}
       {...props}
     />
-  )
+  );
 }
 
 const emptyMediaVariants = cva(
@@ -37,8 +37,8 @@ const emptyMediaVariants = cva(
     defaultVariants: {
       variant: "default",
     },
-  }
-)
+  },
+);
 
 function EmptyMedia({
   className,
@@ -52,20 +52,17 @@ function EmptyMedia({
       className={cn(emptyMediaVariants({ variant, className }))}
       {...props}
     />
-  )
+  );
 }
 
 function EmptyTitle({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
       data-slot="empty-title"
-      className={cn(
-        "text-sm font-medium tracking-tight",
-        className
-      )}
+      className={cn("text-sm font-medium tracking-tight", className)}
       {...props}
     />
-  )
+  );
 }
 
 function EmptyDescription({ className, ...props }: React.ComponentProps<"p">) {
@@ -74,11 +71,11 @@ function EmptyDescription({ className, ...props }: React.ComponentProps<"p">) {
       data-slot="empty-description"
       className={cn(
         "text-sm/relaxed text-muted-foreground [&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function EmptyContent({ className, ...props }: React.ComponentProps<"div">) {
@@ -87,11 +84,11 @@ function EmptyContent({ className, ...props }: React.ComponentProps<"div">) {
       data-slot="empty-content"
       className={cn(
         "flex w-full max-w-sm min-w-0 flex-col items-center gap-2.5 text-sm text-balance",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 export {
@@ -101,4 +98,4 @@ export {
   EmptyDescription,
   EmptyContent,
   EmptyMedia,
-}
+};

apps/gui/src/components/ui/input-group.tsx

@@ -0,0 +1,172 @@
+"use client";
+
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+
+function InputGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="input-group"
+      role="group"
+      className={cn(
+        "group/input-group relative flex h-8 w-full min-w-0 items-center rounded border-2 bg-input shadow-sm transition-colors outline-none in-data-[slot=combobox-content]:focus-within:border-inherit in-data-[slot=combobox-content]:focus-within:ring-0 has-disabled:bg-input/50 has-disabled:opacity-50 has-[[data-slot=input-group-control]:focus-visible]:outline-2 has-[[data-slot=input-group-control]:focus-visible]:outline-offset-2 has-[[data-slot=input-group-control]:focus-visible]:outline-primary has-[[data-slot][aria-invalid=true]]:border-destructive has-[>[data-align=block-end]]:h-auto has-[>[data-align=block-end]]:flex-col has-[>[data-align=block-start]]:h-auto has-[>[data-align=block-start]]:flex-col has-[>textarea]:h-auto has-[>[data-align=block-end]]:[&>input]:pt-3 has-[>[data-align=block-start]]:[&>input]:pb-3 has-[>[data-align=inline-end]]:[&>input]:pr-1.5 has-[>[data-align=inline-start]]:[&>input]:pl-1.5",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+const inputGroupAddonVariants = cva(
+  "flex h-auto cursor-text items-center justify-center gap-2 py-1.5 text-sm font-medium text-muted-foreground select-none group-data-[disabled=true]/input-group:opacity-50 [&>kbd]:rounded-[calc(var(--radius)-5px)] [&>svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      align: {
+        "inline-start":
+          "order-first pl-2 has-[>button]:ml-[-0.3rem] has-[>kbd]:ml-[-0.15rem]",
+        "inline-end":
+          "order-last pr-2 has-[>button]:mr-[-0.3rem] has-[>kbd]:mr-[-0.15rem]",
+        "block-start":
+          "order-first w-full justify-start px-2.5 pt-2 group-has-[>input]/input-group:pt-2 [.border-b]:pb-2",
+        "block-end":
+          "order-last w-full justify-start px-2.5 pb-2 group-has-[>input]/input-group:pb-2 [.border-t]:pt-2",
+      },
+    },
+    defaultVariants: {
+      align: "inline-start",
+    },
+  },
+);
+
+function InputGroupAddon({
+  className,
+  align = "inline-start",
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof inputGroupAddonVariants>) {
+  return (
+    <div
+      role="group"
+      data-slot="input-group-addon"
+      data-align={align}
+      className={cn(inputGroupAddonVariants({ align }), className)}
+      onClick={(e) => {
+        if ((e.target as HTMLElement).closest("button")) {
+          return;
+        }
+        e.currentTarget.parentElement?.querySelector("input")?.focus();
+      }}
+      {...props}
+    />
+  );
+}
+
+const inputGroupButtonVariants = cva(
+  "flex items-center gap-2 text-sm shadow-none",
+  {
+    variants: {
+      size: {
+        xs: "h-6 gap-1 rounded-[calc(var(--radius)-3px)] px-1.5 [&>svg:not([class*='size-'])]:size-3.5",
+        sm: "",
+        "icon-xs":
+          "size-6 rounded-[calc(var(--radius)-3px)] p-0 has-[>svg]:p-0",
+        "icon-sm": "size-8 p-0 has-[>svg]:p-0",
+      },
+    },
+    defaultVariants: {
+      size: "xs",
+    },
+  },
+);
+
+function InputGroupButton({
+  className,
+  type = "button",
+  variant = "ghost",
+  size = "xs",
+  render,
+  ...props
+}: Omit<React.ComponentProps<typeof Button>, "size" | "type"> &
+  VariantProps<typeof inputGroupButtonVariants> & {
+    type?: "button" | "submit" | "reset";
+    render?: React.ReactElement;
+  }) {
+  if (render) {
+    return React.cloneElement(render, {
+      className: cn(
+        inputGroupButtonVariants({ size }),
+        (render.props as any)?.className,
+        className,
+      ),
+      type,
+      ...props,
+    } as any);
+  }
+
+  return (
+    <Button
+      type={type}
+      data-size={size}
+      variant={variant}
+      className={cn(inputGroupButtonVariants({ size }), className)}
+      {...props}
+    />
+  );
+}
+
+function InputGroupText({ className, ...props }: React.ComponentProps<"span">) {
+  return (
+    <span
+      className={cn(
+        "flex items-center gap-2 text-sm text-muted-foreground [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function InputGroupInput({
+  className,
+  ...props
+}: React.ComponentProps<"input">) {
+  return (
+    <Input
+      data-slot="input-group-control"
+      className={cn(
+        "flex-1 rounded-none border-0 bg-transparent shadow-none outline-none focus-visible:outline-none disabled:bg-transparent aria-invalid:outline-none dark:bg-transparent dark:disabled:bg-transparent",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function InputGroupTextarea({
+  className,
+  ...props
+}: React.ComponentProps<"textarea">) {
+  return (
+    <Textarea
+      data-slot="input-group-control"
+      className={cn(
+        "flex-1 resize-none rounded-none border-0 bg-transparent py-2 shadow-none outline-none focus-visible:outline-none disabled:bg-transparent aria-invalid:outline-none dark:bg-transparent dark:disabled:bg-transparent",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupText,
+  InputGroupInput,
+  InputGroupTextarea,
+};

apps/gui/src/components/ui/input.tsx

@@ -1,6 +1,6 @@
-import * as React from "react"
+import * as React from "react";
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
 function Input({ className, type, ...props }: React.ComponentProps<"input">) {
   return (
@@ -9,11 +9,11 @@ function Input({ className, type, ...props }: React.ComponentProps<"input">) {
       data-slot="input"
       className={cn(
         "h-8 w-full min-w-0 rounded border-2 bg-input px-3 py-2 text-sm shadow-sm transition-colors outline-none file:inline-flex file:h-6 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
-export { Input }
+export { Input };

apps/gui/src/components/ui/item.tsx

@@ -1,10 +1,10 @@
-import * as React from "react"
-import { mergeProps } from "@base-ui/react/merge-props"
-import { useRender } from "@base-ui/react/use-render"
-import { cva, type VariantProps } from "class-variance-authority"
+import * as React from "react";
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+import { cva, type VariantProps } from "class-variance-authority";
 
-import { cn } from "@/lib/utils"
-import { Separator } from "@/components/ui/separator"
+import { cn } from "@/lib/utils";
+import { Separator } from "@/components/ui/separator";
 
 function ItemGroup({ className, ...props }: React.ComponentProps<"div">) {
   return (
@@ -13,11 +13,11 @@ function ItemGroup({ className, ...props }: React.ComponentProps<"div">) {
       data-slot="item-group"
       className={cn(
         "group/item-group flex w-full flex-col gap-4 has-data-[size=sm]:gap-2.5 has-data-[size=xs]:gap-2",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function ItemSeparator({
@@ -31,7 +31,7 @@ function ItemSeparator({
       className={cn("my-2", className)}
       {...props}
     />
-  )
+  );
 }
 
 const itemVariants = cva(
@@ -53,8 +53,8 @@ const itemVariants = cva(
       variant: "default",
       size: "default",
     },
-  }
-)
+  },
+);
 
 function Item({
   className,
@@ -69,7 +69,7 @@ function Item({
       {
         className: cn(itemVariants({ variant, size, className })),
       },
-      props
+      props,
     ),
     render,
     state: {
@@ -77,7 +77,7 @@ function Item({
       variant,
       size,
     },
-  })
+  });
 }
 
 const itemMediaVariants = cva(
@@ -94,8 +94,8 @@ const itemMediaVariants = cva(
     defaultVariants: {
       variant: "default",
     },
-  }
-)
+  },
+);
 
 function ItemMedia({
   className,
@@ -109,7 +109,7 @@ function ItemMedia({
       className={cn(itemMediaVariants({ variant, className }))}
       {...props}
     />
-  )
+  );
 }
 
 function ItemContent({ className, ...props }: React.ComponentProps<"div">) {
@@ -118,11 +118,11 @@ function ItemContent({ className, ...props }: React.ComponentProps<"div">) {
       data-slot="item-content"
       className={cn(
         "flex flex-1 flex-col gap-1 group-data-[size=xs]/item:gap-0 [&+[data-slot=item-content]]:flex-none",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function ItemTitle({ className, ...props }: React.ComponentProps<"div">) {
@@ -131,11 +131,11 @@ function ItemTitle({ className, ...props }: React.ComponentProps<"div">) {
       data-slot="item-title"
       className={cn(
         "line-clamp-1 flex w-fit items-center gap-2 text-sm leading-snug font-medium underline-offset-4",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function ItemDescription({ className, ...props }: React.ComponentProps<"p">) {
@@ -144,11 +144,11 @@ function ItemDescription({ className, ...props }: React.ComponentProps<"p">) {
       data-slot="item-description"
       className={cn(
         "line-clamp-2 text-left text-sm leading-normal font-normal text-muted-foreground group-data-[size=xs]/item:text-xs [&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function ItemActions({ className, ...props }: React.ComponentProps<"div">) {
@@ -158,7 +158,7 @@ function ItemActions({ className, ...props }: React.ComponentProps<"div">) {
       className={cn("flex items-center gap-2", className)}
       {...props}
     />
-  )
+  );
 }
 
 function ItemHeader({ className, ...props }: React.ComponentProps<"div">) {
@@ -167,11 +167,11 @@ function ItemHeader({ className, ...props }: React.ComponentProps<"div">) {
       data-slot="item-header"
       className={cn(
         "flex basis-full items-center justify-between gap-2",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function ItemFooter({ className, ...props }: React.ComponentProps<"div">) {
@@ -180,11 +180,11 @@ function ItemFooter({ className, ...props }: React.ComponentProps<"div">) {
       data-slot="item-footer"
       className={cn(
         "flex basis-full items-center justify-between gap-2",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 export {
@@ -198,4 +198,4 @@ export {
   ItemDescription,
   ItemHeader,
   ItemFooter,
-}
+};

apps/gui/src/components/ui/label.tsx

@@ -1,9 +1,9 @@
-"use client"
+"use client";
 
-import * as React from "react"
-import { Label as LabelPrimitive } from "radix-ui"
+import * as React from "react";
+import { Label as LabelPrimitive } from "radix-ui";
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
 function Label({
   className,
@@ -14,11 +14,11 @@ function Label({
       data-slot="label"
       className={cn(
         "flex items-center gap-2 text-sm leading-none font-head font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
-export { Label }
+export { Label };

apps/gui/src/components/ui/navigation-menu.tsx

@@ -1,9 +1,9 @@
-import * as React from "react"
-import { cva } from "class-variance-authority"
-import { ChevronDownIcon } from "lucide-react"
-import { NavigationMenu as NavigationMenuPrimitive } from "radix-ui"
+import * as React from "react";
+import { cva } from "class-variance-authority";
+import { ChevronDownIcon } from "lucide-react";
+import { NavigationMenu as NavigationMenuPrimitive } from "radix-ui";
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
 function NavigationMenu({
   className,
@@ -11,7 +11,7 @@ function NavigationMenu({
   viewport = true,
   ...props
 }: React.ComponentProps<typeof NavigationMenuPrimitive.Root> & {
-  viewport?: boolean
+  viewport?: boolean;
 }) {
   return (
     <NavigationMenuPrimitive.Root
@@ -19,14 +19,14 @@ function NavigationMenu({
       data-viewport={viewport}
       className={cn(
         "group/navigation-menu relative flex max-w-max flex-1 items-center justify-center",
-        className
+        className,
       )}
       {...props}
     >
       {children}
       {viewport && <NavigationMenuViewport />}
     </NavigationMenuPrimitive.Root>
-  )
+  );
 }
 
 function NavigationMenuList({
@@ -38,11 +38,11 @@ function NavigationMenuList({
       data-slot="navigation-menu-list"
       className={cn(
         "group flex flex-1 list-none items-center justify-center gap-0",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function NavigationMenuItem({
@@ -55,12 +55,12 @@ function NavigationMenuItem({
       className={cn("relative", className)}
       {...props}
     />
-  )
+  );
 }
 
 const navigationMenuTriggerStyle = cva(
-  "group/navigation-menu-trigger inline-flex h-9 w-max items-center justify-center px-2.5 py-1.5 text-sm font-medium transition-all outline-none hover:bg-secondary hover:text-foreground focus:bg-secondary focus:text-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:pointer-events-none disabled:opacity-50 data-popup-open:bg-secondary data-popup-open:text-foreground data-open:bg-secondary data-open:text-foreground"
-)
+  "group/navigation-menu-trigger inline-flex h-9 w-max items-center justify-center px-2.5 py-1.5 text-sm font-medium transition-all outline-none hover:bg-secondary hover:text-foreground focus:bg-secondary focus:text-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:pointer-events-none disabled:opacity-50 data-popup-open:bg-secondary data-popup-open:text-foreground data-open:bg-secondary data-open:text-foreground",
+);
 
 function NavigationMenuTrigger({
   className,
@@ -79,7 +79,7 @@ function NavigationMenuTrigger({
         aria-hidden="true"
       />
     </NavigationMenuPrimitive.Trigger>
-  )
+  );
 }
 
 function NavigationMenuContent({
@@ -91,11 +91,11 @@ function NavigationMenuContent({
       data-slot="navigation-menu-content"
       className={cn(
         "top-0 left-0 w-full p-1 ease-[cubic-bezier(0.22,1,0.36,1)] group-data-[viewport=false]/navigation-menu:top-full group-data-[viewport=false]/navigation-menu:mt-1.5 group-data-[viewport=false]/navigation-menu:overflow-hidden group-data-[viewport=false]/navigation-menu:border group-data-[viewport=false]/navigation-menu:border-border/30 group-data-[viewport=false]/navigation-menu:bg-popover group-data-[viewport=false]/navigation-menu:text-popover-foreground group-data-[viewport=false]/navigation-menu:shadow-md group-data-[viewport=false]/navigation-menu:duration-300 data-[motion=from-end]:slide-in-from-right-52 data-[motion=from-start]:slide-in-from-left-52 data-[motion=to-end]:slide-out-to-right-52 data-[motion=to-start]:slide-out-to-left-52 data-[motion^=from-]:animate-in data-[motion^=from-]:fade-in data-[motion^=to-]:animate-out data-[motion^=to-]:fade-out **:data-[slot=navigation-menu-link]:focus:ring-0 **:data-[slot=navigation-menu-link]:focus:outline-none md:absolute md:w-auto group-data-[viewport=false]/navigation-menu:data-open:animate-in group-data-[viewport=false]/navigation-menu:data-open:fade-in-0 group-data-[viewport=false]/navigation-menu:data-open:zoom-in-95 group-data-[viewport=false]/navigation-menu:data-closed:animate-out group-data-[viewport=false]/navigation-menu:data-closed:fade-out-0 group-data-[viewport=false]/navigation-menu:data-closed:zoom-out-95",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function NavigationMenuViewport({
@@ -105,19 +105,19 @@ function NavigationMenuViewport({
   return (
     <div
       className={cn(
-        "absolute top-full left-0 isolate z-50 flex justify-center"
+        "absolute top-full left-0 isolate z-50 flex justify-center",
       )}
     >
       <NavigationMenuPrimitive.Viewport
         data-slot="navigation-menu-viewport"
         className={cn(
           "origin-top-center relative mt-1.5 h-(--radix-navigation-menu-viewport-height) w-full overflow-hidden border border-border/30 bg-popover text-popover-foreground shadow-md duration-100 md:w-(--radix-navigation-menu-viewport-width) data-open:animate-in data-open:zoom-in-90 data-closed:animate-out data-closed:zoom-out-90",
-          className
+          className,
         )}
         {...props}
       />
     </div>
-  )
+  );
 }
 
 function NavigationMenuLink({
@@ -129,11 +129,11 @@ function NavigationMenuLink({
       data-slot="navigation-menu-link"
       className={cn(
         "flex items-center gap-2 p-2 text-sm transition-all outline-none hover:bg-secondary hover:text-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary in-data-[slot=navigation-menu-content]:rounded-sm data-active:bg-primary/15 data-active:text-primary [&_svg:not([class*='size-'])]:size-4",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function NavigationMenuIndicator({
@@ -145,13 +145,13 @@ function NavigationMenuIndicator({
       data-slot="navigation-menu-indicator"
       className={cn(
         "top-full z-1 flex h-1.5 items-end justify-center overflow-hidden data-[state=hidden]:animate-out data-[state=hidden]:fade-out data-[state=visible]:animate-in data-[state=visible]:fade-in",
-        className
+        className,
       )}
       {...props}
     >
       <div className="relative top-[60%] h-2 w-2 rotate-45 rounded-tl-sm bg-border shadow-md" />
     </NavigationMenuPrimitive.Indicator>
-  )
+  );
 }
 
 export {
@@ -164,4 +164,4 @@ export {
   NavigationMenuIndicator,
   NavigationMenuViewport,
   navigationMenuTriggerStyle,
-}
+};

apps/gui/src/components/ui/select.tsx

@@ -1,12 +1,12 @@
-"use client"
+"use client";
 
-import * as React from "react"
-import { Select as SelectPrimitive } from "@base-ui/react/select"
-import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from "lucide-react"
+import * as React from "react";
+import { Select as SelectPrimitive } from "@base-ui/react/select";
+import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from "lucide-react";
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
-const Select = SelectPrimitive.Root
+const Select = SelectPrimitive.Root;
 
 function SelectGroup({ className, ...props }: SelectPrimitive.Group.Props) {
   return (
@@ -15,7 +15,7 @@ function SelectGroup({ className, ...props }: SelectPrimitive.Group.Props) {
       className={cn("scroll-my-1 p-1", className)}
       {...props}
     />
-  )
+  );
 }
 
 function SelectValue({ className, ...props }: SelectPrimitive.Value.Props) {
@@ -25,7 +25,7 @@ function SelectValue({ className, ...props }: SelectPrimitive.Value.Props) {
       className={cn("flex flex-1 text-left", className)}
       {...props}
     />
-  )
+  );
 }
 
 function SelectTrigger({
@@ -34,7 +34,7 @@ function SelectTrigger({
   children,
   ...props
 }: SelectPrimitive.Trigger.Props & {
-  size?: "sm" | "default"
+  size?: "sm" | "default";
 }) {
   return (
     <SelectPrimitive.Trigger
@@ -42,7 +42,7 @@ function SelectTrigger({
       data-size={size}
       className={cn(
         "flex w-fit items-center justify-between gap-1.5 rounded border border-border/30 bg-input py-2 pr-2 pl-2.5 text-sm whitespace-nowrap shadow-sm transition-colors outline-none select-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive data-placeholder:text-muted-foreground data-[size=default]:h-8 data-[size=sm]:h-7 data-[size=sm]:rounded *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-1.5 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
-        className
+        className,
       )}
       {...props}
     >
@@ -53,7 +53,7 @@ function SelectTrigger({
         }
       />
     </SelectPrimitive.Trigger>
-  )
+  );
 }
 
 function SelectContent({
@@ -83,7 +83,10 @@ function SelectContent({
         <SelectPrimitive.Popup
           data-slot="select-content"
           data-align-trigger={alignItemWithTrigger}
-          className={cn("relative isolate z-50 max-h-(--available-height) w-(--anchor-width) min-w-36 origin-(--transform-origin) overflow-x-hidden overflow-y-auto rounded border border-border/30 bg-popover text-popover-foreground shadow-md duration-100 data-[align-trigger=true]:animate-none data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", className )}
+          className={cn(
+            "relative isolate z-50 max-h-(--available-height) w-(--anchor-width) min-w-36 origin-(--transform-origin) overflow-x-hidden overflow-y-auto rounded border border-border/30 bg-popover text-popover-foreground shadow-md duration-100 data-[align-trigger=true]:animate-none data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+            className,
+          )}
           {...props}
         >
           <SelectScrollUpButton />
@@ -92,7 +95,7 @@ function SelectContent({
         </SelectPrimitive.Popup>
       </SelectPrimitive.Positioner>
     </SelectPrimitive.Portal>
-  )
+  );
 }
 
 function SelectLabel({
@@ -105,7 +108,7 @@ function SelectLabel({
       className={cn("px-1.5 py-1 text-xs text-muted-foreground", className)}
       {...props}
     />
-  )
+  );
 }
 
 function SelectItem({
@@ -118,7 +121,7 @@ function SelectItem({
       data-slot="select-item"
       className={cn(
         "relative flex w-full cursor-default items-center gap-1.5 rounded-sm py-1 pr-8 pl-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
-        className
+        className,
       )}
       {...props}
     >
@@ -133,7 +136,7 @@ function SelectItem({
         <CheckIcon className="pointer-events-none" />
       </SelectPrimitive.ItemIndicator>
     </SelectPrimitive.Item>
-  )
+  );
 }
 
 function SelectSeparator({
@@ -146,7 +149,7 @@ function SelectSeparator({
       className={cn("pointer-events-none -mx-1 my-1 h-px bg-border", className)}
       {...props}
     />
-  )
+  );
 }
 
 function SelectScrollUpButton({
@@ -158,13 +161,13 @@ function SelectScrollUpButton({
       data-slot="select-scroll-up-button"
       className={cn(
         "top-0 z-10 flex w-full cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-4",
-        className
+        className,
       )}
       {...props}
     >
       <ChevronUpIcon />
     </SelectPrimitive.ScrollUpArrow>
-  )
+  );
 }
 
 function SelectScrollDownButton({
@@ -176,13 +179,13 @@ function SelectScrollDownButton({
       data-slot="select-scroll-down-button"
       className={cn(
         "bottom-0 z-10 flex w-full cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-4",
-        className
+        className,
       )}
       {...props}
     >
       <ChevronDownIcon />
     </SelectPrimitive.ScrollDownArrow>
-  )
+  );
 }
 
 export {
@@ -196,4 +199,4 @@ export {
   SelectSeparator,
   SelectTrigger,
   SelectValue,
-}
+};

apps/gui/src/components/ui/separator.tsx

@@ -1,9 +1,9 @@
-"use client"
+"use client";
 
-import * as React from "react"
-import * as SeparatorPrimitive from "@radix-ui/react-separator"
+import * as React from "react";
+import * as SeparatorPrimitive from "@radix-ui/react-separator";
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
 const Separator = React.forwardRef<
   React.ElementRef<typeof SeparatorPrimitive.Root>,
@@ -11,7 +11,7 @@ const Separator = React.forwardRef<
 >(
   (
     { className, orientation = "horizontal", decorative = true, ...props },
-    ref
+    ref,
   ) => (
     <SeparatorPrimitive.Root
       ref={ref}
@@ -20,12 +20,12 @@ const Separator = React.forwardRef<
       className={cn(
         "shrink-0 bg-border",
         orientation === "horizontal" ? "h-[1px] w-full" : "h-full w-[1px]",
-        className
+        className,
       )}
       {...props}
     />
-  )
-)
-Separator.displayName = SeparatorPrimitive.Root.displayName
+  ),
+);
+Separator.displayName = SeparatorPrimitive.Root.displayName;
 
-export { Separator }
+export { Separator };

apps/gui/src/components/ui/sheet.tsx

@@ -1,19 +1,19 @@
-"use client"
+"use client";
 
-import * as React from "react"
-import * as SheetPrimitive from "@radix-ui/react-dialog"
-import { cva, type VariantProps } from "class-variance-authority"
-import { X } from "lucide-react"
+import * as React from "react";
+import * as SheetPrimitive from "@radix-ui/react-dialog";
+import { cva, type VariantProps } from "class-variance-authority";
+import { X } from "lucide-react";
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
-const Sheet = SheetPrimitive.Root
+const Sheet = SheetPrimitive.Root;
 
-const SheetTrigger = SheetPrimitive.Trigger
+const SheetTrigger = SheetPrimitive.Trigger;
 
-const SheetClose = SheetPrimitive.Close
+const SheetClose = SheetPrimitive.Close;
 
-const SheetPortal = SheetPrimitive.Portal
+const SheetPortal = SheetPrimitive.Portal;
 
 const SheetOverlay = React.forwardRef<
   React.ElementRef<typeof SheetPrimitive.Overlay>,
@@ -22,13 +22,13 @@ const SheetOverlay = React.forwardRef<
   <SheetPrimitive.Overlay
     className={cn(
       "fixed inset-0 z-50 bg-black/80  data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
-      className
+      className,
     )}
     {...props}
     ref={ref}
   />
-))
-SheetOverlay.displayName = SheetPrimitive.Overlay.displayName
+));
+SheetOverlay.displayName = SheetPrimitive.Overlay.displayName;
 
 const sheetVariants = cva(
   "fixed z-50 gap-4 bg-background p-6 shadow-lg transition ease-in-out data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:duration-300 data-[state=open]:duration-500",
@@ -46,11 +46,12 @@ const sheetVariants = cva(
     defaultVariants: {
       side: "right",
     },
-  }
-)
+  },
+);
 
 interface SheetContentProps
-  extends React.ComponentPropsWithoutRef<typeof SheetPrimitive.Content>,
+  extends
+    React.ComponentPropsWithoutRef<typeof SheetPrimitive.Content>,
     VariantProps<typeof sheetVariants> {}
 
 const SheetContent = React.forwardRef<
@@ -71,8 +72,8 @@ const SheetContent = React.forwardRef<
       </SheetPrimitive.Close>
     </SheetPrimitive.Content>
   </SheetPortal>
-))
-SheetContent.displayName = SheetPrimitive.Content.displayName
+));
+SheetContent.displayName = SheetPrimitive.Content.displayName;
 
 const SheetHeader = ({
   className,
@@ -81,12 +82,12 @@ const SheetHeader = ({
   <div
     className={cn(
       "flex flex-col space-y-2 text-center sm:text-left",
-      className
+      className,
     )}
     {...props}
   />
-)
-SheetHeader.displayName = "SheetHeader"
+);
+SheetHeader.displayName = "SheetHeader";
 
 const SheetFooter = ({
   className,
@@ -95,12 +96,12 @@ const SheetFooter = ({
   <div
     className={cn(
       "flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2",
-      className
+      className,
     )}
     {...props}
   />
-)
-SheetFooter.displayName = "SheetFooter"
+);
+SheetFooter.displayName = "SheetFooter";
 
 const SheetTitle = React.forwardRef<
   React.ElementRef<typeof SheetPrimitive.Title>,
@@ -111,8 +112,8 @@ const SheetTitle = React.forwardRef<
     className={cn("text-lg font-semibold text-foreground", className)}
     {...props}
   />
-))
-SheetTitle.displayName = SheetPrimitive.Title.displayName
+));
+SheetTitle.displayName = SheetPrimitive.Title.displayName;
 
 const SheetDescription = React.forwardRef<
   React.ElementRef<typeof SheetPrimitive.Description>,
@@ -123,8 +124,8 @@ const SheetDescription = React.forwardRef<
     className={cn("text-sm text-muted-foreground", className)}
     {...props}
   />
-))
-SheetDescription.displayName = SheetPrimitive.Description.displayName
+));
+SheetDescription.displayName = SheetPrimitive.Description.displayName;
 
 export {
   Sheet,
@@ -137,4 +138,4 @@ export {
   SheetFooter,
   SheetTitle,
   SheetDescription,
-}
+};

apps/gui/src/components/ui/sidebar.tsx

@@ -1,55 +1,55 @@
-"use client"
+"use client";
 
-import * as React from "react"
-import { cva, type VariantProps } from "class-variance-authority"
-import { PanelLeftIcon } from "lucide-react"
-import { Slot } from "radix-ui"
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { PanelLeftIcon } from "lucide-react";
+import { Slot } from "radix-ui";
 
-import { cn } from "@/lib/utils"
-import { useIsMobile } from "@/hooks/use-mobile"
-import { Button } from "@/components/ui/button"
-import { Input } from "@/components/ui/input"
-import { Separator } from "@/components/ui/separator"
+import { cn } from "@/lib/utils";
+import { useIsMobile } from "@/hooks/use-mobile";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Separator } from "@/components/ui/separator";
 import {
   Sheet,
   SheetContent,
   SheetDescription,
   SheetHeader,
   SheetTitle,
-} from "@/components/ui/sheet"
-import { Skeleton } from "@/components/ui/skeleton"
+} from "@/components/ui/sheet";
+import { Skeleton } from "@/components/ui/skeleton";
 import {
   Tooltip,
   TooltipContent,
   TooltipTrigger,
-} from "@/components/ui/tooltip"
+} from "@/components/ui/tooltip";
 
-const SIDEBAR_COOKIE_NAME = "sidebar_state"
-const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7
-const SIDEBAR_WIDTH = "16rem"
-const SIDEBAR_WIDTH_MOBILE = "18rem"
-const SIDEBAR_WIDTH_ICON = "3rem"
-const SIDEBAR_KEYBOARD_SHORTCUT = "b"
+const SIDEBAR_COOKIE_NAME = "sidebar_state";
+const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7;
+const SIDEBAR_WIDTH = "16rem";
+const SIDEBAR_WIDTH_MOBILE = "18rem";
+const SIDEBAR_WIDTH_ICON = "3rem";
+const SIDEBAR_KEYBOARD_SHORTCUT = "b";
 
 type SidebarContextProps = {
-  state: "expanded" | "collapsed"
-  open: boolean
-  setOpen: (open: boolean) => void
-  openMobile: boolean
-  setOpenMobile: (open: boolean) => void
-  isMobile: boolean
-  toggleSidebar: () => void
-}
+  state: "expanded" | "collapsed";
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  openMobile: boolean;
+  setOpenMobile: (open: boolean) => void;
+  isMobile: boolean;
+  toggleSidebar: () => void;
+};
 
-const SidebarContext = React.createContext<SidebarContextProps | null>(null)
+const SidebarContext = React.createContext<SidebarContextProps | null>(null);
 
 function useSidebar() {
-  const context = React.useContext(SidebarContext)
+  const context = React.useContext(SidebarContext);
   if (!context) {
-    throw new Error("useSidebar must be used within a SidebarProvider.")
+    throw new Error("useSidebar must be used within a SidebarProvider.");
   }
 
-  return context
+  return context;
 }
 
 function SidebarProvider({
@@ -61,36 +61,36 @@ function SidebarProvider({
   children,
   ...props
 }: React.ComponentProps<"div"> & {
-  defaultOpen?: boolean
-  open?: boolean
-  onOpenChange?: (open: boolean) => void
+  defaultOpen?: boolean;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
 }) {
-  const isMobile = useIsMobile()
-  const [openMobile, setOpenMobile] = React.useState(false)
+  const isMobile = useIsMobile();
+  const [openMobile, setOpenMobile] = React.useState(false);
 
   // This is the internal state of the sidebar.
   // We use openProp and setOpenProp for control from outside the component.
-  const [_open, _setOpen] = React.useState(defaultOpen)
-  const open = openProp ?? _open
+  const [_open, _setOpen] = React.useState(defaultOpen);
+  const open = openProp ?? _open;
   const setOpen = React.useCallback(
     (value: boolean | ((value: boolean) => boolean)) => {
-      const openState = typeof value === "function" ? value(open) : value
+      const openState = typeof value === "function" ? value(open) : value;
       if (setOpenProp) {
-        setOpenProp(openState)
+        setOpenProp(openState);
       } else {
-        _setOpen(openState)
+        _setOpen(openState);
       }
 
       // This sets the cookie to keep the sidebar state.
-      document.cookie = `${SIDEBAR_COOKIE_NAME}=${openState}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}`
+      document.cookie = `${SIDEBAR_COOKIE_NAME}=${openState}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}`;
     },
-    [setOpenProp, open]
-  )
+    [setOpenProp, open],
+  );
 
   // Helper to toggle the sidebar.
   const toggleSidebar = React.useCallback(() => {
-    return isMobile ? setOpenMobile((open) => !open) : setOpen((open) => !open)
-  }, [isMobile, setOpen, setOpenMobile])
+    return isMobile ? setOpenMobile((open) => !open) : setOpen((open) => !open);
+  }, [isMobile, setOpen, setOpenMobile]);
 
   // Adds a keyboard shortcut to toggle the sidebar.
   React.useEffect(() => {
@@ -99,18 +99,18 @@ function SidebarProvider({
         event.key === SIDEBAR_KEYBOARD_SHORTCUT &&
         (event.metaKey || event.ctrlKey)
       ) {
-        event.preventDefault()
-        toggleSidebar()
+        event.preventDefault();
+        toggleSidebar();
       }
-    }
+    };
 
-    window.addEventListener("keydown", handleKeyDown)
-    return () => window.removeEventListener("keydown", handleKeyDown)
-  }, [toggleSidebar])
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [toggleSidebar]);
 
   // We add a state so that we can do data-state="expanded" or "collapsed".
   // This makes it easier to style the sidebar with Tailwind classes.
-  const state = open ? "expanded" : "collapsed"
+  const state = open ? "expanded" : "collapsed";
 
   const contextValue = React.useMemo<SidebarContextProps>(
     () => ({
@@ -122,8 +122,8 @@ function SidebarProvider({
       setOpenMobile,
       toggleSidebar,
     }),
-    [state, open, setOpen, isMobile, openMobile, setOpenMobile, toggleSidebar]
-  )
+    [state, open, setOpen, isMobile, openMobile, setOpenMobile, toggleSidebar],
+  );
 
   return (
     <SidebarContext.Provider value={contextValue}>
@@ -138,14 +138,14 @@ function SidebarProvider({
         }
         className={cn(
           "group/sidebar-wrapper flex min-h-svh w-full has-data-[variant=inset]:bg-sidebar",
-          className
+          className,
         )}
         {...props}
       >
         {children}
       </div>
     </SidebarContext.Provider>
-  )
+  );
 }
 
 function Sidebar({
@@ -157,11 +157,11 @@ function Sidebar({
   dir,
   ...props
 }: React.ComponentProps<"div"> & {
-  side?: "left" | "right"
-  variant?: "sidebar" | "floating" | "inset"
-  collapsible?: "offcanvas" | "icon" | "none"
+  side?: "left" | "right";
+  variant?: "sidebar" | "floating" | "inset";
+  collapsible?: "offcanvas" | "icon" | "none";
 }) {
-  const { isMobile, state, openMobile, setOpenMobile } = useSidebar()
+  const { isMobile, state, openMobile, setOpenMobile } = useSidebar();
 
   if (collapsible === "none") {
     return (
@@ -169,13 +169,13 @@ function Sidebar({
         data-slot="sidebar"
         className={cn(
           "flex h-full w-(--sidebar-width) flex-col bg-card text-sidebar-foreground",
-          className
+          className,
         )}
         {...props}
       >
         {children}
       </div>
-    )
+    );
   }
 
   if (isMobile) {
@@ -201,7 +201,7 @@ function Sidebar({
           <div className="flex h-full w-full flex-col">{children}</div>
         </SheetContent>
       </Sheet>
-    )
+    );
   }
 
   return (
@@ -222,7 +222,7 @@ function Sidebar({
           "group-data-[side=right]:rotate-180",
           variant === "floating" || variant === "inset"
             ? "group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4)))]"
-            : "group-data-[collapsible=icon]:w-(--sidebar-width-icon)"
+            : "group-data-[collapsible=icon]:w-(--sidebar-width-icon)",
         )}
       />
       <div
@@ -234,7 +234,7 @@ function Sidebar({
           variant === "floating" || variant === "inset"
             ? "p-2 group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4))+2px)]"
             : "group-data-[collapsible=icon]:w-(--sidebar-width-icon) group-data-[side=left]:border-r-2 group-data-[side=right]:border-l-2",
-          className
+          className,
         )}
         {...props}
       >
@@ -247,7 +247,7 @@ function Sidebar({
         </div>
       </div>
     </div>
-  )
+  );
 }
 
 function SidebarTrigger({
@@ -255,7 +255,7 @@ function SidebarTrigger({
   onClick,
   ...props
 }: React.ComponentProps<typeof Button>) {
-  const { toggleSidebar } = useSidebar()
+  const { toggleSidebar } = useSidebar();
 
   return (
     <Button
@@ -265,19 +265,19 @@ function SidebarTrigger({
       size="icon"
       className={cn(className)}
       onClick={(event) => {
-        onClick?.(event)
-        toggleSidebar()
+        onClick?.(event);
+        toggleSidebar();
       }}
       {...props}
     >
       <PanelLeftIcon />
       <span className="sr-only">Toggle Sidebar</span>
     </Button>
-  )
+  );
 }
 
 function SidebarRail({ className, ...props }: React.ComponentProps<"button">) {
-  const { toggleSidebar } = useSidebar()
+  const { toggleSidebar } = useSidebar();
 
   return (
     <button
@@ -294,11 +294,11 @@ function SidebarRail({ className, ...props }: React.ComponentProps<"button">) {
         "group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full hover:group-data-[collapsible=offcanvas]:bg-sidebar",
         "[[data-side=left][data-collapsible=offcanvas]_&]:-right-2",
         "[[data-side=right][data-collapsible=offcanvas]_&]:-left-2",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function SidebarInset({ className, ...props }: React.ComponentProps<"main">) {
@@ -307,11 +307,11 @@ function SidebarInset({ className, ...props }: React.ComponentProps<"main">) {
       data-slot="sidebar-inset"
       className={cn(
         "relative flex w-full flex-1 flex-col bg-background md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:ml-0 md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:shadow-sm md:peer-data-[variant=inset]:peer-data-[state=collapsed]:ml-2",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function SidebarInput({
@@ -325,7 +325,7 @@ function SidebarInput({
       className={cn("h-8 w-full bg-background shadow-none", className)}
       {...props}
     />
-  )
+  );
 }
 
 function SidebarHeader({ className, ...props }: React.ComponentProps<"div">) {
@@ -336,7 +336,7 @@ function SidebarHeader({ className, ...props }: React.ComponentProps<"div">) {
       className={cn("flex flex-col gap-2 p-2", className)}
       {...props}
     />
-  )
+  );
 }
 
 function SidebarFooter({ className, ...props }: React.ComponentProps<"div">) {
@@ -347,7 +347,7 @@ function SidebarFooter({ className, ...props }: React.ComponentProps<"div">) {
       className={cn("flex flex-col gap-2 p-2", className)}
       {...props}
     />
-  )
+  );
 }
 
 function SidebarSeparator({
@@ -361,7 +361,7 @@ function SidebarSeparator({
       className={cn("mx-2 w-auto bg-sidebar-border", className)}
       {...props}
     />
-  )
+  );
 }
 
 function SidebarContent({ className, ...props }: React.ComponentProps<"div">) {
@@ -371,11 +371,11 @@ function SidebarContent({ className, ...props }: React.ComponentProps<"div">) {
       data-sidebar="content"
       className={cn(
         "no-scrollbar flex min-h-0 flex-1 flex-col gap-0 overflow-auto group-data-[collapsible=icon]:overflow-hidden",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function SidebarGroup({ className, ...props }: React.ComponentProps<"div">) {
@@ -386,7 +386,7 @@ function SidebarGroup({ className, ...props }: React.ComponentProps<"div">) {
       className={cn("relative flex w-full min-w-0 flex-col p-2", className)}
       {...props}
     />
-  )
+  );
 }
 
 function SidebarGroupLabel({
@@ -394,7 +394,7 @@ function SidebarGroupLabel({
   asChild = false,
   ...props
 }: React.ComponentProps<"div"> & { asChild?: boolean }) {
-  const Comp = asChild ? Slot.Root : "div"
+  const Comp = asChild ? Slot.Root : "div";
 
   return (
     <Comp
@@ -402,11 +402,11 @@ function SidebarGroupLabel({
       data-sidebar="group-label"
       className={cn(
         "flex h-8 shrink-0 items-center rounded-md px-2 text-xs font-medium text-sidebar-foreground/70 ring-sidebar-ring outline-hidden transition-[margin,opacity] duration-200 ease-linear group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0 focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function SidebarGroupAction({
@@ -414,7 +414,7 @@ function SidebarGroupAction({
   asChild = false,
   ...props
 }: React.ComponentProps<"button"> & { asChild?: boolean }) {
-  const Comp = asChild ? Slot.Root : "button"
+  const Comp = asChild ? Slot.Root : "button";
 
   return (
     <Comp
@@ -422,11 +422,11 @@ function SidebarGroupAction({
       data-sidebar="group-action"
       className={cn(
         "absolute top-3.5 right-3 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-sidebar-foreground ring-sidebar-ring outline-hidden transition-transform group-data-[collapsible=icon]:hidden after:absolute after:-inset-2 hover:bg-accent hover:text-accent-foreground focus-visible:ring-2 md:after:hidden [&>svg]:size-4 [&>svg]:shrink-0",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function SidebarGroupContent({
@@ -440,7 +440,7 @@ function SidebarGroupContent({
       className={cn("w-full text-sm", className)}
       {...props}
     />
-  )
+  );
 }
 
 function SidebarMenu({ className, ...props }: React.ComponentProps<"ul">) {
@@ -451,7 +451,7 @@ function SidebarMenu({ className, ...props }: React.ComponentProps<"ul">) {
       className={cn("flex w-full min-w-0 flex-col gap-0", className)}
       {...props}
     />
-  )
+  );
 }
 
 function SidebarMenuItem({ className, ...props }: React.ComponentProps<"li">) {
@@ -462,7 +462,7 @@ function SidebarMenuItem({ className, ...props }: React.ComponentProps<"li">) {
       className={cn("group/menu-item relative", className)}
       {...props}
     />
-  )
+  );
 }
 
 const sidebarMenuButtonVariants = cva(
@@ -484,8 +484,8 @@ const sidebarMenuButtonVariants = cva(
       variant: "default",
       size: "default",
     },
-  }
-)
+  },
+);
 
 function SidebarMenuButton({
   asChild = false,
@@ -496,12 +496,12 @@ function SidebarMenuButton({
   className,
   ...props
 }: React.ComponentProps<"button"> & {
-  asChild?: boolean
-  isActive?: boolean
-  tooltip?: string | React.ComponentProps<typeof TooltipContent>
+  asChild?: boolean;
+  isActive?: boolean;
+  tooltip?: string | React.ComponentProps<typeof TooltipContent>;
 } & VariantProps<typeof sidebarMenuButtonVariants>) {
-  const Comp = asChild ? Slot.Root : "button"
-  const { isMobile, state } = useSidebar()
+  const Comp = asChild ? Slot.Root : "button";
+  const { isMobile, state } = useSidebar();
 
   const button = (
     <Comp
@@ -512,16 +512,16 @@ function SidebarMenuButton({
       className={cn(sidebarMenuButtonVariants({ variant, size }), className)}
       {...props}
     />
-  )
+  );
 
   if (!tooltip) {
-    return button
+    return button;
   }
 
   if (typeof tooltip === "string") {
     tooltip = {
       children: tooltip,
-    }
+    };
   }
 
   return (
@@ -534,7 +534,7 @@ function SidebarMenuButton({
         {...tooltip}
       />
     </Tooltip>
-  )
+  );
 }
 
 function SidebarMenuAction({
@@ -543,10 +543,10 @@ function SidebarMenuAction({
   showOnHover = false,
   ...props
 }: React.ComponentProps<"button"> & {
-  asChild?: boolean
-  showOnHover?: boolean
+  asChild?: boolean;
+  showOnHover?: boolean;
 }) {
-  const Comp = asChild ? Slot.Root : "button"
+  const Comp = asChild ? Slot.Root : "button";
 
   return (
     <Comp
@@ -556,11 +556,11 @@ function SidebarMenuAction({
         "absolute top-1.5 right-1 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-sidebar-foreground ring-sidebar-ring outline-hidden transition-transform group-data-[collapsible=icon]:hidden peer-hover/menu-button:text-sidebar-accent-foreground peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5 peer-data-[size=sm]/menu-button:top-1 after:absolute after:-inset-2 hover:bg-accent hover:text-accent-foreground focus-visible:ring-2 md:after:hidden [&>svg]:size-4 [&>svg]:shrink-0",
         showOnHover &&
           "group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 peer-data-active/menu-button:text-sidebar-accent-foreground aria-expanded:opacity-100 md:opacity-0",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function SidebarMenuBadge({
@@ -573,11 +573,11 @@ function SidebarMenuBadge({
       data-sidebar="menu-badge"
       className={cn(
         "pointer-events-none absolute right-1 flex h-5 min-w-5 items-center justify-center rounded-md px-1 text-xs font-medium text-sidebar-foreground tabular-nums select-none group-data-[collapsible=icon]:hidden peer-hover/menu-button:text-sidebar-accent-foreground peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5 peer-data-[size=sm]/menu-button:top-1 peer-data-active/menu-button:text-sidebar-accent-foreground",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function SidebarMenuSkeleton({
@@ -585,12 +585,12 @@ function SidebarMenuSkeleton({
   showIcon = false,
   ...props
 }: React.ComponentProps<"div"> & {
-  showIcon?: boolean
+  showIcon?: boolean;
 }) {
   // Random width between 50 to 90%.
   const [width] = React.useState(() => {
-    return `${Math.floor(Math.random() * 40) + 50}%`
-  })
+    return `${Math.floor(Math.random() * 40) + 50}%`;
+  });
 
   return (
     <div
@@ -615,7 +615,7 @@ function SidebarMenuSkeleton({
         }
       />
     </div>
-  )
+  );
 }
 
 function SidebarMenuSub({ className, ...props }: React.ComponentProps<"ul">) {
@@ -625,11 +625,11 @@ function SidebarMenuSub({ className, ...props }: React.ComponentProps<"ul">) {
       data-sidebar="menu-sub"
       className={cn(
         "mx-3.5 flex min-w-0 translate-x-px flex-col gap-1 border-l border-sidebar-border px-2.5 py-0.5 group-data-[collapsible=icon]:hidden",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function SidebarMenuSubItem({
@@ -643,7 +643,7 @@ function SidebarMenuSubItem({
       className={cn("group/menu-sub-item relative", className)}
       {...props}
     />
-  )
+  );
 }
 
 function SidebarMenuSubButton({
@@ -653,11 +653,11 @@ function SidebarMenuSubButton({
   className,
   ...props
 }: React.ComponentProps<"a"> & {
-  asChild?: boolean
-  size?: "sm" | "md"
-  isActive?: boolean
+  asChild?: boolean;
+  size?: "sm" | "md";
+  isActive?: boolean;
 }) {
-  const Comp = asChild ? Slot.Root : "a"
+  const Comp = asChild ? Slot.Root : "a";
 
   return (
     <Comp
@@ -667,11 +667,11 @@ function SidebarMenuSubButton({
       data-active={isActive}
       className={cn(
         "flex h-7 min-w-0 -translate-x-px items-center gap-2 overflow-hidden rounded-md px-2 text-sidebar-foreground ring-sidebar-ring outline-hidden group-data-[collapsible=icon]:hidden hover:bg-accent hover:text-accent-foreground focus-visible:ring-2 active:bg-accent active:text-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[size=md]:text-sm data-[size=sm]:text-xs data-active:bg-primary data-active:text-primary-foreground [&>span:last-child]:truncate [&>svg]:size-4 [&>svg]:shrink-0 [&>svg]:text-sidebar-accent-foreground",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 export {
@@ -699,4 +699,4 @@ export {
   SidebarSeparator,
   SidebarTrigger,
   useSidebar,
-}
+};

apps/gui/src/components/ui/skeleton.tsx

@@ -1,4 +1,4 @@
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
 function Skeleton({
   className,
@@ -10,7 +10,7 @@ function Skeleton({
       className={cn("animate-pulse rounded-md bg-muted/60", className)}
       {...props}
     />
-  )
+  );
 }
 
-export { Skeleton }
+export { Skeleton };

apps/gui/src/components/ui/spinner.tsx

@@ -1,6 +1,6 @@
-import { Loader2Icon } from "lucide-react"
+import { Loader2Icon } from "lucide-react";
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
 function Spinner({ className, ...props }: React.ComponentProps<"svg">) {
   return (
@@ -11,7 +11,7 @@ function Spinner({ className, ...props }: React.ComponentProps<"svg">) {
       className={cn("size-4 animate-spin", className)}
       {...props}
     />
-  )
+  );
 }
 
-export { Spinner }
+export { Spinner };

apps/gui/src/components/ui/table.tsx

@@ -1,8 +1,8 @@
-"use client"
+"use client";
 
-import * as React from "react"
+import * as React from "react";
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
 function Table({ className, ...props }: React.ComponentProps<"table">) {
   return (
@@ -16,7 +16,7 @@ function Table({ className, ...props }: React.ComponentProps<"table">) {
         {...props}
       />
     </div>
-  )
+  );
 }
 
 function TableHeader({ className, ...props }: React.ComponentProps<"thead">) {
@@ -26,7 +26,7 @@ function TableHeader({ className, ...props }: React.ComponentProps<"thead">) {
       className={cn("[&_tr]:border-b-2", className)}
       {...props}
     />
-  )
+  );
 }
 
 function TableBody({ className, ...props }: React.ComponentProps<"tbody">) {
@@ -36,7 +36,7 @@ function TableBody({ className, ...props }: React.ComponentProps<"tbody">) {
       className={cn("[&_tr:last-child]:border-0", className)}
       {...props}
     />
-  )
+  );
 }
 
 function TableFooter({ className, ...props }: React.ComponentProps<"tfoot">) {
@@ -45,11 +45,11 @@ function TableFooter({ className, ...props }: React.ComponentProps<"tfoot">) {
       data-slot="table-footer"
       className={cn(
         "border-t-2 bg-muted/50 font-medium [&>tr]:last:border-b-0",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function TableRow({ className, ...props }: React.ComponentProps<"tr">) {
@@ -58,11 +58,11 @@ function TableRow({ className, ...props }: React.ComponentProps<"tr">) {
       data-slot="table-row"
       className={cn(
         "border-b-2 transition-colors hover:bg-accent has-aria-expanded:bg-accent data-[state=selected]:bg-accent",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function TableHead({ className, ...props }: React.ComponentProps<"th">) {
@@ -71,11 +71,11 @@ function TableHead({ className, ...props }: React.ComponentProps<"th">) {
       data-slot="table-head"
       className={cn(
         "h-10 bg-muted px-2 text-left align-middle font-head font-medium whitespace-nowrap text-foreground [&:has([role=checkbox])]:pr-0",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function TableCell({ className, ...props }: React.ComponentProps<"td">) {
@@ -84,11 +84,11 @@ function TableCell({ className, ...props }: React.ComponentProps<"td">) {
       data-slot="table-cell"
       className={cn(
         "p-2 align-middle whitespace-nowrap [&:has([role=checkbox])]:pr-0",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function TableCaption({
@@ -101,7 +101,7 @@ function TableCaption({
       className={cn("mt-4 text-sm text-muted-foreground", className)}
       {...props}
     />
-  )
+  );
 }
 
 export {
@@ -113,4 +113,4 @@ export {
   TableRow,
   TableCell,
   TableCaption,
-}
+};

apps/gui/src/components/ui/tabs.tsx

@@ -1,10 +1,10 @@
-"use client"
+"use client";
 
-import * as React from "react"
-import { cva, type VariantProps } from "class-variance-authority"
-import { Tabs as TabsPrimitive } from "radix-ui"
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { Tabs as TabsPrimitive } from "radix-ui";
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
 function Tabs({
   className,
@@ -17,11 +17,11 @@ function Tabs({
       data-orientation={orientation}
       className={cn(
         "group/tabs flex gap-2 data-horizontal:flex-col",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 const tabsListVariants = cva(
@@ -36,8 +36,8 @@ const tabsListVariants = cva(
     defaultVariants: {
       variant: "default",
     },
-  }
-)
+  },
+);
 
 function TabsList({
   className,
@@ -52,7 +52,7 @@ function TabsList({
       className={cn(tabsListVariants({ variant }), className)}
       {...props}
     />
-  )
+  );
 }
 
 function TabsTrigger({
@@ -67,11 +67,11 @@ function TabsTrigger({
         "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-active:bg-transparent",
         "data-active:bg-primary data-active:text-primary-foreground group-data-[variant=line]/tabs-list:data-active:text-foreground",
         "after:absolute after:bg-foreground after:opacity-0 after:transition-opacity group-data-horizontal/tabs:after:inset-x-0 group-data-horizontal/tabs:after:bottom-[-5px] group-data-horizontal/tabs:after:h-1 group-data-vertical/tabs:after:inset-y-0 group-data-vertical/tabs:after:-right-1 group-data-vertical/tabs:after:w-1 group-data-[variant=line]/tabs-list:data-active:after:opacity-100",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function TabsContent({
@@ -84,7 +84,7 @@ function TabsContent({
       className={cn("flex-1 text-sm outline-none", className)}
       {...props}
     />
-  )
+  );
 }
 
-export { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants }
+export { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants };

apps/gui/src/components/ui/textarea.tsx

@@ -1,6 +1,6 @@
-import * as React from "react"
+import * as React from "react";
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
 function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
   return (
@@ -8,11 +8,11 @@ function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
       data-slot="textarea"
       className={cn(
         "flex field-sizing-content min-h-16 w-full rounded border-2 bg-input px-3 py-2 text-sm shadow-sm transition-colors outline-none placeholder:text-muted-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
-export { Textarea }
+export { Textarea };

apps/gui/src/components/ui/tooltip.tsx

@@ -1,15 +1,15 @@
-"use client"
+"use client";
 
-import * as React from "react"
-import * as TooltipPrimitive from "@radix-ui/react-tooltip"
+import * as React from "react";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
-const TooltipProvider = TooltipPrimitive.Provider
+const TooltipProvider = TooltipPrimitive.Provider;
 
-const Tooltip = TooltipPrimitive.Root
+const Tooltip = TooltipPrimitive.Root;
 
-const TooltipTrigger = TooltipPrimitive.Trigger
+const TooltipTrigger = TooltipPrimitive.Trigger;
 
 const TooltipContent = React.forwardRef<
   React.ElementRef<typeof TooltipPrimitive.Content>,
@@ -20,11 +20,11 @@ const TooltipContent = React.forwardRef<
     sideOffset={sideOffset}
     className={cn(
       "z-50 overflow-hidden rounded-md border bg-popover px-3 py-1.5 text-sm text-popover-foreground shadow-md animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 origin-[--radix-tooltip-content-transform-origin]",
-      className
+      className,
     )}
     {...props}
   />
-))
-TooltipContent.displayName = TooltipPrimitive.Content.displayName
+));
+TooltipContent.displayName = TooltipPrimitive.Content.displayName;
 
-export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider };

apps/gui/src/hooks/use-mobile.tsx

@@ -1,19 +1,21 @@
-import * as React from "react"
+import * as React from "react";
 
-const MOBILE_BREAKPOINT = 768
+const MOBILE_BREAKPOINT = 768;
 
 export function useIsMobile() {
-  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(
+    undefined,
+  );
 
   React.useEffect(() => {
-    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
     const onChange = () => {
-      setIsMobile(mql.matches)
-    }
-    mql.addEventListener("change", onChange)
-    setIsMobile(mql.matches)
-    return () => mql.removeEventListener("change", onChange)
-  }, [])
+      setIsMobile(mql.matches);
+    };
+    mql.addEventListener("change", onChange);
+    setIsMobile(mql.matches);
+    return () => mql.removeEventListener("change", onChange);
+  }, []);
 
-  return !!isMobile
+  return !!isMobile;
 }

apps/gui/src/lib/simulation-types.ts

@@ -46,6 +46,7 @@ export interface EntityInfo {
   id: string;
   name: string;
   isPlayer: boolean;
+  isAgent: boolean;
 }
 
 export interface WaitingContext {

apps/gui/src/lib/simulation.ts

@@ -1,971 +0,0 @@
-import dotenv from "dotenv";
-import Database from "better-sqlite3";
-import path from "path";
-import fs from "fs";
-import { SQLiteRepository } from "@omnia/core";
-
-// Load .env from monorepo root or apps/gui/
-const cwd = process.cwd();
-const envCandidates = [
-  path.resolve(cwd, ".env"),
-  path.resolve(cwd, "../../.env"),
-];
-for (const c of envCandidates) {
-  if (fs.existsSync(c) && fs.statSync(c).isFile()) {
-    dotenv.config({ path: c });
-    break;
-  }
-}
-
-import { BufferRepository, LedgerRepository, HandoffEngine, checkHandoffTrigger } from "@omnia/memory";
-import { Architect, AliasDeltaGenerator } from "@omnia/architect";
-import {
-  ActorAgent,
-  ActorPromptBuilder,
-  IActorProseGenerator,
-  buildBufferEntryForIntent,
-} from "@omnia/actor";
-import { GeminiProvider, ILLMProvider, MockLLMProvider, ProviderManager, OpenRouterProvider, IEmbeddingProvider, GeminiEmbeddingProvider, MockEmbeddingProvider, ModelProviderInstance } from "@omnia/llm";
-import { ScenarioLoader } from "@omnia/scenario";
-
-import type {
-  IntentInfo,
-  LogEntry,
-  EntityInfo,
-  WaitingContext,
-  SimSnapshot,
-} from "./simulation-types.js";
-
-export type { SimSnapshot, EntityInfo, LogEntry, IntentInfo, WaitingContext };
-
-class FixedProseGenerator implements IActorProseGenerator {
-  constructor(private prose: string) {}
-
-  async generate(
-    entityId: string,
-    systemPrompt: string,
-    userContext: string,
-  ): Promise<string> {
-    void entityId;
-    void systemPrompt;
-    void userContext;
-    return this.prose;
-  }
-}
-
-interface SavedState {
-  scenarioName: string;
-  scenarioDescription: string;
-  turn: number;
-  maxTurns: number;
-  entities: EntityInfo[];
-  playerEntityId: string | undefined;
-  entityIndex: number;
-  status: "running" | "waiting_player" | "done" | "error";
-  error?: string;
-  waitingEntity?: WaitingContext;
-  aliasDoneForTurn: boolean;
-  log: LogEntry[];
-  providerMappings: Record<string, string>;
-}
-
-function loadSessionState(db: Database.Database, id: string): SavedState | null {
-  try {
-    db.prepare(`
-      CREATE TABLE IF NOT EXISTS gui_meta (
-        id TEXT PRIMARY KEY,
-        state_json TEXT
-      )
-    `).run();
-    const row = db.prepare(`SELECT state_json FROM gui_meta WHERE id = ?`).get(id) as { state_json: string } | undefined;
-    return row ? (JSON.parse(row.state_json) as SavedState) : null;
-  } catch {
-    return null;
-  }
-}
-
-interface SimSession {
-  db: Database.Database;
-  dbPath: string;
-  coreRepo: SQLiteRepository;
-  bufferRepo: BufferRepository;
-  ledgerRepo: LedgerRepository;
-  worldInstanceId: string;
-  scenarioName: string;
-  scenarioDescription: string;
-  turn: number;
-  maxTurns: number;
-  entities: EntityInfo[];
-  playerEntityId: string | undefined;
-  entityIndex: number;
-  actorProvider: ILLMProvider;
-  validatorProvider: ILLMProvider;
-  decoderProvider: ILLMProvider;
-  timedeltaProvider: ILLMProvider;
-  handoffProvider: ILLMProvider;
-  embeddingProvider: IEmbeddingProvider;
-  architect: Architect;
-  aliasGenerator: AliasDeltaGenerator;
-  log: LogEntry[];
-  status: "running" | "waiting_player" | "done" | "error";
-  error?: string;
-  waitingEntity?: WaitingContext;
-  aliasDoneForTurn: boolean;
-  providerMappings: Record<string, string>;
-}
-
-class SimulationManager {
-  private sessions = new Map<string, SimSession>();
-
-  async create(
-    scenarioPath: string,
-    playEntityName?: string,
-    providerInstanceId?: string,
-  ): Promise<SimSnapshot> {
-    let activeInstance: ModelProviderInstance | null = providerInstanceId
-      ? ProviderManager.list().find((p) => p.id === providerInstanceId) || null
-      : ProviderManager.getActive("generative");
-
-    if (!activeInstance) {
-      const envKey = process.env.GOOGLE_API_KEY;
-      if (envKey) {
-        activeInstance = ProviderManager.create("Default (Env)", "google-genai", envKey, undefined, "generative");
-      }
-    }
-    if (!activeInstance) {
-      return {
-        id: "",
-        status: "error",
-        turn: 0,
-        maxTurns: 20,
-        scenarioName: "",
-        scenarioDescription: "",
-        entities: [],
-        log: [],
-        entityIndex: 0,
-        error: "No active LLM Provider Instance found. Please configure a key in Settings first.",
-      };
-    }
-
-    const scenarioJson = JSON.parse(fs.readFileSync(scenarioPath, "utf-8"));
-    const id = `sim-${Date.now()}`;
-
-    const dbDir = path.resolve(process.cwd(), "data");
-    fs.mkdirSync(dbDir, { recursive: true });
-    const dbPath = path.join(dbDir, `${id}.db`);
-    const db = new Database(dbPath);
-    const coreRepo = new SQLiteRepository(db);
-    const bufferRepo = new BufferRepository(db);
-    const ledgerRepo = new LedgerRepository(db);
-    const loader = new ScenarioLoader(coreRepo, bufferRepo);
-
-    const worldInstanceId = id;
-    await loader.initializeWorld(scenarioJson, worldInstanceId);
-
-    const worldState = coreRepo.loadWorldState(worldInstanceId);
-    if (!worldState) {
-      db.close();
-      return {
-        id: "",
-        status: "error",
-        turn: 0,
-        maxTurns: 20,
-        scenarioName: "",
-        scenarioDescription: "",
-        entities: [],
-        log: [],
-        entityIndex: 0,
-        error: "Failed to load world state after initialization.",
-      };
-    }
-
-    const rawEntities = Array.from(worldState.entities.values());
-    const entityInfos: EntityInfo[] = rawEntities.map((e) => ({
-      id: e.id,
-      name: (e.attributes.get("name")?.getValue() as string) || e.id,
-      isPlayer: false,
-    }));
-
-    let playerEntityId: string | undefined;
-    if (playEntityName) {
-      let matched = worldState.getEntity(playEntityName);
-      if (!matched) {
-        for (const ent of rawEntities) {
-          const nameAttr = ent.attributes.get("name")?.getValue() as
-            | string
-            | undefined;
-          if (nameAttr?.toLowerCase() === playEntityName.toLowerCase()) {
-            matched = ent;
-            break;
-          }
-        }
-      }
-      if (!matched) {
-        for (const ent of rawEntities) {
-          const nameAttr = ent.attributes.get("name")?.getValue() as
-            | string
-            | undefined;
-          if (
-            nameAttr?.toLowerCase().includes(playEntityName.toLowerCase()) ||
-            ent.id.toLowerCase().includes(playEntityName.toLowerCase())
-          ) {
-            matched = ent;
-            break;
-          }
-        }
-      }
-      if (matched) {
-        playerEntityId = matched.id;
-        const info = entityInfos.find((e) => e.id === matched.id);
-        if (info) info.isPlayer = true;
-      }
-    }
-
-    const list = ProviderManager.list();
-    const active = ProviderManager.getActive("generative") || activeInstance;
-    const mappings = ProviderManager.getMappings();
-
-    const resolveProviderForTask = (task: string): ILLMProvider => {
-      const mappedId = mappings[task];
-      let inst = mappedId ? list.find((p) => p.id === mappedId) : null;
-      if (!inst || inst.type !== "generative") {
-        inst = active;
-      }
-
-      const key = inst ? inst.apiKey : (process.env.GOOGLE_API_KEY || "");
-      const providerName = inst ? inst.providerName : "google-genai";
-      const modelName = inst ? inst.modelName : undefined;
-      const instanceName = inst ? inst.name : undefined;
-      const maxContext = inst ? inst.maxContext : undefined;
-
-      if (providerName === "google-genai") {
-        return new GeminiProvider(key, modelName, instanceName, maxContext);
-      } else if (providerName === "openrouter") {
-        return new OpenRouterProvider(key, modelName, instanceName, maxContext);
-      } else {
-        return new MockLLMProvider([]);
-      }
-    };
-
-    const resolveEmbeddingProvider = (): IEmbeddingProvider => {
-      const mappedId = mappings["embeddings"];
-      let inst = mappedId ? list.find((p) => p.id === mappedId) : null;
-      if (!inst || inst.type !== "embedding") {
-        inst = ProviderManager.getActive("embedding");
-      }
-
-      const key = inst ? inst.apiKey : (process.env.GOOGLE_API_KEY || "");
-      const providerName = inst ? inst.providerName : "google-genai";
-      const modelName = inst ? inst.modelName : undefined;
-
-      if (providerName === "google-genai") {
-        return new GeminiEmbeddingProvider(key, modelName);
-      } else {
-        return new MockEmbeddingProvider(modelName);
-      }
-    };
-
-    const actorProvider = resolveProviderForTask("actor-prose");
-    const validatorProvider = resolveProviderForTask("llm-validator");
-    const decoderProvider = resolveProviderForTask("intent-decoder");
-    const timedeltaProvider = resolveProviderForTask("timedelta");
-    const handoffProvider = resolveProviderForTask("handoff");
-    const embeddingProvider = resolveEmbeddingProvider();
-
-    const architect = new Architect(
-      { validator: validatorProvider, timedelta: timedeltaProvider },
-      coreRepo,
-    );
-    const aliasGenerator = new AliasDeltaGenerator(actorProvider);
-
-    const session: SimSession = {
-      db,
-      dbPath,
-      coreRepo,
-      bufferRepo,
-      ledgerRepo,
-      worldInstanceId: worldInstanceId,
-      scenarioName: scenarioJson.name,
-      scenarioDescription: scenarioJson.description || "",
-      turn: 1,
-      maxTurns: 20,
-      entities: entityInfos,
-      playerEntityId,
-      entityIndex: 0,
-      actorProvider,
-      validatorProvider,
-      decoderProvider,
-      timedeltaProvider,
-      handoffProvider,
-      embeddingProvider,
-      architect,
-      aliasGenerator,
-      log: [],
-      status: "running",
-      aliasDoneForTurn: false,
-      providerMappings: mappings,
-    };
-
-    this.sessions.set(id, session);
-    return this.snapshot(session);
-  }
-
-  async step(id: string): Promise<SimSnapshot | null> {
-    const session = this.sessions.get(id);
-    if (!session) return null;
-    if (session.status !== "running") return this.snapshot(session);
-
-    try {
-      if (session.turn > session.maxTurns) {
-        session.status = "done";
-        this.save(session);
-        return this.snapshot(session);
-      }
-
-      if (!session.aliasDoneForTurn && session.entityIndex === 0) {
-        await this.runAliasResolution(session);
-        await this.runHandoffResolution(session);
-        session.aliasDoneForTurn = true;
-        this.save(session);
-        return this.snapshot(session);
-      }
-
-      if (session.entityIndex >= session.entities.length) {
-        session.turn++;
-        session.entityIndex = 0;
-        session.aliasDoneForTurn = false;
-        this.save(session);
-        return this.snapshot(session);
-      }
-
-      const info = session.entities[session.entityIndex];
-
-      if (info.isPlayer) {
-        await this.preparePlayerTurn(session, info);
-        this.save(session);
-        return this.snapshot(session);
-      }
-
-      await this.processNpcTurn(session, info);
-      session.entityIndex++;
-    } catch (err) {
-      session.status = "error";
-      session.error = err instanceof Error ? err.message : String(err);
-    }
-
-    this.save(session);
-    return this.snapshot(session);
-  }
-
-  async submitPlayerAction(
-    id: string,
-    prose: string,
-  ): Promise<SimSnapshot | null> {
-    const session = this.sessions.get(id);
-    if (!session) return null;
-    if (session.status !== "waiting_player") return this.snapshot(session);
-    if (!session.waitingEntity) return this.snapshot(session);
-
-    const ctx = session.waitingEntity;
-    session.waitingEntity = undefined;
-    session.status = "running";
-
-    try {
-      const worldState = session.coreRepo.loadWorldState(
-        session.worldInstanceId,
-      );
-      if (!worldState) throw new Error("World state lost");
-
-      const entity = worldState.getEntity(ctx.entityId);
-      if (!entity) throw new Error(`Player entity "${ctx.entityId}" not found`);
-
-      const playerActor = new ActorAgent(
-        { actor: session.actorProvider, decoder: session.decoderProvider },
-        session.bufferRepo,
-        session.ledgerRepo,
-        20,
-        new FixedProseGenerator(prose),
-      );
-
-      const result = await playerActor.act(worldState, entity);
-
-      const entry: LogEntry = {
-        turn: session.turn,
-        entityId: ctx.entityId,
-        entityName: ctx.name,
-        narrativeProse: result.narrativeProse,
-        intents: [],
-        timestamp: worldState.clock.get().toISOString(),
-        rawPrompt: {
-          systemPrompt: ctx.systemPrompt,
-          userContext: ctx.userContext,
-        },
-      };
-
-      if (session.decoderProvider.lastCalls && session.decoderProvider.lastCalls.length > 0) {
-        const call = session.decoderProvider.lastCalls[session.decoderProvider.lastCalls.length - 1];
-        entry.decoderPrompt = {
-          systemPrompt: call.systemPrompt,
-          userContext: call.userContext,
-        };
-        entry.decoderUsage = call.usage;
-      }
-
-      for (const intent of result.intents.intents) {
-        const outcome = await session.architect.processIntent(
-          worldState,
-          intent,
-        );
-        const ts = worldState.clock.get().toISOString();
-
-        entry.intents.push({
-          type: intent.type,
-          description: intent.description,
-          selfDescription: intent.selfDescription,
-          modifiers: intent.modifiers || [],
-          targetIds: intent.targetIds,
-          isValid: outcome.isValid,
-          reason: outcome.reason,
-          minutesToAdvance: outcome.timeDelta?.minutesToAdvance,
-        });
-
-        const actorEntry = buildBufferEntryForIntent(
-          intent,
-          ts,
-          entity.locationId,
-        );
-        if (intent.type === "action") {
-          actorEntry.outcome = {
-            isValid: outcome.isValid,
-            reason: outcome.reason,
-          };
-        }
-        session.bufferRepo.save(actorEntry);
-
-        if (
-          entity.locationId &&
-          (intent.type === "dialogue" || intent.type === "action")
-        ) {
-          for (const [, other] of worldState.entities) {
-            if (
-              other.id !== ctx.entityId &&
-              other.locationId === entity.locationId
-            ) {
-              const observerEntry = buildBufferEntryForIntent(
-                intent,
-                ts,
-                entity.locationId,
-              );
-              if (intent.type === "action") {
-                observerEntry.outcome = {
-                  isValid: outcome.isValid,
-                  reason: outcome.reason,
-                };
-              }
-              session.bufferRepo.save({
-                ...observerEntry,
-                ownerId: other.id,
-              });
-            }
-          }
-        }
-      }
-
-      session.log.push(entry);
-      session.coreRepo.saveWorldState(worldState);
-      session.entityIndex++;
-    } catch (err) {
-      session.status = "error";
-      session.error = err instanceof Error ? err.message : String(err);
-    }
-
-    this.save(session);
-    return this.snapshot(session);
-  }
-
-  private async preparePlayerTurn(
-    session: SimSession,
-    info: EntityInfo,
-  ): Promise<void> {
-    const worldState = session.coreRepo.loadWorldState(
-      session.worldInstanceId,
-    );
-    if (!worldState) throw new Error("World state lost");
-
-    const entity = worldState.getEntity(info.id);
-    if (!entity) throw new Error(`Entity "${info.id}" not found`);
-
-    const promptBuilder = new ActorPromptBuilder(session.bufferRepo, session.ledgerRepo, 20);
-    const { systemPrompt, userContext } = promptBuilder.build(
-      worldState,
-      entity,
-    );
-
-    session.waitingEntity = {
-      entityId: info.id,
-      name: info.name,
-      systemPrompt,
-      userContext,
-    };
-    session.status = "waiting_player";
-  }
-
-  private async processNpcTurn(
-    session: SimSession,
-    info: EntityInfo,
-  ): Promise<void> {
-    const worldState = session.coreRepo.loadWorldState(
-      session.worldInstanceId,
-    );
-    if (!worldState) throw new Error("World state lost");
-
-    const entity = worldState.getEntity(info.id);
-    if (!entity) throw new Error(`Entity "${info.id}" not found`);
-
-    const actor = new ActorAgent(
-      { actor: session.actorProvider, decoder: session.decoderProvider },
-      session.bufferRepo,
-      session.ledgerRepo,
-      20,
-    );
-    const result = await actor.act(worldState, entity);
-
-    const entry: LogEntry = {
-      turn: session.turn,
-      entityId: info.id,
-      entityName: info.name,
-      narrativeProse: result.narrativeProse,
-      intents: [],
-      timestamp: worldState.clock.get().toISOString(),
-    };
-
-    if (session.actorProvider.lastCalls && session.actorProvider.lastCalls.length > 0) {
-      const actorCall = session.actorProvider.lastCalls[session.actorProvider.lastCalls.length - 1];
-      entry.rawPrompt = {
-        systemPrompt: actorCall.systemPrompt,
-        userContext: actorCall.userContext,
-      };
-      entry.usage = actorCall.usage;
-    }
-
-    if (session.decoderProvider.lastCalls && session.decoderProvider.lastCalls.length > 0) {
-      const decoderCall = session.decoderProvider.lastCalls[session.decoderProvider.lastCalls.length - 1];
-      entry.decoderPrompt = {
-        systemPrompt: decoderCall.systemPrompt,
-        userContext: decoderCall.userContext,
-      };
-      entry.decoderUsage = decoderCall.usage;
-    }
-
-    for (const intent of result.intents.intents) {
-      const outcome = await session.architect.processIntent(
-        worldState,
-        intent,
-      );
-      const ts = worldState.clock.get().toISOString();
-
-      entry.intents.push({
-        type: intent.type,
-        description: intent.description,
-        selfDescription: intent.selfDescription,
-        modifiers: intent.modifiers || [],
-        targetIds: intent.targetIds,
-        isValid: outcome.isValid,
-        reason: outcome.reason,
-        minutesToAdvance: outcome.timeDelta?.minutesToAdvance,
-      });
-
-      const actorEntry = buildBufferEntryForIntent(
-        intent,
-        ts,
-        entity.locationId,
-      );
-      if (intent.type === "action") {
-        actorEntry.outcome = {
-          isValid: outcome.isValid,
-          reason: outcome.reason,
-        };
-      }
-      session.bufferRepo.save(actorEntry);
-
-      if (
-        entity.locationId &&
-        (intent.type === "dialogue" || intent.type === "action")
-      ) {
-        for (const [, other] of worldState.entities) {
-          if (
-            other.id !== info.id &&
-            other.locationId === entity.locationId
-          ) {
-            const observerEntry = buildBufferEntryForIntent(
-              intent,
-              ts,
-              entity.locationId,
-            );
-            if (intent.type === "action") {
-              observerEntry.outcome = {
-                isValid: outcome.isValid,
-                reason: outcome.reason,
-              };
-            }
-            session.bufferRepo.save({ ...observerEntry, ownerId: other.id });
-          }
-        }
-      }
-    }
-
-    session.log.push(entry);
-    session.coreRepo.saveWorldState(worldState);
-  }
-
-  private async runHandoffResolution(session: SimSession): Promise<void> {
-    const worldState = session.coreRepo.loadWorldState(
-      session.worldInstanceId,
-    );
-    if (!worldState) throw new Error("World state lost");
-
-    const handoffEngine = new HandoffEngine(
-      session.handoffProvider,
-      session.embeddingProvider,
-      session.bufferRepo,
-      session.ledgerRepo,
-    );
-
-    const entities = Array.from(worldState.entities.values());
-    for (const entity of entities) {
-      const bufferEntries = session.bufferRepo.listForOwner(entity.id);
-      const maxContext = session.handoffProvider.maxContext !== undefined ? session.handoffProvider.maxContext : 32768;
-
-      const trigger = checkHandoffTrigger(entity, bufferEntries, worldState.clock.get(), maxContext);
-      if (trigger !== "none") {
-        await handoffEngine.runHandoff(entity, bufferEntries, worldState.clock.get());
-      }
-    }
-  }
-
-  private async runAliasResolution(session: SimSession): Promise<void> {
-    const worldState = session.coreRepo.loadWorldState(
-      session.worldInstanceId,
-    );
-    if (!worldState) throw new Error("World state lost");
-
-    const entities = Array.from(worldState.entities.values());
-    for (const viewer of entities) {
-      if (!viewer.locationId) continue;
-      for (const target of entities) {
-        if (viewer.id === target.id) continue;
-        if (
-          target.locationId === viewer.locationId &&
-          !viewer.aliases.has(target.id)
-        ) {
-          const alias = await session.aliasGenerator.generate(viewer, target);
-          viewer.aliases.set(target.id, alias);
-          session.coreRepo.saveEntity(viewer, worldState.id);
-        }
-      }
-    }
-  }
-
-  close(id: string): void {
-    const session = this.sessions.get(id);
-    if (session) {
-      session.db.close();
-      this.sessions.delete(id);
-    }
-  }
-
-  deleteSession(id: string): void {
-    const session = this.sessions.get(id);
-    if (session) {
-      session.db.close();
-      this.sessions.delete(id);
-    }
-    const dbDir = path.resolve(process.cwd(), "data");
-    const dbPath = path.join(dbDir, `${id}.db`);
-    if (fs.existsSync(dbPath)) {
-      try {
-        fs.unlinkSync(dbPath);
-      } catch (err) {
-        console.error(`Failed to delete session file ${dbPath}:`, err);
-      }
-    }
-  }
-
-  async load(id: string): Promise<SimSnapshot | null> {
-    const active = this.sessions.get(id);
-    if (active) {
-      return this.snapshot(active);
-    }
-
-    const dbDir = path.resolve(process.cwd(), "data");
-    const dbPath = path.join(dbDir, `${id}.db`);
-    if (!fs.existsSync(dbPath)) return null;
-
-    try {
-      const db = new Database(dbPath);
-      const state = loadSessionState(db, id);
-      if (!state) {
-        db.close();
-        return null;
-      }
-
-      const list = ProviderManager.list();
-      const active = ProviderManager.getActive("generative");
-      const mappings = state.providerMappings || {};
-
-      const resolveProviderForTask = (task: string): ILLMProvider => {
-        const mappedId = mappings[task];
-        let inst = mappedId ? list.find((p) => p.id === mappedId) : null;
-        if (!inst || inst.type !== "generative") {
-          inst = active;
-        }
-
-        if (!inst) {
-          const envKey = process.env.GOOGLE_API_KEY;
-          if (envKey) {
-            inst = ProviderManager.create("Default (Env)", "google-genai", envKey, undefined, "generative");
-          }
-        }
-
-        if (!inst) {
-          throw new Error(`No active LLM Provider Instance found for task "${task}". Please configure a key in Settings first.`);
-        }
-
-        if (inst.providerName === "google-genai") {
-          return new GeminiProvider(inst.apiKey, inst.modelName, inst.name, inst.maxContext);
-        } else if (inst.providerName === "openrouter") {
-          return new OpenRouterProvider(inst.apiKey, inst.modelName, inst.name, inst.maxContext);
-        } else {
-          return new MockLLMProvider([]);
-        }
-      };
-
-      const resolveEmbeddingProvider = (): IEmbeddingProvider => {
-        const mappedId = mappings["embeddings"];
-        let inst = mappedId ? list.find((p) => p.id === mappedId) : null;
-        if (!inst || inst.type !== "embedding") {
-          inst = ProviderManager.getActive("embedding");
-        }
-        if (!inst) {
-          const envKey = process.env.GOOGLE_API_KEY;
-          if (envKey) {
-            inst = ProviderManager.create("Default Embed (Env)", "google-genai", envKey, "gemini-embedding-001", "embedding");
-          }
-        }
-
-        if (!inst) {
-          throw new Error(`No active Embedding Provider Instance found for task "embeddings". Please configure an embedding key in Settings first.`);
-        }
-
-        if (inst.providerName === "google-genai") {
-          return new GeminiEmbeddingProvider(inst.apiKey, inst.modelName);
-        } else {
-          return new MockEmbeddingProvider(inst.modelName);
-        }
-      };
-
-      const coreRepo = new SQLiteRepository(db);
-      const bufferRepo = new BufferRepository(db);
-      const ledgerRepo = new LedgerRepository(db);
-
-      const actorProvider = resolveProviderForTask("actor-prose");
-      const validatorProvider = resolveProviderForTask("llm-validator");
-      const decoderProvider = resolveProviderForTask("intent-decoder");
-      const timedeltaProvider = resolveProviderForTask("timedelta");
-      const handoffProvider = resolveProviderForTask("handoff");
-      const embeddingProvider = resolveEmbeddingProvider();
-
-      const architect = new Architect(
-        { validator: validatorProvider, timedelta: timedeltaProvider },
-        coreRepo,
-      );
-      const aliasGenerator = new AliasDeltaGenerator(actorProvider);
-
-      const session: SimSession = {
-        db,
-        dbPath,
-        coreRepo,
-        bufferRepo,
-        ledgerRepo,
-        worldInstanceId: id,
-        scenarioName: state.scenarioName,
-        scenarioDescription: state.scenarioDescription,
-        turn: state.turn,
-        maxTurns: state.maxTurns,
-        entities: state.entities || [],
-        playerEntityId: state.playerEntityId,
-        entityIndex: state.entityIndex,
-        actorProvider,
-        validatorProvider,
-        decoderProvider,
-        timedeltaProvider,
-        handoffProvider,
-        embeddingProvider,
-        architect,
-        aliasGenerator,
-        log: state.log || [],
-        status: state.status,
-        error: state.error,
-        waitingEntity: state.waitingEntity,
-        aliasDoneForTurn: state.aliasDoneForTurn || false,
-        providerMappings: mappings,
-      };
-
-      this.sessions.set(id, session);
-      return this.snapshot(session);
-    } catch (err) {
-      console.error(`Failed to load session ${id}:`, err);
-      return null;
-    }
-  }
-
-  listSavedSessions(): SimSnapshot[] {
-    const dbDir = path.resolve(process.cwd(), "data");
-    if (!fs.existsSync(dbDir)) return [];
-
-    const snapshots: SimSnapshot[] = [];
-    const files = fs.readdirSync(dbDir).filter(f => f.startsWith("sim-") && f.endsWith(".db"));
-
-    for (const file of files) {
-      const id = file.replace(".db", "");
-      const dbPath = path.join(dbDir, file);
-
-      const active = this.sessions.get(id);
-      if (active) {
-        snapshots.push(this.snapshot(active));
-        continue;
-      }
-
-      try {
-        const db = new Database(dbPath);
-        const state = loadSessionState(db, id);
-        db.close();
-
-        if (state) {
-          snapshots.push({
-            id,
-            status: state.status,
-            turn: state.turn,
-            maxTurns: state.maxTurns,
-            scenarioName: state.scenarioName,
-            scenarioDescription: state.scenarioDescription,
-            entities: state.entities || [],
-            log: state.log || [],
-            entityIndex: state.entityIndex,
-            waitingEntity: state.waitingEntity,
-            error: state.error,
-          });
-        }
-      } catch {
-        /* skip */
-      }
-    }
-
-    return snapshots.sort((a, b) => {
-      const tsA = parseInt(a.id.replace("sim-", ""), 10) || 0;
-      const tsB = parseInt(b.id.replace("sim-", ""), 10) || 0;
-      return tsB - tsA;
-    });
-  }
-
-  async regenerateAllEmbeddings(newProviderInstanceId?: string): Promise<void> {
-    const dbDir = path.resolve(process.cwd(), "data");
-    if (!fs.existsSync(dbDir)) return;
-
-    const files = fs.readdirSync(dbDir).filter(f => f.startsWith("sim-") && f.endsWith(".db"));
-
-    const list = ProviderManager.list();
-    let inst = newProviderInstanceId ? list.find((p) => p.id === newProviderInstanceId) : null;
-    if (!inst || inst.type !== "embedding") {
-      inst = ProviderManager.getActive("embedding");
-    }
-
-    const key = inst ? inst.apiKey : (process.env.GOOGLE_API_KEY || "");
-    const providerName = inst ? inst.providerName : "google-genai";
-    const modelName = inst ? inst.modelName : undefined;
-
-    let embeddingProvider: IEmbeddingProvider;
-    if (providerName === "google-genai") {
-      embeddingProvider = new GeminiEmbeddingProvider(key, modelName);
-    } else {
-      embeddingProvider = new MockEmbeddingProvider(modelName);
-    }
-
-    for (const file of files) {
-      const dbPath = path.join(dbDir, file);
-      const id = file.replace(".db", "");
-      const activeSession = this.sessions.get(id);
-      const db = activeSession ? activeSession.db : new Database(dbPath);
-
-      try {
-        const rows = db.prepare(`SELECT id, content FROM ledger_entries`).all() as { id: string; content: string }[];
-        
-        for (const row of rows) {
-          const vector = await embeddingProvider.embed(row.content);
-          const buffer = Buffer.from(new Float32Array(vector).buffer);
-          db.prepare(`UPDATE ledger_entries SET embedding = ? WHERE id = ?`).run(buffer, row.id);
-        }
-      } catch (err) {
-        console.error(`Failed to regenerate embeddings for ${file}:`, err);
-      } finally {
-        if (!activeSession) {
-          db.close();
-        }
-      }
-    }
-  }
-
-  private save(session: SimSession): void {
-    const state: SavedState = {
-      scenarioName: session.scenarioName,
-      scenarioDescription: session.scenarioDescription,
-      turn: session.turn,
-      maxTurns: session.maxTurns,
-      entities: session.entities,
-      playerEntityId: session.playerEntityId,
-      entityIndex: session.entityIndex,
-      status: session.status,
-      error: session.error,
-      waitingEntity: session.waitingEntity,
-      aliasDoneForTurn: session.aliasDoneForTurn,
-      log: session.log,
-      providerMappings: session.providerMappings,
-    };
-
-    session.db.prepare(`
-      CREATE TABLE IF NOT EXISTS gui_meta (
-        id TEXT PRIMARY KEY,
-        state_json TEXT
-      )
-    `).run();
-
-    session.db.prepare(`
-      INSERT INTO gui_meta (id, state_json)
-      VALUES (?, ?)
-      ON CONFLICT(id) DO UPDATE SET state_json = excluded.state_json
-    `).run(session.worldInstanceId, JSON.stringify(state));
-  }
-
-  getSnapshot(id: string): SimSnapshot | null {
-    const session = this.sessions.get(id);
-    return session ? this.snapshot(session) : null;
-  }
-
-  private snapshot(session: SimSession): SimSnapshot {
-    return {
-      id: session.worldInstanceId,
-      status: session.status,
-      turn: session.turn,
-      maxTurns: session.maxTurns,
-      scenarioName: session.scenarioName,
-      scenarioDescription: session.scenarioDescription,
-      entities: session.entities,
-      log: session.log,
-      entityIndex: session.entityIndex,
-      waitingEntity: session.waitingEntity,
-      error: session.error,
-    };
-  }
-}
-
-export const simulationManager = new SimulationManager();

apps/gui/src/lib/simulation/alias-handoff.ts

@@ -0,0 +1,71 @@
+import { HandoffEngine, checkHandoffTrigger } from "@omnia/memory";
+import type { SimSession } from "./types";
+
+/**
+ * Runs the HandoffEngine for every agent entity that has accumulated enough
+ * buffer entries to warrant a handoff (compression to long-term memory).
+ */
+export async function runHandoffResolution(session: SimSession): Promise<void> {
+  const worldState = session.coreRepo.loadWorldState(session.worldInstanceId);
+  if (!worldState) throw new Error("World state lost");
+
+  const handoffEngine = new HandoffEngine(
+    session.handoffProvider,
+    session.embeddingProvider,
+    session.bufferRepo,
+    session.ledgerRepo,
+  );
+
+  const entities = Array.from(worldState.entities.values());
+  for (const entity of entities) {
+    if (!entity.isAgent) continue;
+
+    const bufferEntries = session.bufferRepo.listForOwner(entity.id);
+    const maxContext =
+      session.handoffProvider.maxContext !== undefined
+        ? session.handoffProvider.maxContext
+        : 32768;
+
+    const trigger = checkHandoffTrigger(
+      entity,
+      bufferEntries,
+      worldState.clock.get(),
+      maxContext,
+    );
+    if (trigger !== "none") {
+      await handoffEngine.runHandoff(
+        entity,
+        bufferEntries,
+        worldState.clock.get(),
+      );
+    }
+  }
+}
+
+/**
+ * For every agent that shares a location with another entity they haven't
+ * previously encountered, generates a first-person alias description and
+ * persists it on the viewing entity.
+ */
+export async function runAliasResolution(session: SimSession): Promise<void> {
+  const worldState = session.coreRepo.loadWorldState(session.worldInstanceId);
+  if (!worldState) throw new Error("World state lost");
+
+  const entities = Array.from(worldState.entities.values());
+  for (const viewer of entities) {
+    if (!viewer.isAgent) continue;
+    if (!viewer.locationId) continue;
+
+    for (const target of entities) {
+      if (viewer.id === target.id) continue;
+      if (
+        target.locationId === viewer.locationId &&
+        !viewer.aliases.has(target.id)
+      ) {
+        const alias = await session.aliasGenerator.generate(viewer, target);
+        viewer.aliases.set(target.id, alias);
+        session.coreRepo.saveEntity(viewer, worldState.id);
+      }
+    }
+  }
+}

apps/gui/src/lib/simulation/env.ts

@@ -0,0 +1,16 @@
+import dotenv from "dotenv";
+import path from "path";
+import fs from "fs";
+
+// Load .env from monorepo root or apps/gui/
+const cwd = process.cwd();
+const envCandidates = [
+  path.resolve(cwd, ".env"),
+  path.resolve(cwd, "../../.env"),
+];
+for (const c of envCandidates) {
+  if (fs.existsSync(c) && fs.statSync(c).isFile()) {
+    dotenv.config({ path: c });
+    break;
+  }
+}

apps/gui/src/lib/simulation/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Barrel entry point for the simulation module.
+ *
+ * Consumers import from "@/lib/simulation" exactly as before — no import
+ * paths need to change anywhere in the codebase.
+ */
+import { SimulationManager } from "./simulation-manager";
+
+export const simulationManager = new SimulationManager();
+
+export type {
+  SimSnapshot,
+  EntityInfo,
+  LogEntry,
+  IntentInfo,
+  WaitingContext,
+} from "../simulation-types";

apps/gui/src/lib/simulation/provider-resolver.ts

@@ -0,0 +1,146 @@
+import {
+  MockLLMProvider,
+  MockEmbeddingProvider,
+  ProviderManager,
+  buildLLMProvider,
+  buildEmbeddingProvider,
+} from "@omnia/llm";
+import type {
+  ILLMProvider,
+  IEmbeddingProvider,
+  ModelProviderInstance,
+} from "@omnia/llm";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface ResolvedProviders {
+  actorProvider: ILLMProvider;
+  validatorProvider: ILLMProvider;
+  decoderProvider: ILLMProvider;
+  timedeltaProvider: ILLMProvider;
+  handoffProvider: ILLMProvider;
+  embeddingProvider: IEmbeddingProvider;
+}
+
+export interface ProviderResolverOptions {
+  /**
+   * Pre-resolved generative instance to fall back to when ProviderManager has
+   * no active generative provider (e.g. when the caller already validated a
+   * specific provider during session creation).
+   */
+  fallbackInstance?: ModelProviderInstance | null;
+  /**
+   * When true, throws an Error if no provider can be resolved for a task.
+   * When false (default), falls back silently to MockLLMProvider / MockEmbeddingProvider.
+   */
+  required?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Resolution logic
+// ---------------------------------------------------------------------------
+
+/**
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolves all six LLM + embedding providers needed for a simulation session.
+ *
+ * Resolution order for each generative task:
+ *  1. Task-specific mapping from ProviderManager (via `mappings[task]`)
+ *  2. ProviderManager active generative instance
+ *  3. `fallbackInstance` (if supplied)
+ *  4. GOOGLE_API_KEY env var → auto-creates a temporary GeminiProvider
+ *  5. Throws (if `required`) or returns MockLLMProvider
+ */
+export function resolveProviders(
+  mappings: Record<string, string>,
+  options: ProviderResolverOptions = {},
+): ResolvedProviders {
+  const { fallbackInstance = null, required = false } = options;
+  const list = ProviderManager.list();
+  const activeGenerative =
+    ProviderManager.getActive("generative") ?? fallbackInstance ?? null;
+
+  const resolveGenerative = (task: string): ILLMProvider => {
+    const mappedId = mappings[task];
+    let inst: ModelProviderInstance | null = mappedId
+      ? (list.find((p) => p.id === mappedId) ?? null)
+      : null;
+
+    if (!inst || inst.type !== "generative") {
+      inst = activeGenerative;
+    }
+
+    if (!inst) {
+      const envKey = process.env.GOOGLE_API_KEY;
+      if (envKey) {
+        inst = ProviderManager.create(
+          "Default (Env)",
+          "google-genai",
+          envKey,
+          undefined,
+          "generative",
+        );
+      }
+    }
+
+    if (!inst) {
+      if (required) {
+        throw new Error(
+          `No active LLM Provider Instance found for task "${task}". Please configure a key in Settings first.`,
+        );
+      }
+      return new MockLLMProvider([]);
+    }
+
+    return buildLLMProvider(inst);
+  };
+
+  const resolveEmbedding = (): IEmbeddingProvider => {
+    const mappedId = mappings["embeddings"];
+    let inst: ModelProviderInstance | null = mappedId
+      ? (list.find((p) => p.id === mappedId) ?? null)
+      : null;
+
+    if (!inst || inst.type !== "embedding") {
+      inst = ProviderManager.getActive("embedding");
+    }
+
+    if (!inst) {
+      const envKey = process.env.GOOGLE_API_KEY;
+      if (envKey) {
+        inst = ProviderManager.create(
+          "Default Embed (Env)",
+          "google-genai",
+          envKey,
+          "gemini-embedding-001",
+          "embedding",
+        );
+      }
+    }
+
+    if (!inst) {
+      if (required) {
+        throw new Error(
+          `No active Embedding Provider Instance found. Please configure an embedding key in Settings first.`,
+        );
+      }
+      return new MockEmbeddingProvider(undefined);
+    }
+
+    return buildEmbeddingProvider(inst);
+  };
+
+  return {
+    actorProvider: resolveGenerative("actor-prose"),
+    validatorProvider: resolveGenerative("llm-validator"),
+    decoderProvider: resolveGenerative("intent-decoder"),
+    timedeltaProvider: resolveGenerative("timedelta"),
+    handoffProvider: resolveGenerative("handoff"),
+    embeddingProvider: resolveEmbedding(),
+  };
+}

apps/gui/src/lib/simulation/session-store.ts

@@ -0,0 +1,139 @@
+import Database from "better-sqlite3";
+import path from "path";
+import fs from "fs";
+import type { SimSession, SavedState } from "./types";
+import type { SimSnapshot } from "../simulation-types";
+
+export const DATA_DIR = path.resolve(process.cwd(), "data");
+
+// ---------------------------------------------------------------------------
+// Low-level read/write helpers
+// ---------------------------------------------------------------------------
+
+export function loadSessionState(
+  db: Database.Database,
+  id: string,
+): SavedState | null {
+  try {
+    db.prepare(
+      `CREATE TABLE IF NOT EXISTS gui_meta (
+        id TEXT PRIMARY KEY,
+        state_json TEXT
+      )`,
+    ).run();
+    const row = db
+      .prepare(`SELECT state_json FROM gui_meta WHERE id = ?`)
+      .get(id) as { state_json: string } | undefined;
+    return row ? (JSON.parse(row.state_json) as SavedState) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveSession(session: SimSession): void {
+  const state: SavedState = {
+    scenarioName: session.scenarioName,
+    scenarioDescription: session.scenarioDescription,
+    turn: session.turn,
+    maxTurns: session.maxTurns,
+    entities: session.entities,
+    playerEntityId: session.playerEntityId,
+    entityIndex: session.entityIndex,
+    status: session.status,
+    error: session.error,
+    waitingEntity: session.waitingEntity,
+    aliasDoneForTurn: session.aliasDoneForTurn,
+    log: session.log,
+    providerMappings: session.providerMappings,
+  };
+
+  session.db
+    .prepare(
+      `CREATE TABLE IF NOT EXISTS gui_meta (
+        id TEXT PRIMARY KEY,
+        state_json TEXT
+      )`,
+    )
+    .run();
+
+  session.db
+    .prepare(
+      `INSERT INTO gui_meta (id, state_json)
+       VALUES (?, ?)
+       ON CONFLICT(id) DO UPDATE SET state_json = excluded.state_json`,
+    )
+    .run(session.worldInstanceId, JSON.stringify(state));
+}
+
+// ---------------------------------------------------------------------------
+// Session file management
+// ---------------------------------------------------------------------------
+
+export function deleteSessionFile(id: string): void {
+  const dbPath = path.join(DATA_DIR, `${id}.db`);
+  if (fs.existsSync(dbPath)) {
+    try {
+      fs.unlinkSync(dbPath);
+    } catch (err) {
+      console.error(`Failed to delete session file ${dbPath}:`, err);
+    }
+  }
+}
+
+/**
+ * Lists all saved simulation snapshots by scanning the data directory.
+ * Active in-memory sessions are snapshotted via the provided callback;
+ * inactive ones are read directly from their `.db` files.
+ */
+export function listSavedSessions(
+  activeSessions: Map<string, SimSession>,
+  snapshotFn: (session: SimSession) => SimSnapshot,
+): SimSnapshot[] {
+  if (!fs.existsSync(DATA_DIR)) return [];
+
+  const snapshots: SimSnapshot[] = [];
+  const files = fs
+    .readdirSync(DATA_DIR)
+    .filter((f) => f.startsWith("sim-") && f.endsWith(".db"));
+
+  for (const file of files) {
+    const id = file.replace(".db", "");
+    const dbPath = path.join(DATA_DIR, file);
+
+    const active = activeSessions.get(id);
+    if (active) {
+      snapshots.push(snapshotFn(active));
+      continue;
+    }
+
+    try {
+      const db = new Database(dbPath);
+      const state = loadSessionState(db, id);
+      db.close();
+
+      if (state) {
+        snapshots.push({
+          id,
+          status: state.status,
+          turn: state.turn,
+          maxTurns: state.maxTurns,
+          scenarioName: state.scenarioName,
+          scenarioDescription: state.scenarioDescription,
+          entities: state.entities || [],
+          log: state.log || [],
+          entityIndex: state.entityIndex,
+          waitingEntity: state.waitingEntity,
+          error: state.error,
+        });
+      }
+    } catch {
+      /* skip corrupt / in-use db files */
+    }
+  }
+
+  return snapshots.sort((a, b) => {
+    const tsA = parseInt(a.id.replace("sim-", ""), 10) || 0;
+    const tsB = parseInt(b.id.replace("sim-", ""), 10) || 0;
+    return tsB - tsA;
+  });
+}

apps/gui/src/lib/simulation/simulation-manager.ts

@@ -0,0 +1,471 @@
+import "./env"; // Must be first — loads .env before any code reads process.env
+import Database from "better-sqlite3";
+import path from "path";
+import fs from "fs";
+import { SQLiteRepository } from "@omnia/core";
+import { BufferRepository, LedgerRepository } from "@omnia/memory";
+import { Architect, AliasDeltaGenerator } from "@omnia/architect";
+import { ProviderManager, buildEmbeddingProvider } from "@omnia/llm";
+import type { ModelProviderInstance, IEmbeddingProvider } from "@omnia/llm";
+import { ScenarioLoader } from "@omnia/scenario";
+import type { SimSnapshot } from "../simulation-types";
+import type { SimSession, EntityInfo } from "./types";
+import { resolveProviders } from "./provider-resolver";
+import {
+  DATA_DIR,
+  loadSessionState,
+  saveSession,
+  listSavedSessions,
+  deleteSessionFile,
+} from "./session-store";
+import {
+  preparePlayerTurn,
+  processNpcTurn,
+  executePlayerAction,
+} from "./turn-executor";
+import { runAliasResolution, runHandoffResolution } from "./alias-handoff";
+
+export class SimulationManager {
+  private sessions = new Map<string, SimSession>();
+
+  // ---------------------------------------------------------------------------
+  // Session lifecycle
+  // ---------------------------------------------------------------------------
+
+  async create(
+    scenarioPath: string,
+    playEntityName?: string,
+    providerInstanceId?: string,
+  ): Promise<SimSnapshot> {
+    // Resolve or validate the active generative provider upfront so we can
+    // return a clean error snapshot before touching the filesystem.
+    let activeInstance: ModelProviderInstance | null = providerInstanceId
+      ? ProviderManager.list().find((p) => p.id === providerInstanceId) || null
+      : ProviderManager.getActive("generative");
+
+    if (!activeInstance) {
+      const envKey = process.env.GOOGLE_API_KEY;
+      if (envKey) {
+        activeInstance = ProviderManager.create(
+          "Default (Env)",
+          "google-genai",
+          envKey,
+          undefined,
+          "generative",
+        );
+      }
+    }
+    if (!activeInstance) {
+      return {
+        id: "",
+        status: "error",
+        turn: 0,
+        maxTurns: 20,
+        scenarioName: "",
+        scenarioDescription: "",
+        entities: [],
+        log: [],
+        entityIndex: 0,
+        error:
+          "No active LLM Provider Instance found. Please configure a key in Settings first.",
+      };
+    }
+
+    const scenarioJson = JSON.parse(fs.readFileSync(scenarioPath, "utf-8"));
+    const id = `sim-${Date.now()}`;
+
+    fs.mkdirSync(DATA_DIR, { recursive: true });
+    const dbPath = path.join(DATA_DIR, `${id}.db`);
+    const db = new Database(dbPath);
+    const coreRepo = new SQLiteRepository(db);
+    const bufferRepo = new BufferRepository(db);
+    const ledgerRepo = new LedgerRepository(db);
+    const loader = new ScenarioLoader(coreRepo, bufferRepo);
+
+    const worldInstanceId = id;
+    await loader.initializeWorld(scenarioJson, worldInstanceId);
+
+    const worldState = coreRepo.loadWorldState(worldInstanceId);
+    if (!worldState) {
+      db.close();
+      return {
+        id: "",
+        status: "error",
+        turn: 0,
+        maxTurns: 20,
+        scenarioName: "",
+        scenarioDescription: "",
+        entities: [],
+        log: [],
+        entityIndex: 0,
+        error: "Failed to load world state after initialization.",
+      };
+    }
+
+    // Build entity list
+    const rawEntities = Array.from(worldState.entities.values());
+    const entityInfos: EntityInfo[] = rawEntities.map((e) => ({
+      id: e.id,
+      name: (e.attributes.get("name")?.getValue() as string) || e.id,
+      isPlayer: false,
+      isAgent: e.isAgent,
+    }));
+
+    // Resolve player entity (exact match → name match → fuzzy)
+    let playerEntityId: string | undefined;
+    if (playEntityName) {
+      let matched = worldState.getEntity(playEntityName);
+      if (!matched) {
+        for (const ent of rawEntities) {
+          const nameAttr = ent.attributes.get("name")?.getValue() as
+            string | undefined;
+          if (nameAttr?.toLowerCase() === playEntityName.toLowerCase()) {
+            matched = ent;
+            break;
+          }
+        }
+      }
+      if (!matched) {
+        for (const ent of rawEntities) {
+          const nameAttr = ent.attributes.get("name")?.getValue() as
+            string | undefined;
+          if (
+            nameAttr?.toLowerCase().includes(playEntityName.toLowerCase()) ||
+            ent.id.toLowerCase().includes(playEntityName.toLowerCase())
+          ) {
+            matched = ent;
+            break;
+          }
+        }
+      }
+      if (matched) {
+        playerEntityId = matched.id;
+        const info = entityInfos.find((e) => e.id === matched!.id);
+        if (info) info.isPlayer = true;
+      }
+    }
+
+    const mappings = ProviderManager.getMappings();
+    const {
+      actorProvider,
+      validatorProvider,
+      decoderProvider,
+      timedeltaProvider,
+      handoffProvider,
+      embeddingProvider,
+    } = resolveProviders(mappings, { fallbackInstance: activeInstance });
+
+    const architect = new Architect(
+      { validator: validatorProvider, timedelta: timedeltaProvider },
+      coreRepo,
+    );
+    const aliasGenerator = new AliasDeltaGenerator(actorProvider);
+
+    const session: SimSession = {
+      db,
+      dbPath,
+      coreRepo,
+      bufferRepo,
+      ledgerRepo,
+      worldInstanceId,
+      scenarioName: scenarioJson.name,
+      scenarioDescription: scenarioJson.description || "",
+      turn: 1,
+      maxTurns: 20,
+      entities: entityInfos,
+      playerEntityId,
+      entityIndex: 0,
+      actorProvider,
+      validatorProvider,
+      decoderProvider,
+      timedeltaProvider,
+      handoffProvider,
+      embeddingProvider,
+      architect,
+      aliasGenerator,
+      log: [],
+      status: "running",
+      aliasDoneForTurn: false,
+      providerMappings: mappings,
+    };
+
+    this.sessions.set(id, session);
+    return this.snapshot(session);
+  }
+
+  async load(id: string): Promise<SimSnapshot | null> {
+    const active = this.sessions.get(id);
+    if (active) return this.snapshot(active);
+
+    const dbPath = path.join(DATA_DIR, `${id}.db`);
+    if (!fs.existsSync(dbPath)) return null;
+
+    try {
+      const db = new Database(dbPath);
+      const state = loadSessionState(db, id);
+      if (!state) {
+        db.close();
+        return null;
+      }
+
+      const mappings = state.providerMappings || {};
+      const {
+        actorProvider,
+        validatorProvider,
+        decoderProvider,
+        timedeltaProvider,
+        handoffProvider,
+        embeddingProvider,
+      } = resolveProviders(mappings, { required: true });
+
+      const coreRepo = new SQLiteRepository(db);
+      const bufferRepo = new BufferRepository(db);
+      const ledgerRepo = new LedgerRepository(db);
+      const architect = new Architect(
+        { validator: validatorProvider, timedelta: timedeltaProvider },
+        coreRepo,
+      );
+      const aliasGenerator = new AliasDeltaGenerator(actorProvider);
+
+      const session: SimSession = {
+        db,
+        dbPath,
+        coreRepo,
+        bufferRepo,
+        ledgerRepo,
+        worldInstanceId: id,
+        scenarioName: state.scenarioName,
+        scenarioDescription: state.scenarioDescription,
+        turn: state.turn,
+        maxTurns: state.maxTurns,
+        entities: state.entities || [],
+        playerEntityId: state.playerEntityId,
+        entityIndex: state.entityIndex,
+        actorProvider,
+        validatorProvider,
+        decoderProvider,
+        timedeltaProvider,
+        handoffProvider,
+        embeddingProvider,
+        architect,
+        aliasGenerator,
+        log: state.log || [],
+        status: state.status,
+        error: state.error,
+        waitingEntity: state.waitingEntity,
+        aliasDoneForTurn: state.aliasDoneForTurn || false,
+        providerMappings: mappings,
+      };
+
+      this.sessions.set(id, session);
+      return this.snapshot(session);
+    } catch (err) {
+      console.error(`Failed to load session ${id}:`, err);
+      return null;
+    }
+  }
+
+  close(id: string): void {
+    const session = this.sessions.get(id);
+    if (session) {
+      session.db.close();
+      this.sessions.delete(id);
+    }
+  }
+
+  deleteSession(id: string): void {
+    const session = this.sessions.get(id);
+    if (session) {
+      session.db.close();
+      this.sessions.delete(id);
+    }
+    deleteSessionFile(id);
+  }
+
+  listSavedSessions(): SimSnapshot[] {
+    return listSavedSessions(this.sessions, (s) => this.snapshot(s));
+  }
+
+  getSnapshot(id: string): SimSnapshot | null {
+    const session = this.sessions.get(id);
+    return session ? this.snapshot(session) : null;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Simulation stepping
+  // ---------------------------------------------------------------------------
+
+  async step(id: string): Promise<SimSnapshot | null> {
+    const session = this.sessions.get(id);
+    if (!session) return null;
+    if (session.status !== "running") return this.snapshot(session);
+
+    try {
+      if (session.turn > session.maxTurns) {
+        session.status = "done";
+        saveSession(session);
+        return this.snapshot(session);
+      }
+
+      // Start of turn: alias + handoff resolution before any entity acts
+      if (!session.aliasDoneForTurn && session.entityIndex === 0) {
+        await runAliasResolution(session);
+        await runHandoffResolution(session);
+        session.aliasDoneForTurn = true;
+        saveSession(session);
+        return this.snapshot(session);
+      }
+
+      // End of turn: advance to next turn
+      if (session.entityIndex >= session.entities.length) {
+        session.turn++;
+        session.entityIndex = 0;
+        session.aliasDoneForTurn = false;
+        saveSession(session);
+        return this.snapshot(session);
+      }
+
+      const info = session.entities[session.entityIndex];
+
+      if (!info.isAgent) {
+        session.entityIndex++;
+        saveSession(session);
+        return this.snapshot(session);
+      }
+
+      if (info.isPlayer) {
+        await preparePlayerTurn(session, info);
+        saveSession(session);
+        return this.snapshot(session);
+      }
+
+      await processNpcTurn(session, info);
+      session.entityIndex++;
+    } catch (err) {
+      session.status = "error";
+      session.error = err instanceof Error ? err.message : String(err);
+    }
+
+    saveSession(session);
+    return this.snapshot(session);
+  }
+
+  async submitPlayerAction(
+    id: string,
+    prose: string,
+  ): Promise<SimSnapshot | null> {
+    const session = this.sessions.get(id);
+    if (!session) return null;
+    if (session.status !== "waiting_player") return this.snapshot(session);
+    if (!session.waitingEntity) return this.snapshot(session);
+
+    const ctx = session.waitingEntity;
+    session.waitingEntity = undefined;
+    session.status = "running";
+
+    try {
+      await executePlayerAction(session, ctx, prose);
+      session.entityIndex++;
+    } catch (err) {
+      session.status = "error";
+      session.error = err instanceof Error ? err.message : String(err);
+    }
+
+    saveSession(session);
+    return this.snapshot(session);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Utility
+  // ---------------------------------------------------------------------------
+
+  async regenerateAllEmbeddings(newProviderInstanceId?: string): Promise<void> {
+    if (!fs.existsSync(DATA_DIR)) return;
+
+    const files = fs
+      .readdirSync(DATA_DIR)
+      .filter((f) => f.startsWith("sim-") && f.endsWith(".db"));
+
+    const list = ProviderManager.list();
+    let inst = newProviderInstanceId
+      ? (list.find((p) => p.id === newProviderInstanceId) ?? null)
+      : null;
+    if (!inst || inst.type !== "embedding") {
+      inst = ProviderManager.getActive("embedding");
+    }
+
+    if (!inst) {
+      const envKey = process.env.GOOGLE_API_KEY || "";
+      if (envKey) {
+        inst = {
+          id: "regen-env-fallback",
+          name: "Gemini Embed (Env)",
+          providerName: "google-genai",
+          apiKey: envKey,
+          isActive: true,
+          modelName: "gemini-embedding-001",
+          type: "embedding",
+          maxContext: 0,
+        };
+      } else {
+        inst = {
+          id: "regen-mock-fallback",
+          name: "Mock Embed (Fallback)",
+          providerName: "mock",
+          apiKey: "",
+          isActive: true,
+          modelName: undefined,
+          type: "embedding",
+          maxContext: 0,
+        };
+      }
+    }
+
+    const embeddingProvider: IEmbeddingProvider = buildEmbeddingProvider(inst);
+
+    for (const file of files) {
+      const dbPath = path.join(DATA_DIR, file);
+      const fileId = file.replace(".db", "");
+      const activeSession = this.sessions.get(fileId);
+      const db = activeSession ? activeSession.db : new Database(dbPath);
+
+      try {
+        const rows = db
+          .prepare(`SELECT id, content FROM ledger_entries`)
+          .all() as { id: string; content: string }[];
+
+        for (const row of rows) {
+          const vector = await embeddingProvider.embed(row.content);
+          const buffer = Buffer.from(new Float32Array(vector).buffer);
+          db.prepare(
+            `UPDATE ledger_entries SET embedding = ? WHERE id = ?`,
+          ).run(buffer, row.id);
+        }
+      } catch (err) {
+        console.error(`Failed to regenerate embeddings for ${file}:`, err);
+      } finally {
+        if (!activeSession) db.close();
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private
+  // ---------------------------------------------------------------------------
+
+  private snapshot(session: SimSession): SimSnapshot {
+    return {
+      id: session.worldInstanceId,
+      status: session.status,
+      turn: session.turn,
+      maxTurns: session.maxTurns,
+      scenarioName: session.scenarioName,
+      scenarioDescription: session.scenarioDescription,
+      entities: session.entities,
+      log: session.log,
+      entityIndex: session.entityIndex,
+      waitingEntity: session.waitingEntity,
+      error: session.error,
+    };
+  }
+}

apps/gui/src/lib/simulation/turn-executor.ts

@@ -0,0 +1,277 @@
+import {
+  ActorAgent,
+  ActorPromptBuilder,
+  buildBufferEntryForIntent,
+} from "@omnia/actor";
+import type { IActorProseGenerator } from "@omnia/actor";
+import type { SimSession } from "./types";
+import type {
+  EntityInfo,
+  IntentInfo,
+  LogEntry,
+  WaitingContext,
+} from "../simulation-types";
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** Prose generator that returns a fixed player-supplied string verbatim. */
+class FixedProseGenerator implements IActorProseGenerator {
+  constructor(private prose: string) {}
+
+  async generate(
+    entityId: string,
+    systemPrompt: string,
+    userContext: string,
+  ): Promise<string> {
+    void entityId;
+    void systemPrompt;
+    void userContext;
+    return this.prose;
+  }
+}
+
+/**
+ * Processes every intent produced by an actor turn:
+ * - Validates via Architect
+ * - Appends to actor's own buffer
+ * - Fan-outs to co-located observers for dialogue/action intents
+ *
+ * Extracted to eliminate verbatim duplication between NPC and player paths.
+ */
+async function processIntents(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  intents: any[],
+  actorEntityId: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  entity: any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  worldState: any,
+  session: SimSession,
+): Promise<IntentInfo[]> {
+  const intentInfos: IntentInfo[] = [];
+
+  for (const intent of intents) {
+    const outcome = await session.architect.processIntent(worldState, intent);
+    const ts = worldState.clock.get().toISOString();
+
+    intentInfos.push({
+      type: intent.type,
+      description: intent.description,
+      selfDescription: intent.selfDescription,
+      modifiers: intent.modifiers || [],
+      targetIds: intent.targetIds,
+      isValid: outcome.isValid,
+      reason: outcome.reason,
+      minutesToAdvance: outcome.timeDelta?.minutesToAdvance,
+    });
+
+    const actorEntry = buildBufferEntryForIntent(intent, ts, entity.locationId);
+    if (intent.type === "action") {
+      actorEntry.outcome = { isValid: outcome.isValid, reason: outcome.reason };
+    }
+    session.bufferRepo.save(actorEntry);
+
+    // Fan-out observable events to co-located entities
+    if (
+      entity.locationId &&
+      (intent.type === "dialogue" || intent.type === "action")
+    ) {
+      for (const [, other] of worldState.entities) {
+        if (
+          other.id !== actorEntityId &&
+          other.locationId === entity.locationId
+        ) {
+          const observerEntry = buildBufferEntryForIntent(
+            intent,
+            ts,
+            entity.locationId,
+          );
+          if (intent.type === "action") {
+            observerEntry.outcome = {
+              isValid: outcome.isValid,
+              reason: outcome.reason,
+            };
+          }
+          session.bufferRepo.save({ ...observerEntry, ownerId: other.id });
+        }
+      }
+    }
+  }
+
+  return intentInfos;
+}
+
+// ---------------------------------------------------------------------------
+// Exported turn functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds the prompt for the player entity and sets the session to
+ * `waiting_player` so the next client call can supply the prose.
+ */
+export async function preparePlayerTurn(
+  session: SimSession,
+  info: EntityInfo,
+): Promise<void> {
+  const worldState = session.coreRepo.loadWorldState(session.worldInstanceId);
+  if (!worldState) throw new Error("World state lost");
+
+  const entity = worldState.getEntity(info.id);
+  if (!entity) throw new Error(`Entity "${info.id}" not found`);
+
+  const promptBuilder = new ActorPromptBuilder(
+    session.bufferRepo,
+    session.ledgerRepo,
+    20,
+  );
+  const { systemPrompt, userContext } = promptBuilder.build(worldState, entity);
+
+  session.waitingEntity = {
+    entityId: info.id,
+    name: info.name,
+    systemPrompt,
+    userContext,
+  };
+  session.status = "waiting_player";
+}
+
+/**
+ * Runs an autonomous NPC turn: generates prose via ActorAgent, validates
+ * and persists all intents, and appends a LogEntry to the session.
+ */
+export async function processNpcTurn(
+  session: SimSession,
+  info: EntityInfo,
+): Promise<void> {
+  const worldState = session.coreRepo.loadWorldState(session.worldInstanceId);
+  if (!worldState) throw new Error("World state lost");
+
+  const entity = worldState.getEntity(info.id);
+  if (!entity) throw new Error(`Entity "${info.id}" not found`);
+
+  const actor = new ActorAgent(
+    { actor: session.actorProvider, decoder: session.decoderProvider },
+    session.bufferRepo,
+    session.ledgerRepo,
+    20,
+  );
+  const result = await actor.act(worldState, entity);
+
+  const entry: LogEntry = {
+    turn: session.turn,
+    entityId: info.id,
+    entityName: info.name,
+    narrativeProse: result.narrativeProse,
+    intents: [],
+    timestamp: worldState.clock.get().toISOString(),
+  };
+
+  if (
+    session.actorProvider.lastCalls &&
+    session.actorProvider.lastCalls.length > 0
+  ) {
+    const actorCall =
+      session.actorProvider.lastCalls[
+        session.actorProvider.lastCalls.length - 1
+      ];
+    entry.rawPrompt = {
+      systemPrompt: actorCall.systemPrompt,
+      userContext: actorCall.userContext,
+    };
+    entry.usage = actorCall.usage;
+  }
+
+  if (
+    session.decoderProvider.lastCalls &&
+    session.decoderProvider.lastCalls.length > 0
+  ) {
+    const decoderCall =
+      session.decoderProvider.lastCalls[
+        session.decoderProvider.lastCalls.length - 1
+      ];
+    entry.decoderPrompt = {
+      systemPrompt: decoderCall.systemPrompt,
+      userContext: decoderCall.userContext,
+    };
+    entry.decoderUsage = decoderCall.usage;
+  }
+
+  entry.intents = await processIntents(
+    result.intents.intents,
+    info.id,
+    entity,
+    worldState,
+    session,
+  );
+
+  session.log.push(entry);
+  session.coreRepo.saveWorldState(worldState);
+}
+
+/**
+ * Executes the player's turn using the prose they supplied.
+ * Uses a `FixedProseGenerator` so the ActorAgent bypasses its LLM call and
+ * returns the player's text directly.
+ */
+export async function executePlayerAction(
+  session: SimSession,
+  ctx: WaitingContext,
+  prose: string,
+): Promise<void> {
+  const worldState = session.coreRepo.loadWorldState(session.worldInstanceId);
+  if (!worldState) throw new Error("World state lost");
+
+  const entity = worldState.getEntity(ctx.entityId);
+  if (!entity) throw new Error(`Player entity "${ctx.entityId}" not found`);
+
+  const playerActor = new ActorAgent(
+    { actor: session.actorProvider, decoder: session.decoderProvider },
+    session.bufferRepo,
+    session.ledgerRepo,
+    20,
+    new FixedProseGenerator(prose),
+  );
+
+  const result = await playerActor.act(worldState, entity);
+
+  const entry: LogEntry = {
+    turn: session.turn,
+    entityId: ctx.entityId,
+    entityName: ctx.name,
+    narrativeProse: result.narrativeProse,
+    intents: [],
+    timestamp: worldState.clock.get().toISOString(),
+    rawPrompt: {
+      systemPrompt: ctx.systemPrompt,
+      userContext: ctx.userContext,
+    },
+  };
+
+  if (
+    session.decoderProvider.lastCalls &&
+    session.decoderProvider.lastCalls.length > 0
+  ) {
+    const call =
+      session.decoderProvider.lastCalls[
+        session.decoderProvider.lastCalls.length - 1
+      ];
+    entry.decoderPrompt = {
+      systemPrompt: call.systemPrompt,
+      userContext: call.userContext,
+    };
+    entry.decoderUsage = call.usage;
+  }
+
+  entry.intents = await processIntents(
+    result.intents.intents,
+    ctx.entityId,
+    entity,
+    worldState,
+    session,
+  );
+
+  session.log.push(entry);
+  session.coreRepo.saveWorldState(worldState);
+}

apps/gui/src/lib/simulation/types.ts

@@ -0,0 +1,68 @@
+import type Database from "better-sqlite3";
+import type { SQLiteRepository } from "@omnia/core";
+import type { BufferRepository, LedgerRepository } from "@omnia/memory";
+import type { Architect, AliasDeltaGenerator } from "@omnia/architect";
+import type { ILLMProvider, IEmbeddingProvider } from "@omnia/llm";
+import type { EntityInfo, LogEntry, WaitingContext } from "../simulation-types";
+
+export type {
+  EntityInfo,
+  IntentInfo,
+  LogEntry,
+  SimSnapshot,
+  WaitingContext,
+} from "../simulation-types";
+
+// ---------------------------------------------------------------------------
+// Persisted state (written to sqlite gui_meta table as JSON)
+// ---------------------------------------------------------------------------
+
+export interface SavedState {
+  scenarioName: string;
+  scenarioDescription: string;
+  turn: number;
+  maxTurns: number;
+  entities: EntityInfo[];
+  playerEntityId: string | undefined;
+  entityIndex: number;
+  status: "running" | "waiting_player" | "done" | "error";
+  error?: string;
+  waitingEntity?: WaitingContext;
+  aliasDoneForTurn: boolean;
+  log: LogEntry[];
+  providerMappings: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// In-memory session (held in SimulationManager.sessions Map)
+// ---------------------------------------------------------------------------
+
+export interface SimSession {
+  db: Database.Database;
+  dbPath: string;
+  coreRepo: SQLiteRepository;
+  bufferRepo: BufferRepository;
+  ledgerRepo: LedgerRepository;
+  worldInstanceId: string;
+  scenarioName: string;
+  scenarioDescription: string;
+  turn: number;
+  maxTurns: number;
+  entities: EntityInfo[];
+  playerEntityId: string | undefined;
+  entityIndex: number;
+  actorProvider: ILLMProvider;
+  validatorProvider: ILLMProvider;
+  decoderProvider: ILLMProvider;
+  timedeltaProvider: ILLMProvider;
+  handoffProvider: ILLMProvider;
+  embeddingProvider: IEmbeddingProvider;
+  architect: Architect;
+  aliasGenerator: AliasDeltaGenerator;
+  log: LogEntry[];
+  status: "running" | "waiting_player" | "done" | "error";
+  error?: string;
+  waitingEntity?: WaitingContext;
+  aliasDoneForTurn: boolean;
+  providerMappings: Record<string, string>;
+}

apps/gui/tsconfig.json

@@ -1,11 +1,7 @@
 {
   "compilerOptions": {
     "target": "ES2022",
-    "lib": [
-      "dom",
-      "dom.iterable",
-      "esnext"
-    ],
+    "lib": ["dom", "dom.iterable", "esnext"],
     "allowJs": true,
     "skipLibCheck": true,
     "strict": true,
@@ -23,9 +19,7 @@
       }
     ],
     "paths": {
-      "@/*": [
-        "./src/*"
-      ]
+      "@/*": ["./src/*"]
     }
   },
   "include": [
@@ -35,7 +29,5 @@
     ".next/types/**/*.ts",
     ".next/dev/types/**/*.ts"
   ],
-  "exclude": [
-    "node_modules"
-  ]
+  "exclude": ["node_modules"]
 }

eslint.config.mjs

@@ -5,7 +5,12 @@ import tseslint from "typescript-eslint";
 
 export default [
   {
-    ignores: ["**/dist/**", "**/node_modules/**", "**/.astro/**", "**/.next/**"],
+    ignores: [
+      "**/dist/**",
+      "**/node_modules/**",
+      "**/.astro/**",
+      "**/.next/**",
+    ],
   },
 
   js.configs.recommended,

package.json

@@ -19,7 +19,8 @@
     "watch": "tsc -b --watch",
     "test": "vitest run --project unit",
     "test:watch": "vitest --project unit",
-    "test:evals": "vitest run --project evals"
+    "test:evals": "vitest run --project evals",
+    "setup-provider": "node packages/llm/dist/bin/setup-provider.js"
   },
   "keywords": [],
   "author": "sortedcord",
@@ -27,7 +28,7 @@
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "^11.9.0",
+      "version": "11.13.0",
       "onFail": "download"
     }
   },
@@ -47,7 +48,12 @@
     "zod": "^4.4.3"
   },
   "dependencies": {
+    "@langchain/anthropic": "^0.3.11",
+    "@langchain/deepseek": "^1.1.5",
     "@langchain/google-genai": "^2.2.0",
+    "@langchain/groq": "^1.3.1",
+    "@langchain/ollama": "^0.2.3",
+    "@langchain/openai": "^0.3.17",
     "@langchain/openrouter": "^0.4.3",
     "@types/node": "^20.19.43",
     "dotenv": "^17.4.2"

packages/actor/src/actor.ts

@@ -1,23 +1,22 @@
 import { Entity, WorldState } from "@omnia/core";
 import { ILLMProvider } from "@omnia/llm";
+import { BufferEntry, BufferRepository, LedgerRepository } from "@omnia/memory";
+import { Intent, IntentDecoder, IntentSequence } from "@omnia/intent";
 import {
-  BufferEntry,
-  BufferRepository,
-  LedgerRepository,
-} from "@omnia/memory";
-import {
-  Intent,
-  IntentDecoder,
-  IntentSequence,
-} from "@omnia/intent";
-import { ActorPromptBuilder, ActorResponseSchema } from "./actor-prompt-builder.js";
+  ActorPromptBuilder,
+  ActorResponseSchema,
+} from "./actor-prompt-builder.js";
 
 /**
  * Interface to generate narrative prose for an actor.
  * Allows switching between LLM generators and human CLI inputs.
  */
 export interface IActorProseGenerator {
-  generate(entityId: string, systemPrompt: string, userContext: string): Promise<string>;
+  generate(
+    entityId: string,
+    systemPrompt: string,
+    userContext: string,
+  ): Promise<string>;
 }
 
 /**
@@ -26,7 +25,11 @@ export interface IActorProseGenerator {
 export class LLMActorProseGenerator implements IActorProseGenerator {
   constructor(private llmProvider: ILLMProvider) {}
 
-  async generate(entityId: string, systemPrompt: string, userContext: string): Promise<string> {
+  async generate(
+    entityId: string,
+    systemPrompt: string,
+    userContext: string,
+  ): Promise<string> {
     const response = await this.llmProvider.generateStructuredResponse({
       systemPrompt,
       userContext,
@@ -89,7 +92,11 @@ export class ActorAgent {
       decoderProv = llmProvider;
     }
 
-    this.promptBuilder = new ActorPromptBuilder(bufferRepo, ledgerRepo, memoryLimit);
+    this.promptBuilder = new ActorPromptBuilder(
+      bufferRepo,
+      ledgerRepo,
+      memoryLimit,
+    );
     this.decoder = new IntentDecoder(decoderProv);
     this.generator = generator ?? new LLMActorProseGenerator(actorProv);
     this.llmProvider = actorProv;
@@ -102,10 +109,13 @@ export class ActorAgent {
    * 2. Asks the generator (LLM or human) for narrative prose.
    * 3. Decodes the prose into a structured IntentSequence.
    */
-  async act(
-    worldState: WorldState,
-    entity: Entity,
-  ): Promise<ActorTurnResult> {
+  async act(worldState: WorldState, entity: Entity): Promise<ActorTurnResult> {
+    if (!entity.isAgent) {
+      throw new Error(
+        `Entity "${entity.id}" is not an agent and cannot use the actor interface.`,
+      );
+    }
+
     const { systemPrompt, userContext } = this.promptBuilder.build(
       worldState,
       entity,

packages/actor/tests/actor-prompt-builder.test.ts

@@ -11,7 +11,7 @@ describe("ActorPromptBuilder with Long-Term Memory Integration", () => {
 
   beforeEach(() => {
     db = new Database(":memory:");
-    
+
     // Core database schemas for testing
     db.exec(`
       CREATE TABLE objects (
@@ -32,8 +32,11 @@ describe("ActorPromptBuilder with Long-Term Memory Integration", () => {
   });
 
   it("should inject both recent memory and recalled long-term memory with subjective aliases resolved", () => {
-    const world = new WorldState("world-123", new Date("2024-01-10T12:00:00.000Z"));
-    
+    const world = new WorldState(
+      "world-123",
+      new Date("2024-01-10T12:00:00.000Z"),
+    );
+
     const alice = new Entity("alice", "tavern");
     // Add subjective alias for bob
     alice.aliases.set("bob", "Strider");
@@ -85,7 +88,10 @@ describe("ActorPromptBuilder with Long-Term Memory Integration", () => {
   });
 
   it("should not explode if ledger contains no memories or is empty", () => {
-    const world = new WorldState("world-123", new Date("2024-01-10T12:00:00.000Z"));
+    const world = new WorldState(
+      "world-123",
+      new Date("2024-01-10T12:00:00.000Z"),
+    );
     const alice = new Entity("alice", "tavern");
     world.addEntity(alice);
 

packages/actor/tests/actor.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from "vitest";
+import { WorldState, Entity } from "@omnia/core";
+import { ActorAgent } from "../src/actor.js";
+import { MockLLMProvider } from "@omnia/llm";
+
+describe("ActorAgent Unit Tests", () => {
+  it("should throw an error if trying to act with a non-agent entity", async () => {
+    const world = new WorldState("world-123");
+    const nonAgentEntity = new Entity("stone", null, false); // isAgent = false
+    world.addEntity(nonAgentEntity);
+
+    const mockLlm = new MockLLMProvider([]);
+    const actor = new ActorAgent(mockLlm);
+
+    await expect(actor.act(world, nonAgentEntity)).rejects.toThrow(
+      'Entity "stone" is not an agent and cannot use the actor interface.',
+    );
+  });
+});

packages/architect/src/architect.ts

@@ -13,7 +13,8 @@ export class Architect {
   private timeDeltaGenerator: TimeDeltaGenerator;
 
   constructor(
-    llmProvider: ILLMProvider | { validator: ILLMProvider; timedelta: ILLMProvider },
+    llmProvider:
+      ILLMProvider | { validator: ILLMProvider; timedelta: ILLMProvider },
     private repo?: SQLiteRepository,
   ) {
     let valProv: ILLMProvider;
@@ -60,8 +61,12 @@ export class Architect {
     if (intent.type === "monologue") {
       return {
         isValid: true,
-        reason: "Monologue intent bypasses validation (internal thought, not perceivable).",
-        timeDelta: { minutesToAdvance: 0, explanation: "Internal thought — no time elapsed." },
+        reason:
+          "Monologue intent bypasses validation (internal thought, not perceivable).",
+        timeDelta: {
+          minutesToAdvance: 0,
+          explanation: "Internal thought — no time elapsed.",
+        },
       };
     }
 

packages/architect/src/index.ts

@@ -1,4 +1,3 @@
 export * from "./llm-validator.js";
 export * from "./architect.js";
 export * from "./delta.js";
-

packages/architect/src/llm-validator.ts

@@ -28,7 +28,8 @@ export class LLMValidator {
     if (intent.type === "monologue") {
       return {
         isValid: true,
-        reason: "Monologue intents are internal thoughts and bypass validation.",
+        reason:
+          "Monologue intents are internal thoughts and bypass validation.",
       };
     }
 

packages/architect/tests/architect.test.ts

@@ -1,6 +1,11 @@
 import { describe, test, expect } from "vitest";
 import Database from "better-sqlite3";
-import { WorldState, Entity, SQLiteRepository, AttributeVisibility } from "@omnia/core";
+import {
+  WorldState,
+  Entity,
+  SQLiteRepository,
+  AttributeVisibility,
+} from "@omnia/core";
 import { MockLLMProvider } from "@omnia/llm";
 import { Architect, AliasDeltaGenerator } from "@omnia/architect";
 import { Intent } from "@omnia/intent";
@@ -96,7 +101,10 @@ describe("TimeDeltaGenerator & Architect.processIntent Unit Tests (Tier 1)", ()
     const db = new Database(":memory:");
     const repo = new SQLiteRepository(db);
 
-    const world = new WorldState("world-xyz", new Date("2026-07-06T12:00:00.000Z"));
+    const world = new WorldState(
+      "world-xyz",
+      new Date("2026-07-06T12:00:00.000Z"),
+    );
     const alice = new Entity("alice");
     world.addEntity(alice);
 
@@ -106,8 +114,14 @@ describe("TimeDeltaGenerator & Architect.processIntent Unit Tests (Tier 1)", ()
     // Setup mock LLM responses:
     // First call: validateIntent (ValidationResult)
     // Second call: TimeDeltaGenerator (TimeDelta)
-    const mockValidation = { isValid: true, reason: "Alice has the lockpick kit and skill." };
-    const mockTimeDelta = { minutesToAdvance: 20, explanation: "Picking a lock takes time." };
+    const mockValidation = {
+      isValid: true,
+      reason: "Alice has the lockpick kit and skill.",
+    };
+    const mockTimeDelta = {
+      minutesToAdvance: 20,
+      explanation: "Picking a lock takes time.",
+    };
     const llmProvider = new MockLLMProvider([mockValidation, mockTimeDelta]);
 
     const architect = new Architect(llmProvider, repo);
@@ -131,7 +145,9 @@ describe("TimeDeltaGenerator & Architect.processIntent Unit Tests (Tier 1)", ()
     expect(result.timeDelta!.minutesToAdvance).toBe(20);
 
     // Verify clock was advanced locally
-    const expectedTime = new Date(new Date("2026-07-06T12:00:00.000Z").getTime() + 20 * 60_000);
+    const expectedTime = new Date(
+      new Date("2026-07-06T12:00:00.000Z").getTime() + 20 * 60_000,
+    );
     expect(world.clock.get().toISOString()).toBe(expectedTime.toISOString());
 
     // Verify it was persisted to the database
@@ -151,7 +167,10 @@ describe("TimeDeltaGenerator & Architect.processIntent Unit Tests (Tier 1)", ()
     world.addEntity(bob);
     repo.saveWorldState(world);
 
-    const mockValidation = { isValid: false, reason: "Bob is bound by chains." };
+    const mockValidation = {
+      isValid: false,
+      reason: "Bob is bound by chains.",
+    };
     const llmProvider = new MockLLMProvider([mockValidation]); // TimeDeltaGenerator shouldn't be called
 
     const architect = new Architect(llmProvider, repo);
@@ -188,8 +207,16 @@ describe("AliasDeltaGenerator Unit Tests (Tier 1)", () => {
     const world = new WorldState("world-1");
     const viewer = new Entity("viewer-1");
     const target = new Entity("target-1");
-    target.addAttribute("appearance", "A tall elf with silver hair", AttributeVisibility.PUBLIC);
-    target.addAttribute("clothing", "A green tunic", AttributeVisibility.PUBLIC);
+    target.addAttribute(
+      "appearance",
+      "A tall elf with silver hair",
+      AttributeVisibility.PUBLIC,
+    );
+    target.addAttribute(
+      "clothing",
+      "A green tunic",
+      AttributeVisibility.PUBLIC,
+    );
     world.addEntity(viewer);
     world.addEntity(target);
 

packages/core/src/clock.ts

@@ -85,7 +85,7 @@ export function naturalizeTime(now: Date, past: Date): string {
   const nowHour = now.getHours();
   const pastIsWaking = pastHour >= 5 && pastHour < 22;
   const nowIsWaking = nowHour >= 5 && nowHour < 22;
-  
+
   const isSameSubjectiveDay = pastIsWaking && nowIsWaking && deltaHours < 18;
 
   if (isSameSubjectiveDay) {

packages/core/src/entity.ts

@@ -3,9 +3,11 @@ import { AttributableObject } from "./attribute.js";
 export class Entity extends AttributableObject {
   locationId: string | null = null;
   readonly aliases: Map<string, string> = new Map();
+  isAgent: boolean = true;
 
-  constructor(id?: string, locationId?: string | null) {
+  constructor(id?: string, locationId?: string | null, isAgent?: boolean) {
     super(id);
     this.locationId = locationId ?? null;
+    this.isAgent = isAgent ?? true;
   }
 }

packages/core/src/index.ts

@@ -10,4 +10,3 @@ export * from "./world.js";
 export * from "./clock.js";
 export * from "./repository.js";
 export * from "./alias.js";
-

packages/core/src/repository.ts

@@ -73,6 +73,13 @@ export class SQLiteRepository {
     } catch {
       // Column already exists, ignore error
     }
+
+    // Safely add is_agent column if it does not exist in an existing database
+    try {
+      this.db.exec("ALTER TABLE objects ADD COLUMN is_agent INTEGER;");
+    } catch {
+      // Column already exists, ignore error
+    }
   }
 
   save(obj: AttributableObject, type: string, worldId?: string): void {
@@ -85,15 +92,20 @@ export class SQLiteRepository {
       let locationId: string | null = null;
       let aliasesJson: string | null = null;
       let connectionsJson: string | null = null;
+      let isAgent: number | null = null;
 
       if (obj instanceof Entity) {
         locationId = obj.locationId;
         aliasesJson = JSON.stringify(Array.from(obj.aliases.entries()));
+        isAgent = obj.isAgent ? 1 : 0;
       }
 
       // Check if it's a location (using duck typing to avoid circular import of Location)
       if (type === "location") {
-        const loc = obj as { parentId?: string | null; connections?: unknown[] };
+        const loc = obj as {
+          parentId?: string | null;
+          connections?: unknown[];
+        };
         locationId = loc.parentId ?? null;
         if (loc.connections) {
           connectionsJson = JSON.stringify(loc.connections);
@@ -104,18 +116,28 @@ export class SQLiteRepository {
       this.db
         .prepare(
           `
-        INSERT INTO objects (id, type, world_id, clock_iso, location_id, aliases_json, connections_json)
-        VALUES (?, ?, ?, ?, ?, ?, ?)
+        INSERT INTO objects (id, type, world_id, clock_iso, location_id, aliases_json, connections_json, is_agent)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
         ON CONFLICT(id) DO UPDATE SET 
           type = excluded.type, 
           world_id = excluded.world_id,
           clock_iso = excluded.clock_iso,
           location_id = excluded.location_id,
           aliases_json = excluded.aliases_json,
-          connections_json = excluded.connections_json
+          connections_json = excluded.connections_json,
+          is_agent = excluded.is_agent
       `,
         )
-        .run(obj.id, type, worldId || null, clockIso, locationId, aliasesJson, connectionsJson);
+        .run(
+          obj.id,
+          type,
+          worldId || null,
+          clockIso,
+          locationId,
+          aliasesJson,
+          connectionsJson,
+          isAgent,
+        );
 
       // Get current attributes from db to delete the ones that are no longer present
       const existingAttrs = this.db
@@ -208,16 +230,27 @@ export class SQLiteRepository {
     const objRow = this.db
       .prepare(
         `
-      SELECT type, location_id, aliases_json FROM objects WHERE id = ?
+      SELECT type, location_id, aliases_json, is_agent FROM objects WHERE id = ?
     `,
       )
-      .get(id) as { type: string; location_id: string | null; aliases_json: string | null } | undefined;
+      .get(id) as
+      | {
+          type: string;
+          location_id: string | null;
+          aliases_json: string | null;
+          is_agent: number | null;
+        }
+      | undefined;
 
     if (!objRow || objRow.type !== "entity") {
       return null;
     }
 
-    const entity = new Entity(id, objRow.location_id);
+    const entity = new Entity(
+      id,
+      objRow.location_id,
+      objRow.is_agent !== null ? objRow.is_agent === 1 : true,
+    );
     if (objRow.aliases_json) {
       const entries = JSON.parse(objRow.aliases_json) as [string, string][];
       for (const [k, v] of entries) {
@@ -238,7 +271,13 @@ export class SQLiteRepository {
       SELECT type, location_id, connections_json FROM objects WHERE id = ?
     `,
       )
-      .get(id) as { type: string; location_id: string | null; connections_json: string | null } | undefined;
+      .get(id) as
+      | {
+          type: string;
+          location_id: string | null;
+          connections_json: string | null;
+        }
+      | undefined;
 
     if (!objRow || objRow.type !== "location") {
       return null;
@@ -246,7 +285,9 @@ export class SQLiteRepository {
 
     const location = factory(id, objRow.location_id);
     if (objRow.connections_json) {
-      (location as { connections?: unknown[] }).connections = JSON.parse(objRow.connections_json);
+      (location as { connections?: unknown[] }).connections = JSON.parse(
+        objRow.connections_json,
+      );
     }
     this.reconstituteAttributes(location);
     return location;
@@ -262,13 +303,19 @@ export class SQLiteRepository {
       SELECT id, location_id, connections_json FROM objects WHERE type = 'location' AND world_id = ?
     `,
       )
-      .all(worldId) as { id: string; location_id: string | null; connections_json: string | null }[];
+      .all(worldId) as {
+      id: string;
+      location_id: string | null;
+      connections_json: string | null;
+    }[];
 
     const locations: T[] = [];
     for (const row of rows) {
       const loc = factory(row.id, row.location_id);
       if (row.connections_json) {
-        (loc as { connections?: unknown[] }).connections = JSON.parse(row.connections_json);
+        (loc as { connections?: unknown[] }).connections = JSON.parse(
+          row.connections_json,
+        );
       }
       this.reconstituteAttributes(loc);
       locations.push(loc);
@@ -300,13 +347,19 @@ export class SQLiteRepository {
       SELECT id, location_id, connections_json FROM objects WHERE type = 'location' AND world_id = ?
     `,
       )
-      .all(id) as { id: string; location_id: string | null; connections_json: string | null }[];
+      .all(id) as {
+      id: string;
+      location_id: string | null;
+      connections_json: string | null;
+    }[];
 
     for (const row of locationRows) {
       const loc = new GenericObject(row.id);
       (loc as { parentId?: string | null }).parentId = row.location_id;
       if (row.connections_json) {
-        (loc as { connections?: unknown[] }).connections = JSON.parse(row.connections_json);
+        (loc as { connections?: unknown[] }).connections = JSON.parse(
+          row.connections_json,
+        );
       }
       this.reconstituteAttributes(loc);
       worldState.addLocation(loc);
@@ -316,13 +369,22 @@ export class SQLiteRepository {
     const entityRows = this.db
       .prepare(
         `
-      SELECT id, location_id, aliases_json FROM objects WHERE type = 'entity' AND world_id = ?
+      SELECT id, location_id, aliases_json, is_agent FROM objects WHERE type = 'entity' AND world_id = ?
     `,
       )
-      .all(id) as { id: string; location_id: string | null; aliases_json: string | null }[];
+      .all(id) as {
+      id: string;
+      location_id: string | null;
+      aliases_json: string | null;
+      is_agent: number | null;
+    }[];
 
     for (const row of entityRows) {
-      const entity = new Entity(row.id, row.location_id);
+      const entity = new Entity(
+        row.id,
+        row.location_id,
+        row.is_agent !== null ? row.is_agent === 1 : true,
+      );
       if (row.aliases_json) {
         const entries = JSON.parse(row.aliases_json) as [string, string][];
         for (const [k, v] of entries) {
@@ -340,14 +402,22 @@ export class SQLiteRepository {
     const rows = this.db
       .prepare(
         `
-      SELECT id, aliases_json FROM objects WHERE type = 'entity'
+      SELECT id, aliases_json, is_agent FROM objects WHERE type = 'entity'
     `,
       )
-      .all() as { id: string; aliases_json: string | null }[];
+      .all() as {
+      id: string;
+      aliases_json: string | null;
+      is_agent: number | null;
+    }[];
 
     const entities: Entity[] = [];
     for (const row of rows) {
-      const entity = new Entity(row.id);
+      const entity = new Entity(
+        row.id,
+        null,
+        row.is_agent !== null ? row.is_agent === 1 : true,
+      );
       if (row.aliases_json) {
         const entries = JSON.parse(row.aliases_json) as [string, string][];
         for (const [k, v] of entries) {

packages/core/src/world.ts

@@ -1,4 +1,8 @@
-import { AttributableObject, Attribute, serializeAttributes } from "./attribute.js";
+import {
+  AttributableObject,
+  Attribute,
+  serializeAttributes,
+} from "./attribute.js";
 import { Entity } from "./entity.js";
 import { WorldClock } from "./clock.js";
 import { resolveAlias } from "./alias.js";
@@ -54,8 +58,15 @@ export function serializeObjectiveWorldState(worldState: WorldState): string {
   // Serialize world attributes
   if (worldState.attributes.size > 0) {
     lines.push("World Attributes:");
-    const worldAttrsStr = serializeAttributes(Array.from(worldState.attributes.values()));
-    lines.push(worldAttrsStr.split("\n").map(l => "  " + l).join("\n"));
+    const worldAttrsStr = serializeAttributes(
+      Array.from(worldState.attributes.values()),
+    );
+    lines.push(
+      worldAttrsStr
+        .split("\n")
+        .map((l) => "  " + l)
+        .join("\n"),
+    );
   }
 
   // Serialize locations and their attributes/portals
@@ -63,33 +74,46 @@ export function serializeObjectiveWorldState(worldState: WorldState): string {
   if (worldState.locations.size > 0) {
     for (const loc of worldState.locations.values()) {
       lines.push(`  - Location [ID: ${loc.id}]:`);
-      
+
       const parentId = (loc as { parentId?: string | null }).parentId;
       if (parentId) {
         lines.push(`      * Parent Location ID: ${parentId}`);
       }
-      
+
       if (loc.attributes.size > 0) {
-        const locAttrsStr = serializeAttributes(Array.from(loc.attributes.values()));
-        lines.push(locAttrsStr.split("\n").map(l => "      " + l).join("\n"));
+        const locAttrsStr = serializeAttributes(
+          Array.from(loc.attributes.values()),
+        );
+        lines.push(
+          locAttrsStr
+            .split("\n")
+            .map((l) => "      " + l)
+            .join("\n"),
+        );
       } else {
         lines.push("      * (No attributes)");
       }
 
-      const connections = (loc as { connections?: unknown[] }).connections as {
-        targetId: string;
-        portalName?: string;
-        portalStateDescriptor?: string;
-        visionProp: number;
-        soundProp: number;
-        bidirectional: boolean;
-      }[] | undefined;
+      const connections = (loc as { connections?: unknown[] }).connections as
+        | {
+            targetId: string;
+            portalName?: string;
+            portalStateDescriptor?: string;
+            visionProp: number;
+            soundProp: number;
+            bidirectional: boolean;
+          }[]
+        | undefined;
 
       if (connections && connections.length > 0) {
         lines.push("      * Connections:");
         for (const conn of connections) {
-          const portalStr = conn.portalName ? ` via ${conn.portalName} (${conn.portalStateDescriptor || "normal"})` : "";
-          lines.push(`          -> To: ${conn.targetId}${portalStr} (Vision: ${conn.visionProp}, Sound: ${conn.soundProp})`);
+          const portalStr = conn.portalName
+            ? ` via ${conn.portalName} (${conn.portalStateDescriptor || "normal"})`
+            : "";
+          lines.push(
+            `          -> To: ${conn.targetId}${portalStr} (Vision: ${conn.visionProp}, Sound: ${conn.soundProp})`,
+          );
         }
       }
     }
@@ -106,8 +130,15 @@ export function serializeObjectiveWorldState(worldState: WorldState): string {
         lines.push(`      * Location ID: ${entity.locationId}`);
       }
       if (entity.attributes.size > 0) {
-        const entityAttrsStr = serializeAttributes(Array.from(entity.attributes.values()));
-        lines.push(entityAttrsStr.split("\n").map(l => "      " + l).join("\n"));
+        const entityAttrsStr = serializeAttributes(
+          Array.from(entity.attributes.values()),
+        );
+        lines.push(
+          entityAttrsStr
+            .split("\n")
+            .map((l) => "      " + l)
+            .join("\n"),
+        );
       } else {
         lines.push("      * (No attributes)");
       }
@@ -119,7 +150,6 @@ export function serializeObjectiveWorldState(worldState: WorldState): string {
   return lines.join("\n");
 }
 
-
 /**
  * Serializes a single attribute the way a viewer perceives it — name and
  * value only, no visibility/ACL metadata (the viewer already sees only
@@ -158,13 +188,23 @@ export function serializeSubjectiveWorldState(
   const worldVisible = worldState.getVisibleAttributesFor(viewerId);
   if (worldVisible.length > 0) {
     lines.push("World (as you know it):");
-    lines.push(serializeVisibleAttributes(worldVisible).split("\n").map((l) => "  " + l).join("\n"));
+    lines.push(
+      serializeVisibleAttributes(worldVisible)
+        .split("\n")
+        .map((l) => "  " + l)
+        .join("\n"),
+    );
   }
 
   // --- Self ---
   lines.push(`Self (${viewerAlias}):`);
   const selfVisible = viewer.getVisibleAttributesFor(viewerId);
-  lines.push(serializeVisibleAttributes(selfVisible).split("\n").map((l) => "  " + l).join("\n"));
+  lines.push(
+    serializeVisibleAttributes(selfVisible)
+      .split("\n")
+      .map((l) => "  " + l)
+      .join("\n"),
+  );
 
   // --- Location / perceived entities ---
   lines.push("What you perceive around you:");
@@ -175,7 +215,12 @@ export function serializeSubjectiveWorldState(
       const locVisible = location.getVisibleAttributesFor(viewerId);
       if (locVisible.length > 0) {
         lines.push("    Location attributes:");
-        lines.push(serializeVisibleAttributes(locVisible).split("\n").map((l) => "      " + l).join("\n"));
+        lines.push(
+          serializeVisibleAttributes(locVisible)
+            .split("\n")
+            .map((l) => "      " + l)
+            .join("\n"),
+        );
       }
     }
   } else {
@@ -199,7 +244,12 @@ export function serializeSubjectiveWorldState(
       const alias = resolveAlias(viewer, e.id);
       lines.push(`    - ${alias}:`);
       const eVisible = e.getVisibleAttributesFor(viewerId);
-      lines.push(serializeVisibleAttributes(eVisible).split("\n").map((l) => "      " + l).join("\n"));
+      lines.push(
+        serializeVisibleAttributes(eVisible)
+          .split("\n")
+          .map((l) => "      " + l)
+          .join("\n"),
+      );
     }
   } else {
     lines.push("  You are alone here.");

packages/core/tests/clock.test.ts

@@ -11,23 +11,39 @@ describe("TimeNaturalization Unit Tests (Tier 1)", () => {
 
   test("Tier 1: relative time ranges (< 6 hours)", () => {
     const now = new Date(2026, 6, 8, 12, 0, 0);
-    
+
     // < 1 minute
-    expect(naturalizeTime(now, new Date(2026, 6, 8, 11, 59, 30))).toBe("just now");
+    expect(naturalizeTime(now, new Date(2026, 6, 8, 11, 59, 30))).toBe(
+      "just now",
+    );
     // < 3 minutes
-    expect(naturalizeTime(now, new Date(2026, 6, 8, 11, 58, 0))).toBe("moments ago");
+    expect(naturalizeTime(now, new Date(2026, 6, 8, 11, 58, 0))).toBe(
+      "moments ago",
+    );
     // < 10 minutes
-    expect(naturalizeTime(now, new Date(2026, 6, 8, 11, 52, 0))).toBe("a few minutes ago");
+    expect(naturalizeTime(now, new Date(2026, 6, 8, 11, 52, 0))).toBe(
+      "a few minutes ago",
+    );
     // < 30 minutes
-    expect(naturalizeTime(now, new Date(2026, 6, 8, 11, 40, 0))).toBe("several minutes ago");
+    expect(naturalizeTime(now, new Date(2026, 6, 8, 11, 40, 0))).toBe(
+      "several minutes ago",
+    );
     // < 45 minutes
-    expect(naturalizeTime(now, new Date(2026, 6, 8, 11, 20, 0))).toBe("about half an hour ago");
+    expect(naturalizeTime(now, new Date(2026, 6, 8, 11, 20, 0))).toBe(
+      "about half an hour ago",
+    );
     // < 1.5 hours (90 minutes)
-    expect(naturalizeTime(now, new Date(2026, 6, 8, 10, 50, 0))).toBe("about an hour ago");
+    expect(naturalizeTime(now, new Date(2026, 6, 8, 10, 50, 0))).toBe(
+      "about an hour ago",
+    );
     // < 3 hours
-    expect(naturalizeTime(now, new Date(2026, 6, 8, 9, 30, 0))).toBe("a couple hours ago");
+    expect(naturalizeTime(now, new Date(2026, 6, 8, 9, 30, 0))).toBe(
+      "a couple hours ago",
+    );
     // < 6 hours
-    expect(naturalizeTime(now, new Date(2026, 6, 8, 7, 0, 0))).toBe("a few hours ago");
+    expect(naturalizeTime(now, new Date(2026, 6, 8, 7, 0, 0))).toBe(
+      "a few hours ago",
+    );
   });
 
   test("Tier 2: Same subjective day vs yesterday periods (6h <= delta < 48h)", () => {
@@ -35,12 +51,16 @@ describe("TimeNaturalization Unit Tests (Tier 1)", () => {
     // 9am to 3pm (delta 6h) -> morning
     const nowWaking = new Date(2026, 6, 8, 15, 0, 0);
     const pastMorning = new Date(2026, 6, 8, 9, 0, 0);
-    expect(naturalizeTime(nowWaking, pastMorning)).toBe("earlier today, in the morning");
+    expect(naturalizeTime(nowWaking, pastMorning)).toBe(
+      "earlier today, in the morning",
+    );
 
     // 2pm to 9pm (delta 7h) -> afternoon
     const nowEvening = new Date(2026, 6, 8, 21, 0, 0);
     const pastAfternoon = new Date(2026, 6, 8, 14, 0, 0);
-    expect(naturalizeTime(nowEvening, pastAfternoon)).toBe("earlier today, in the afternoon");
+    expect(naturalizeTime(nowEvening, pastAfternoon)).toBe(
+      "earlier today, in the afternoon",
+    );
 
     // 2. Previous night (past period: night (21-23))
     // 11pm to 5am (delta 6h) -> last night
@@ -52,45 +72,73 @@ describe("TimeNaturalization Unit Tests (Tier 1)", () => {
     // 1am to 7am (delta 6h) -> around midnight
     const nowMidnightRun = new Date(2026, 6, 8, 7, 0, 0);
     const pastMidnight = new Date(2026, 6, 8, 1, 0, 0);
-    expect(naturalizeTime(nowMidnightRun, pastMidnight)).toBe("around midnight");
+    expect(naturalizeTime(nowMidnightRun, pastMidnight)).toBe(
+      "around midnight",
+    );
 
     // 4. Late night (past period: late night (3-4))
     // 3am to 9am (delta 6h) -> late last night
     const nowLateNightRun = new Date(2026, 6, 8, 9, 0, 0);
     const pastLateNight = new Date(2026, 6, 8, 3, 0, 0);
-    expect(naturalizeTime(nowLateNightRun, pastLateNight)).toBe("late last night");
+    expect(naturalizeTime(nowLateNightRun, pastLateNight)).toBe(
+      "late last night",
+    );
 
     // 5. Yesterday waking hours (delta >= 6h, diff day / waking check fails)
     // 3pm to 9am next day (delta 18h) -> yesterday afternoon
     const nowNextDay = new Date(2026, 6, 9, 9, 0, 0);
     const pastYesterdayAfternoon = new Date(2026, 6, 8, 15, 0, 0);
-    expect(naturalizeTime(nowNextDay, pastYesterdayAfternoon)).toBe("yesterday afternoon");
+    expect(naturalizeTime(nowNextDay, pastYesterdayAfternoon)).toBe(
+      "yesterday afternoon",
+    );
   });
 
   test("Tier 3: Coarse relative time ranges (delta >= 48 hours)", () => {
     const now = new Date(2026, 6, 10, 12, 0, 0);
 
     // 2 days
-    expect(naturalizeTime(now, new Date(2026, 6, 8, 11, 0, 0))).toBe("a couple days ago");
+    expect(naturalizeTime(now, new Date(2026, 6, 8, 11, 0, 0))).toBe(
+      "a couple days ago",
+    );
     // 3-6 days
-    expect(naturalizeTime(now, new Date(2026, 6, 6, 12, 0, 0))).toBe("a few days ago");
+    expect(naturalizeTime(now, new Date(2026, 6, 6, 12, 0, 0))).toBe(
+      "a few days ago",
+    );
     // 7-13 days
-    expect(naturalizeTime(now, new Date(2026, 6, 1, 12, 0, 0))).toBe("about a week ago");
+    expect(naturalizeTime(now, new Date(2026, 6, 1, 12, 0, 0))).toBe(
+      "about a week ago",
+    );
     // 14-20 days
-    expect(naturalizeTime(now, new Date(2026, 5, 25, 12, 0, 0))).toBe("a couple weeks ago");
+    expect(naturalizeTime(now, new Date(2026, 5, 25, 12, 0, 0))).toBe(
+      "a couple weeks ago",
+    );
     // 21-29 days
-    expect(naturalizeTime(now, new Date(2026, 5, 15, 12, 0, 0))).toBe("a few weeks ago");
+    expect(naturalizeTime(now, new Date(2026, 5, 15, 12, 0, 0))).toBe(
+      "a few weeks ago",
+    );
     // 30-59 days
-    expect(naturalizeTime(now, new Date(2026, 5, 1, 12, 0, 0))).toBe("about a month ago");
+    expect(naturalizeTime(now, new Date(2026, 5, 1, 12, 0, 0))).toBe(
+      "about a month ago",
+    );
     // 60-89 days
-    expect(naturalizeTime(now, new Date(2026, 4, 1, 12, 0, 0))).toBe("a couple months ago");
+    expect(naturalizeTime(now, new Date(2026, 4, 1, 12, 0, 0))).toBe(
+      "a couple months ago",
+    );
     // 90-179 days
-    expect(naturalizeTime(now, new Date(2026, 3, 1, 12, 0, 0))).toBe("a few months ago");
+    expect(naturalizeTime(now, new Date(2026, 3, 1, 12, 0, 0))).toBe(
+      "a few months ago",
+    );
     // 180-364 days
-    expect(naturalizeTime(now, new Date(2026, 0, 1, 12, 0, 0))).toBe("many months ago");
+    expect(naturalizeTime(now, new Date(2026, 0, 1, 12, 0, 0))).toBe(
+      "many months ago",
+    );
     // 365-729 days
-    expect(naturalizeTime(now, new Date(2025, 6, 1, 12, 0, 0))).toBe("about a year ago");
+    expect(naturalizeTime(now, new Date(2025, 6, 1, 12, 0, 0))).toBe(
+      "about a year ago",
+    );
     // >= 730 days
-    expect(naturalizeTime(now, new Date(2023, 6, 1, 12, 0, 0))).toBe("years ago");
+    expect(naturalizeTime(now, new Date(2023, 6, 1, 12, 0, 0))).toBe(
+      "years ago",
+    );
   });
 });

packages/core/tests/core.test.ts

@@ -61,16 +61,21 @@ describe("Attribute & AttributableObject Unit Tests (Tier 1)", () => {
   test("AttributableObject visibility filtering", () => {
     const actor = new MockAttributable("actor");
     actor.addAttribute("eyes", "blue", AttributeVisibility.PUBLIC);
-    actor.addAttribute("secret", "42", AttributeVisibility.PRIVATE, new Set(["friend"]));
+    actor.addAttribute(
+      "secret",
+      "42",
+      AttributeVisibility.PRIVATE,
+      new Set(["friend"]),
+    );
 
     // Public viewer should only see public attributes
     const publicAttrs = actor.getVisibleAttributesFor("stranger");
-    expect(publicAttrs.map(a => a.name)).toEqual(["eyes"]);
+    expect(publicAttrs.map((a) => a.name)).toEqual(["eyes"]);
 
     // Authorized viewer should see both
     const privateAttrs = actor.getVisibleAttributesFor("friend");
-    expect(privateAttrs.map(a => a.name)).toContain("eyes");
-    expect(privateAttrs.map(a => a.name)).toContain("secret");
+    expect(privateAttrs.map((a) => a.name)).toContain("eyes");
+    expect(privateAttrs.map((a) => a.name)).toContain("secret");
   });
 });
 
@@ -131,7 +136,12 @@ describe("SQLiteRepository Unit Tests (Tier 1)", () => {
     const alice = new Entity("alice", "location-a");
     alice.addAttribute("name", "Alice Smith", AttributeVisibility.PUBLIC);
     // Secret attribute visible only to 'bob'
-    alice.addAttribute("diaries", "Private thoughts", AttributeVisibility.PRIVATE, new Set(["bob"]));
+    alice.addAttribute(
+      "diaries",
+      "Private thoughts",
+      AttributeVisibility.PRIVATE,
+      new Set(["bob"]),
+    );
     world.addEntity(alice);
 
     const bob = new Entity("bob");
@@ -161,7 +171,9 @@ describe("SQLiteRepository Unit Tests (Tier 1)", () => {
     expect(loadedAlice!.locationId).toBe("location-a");
     expect(loadedBob!.locationId).toBeNull();
     expect(loadedAlice!.attributes.get("name")?.getValue()).toBe("Alice Smith");
-    expect(loadedAlice!.attributes.get("name")?.visibility).toBe(AttributeVisibility.PUBLIC);
+    expect(loadedAlice!.attributes.get("name")?.visibility).toBe(
+      AttributeVisibility.PUBLIC,
+    );
 
     const diaryAttr = loadedAlice!.attributes.get("diaries")!;
     expect(diaryAttr.getValue()).toBe("Private thoughts");
@@ -191,17 +203,46 @@ describe("SQLiteRepository Unit Tests (Tier 1)", () => {
 
     db.close();
   });
+
+  test("Save and load entity isAgent property", () => {
+    const db = new Database(":memory:");
+    const repo = new SQLiteRepository(db);
+
+    const world = new WorldState("world-xyz");
+    const alice = new Entity("alice", null, false);
+    const bob = new Entity("bob", null, true);
+    world.addEntity(alice);
+    world.addEntity(bob);
+
+    repo.saveWorldState(world);
+
+    const loadedWorld = repo.loadWorldState("world-xyz")!;
+    const loadedAlice = loadedWorld.getEntity("alice")!;
+    const loadedBob = loadedWorld.getEntity("bob")!;
+
+    expect(loadedAlice.isAgent).toBe(false);
+    expect(loadedBob.isAgent).toBe(true);
+
+    db.close();
+  });
 });
 
 describe("Serializer & serializeObjectiveWorldState Unit Tests (Tier 1)", () => {
   test("serializeAttributes utility", () => {
     const obj = new MockAttributable("obj-1");
     obj.addAttribute("health", "100", AttributeVisibility.PUBLIC);
-    obj.addAttribute("secret", "key-123", AttributeVisibility.PRIVATE, new Set(["alice"]));
+    obj.addAttribute(
+      "secret",
+      "key-123",
+      AttributeVisibility.PRIVATE,
+      new Set(["alice"]),
+    );
 
     const result = serializeAttributes(Array.from(obj.attributes.values()));
     expect(result).toContain("* health: 100 (Visibility: PUBLIC)");
-    expect(result).toContain("* secret: key-123 (Visibility: PRIVATE) (Visible to: alice)");
+    expect(result).toContain(
+      "* secret: key-123 (Visibility: PRIVATE) (Visible to: alice)",
+    );
   });
 
   test("serializeObjectiveWorldState utility", () => {

packages/intent/tests/intent.test.ts

@@ -25,7 +25,11 @@ describe("IntentDecoder Unit Tests (Tier 1)", () => {
     const llm = new MockLLMProvider([mockResponse]);
     const decoder = new IntentDecoder(llm);
 
-    const result = await decoder.decode(world, "alice", "Alice opened the chest.");
+    const result = await decoder.decode(
+      world,
+      "alice",
+      "Alice opened the chest.",
+    );
 
     expect(result.intents).toHaveLength(1);
     expect(result.intents[0].type).toBe("action");

packages/intent/tsconfig.json

@@ -5,8 +5,5 @@
     "outDir": "dist"
   },
   "include": ["src"],
-  "references": [
-    { "path": "../core" },
-    { "path": "../llm" }
-  ]
+  "references": [{ "path": "../core" }, { "path": "../llm" }]
 }

packages/llm/README.md

@@ -0,0 +1,532 @@
+# @omnia/llm
+
+LLM abstraction layer providing pluggable, database-backed provider instances for generative and embedding tasks.
+
+## Architecture Overview
+
+The system is built around four layers:
+
+1. **Registry** — each provider class self-registers its metadata (id, envVar, capabilities, default model, etc.) via `static {}` blocks; `PROVIDER_REGISTRY` is derived from these registrations at runtime — there is no hand-maintained provider list
+2. **Provider Manager** — SQLite-backed CRUD for persisted provider instances, with env-var bootstrap driven by the registry
+3. **Provider Factory** — `buildLLMProvider(inst)` / `buildEmbeddingProvider(inst)` resolve a stored instance to a live provider class via the registry
+4. **Interfaces** — contracts that all providers implement
+
+```mermaid
+graph TD
+    subgraph Self-Registering Providers
+        GP["GeminiProvider"]
+        ORP["OpenRouterProvider"]
+        MP["MockLLMProvider"]
+        GEP["GeminiEmbeddingProvider"]
+        MEP["MockEmbeddingProvider"]
+    end
+
+    subgraph Registry
+        PR["ProviderRegistry\n(derived, not authored)"]
+    end
+
+    subgraph Storage
+        PM["ProviderManager\n(db.ts + bootstrap.ts + row-mapper.ts)"]
+        DB[("settings.db")]
+    end
+
+    subgraph Factory
+        PF["buildLLMProvider()\nbuildEmbeddingProvider()"]
+    end
+
+    GP -->|static block| PR
+    ORP -->|static block| PR
+    MP -->|static block| PR
+    GEP -->|static block| PR
+    MEP -->|static block| PR
+
+    PM -->|reads/writes| DB
+    PM -->|bootstrap from| PR
+
+    PF -->|looks up| PR
+    PF -->|instantiates| GP
+    PF -->|instantiates| ORP
+```
+
+## Core Interfaces
+
+Defined in [`llm.ts`](src/llm.ts):
+
+### `ILLMProvider`
+
+The primary contract for generative (text-to-structured-data) providers.
+
+| Member                                   | Type                      | Description                                                |
+| ---------------------------------------- | ------------------------- | ---------------------------------------------------------- |
+| `providerName`                           | `string`                  | Human-readable provider label                              |
+| `maxContext`                             | `number?`                 | Maximum context window in tokens                           |
+| `generateStructuredResponse<T>(request)` | `Promise<LLMResponse<T>>` | Sends a prompt + Zod schema → returns parsed, typed output |
+| `lastCalls`                              | `LLMCallRecord[]?`        | Audit trail of recent calls (prompts + usage)              |
+
+### `IEmbeddingProvider`
+
+Contract for text-to-vector embedding providers.
+
+| Member         | Type                | Description                                        |
+| -------------- | ------------------- | -------------------------------------------------- |
+| `providerName` | `string`            | Human-readable provider label                      |
+| `embed(text)`  | `Promise<number[]>` | Returns a dense vector embedding of the input text |
+
+### `LLMRequest<T>`
+
+Input to `generateStructuredResponse`:
+
+```typescript
+{
+  systemPrompt: string;    // System-level instructions
+  userContext:   string;    // User/task-specific context
+  schema:        T;         // Zod schema — output is validated against this
+  temperature?:  number;    // Sampling temperature (optional)
+}
+```
+
+### `LLMResponse<T>`
+
+Output from `generateStructuredResponse`:
+
+```typescript
+{
+  success: boolean;
+  data?:   T;               // Parsed, schema-validated output
+  error?:  string;          // Error message on failure
+  usage?:  {
+    inputTokens:          number;
+    outputTokens:         number;
+    totalTokens:          number;
+    modelName?:           string;
+    providerInstanceName?: string;
+    maxContext?:           number;
+  };
+}
+```
+
+### `ModelProviderInstance`
+
+The persisted configuration record for a single provider instance:
+
+```typescript
+{
+  id:           string;                     // Unique ID ("provider-<timestamp>")
+  name:         string;                     // User-facing name ("Gemini (Env)")
+  providerName: string;                     // Provider type key ("google-genai" | "openrouter" | "mock")
+  apiKey:       string;                     // API key
+  isActive:     boolean;                    // Whether this is the active instance for its type
+  modelName?:   string;                     // Specific model to use
+  type:         "generative" | "embedding"; // Instance category
+  maxContext?:  number;                     // Context window limit
+}
+```
+
+### `ModelProviderMeta`
+
+Static metadata for each available provider type (used by the UI's provider picker):
+
+| Member                  | Type     | Description                                                  |
+| ----------------------- | -------- | ------------------------------------------------------------ |
+| `id`                    | `string` | `"google-genai"` \| `"openrouter"` \| `"ollama"` \| `"mock"` |
+| `displayName`           | `string` | Human-readable name                                          |
+| `description`           | `string` | Human-readable description                                   |
+| `defaultModel`          | `string` | Default generative model                                     |
+| `defaultEmbeddingModel` | `string` | Default embedding model                                      |
+
+Provider metadata is **self-declared** by each provider class in a `static {}` block and collected into `PROVIDER_REGISTRY` (derived, not authored). The `getAvailableProviders()` function and `AVAILABLE_PROVIDERS` helper in [`llm.ts`](src/llm.ts) read from the registry at call time.
+
+## Provider Manager
+
+`ProviderManager` is a **static class** that provides full CRUD over provider instances, backed by a SQLite database (`data/settings.db` at the workspace root). Internally split across:
+
+- [`db.ts`](src/db.ts) — memoized DB handle + schema migrations (`PRAGMA user_version`)
+- [`bin/setup-provider.ts`](src/bin/setup-provider.ts) — CLI tool to set up provider instances in the database
+- [`row-mapper.ts`](src/row-mapper.ts) — `mapRow()` (written once, used everywhere)
+- [`provider-manager.ts`](src/provider-manager.ts) — thin CRUD: `list`, `create`, `delete`, `setActive`, `update`, `getActive`, `getMappings`, `setMapping`
+
+### Storage
+
+The database is auto-created on first access. The table schema:
+
+```sql
+CREATE TABLE IF NOT EXISTS provider_instances (
+  id           TEXT PRIMARY KEY,
+  name         TEXT NOT NULL,
+  providerName TEXT NOT NULL,
+  apiKey       TEXT NOT NULL,
+  isActive     INTEGER NOT NULL DEFAULT 0,
+  modelName    TEXT,
+  type         TEXT NOT NULL DEFAULT 'generative',
+  maxContext   INTEGER
+);
+```
+
+A second table stores per-task provider overrides:
+
+```sql
+CREATE TABLE IF NOT EXISTS provider_mappings (
+  task                TEXT PRIMARY KEY,
+  providerInstanceId  TEXT NOT NULL
+);
+```
+
+### API
+
+| Method                                                                    | Signature                         | Description                                                                               |
+| ------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------- |
+| `list()`                                                                  | `→ ModelProviderInstance[]`       | Returns all saved instances                                                               |
+| `create(name, providerName, apiKey, modelName?, type?, maxContext?)`      | `→ ModelProviderInstance`         | Creates a new instance. Auto-activates if it's the first of its type                      |
+| `delete(id)`                                                              | `→ void`                          | Removes an instance. If it was active, auto-promotes the next instance of the same type   |
+| `setActive(id)`                                                           | `→ void`                          | Deactivates all instances of the same type, then activates the target                     |
+| `update(id, name, providerName, apiKey?, modelName?, type?, maxContext?)` | `→ void`                          | Updates an existing instance. If `apiKey` is empty/omitted, the existing key is preserved |
+| `getActive(type?)`                                                        | `→ ModelProviderInstance \| null` | Returns the currently active instance for the given type (`"generative"` by default)      |
+| `getMappings()`                                                           | `→ Record<string, string>`        | Returns all task → providerInstanceId mappings                                            |
+| `setMapping(task, providerInstanceId)`                                    | `→ void`                          | Sets or removes (if `providerInstanceId` is empty) a task-specific mapping                |
+
+### Active Instance Invariants
+
+- **Only one active instance per type** — `setActive()` deactivates all sibling instances before activating the target.
+- **Auto-promotion on delete** — if the deleted instance was active, the first remaining instance of the same type is promoted.
+- **Auto-activation on create** — if no active instance exists for the type, the new instance is automatically activated.
+
+### Manual Seeding via CLI
+
+Rather than automatically bootstrapping from environment variables at runtime, which adds runtime complexity, you can quickly seed the database using the CLI setup tool:
+
+#### Seeding All Environment-Variable Providers
+
+```bash
+pnpm setup-provider --all
+```
+
+This command auto-detects and inserts provider instances into `data/settings.db` for any registered providers whose corresponding environment variables (such as `GOOGLE_API_KEY`, `OPENAI_API_KEY`, etc.) are defined.
+
+#### Creating a Specific Provider Instance
+
+```bash
+pnpm setup-provider --provider google-genai --key YOUR_API_KEY [--name "My Gemini"] [--model gemini-2.5-flash] [--type generative] [--max-context 32768] [--endpoint url]
+```
+
+### Credential Resolution Cascade
+
+When initializing a provider (e.g. `new GeminiProvider()`):
+
+1. **Explicit Credentials** — If `apiKey`, `modelName`, etc. are passed directly to the constructor, they are used.
+2. **Active DB Instance** — If not explicitly passed, it looks up the active DB instance via `ProviderManager.getActive()`. If found and matches the provider, its API key and configuration are used.
+3. **Environment Fallback** — If there is no matching active DB instance, it resolves the key directly from the corresponding environment variable (e.g., `GOOGLE_API_KEY`) via `resolveCredentials`.
+
+## Available Providers
+
+### Google Gemini — `GeminiProvider`
+
+| Property                    | Value                                                        |
+| --------------------------- | ------------------------------------------------------------ |
+| **File**                    | [`providers/google-genai.ts`](src/providers/google-genai.ts) |
+| **Provider ID**             | `google-genai`                                               |
+| **SDK**                     | `@langchain/google-genai` (`ChatGoogleGenerativeAI`)         |
+| **Default Model**           | `gemini-2.5-flash`                                           |
+| **Default Embedding Model** | `gemini-embedding-001`                                       |
+| **Default Max Context**     | `32768`                                                      |
+| **Type**                    | Generative                                                   |
+
+**Key resolution** in the constructor follows this cascade:
+
+```
+1. Explicit apiKey argument       → use it
+2. ProviderManager.getActive()    → if providerName matches "google-genai"
+3. GOOGLE_API_KEY env var         → final fallback
+4. None found                     → throw Error
+```
+
+Also exports `GeminiEmbeddingProvider` (implements `IEmbeddingProvider`) using the same key resolution pattern but querying for the `"embedding"` type.
+
+### Anthropic Claude — `AnthropicProvider`
+
+| Property                    | Value                                                  |
+| --------------------------- | ------------------------------------------------------ |
+| **File**                    | [`providers/anthropic.ts`](src/providers/anthropic.ts) |
+| **Provider ID**             | `anthropic`                                            |
+| **SDK**                     | `@langchain/anthropic` (`ChatAnthropic`)               |
+| **Default Model**           | `claude-3-5-sonnet-latest`                             |
+| **Default Embedding Model** | _(none)_                                               |
+| **Default Max Context**     | `200000`                                               |
+| **Type**                    | Generative only (no embedding provider)                |
+
+**Key resolution** in the constructor follows this cascade:
+
+```
+1. Explicit apiKey argument       → use it
+2. ProviderManager.getActive()    → if providerName matches "anthropic"
+3. ANTHROPIC_API_KEY env var      → final fallback
+4. None found                     → throw Error
+```
+
+### Groq — `GroqProvider`
+
+| Property                    | Value                                        |
+| --------------------------- | -------------------------------------------- |
+| **File**                    | [`providers/groq.ts`](src/providers/groq.ts) |
+| **Provider ID**             | `groq`                                       |
+| **SDK**                     | `@langchain/groq` (`ChatGroq`)               |
+| **Default Model**           | `llama-3.3-70b-versatile`                    |
+| **Default Embedding Model** | _(none)_                                     |
+| **Default Max Context**     | `8192`                                       |
+| **Type**                    | Generative only (no embedding provider)      |
+
+**Key resolution** in the constructor follows this cascade:
+
+```
+1. Explicit apiKey argument       → use it
+2. ProviderManager.getActive()    → if providerName matches "groq"
+3. GROQ_API_KEY env var           → final fallback
+4. None found                     → throw Error
+```
+
+### DeepSeek — `DeepSeekProvider`
+
+| Property                    | Value                                                |
+| --------------------------- | ---------------------------------------------------- |
+| **File**                    | [`providers/deepseek.ts`](src/providers/deepseek.ts) |
+| **Provider ID**             | `deepseek`                                           |
+| **SDK**                     | `@langchain/deepseek` (`ChatDeepSeek`)               |
+| **Default Model**           | `deepseek-chat`                                      |
+| **Default Embedding Model** | _(none)_                                             |
+| **Default Max Context**     | `64000`                                              |
+| **Type**                    | Generative only (no embedding provider)              |
+
+**Key resolution** in the constructor follows this cascade:
+
+```
+1. Explicit apiKey argument       → use it
+2. ProviderManager.getActive()    → if providerName matches "deepseek"
+3. DEEPSEEK_API_KEY env var       → final fallback
+4. None found                     → throw Error
+```
+
+### OpenAI — `OpenAIProvider`
+
+| Property                    | Value                                                  |
+| --------------------------- | ------------------------------------------------------ |
+| **File**                    | [`providers/openai.ts`](src/providers/openai.ts)       |
+| **Provider ID**             | `openai`                                               |
+| **SDK**                     | `@langchain/openai` (`ChatOpenAI`, `OpenAIEmbeddings`) |
+| **Default Model**           | `gpt-4o-mini`                                          |
+| **Default Embedding Model** | `text-embedding-3-small`                               |
+| **Default Max Context**     | `128000`                                               |
+| **Type**                    | Generative + Embedding                                 |
+
+**Key resolution** in the constructor follows this cascade:
+
+```
+1. Explicit apiKey argument       → use it
+2. ProviderManager.getActive()    → if providerName matches "openai"
+3. OPENAI_API_KEY env var         → final fallback
+4. None found                     → throw Error
+```
+
+Also exports `OpenAIEmbeddingProvider` (implements `IEmbeddingProvider`) using the same key resolution pattern against the `"embedding"` type instance. The default embedding model is `text-embedding-3-small`.
+
+### OpenRouter — `OpenRouterProvider`
+
+| Property                    | Value                                                    |
+| --------------------------- | -------------------------------------------------------- |
+| **File**                    | [`providers/openrouter.ts`](src/providers/openrouter.ts) |
+| **Provider ID**             | `openrouter`                                             |
+| **SDK**                     | `@langchain/openrouter` (`ChatOpenRouter`)               |
+| **Default Model**           | `google/gemini-2.5-flash`                                |
+| **Default Embedding Model** | `openai/text-embedding-3-small`                          |
+| **Default Max Context**     | `32768`                                                  |
+| **Type**                    | Generative only (no embedding provider)                  |
+
+Same three-step key resolution as Gemini (`explicit → ProviderManager → env var`), using `OPENROUTER_API_KEY`.
+
+### Ollama — `OllamaProvider`
+
+| Property                    | Value                                            |
+| --------------------------- | ------------------------------------------------ |
+| **File**                    | [`providers/ollama.ts`](src/providers/ollama.ts) |
+| **Provider ID**             | `ollama`                                         |
+| **SDK**                     | `@langchain/ollama` (`ChatOllama`)               |
+| **Default Model**           | `llama3.1`                                       |
+| **Default Embedding Model** | `nomic-embed-text`                               |
+| **Default Max Context**     | `32768`                                          |
+| **Type**                    | Generative + Embedding                           |
+
+Ollama runs **locally** — no API key is required. The `endpointUrl` field in `ModelProviderInstance` stores the Ollama server base URL (default: `http://localhost:11434`).
+
+**Key resolution** in the constructor:
+
+```
+1. Explicit baseUrl argument        → use it
+2. ProviderManager.getActive()      → if providerName matches "ollama"
+                                      (endpointUrl field = base URL)
+3. Default                          → http://localhost:11434
+```
+
+Also exports `OllamaEmbeddingProvider` (implements `IEmbeddingProvider`), which uses the same resolution pattern against the `"embedding"` type instance. The default embedding model is `nomic-embed-text`.
+
+> [!TIP]
+> To get started: `ollama pull llama3.1` and `ollama pull nomic-embed-text`. Then create a provider instance with `endpointUrl` = `http://localhost:11434`.
+
+### Mock — `MockLLMProvider`
+
+| Property        | Value                                        |
+| --------------- | -------------------------------------------- |
+| **File**        | [`providers/mock.ts`](src/providers/mock.ts) |
+| **Provider ID** | `mock`                                       |
+| **Type**        | Generative + Embedding                       |
+
+Stateless mock for testing and offline development:
+
+- **Generative** (`MockLLMProvider`): Takes an array of canned responses at construction. Returns them in order, one per call. Returns `{ success: false, error: "Mock responses exhausted" }` when depleted.
+- **Embedding** (`MockEmbeddingProvider`): Returns a deterministic 768-dimensional vector derived from the input text using `Math.sin`.
+
+## Provider Resolution (Runtime)
+
+The [`resolveProviders()`](../../../apps/gui/src/lib/simulation/provider-resolver.ts) function (in `apps/gui`) instantiates all providers needed for a simulation session. It resolves **six** provider slots:
+
+| Slot                | Type       | Task Key           |
+| ------------------- | ---------- | ------------------ |
+| `actorProvider`     | Generative | `"actor-prose"`    |
+| `validatorProvider` | Generative | `"llm-validator"`  |
+| `decoderProvider`   | Generative | `"intent-decoder"` |
+| `timedeltaProvider` | Generative | `"timedelta"`      |
+| `handoffProvider`   | Generative | `"handoff"`        |
+| `embeddingProvider` | Embedding  | `"embeddings"`     |
+
+### Generative Resolution Order
+
+For each generative slot (`resolveGenerative(task)`):
+
+```
+1. Task-specific mapping     → mappings[task] → find instance by ID
+2. Active generative instance → ProviderManager.getActive("generative")
+3. Fallback instance         → options.fallbackInstance (if provided)
+4. GOOGLE_API_KEY env var    → auto-create via ProviderManager.create()
+5. No provider available     → throw Error (if required) or MockLLMProvider
+```
+
+### Embedding Resolution Order
+
+For the embedding slot (`resolveEmbedding()`):
+
+```
+1. Task-specific mapping     → mappings["embeddings"] → find instance by ID
+2. Active embedding instance → ProviderManager.getActive("embedding")
+3. GOOGLE_API_KEY env var    → auto-create via ProviderManager.create()
+4. No provider available     → throw Error (if required) or MockEmbeddingProvider
+```
+
+### Instance → Class Mapping
+
+The `buildLLMProvider()` and `buildEmbeddingProvider()` functions perform the final dispatch:
+
+| `providerName`    | Generative Class     | Embedding Class           |
+| ----------------- | -------------------- | ------------------------- |
+| `"google-genai"`  | `GeminiProvider`     | `GeminiEmbeddingProvider` |
+| `"openai"`        | `OpenAIProvider`     | `OpenAIEmbeddingProvider` |
+| `"openrouter"`    | `OpenRouterProvider` | _(falls through to mock)_ |
+| `"ollama"`        | `OllamaProvider`     | `OllamaEmbeddingProvider` |
+| `"anthropic"`     | `AnthropicProvider`  | _(falls through to mock)_ |
+| `"groq"`          | `GroqProvider`       | _(falls through to mock)_ |
+| `"deepseek"`      | `DeepSeekProvider`   | _(falls through to mock)_ |
+| _(anything else)_ | `MockLLMProvider`    | `MockEmbeddingProvider`   |
+
+## Model Listing and Discovery
+
+The `ModelLister` class provides a unified interface to dynamically query available models from the remote provider APIs.
+
+### Caching and TTL
+
+All list requests are cached in-memory with a **5-minute TTL** (`300,000ms`) to prevent rapid, repetitive remote API requests and avoid rate limit exhaustion.
+
+- **Cache Key**: Generated using `providerName` combined with either the `apiKey` or `endpointUrl`.
+- **Invalidation**: Call `ModelLister.invalidateCache(providerName, apiKey, endpointUrl)` to clear cache for specific instances, or `ModelLister.clearCache()` to wipe all lists.
+
+### Provider Integration Details
+
+| Provider          | Endpoint                     | Auth Header             | Pagination                  |
+| ----------------- | ---------------------------- | ----------------------- | --------------------------- |
+| **Google Gemini** | `GET /v1beta/models?key=KEY` | Query Param             | ✅ Loop via `nextPageToken` |
+| **OpenAI**        | `GET /v1/models`             | `Authorization: Bearer` | ❌                          |
+| **Anthropic**     | `GET /v1/models`             | `x-api-key`             | ✅ Loop via `after_id`      |
+| **Groq**          | `GET /openai/v1/models`      | `Authorization: Bearer` | ❌                          |
+| **DeepSeek**      | `GET /models`                | `Authorization: Bearer` | ❌                          |
+| **Ollama**        | `GET /api/tags`              | None (Local)            | ❌                          |
+| **OpenRouter**    | `GET /api/v1/models`         | Optional Bearer         | ❌                          |
+| **Mock**          | Instant return (no fetch)    | —                       | —                           |
+
+### Methods
+
+- `listModels(providerName: string, apiKey: string, endpointUrl?: string): Promise<ModelInfo[]>`
+- `invalidateCache(providerName: string, apiKey: string, endpointUrl?: string): void`
+- `clearCache(): void`
+
+---
+
+## Structured Output
+
+All real providers use LangChain's `.withStructuredOutput(schema, { includeRaw: true })` pattern:
+
+```typescript
+const structuredModel = this.model.withStructuredOutput(request.schema, {
+  includeRaw: true,
+});
+const result = await structuredModel.invoke([
+  { role: "system", content: request.systemPrompt },
+  { role: "user", content: request.userContext },
+]);
+```
+
+This sends the Zod schema to the model as a structured output constraint. The response includes both `parsed` (schema-validated data) and `raw` (full API response with usage metadata).
+
+## Configuration
+
+[`config.ts`](src/config.ts) parses environment variables using Zod:
+
+| Variable             | Required | Description              |
+| -------------------- | -------- | ------------------------ |
+| `GOOGLE_API_KEY`     | No       | Google Gemini API key    |
+| `OPENAI_API_KEY`     | No       | OpenAI API key           |
+| `OPENROUTER_API_KEY` | No       | OpenRouter API key       |
+| `ANTHROPIC_API_KEY`  | No       | Anthropic Claude API key |
+| `GROQ_API_KEY`       | No       | Groq API key             |
+| `DEEPSEEK_API_KEY`   | No       | DeepSeek API key         |
+
+Env var keys are derived from `PROVIDER_REGISTRY` — each provider's `envVar` field is read by `getLlmConfig()` to build the zod schema lazily. Adding a new provider with `envVar: "NEW_KEY"` automatically adds it to config validation.
+
+## File Map
+
+```
+packages/llm/
+├── src/
+│   ├── index.ts              # Re-exports everything
+│   ├── llm.ts                # Interfaces, types, getAvailableProviders()
+│   ├── registry.ts           # ProviderRegistry (derived), registerProvider/registerGenerative/registerEmbedding
+│   ├── base-provider.ts      # BaseLLMProvider (shared generateStructuredResponse), resolveCredentials
+│   ├── config.ts             # Env var parsing (lazy, registry-derived Zod)
+│   ├── model-lister.ts       # ModelLister (cache + fetchWithTimeout), fetchOpenAICompatibleModels
+│   ├── provider-factory.ts   # buildLLMProvider() / buildEmbeddingProvider() (registry lookup)
+│   ├── provider-manager.ts   # ProviderManager (thin CRUD)
+│   ├── db.ts                 # Memoized DB handle + migrations
+│   ├── row-mapper.ts         # mapRow()
+│   ├── bin/
+│   │   └── setup-provider.ts # CLI tool to set up provider instances in the database
+│   └── providers/
+│       ├── google-genai.ts   # GeminiProvider + GeminiEmbeddingProvider (self-registering)
+│       ├── ollama.ts         # OllamaProvider + OllamaEmbeddingProvider
+│       ├── openrouter.ts     # OpenRouterProvider
+│       ├── anthropic.ts      # AnthropicProvider
+│       ├── openai.ts         # OpenAIProvider + OpenAIEmbeddingProvider
+│       ├── groq.ts           # GroqProvider
+│       ├── deepseek.ts       # DeepSeekProvider
+│       └── mock.ts           # MockLLMProvider + MockEmbeddingProvider
+├── tests/
+│   ├── mock.test.ts
+│   ├── openrouter.test.ts
+│   ├── model-lister.test.ts  # ModelLister cache and fetch logic unit tests
+│   ├── provider-manager.test.ts
+│   └── cli.test.ts           # Integration tests for setup-provider CLI tool
+└── package.json
+```

packages/llm/chat-openai.md

@@ -0,0 +1,225 @@
+> ## Documentation Index
+>
+> Fetch the complete documentation index at: https://docs.langchain.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# OpenAI integrations
+
+> Integrate with OpenAI using LangChain JavaScript.
+
+LangChain integrates with OpenAI and Azure OpenAI through the `@langchain/openai` package.
+
+> [OpenAI](https://en.wikipedia.org/wiki/OpenAI) is American artificial intelligence (AI) research laboratory
+> consisting of the non-profit `OpenAI Incorporated`
+> and its for-profit subsidiary corporation `OpenAI Limited Partnership`.
+> OpenAI conducts AI research with the declared intention of promoting and developing a friendly AI.
+> OpenAI systems run on an `Azure`-based supercomputing platform from `Microsoft`.
+
+> The [OpenAI API](https://platform.openai.com/docs/models) is powered by a diverse set of models with different capabilities and price points.
+>
+> [ChatGPT](https://chat.openai.com) is the Artificial Intelligence (AI) chatbot developed by `OpenAI`.
+
+## Installation and setup
+
+- Get an OpenAI api key and set it as an environment variable (`OPENAI_API_KEY`)
+
+## Chat model
+
+See a [usage example](/oss/javascript/integrations/chat/openai).
+
+```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
+import { ChatOpenAI } from "@langchain/openai";
+```
+
+## LLM
+
+See a [usage example](/oss/javascript/integrations/llms/openai).
+
+<Tip>
+  See [this section for general instructions on installing LangChain packages](/oss/javascript/langchain/install).
+</Tip>
+
+```bash npm theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
+npm install @langchain/openai @langchain/core
+```
+
+```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
+import { OpenAI } from "@langchain/openai";
+```
+
+## Text embedding model
+
+See a [usage example](/oss/javascript/integrations/embeddings/openai)
+
+```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
+import { OpenAIEmbeddings } from "@langchain/openai";
+```
+
+## Chain
+
+```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
+import { OpenAIModerationChain } from "@langchain/classic/chains";
+```
+
+## Middleware
+
+Middleware specifically designed for OpenAI models. Learn more about [middleware](/oss/javascript/langchain/middleware/overview).
+
+| Middleware                                | Description                                               |
+| ----------------------------------------- | --------------------------------------------------------- |
+| [Content moderation](#content-moderation) | Moderate agent traffic using OpenAI's moderation endpoint |
+
+### Content moderation
+
+Moderate agent traffic (user input, model output, and tool results) using OpenAI's moderation endpoint to detect and handle unsafe content. Content moderation is useful for the following:
+
+- Applications requiring content safety and compliance
+- Filtering harmful, hateful, or inappropriate content
+- Customer-facing agents that need safety guardrails
+- Meeting platform moderation requirements
+
+<Info>
+  Learn more about [OpenAI's moderation models](https://platform.openai.com/docs/guides/moderation) and categories.
+</Info>
+
+**API reference:** [`openAIModerationMiddleware`](https://reference.langchain.com/javascript/langchain/index/openAIModerationMiddleware)
+
+```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
+import { createAgent, openAIModerationMiddleware } from "langchain";
+
+const agent = createAgent({
+  model: "openai:gpt-5.5",
+  tools: [searchTool, databaseTool],
+  middleware: [
+    openAIModerationMiddleware({
+      model: "openai:gpt-5.5",
+      moderationModel: "omni-moderation-latest",
+      checkInput: true,
+      checkOutput: true,
+      exitBehavior: "end",
+    }),
+  ],
+});
+```
+
+<Accordion title="Configuration options">
+  <ParamField body="model" type="string | BaseChatModel" required>
+    OpenAI model to use for moderation. Can be either a model name string (e.g., `"openai:gpt-5.5"`) or a `BaseChatModel` instance. The middleware will use this model's client to access the moderation endpoint.
+  </ParamField>
+
+  <ParamField body="moderationModel" type="ModerationModel" default="omni-moderation-latest">
+    OpenAI moderation model to use. Options: `'omni-moderation-latest'`, `'omni-moderation-2024-09-26'`, `'text-moderation-latest'`, `'text-moderation-stable'`
+  </ParamField>
+
+  <ParamField body="checkInput" type="boolean" default="true">
+    Whether to check user input messages before the model is called
+  </ParamField>
+
+  <ParamField body="checkOutput" type="boolean" default="true">
+    Whether to check model output messages after the model is called
+  </ParamField>
+
+  <ParamField body="checkToolResults" type="boolean" default="false">
+    Whether to check tool result messages before the model is called
+  </ParamField>
+
+  <ParamField body="exitBehavior" type="'error' | 'end' | 'replace'" default="'end'">
+    How to handle violations when content is flagged. Options:
+
+    * `'end'` - End agent execution immediately with a violation message
+    * `'error'` - Throw `OpenAIModerationError` exception
+    * `'replace'` - Replace the flagged content with the violation message and continue
+
+  </ParamField>
+
+  <ParamField body="violationMessage" type="string | undefined">
+    Custom template for violation messages. Supports template variables:
+
+    * `{categories}` - Comma-separated list of flagged categories
+    * `{category_scores}` - JSON string of category scores
+    * `{original_content}` - The original flagged content
+
+    Default: `"I'm sorry, but I can't comply with that request. It was flagged for {categories}."`
+
+  </ParamField>
+</Accordion>
+
+<Accordion title="Full example">
+  The middleware integrates OpenAI's moderation endpoint to check content at different stages:
+
+**Moderation stages:**
+
+- `checkInput` - User messages before model call
+- `checkOutput` - AI messages after model call
+- `checkToolResults` - Tool outputs before model call
+
+**Exit behaviors:**
+
+- `'end'` (default) - Stop execution with violation message
+- `'error'` - Throw exception for application handling
+- `'replace'` - Replace flagged content and continue
+
+```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
+import { createAgent, openAIModerationMiddleware } from "langchain";
+
+// Basic moderation
+const agent = createAgent({
+  model: "openai:gpt-5.5",
+  tools: [searchTool, customerDataTool],
+  middleware: [
+    openAIModerationMiddleware({
+      model: "openai:gpt-5.5",
+      moderationModel: "omni-moderation-latest",
+      checkInput: true,
+      checkOutput: true,
+    }),
+  ],
+});
+
+// Strict moderation with custom message
+const agentStrict = createAgent({
+  model: "openai:gpt-5.5",
+  tools: [searchTool, customerDataTool],
+  middleware: [
+    openAIModerationMiddleware({
+      model: "openai:gpt-5.5",
+      moderationModel: "omni-moderation-latest",
+      checkInput: true,
+      checkOutput: true,
+      checkToolResults: true,
+      exitBehavior: "error",
+      violationMessage:
+        "Content policy violation detected: {categories}. " +
+        "Please rephrase your request.",
+    }),
+  ],
+});
+
+// Moderation with replacement behavior
+const agentReplace = createAgent({
+  model: "openai:gpt-5.5",
+  tools: [searchTool],
+  middleware: [
+    openAIModerationMiddleware({
+      model: "openai:gpt-5.5",
+      checkInput: true,
+      exitBehavior: "replace",
+      violationMessage: "[Content removed due to safety policies]",
+    }),
+  ],
+});
+```
+
+</Accordion>
+
+---
+
+<div className="source-links">
+  <Callout icon="terminal-2">
+    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
+  </Callout>
+
+  <Callout icon="edit">
+    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/javascript/integrations/providers/openai.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
+  </Callout>
+</div>

packages/llm/package.json

@@ -6,6 +6,9 @@
   "exports": {
     ".": "./dist/index.js"
   },
+  "scripts": {
+    "setup-provider": "node ./dist/bin/setup-provider.js"
+  },
   "dependencies": {
     "@types/node": "^26.1.0",
     "better-sqlite3": "^12.11.1"

packages/llm/src/base-provider.ts

@@ -0,0 +1,112 @@
+import { z } from "zod";
+import type {
+  ILLMProvider,
+  LLMRequest,
+  LLMResponse,
+  LLMCallRecord,
+} from "./llm.js";
+import { ProviderManager } from "./provider-manager.js";
+import { getLlmConfig } from "./config.js";
+
+export interface ResolvedCredentials {
+  key: string | undefined;
+  model: string | undefined;
+  providerInstanceName: string | undefined;
+  maxContext: number | undefined;
+}
+
+export function resolveCredentials(opts: {
+  explicitKey?: string;
+  explicitModel?: string;
+  explicitProviderInstanceName?: string;
+  explicitMaxContext?: number;
+  providerId: string;
+  envVarName: string;
+  type: "generative" | "embedding";
+}): ResolvedCredentials {
+  let key = opts.explicitKey;
+  let model = opts.explicitModel;
+  let providerInstanceName = opts.explicitProviderInstanceName;
+  let maxContext = opts.explicitMaxContext;
+
+  if (!key) {
+    const active = ProviderManager.getActive(opts.type);
+    if (active && active.providerName === opts.providerId) {
+      key = active.apiKey;
+      if (!model) model = active.modelName;
+      if (!providerInstanceName) providerInstanceName = active.name;
+      if (maxContext === undefined) maxContext = active.maxContext;
+    }
+  }
+
+  if (!key) {
+    const cfg = getLlmConfig();
+    key = cfg[opts.envVarName];
+    if (!providerInstanceName && key) {
+      providerInstanceName = "Environment Variable";
+    }
+  }
+
+  return { key, model, providerInstanceName, maxContext };
+}
+
+export abstract class BaseLLMProvider implements ILLMProvider {
+  abstract providerName: string;
+  protected abstract readonly model: unknown;
+  protected abstract modelNameUsed: string;
+  protected abstract providerInstanceName?: string;
+  protected abstract maxContextUsed?: number;
+  protected abstract defaultMaxContext: number;
+  lastCalls: LLMCallRecord[] = [];
+
+  async generateStructuredResponse<T extends z.ZodTypeAny>(
+    request: LLMRequest<T>,
+  ): Promise<LLMResponse<z.infer<T>>> {
+    const structuredModel = (
+      this.model as {
+        withStructuredOutput(
+          s: z.ZodTypeAny,
+          o: { includeRaw: true },
+        ): {
+          invoke(m: unknown): Promise<unknown>;
+        };
+      }
+    ).withStructuredOutput(request.schema, { includeRaw: true });
+    const result = (await structuredModel.invoke([
+      { role: "system", content: request.systemPrompt },
+      { role: "user", content: request.userContext },
+    ])) as unknown as {
+      parsed?: z.infer<T>;
+      raw?: {
+        usage_metadata?: {
+          input_tokens?: number;
+          output_tokens?: number;
+          total_tokens?: number;
+        };
+      };
+    };
+
+    const parsed = result?.parsed;
+    const raw = result?.raw;
+
+    const usage = {
+      inputTokens: raw?.usage_metadata?.input_tokens || 0,
+      outputTokens: raw?.usage_metadata?.output_tokens || 0,
+      totalTokens: raw?.usage_metadata?.total_tokens || 0,
+      modelName: this.modelNameUsed,
+      providerInstanceName: this.providerInstanceName || "Default",
+      maxContext:
+        this.maxContextUsed !== undefined
+          ? this.maxContextUsed
+          : this.defaultMaxContext,
+    };
+
+    this.lastCalls.push({
+      systemPrompt: request.systemPrompt,
+      userContext: request.userContext,
+      usage,
+    });
+
+    return { success: true, data: parsed, usage };
+  }
+}

packages/llm/src/bin/setup-provider.ts

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+import { ProviderRegistry, ProviderManager } from "../index.js";
+import dotenv from "dotenv";
+import path from "path";
+import fs from "fs";
+
+// Load dotenv from workspace root
+function loadEnv() {
+  let current = process.cwd();
+  while (current !== "/" && current !== path.parse(current).root) {
+    if (fs.existsSync(path.join(current, "pnpm-workspace.yaml"))) {
+      dotenv.config({ path: path.join(current, ".env") });
+      return;
+    }
+    current = path.dirname(current);
+  }
+  dotenv.config();
+}
+
+loadEnv();
+
+function printHelp() {
+  console.log(`
+Usage:
+  node packages/llm/dist/bin/setup-provider.js [options]
+
+Options:
+  --provider <id>     ID of the provider (e.g. google-genai, openai, anthropic, groq, etc.)
+  --name <name>       Display name for the instance (default: provider displayName)
+  --key <key>         API key (default: loaded from the provider's env variable, e.g. GOOGLE_API_KEY)
+  --model <model>     Model name (default: provider's default model)
+  --type <type>       "generative" | "embedding" (default: "generative")
+  --max-context <num> Max context window tokens (default: provider's default max context)
+  --endpoint <url>    Custom endpoint URL (optional)
+  --all               Auto-detect and seed all providers whose environment variables are set
+  -h, --help          Show this help message
+
+Registered Providers:
+${ProviderRegistry.all()
+  .map((p) => `  - ${p.id} (${p.displayName}) [Env: ${p.envVar || "None"}]`)
+  .join("\n")}
+`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("-h") || args.includes("--help") || args.length === 0) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const options: Record<string, string> = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const nextVal = args[i + 1];
+      if (nextVal && !nextVal.startsWith("--")) {
+        options[key] = nextVal;
+        i++;
+      } else {
+        options[key] = "true";
+      }
+    }
+  }
+
+  if (options.all === "true") {
+    // Seed all providers from environment variables
+    const existing = ProviderManager.list();
+    let seededCount = 0;
+
+    for (const def of ProviderRegistry.all()) {
+      if (!def.envVar) continue;
+      const key = process.env[def.envVar]?.trim();
+      if (!key) continue;
+
+      if (def.capabilities.generative) {
+        const hasGen = existing.some(
+          (p) => p.providerName === def.id && p.type === "generative",
+        );
+        if (!hasGen) {
+          const name = `${def.displayName} (CLI)`;
+          ProviderManager.create(
+            name,
+            def.id,
+            key,
+            def.defaultModel,
+            "generative",
+            def.defaultMaxContext,
+          );
+          console.log(`Created generative instance: ${name}`);
+          seededCount++;
+        }
+      }
+
+      if (def.capabilities.embedding) {
+        const hasEmbed = existing.some(
+          (p) => p.providerName === def.id && p.type === "embedding",
+        );
+        if (!hasEmbed) {
+          const name = `${def.displayName} Embed (CLI)`;
+          ProviderManager.create(
+            name,
+            def.id,
+            key,
+            def.defaultEmbeddingModel || "",
+            "embedding",
+            0,
+          );
+          console.log(`Created embedding instance: ${name}`);
+          seededCount++;
+        }
+      }
+    }
+
+    if (seededCount === 0) {
+      console.log(
+        "No new provider instances seeded. (Either already existed or env vars not set)",
+      );
+    } else {
+      console.log(`Successfully seeded ${seededCount} provider instance(s).`);
+    }
+    process.exit(0);
+  }
+
+  const providerId = options.provider;
+  if (!providerId) {
+    console.error("Error: --provider <id> or --all is required.");
+    printHelp();
+    process.exit(1);
+  }
+
+  const def = ProviderRegistry.get(providerId);
+  if (!def) {
+    console.error(`Error: Provider '${providerId}' is not registered.`);
+    console.error(
+      `Available providers: ${ProviderRegistry.all()
+        .map((p) => p.id)
+        .join(", ")}`,
+    );
+    process.exit(1);
+  }
+
+  const type = (options.type === "embedding" ? "embedding" : "generative") as
+    "generative" | "embedding";
+
+  // Resolve key
+  let apiKey: string | undefined = options.key;
+  if (!apiKey && def.envVar) {
+    apiKey = process.env[def.envVar]?.trim();
+  }
+  if (!apiKey) {
+    console.error(
+      `Error: API Key is required. Please set ${def.envVar || "the environment variable"} or pass --key <apiKey>.`,
+    );
+    process.exit(1);
+  }
+
+  // Resolve model
+  const defaultModel =
+    type === "embedding" ? def.defaultEmbeddingModel || "" : def.defaultModel;
+  const modelName = options.model || defaultModel;
+
+  // Resolve name
+  const name = options.name || `${def.displayName} (CLI)`;
+
+  // Resolve maxContext
+  const maxContext = options["max-context"]
+    ? parseInt(options["max-context"], 10)
+    : type === "embedding"
+      ? 0
+      : def.defaultMaxContext;
+
+  const endpointUrl = options.endpoint;
+
+  const instance = ProviderManager.create(
+    name,
+    def.id,
+    apiKey,
+    modelName,
+    type,
+    maxContext,
+    endpointUrl,
+  );
+
+  console.log(`Successfully created provider instance:`);
+  console.log(JSON.stringify(instance, null, 2));
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

packages/llm/src/config.ts

@@ -1,8 +1,25 @@
 import { z } from "zod";
+import { ProviderRegistry } from "./registry.js";
 
-const LLMConfigSchema = z.object({
-  GOOGLE_API_KEY: z.string().optional(),
-  OPENROUTER_API_KEY: z.string().optional(),
-});
+let _config: Record<string, string | undefined> | null = null;
 
-export const llmConfig = LLMConfigSchema.parse(process.env);
+export function getLlmConfig(): Record<string, string | undefined> {
+  if (!_config) {
+    const envVars: string[] = [];
+    for (const def of ProviderRegistry.all()) {
+      if (def.envVar && !envVars.includes(def.envVar)) {
+        envVars.push(def.envVar);
+      }
+    }
+    const shape: Record<string, z.ZodOptional<z.ZodString>> = {};
+    for (const key of envVars) {
+      shape[key] = z.string().optional();
+    }
+    _config = z.object(shape).parse(process.env);
+  }
+  return _config;
+}
+
+export function resetLlmConfig(): void {
+  _config = null;
+}

packages/llm/src/db.ts

@@ -0,0 +1,82 @@
+import Database from "better-sqlite3";
+import type BetterSqlite3 from "better-sqlite3";
+import path from "path";
+import fs from "fs";
+
+let _db: BetterSqlite3.Database | null = null;
+let _dbPathOverride: string | null = null;
+
+export function setDbPath(p: string | null) {
+  if (_dbPathOverride !== p) {
+    _db?.close();
+    _db = null;
+    _dbPathOverride = p;
+  }
+}
+
+function findDbPath(): string {
+  if (process.env.OMNIA_DB_PATH) {
+    const dir = path.dirname(process.env.OMNIA_DB_PATH);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    return process.env.OMNIA_DB_PATH;
+  }
+  let current = process.cwd();
+  while (current !== "/" && current !== path.parse(current).root) {
+    if (fs.existsSync(path.join(current, "pnpm-workspace.yaml"))) {
+      const dbDir = path.resolve(current, "data");
+      if (!fs.existsSync(dbDir)) {
+        fs.mkdirSync(dbDir, { recursive: true });
+      }
+      return path.join(dbDir, "settings.db");
+    }
+    current = path.dirname(current);
+  }
+  const dbDir = path.resolve(process.cwd(), "data");
+  if (!fs.existsSync(dbDir)) {
+    fs.mkdirSync(dbDir, { recursive: true });
+  }
+  return path.join(dbDir, "settings.db");
+}
+
+function runMigrations(db: BetterSqlite3.Database): void {
+  const version = db.pragma("user_version", { simple: true }) as number;
+
+  if (version < 1) {
+    db.prepare(
+      `
+      CREATE TABLE IF NOT EXISTS provider_instances (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        providerName TEXT NOT NULL,
+        apiKey TEXT NOT NULL,
+        isActive INTEGER NOT NULL DEFAULT 0,
+        modelName TEXT,
+        type TEXT NOT NULL DEFAULT 'generative',
+        maxContext INTEGER,
+        endpointUrl TEXT
+      )
+      `,
+    ).run();
+    db.pragma("user_version = 1");
+  }
+
+  db.prepare(
+    `
+    CREATE TABLE IF NOT EXISTS provider_mappings (
+      task TEXT PRIMARY KEY,
+      providerInstanceId TEXT NOT NULL
+    )
+    `,
+  ).run();
+}
+
+export function getDb(): BetterSqlite3.Database {
+  if (!_db) {
+    const dbPath = _dbPathOverride ?? findDbPath();
+    _db = new Database(dbPath);
+    runMigrations(_db);
+  }
+  return _db;
+}

packages/llm/src/index.ts

@@ -1,6 +1,14 @@
 export * from "./llm.js";
 export * from "./config.js";
+export * from "./registry.js";
+export * from "./provider-factory.js";
+export * from "./model-lister.js";
+export * from "./provider-manager.js";
 export * from "./providers/google-genai.js";
 export * from "./providers/mock.js";
+export * from "./providers/ollama.js";
 export * from "./providers/openrouter.js";
-export * from "./provider-manager.js";
+export * from "./providers/anthropic.js";
+export * from "./providers/openai.js";
+export * from "./providers/groq.js";
+export * from "./providers/deepseek.js";

packages/llm/src/llm.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ProviderRegistry } from "./registry.js";
 
 export interface LLMRequest<T extends z.ZodTypeAny> {
   systemPrompt: string;
@@ -57,6 +58,7 @@ export interface ModelProviderInstance {
   modelName?: string;
   type: "generative" | "embedding";
   maxContext?: number;
+  endpointUrl?: string;
 }
 
 export interface ModelProviderMeta {
@@ -67,26 +69,21 @@ export interface ModelProviderMeta {
   defaultEmbeddingModel: string;
 }
 
-export const AVAILABLE_PROVIDERS: ModelProviderMeta[] = [
-  {
-    id: "google-genai",
-    displayName: "Google Gemini",
-    description: "Official Gemini integration using Google Gen AI SDK",
-    defaultModel: "gemini-2.5-flash",
-    defaultEmbeddingModel: "gemini-embedding-001",
+export function getAvailableProviders(): ModelProviderMeta[] {
+  return ProviderRegistry.all().map((def) => ({
+    id: def.id,
+    displayName: def.displayName,
+    description: def.description,
+    defaultModel: def.defaultModel,
+    defaultEmbeddingModel: def.defaultEmbeddingModel || "",
+  }));
+}
+
+export const AVAILABLE_PROVIDERS = {
+  get count(): number {
+    return getAvailableProviders().length;
   },
-  {
-    id: "openrouter",
-    displayName: "OpenRouter",
-    description: "Multi-model router supporting Anthropic, OpenAI, DeepSeek, and local models",
-    defaultModel: "google/gemini-2.5-flash",
-    defaultEmbeddingModel: "openai/text-embedding-3-small",
+  toArray(): ModelProviderMeta[] {
+    return getAvailableProviders();
   },
-  {
-    id: "mock",
-    displayName: "Mock LLM Provider",
-    description: "Stateless mock provider for testing and offline development",
-    defaultModel: "mock",
-    defaultEmbeddingModel: "mock-embeddings",
-  },
-];
+};

packages/llm/src/model-lister.ts

@@ -0,0 +1,105 @@
+/**
+ * ModelLister — fetches available models from each provider's REST API.
+ * Results are cached in-memory with a 5-minute TTL to avoid repeated calls.
+ */
+
+import { ProviderRegistry } from "./registry.js";
+
+export interface ModelInfo {
+  id: string;
+  name: string;
+  ownedBy?: string;
+}
+
+interface CacheEntry {
+  models: ModelInfo[];
+  fetchedAt: number;
+}
+
+const CACHE_TTL_MS = 5 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 10_000;
+
+const modelCache = new Map<string, CacheEntry>();
+
+function cacheKey(
+  providerName: string,
+  apiKey: string,
+  endpointUrl?: string,
+): string {
+  return `${providerName}:${endpointUrl || apiKey}`;
+}
+
+export async function fetchWithTimeout(
+  url: string,
+  init?: RequestInit,
+): Promise<Response> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function fetchOpenAICompatibleModels(
+  baseUrl: string,
+  apiKey: string,
+): Promise<ModelInfo[]> {
+  const res = await fetchWithTimeout(`${baseUrl}/models`, {
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      Accept: "application/json",
+    },
+  });
+  if (!res.ok) return [];
+
+  const json = (await res.json()) as {
+    data?: { id: string; owned_by?: string; name?: string }[];
+  };
+
+  return (json.data ?? []).map((m) => ({
+    id: m.id,
+    name: m.name || m.id,
+    ownedBy: m.owned_by,
+  }));
+}
+
+export class ModelLister {
+  static async listModels(
+    providerName: string,
+    apiKey: string,
+    endpointUrl?: string,
+  ): Promise<ModelInfo[]> {
+    const key = cacheKey(providerName, apiKey, endpointUrl);
+    const cached = modelCache.get(key);
+    if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
+      return cached.models;
+    }
+
+    const def = ProviderRegistry.get(providerName);
+    let models: ModelInfo[] = [];
+    try {
+      if (def?.listModels) {
+        models = await def.listModels(apiKey, endpointUrl);
+      }
+    } catch {
+      models = [];
+    }
+
+    modelCache.set(key, { models, fetchedAt: Date.now() });
+    return models;
+  }
+
+  static invalidateCache(
+    providerName: string,
+    apiKey: string,
+    endpointUrl?: string,
+  ): void {
+    modelCache.delete(cacheKey(providerName, apiKey, endpointUrl));
+  }
+
+  static clearCache(): void {
+    modelCache.clear();
+  }
+}

packages/llm/src/provider-factory.ts

@@ -0,0 +1,21 @@
+import type {
+  ILLMProvider,
+  IEmbeddingProvider,
+  ModelProviderInstance,
+} from "./llm.js";
+import { MockLLMProvider, MockEmbeddingProvider } from "./providers/mock.js";
+import { ProviderRegistry } from "./registry.js";
+
+export function buildLLMProvider(inst: ModelProviderInstance): ILLMProvider {
+  const def = ProviderRegistry.get(inst.providerName);
+  return def?.generativeCreate?.(inst) ?? new MockLLMProvider([]);
+}
+
+export function buildEmbeddingProvider(
+  inst: ModelProviderInstance,
+): IEmbeddingProvider {
+  const def = ProviderRegistry.get(inst.providerName);
+  return (
+    def?.embeddingCreate?.(inst) ?? new MockEmbeddingProvider(inst.modelName)
+  );
+}

packages/llm/src/provider-manager.ts

@@ -1,148 +1,16 @@
-import Database from "better-sqlite3";
-import path from "path";
-import fs from "fs";
 import type { ModelProviderInstance } from "./llm.js";
+import { getDb } from "./db.js";
+import { mapRow, type DbRow } from "./row-mapper.js";
 
-let dbPathOverride: string | null = null;
-let hasBootstrapped = false;
-
-export function setDbPathOverride(p: string | null) {
-  dbPathOverride = p;
-}
-
-export function resetHasBootstrapped() {
-  hasBootstrapped = false;
-}
-
-function getWorkspaceRoot() {
-  let current = process.cwd();
-  while (current !== "/" && current !== path.parse(current).root) {
-    if (
-      fs.existsSync(path.join(current, "pnpm-workspace.yaml")) ||
-      fs.existsSync(path.join(current, "package.json"))
-    ) {
-      if (fs.existsSync(path.join(current, "pnpm-workspace.yaml"))) {
-        return current;
-      }
-    }
-    current = path.dirname(current);
-  }
-  return process.cwd();
-}
-
-function getSettingsDb() {
-  let dbPath: string;
-  if (dbPathOverride) {
-    dbPath = dbPathOverride;
-  } else {
-    const wsRoot = getWorkspaceRoot();
-    const dbDir = path.resolve(wsRoot, "data");
-    if (!fs.existsSync(dbDir)) {
-      fs.mkdirSync(dbDir, { recursive: true });
-    }
-    dbPath = path.join(dbDir, "settings.db");
-  }
-  const db = new Database(dbPath);
-  
-  db.prepare(`
-    CREATE TABLE IF NOT EXISTS provider_instances (
-      id TEXT PRIMARY KEY,
-      name TEXT NOT NULL,
-      providerName TEXT NOT NULL,
-      apiKey TEXT NOT NULL,
-      isActive INTEGER NOT NULL DEFAULT 0,
-      modelName TEXT,
-      type TEXT NOT NULL DEFAULT 'generative'
-    )
-  `).run();
-
-  try {
-    db.prepare(`ALTER TABLE provider_instances ADD COLUMN modelName TEXT`).run();
-  } catch {
-    // ignore
-  }
-
-  try {
-    db.prepare(`ALTER TABLE provider_instances ADD COLUMN type TEXT NOT NULL DEFAULT 'generative'`).run();
-  } catch {
-    // ignore
-  }
-
-  try {
-    db.prepare(`ALTER TABLE provider_instances ADD COLUMN maxContext INTEGER`).run();
-  } catch {
-    // ignore
-  }
-
-  // Auto-bootstrap environment variables if DB contains 0 instances
-  try {
-    if (!hasBootstrapped) {
-      const totalCount = db.prepare(`SELECT COUNT(*) as count FROM provider_instances`).get() as { count: number };
-      if (totalCount.count === 0) {
-        const googleKey = process.env.GOOGLE_API_KEY;
-        const openRouterKey = process.env.OPENROUTER_API_KEY;
-        let hasInsertedGenerative = false;
-
-        if (googleKey && googleKey.trim()) {
-          const id = "provider-default-google";
-          db.prepare(`
-            INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName, type, maxContext)
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-          `).run(id, "Gemini (Env)", "google-genai", googleKey.trim(), 1, "gemini-2.5-flash", "generative", 32768);
-          hasInsertedGenerative = true;
-
-          const embedId = "provider-default-google-embed";
-          db.prepare(`
-            INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName, type, maxContext)
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-          `).run(embedId, "Gemini Embed (Env)", "google-genai", googleKey.trim(), 1, "gemini-embedding-001", "embedding", 0);
-        }
-
-        if (openRouterKey && openRouterKey.trim()) {
-          const id = "provider-default-openrouter";
-          const isActive = hasInsertedGenerative ? 0 : 1;
-          db.prepare(`
-            INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName, type, maxContext)
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-          `).run(id, "OpenRouter (Env)", "openrouter", openRouterKey.trim(), isActive, "google/gemini-2.5-flash", "generative", 32768);
-        }
-      }
-      hasBootstrapped = true;
-    }
-  } catch {
-    // ignore write lock issues or other DB errors during bootstrap
-  }
-  
-  return db;
-}
+export { setDbPath as setDbPathOverride } from "./db.js";
 
 export class ProviderManager {
   static list(): ModelProviderInstance[] {
-    const db = getSettingsDb();
-    try {
-      const rows = db.prepare(`SELECT * FROM provider_instances`).all() as {
-        id: string;
-        name: string;
-        providerName: string;
-        apiKey: string;
-        isActive: number;
-        modelName?: string;
-        type: string;
-        maxContext?: number;
-      }[];
-      return rows.map((r) => ({
-        id: r.id,
-        name: r.name,
-        providerName: r.providerName,
-        apiKey: r.apiKey,
-        isActive: r.isActive === 1,
-        modelName: r.modelName || undefined,
-        type: (r.type as "generative" | "embedding") || "generative",
-        maxContext: r.maxContext !== undefined && r.maxContext !== null ? r.maxContext : (r.type === "embedding" ? 0 : 32768),
-      }));
-    } finally {
-      db.close();
-    }
+    const db = getDb();
+    const rows = db
+      .prepare("SELECT * FROM provider_instances")
+      .all() as DbRow[];
+    return rows.map(mapRow);
   }
 
   static create(
@@ -151,58 +19,80 @@ export class ProviderManager {
     apiKey: string,
     modelName?: string,
     type: "generative" | "embedding" = "generative",
-    maxContext?: number
+    maxContext?: number,
+    endpointUrl?: string,
   ): ModelProviderInstance {
-    const db = getSettingsDb();
-    try {
-      const id = "provider-" + Date.now();
-      const activeCount = db
-        .prepare(`SELECT COUNT(*) as count FROM provider_instances WHERE isActive = 1 AND type = ?`)
-        .get(type) as { count: number };
-      const isActive = activeCount.count === 0 ? 1 : 0;
-      
-      const actualMaxContext = maxContext !== undefined ? maxContext : (type === "generative" ? 32768 : 0);
+    const db = getDb();
+    const id = "provider-" + Date.now();
+    const activeCount = db
+      .prepare(
+        "SELECT COUNT(*) as count FROM provider_instances WHERE isActive = 1 AND type = ?",
+      )
+      .get(type) as { count: number };
+    const isActive = activeCount.count === 0 ? 1 : 0;
 
-      db.prepare(`
-        INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName, type, maxContext)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-      `).run(id, name, providerName, apiKey, isActive, modelName || null, type, actualMaxContext);
-      
-      return { id, name, providerName, apiKey, isActive: isActive === 1, modelName, type, maxContext: actualMaxContext };
-    } finally {
-      db.close();
-    }
+    const actualMaxContext =
+      maxContext !== undefined ? maxContext : type === "generative" ? 32768 : 0;
+
+    db.prepare(
+      `INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName, type, maxContext, endpointUrl)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      id,
+      name,
+      providerName,
+      apiKey,
+      isActive,
+      modelName || null,
+      type,
+      actualMaxContext,
+      endpointUrl || null,
+    );
+
+    return {
+      id,
+      name,
+      providerName,
+      apiKey,
+      isActive: isActive === 1,
+      modelName,
+      type,
+      maxContext: actualMaxContext,
+      endpointUrl,
+    };
   }
 
   static delete(id: string): void {
-    const db = getSettingsDb();
-    try {
-      const provider = db.prepare(`SELECT isActive, type FROM provider_instances WHERE id = ?`).get(id) as { isActive: number; type: string } | undefined;
-      db.prepare(`DELETE FROM provider_instances WHERE id = ?`).run(id);
-      
-      if (provider && provider.isActive === 1) {
-        const next = db
-          .prepare(`SELECT id FROM provider_instances WHERE type = ? LIMIT 1`)
-          .get(provider.type) as { id: string } | undefined;
-        if (next) {
-          db.prepare(`UPDATE provider_instances SET isActive = 1 WHERE id = ?`).run(next.id);
-        }
+    const db = getDb();
+    const provider = db
+      .prepare("SELECT isActive, type FROM provider_instances WHERE id = ?")
+      .get(id) as { isActive: number; type: string } | undefined;
+    db.prepare("DELETE FROM provider_instances WHERE id = ?").run(id);
+
+    if (provider && provider.isActive === 1) {
+      const next = db
+        .prepare("SELECT id FROM provider_instances WHERE type = ? LIMIT 1")
+        .get(provider.type) as { id: string } | undefined;
+      if (next) {
+        db.prepare(
+          "UPDATE provider_instances SET isActive = 1 WHERE id = ?",
+        ).run(next.id);
       }
-    } finally {
-      db.close();
     }
   }
 
   static setActive(id: string): void {
-    const db = getSettingsDb();
-    try {
-      const target = db.prepare(`SELECT type FROM provider_instances WHERE id = ?`).get(id) as { type: string } | undefined;
-      if (target) {
-        db.prepare(`UPDATE provider_instances SET isActive = 0 WHERE type = ?`).run(target.type);
-        db.prepare(`UPDATE provider_instances SET isActive = 1 WHERE id = ?`).run(id);
-      }
-    } finally {
-      db.close();
+    const db = getDb();
+    const target = db
+      .prepare("SELECT type FROM provider_instances WHERE id = ?")
+      .get(id) as { type: string } | undefined;
+    if (target) {
+      db.prepare(
+        "UPDATE provider_instances SET isActive = 0 WHERE type = ?",
+      ).run(target.type);
+      db.prepare("UPDATE provider_instances SET isActive = 1 WHERE id = ?").run(
+        id,
+      );
     }
   }
 
@@ -213,229 +103,100 @@ export class ProviderManager {
     apiKey?: string,
     modelName?: string,
     type: "generative" | "embedding" = "generative",
-    maxContext?: number
+    maxContext?: number,
+    endpointUrl?: string,
   ): void {
-    const db = getSettingsDb();
-    try {
-      const actualMaxContext = maxContext !== undefined ? maxContext : (type === "generative" ? 32768 : 0);
-      if (apiKey && apiKey.trim()) {
-        db.prepare(`
-          UPDATE provider_instances
-          SET name = ?, providerName = ?, apiKey = ?, modelName = ?, type = ?, maxContext = ?
-          WHERE id = ?
-        `).run(name, providerName, apiKey, modelName || null, type, actualMaxContext, id);
-      } else {
-        db.prepare(`
-          UPDATE provider_instances
-          SET name = ?, providerName = ?, modelName = ?, type = ?, maxContext = ?
-          WHERE id = ?
-        `).run(name, providerName, modelName || null, type, actualMaxContext, id);
-      }
-    } finally {
-      db.close();
+    const db = getDb();
+    const actualMaxContext =
+      maxContext !== undefined ? maxContext : type === "generative" ? 32768 : 0;
+
+    if (apiKey && apiKey.trim()) {
+      db.prepare(
+        `UPDATE provider_instances
+         SET name = ?, providerName = ?, apiKey = ?, modelName = ?, type = ?, maxContext = ?, endpointUrl = ?
+         WHERE id = ?`,
+      ).run(
+        name,
+        providerName,
+        apiKey,
+        modelName || null,
+        type,
+        actualMaxContext,
+        endpointUrl || null,
+        id,
+      );
+    } else {
+      db.prepare(
+        `UPDATE provider_instances
+         SET name = ?, providerName = ?, modelName = ?, type = ?, maxContext = ?, endpointUrl = ?
+         WHERE id = ?`,
+      ).run(
+        name,
+        providerName,
+        modelName || null,
+        type,
+        actualMaxContext,
+        endpointUrl || null,
+        id,
+      );
     }
   }
 
-  static getActive(type: "generative" | "embedding" = "generative"): ModelProviderInstance | null {
-    const db = getSettingsDb();
+  static getActive(
+    type: "generative" | "embedding" = "generative",
+  ): ModelProviderInstance | null {
+    const db = getDb();
     try {
-      const row = db.prepare(`SELECT * FROM provider_instances WHERE isActive = 1 AND type = ?`).get(type) as {
-        id: string;
-        name: string;
-        providerName: string;
-        apiKey: string;
-        isActive: number;
-        modelName?: string;
-        type: string;
-        maxContext?: number;
-      } | undefined;
+      const row = db
+        .prepare(
+          "SELECT * FROM provider_instances WHERE isActive = 1 AND type = ?",
+        )
+        .get(type) as DbRow | undefined;
 
-      if (!row) {
-        const totalCount = db.prepare(`SELECT COUNT(*) as count FROM provider_instances`).get() as { count: number };
-        if (totalCount.count === 0) {
-          const googleKey = process.env.GOOGLE_API_KEY;
-          const openRouterKey = process.env.OPENROUTER_API_KEY;
-          let hasInsertedGenerative = false;
-
-          if (googleKey && googleKey.trim()) {
-            const id = "provider-default-google";
-            db.prepare(`
-              INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName, type, maxContext)
-              VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-            `).run(id, "Gemini (Env)", "google-genai", googleKey.trim(), 1, "gemini-2.5-flash", "generative", 32768);
-            hasInsertedGenerative = true;
-
-            const embedId = "provider-default-google-embed";
-            db.prepare(`
-              INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName, type, maxContext)
-              VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-            `).run(embedId, "Gemini Embed (Env)", "google-genai", googleKey.trim(), 1, "gemini-embedding-001", "embedding", 0);
-          }
-
-          if (openRouterKey && openRouterKey.trim()) {
-            const id = "provider-default-openrouter";
-            const isActive = hasInsertedGenerative ? 0 : 1;
-            db.prepare(`
-              INSERT INTO provider_instances (id, name, providerName, apiKey, isActive, modelName, type, maxContext)
-              VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-            `).run(id, "OpenRouter (Env)", "openrouter", openRouterKey.trim(), isActive, "google/gemini-2.5-flash", "generative", 32768);
-          }
-
-          const retryRow = db.prepare(`SELECT * FROM provider_instances WHERE isActive = 1 AND type = ?`).get(type) as {
-            id: string;
-            name: string;
-            providerName: string;
-            apiKey: string;
-            isActive: number;
-            modelName?: string;
-            type: string;
-            maxContext?: number;
-          } | undefined;
-
-          if (retryRow) {
-            return {
-              id: retryRow.id,
-              name: retryRow.name,
-              providerName: retryRow.providerName,
-              apiKey: retryRow.apiKey,
-              isActive: true,
-              modelName: retryRow.modelName || undefined,
-              type: retryRow.type as "generative" | "embedding",
-              maxContext: retryRow.maxContext !== undefined && retryRow.maxContext !== null ? retryRow.maxContext : (retryRow.type === "embedding" ? 0 : 32768),
-            };
-          }
-        }
-
-        // If there's no active row but some rows exist, return the first one as active, or update it
-        const firstRow = db.prepare(`SELECT * FROM provider_instances WHERE type = ? LIMIT 1`).get(type) as {
-          id: string;
-          name: string;
-          providerName: string;
-          apiKey: string;
-          isActive: number;
-          modelName?: string;
-          type: string;
-          maxContext?: number;
-        } | undefined;
-        if (firstRow) {
-          db.prepare(`UPDATE provider_instances SET isActive = 1 WHERE id = ?`).run(firstRow.id);
-          return {
-            id: firstRow.id,
-            name: firstRow.name,
-            providerName: firstRow.providerName,
-            apiKey: firstRow.apiKey,
-            isActive: true,
-            modelName: firstRow.modelName || undefined,
-            type: firstRow.type as "generative" | "embedding",
-            maxContext: firstRow.maxContext !== undefined && firstRow.maxContext !== null ? firstRow.maxContext : (firstRow.type === "embedding" ? 0 : 32768),
-          };
-        }
-        return null;
+      if (row) {
+        return mapRow(row);
       }
 
-      return {
-        id: row.id,
-        name: row.name,
-        providerName: row.providerName,
-        apiKey: row.apiKey,
-        isActive: true,
-        modelName: row.modelName || undefined,
-        type: (row.type as "generative" | "embedding") || "generative",
-        maxContext: row.maxContext !== undefined && row.maxContext !== null ? row.maxContext : (row.type === "embedding" ? 0 : 32768),
-      };
-    } catch {
-      const googleKey = process.env.GOOGLE_API_KEY;
-      if (type === "embedding") {
-        if (googleKey && googleKey.trim()) {
-          return {
-            id: "provider-default-env-embed-fallback",
-            name: "Gemini Embed (Env Fallback)",
-            providerName: "google-genai",
-            apiKey: googleKey.trim(),
-            isActive: true,
-            modelName: "gemini-embedding-001",
-            type: "embedding",
-            maxContext: 0,
-          };
-        }
-        return null;
+      const firstRow = db
+        .prepare("SELECT * FROM provider_instances WHERE type = ? LIMIT 1")
+        .get(type) as DbRow | undefined;
+
+      if (firstRow) {
+        db.prepare(
+          "UPDATE provider_instances SET isActive = 1 WHERE id = ?",
+        ).run(firstRow.id);
+        return mapRow(firstRow);
       }
 
-      // generative fallback
-      if (googleKey && googleKey.trim()) {
-        return {
-          id: "provider-default-env-fallback",
-          name: "Gemini (Env Fallback)",
-          providerName: "google-genai",
-          apiKey: googleKey.trim(),
-          isActive: true,
-          modelName: "gemini-2.5-flash",
-          type: "generative",
-          maxContext: 32768,
-        };
-      }
-      const openRouterKey = process.env.OPENROUTER_API_KEY;
-      if (openRouterKey && openRouterKey.trim()) {
-        return {
-          id: "provider-default-env-fallback",
-          name: "OpenRouter (Env Fallback)",
-          providerName: "openrouter",
-          apiKey: openRouterKey.trim(),
-          isActive: true,
-          modelName: "google/gemini-2.5-flash",
-          type: "generative",
-          maxContext: 32768,
-        };
-      }
       return null;
-    } finally {
-      db.close();
+    } catch {
+      return null;
     }
   }
 
   static getMappings(): Record<string, string> {
-    const db = getSettingsDb();
-    try {
-      db.prepare(`
-        CREATE TABLE IF NOT EXISTS provider_mappings (
-          task TEXT PRIMARY KEY,
-          providerInstanceId TEXT NOT NULL
-        )
-      `).run();
-      const rows = db.prepare(`SELECT * FROM provider_mappings`).all() as {
-        task: string;
-        providerInstanceId: string;
-      }[];
-      const mappings: Record<string, string> = {};
-      for (const row of rows) {
-        mappings[row.task] = row.providerInstanceId;
-      }
-      return mappings;
-    } finally {
-      db.close();
+    const db = getDb();
+    const rows = db.prepare("SELECT * FROM provider_mappings").all() as {
+      task: string;
+      providerInstanceId: string;
+    }[];
+    const mappings: Record<string, string> = {};
+    for (const row of rows) {
+      mappings[row.task] = row.providerInstanceId;
     }
+    return mappings;
   }
 
   static setMapping(task: string, providerInstanceId: string): void {
-    const db = getSettingsDb();
-    try {
-      db.prepare(`
-        CREATE TABLE IF NOT EXISTS provider_mappings (
-          task TEXT PRIMARY KEY,
-          providerInstanceId TEXT NOT NULL
-        )
-      `).run();
-      if (!providerInstanceId) {
-        db.prepare(`DELETE FROM provider_mappings WHERE task = ?`).run(task);
-      } else {
-        db.prepare(`
-          INSERT INTO provider_mappings (task, providerInstanceId)
-          VALUES (?, ?)
-          ON CONFLICT(task) DO UPDATE SET providerInstanceId = excluded.providerInstanceId
-        `).run(task, providerInstanceId);
-      }
-    } finally {
-      db.close();
+    const db = getDb();
+    if (!providerInstanceId) {
+      db.prepare("DELETE FROM provider_mappings WHERE task = ?").run(task);
+    } else {
+      db.prepare(
+        `INSERT INTO provider_mappings (task, providerInstanceId)
+         VALUES (?, ?)
+         ON CONFLICT(task) DO UPDATE SET providerInstanceId = excluded.providerInstanceId`,
+      ).run(task, providerInstanceId);
     }
   }
 }

packages/llm/src/providers/anthropic.ts

@@ -0,0 +1,116 @@
+import { ChatAnthropic } from "@langchain/anthropic";
+import { ILLMProvider } from "../llm.js";
+import type { ModelProviderInstance } from "../llm.js";
+import { BaseLLMProvider, resolveCredentials } from "../base-provider.js";
+import { registerProvider, registerGenerative } from "../registry.js";
+import { fetchWithTimeout, type ModelInfo } from "../model-lister.js";
+
+async function fetchAnthropicModels(apiKey: string): Promise<ModelInfo[]> {
+  const models: ModelInfo[] = [];
+  let afterId: string | undefined;
+
+  do {
+    const url = new URL("https://api.anthropic.com/v1/models");
+    url.searchParams.set("limit", "1000");
+    if (afterId) {
+      url.searchParams.set("after_id", afterId);
+    }
+
+    const res = await fetchWithTimeout(url.toString(), {
+      headers: {
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+        Accept: "application/json",
+      },
+    });
+    if (!res.ok) return models;
+
+    const json = (await res.json()) as {
+      data?: { id: string; display_name?: string }[];
+      has_more?: boolean;
+      last_id?: string;
+    };
+
+    for (const m of json.data ?? []) {
+      models.push({ id: m.id, name: m.display_name || m.id });
+    }
+
+    afterId = json.has_more ? json.last_id : undefined;
+  } while (afterId);
+
+  return models;
+}
+
+export class AnthropicProvider extends BaseLLMProvider {
+  static {
+    registerProvider({
+      id: "anthropic",
+      displayName: "Anthropic Claude",
+      description: "Official Claude integration using @langchain/anthropic SDK",
+      envVar: "ANTHROPIC_API_KEY",
+      capabilities: { generative: true, embedding: false },
+      defaultModel: "claude-3-5-sonnet-latest",
+      defaultMaxContext: 200000,
+      fallbackPriority: 2,
+      listModels: fetchAnthropicModels,
+    });
+    registerGenerative(
+      "anthropic",
+      (inst: ModelProviderInstance) =>
+        new AnthropicProvider(
+          inst.apiKey,
+          inst.modelName,
+          inst.name,
+          inst.maxContext,
+        ),
+    );
+  }
+
+  static create(inst: ModelProviderInstance): ILLMProvider {
+    return new AnthropicProvider(
+      inst.apiKey,
+      inst.modelName,
+      inst.name,
+      inst.maxContext,
+    );
+  }
+
+  providerName = "Anthropic";
+  protected readonly model: ChatAnthropic;
+  protected modelNameUsed: string;
+  protected providerInstanceName?: string;
+  protected maxContextUsed?: number;
+  protected defaultMaxContext = 200000;
+
+  constructor(
+    apiKey?: string,
+    modelName?: string,
+    providerInstanceName?: string,
+    maxContext?: number,
+  ) {
+    super();
+    const {
+      key,
+      model,
+      providerInstanceName: resolvedName,
+      maxContext: resolvedMax,
+    } = resolveCredentials({
+      explicitKey: apiKey,
+      explicitModel: modelName,
+      explicitProviderInstanceName: providerInstanceName,
+      explicitMaxContext: maxContext,
+      providerId: "anthropic",
+      envVarName: "ANTHROPIC_API_KEY",
+      type: "generative",
+    });
+    if (!key) {
+      throw new Error(
+        "ANTHROPIC_API_KEY is required to initialize AnthropicProvider",
+      );
+    }
+    this.providerInstanceName = resolvedName;
+    this.maxContextUsed = resolvedMax;
+    this.modelNameUsed = model || "claude-3-5-sonnet-latest";
+    this.model = new ChatAnthropic({ apiKey: key, model: this.modelNameUsed });
+  }
+}

packages/llm/src/providers/deepseek.ts

@@ -0,0 +1,82 @@
+import { ChatDeepSeek } from "@langchain/deepseek";
+import { ILLMProvider } from "../llm.js";
+import type { ModelProviderInstance } from "../llm.js";
+import { BaseLLMProvider, resolveCredentials } from "../base-provider.js";
+import { registerProvider, registerGenerative } from "../registry.js";
+import { fetchOpenAICompatibleModels } from "../model-lister.js";
+
+export class DeepSeekProvider extends BaseLLMProvider {
+  static {
+    registerProvider({
+      id: "deepseek",
+      displayName: "DeepSeek",
+      description:
+        "Official DeepSeek integration using @langchain/deepseek SDK",
+      envVar: "DEEPSEEK_API_KEY",
+      capabilities: { generative: true, embedding: false },
+      defaultModel: "deepseek-chat",
+      defaultMaxContext: 64000,
+      fallbackPriority: 4,
+      listModels: (apiKey) =>
+        fetchOpenAICompatibleModels("https://api.deepseek.com", apiKey),
+    });
+    registerGenerative(
+      "deepseek",
+      (inst: ModelProviderInstance) =>
+        new DeepSeekProvider(
+          inst.apiKey,
+          inst.modelName,
+          inst.name,
+          inst.maxContext,
+        ),
+    );
+  }
+
+  static create(inst: ModelProviderInstance): ILLMProvider {
+    return new DeepSeekProvider(
+      inst.apiKey,
+      inst.modelName,
+      inst.name,
+      inst.maxContext,
+    );
+  }
+
+  providerName = "DeepSeek";
+  protected readonly model: ChatDeepSeek;
+  protected modelNameUsed: string;
+  protected providerInstanceName?: string;
+  protected maxContextUsed?: number;
+  protected defaultMaxContext = 64000;
+
+  constructor(
+    apiKey?: string,
+    modelName?: string,
+    providerInstanceName?: string,
+    maxContext?: number,
+  ) {
+    super();
+    const {
+      key,
+      model,
+      providerInstanceName: resolvedName,
+      maxContext: resolvedMax,
+    } = resolveCredentials({
+      explicitKey: apiKey,
+      explicitModel: modelName,
+      explicitProviderInstanceName: providerInstanceName,
+      explicitMaxContext: maxContext,
+      providerId: "deepseek",
+      envVarName: "DEEPSEEK_API_KEY",
+      type: "generative",
+    });
+    if (!key) {
+      throw new Error(
+        "DEEPSEEK_API_KEY is required to initialize DeepSeekProvider",
+      );
+    }
+    this.providerInstanceName = resolvedName;
+    this.maxContextUsed = resolvedMax;
+    this.modelNameUsed = model || "deepseek-chat";
+    this.model = new ChatDeepSeek({ apiKey: key, model: this.modelNameUsed });
+  }
+}

packages/llm/src/providers/google-genai.ts

@@ -1,129 +1,169 @@
-import { z } from "zod";
-import { ChatGoogleGenerativeAI, GoogleGenerativeAIEmbeddings } from "@langchain/google-genai";
-import { ILLMProvider, LLMRequest, LLMResponse, LLMCallRecord, IEmbeddingProvider } from "../llm.js";
-import { llmConfig } from "../config.js";
+import {
+  ChatGoogleGenerativeAI,
+  GoogleGenerativeAIEmbeddings,
+} from "@langchain/google-genai";
+import type {
+  ILLMProvider,
+  IEmbeddingProvider,
+  ModelProviderInstance,
+} from "../llm.js";
+import {
+  registerProvider,
+  registerGenerative,
+  registerEmbedding,
+} from "../registry.js";
+import { fetchWithTimeout, type ModelInfo } from "../model-lister.js";
+import { BaseLLMProvider, resolveCredentials } from "../base-provider.js";
+import { getLlmConfig } from "../config.js";
 import { ProviderManager } from "../provider-manager.js";
 
-export class GeminiProvider implements ILLMProvider {
-  static readonly providerId = "google-genai";
-  static readonly displayName = "Google Gemini";
-  static readonly description = "Official Gemini integration using Google Gen AI SDK";
-  static readonly defaultModel = "gemini-2.5-flash";
+async function fetchGeminiModels(apiKey: string): Promise<ModelInfo[]> {
+  const models: ModelInfo[] = [];
+  let pageToken: string | undefined;
+
+  do {
+    const url = new URL(
+      "https://generativelanguage.googleapis.com/v1beta/models",
+    );
+    url.searchParams.set("key", apiKey);
+    url.searchParams.set("pageSize", "100");
+    if (pageToken) {
+      url.searchParams.set("pageToken", pageToken);
+    }
+
+    const res = await fetchWithTimeout(url.toString());
+    if (!res.ok) return models;
+
+    const json = (await res.json()) as {
+      models?: { name: string; displayName?: string }[];
+      nextPageToken?: string;
+    };
+
+    for (const m of json.models ?? []) {
+      const id = m.name.replace(/^models\//, "");
+      models.push({ id, name: m.displayName || id });
+    }
+
+    pageToken = json.nextPageToken;
+  } while (pageToken);
+
+  return models;
+}
+
+export class GeminiProvider extends BaseLLMProvider {
+  static {
+    registerProvider({
+      id: "google-genai",
+      displayName: "Google Gemini",
+      description: "Official Gemini integration using Google Gen AI SDK",
+      envVar: "GOOGLE_API_KEY",
+      capabilities: { generative: true, embedding: true },
+      defaultModel: "gemini-2.5-flash",
+      defaultEmbeddingModel: "gemini-embedding-001",
+      defaultMaxContext: 32768,
+      fallbackPriority: 0,
+      listModels: fetchGeminiModels,
+    });
+    registerGenerative(
+      "google-genai",
+      (inst: ModelProviderInstance) =>
+        new GeminiProvider(
+          inst.apiKey,
+          inst.modelName,
+          inst.name,
+          inst.maxContext,
+        ),
+    );
+  }
 
   providerName = "Gemini";
-  private model: ChatGoogleGenerativeAI;
-  private modelNameUsed: string;
-  private providerInstanceName?: string;
-  private maxContextUsed?: number;
-  lastCalls: LLMCallRecord[] = [];
+  protected readonly model: ChatGoogleGenerativeAI;
+  protected modelNameUsed: string;
+  protected providerInstanceName?: string;
+  protected maxContextUsed?: number;
+  protected readonly defaultMaxContext = 32768;
 
-  constructor(apiKey?: string, modelName?: string, providerInstanceName?: string, maxContext?: number) {
-    let key = apiKey;
-    let model = modelName;
-    this.providerInstanceName = providerInstanceName;
-    this.maxContextUsed = maxContext;
+  static create(inst: ModelProviderInstance): ILLMProvider {
+    return new GeminiProvider(
+      inst.apiKey,
+      inst.modelName,
+      inst.name,
+      inst.maxContext,
+    );
+  }
 
+  constructor(
+    apiKey?: string,
+    modelName?: string,
+    providerInstanceName?: string,
+    maxContext?: number,
+  ) {
+    super();
+    const {
+      key,
+      model,
+      providerInstanceName: pn,
+      maxContext: mc,
+    } = resolveCredentials({
+      explicitKey: apiKey,
+      explicitModel: modelName,
+      explicitProviderInstanceName: providerInstanceName,
+      explicitMaxContext: maxContext,
+      providerId: "google-genai",
+      envVarName: "GOOGLE_API_KEY",
+      type: "generative",
+    });
     if (!key) {
-      const active = ProviderManager.getActive("generative");
-      if (active && active.providerName === GeminiProvider.providerId) {
-        key = active.apiKey;
-        if (!model) {
-          model = active.modelName;
-        }
-        if (!this.providerInstanceName) {
-          this.providerInstanceName = active.name;
-        }
-        if (this.maxContextUsed === undefined) {
-          this.maxContextUsed = active.maxContext;
-        }
-      }
+      throw new Error(
+        "GOOGLE_API_KEY is required to initialize GeminiProvider",
+      );
     }
-
-    if (!key) {
-      key = llmConfig.GOOGLE_API_KEY;
-      if (!this.providerInstanceName && key) {
-        this.providerInstanceName = "Environment Variable";
-      }
-    }
-
-    if (!key) {
-      throw new Error("GOOGLE_API_KEY is required to initialize GeminiProvider");
-    }
-
+    this.providerInstanceName = pn;
+    this.maxContextUsed = mc;
     this.modelNameUsed = model || "gemini-2.5-flash";
     this.model = new ChatGoogleGenerativeAI({
       apiKey: key,
       model: this.modelNameUsed,
     });
   }
-
-  async generateStructuredResponse<T extends z.ZodTypeAny>(
-    request: LLMRequest<T>,
-  ): Promise<LLMResponse<z.infer<T>>> {
-    const structuredModel = this.model.withStructuredOutput(request.schema, { includeRaw: true });
-    const result = (await structuredModel.invoke([
-      { role: "system", content: request.systemPrompt },
-      { role: "user", content: request.userContext },
-    ])) as unknown as {
-      parsed?: z.infer<T>;
-      raw?: {
-        usage_metadata?: {
-          input_tokens?: number;
-          output_tokens?: number;
-          total_tokens?: number;
-        };
-      };
-    };
-
-    const parsed = result?.parsed;
-    const raw = result?.raw;
-
-    const usage = {
-      inputTokens: raw?.usage_metadata?.input_tokens || 0,
-      outputTokens: raw?.usage_metadata?.output_tokens || 0,
-      totalTokens: raw?.usage_metadata?.total_tokens || 0,
-      modelName: this.modelNameUsed,
-      providerInstanceName: this.providerInstanceName || "Default",
-      maxContext: this.maxContextUsed !== undefined ? this.maxContextUsed : 32768,
-    };
-
-    this.lastCalls.push({
-      systemPrompt: request.systemPrompt,
-      userContext: request.userContext,
-      usage,
-    });
-
-    return { success: true, data: parsed, usage };
-  }
 }
 
 export class GeminiEmbeddingProvider implements IEmbeddingProvider {
-  static readonly providerId = "google-genai";
-  static readonly displayName = "Google Gemini Embeddings";
+  static {
+    registerEmbedding(
+      "google-genai",
+      (inst: ModelProviderInstance) =>
+        new GeminiEmbeddingProvider(inst.apiKey, inst.modelName),
+    );
+  }
 
   providerName = "Gemini";
   private model: GoogleGenerativeAIEmbeddings;
 
+  static create(inst: ModelProviderInstance): IEmbeddingProvider {
+    return new GeminiEmbeddingProvider(inst.apiKey, inst.modelName);
+  }
+
   constructor(apiKey?: string, modelName?: string) {
     let key = apiKey;
     let model = modelName;
 
     if (!key) {
       const active = ProviderManager.getActive("embedding");
-      if (active) {
+      if (active && active.providerName === "google-genai") {
         key = active.apiKey;
-        if (!model) {
-          model = active.modelName;
-        }
+        if (!model) model = active.modelName;
       }
     }
 
     if (!key) {
-      key = llmConfig.GOOGLE_API_KEY;
+      key = getLlmConfig().GOOGLE_API_KEY;
     }
 
     if (!key) {
-      throw new Error("GOOGLE_API_KEY is required to initialize GeminiEmbeddingProvider");
+      throw new Error(
+        "GOOGLE_API_KEY is required to initialize GeminiEmbeddingProvider",
+      );
     }
 
     this.model = new GoogleGenerativeAIEmbeddings({

packages/llm/src/providers/groq.ts

@@ -0,0 +1,79 @@
+import { ChatGroq } from "@langchain/groq";
+import { ILLMProvider } from "../llm.js";
+import type { ModelProviderInstance } from "../llm.js";
+import { BaseLLMProvider, resolveCredentials } from "../base-provider.js";
+import { registerProvider, registerGenerative } from "../registry.js";
+import { fetchOpenAICompatibleModels } from "../model-lister.js";
+
+export class GroqProvider extends BaseLLMProvider {
+  static {
+    registerProvider({
+      id: "groq",
+      displayName: "Groq",
+      description: "Official Groq integration using @langchain/groq SDK",
+      envVar: "GROQ_API_KEY",
+      capabilities: { generative: true, embedding: false },
+      defaultModel: "llama-3.3-70b-versatile",
+      defaultMaxContext: 8192,
+      fallbackPriority: 3,
+      listModels: (apiKey) =>
+        fetchOpenAICompatibleModels("https://api.groq.com/openai/v1", apiKey),
+    });
+    registerGenerative(
+      "groq",
+      (inst: ModelProviderInstance) =>
+        new GroqProvider(
+          inst.apiKey,
+          inst.modelName,
+          inst.name,
+          inst.maxContext,
+        ),
+    );
+  }
+
+  static create(inst: ModelProviderInstance): ILLMProvider {
+    return new GroqProvider(
+      inst.apiKey,
+      inst.modelName,
+      inst.name,
+      inst.maxContext,
+    );
+  }
+
+  providerName = "Groq";
+  protected readonly model: ChatGroq;
+  protected modelNameUsed: string;
+  protected providerInstanceName?: string;
+  protected maxContextUsed?: number;
+  protected defaultMaxContext = 8192;
+
+  constructor(
+    apiKey?: string,
+    modelName?: string,
+    providerInstanceName?: string,
+    maxContext?: number,
+  ) {
+    super();
+    const {
+      key,
+      model,
+      providerInstanceName: resolvedName,
+      maxContext: resolvedMax,
+    } = resolveCredentials({
+      explicitKey: apiKey,
+      explicitModel: modelName,
+      explicitProviderInstanceName: providerInstanceName,
+      explicitMaxContext: maxContext,
+      providerId: "groq",
+      envVarName: "GROQ_API_KEY",
+      type: "generative",
+    });
+    if (!key) {
+      throw new Error("GROQ_API_KEY is required to initialize GroqProvider");
+    }
+    this.providerInstanceName = resolvedName;
+    this.maxContextUsed = resolvedMax;
+    this.modelNameUsed = model || "llama-3.3-70b-versatile";
+    this.model = new ChatGroq({ apiKey: key, model: this.modelNameUsed });
+  }
+}

packages/llm/src/providers/mock.ts

@@ -1,11 +1,38 @@
 import { z } from "zod";
-import { ILLMProvider, LLMRequest, LLMResponse, LLMCallRecord, IEmbeddingProvider } from "../llm.js";
+import {
+  ILLMProvider,
+  LLMRequest,
+  LLMResponse,
+  LLMCallRecord,
+  IEmbeddingProvider,
+} from "../llm.js";
+import type { ModelProviderInstance } from "../llm.js";
+import {
+  registerProvider,
+  registerGenerative,
+  registerEmbedding,
+} from "../registry.js";
 
 export class MockLLMProvider implements ILLMProvider {
-  static readonly providerId = "mock";
-  static readonly displayName = "Mock LLM Provider";
-  static readonly description = "Stateless mock provider for testing and offline development";
-  static readonly defaultModel = "mock";
+  static {
+    registerProvider({
+      id: "mock",
+      displayName: "Mock LLM Provider",
+      description:
+        "Stateless mock provider for testing and offline development",
+      capabilities: { generative: true, embedding: true },
+      defaultModel: "mock",
+      defaultEmbeddingModel: "mock-embeddings",
+      defaultMaxContext: 0,
+      fallbackPriority: 1000,
+      listModels: () => Promise.resolve([{ id: "mock", name: "Mock Model" }]),
+    });
+    registerGenerative("mock", () => new MockLLMProvider([]));
+  }
+
+  static create(inst: ModelProviderInstance): ILLMProvider {
+    return new MockLLMProvider([]);
+  }
 
   providerName = "mock";
   private callCount = 0;
@@ -30,13 +57,26 @@ export class MockLLMProvider implements ILLMProvider {
       const parsed = request.schema.parse(next);
       return { success: true, data: parsed, usage };
     } catch (e) {
-      return { success: false, error: e instanceof Error ? e.message : String(e) };
+      return {
+        success: false,
+        error: e instanceof Error ? e.message : String(e),
+      };
     }
   }
 }
 
 export class MockEmbeddingProvider implements IEmbeddingProvider {
-  static readonly providerId = "mock";
+  static {
+    registerEmbedding(
+      "mock",
+      (inst: ModelProviderInstance) =>
+        new MockEmbeddingProvider(inst.modelName),
+    );
+  }
+
+  static create(inst: ModelProviderInstance): IEmbeddingProvider {
+    return new MockEmbeddingProvider(inst.modelName);
+  }
 
   providerName = "mock";
 

packages/llm/src/providers/ollama.ts

@@ -0,0 +1,172 @@
+import { ChatOllama, OllamaEmbeddings } from "@langchain/ollama";
+import { ILLMProvider, IEmbeddingProvider } from "../llm.js";
+import type { ModelProviderInstance } from "../llm.js";
+import { ProviderManager } from "../provider-manager.js";
+import { BaseLLMProvider } from "../base-provider.js";
+import {
+  registerProvider,
+  registerGenerative,
+  registerEmbedding,
+} from "../registry.js";
+import { fetchWithTimeout, type ModelInfo } from "../model-lister.js";
+
+async function fetchOllamaModels(endpointUrl: string): Promise<ModelInfo[]> {
+  const base = endpointUrl.replace(/\/$/, "");
+  const res = await fetchWithTimeout(`${base}/api/tags`);
+  if (!res.ok) return [];
+
+  const json = (await res.json()) as {
+    models?: { name: string; model?: string }[];
+  };
+
+  return (json.models ?? []).map((m) => ({
+    id: m.name,
+    name: m.name,
+  }));
+}
+
+export class OllamaProvider extends BaseLLMProvider {
+  static {
+    registerProvider({
+      id: "ollama",
+      displayName: "Ollama",
+      description:
+        "Local model runner supporting open-source LLMs via the Ollama server",
+      capabilities: { generative: true, embedding: true },
+      defaultModel: "llama3.1",
+      defaultEmbeddingModel: "nomic-embed-text",
+      defaultMaxContext: 32768,
+      fallbackPriority: 100,
+      listModels: (_apiKey, endpointUrl) =>
+        fetchOllamaModels(endpointUrl || "http://localhost:11434"),
+    });
+    registerGenerative(
+      "ollama",
+      (inst: ModelProviderInstance) =>
+        new OllamaProvider(
+          inst.endpointUrl,
+          inst.modelName,
+          inst.name,
+          inst.maxContext,
+        ),
+    );
+  }
+
+  static create(inst: ModelProviderInstance): ILLMProvider {
+    return new OllamaProvider(
+      inst.endpointUrl,
+      inst.modelName,
+      inst.name,
+      inst.maxContext,
+    );
+  }
+
+  providerName = "Ollama";
+  protected readonly model: ChatOllama;
+  protected modelNameUsed: string;
+  protected providerInstanceName?: string;
+  protected maxContextUsed?: number;
+  protected defaultMaxContext = 32768;
+
+  /**
+   * Creates an OllamaProvider.
+   *
+   * Resolution order for configuration:
+   *  1. Explicit constructor arguments
+   *  2. Active "generative" instance in ProviderManager whose providerName === "ollama"
+   *  3. Defaults (baseUrl: http://localhost:11434, model: llama3.1)
+   *
+   * No API key is required for Ollama. The `endpointUrl` in
+   * ModelProviderInstance stores the Ollama server base URL
+   * (e.g. "http://localhost:11434").
+   */
+  constructor(
+    baseUrl?: string,
+    modelName?: string,
+    providerInstanceName?: string,
+    maxContext?: number,
+  ) {
+    super();
+    let url = baseUrl;
+    let model = modelName;
+    this.providerInstanceName = providerInstanceName;
+    this.maxContextUsed = maxContext;
+
+    if (!url || !model) {
+      const active = ProviderManager.getActive("generative");
+      if (active && active.providerName === "ollama") {
+        if (!url) {
+          url = active.endpointUrl;
+        }
+        if (!model) {
+          model = active.modelName;
+        }
+        if (!this.providerInstanceName) {
+          this.providerInstanceName = active.name;
+        }
+        if (this.maxContextUsed === undefined) {
+          this.maxContextUsed = active.maxContext;
+        }
+      }
+    }
+
+    this.modelNameUsed = model || "llama3.1";
+    this.model = new ChatOllama({
+      baseUrl: url || "http://localhost:11434",
+      model: this.modelNameUsed,
+    });
+  }
+}
+
+export class OllamaEmbeddingProvider implements IEmbeddingProvider {
+  static {
+    registerEmbedding(
+      "ollama",
+      (inst: ModelProviderInstance) =>
+        new OllamaEmbeddingProvider(inst.endpointUrl, inst.modelName),
+    );
+  }
+
+  static create(inst: ModelProviderInstance): IEmbeddingProvider {
+    return new OllamaEmbeddingProvider(inst.endpointUrl, inst.modelName);
+  }
+
+  providerName = "Ollama";
+  private model: OllamaEmbeddings;
+
+  /**
+   * Creates an OllamaEmbeddingProvider.
+   *
+   * Resolution order:
+   *  1. Explicit constructor arguments
+   *  2. Active "embedding" instance in ProviderManager
+   *  3. Defaults (baseUrl: http://localhost:11434, model: nomic-embed-text)
+   *
+   * The `endpointUrl` field in ModelProviderInstance stores the base URL.
+   */
+  constructor(baseUrl?: string, modelName?: string) {
+    let url = baseUrl;
+    let model = modelName;
+
+    if (!url || !model) {
+      const active = ProviderManager.getActive("embedding");
+      if (active && active.providerName === "ollama") {
+        if (!url) {
+          url = active.endpointUrl;
+        }
+        if (!model) {
+          model = active.modelName;
+        }
+      }
+    }
+
+    this.model = new OllamaEmbeddings({
+      baseUrl: url || "http://localhost:11434",
+      model: model || "nomic-embed-text",
+    });
+  }
+
+  async embed(text: string): Promise<number[]> {
+    return this.model.embedQuery(text);
+  }
+}

packages/llm/src/providers/openai.ts

@@ -0,0 +1,139 @@
+import { ChatOpenAI, OpenAIEmbeddings } from "@langchain/openai";
+import { ILLMProvider, IEmbeddingProvider } from "../llm.js";
+import type { ModelProviderInstance } from "../llm.js";
+import { getLlmConfig } from "../config.js";
+import { ProviderManager } from "../provider-manager.js";
+import { BaseLLMProvider, resolveCredentials } from "../base-provider.js";
+import {
+  registerProvider,
+  registerGenerative,
+  registerEmbedding,
+} from "../registry.js";
+import { fetchOpenAICompatibleModels } from "../model-lister.js";
+
+export class OpenAIProvider extends BaseLLMProvider {
+  static {
+    registerProvider({
+      id: "openai",
+      displayName: "OpenAI",
+      description: "Official OpenAI integration using @langchain/openai SDK",
+      envVar: "OPENAI_API_KEY",
+      capabilities: { generative: true, embedding: true },
+      defaultModel: "gpt-4o-mini",
+      defaultEmbeddingModel: "text-embedding-3-small",
+      defaultMaxContext: 128000,
+      fallbackPriority: 1,
+      listModels: (apiKey) =>
+        fetchOpenAICompatibleModels("https://api.openai.com/v1", apiKey),
+    });
+    registerGenerative(
+      "openai",
+      (inst: ModelProviderInstance) =>
+        new OpenAIProvider(
+          inst.apiKey,
+          inst.modelName,
+          inst.name,
+          inst.maxContext,
+        ),
+    );
+  }
+
+  static create(inst: ModelProviderInstance): ILLMProvider {
+    return new OpenAIProvider(
+      inst.apiKey,
+      inst.modelName,
+      inst.name,
+      inst.maxContext,
+    );
+  }
+
+  providerName = "OpenAI";
+  protected readonly model: ChatOpenAI;
+  protected modelNameUsed: string;
+  protected providerInstanceName?: string;
+  protected maxContextUsed?: number;
+  protected defaultMaxContext = 128000;
+
+  constructor(
+    apiKey?: string,
+    modelName?: string,
+    providerInstanceName?: string,
+    maxContext?: number,
+  ) {
+    super();
+    const {
+      key,
+      model,
+      providerInstanceName: resolvedName,
+      maxContext: resolvedMax,
+    } = resolveCredentials({
+      explicitKey: apiKey,
+      explicitModel: modelName,
+      explicitProviderInstanceName: providerInstanceName,
+      explicitMaxContext: maxContext,
+      providerId: "openai",
+      envVarName: "OPENAI_API_KEY",
+      type: "generative",
+    });
+    if (!key) {
+      throw new Error(
+        "OPENAI_API_KEY is required to initialize OpenAIProvider",
+      );
+    }
+    this.providerInstanceName = resolvedName;
+    this.maxContextUsed = resolvedMax;
+    this.modelNameUsed = model || "gpt-4o-mini";
+    this.model = new ChatOpenAI({ apiKey: key, model: this.modelNameUsed });
+  }
+}
+
+export class OpenAIEmbeddingProvider implements IEmbeddingProvider {
+  static {
+    registerEmbedding(
+      "openai",
+      (inst: ModelProviderInstance) =>
+        new OpenAIEmbeddingProvider(inst.apiKey, inst.modelName),
+    );
+  }
+
+  static create(inst: ModelProviderInstance): IEmbeddingProvider {
+    return new OpenAIEmbeddingProvider(inst.apiKey, inst.modelName);
+  }
+
+  providerName = "OpenAI";
+  private model: OpenAIEmbeddings;
+
+  constructor(apiKey?: string, modelName?: string) {
+    let key = apiKey;
+    let model = modelName;
+
+    if (!key) {
+      const active = ProviderManager.getActive("embedding");
+      if (active && active.providerName === "openai") {
+        key = active.apiKey;
+        if (!model) {
+          model = active.modelName;
+        }
+      }
+    }
+
+    if (!key) {
+      key = getLlmConfig().OPENAI_API_KEY;
+    }
+
+    if (!key) {
+      throw new Error(
+        "OPENAI_API_KEY is required to initialize OpenAIEmbeddingProvider",
+      );
+    }
+
+    this.model = new OpenAIEmbeddings({
+      apiKey: key,
+      model: model || "text-embedding-3-small",
+    });
+  }
+
+  async embed(text: string): Promise<number[]> {
+    return this.model.embedQuery(text);
+  }
+}

packages/llm/src/providers/openrouter.ts

@@ -1,98 +1,107 @@
-import { z } from "zod";
 import { ChatOpenRouter } from "@langchain/openrouter";
-import { ILLMProvider, LLMRequest, LLMResponse, LLMCallRecord } from "../llm.js";
-import { llmConfig } from "../config.js";
-import { ProviderManager } from "../provider-manager.js";
+import { ILLMProvider } from "../llm.js";
+import type { ModelProviderInstance } from "../llm.js";
+import { BaseLLMProvider, resolveCredentials } from "../base-provider.js";
+import { registerProvider, registerGenerative } from "../registry.js";
+import { fetchWithTimeout, type ModelInfo } from "../model-lister.js";
 
-export class OpenRouterProvider implements ILLMProvider {
-  static readonly providerId = "openrouter";
-  static readonly displayName = "OpenRouter";
-  static readonly description = "Multi-model router supporting Anthropic, OpenAI, DeepSeek, and local models";
-  static readonly defaultModel = "google/gemini-2.5-flash";
+async function fetchOpenRouterModels(apiKey: string): Promise<ModelInfo[]> {
+  const res = await fetchWithTimeout(
+    "https://openrouter.ai/api/v1/models",
+    apiKey
+      ? {
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+            Accept: "application/json",
+          },
+        }
+      : { headers: { Accept: "application/json" } },
+  );
+  if (!res.ok) return [];
+
+  const json = (await res.json()) as {
+    data?: { id: string; name?: string; owned_by?: string }[];
+  };
+
+  return (json.data ?? []).map((m) => ({
+    id: m.id,
+    name: m.name || m.id,
+    ownedBy: m.owned_by,
+  }));
+}
+
+export class OpenRouterProvider extends BaseLLMProvider {
+  static {
+    registerProvider({
+      id: "openrouter",
+      displayName: "OpenRouter",
+      description:
+        "Multi-model router supporting Anthropic, OpenAI, DeepSeek, and local models",
+      envVar: "OPENROUTER_API_KEY",
+      capabilities: { generative: true, embedding: false },
+      defaultModel: "google/gemini-2.5-flash",
+      defaultEmbeddingModel: "openai/text-embedding-3-small",
+      defaultMaxContext: 32768,
+      fallbackPriority: 5,
+      listModels: fetchOpenRouterModels,
+    });
+    registerGenerative(
+      "openrouter",
+      (inst: ModelProviderInstance) =>
+        new OpenRouterProvider(
+          inst.apiKey,
+          inst.modelName,
+          inst.name,
+          inst.maxContext,
+        ),
+    );
+  }
+
+  static create(inst: ModelProviderInstance): ILLMProvider {
+    return new OpenRouterProvider(
+      inst.apiKey,
+      inst.modelName,
+      inst.name,
+      inst.maxContext,
+    );
+  }
 
   providerName = "OpenRouter";
-  private model: ChatOpenRouter;
-  private modelNameUsed: string;
-  private providerInstanceName?: string;
-  private maxContextUsed?: number;
-  lastCalls: LLMCallRecord[] = [];
-
-  constructor(apiKey?: string, modelName?: string, providerInstanceName?: string, maxContext?: number) {
-    let key = apiKey;
-    let model = modelName;
-    this.providerInstanceName = providerInstanceName;
-    this.maxContextUsed = maxContext;
+  protected readonly model: ChatOpenRouter;
+  protected modelNameUsed: string;
+  protected providerInstanceName?: string;
+  protected maxContextUsed?: number;
+  protected defaultMaxContext = 32768;
 
+  constructor(
+    apiKey?: string,
+    modelName?: string,
+    providerInstanceName?: string,
+    maxContext?: number,
+  ) {
+    super();
+    const {
+      key,
+      model,
+      providerInstanceName: resolvedName,
+      maxContext: resolvedMax,
+    } = resolveCredentials({
+      explicitKey: apiKey,
+      explicitModel: modelName,
+      explicitProviderInstanceName: providerInstanceName,
+      explicitMaxContext: maxContext,
+      providerId: "openrouter",
+      envVarName: "OPENROUTER_API_KEY",
+      type: "generative",
+    });
     if (!key) {
-      const active = ProviderManager.getActive("generative");
-      if (active && active.providerName === OpenRouterProvider.providerId) {
-        key = active.apiKey;
-        if (!model) {
-          model = active.modelName;
-        }
-        if (!this.providerInstanceName) {
-          this.providerInstanceName = active.name;
-        }
-        if (this.maxContextUsed === undefined) {
-          this.maxContextUsed = active.maxContext;
-        }
-      }
+      throw new Error(
+        "OPENROUTER_API_KEY is required to initialize OpenRouterProvider",
+      );
     }
-
-    if (!key) {
-      key = llmConfig.OPENROUTER_API_KEY;
-      if (!this.providerInstanceName && key) {
-        this.providerInstanceName = "Environment Variable";
-      }
-    }
-
-    if (!key) {
-      throw new Error("OPENROUTER_API_KEY is required to initialize OpenRouterProvider");
-    }
-
+    this.providerInstanceName = resolvedName;
+    this.maxContextUsed = resolvedMax;
     this.modelNameUsed = model || "google/gemini-2.5-flash";
-    this.model = new ChatOpenRouter({
-      apiKey: key,
-      model: this.modelNameUsed,
-    });
-  }
-
-  async generateStructuredResponse<T extends z.ZodTypeAny>(
-    request: LLMRequest<T>,
-  ): Promise<LLMResponse<z.infer<T>>> {
-    const structuredModel = this.model.withStructuredOutput(request.schema, { includeRaw: true });
-    const result = (await structuredModel.invoke([
-      { role: "system", content: request.systemPrompt },
-      { role: "user", content: request.userContext },
-    ])) as unknown as {
-      parsed?: z.infer<T>;
-      raw?: {
-        usage_metadata?: {
-          input_tokens?: number;
-          output_tokens?: number;
-          total_tokens?: number;
-        };
-      };
-    };
-
-    const parsed = result?.parsed;
-    const raw = result?.raw;
-
-    const usage = {
-      inputTokens: raw?.usage_metadata?.input_tokens || 0,
-      outputTokens: raw?.usage_metadata?.output_tokens || 0,
-      totalTokens: raw?.usage_metadata?.total_tokens || 0,
-      modelName: this.modelNameUsed,
-      providerInstanceName: this.providerInstanceName || "Default",
-      maxContext: this.maxContextUsed !== undefined ? this.maxContextUsed : 32768,
-    };
-
-    this.lastCalls.push({
-      systemPrompt: request.systemPrompt,
-      userContext: request.userContext,
-      usage,
-    });
-
-    return { success: true, data: parsed, usage };
+    this.model = new ChatOpenRouter({ apiKey: key, model: this.modelNameUsed });
   }
 }

packages/llm/src/registry.ts

@@ -0,0 +1,79 @@
+import type {
+  ILLMProvider,
+  IEmbeddingProvider,
+  ModelProviderInstance,
+  ModelProviderMeta,
+} from "./llm.js";
+import type { ModelInfo } from "./model-lister.js";
+
+export interface ProviderDefinition {
+  id: string;
+  displayName: string;
+  description: string;
+  envVar?: string;
+  capabilities: { generative: boolean; embedding: boolean };
+  defaultModel: string;
+  defaultEmbeddingModel?: string;
+  defaultMaxContext: number;
+  fallbackPriority: number;
+  listModels?: (apiKey: string, endpointUrl?: string) => Promise<ModelInfo[]>;
+  generativeCreate?: (inst: ModelProviderInstance) => ILLMProvider;
+  embeddingCreate?: (inst: ModelProviderInstance) => IEmbeddingProvider;
+}
+
+const _entries = new Map<string, ProviderDefinition>();
+
+type ProviderMeta = Omit<
+  ProviderDefinition,
+  "generativeCreate" | "embeddingCreate"
+>;
+
+export function registerProvider(meta: ProviderMeta) {
+  const existing = _entries.get(meta.id);
+  _entries.set(meta.id, {
+    ...existing,
+    ...meta,
+    generativeCreate: existing?.generativeCreate,
+    embeddingCreate: existing?.embeddingCreate,
+  });
+}
+
+export function registerGenerative(
+  id: string,
+  createFn: (inst: ModelProviderInstance) => ILLMProvider,
+) {
+  const existing = _entries.get(id);
+  if (existing) {
+    existing.generativeCreate = createFn;
+  } else {
+    _entries.set(id, { id, generativeCreate: createFn } as ProviderDefinition);
+  }
+}
+
+export function registerEmbedding(
+  id: string,
+  createFn: (inst: ModelProviderInstance) => IEmbeddingProvider,
+) {
+  const existing = _entries.get(id);
+  if (existing) {
+    existing.embeddingCreate = createFn;
+  } else {
+    _entries.set(id, { id, embeddingCreate: createFn } as ProviderDefinition);
+  }
+}
+
+export const ProviderRegistry = {
+  all: (): ProviderDefinition[] => [..._entries.values()],
+  get: (id: string): ProviderDefinition | undefined => _entries.get(id),
+  has: (id: string): boolean => _entries.has(id),
+} as const;
+
+export function toProviderMeta(def: ProviderDefinition): ModelProviderMeta {
+  return {
+    id: def.id,
+    displayName: def.displayName,
+    description: def.description,
+    defaultModel: def.defaultModel,
+    defaultEmbeddingModel: def.defaultEmbeddingModel || "",
+  };
+}

packages/llm/src/row-mapper.ts

@@ -0,0 +1,32 @@
+import type { ModelProviderInstance } from "./llm.js";
+
+export type DbRow = {
+  id: string;
+  name: string;
+  providerName: string;
+  apiKey: string;
+  isActive: number;
+  modelName?: string;
+  type: string;
+  maxContext?: number;
+  endpointUrl?: string;
+};
+
+export function mapRow(r: DbRow): ModelProviderInstance {
+  return {
+    id: r.id,
+    name: r.name,
+    providerName: r.providerName,
+    apiKey: r.apiKey,
+    isActive: r.isActive === 1,
+    modelName: r.modelName || undefined,
+    type: (r.type as "generative" | "embedding") || "generative",
+    maxContext:
+      r.maxContext !== undefined && r.maxContext !== null
+        ? r.maxContext
+        : r.type === "embedding"
+          ? 0
+          : 32768,
+    endpointUrl: r.endpointUrl || undefined,
+  };
+}

packages/llm/tests/cli.test.ts

@@ -0,0 +1,126 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import Database from "better-sqlite3";
+
+describe("setup-provider CLI Tool Tests", () => {
+  let tempDbPath: string;
+  let scriptPath: string;
+
+  beforeEach(() => {
+    // Generate a unique temp database path
+    tempDbPath = path.resolve(
+      process.cwd(),
+      `test-cli-${Date.now()}-${Math.random().toString(36).substring(2)}.db`,
+    );
+    scriptPath = path.resolve(
+      process.cwd(),
+      "packages/llm/dist/bin/setup-provider.js",
+    );
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(tempDbPath)) {
+      try {
+        fs.unlinkSync(tempDbPath);
+      } catch {
+        // ignore
+      }
+    }
+  });
+
+  test("prints help message when --help or -h is passed", () => {
+    const stdout = execSync(`node ${scriptPath} --help`).toString();
+    expect(stdout).toContain("Usage:");
+    expect(stdout).toContain("Options:");
+    expect(stdout).toContain("Registered Providers:");
+  });
+
+  test("creates a provider instance successfully via CLI flags", () => {
+    const cmd = `node ${scriptPath} --provider google-genai --key mock-key-abc --name "Test Gemini" --model "gemini-2.5-flash"`;
+    const stdout = execSync(cmd, {
+      env: { ...process.env, OMNIA_DB_PATH: tempDbPath },
+    }).toString();
+
+    expect(stdout).toContain("Successfully created provider instance:");
+    expect(stdout).toContain("Test Gemini");
+    expect(stdout).toContain("google-genai");
+    expect(stdout).toContain("mock-key-abc");
+
+    // Read the SQLite db directly to verify
+    const db = new Database(tempDbPath);
+    const rows = db.prepare("SELECT * FROM provider_instances").all() as {
+      name: string;
+      providerName: string;
+      apiKey: string;
+      modelName: string;
+      isActive: number;
+    }[];
+    expect(rows.length).toBe(1);
+    expect(rows[0].name).toBe("Test Gemini");
+    expect(rows[0].providerName).toBe("google-genai");
+    expect(rows[0].apiKey).toBe("mock-key-abc");
+    expect(rows[0].modelName).toBe("gemini-2.5-flash");
+    expect(rows[0].isActive).toBe(1);
+    db.close();
+  });
+
+  test("fails when required key is missing and env var is not set", () => {
+    let error: { status?: number; stderr?: Buffer } | undefined;
+    try {
+      execSync(`node ${scriptPath} --provider google-genai`, {
+        env: { ...process.env, OMNIA_DB_PATH: tempDbPath, GOOGLE_API_KEY: "" },
+        stdio: "pipe",
+      });
+    } catch (e) {
+      error = e as { status?: number; stderr?: Buffer };
+    }
+    expect(error).toBeDefined();
+    expect(error?.status).toBe(1);
+    expect(error?.stderr?.toString()).toContain("Error: API Key is required");
+  });
+
+  test("seeds from environment variables when using --all", () => {
+    const cmd = `node ${scriptPath} --all`;
+    const stdout = execSync(cmd, {
+      env: {
+        ...process.env,
+        OMNIA_DB_PATH: tempDbPath,
+        GOOGLE_API_KEY: "mock-google-key-all",
+        OPENAI_API_KEY: "",
+        ANTHROPIC_API_KEY: "",
+        GROQ_API_KEY: "",
+        DEEPSEEK_API_KEY: "",
+        OPENROUTER_API_KEY: "",
+      },
+    }).toString();
+
+    expect(stdout).toContain(
+      "Created generative instance: Google Gemini (CLI)",
+    );
+    expect(stdout).toContain(
+      "Created embedding instance: Google Gemini Embed (CLI)",
+    );
+
+    const db = new Database(tempDbPath);
+    const rows = db.prepare("SELECT * FROM provider_instances").all() as {
+      type: string;
+      apiKey: string;
+      modelName: string;
+    }[];
+    // Should have both generative and embedding instances
+    expect(rows.length).toBe(2);
+    const gen = rows.find((r) => r.type === "generative");
+    const embed = rows.find((r) => r.type === "embedding");
+
+    expect(gen).toBeDefined();
+    expect(gen?.apiKey).toBe("mock-google-key-all");
+    expect(gen?.modelName).toBe("gemini-2.5-flash");
+
+    expect(embed).toBeDefined();
+    expect(embed?.apiKey).toBe("mock-google-key-all");
+    expect(embed?.modelName).toBe("gemini-embedding-001");
+    db.close();
+  });
+});

packages/llm/tests/deepseek.test.ts

@@ -0,0 +1,128 @@
+import { describe, test, expect, vi } from "vitest";
+import { z } from "zod";
+
+const mockConfig: Record<string, string | undefined> = {};
+
+vi.mock("../src/config.js", () => ({
+  getLlmConfig: () => mockConfig,
+  resetLlmConfig: () => {
+    for (const key of Object.keys(mockConfig)) {
+      delete mockConfig[key];
+    }
+  },
+}));
+
+const { getActiveMock } = vi.hoisted(() => ({
+  getActiveMock: vi.fn().mockReturnValue(null),
+}));
+
+vi.mock("../src/provider-manager.js", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("../src/provider-manager.js")>();
+  return {
+    ...actual,
+    ProviderManager: {
+      ...actual.ProviderManager,
+      getActive: getActiveMock,
+    },
+  };
+});
+
+import { DeepSeekProvider } from "../src/providers/deepseek.js";
+
+// Mock the ChatDeepSeek class
+vi.mock("@langchain/deepseek", () => {
+  return {
+    ChatDeepSeek: class {
+      config: unknown;
+      constructor(config: unknown) {
+        this.config = config;
+      }
+      withStructuredOutput = vi.fn().mockImplementation(() => {
+        return {
+          invoke: vi.fn().mockImplementation(async () => {
+            return {
+              parsed: {
+                name: "mocked response",
+                success: true,
+              },
+              raw: {
+                usage_metadata: {
+                  input_tokens: 10,
+                  output_tokens: 5,
+                  total_tokens: 15,
+                },
+              },
+            };
+          }),
+        };
+      });
+    },
+  };
+});
+
+describe("DeepSeekProvider Unit Tests (Tier 1)", () => {
+  test("initializes successfully with a provided apiKey", () => {
+    const provider = new DeepSeekProvider("dummy-key");
+    expect(provider.providerName).toBe("DeepSeek");
+  });
+
+  test("initializes successfully with apiKey from config", () => {
+    const originalKey = process.env.DEEPSEEK_API_KEY;
+    process.env.DEEPSEEK_API_KEY = "env-dummy-key";
+    mockConfig.DEEPSEEK_API_KEY = "env-dummy-key";
+
+    try {
+      const provider = new DeepSeekProvider();
+      expect(provider.providerName).toBe("DeepSeek");
+    } finally {
+      process.env.DEEPSEEK_API_KEY = originalKey;
+      delete mockConfig.DEEPSEEK_API_KEY;
+    }
+  });
+
+  test("throws error if no API key is provided or in config", () => {
+    const originalKey = process.env.DEEPSEEK_API_KEY;
+    process.env.DEEPSEEK_API_KEY = undefined;
+    mockConfig.DEEPSEEK_API_KEY = undefined;
+
+    try {
+      expect(() => new DeepSeekProvider()).toThrow(
+        "DEEPSEEK_API_KEY is required to initialize DeepSeekProvider",
+      );
+    } finally {
+      process.env.DEEPSEEK_API_KEY = originalKey;
+    }
+  });
+
+  test("generateStructuredResponse invokes the model with structured output, records usage and updates lastCalls", async () => {
+    const provider = new DeepSeekProvider("dummy-key");
+    const TestSchema = z.object({
+      name: z.string(),
+      success: z.boolean(),
+    });
+
+    const response = await provider.generateStructuredResponse({
+      systemPrompt: "system prompt",
+      userContext: "user context",
+      schema: TestSchema,
+    });
+
+    expect(response.success).toBe(true);
+    expect(response.data).toEqual({
+      name: "mocked response",
+      success: true,
+    });
+
+    expect(response.usage).toEqual({
+      inputTokens: 10,
+      outputTokens: 5,
+      totalTokens: 15,
+      modelName: "deepseek-chat",
+      providerInstanceName: "Default",
+      maxContext: 64000,
+    });
+
+    expect(provider.lastCalls.length).toBe(1);
+  });
+});

packages/llm/tests/groq.test.ts

@@ -0,0 +1,128 @@
+import { describe, test, expect, vi } from "vitest";
+import { z } from "zod";
+
+const mockConfig: Record<string, string | undefined> = {};
+
+vi.mock("../src/config.js", () => ({
+  getLlmConfig: () => mockConfig,
+  resetLlmConfig: () => {
+    for (const key of Object.keys(mockConfig)) {
+      delete mockConfig[key];
+    }
+  },
+}));
+
+const { getActiveMock } = vi.hoisted(() => ({
+  getActiveMock: vi.fn().mockReturnValue(null),
+}));
+
+vi.mock("../src/provider-manager.js", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("../src/provider-manager.js")>();
+  return {
+    ...actual,
+    ProviderManager: {
+      ...actual.ProviderManager,
+      getActive: getActiveMock,
+    },
+  };
+});
+
+import { GroqProvider } from "../src/providers/groq.js";
+
+// Mock the ChatGroq class
+vi.mock("@langchain/groq", () => {
+  return {
+    ChatGroq: class {
+      config: unknown;
+      constructor(config: unknown) {
+        this.config = config;
+      }
+      withStructuredOutput = vi.fn().mockImplementation(() => {
+        return {
+          invoke: vi.fn().mockImplementation(async () => {
+            return {
+              parsed: {
+                name: "mocked response",
+                success: true,
+              },
+              raw: {
+                usage_metadata: {
+                  input_tokens: 10,
+                  output_tokens: 5,
+                  total_tokens: 15,
+                },
+              },
+            };
+          }),
+        };
+      });
+    },
+  };
+});
+
+describe("GroqProvider Unit Tests (Tier 1)", () => {
+  test("initializes successfully with a provided apiKey", () => {
+    const provider = new GroqProvider("dummy-key");
+    expect(provider.providerName).toBe("Groq");
+  });
+
+  test("initializes successfully with apiKey from config", () => {
+    const originalKey = process.env.GROQ_API_KEY;
+    process.env.GROQ_API_KEY = "env-dummy-key";
+    mockConfig.GROQ_API_KEY = "env-dummy-key";
+
+    try {
+      const provider = new GroqProvider();
+      expect(provider.providerName).toBe("Groq");
+    } finally {
+      process.env.GROQ_API_KEY = originalKey;
+      delete mockConfig.GROQ_API_KEY;
+    }
+  });
+
+  test("throws error if no API key is provided or in config", () => {
+    const originalKey = process.env.GROQ_API_KEY;
+    process.env.GROQ_API_KEY = undefined;
+    mockConfig.GROQ_API_KEY = undefined;
+
+    try {
+      expect(() => new GroqProvider()).toThrow(
+        "GROQ_API_KEY is required to initialize GroqProvider",
+      );
+    } finally {
+      process.env.GROQ_API_KEY = originalKey;
+    }
+  });
+
+  test("generateStructuredResponse invokes the model with structured output, records usage and updates lastCalls", async () => {
+    const provider = new GroqProvider("dummy-key");
+    const TestSchema = z.object({
+      name: z.string(),
+      success: z.boolean(),
+    });
+
+    const response = await provider.generateStructuredResponse({
+      systemPrompt: "system prompt",
+      userContext: "user context",
+      schema: TestSchema,
+    });
+
+    expect(response.success).toBe(true);
+    expect(response.data).toEqual({
+      name: "mocked response",
+      success: true,
+    });
+
+    expect(response.usage).toEqual({
+      inputTokens: 10,
+      outputTokens: 5,
+      totalTokens: 15,
+      modelName: "llama-3.3-70b-versatile",
+      providerInstanceName: "Default",
+      maxContext: 8192,
+    });
+
+    expect(provider.lastCalls.length).toBe(1);
+  });
+});

packages/llm/tests/mock.test.ts

@@ -72,7 +72,7 @@ describe("MockEmbeddingProvider Unit Tests (Tier 1)", () => {
     expect(vec1.length).toBe(768);
     expect(vec2.length).toBe(768);
     expect(vec1).toEqual(vec2); // Deterministic
-    
+
     // Ensure values are numbers between -1.0 and 1.0 (since they are generated with Math.sin)
     expect(typeof vec1[0]).toBe("number");
     expect(vec1[0]).toBeGreaterThanOrEqual(-1.0);

packages/llm/tests/model-lister.test.ts

@@ -0,0 +1,120 @@
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import { ModelLister } from "@omnia/llm";
+
+describe("ModelLister Unit Tests (Tier 1)", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", vi.fn());
+    ModelLister.clearCache();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test("returns mock provider list instantly without fetch", async () => {
+    const models = await ModelLister.listModels("mock", "none");
+    expect(models).toEqual([{ id: "mock", name: "Mock Model" }]);
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  test("fetches and caches OpenAI-compatible models", async () => {
+    const mockResponse = {
+      data: [
+        { id: "gpt-4o", owned_by: "openai" },
+        { id: "gpt-4o-mini", owned_by: "openai" },
+      ],
+    };
+
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => mockResponse,
+    });
+    vi.stubGlobal("fetch", mockFetch);
+
+    // First call: Should fetch
+    const models = await ModelLister.listModels("openai", "test-key");
+    expect(models).toEqual([
+      { id: "gpt-4o", name: "gpt-4o", ownedBy: "openai" },
+      { id: "gpt-4o-mini", name: "gpt-4o-mini", ownedBy: "openai" },
+    ]);
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    expect(mockFetch).toHaveBeenCalledWith(
+      "https://api.openai.com/v1/models",
+      expect.objectContaining({
+        headers: {
+          Authorization: "Bearer test-key",
+          Accept: "application/json",
+        },
+      }),
+    );
+
+    // Second call: Should read from cache
+    const cachedModels = await ModelLister.listModels("openai", "test-key");
+    expect(cachedModels).toEqual(models);
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+  });
+
+  test("respects cache invalidation", async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ data: [{ id: "model-1" }] }),
+    });
+    vi.stubGlobal("fetch", mockFetch);
+
+    await ModelLister.listModels("openai", "test-key");
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+
+    // Invalidate
+    ModelLister.invalidateCache("openai", "test-key");
+
+    // Second call: Should fetch again
+    await ModelLister.listModels("openai", "test-key");
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+
+  test("gracefully returns empty array on fetch failure", async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 500,
+    });
+    vi.stubGlobal("fetch", mockFetch);
+
+    const models = await ModelLister.listModels("openai", "bad-key");
+    expect(models).toEqual([]);
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+  });
+
+  test("handles Gemini pagination correctly", async () => {
+    const mockFetch = vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          models: [
+            {
+              name: "models/gemini-2.5-flash",
+              displayName: "Gemini 2.5 Flash",
+            },
+          ],
+          nextPageToken: "token-1",
+        }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          models: [
+            { name: "models/gemini-2.5-pro", displayName: "Gemini 2.5 Pro" },
+          ],
+        }),
+      });
+
+    vi.stubGlobal("fetch", mockFetch);
+
+    const models = await ModelLister.listModels("google-genai", "gemini-key");
+    expect(models).toEqual([
+      { id: "gemini-2.5-flash", name: "Gemini 2.5 Flash" },
+      { id: "gemini-2.5-pro", name: "Gemini 2.5 Pro" },
+    ]);
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+});

packages/llm/tests/openai.test.ts

@@ -0,0 +1,167 @@
+import { describe, test, expect, vi } from "vitest";
+import { z } from "zod";
+
+const mockConfig: Record<string, string | undefined> = {};
+
+vi.mock("../src/config.js", () => ({
+  getLlmConfig: () => mockConfig,
+  resetLlmConfig: () => {
+    for (const key of Object.keys(mockConfig)) {
+      delete mockConfig[key];
+    }
+  },
+}));
+
+const { getActiveMock } = vi.hoisted(() => ({
+  getActiveMock: vi.fn().mockReturnValue(null),
+}));
+
+vi.mock("../src/provider-manager.js", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("../src/provider-manager.js")>();
+  return {
+    ...actual,
+    ProviderManager: {
+      ...actual.ProviderManager,
+      getActive: getActiveMock,
+    },
+  };
+});
+
+import {
+  OpenAIProvider,
+  OpenAIEmbeddingProvider,
+} from "../src/providers/openai.js";
+
+// Mock the ChatOpenAI and OpenAIEmbeddings classes
+vi.mock("@langchain/openai", () => {
+  return {
+    ChatOpenAI: class {
+      config: unknown;
+      constructor(config: unknown) {
+        this.config = config;
+      }
+      withStructuredOutput = vi.fn().mockImplementation(() => {
+        return {
+          invoke: vi.fn().mockImplementation(async () => {
+            return {
+              parsed: {
+                name: "mocked response",
+                success: true,
+              },
+              raw: {
+                usage_metadata: {
+                  input_tokens: 10,
+                  output_tokens: 5,
+                  total_tokens: 15,
+                },
+              },
+            };
+          }),
+        };
+      });
+    },
+    OpenAIEmbeddings: class {
+      config: unknown;
+      constructor(config: unknown) {
+        this.config = config;
+      }
+      embedQuery = vi.fn().mockImplementation(async (text: string) => {
+        return [0.1, 0.2, 0.3];
+      });
+    },
+  };
+});
+
+describe("OpenAIProvider Unit Tests (Tier 1)", () => {
+  test("initializes successfully with a provided apiKey", () => {
+    const provider = new OpenAIProvider("dummy-key");
+    expect(provider.providerName).toBe("OpenAI");
+  });
+
+  test("initializes successfully with apiKey from config", () => {
+    const originalKey = process.env.OPENAI_API_KEY;
+    process.env.OPENAI_API_KEY = "env-dummy-key";
+    mockConfig.OPENAI_API_KEY = "env-dummy-key";
+
+    try {
+      const provider = new OpenAIProvider();
+      expect(provider.providerName).toBe("OpenAI");
+    } finally {
+      process.env.OPENAI_API_KEY = originalKey;
+      delete mockConfig.OPENAI_API_KEY;
+    }
+  });
+
+  test("throws error if no API key is provided or in config", () => {
+    const originalKey = process.env.OPENAI_API_KEY;
+    process.env.OPENAI_API_KEY = undefined;
+    mockConfig.OPENAI_API_KEY = undefined;
+
+    try {
+      expect(() => new OpenAIProvider()).toThrow(
+        "OPENAI_API_KEY is required to initialize OpenAIProvider",
+      );
+    } finally {
+      process.env.OPENAI_API_KEY = originalKey;
+    }
+  });
+
+  test("generateStructuredResponse invokes the model with structured output, records usage and updates lastCalls", async () => {
+    const provider = new OpenAIProvider("dummy-key");
+    const TestSchema = z.object({
+      name: z.string(),
+      success: z.boolean(),
+    });
+
+    const response = await provider.generateStructuredResponse({
+      systemPrompt: "system prompt",
+      userContext: "user context",
+      schema: TestSchema,
+    });
+
+    expect(response.success).toBe(true);
+    expect(response.data).toEqual({
+      name: "mocked response",
+      success: true,
+    });
+
+    expect(response.usage).toEqual({
+      inputTokens: 10,
+      outputTokens: 5,
+      totalTokens: 15,
+      modelName: "gpt-4o-mini",
+      providerInstanceName: "Default",
+      maxContext: 128000,
+    });
+
+    expect(provider.lastCalls.length).toBe(1);
+  });
+});
+
+describe("OpenAIEmbeddingProvider Unit Tests (Tier 1)", () => {
+  test("initializes successfully with a provided apiKey", () => {
+    const provider = new OpenAIEmbeddingProvider("dummy-key");
+    expect(provider.providerName).toBe("OpenAI");
+  });
+
+  test("initializes successfully with apiKey from config", () => {
+    const originalKey = process.env.OPENAI_API_KEY;
+    process.env.OPENAI_API_KEY = "env-dummy-key";
+    mockConfig.OPENAI_API_KEY = "env-dummy-key";
+
+    try {
+      const provider = new OpenAIEmbeddingProvider();
+      expect(provider.providerName).toBe("OpenAI");
+    } finally {
+      process.env.OPENAI_API_KEY = originalKey;
+      delete mockConfig.OPENAI_API_KEY;
+    }
+  });
+
+  test("embed returns dummy array successfully", async () => {
+    const provider = new OpenAIEmbeddingProvider("dummy-key");
+    const result = await provider.embed("hello");
+    expect(result).toEqual([0.1, 0.2, 0.3]);
+  });
+});

packages/llm/tests/openrouter.test.ts

@@ -1,7 +1,34 @@
 import { describe, test, expect, vi } from "vitest";
 import { z } from "zod";
+
+const mockConfig: Record<string, string | undefined> = {};
+
+vi.mock("../src/config.js", () => ({
+  getLlmConfig: () => mockConfig,
+  resetLlmConfig: () => {
+    for (const key of Object.keys(mockConfig)) {
+      delete mockConfig[key];
+    }
+  },
+}));
+
+const { getActiveMock } = vi.hoisted(() => ({
+  getActiveMock: vi.fn().mockReturnValue(null),
+}));
+
+vi.mock("../src/provider-manager.js", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("../src/provider-manager.js")>();
+  return {
+    ...actual,
+    ProviderManager: {
+      ...actual.ProviderManager,
+      getActive: getActiveMock,
+    },
+  };
+});
+
 import { OpenRouterProvider } from "../src/providers/openrouter.js";
-import { llmConfig } from "../src/config.js";
 
 // Mock the ChatOpenRouter class
 vi.mock("@langchain/openrouter", () => {
@@ -14,7 +41,6 @@ vi.mock("@langchain/openrouter", () => {
       withStructuredOutput = vi.fn().mockImplementation(() => {
         return {
           invoke: vi.fn().mockImplementation(async () => {
-            // Return a mock output that matches the includeRaw: true structure
             return {
               parsed: {
                 name: "mocked response",
@@ -42,29 +68,30 @@ describe("OpenRouterProvider Unit Tests (Tier 1)", () => {
   });
 
   test("initializes successfully with apiKey from config", () => {
-    // Save current config
-    const originalKey = llmConfig.OPENROUTER_API_KEY;
-    llmConfig.OPENROUTER_API_KEY = "env-dummy-key";
-    
+    const originalKey = process.env.OPENROUTER_API_KEY;
+    process.env.OPENROUTER_API_KEY = "env-dummy-key";
+    mockConfig.OPENROUTER_API_KEY = "env-dummy-key";
+
     try {
       const provider = new OpenRouterProvider();
       expect(provider.providerName).toBe("OpenRouter");
     } finally {
-      llmConfig.OPENROUTER_API_KEY = originalKey;
+      process.env.OPENROUTER_API_KEY = originalKey;
+      delete mockConfig.OPENROUTER_API_KEY;
     }
   });
 
   test("throws error if no API key is provided or in config", () => {
-    // Save current config
-    const originalKey = llmConfig.OPENROUTER_API_KEY;
-    llmConfig.OPENROUTER_API_KEY = undefined;
+    const originalKey = process.env.OPENROUTER_API_KEY;
+    process.env.OPENROUTER_API_KEY = undefined;
+    mockConfig.OPENROUTER_API_KEY = undefined;
 
     try {
       expect(() => new OpenRouterProvider()).toThrow(
-        "OPENROUTER_API_KEY is required to initialize OpenRouterProvider"
+        "OPENROUTER_API_KEY is required to initialize OpenRouterProvider",
       );
     } finally {
-      llmConfig.OPENROUTER_API_KEY = originalKey;
+      process.env.OPENROUTER_API_KEY = originalKey;
     }
   });
 

packages/llm/tests/provider-manager.test.ts

@@ -1,23 +1,33 @@
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import fs from "fs";
 import path from "path";
-import { ProviderManager, setDbPathOverride, resetHasBootstrapped } from "../src/index.js";
+import { ProviderManager, setDbPathOverride } from "../src/index.js";
 
 describe("ProviderManager Bootstrapping & CRUD Unit Tests", () => {
   let tempDbPath: string;
-  let originalGoogle: string | undefined;
-  let originalOpenRouter: string | undefined;
+  let savedEnv: Record<string, string | undefined>;
 
   beforeEach(() => {
-    originalGoogle = process.env.GOOGLE_API_KEY;
-    originalOpenRouter = process.env.OPENROUTER_API_KEY;
+    savedEnv = {
+      GOOGLE_API_KEY: process.env.GOOGLE_API_KEY,
+      OPENROUTER_API_KEY: process.env.OPENROUTER_API_KEY,
+      ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
+      OPENAI_API_KEY: process.env.OPENAI_API_KEY,
+      GROQ_API_KEY: process.env.GROQ_API_KEY,
+      DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY,
+    };
     delete process.env.GOOGLE_API_KEY;
     delete process.env.OPENROUTER_API_KEY;
-
-    resetHasBootstrapped();
+    delete process.env.ANTHROPIC_API_KEY;
+    delete process.env.OPENAI_API_KEY;
+    delete process.env.GROQ_API_KEY;
+    delete process.env.DEEPSEEK_API_KEY;
 
     // Generate a unique temp database path for this test run
-    tempDbPath = path.resolve(process.cwd(), `test-settings-${Date.now()}-${Math.random().toString(36).substring(2)}.db`);
+    tempDbPath = path.resolve(
+      process.cwd(),
+      `test-settings-${Date.now()}-${Math.random().toString(36).substring(2)}.db`,
+    );
     setDbPathOverride(tempDbPath);
   });
 
@@ -30,57 +40,198 @@ describe("ProviderManager Bootstrapping & CRUD Unit Tests", () => {
         // ignore
       }
     }
-    if (originalGoogle !== undefined) {
-      process.env.GOOGLE_API_KEY = originalGoogle;
-    } else {
-      delete process.env.GOOGLE_API_KEY;
-    }
-    if (originalOpenRouter !== undefined) {
-      process.env.OPENROUTER_API_KEY = originalOpenRouter;
-    } else {
-      delete process.env.OPENROUTER_API_KEY;
+    for (const [key, value] of Object.entries(savedEnv)) {
+      if (value !== undefined) {
+        process.env[key] = value;
+      } else {
+        delete process.env[key];
+      }
     }
   });
 
-  test("auto-bootstraps Gemini and OpenRouter when database is empty and environment variables are present", () => {
-    process.env.GOOGLE_API_KEY = "mock-google-key-123";
-    process.env.OPENROUTER_API_KEY = "mock-openrouter-key-456";
-
+  test("returns empty list when database is empty and no auto-bootstraps", () => {
+    process.env.GOOGLE_API_KEY = "mock-google-key";
     const list = ProviderManager.list();
-    expect(list.length).toBe(3);
-
-    const gemini = list.find((p) => p.providerName === "google-genai");
-    expect(gemini).toBeDefined();
-    expect(gemini?.name).toBe("Gemini (Env)");
-    expect(gemini?.apiKey).toBe("mock-google-key-123");
-    expect(gemini?.modelName).toBe("gemini-2.5-flash");
-    expect(gemini?.isActive).toBe(true); // first inserted is active
-
-    const openrouter = list.find((p) => p.providerName === "openrouter");
-    expect(openrouter).toBeDefined();
-    expect(openrouter?.name).toBe("OpenRouter (Env)");
-    expect(openrouter?.apiKey).toBe("mock-openrouter-key-456");
-    expect(openrouter?.modelName).toBe("google/gemini-2.5-flash");
-    expect(openrouter?.isActive).toBe(false); // second inserted is inactive
+    expect(list.length).toBe(0);
   });
 
-  test("treats bootstrapped instances as normal provider instances (editable and deletable)", () => {
-    process.env.GOOGLE_API_KEY = "mock-google-key-123";
+  test("getActive returns null when no providers exist and no env vars", () => {
+    const active = ProviderManager.getActive("generative");
+    expect(active).toBeNull();
+    const activeEmbed = ProviderManager.getActive("embedding");
+    expect(activeEmbed).toBeNull();
+  });
+
+  test("getActive returns null when DB is empty", () => {
+    process.env.GOOGLE_API_KEY = "mock-google-key-123";
+    const active = ProviderManager.getActive("generative");
+    expect(active).toBeNull();
+  });
+
+  test("getActive returns first instance of type when none is active", () => {
+    // Manually create instances without any env var bootstrap
+    const inst1 = ProviderManager.create("Test Gemini", "google-genai", "key1");
+    const inst2 = ProviderManager.create(
+      "Test OpenAI",
+      "openai",
+      "key2",
+      "gpt-4o",
+      "generative",
+      128000,
+    );
+    expect(inst1.isActive).toBe(true); // first created auto-activates
+    expect(inst2.isActive).toBe(false);
+
+    // Deactivate both
+    ProviderManager.setActive("__nonexistent__"); // no-op for nonexistent
+
+    // Deactivate inst1 by setting another as active, then delete that
+    ProviderManager.setActive(inst2.id);
+    expect(
+      ProviderManager.list().find((p) => p.id === inst2.id)?.isActive,
+    ).toBe(true);
+    expect(
+      ProviderManager.list().find((p) => p.id === inst1.id)?.isActive,
+    ).toBe(false);
+
+    // Delete the active one → auto-promotes inst1
+    ProviderManager.delete(inst2.id);
+    const promoted = ProviderManager.list().find((p) => p.id === inst1.id);
+    expect(promoted?.isActive).toBe(true);
+  });
+
+  test("setActive correctly deactivates siblings and activates target", () => {
+    const inst1 = ProviderManager.create(
+      "First Gemini",
+      "google-genai",
+      "key1",
+      undefined,
+      "generative",
+    );
+    const inst2 = ProviderManager.create(
+      "Second Gemini",
+      "google-genai",
+      "key2",
+      undefined,
+      "generative",
+    );
+
+    expect(inst1.isActive).toBe(true);
+    expect(inst2.isActive).toBe(false);
+
+    ProviderManager.setActive(inst2.id);
 
-    // Trigger bootstrap
     const list = ProviderManager.list();
-    expect(list.length).toBe(2);
-    const bootstrapped = list.find((p) => p.name === "Gemini (Env)");
-    expect(bootstrapped).toBeDefined();
-    if (!bootstrapped) return;
-    expect(bootstrapped.isActive).toBe(true);
+    const updated1 = list.find((p) => p.id === inst1.id);
+    const updated2 = list.find((p) => p.id === inst2.id);
+    expect(updated1?.isActive).toBe(false);
+    expect(updated2?.isActive).toBe(true);
+  });
+
+  test("getMappings returns empty object initially, setMapping persists mappings", () => {
+    const mappings = ProviderManager.getMappings();
+    expect(mappings).toEqual({});
+
+    const inst = ProviderManager.create(
+      "Test Provider",
+      "google-genai",
+      "key1",
+    );
+
+    ProviderManager.setMapping("actor-prose", inst.id);
+    ProviderManager.setMapping("embeddings", inst.id);
+
+    const updated = ProviderManager.getMappings();
+    expect(updated["actor-prose"]).toBe(inst.id);
+    expect(updated["embeddings"]).toBe(inst.id);
+  });
+
+  test("setMapping with empty providerInstanceId deletes the mapping", () => {
+    const inst = ProviderManager.create(
+      "Test Provider",
+      "google-genai",
+      "key1",
+    );
+
+    ProviderManager.setMapping("test-task", inst.id);
+    expect(ProviderManager.getMappings()["test-task"]).toBe(inst.id);
+
+    ProviderManager.setMapping("test-task", "");
+    expect(ProviderManager.getMappings()["test-task"]).toBeUndefined();
+  });
+
+  test("create returns instance with correct fields and endpointUrl support", () => {
+    const inst = ProviderManager.create(
+      "Ollama Local",
+      "ollama",
+      "",
+      "llama3.1",
+      "generative",
+      32768,
+      "http://localhost:11434",
+    );
+
+    expect(inst.id).toMatch(/^provider-/);
+    expect(inst.name).toBe("Ollama Local");
+    expect(inst.providerName).toBe("ollama");
+    expect(inst.modelName).toBe("llama3.1");
+    expect(inst.endpointUrl).toBe("http://localhost:11434");
+  });
+
+  test("update preserves apiKey when not provided", () => {
+    const inst = ProviderManager.create(
+      "Original",
+      "openai",
+      "original-key",
+      "gpt-4o",
+      "generative",
+      128000,
+    );
+
+    ProviderManager.update(
+      inst.id,
+      "Renamed",
+      "openai",
+      undefined, // no apiKey → preserve existing
+      "gpt-4o-mini",
+      "generative",
+      64000,
+    );
+
+    const updated = ProviderManager.list().find((p) => p.id === inst.id);
+    expect(updated?.name).toBe("Renamed");
+    expect(updated?.apiKey).toBe("original-key"); // preserved
+    expect(updated?.modelName).toBe("gpt-4o-mini");
+    expect(updated?.maxContext).toBe(64000);
+  });
+  test("treats created instances as normal provider instances (editable and deletable)", () => {
+    const inst = ProviderManager.create(
+      "Google Gemini (Env)",
+      "google-genai",
+      "mock-google-key-123",
+      "gemini-2.5-flash",
+      "generative",
+    );
+
+    const list = ProviderManager.list();
+    expect(list.length).toBe(1);
+    const created = list.find((p) => p.id === inst.id);
+    expect(created).toBeDefined();
+    if (!created) return;
+    expect(created.isActive).toBe(true);
 
     // Edit name and key
-    ProviderManager.update(bootstrapped.id, "My Gemini Key", "google-genai", "new-secret-key", "gemini-2.5-pro");
-    
+    ProviderManager.update(
+      created.id,
+      "My Gemini Key",
+      "google-genai",
+      "new-secret-key",
+      "gemini-2.5-pro",
+    );
+
     const listAfterUpdate = ProviderManager.list();
-    expect(listAfterUpdate.length).toBe(2);
-    const updated = listAfterUpdate.find((p) => p.id === bootstrapped.id);
+    expect(listAfterUpdate.length).toBe(1);
+    const updated = listAfterUpdate.find((p) => p.id === created.id);
     expect(updated).toBeDefined();
     if (!updated) return;
     expect(updated.name).toBe("My Gemini Key");
@@ -88,8 +239,8 @@ describe("ProviderManager Bootstrapping & CRUD Unit Tests", () => {
     expect(updated.modelName).toBe("gemini-2.5-pro");
 
     // Delete instance
-    ProviderManager.delete(bootstrapped.id);
+    ProviderManager.delete(created.id);
     const listAfterDelete = ProviderManager.list();
-    expect(listAfterDelete.length).toBe(1);
+    expect(listAfterDelete.length).toBe(0);
   });
 });

packages/memory/src/buffer.ts

@@ -26,7 +26,11 @@ export function serializeSubjectiveBufferEntry(
   const isSelf = viewer.id === entry.intent.actorId;
 
   if (isSelf) {
-    let details = (entry.intent.selfDescription || entry.intent.description || entry.intent.originalText).trim();
+    let details = (
+      entry.intent.selfDescription ||
+      entry.intent.description ||
+      entry.intent.originalText
+    ).trim();
     if (details.length > 0) {
       details = details.charAt(0).toUpperCase() + details.slice(1);
     }
@@ -69,7 +73,9 @@ export class BufferRepository {
     `);
 
     try {
-      this.db.exec(`ALTER TABLE buffer_entries ADD COLUMN pinned INTEGER DEFAULT 0;`);
+      this.db.exec(
+        `ALTER TABLE buffer_entries ADD COLUMN pinned INTEGER DEFAULT 0;`,
+      );
     } catch {
       // ignore
     }

packages/memory/src/handoff.ts

@@ -1,6 +1,10 @@
 import { z } from "zod";
 import { Entity, naturalizeTime } from "@omnia/core";
-import { BufferEntry, serializeSubjectiveBufferEntry, BufferRepository } from "./buffer.js";
+import {
+  BufferEntry,
+  serializeSubjectiveBufferEntry,
+  BufferRepository,
+} from "./buffer.js";
 import { LedgerEntry, LedgerRepository } from "./ledger.js";
 import { ILLMProvider, IEmbeddingProvider } from "@omnia/llm";
 
@@ -56,12 +60,18 @@ function checkSceneExit(entity: Entity, bufferEntries: BufferEntry[]): boolean {
 
   // Find the location of the most recent buffer entries
   const lastEntry = bufferEntries[bufferEntries.length - 1];
-  if (lastEntry.locationId && entity.locationId && lastEntry.locationId !== entity.locationId) {
+  if (
+    lastEntry.locationId &&
+    entity.locationId &&
+    lastEntry.locationId !== entity.locationId
+  ) {
     return true;
   }
 
   // Also check if there are entries from different locations in the buffer
-  const locations = new Set(bufferEntries.map(e => e.locationId).filter(loc => loc !== null));
+  const locations = new Set(
+    bufferEntries.map((e) => e.locationId).filter((loc) => loc !== null),
+  );
   if (locations.size > 1) {
     return true;
   }
@@ -75,17 +85,25 @@ function checkIdleDecay(bufferEntries: BufferEntry[]): boolean {
 
   // Check the last N entries
   const lastN = bufferEntries.slice(-N);
-  return lastN.every(e => e.intent.type === "monologue");
+  return lastN.every((e) => e.intent.type === "monologue");
 }
 
 function checkAttributeTrigger(entity: Entity): boolean {
   const consciousness = entity.attributes.get("consciousness");
-  if (consciousness && consciousness.getValue().toLowerCase() === "unconscious") {
+  if (
+    consciousness &&
+    consciousness.getValue().toLowerCase() === "unconscious"
+  ) {
     return true;
   }
 
   const status = entity.attributes.get("status");
-  if (status && ["unconscious", "asleep", "dead", "inactive"].includes(status.getValue().toLowerCase())) {
+  if (
+    status &&
+    ["unconscious", "asleep", "dead", "inactive"].includes(
+      status.getValue().toLowerCase(),
+    )
+  ) {
     return true;
   }
 
@@ -108,7 +126,7 @@ export function checkHandoffTrigger(
   // Involuntary triggers first (hard)
   if (maxContext > 0) {
     const memoryLength = getMemorySectionLength(entity, bufferEntries, now);
-    const charCeiling = maxContext * 4 * 0.60;
+    const charCeiling = maxContext * 4 * 0.6;
     if (memoryLength > charCeiling) {
       return "involuntary";
     }
@@ -201,10 +219,12 @@ export class HandoffEngine {
       return false;
     }
 
-    const candidatesList = candidates.map((entry) => {
-      const serialized = serializeSubjectiveBufferEntry(entry, entity);
-      return `ID: ${entry.id} | Timestamp: ${entry.timestamp} | Location: ${entry.locationId || "None"}\nContent: ${serialized}`;
-    }).join("\n---\n");
+    const candidatesList = candidates
+      .map((entry) => {
+        const serialized = serializeSubjectiveBufferEntry(entry, entity);
+        return `ID: ${entry.id} | Timestamp: ${entry.timestamp} | Location: ${entry.locationId || "None"}\nContent: ${serialized}`;
+      })
+      .join("\n---\n");
 
     const systemPrompt = `
 You are the memory Handoff Engine. Your task is to process a list of recent working memory buffer entries for an entity and select which memories to promote to the long-term Ledger, and which to forget or summarize.
@@ -239,7 +259,7 @@ ${candidatesList}
     }
 
     const result = response.data;
-    const db = (this.bufferRepo as unknown as { db: Record<string, unknown> }).db;
+    const db = (this.bufferRepo as any).db;
 
     const ledgerEntries: LedgerEntry[] = [];
     for (const chunk of result.chunks) {
@@ -252,7 +272,11 @@ ${candidatesList}
       }
 
       ledgerEntries.push({
-        id: "ledger-" + Math.random().toString(36).substr(2, 9) + "-" + Date.now(),
+        id:
+          "ledger-" +
+          Math.random().toString(36).substr(2, 9) +
+          "-" +
+          Date.now(),
         ownerId: entity.id,
         timestamp: now.toISOString(),
         locationId: entity.locationId,

packages/memory/src/ledger.ts

@@ -82,7 +82,7 @@ export class LedgerRepository {
         entry.importance,
         entry.embedding.length > 0
           ? Buffer.from(new Float32Array(entry.embedding).buffer)
-          : null
+          : null,
       );
 
       deleteEntities.run(entry.id);
@@ -92,14 +92,18 @@ export class LedgerRepository {
     })();
   }
 
-  private mapRowToEntry(row: Record<string, unknown>, involvedEntityIds: string[]): LedgerEntry {
+  private mapRowToEntry(
+    row: Record<string, unknown>,
+    involvedEntityIds: string[],
+  ): LedgerEntry {
     const embedding: number[] = row.embedding
       ? Array.from(
           new Float32Array(
             (row.embedding as Buffer).buffer,
             (row.embedding as Buffer).byteOffset,
-            (row.embedding as Buffer).byteLength / Float32Array.BYTES_PER_ELEMENT
-          )
+            (row.embedding as Buffer).byteLength /
+              Float32Array.BYTES_PER_ELEMENT,
+          ),
         )
       : [];
 
@@ -123,7 +127,7 @@ export class LedgerRepository {
       SELECT id, owner_id, timestamp, location_id, content, quotes_json, importance, embedding
       FROM ledger_entries
       WHERE id = ?
-    `
+    `,
       )
       .get(id) as Record<string, unknown> | undefined;
 
@@ -133,11 +137,14 @@ export class LedgerRepository {
       .prepare(
         `
       SELECT entity_id FROM ledger_involved_entities WHERE entry_id = ?
-    `
+    `,
       )
       .all(id) as { entity_id: string }[];
 
-    return this.mapRowToEntry(row, entitiesRows.map((er) => er.entity_id));
+    return this.mapRowToEntry(
+      row,
+      entitiesRows.map((er) => er.entity_id),
+    );
   }
 
   /**
@@ -151,7 +158,7 @@ export class LedgerRepository {
     ownerId: string,
     currentLocationId: string | null,
     currentInvolvedEntityIds: string[],
-    limit: number = 20
+    limit: number = 20,
   ): LedgerEntry[] {
     let query = `
       SELECT DISTINCT le.id, le.owner_id, le.timestamp, le.location_id, le.content, le.quotes_json, le.importance, le.embedding
@@ -182,18 +189,21 @@ export class LedgerRepository {
     `;
     params.push(limit);
 
-    const rows = this.db.prepare(query).all(...params) as Record<string, unknown>[];
+    const rows = this.db.prepare(query).all(...params) as Record<
+      string,
+      unknown
+    >[];
 
     if (rows.length === 0) return [];
 
-    const entryIds = rows.map((r) => r.id);
+    const entryIds = rows.map((r) => r.id as string);
     const placeholders = entryIds.map(() => "?").join(",");
     const entitiesRows = this.db
       .prepare(
         `
       SELECT entry_id, entity_id FROM ledger_involved_entities
       WHERE entry_id IN (${placeholders})
-    `
+    `,
       )
       .all(...entryIds) as { entry_id: string; entity_id: string }[];
 
@@ -205,7 +215,9 @@ export class LedgerRepository {
       entitiesMap.get(er.entry_id)!.push(er.entity_id);
     }
 
-    return rows.map((row) => this.mapRowToEntry(row, entitiesMap.get(row.id) || []));
+    return rows.map((row) =>
+      this.mapRowToEntry(row, entitiesMap.get(row.id as string) || []),
+    );
   }
 
   private fetchRawNeighbors(ownerId: string, timestamp: string): LedgerEntry[] {
@@ -220,7 +232,7 @@ export class LedgerRepository {
       WHERE owner_id = ? AND timestamp < ?
       ORDER BY timestamp DESC
       LIMIT 1
-    `
+    `,
       )
       .get(ownerId, timestamp) as Record<string, unknown> | undefined;
 
@@ -237,7 +249,7 @@ export class LedgerRepository {
       WHERE owner_id = ? AND timestamp > ?
       ORDER BY timestamp ASC
       LIMIT 1
-    `
+    `,
       )
       .get(ownerId, timestamp) as Record<string, unknown> | undefined;
 
@@ -269,16 +281,22 @@ export class LedgerRepository {
       importanceWeight?: number;
       relevanceWeight?: number;
       decayRate?: number;
-    }
+    },
   ): LedgerEntry[] {
-    const includeAssociativeNeighbors = options?.includeAssociativeNeighbors ?? false;
+    const includeAssociativeNeighbors =
+      options?.includeAssociativeNeighbors ?? false;
     const recencyWeight = options?.recencyWeight ?? 1.0;
     const importanceWeight = options?.importanceWeight ?? 1.0;
     const relevanceWeight = options?.relevanceWeight ?? 1.0;
     const decayRate = options?.decayRate ?? 0.99;
 
     // Fetch candidate pool (limit 100 to provide enough options for Phase 2 ranking)
-    const candidates = this.getRelevant(ownerId, currentLocationId, currentInvolvedEntityIds, 100);
+    const candidates = this.getRelevant(
+      ownerId,
+      currentLocationId,
+      currentInvolvedEntityIds,
+      100,
+    );
     if (candidates.length === 0) return [];
 
     // Score candidates
@@ -318,7 +336,10 @@ export class LedgerRepository {
       for (const entry of selected) {
         const rawNeighbors = this.fetchRawNeighbors(ownerId, entry.timestamp);
         for (const rn of rawNeighbors) {
-          if (!finalEntries.some((fe) => fe.id === rn.id) && !neighborMap.has(rn.id)) {
+          if (
+            !finalEntries.some((fe) => fe.id === rn.id) &&
+            !neighborMap.has(rn.id)
+          ) {
             neighborMap.set(rn.id, rn);
           }
         }
@@ -333,7 +354,7 @@ export class LedgerRepository {
             `
           SELECT entry_id, entity_id FROM ledger_involved_entities
           WHERE entry_id IN (${placeholders})
-        `
+        `,
           )
           .all(...neighborIds) as { entry_id: string; entity_id: string }[];
 
@@ -353,7 +374,10 @@ export class LedgerRepository {
     }
 
     // Sort chronologically ASC for the final prompt output
-    finalEntries.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    finalEntries.sort(
+      (a, b) =>
+        new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime(),
+    );
 
     return finalEntries;
   }