sdlc-agent-4-enterprise-server 1.0.0

package/extension/src/chat-panel/__tests__/context-usage-tracker.test.ts

@@ -0,0 +1,170 @@
+/**
+ * ContextUsageTracker Tests — KSA-249
+ * Covers: TC-CUG-001 to TC-CUG-009 (9 UT cases)
+ * Pure logic — no vscode mock needed.
+ */
+import { describe, it, expect, beforeEach } from "vitest";
+import { ContextUsageTracker } from "../context-usage-tracker";
+
+describe("ContextUsageTracker (KSA-249)", () => {
+  let tracker: ContextUsageTracker;
+
+  beforeEach(() => {
+    tracker = new ContextUsageTracker(128000);
+  });
+
+  // TC-CUG-001: Token Estimation Accuracy
+  describe("TC-CUG-001: Token Estimation", () => {
+    it("estimates 'Hello world' (11 chars) as 3 tokens", () => {
+      tracker.updateFromMessages("tab1", [{ content: "Hello world" }]);
+      const payload = tracker.getUsagePayload("tab1");
+      expect(payload.conversation.tokens).toBe(3); // ceil(11/4)
+    });
+
+    it("estimates empty string as 0 tokens", () => {
+      tracker.updateFromMessages("tab1", [{ content: "" }]);
+      const payload = tracker.getUsagePayload("tab1");
+      expect(payload.conversation.tokens).toBe(0);
+    });
+
+    it("estimates 1000 chars as 250 tokens", () => {
+      const longStr = "a".repeat(1000);
+      tracker.updateFromMessages("tab1", [{ content: longStr }]);
+      const payload = tracker.getUsagePayload("tab1");
+      expect(payload.conversation.tokens).toBe(250); // ceil(1000/4)
+    });
+  });
+
+  // TC-CUG-002: Context Usage Payload Calculation
+  describe("TC-CUG-002: Payload Calculation", () => {
+    it("calculates correct percentages for conversation=45000, mcp=12000, steering=3000", () => {
+      // Set conversation tokens: need 45000 tokens → 45000*4 = 180000 chars
+      tracker.updateFromMessages("tab1", [{ content: "a".repeat(180000) }]);
+      // Set mcp tokens: 12000 → 48000 chars
+      tracker.addToolTokens("tab1", "b".repeat(48000));
+      // Set steering: 3000 → 12000 chars
+      tracker.updateSteeringTokens("tab1", ["c".repeat(12000)]);
+
+      const payload = tracker.getUsagePayload("tab1");
+      expect(payload.conversation.tokens).toBe(45000);
+      expect(payload.mcpTools.tokens).toBe(12000);
+      expect(payload.steering.tokens).toBe(3000);
+      expect(payload.total.tokens).toBe(60000);
+      // percentage = round(60000/128000 * 100) = 47
+      expect(payload.total.percentage).toBe(47);
+      expect(payload.total.threshold).toBe("safe");
+    });
+  });
+
+  // TC-CUG-003: Empty Tab Usage
+  describe("TC-CUG-003: Empty Tab", () => {
+    it("returns zeros for new tab with only steering", () => {
+      // steering 2000 tokens → 8000 chars
+      tracker.updateSteeringTokens("tab1", ["x".repeat(8000)]);
+      const payload = tracker.getUsagePayload("tab1");
+
+      expect(payload.conversation.tokens).toBe(0);
+      expect(payload.mcpTools.tokens).toBe(0);
+      expect(payload.steering.tokens).toBe(2000);
+      expect(payload.total.tokens).toBe(2000);
+      // round(2000/128000*100) = 2
+      expect(payload.total.percentage).toBe(2);
+      expect(payload.total.threshold).toBe("safe");
+    });
+  });
+
+  // TC-CUG-004: Tab Switch Updates Usage (UT-level: per-tab isolation)
+  describe("TC-CUG-004: Tab Isolation", () => {
+    it("returns different data for different tabs", () => {
+      // Tab A: 50000 tokens → 200000 chars
+      tracker.updateFromMessages("tabA", [{ content: "a".repeat(200000) }]);
+      // Tab B: 10000 tokens → 40000 chars
+      tracker.updateFromMessages("tabB", [{ content: "b".repeat(40000) }]);
+
+      const payloadA = tracker.getUsagePayload("tabA");
+      const payloadB = tracker.getUsagePayload("tabB");
+
+      expect(payloadA.total.tokens).toBe(50000);
+      expect(payloadB.total.tokens).toBe(10000);
+    });
+  });
+
+  // TC-CUG-005: Large Token Count Formatting (logic test: percentage rounding)
+  describe("TC-CUG-005: Percentage Rounding", () => {
+    it("rounds percentage correctly for large token counts", () => {
+      // 45231 tokens → 180924 chars
+      tracker.updateFromMessages("tab1", [{ content: "a".repeat(180924) }]);
+      const payload = tracker.getUsagePayload("tab1");
+      expect(payload.conversation.tokens).toBe(45231);
+      // round(45231/128000*100) = 35
+      expect(payload.conversation.percentage).toBe(35);
+    });
+  });
+
+  // TC-CUG-006: Safe Threshold (0-59%)
+  describe("TC-CUG-006: Safe Threshold", () => {
+    it("returns 'safe' for 47% usage", () => {
+      // 47% of 128000 = 60160 tokens → 240640 chars
+      tracker.updateFromMessages("tab1", [{ content: "a".repeat(240640) }]);
+      const payload = tracker.getUsagePayload("tab1");
+      expect(payload.total.threshold).toBe("safe");
+    });
+  });
+
+  // TC-CUG-007: Warning Threshold (60-79%)
+  describe("TC-CUG-007: Warning Threshold", () => {
+    it("returns 'warning' for 60% usage", () => {
+      // 60% of 128000 = 76800 tokens → 307200 chars
+      tracker.updateFromMessages("tab1", [{ content: "a".repeat(307200) }]);
+      const payload = tracker.getUsagePayload("tab1");
+      expect(payload.total.percentage).toBe(60);
+      expect(payload.total.threshold).toBe("warning");
+    });
+
+    it("returns 'warning' for 79% usage", () => {
+      // 79% of 128000 = 101120 tokens → 404480 chars
+      tracker.updateFromMessages("tab1", [{ content: "a".repeat(404480) }]);
+      const payload = tracker.getUsagePayload("tab1");
+      expect(payload.total.percentage).toBe(79);
+      expect(payload.total.threshold).toBe("warning");
+    });
+  });
+
+  // TC-CUG-008: Critical Threshold (80-94%)
+  describe("TC-CUG-008: Critical Threshold", () => {
+    it("returns 'critical' for 80% usage", () => {
+      // 80% of 128000 = 102400 tokens → 409600 chars
+      tracker.updateFromMessages("tab1", [{ content: "a".repeat(409600) }]);
+      const payload = tracker.getUsagePayload("tab1");
+      expect(payload.total.percentage).toBe(80);
+      expect(payload.total.threshold).toBe("critical");
+    });
+
+    it("returns 'critical' for 94% usage", () => {
+      // 94% of 128000 = 120320 tokens → 481280 chars
+      tracker.updateFromMessages("tab1", [{ content: "a".repeat(481280) }]);
+      const payload = tracker.getUsagePayload("tab1");
+      expect(payload.total.percentage).toBe(94);
+      expect(payload.total.threshold).toBe("critical");
+    });
+  });
+
+  // TC-CUG-009: Full Threshold (95-100%)
+  describe("TC-CUG-009: Full Threshold", () => {
+    it("returns 'full' for 95% usage", () => {
+      // 95% of 128000 = 121600 tokens → 486400 chars
+      tracker.updateFromMessages("tab1", [{ content: "a".repeat(486400) }]);
+      const payload = tracker.getUsagePayload("tab1");
+      expect(payload.total.percentage).toBe(95);
+      expect(payload.total.threshold).toBe("full");
+    });
+
+    it("returns 'full' for 100% usage", () => {
+      // 100% of 128000 = 128000 tokens → 512000 chars
+      tracker.updateFromMessages("tab1", [{ content: "a".repeat(512000) }]);
+      const payload = tracker.getUsagePayload("tab1");
+      expect(payload.total.percentage).toBe(100);
+      expect(payload.total.threshold).toBe("full");
+    });
+  });
+});

package/extension/src/chat-panel/__tests__/conversation-manager.test.ts

@@ -0,0 +1,152 @@
+/**
+ * ConversationManager Tests — KSA-240
+ */
+
+import { describe, it, expect, beforeEach } from "vitest";
+import { ConversationManager } from "../conversation-manager";
+
+describe("ConversationManager", () => {
+  let manager: ConversationManager;
+
+  beforeEach(() => {
+    manager = new ConversationManager(10);
+  });
+
+  describe("initialization", () => {
+    it("should create an initial tab on construction", () => {
+      expect(manager.getTabCount()).toBe(1);
+      expect(manager.getActiveTab()).toBeDefined();
+      expect(manager.getActiveTab()!.name).toBe("Chat 1");
+    });
+
+    it("should set initial tab as active", () => {
+      expect(manager.getActiveTab()!.isActive).toBe(true);
+    });
+  });
+
+  describe("createTab", () => {
+    it("should create a new tab with sequential naming", () => {
+      const tab2 = manager.createTab();
+      expect(tab2.name).toBe("Chat 2");
+      expect(manager.getTabCount()).toBe(2);
+    });
+
+    it("should set new tab as active", () => {
+      const tab2 = manager.createTab();
+      expect(tab2.isActive).toBe(true);
+      expect(manager.getActiveTabId()).toBe(tab2.id);
+    });
+
+    it("should deactivate previous tab", () => {
+      const tab1 = manager.getActiveTab()!;
+      manager.createTab();
+      const updatedTab1 = manager.getTab(tab1.id);
+      expect(updatedTab1!.isActive).toBe(false);
+    });
+
+    it("should throw when max tabs reached", () => {
+      const mgr = new ConversationManager(2);
+      mgr.createTab(); // now 2 tabs
+      expect(() => mgr.createTab()).toThrow("Maximum 2 tabs reached");
+    });
+
+    it("should create tab with empty messages and zero token count", () => {
+      const tab = manager.createTab();
+      expect(tab.messages).toEqual([]);
+      expect(tab.tokenCount).toBe(0);
+      expect(tab.maxTokens).toBe(128000);
+    });
+  });
+
+  describe("switchTab", () => {
+    it("should switch to specified tab", () => {
+      const tab1 = manager.getActiveTab()!;
+      manager.createTab();
+      const switched = manager.switchTab(tab1.id);
+      expect(switched.id).toBe(tab1.id);
+      expect(switched.isActive).toBe(true);
+    });
+
+    it("should throw for non-existent tab", () => {
+      expect(() => manager.switchTab("fake-id")).toThrow("Tab fake-id not found");
+    });
+  });
+
+  describe("closeTab", () => {
+    it("should close tab and activate neighbor", () => {
+      const tab1 = manager.getActiveTab()!;
+      const tab2 = manager.createTab();
+      const result = manager.closeTab(tab2.id);
+      expect(result.closedTab.id).toBe(tab2.id);
+      expect(manager.getTabCount()).toBe(1);
+      expect(manager.getActiveTabId()).toBe(tab1.id);
+    });
+
+    it("should throw when trying to close last tab", () => {
+      expect(() => manager.closeTab(manager.getActiveTabId())).toThrow("Cannot close the last tab");
+    });
+
+    it("should activate left neighbor when closing active middle tab", () => {
+      const tab1 = manager.getActiveTab()!;
+      manager.createTab(); // tab2
+      const tab3 = manager.createTab();
+      manager.switchTab(tab1.id);
+      manager.createTab(); // switches to new tab
+      // Close active tab - should go to left neighbor
+      const activeId = manager.getActiveTabId();
+      manager.createTab();
+      manager.switchTab(tab3.id);
+      manager.closeTab(tab3.id);
+      // Should have activated a neighbor
+      expect(manager.getActiveTab()).toBeDefined();
+    });
+  });
+
+  describe("renameTab", () => {
+    it("should rename tab", () => {
+      const tab = manager.getActiveTab()!;
+      manager.renameTab(tab.id, "My Chat");
+      expect(manager.getTab(tab.id)!.name).toBe("My Chat");
+    });
+
+    it("should truncate name at 30 chars", () => {
+      const tab = manager.getActiveTab()!;
+      const longName = "A".repeat(50);
+      manager.renameTab(tab.id, longName);
+      expect(manager.getTab(tab.id)!.name.length).toBe(30);
+    });
+
+    it("should not rename with empty string", () => {
+      const tab = manager.getActiveTab()!;
+      const original = tab.name;
+      manager.renameTab(tab.id, "   ");
+      expect(manager.getTab(tab.id)!.name).toBe(original);
+    });
+  });
+
+  describe("addMessage", () => {
+    it("should add message and update token count", () => {
+      const tab = manager.getActiveTab()!;
+      manager.addMessage(tab.id, {
+        id: "msg-1",
+        role: "user",
+        content: "Hello",
+        timestamp: new Date().toISOString(),
+        tokenCount: 5,
+      });
+      expect(manager.getTab(tab.id)!.messages.length).toBe(1);
+      expect(manager.getTab(tab.id)!.tokenCount).toBe(5);
+    });
+  });
+
+  describe("canCreateTab", () => {
+    it("should return true when under limit", () => {
+      expect(manager.canCreateTab()).toBe(true);
+    });
+
+    it("should return false when at limit", () => {
+      const mgr = new ConversationManager(1);
+      expect(mgr.canCreateTab()).toBe(false);
+    });
+  });
+});

package/extension/src/chat-panel/__tests__/token-counter.test.ts

@@ -0,0 +1,93 @@
+/**
+ * TokenCounter Tests — KSA-240
+ */
+
+import { describe, it, expect } from "vitest";
+import { TokenCounter } from "../token-counter";
+
+describe("TokenCounter", () => {
+  const counter = new TokenCounter();
+
+  describe("countMessageTokens", () => {
+    it("should estimate tokens from content length", () => {
+      // ~4 chars per token + 4 overhead
+      const tokens = counter.countMessageTokens("Hello world"); // 11 chars
+      expect(tokens).toBe(Math.ceil(11 / 4) + 4); // 3 + 4 = 7
+    });
+
+    it("should return 0 for empty content", () => {
+      expect(counter.countMessageTokens("")).toBe(0);
+    });
+
+    it("should handle long content", () => {
+      const content = "a".repeat(1000);
+      const tokens = counter.countMessageTokens(content);
+      expect(tokens).toBe(Math.ceil(1000 / 4) + 4); // 254
+    });
+  });
+
+  describe("getUsagePercentage", () => {
+    it("should calculate correct percentage", () => {
+      expect(counter.getUsagePercentage(50000, 100000)).toBe(50);
+      expect(counter.getUsagePercentage(80000, 100000)).toBe(80);
+      expect(counter.getUsagePercentage(0, 100000)).toBe(0);
+    });
+
+    it("should cap at 100%", () => {
+      expect(counter.getUsagePercentage(150000, 100000)).toBe(100);
+    });
+
+    it("should handle zero maxTokens", () => {
+      expect(counter.getUsagePercentage(100, 0)).toBe(0);
+    });
+  });
+
+  describe("getThresholdState", () => {
+    it("should return safe for < 60%", () => {
+      expect(counter.getThresholdState(0)).toBe("safe");
+      expect(counter.getThresholdState(30)).toBe("safe");
+      expect(counter.getThresholdState(59)).toBe("safe");
+    });
+
+    it("should return warning for 60-79%", () => {
+      expect(counter.getThresholdState(60)).toBe("warning");
+      expect(counter.getThresholdState(70)).toBe("warning");
+      expect(counter.getThresholdState(79)).toBe("warning");
+    });
+
+    it("should return critical for 80-94%", () => {
+      expect(counter.getThresholdState(80)).toBe("critical");
+      expect(counter.getThresholdState(90)).toBe("critical");
+      expect(counter.getThresholdState(94)).toBe("critical");
+    });
+
+    it("should return full for >= 95%", () => {
+      expect(counter.getThresholdState(95)).toBe("full");
+      expect(counter.getThresholdState(100)).toBe("full");
+    });
+  });
+
+  describe("getMaxTokensForModel", () => {
+    it("should return known model limits", () => {
+      expect(counter.getMaxTokensForModel("gpt-4o")).toBe(128000);
+      expect(counter.getMaxTokensForModel("claude-sonnet-4-20250514")).toBe(200000);
+    });
+
+    it("should return default for unknown models", () => {
+      expect(counter.getMaxTokensForModel("unknown-model")).toBe(128000);
+    });
+  });
+
+  describe("custom thresholds", () => {
+    it("should respect custom config", () => {
+      const custom = new TokenCounter({
+        warningThreshold: 0.5,
+        criticalThreshold: 0.7,
+        fullThreshold: 0.9,
+      });
+      expect(custom.getThresholdState(50)).toBe("warning");
+      expect(custom.getThresholdState(70)).toBe("critical");
+      expect(custom.getThresholdState(90)).toBe("full");
+    });
+  });
+});

package/extension/src/chat-panel/chat-models.ts

@@ -0,0 +1,167 @@
+/**
+ * Chat Panel Model Catalog — KSA-237
+ * Single source of truth for the per-provider model list shown in the Chat
+ * Panel model dropdown. Mirrors the catalog used by the Settings panel so the
+ * dropdown reflects the provider configured in SDLC Settings
+ * (kiroSdlc.llmProvider) instead of a hardcoded mixed list.
+ *
+ * When the Anthropic base URL points at the local gateway (127.0.0.1),
+ * the model list is fetched live from GET http://127.0.0.1:{port}/v1/models
+ * which surfaces all available Kiro models. Falls back to this static catalog
+ * when the gateway is unreachable.
+ */
+
+import type { ChatModelEntry } from "./message-protocol";
+
+/** Provider id as stored in kiroSdlc.llmProvider */
+export type ChatProvider = "anthropic" | "openai" | "ollama" | "onnx" | "lmstudio" | "openrouter";
+
+/** Default model id per provider (used when no override is configured). */
+export const DEFAULT_MODELS: Record<string, string> = {
+  anthropic: "claude-sonnet-4-20250514",
+  kiro: "auto",
+  openai: "gpt-4o",
+  ollama: "llama3.1",
+  onnx: "phi-3-mini",
+  lmstudio: "local-model",
+  openrouter: "anthropic/claude-sonnet-4",
+};
+
+/** Available models per provider — static catalog (fallback when gateway is unreachable). */
+export const AVAILABLE_MODELS: Record<string, ChatModelEntry[]> = {
+  kiro: [
+    { id: "auto", name: "Auto" },
+    { id: "claude-opus-4-8", name: "Claude Opus 4.8", rateMultiplier: 2.2 },
+    { id: "claude-opus-4-7", name: "Claude Opus 4.7", rateMultiplier: 2.2 },
+    { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6", rateMultiplier: 1.3 },
+    { id: "claude-sonnet-4-5-20250929", name: "Claude Sonnet 4.5", rateMultiplier: 1.3 },
+    { id: "claude-sonnet-4-20250514", name: "Claude Sonnet 4", rateMultiplier: 1.3 },
+    { id: "claude-haiku-4-5-20251001", name: "Claude Haiku 4.5", rateMultiplier: 0.4 },
+    { id: "deepseek-v3-2", name: "Deepseek v3.2", rateMultiplier: 0.25 },
+    { id: "minimax-m2-5", name: "MiniMax M2.5", rateMultiplier: 0.25 },
+  ],
+  anthropic: [
+    { id: "claude-opus-4-8", name: "Claude Opus 4.8", rateMultiplier: 2.2 },
+    { id: "claude-opus-4-7", name: "Claude Opus 4.7", rateMultiplier: 2.2 },
+    { id: "claude-opus-4-6", name: "Claude Opus 4.6", rateMultiplier: 2.2 },
+    { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6", rateMultiplier: 1.3 },
+    { id: "claude-sonnet-4-5-20250929", name: "Claude Sonnet 4.5", rateMultiplier: 1.3 },
+    { id: "claude-sonnet-4-20250514", name: "Claude Sonnet 4", rateMultiplier: 1.3 },
+    { id: "claude-haiku-4-5-20251001", name: "Claude Haiku 4.5", rateMultiplier: 0.4 },
+    { id: "deepseek-v3-2", name: "Deepseek v3.2", rateMultiplier: 0.25 },
+    { id: "minimax-m2-5", name: "MiniMax M2.5", rateMultiplier: 0.25 },
+  ],
+  openai: [
+    { id: "gpt-4o", name: "GPT-4o" },
+    { id: "gpt-4o-mini", name: "GPT-4o Mini" },
+    { id: "gpt-4-turbo", name: "GPT-4 Turbo" },
+    { id: "o1", name: "o1" },
+    { id: "o1-mini", name: "o1 Mini" },
+    { id: "o3", name: "o3" },
+    { id: "o3-mini", name: "o3 Mini" },
+    { id: "o4-mini", name: "o4 Mini" },
+  ],
+  ollama: [
+    { id: "llama3.1", name: "Llama 3.1" },
+    { id: "llama3.2", name: "Llama 3.2" },
+    { id: "codellama", name: "Code Llama" },
+    { id: "mistral", name: "Mistral" },
+    { id: "mixtral", name: "Mixtral" },
+    { id: "deepseek-coder-v2", name: "DeepSeek Coder v2" },
+    { id: "qwen2.5-coder", name: "Qwen 2.5 Coder" },
+  ],
+  onnx: [
+    { id: "phi-3-mini", name: "Phi-3 Mini (3.8B)" },
+    { id: "smollm2-360m", name: "SmolLM2 (360M)" },
+  ],
+  lmstudio: [
+    { id: "local-model", name: "Local Model (auto-detect)" },
+    { id: "qwen2.5-coder-32b", name: "Qwen 2.5 Coder 32B" },
+    { id: "deepseek-coder-v2-lite", name: "DeepSeek Coder V2 Lite" },
+    { id: "codellama-34b", name: "Code Llama 34B" },
+    { id: "mistral-7b", name: "Mistral 7B" },
+    { id: "llama-3.1-8b", name: "Llama 3.1 8B" },
+    { id: "phi-3-medium", name: "Phi-3 Medium (14B)" },
+  ],
+  openrouter: [
+    { id: "anthropic/claude-sonnet-4", name: "Claude Sonnet 4" },
+    { id: "anthropic/claude-opus-4", name: "Claude Opus 4" },
+    { id: "anthropic/claude-haiku-4", name: "Claude Haiku 4" },
+    { id: "openai/gpt-4o", name: "GPT-4o" },
+    { id: "openai/o3", name: "o3" },
+    { id: "openai/o4-mini", name: "o4 Mini" },
+    { id: "google/gemini-2.5-pro", name: "Gemini 2.5 Pro" },
+    { id: "google/gemini-2.5-flash", name: "Gemini 2.5 Flash" },
+    { id: "deepseek/deepseek-r1", name: "DeepSeek R1" },
+    { id: "deepseek/deepseek-v3", name: "DeepSeek V3" },
+    { id: "meta-llama/llama-4-maverick", name: "Llama 4 Maverick" },
+    { id: "qwen/qwen3-235b", name: "Qwen3 235B" },
+  ],
+};
+
+/** Get the static fallback model list for a provider (never undefined). */
+export function getStaticModels(provider: string): ChatModelEntry[] {
+  return AVAILABLE_MODELS[provider] ?? AVAILABLE_MODELS.anthropic;
+}
+
+/** Get the default model id for a provider. */
+export function getDefaultModel(provider: string): string {
+  return DEFAULT_MODELS[provider] ?? "";
+}
+
+/**
+ * Fetch the model list from an Anthropic-compatible gateway (`{baseUrl}/v1/models`).
+ * `baseUrl` is the configured gateway base URL (e.g. http://127.0.0.1:8990/anthropic).
+ * Returns the parsed model entries, or null on any failure so the caller can
+ * fall back to the static catalog.
+ */
+export async function fetchGatewayModels(baseUrl: string): Promise<ChatModelEntry[] | null> {
+  if (!baseUrl) {
+    return null;
+  }
+  const cleanBase = baseUrl.replace(/\/$/, "");
+  // If base URL already ends with /v1, don't double it
+  const modelsUrl = cleanBase.endsWith("/v1") 
+    ? `${cleanBase}/models`
+    : `${cleanBase}/v1/models`;
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
+    const response = await fetch(modelsUrl, {
+      method: "GET",
+      headers: { "Content-Type": "application/json" },
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+
+    if (!response.ok) {
+      return null;
+    }
+
+    // Anthropic /v1/models envelope extended with Kiro fields: { data: [{ id, display_name, description, rate_multiplier }] }
+    const json = (await response.json()) as {
+      data?: Array<{ id?: string; display_name?: string; name?: string; description?: string; rate_multiplier?: number }>;
+    };
+    const data = Array.isArray(json?.data) ? json.data : [];
+    const models: ChatModelEntry[] = data
+      .filter((m) => typeof m?.id === "string" && m.id.length > 0)
+      .map((m) => {
+        const entry: ChatModelEntry = {
+          id: m.id as string,
+          name: m.display_name || m.name || (m.id as string),
+        };
+        // KSA-237: carry description + rate_multiplier for rich dropdown rendering
+        if (typeof m.description === "string" && m.description.trim()) {
+          entry.description = m.description.trim();
+        }
+        if (typeof m.rate_multiplier === "number") {
+          entry.rateMultiplier = m.rate_multiplier;
+        }
+        return entry;
+      });
+
+    return models.length > 0 ? models : null;
+  } catch {
+    return null;
+  }
+}