npm - kanna-code - Versions diffs - 0.31.0 → 0.32.1 - Mend

kanna-code 0.31.0 → 0.32.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

package/dist/client/assets/index-B3EUEMfY.css +32 -0
package/dist/client/assets/index-EVYrrkP5.js +2593 -0
package/dist/client/index.html +2 -2
package/package.json +2 -1
package/src/server/diff-store.test.ts +35 -0
package/src/server/diff-store.ts +27 -7
package/src/server/event-store.test.ts +18 -0
package/src/server/event-store.ts +32 -0
package/src/server/events.ts +8 -0
package/src/server/generate-commit-message.test.ts +20 -0
package/src/server/generate-commit-message.ts +1 -1
package/src/server/generate-title.ts +1 -1
package/src/server/llm-provider.test.ts +134 -0
package/src/server/llm-provider.ts +207 -0
package/src/server/quick-response.test.ts +202 -0
package/src/server/quick-response.ts +56 -2
package/src/server/read-models.test.ts +78 -1
package/src/server/read-models.ts +54 -4
package/src/server/server.ts +6 -0
package/src/server/ws-router.test.ts +278 -10
package/src/server/ws-router.ts +130 -21
package/src/shared/branding.ts +8 -0
package/src/shared/protocol.ts +18 -0
package/src/shared/types.ts +29 -0
package/dist/client/assets/index-D_R1gYah.js +0 -2598
package/dist/client/assets/index-KvdfpGdt.css +0 -32

package/dist/client/index.html CHANGED Viewed

@@ -30,8 +30,8 @@
       })()
     </script>
     <title>Kanna</title>
-    <script type="module" crossorigin src="/assets/index-D_R1gYah.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-KvdfpGdt.css">
+    <script type="module" crossorigin src="/assets/index-EVYrrkP5.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-B3EUEMfY.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "kanna-code",
   "type": "module",
-  "version": "0.31.0",
+  "version": "0.32.1",
   "description": "A beautiful web UI for Claude Code",
   "license": "MIT",
   "keywords": [
@@ -57,6 +57,7 @@
     "cloudflared": "^0.7.1",
     "default-shell": "^2.2.0",
     "file-type": "^22.0.0",
+    "openai": "^6.34.0",
     "react-resizable-panels": "^4.7.3",
     "uqr": "^0.1.3"
   },

package/src/server/diff-store.test.ts CHANGED Viewed

@@ -176,6 +176,41 @@ describe("DiffStore", () => {
     expect((await run(["git", "log", "-1", "--pretty=%s"], repoRoot)).trim()).toBe("Local only")
   })
+  test("commits tracked files inside newly ignored directories", async () => {
+    const repoRoot = await createRepo()
+    tempDirs.push(repoRoot)
+    await mkdir(path.join(repoRoot, "build", ".wrangler"), { recursive: true })
+    await writeFile(path.join(repoRoot, "build", ".wrangler", "state.sqlite"), "base\n", "utf8")
+    await run(["git", "add", "."], repoRoot)
+    await run(["git", "commit", "-m", "init"], repoRoot)
+    await writeFile(path.join(repoRoot, "build", ".gitignore"), ".wrangler/\n", "utf8")
+    await writeFile(path.join(repoRoot, "build", ".wrangler", "state.sqlite"), "changed\n", "utf8")
+    const store = new DiffStore(repoRoot)
+    await store.initialize()
+    await store.refreshSnapshot("project-1", repoRoot)
+    const result = await store.commitFiles({
+      projectId: "project-1",
+      projectPath: repoRoot,
+      paths: ["build/.wrangler/state.sqlite"],
+      summary: "Commit tracked ignored file",
+      mode: "commit_only",
+    })
+    expect(result).toMatchObject({
+      ok: true,
+      mode: "commit_only",
+      pushed: false,
+    })
+    expect((await run(["git", "log", "-1", "--pretty=%s"], repoRoot)).trim()).toBe("Commit tracked ignored file")
+    const snapshot = store.getProjectSnapshot("project-1")
+    expect(snapshot.files).toHaveLength(1)
+    expect(snapshot.files[0]?.path).toBe("build/.gitignore")
+  })
   test("refreshSnapshot reports origin presence before the first commit", async () => {
     const repoRoot = await createRepo()
     tempDirs.push(repoRoot)

package/src/server/diff-store.ts CHANGED Viewed

@@ -179,12 +179,20 @@ function summarizeGitFailure(detail: string, fallback: string) {
 }
 function createCommitFailure(mode: DiffCommitMode, detail: string): DiffCommitResult {
-  const message = summarizeGitFailure(detail, "Git could not create the commit.")
+  const normalized = detail.toLowerCase()
+  let title = "Commit failed"
+  let message = summarizeGitFailure(detail, "Git could not create the commit.")
+  if (normalized.includes("ignored by one of your .gitignore files")) {
+    title = "Ignored files cannot be staged"
+    message = "One or more selected paths are ignored by .gitignore. Unignore them or remove them from the commit selection."
+  }
   return {
     ok: false,
     mode,
     phase: "commit",
-    title: "Commit failed",
+    title,
     message,
     detail,
   }
@@ -2017,15 +2025,27 @@ export class DiffStore {
     ])
     const hasOriginRemote = originRemoteUrl !== null
-    const currentDirtyPaths = new Set((await listDirtyPaths(repo.repoRoot)).map((entry) => entry.path))
-    const missingPaths = normalizedPaths.filter((relativePath) => !currentDirtyPaths.has(relativePath))
+    const currentDirtyEntries = await listDirtyPaths(repo.repoRoot)
+    const currentDirtyPathsByPath = new Map(currentDirtyEntries.map((entry) => [entry.path, entry]))
+    const missingPaths = normalizedPaths.filter((relativePath) => !currentDirtyPathsByPath.has(relativePath))
     if (missingPaths.length > 0) {
       throw new Error(`File is no longer changed: ${missingPaths[0]}`)
     }
-    const addResult = await runGit(["add", "--", ...normalizedPaths], repo.repoRoot)
-    if (addResult.exitCode !== 0) {
-      throw new Error(addResult.stderr.trim() || "Failed to stage selected files")
+    const trackedPaths = normalizedPaths.filter((relativePath) => !currentDirtyPathsByPath.get(relativePath)?.isUntracked)
+    if (trackedPaths.length > 0) {
+      const addTrackedResult = await runGit(["add", "-u", "--", ...trackedPaths], repo.repoRoot)
+      if (addTrackedResult.exitCode !== 0) {
+        return createCommitFailure(args.mode, formatGitFailure(addTrackedResult))
+      }
+    }
+    const untrackedPaths = normalizedPaths.filter((relativePath) => currentDirtyPathsByPath.get(relativePath)?.isUntracked)
+    if (untrackedPaths.length > 0) {
+      const addUntrackedResult = await runGit(["add", "--", ...untrackedPaths], repo.repoRoot)
+      if (addUntrackedResult.exitCode !== 0) {
+        return createCommitFailure(args.mode, formatGitFailure(addUntrackedResult))
+      }
     }
     const commitArgs = ["commit", "--only", "-m", summary]

package/src/server/event-store.test.ts CHANGED Viewed

@@ -345,6 +345,24 @@ describe("EventStore", () => {
     expect(store.getChat("chat-1")?.unread).toBe(false)
   })
+  test("persists sidebar project order across restart and compaction", async () => {
+    const dataDir = await createTempDataDir()
+    const store = new EventStore(dataDir)
+    await store.initialize()
+    const first = await store.openProject("/tmp/project-a")
+    const second = await store.openProject("/tmp/project-b")
+    await store.setSidebarProjectOrder([second.id, first.id])
+    expect(store.state.sidebarProjectOrder).toEqual([second.id, first.id])
+    await store.compact()
+    const reloaded = new EventStore(dataDir)
+    await reloaded.initialize()
+    expect(reloaded.state.sidebarProjectOrder).toEqual([second.id, first.id])
+  })
   test("prunes stale empty chats after thirty minutes", async () => {
     const dataDir = await createTempDataDir()
     const store = new EventStore(dataDir)

package/src/server/event-store.ts CHANGED Viewed

@@ -59,6 +59,7 @@ function getReplayEventPriority(event: StoreEvent) {
   switch (event.type) {
     case "project_opened":
     case "project_removed":
+    case "sidebar_project_order_set":
       return 0
     case "chat_created":
       return 1
@@ -198,6 +199,7 @@ export class EventStore {
           unread: chat.unread ?? false,
         })
       }
+      this.state.sidebarProjectOrder = [...(parsed.sidebarProjectOrder ?? [])]
       if (parsed.queuedMessages?.length) {
         for (const queuedSet of parsed.queuedMessages) {
           this.state.queuedMessagesByChatId.set(queuedSet.chatId, queuedSet.entries.map((entry) => ({
@@ -223,6 +225,7 @@ export class EventStore {
     this.state.projectIdsByPath.clear()
     this.state.chatsById.clear()
     this.state.queuedMessagesByChatId.clear()
+    this.state.sidebarProjectOrder = []
     this.cachedTranscript = null
   }
@@ -322,6 +325,10 @@ export class EventStore {
         this.state.projectIdsByPath.delete(project.localPath)
         break
       }
+      case "sidebar_project_order_set": {
+        this.state.sidebarProjectOrder = [...event.projectIds]
+        break
+      }
       case "chat_created": {
       const chat = {
           id: event.chatId,
@@ -527,6 +534,30 @@ export class EventStore {
     await this.append(this.projectsLogPath, event)
   }
+  async setSidebarProjectOrder(projectIds: string[]) {
+    const validProjectIds = projectIds.filter((projectId) => {
+      const project = this.state.projectsById.get(projectId)
+      return Boolean(project && !project.deletedAt)
+    })
+    const uniqueProjectIds = [...new Set(validProjectIds)]
+    const current = this.state.sidebarProjectOrder
+    if (
+      uniqueProjectIds.length === current.length
+      && uniqueProjectIds.every((projectId, index) => current[index] === projectId)
+    ) {
+      return
+    }
+    const event: ProjectEvent = {
+      v: STORE_VERSION,
+      type: "sidebar_project_order_set",
+      timestamp: Date.now(),
+      projectIds: uniqueProjectIds,
+    }
+    await this.append(this.projectsLogPath, event)
+  }
   async createChat(projectId: string) {
     const project = this.state.projectsById.get(projectId)
     if (!project || project.deletedAt) {
@@ -930,6 +961,7 @@ export class EventStore {
       v: STORE_VERSION,
       generatedAt: Date.now(),
       projects: this.listProjects().map((project) => ({ ...project })),
+      sidebarProjectOrder: [...this.state.sidebarProjectOrder],
       chats: [...this.state.chatsById.values()]
         .filter((chat) => !chat.deletedAt)
         .map((chat) => ({ ...chat })),

package/src/server/events.ts CHANGED Viewed

@@ -25,6 +25,7 @@ export interface StoreState {
   projectIdsByPath: Map<string, string>
   chatsById: Map<string, ChatRecord>
   queuedMessagesByChatId: Map<string, QueuedChatMessage[]>
+  sidebarProjectOrder: string[]
 }
 export interface SnapshotFile {
@@ -32,6 +33,7 @@ export interface SnapshotFile {
   generatedAt: number
   projects: ProjectRecord[]
   chats: ChatRecord[]
+  sidebarProjectOrder?: string[]
   queuedMessages?: Array<{ chatId: string; entries: QueuedChatMessage[] }>
   messages?: Array<{ chatId: string; entries: TranscriptEntry[] }>
 }
@@ -48,6 +50,11 @@ export type ProjectEvent = {
   type: "project_removed"
   timestamp: number
   projectId: string
+} | {
+  v: 2
+  type: "sidebar_project_order_set"
+  timestamp: number
+  projectIds: string[]
 }
 export type ChatEvent =
@@ -160,6 +167,7 @@ export function createEmptyState(): StoreState {
     projectIdsByPath: new Map(),
     chatsById: new Map(),
     queuedMessagesByChatId: new Map(),
+    sidebarProjectOrder: [],
   }
 }

package/src/server/generate-commit-message.test.ts CHANGED Viewed

@@ -15,6 +15,16 @@ describe("generateCommitMessageDetailed", () => {
         }],
       },
       new QuickResponseAdapter({
+        readLlmProvider: async () => ({
+          provider: "openai",
+          apiKey: "",
+          model: "",
+          baseUrl: "",
+          resolvedBaseUrl: "https://api.openai.com/v1",
+          enabled: false,
+          warning: null,
+          filePathDisplay: "~/.kanna/llm-provider.json",
+        }),
         runClaudeStructured: async () => ({
           subject: "  Add login UI.\nextra line",
           body: "  - wire form\n- add validation  ",
@@ -42,6 +52,16 @@ describe("generateCommitMessageDetailed", () => {
         }],
       },
       new QuickResponseAdapter({
+        readLlmProvider: async () => ({
+          provider: "openai",
+          apiKey: "",
+          model: "",
+          baseUrl: "",
+          resolvedBaseUrl: "https://api.openai.com/v1",
+          enabled: false,
+          warning: null,
+          filePathDisplay: "~/.kanna/llm-provider.json",
+        }),
         runClaudeStructured: async () => {
           throw new Error("Not authenticated")
         },

package/src/server/generate-commit-message.ts CHANGED Viewed

@@ -24,7 +24,7 @@ export interface GenerateCommitMessageResult {
   failureMessage: string | null
 }
-function summarizeFailures(failures: Array<{ provider: "claude" | "codex"; reason: string }>) {
+function summarizeFailures(failures: Array<{ provider: "openai" | "claude" | "codex"; reason: string }>) {
   if (failures.length === 0) return null
   return failures.map((failure) => failure.reason).join("; ")
 }

package/src/server/generate-title.ts CHANGED Viewed

@@ -29,7 +29,7 @@ export interface GenerateChatTitleResult {
   failureMessage: string | null
 }
-function summarizeFailures(failures: Array<{ provider: "claude" | "codex"; reason: string }>) {
+function summarizeFailures(failures: Array<{ provider: "openai" | "claude" | "codex"; reason: string }>) {
   if (failures.length === 0) return null
   return failures.map((failure) => failure.reason).join("; ")
 }

package/src/server/llm-provider.test.ts ADDED Viewed

@@ -0,0 +1,134 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { DEFAULT_OPENAI_SDK_MODEL, DEFAULT_OPENROUTER_SDK_MODEL } from "../shared/types"
+import {
+  normalizeLlmProviderSnapshot,
+  OPENAI_BASE_URL,
+  OPENROUTER_BASE_URL,
+  readLlmProviderSnapshot,
+  resolveLlmProviderBaseUrl,
+  writeLlmProviderSnapshot,
+} from "./llm-provider"
+let tempDirs: string[] = []
+const TEST_FILE_PATH = "/tmp/kanna-test-llm-provider.json"
+afterEach(async () => {
+  await Promise.all(tempDirs.map((dir) => rm(dir, { recursive: true, force: true })))
+  tempDirs = []
+})
+async function createTempFilePath() {
+  const dir = await mkdtemp(path.join(tmpdir(), "kanna-llm-provider-"))
+  tempDirs.push(dir)
+  return path.join(dir, "llm-provider.json")
+}
+describe("resolveLlmProviderBaseUrl", () => {
+  test("derives known provider URLs and preserves custom URLs", () => {
+    expect(resolveLlmProviderBaseUrl("openai", "")).toBe(OPENAI_BASE_URL)
+    expect(resolveLlmProviderBaseUrl("openrouter", "")).toBe(OPENROUTER_BASE_URL)
+    expect(resolveLlmProviderBaseUrl("custom", " https://example.com/v1 ")).toBe("https://example.com/v1")
+  })
+})
+describe("normalizeLlmProviderSnapshot", () => {
+  test("normalizes a valid custom provider config", () => {
+    expect(normalizeLlmProviderSnapshot({
+      provider: "custom",
+      apiKey: "  test-key  ",
+      model: "  gpt-test  ",
+      baseUrl: " https://example.com/v1 ",
+    }, TEST_FILE_PATH)).toEqual({
+      provider: "custom",
+      apiKey: "test-key",
+      model: "gpt-test",
+      baseUrl: "https://example.com/v1",
+      resolvedBaseUrl: "https://example.com/v1",
+      enabled: true,
+      warning: null,
+      filePathDisplay: TEST_FILE_PATH,
+    })
+  })
+  test("disables invalid configs with a warning", () => {
+    const snapshot = normalizeLlmProviderSnapshot({
+      provider: "custom",
+      apiKey: "test-key",
+      model: "gpt-test",
+      baseUrl: "",
+    }, TEST_FILE_PATH)
+    expect(snapshot.enabled).toBe(false)
+    expect(snapshot.warning).toContain("custom provider requires a baseUrl")
+  })
+})
+describe("readLlmProviderSnapshot", () => {
+  test("returns defaults when the file does not exist", async () => {
+    const filePath = await createTempFilePath()
+    expect(await readLlmProviderSnapshot(filePath)).toEqual({
+      provider: "openai",
+      apiKey: "",
+      model: DEFAULT_OPENAI_SDK_MODEL,
+      baseUrl: "",
+      resolvedBaseUrl: OPENAI_BASE_URL,
+      enabled: false,
+      warning: null,
+      filePathDisplay: filePath,
+    })
+  })
+  test("returns a warning when the file contains invalid json", async () => {
+    const filePath = await createTempFilePath()
+    await writeFile(filePath, "{not-json", "utf8")
+    const snapshot = await readLlmProviderSnapshot(filePath)
+    expect(snapshot.enabled).toBe(false)
+    expect(snapshot.warning).toContain("invalid JSON")
+  })
+  test("fills named-provider default models when the file omits them", async () => {
+    const filePath = await createTempFilePath()
+    await writeFile(filePath, JSON.stringify({
+      provider: "openrouter",
+      apiKey: "test-key",
+      baseUrl: null,
+    }), "utf8")
+    const snapshot = await readLlmProviderSnapshot(filePath)
+    expect(snapshot.model).toBe(DEFAULT_OPENROUTER_SDK_MODEL)
+    expect(snapshot.enabled).toBe(true)
+  })
+})
+describe("writeLlmProviderSnapshot", () => {
+  test("writes normalized config to disk", async () => {
+    const filePath = await createTempFilePath()
+    const snapshot = await writeLlmProviderSnapshot({
+      provider: "openrouter",
+      apiKey: " test-key ",
+      model: " openrouter/model ",
+      baseUrl: "ignored",
+    }, filePath)
+    expect(snapshot).toEqual({
+      provider: "openrouter",
+      apiKey: "test-key",
+      model: "openrouter/model",
+      baseUrl: "ignored",
+      resolvedBaseUrl: OPENROUTER_BASE_URL,
+      enabled: true,
+      warning: null,
+      filePathDisplay: filePath,
+    })
+    expect(await Bun.file(filePath).json()).toEqual({
+      provider: "openrouter",
+      apiKey: "test-key",
+      model: "openrouter/model",
+      baseUrl: null,
+    })
+  })
+})

package/src/server/llm-provider.ts ADDED Viewed

@@ -0,0 +1,207 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises"
+import { homedir } from "node:os"
+import path from "node:path"
+import OpenAI from "openai"
+import { getLlmProviderFilePath } from "../shared/branding"
+import {
+  DEFAULT_OPENAI_SDK_MODEL,
+  DEFAULT_OPENROUTER_SDK_MODEL,
+  type LlmProviderFile,
+  type LlmProviderKind,
+  type LlmProviderSnapshot,
+  type LlmProviderValidationResult,
+} from "../shared/types"
+export const OPENAI_BASE_URL = "https://api.openai.com/v1"
+export const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+const DEFAULT_PROVIDER: LlmProviderKind = "openai"
+function formatDisplayPath(filePath: string) {
+  const homePath = homedir()
+  if (filePath === homePath) return "~"
+  if (filePath.startsWith(`${homePath}${path.sep}`)) {
+    return `~${filePath.slice(homePath.length)}`
+  }
+  return filePath
+}
+function resolveProvider(value: unknown) {
+  if (value === "openai" || value === "openrouter" || value === "custom") {
+    return value
+  }
+  return null
+}
+function normalizeString(value: unknown) {
+  return typeof value === "string" ? value.trim() : ""
+}
+export function resolveLlmProviderBaseUrl(provider: LlmProviderKind, baseUrl: string) {
+  if (provider === "openai") return OPENAI_BASE_URL
+  if (provider === "openrouter") return OPENROUTER_BASE_URL
+  return baseUrl.trim()
+}
+export function resolveLlmProviderDefaultModel(provider: LlmProviderKind) {
+  if (provider === "openai") return DEFAULT_OPENAI_SDK_MODEL
+  if (provider === "openrouter") return DEFAULT_OPENROUTER_SDK_MODEL
+  return ""
+}
+export function normalizeLlmProviderSnapshot(
+  value: unknown,
+  filePath = getLlmProviderFilePath(homedir())
+): LlmProviderSnapshot {
+  const source = value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null
+  const warnings: string[] = []
+  if (!source) {
+    return createDefaultSnapshot(
+      filePath,
+      value === undefined || value === null ? null : "LLM provider file must contain a JSON object. Using defaults."
+    )
+  }
+  const provider = resolveProvider(source.provider)
+  const apiKey = normalizeString(source.apiKey)
+  const model = normalizeString(source.model)
+  const baseUrl = normalizeString(source.baseUrl)
+  if (!provider) {
+    warnings.push("provider must be one of openai, openrouter, or custom")
+  }
+  if (source.apiKey !== undefined && typeof source.apiKey !== "string") {
+    warnings.push("apiKey must be a string")
+  }
+  if (source.model !== undefined && typeof source.model !== "string") {
+    warnings.push("model must be a string")
+  }
+  if (source.baseUrl !== undefined && source.baseUrl !== null && typeof source.baseUrl !== "string") {
+    warnings.push("baseUrl must be a string or null")
+  }
+  if ((provider ?? DEFAULT_PROVIDER) === "custom" && !baseUrl) {
+    warnings.push("custom provider requires a baseUrl")
+  }
+  const normalizedProvider = provider ?? DEFAULT_PROVIDER
+  const resolvedModel = model || resolveLlmProviderDefaultModel(normalizedProvider)
+  const resolvedBaseUrl = resolveLlmProviderBaseUrl(normalizedProvider, baseUrl)
+  const enabled = warnings.length === 0 && apiKey.length > 0 && resolvedModel.length > 0 && resolvedBaseUrl.length > 0
+  return {
+    provider: normalizedProvider,
+    apiKey,
+    model: resolvedModel,
+    baseUrl,
+    resolvedBaseUrl,
+    enabled,
+    warning: warnings.length > 0 ? `Some LLM provider settings are invalid: ${warnings.join("; ")}` : null,
+    filePathDisplay: formatDisplayPath(filePath),
+  }
+}
+function createDefaultSnapshot(filePath: string, warning: string | null = null): LlmProviderSnapshot {
+  return {
+    provider: DEFAULT_PROVIDER,
+    apiKey: "",
+    model: DEFAULT_OPENAI_SDK_MODEL,
+    baseUrl: "",
+    resolvedBaseUrl: OPENAI_BASE_URL,
+    enabled: false,
+    warning,
+    filePathDisplay: formatDisplayPath(filePath),
+  }
+}
+export async function readLlmProviderSnapshot(filePath = getLlmProviderFilePath(homedir())) {
+  try {
+    const text = await readFile(filePath, "utf8")
+    if (!text.trim()) {
+      return createDefaultSnapshot(filePath, "LLM provider file was empty. Using defaults.")
+    }
+    return normalizeLlmProviderSnapshot(JSON.parse(text), filePath)
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === "ENOENT") {
+      return createDefaultSnapshot(filePath)
+    }
+    if (error instanceof SyntaxError) {
+      return createDefaultSnapshot(filePath, "LLM provider file is invalid JSON. Using defaults.")
+    }
+    throw error
+  }
+}
+export async function writeLlmProviderSnapshot(
+  value: Pick<LlmProviderFile, "provider" | "apiKey" | "model"> & { baseUrl: string },
+  filePath = getLlmProviderFilePath(homedir())
+) {
+  const snapshot = normalizeLlmProviderSnapshot(value, filePath)
+  const payload: LlmProviderFile = {
+    provider: snapshot.provider,
+    apiKey: snapshot.apiKey,
+    model: snapshot.model,
+    baseUrl: snapshot.provider === "custom" ? snapshot.baseUrl : null,
+  }
+  await mkdir(path.dirname(filePath), { recursive: true })
+  await writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8")
+  return snapshot
+}
+function toSerializableValue(value: unknown): unknown {
+  if (value === null || value === undefined) return value ?? null
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value
+  if (Array.isArray(value)) {
+    return value.map((entry) => toSerializableValue(entry))
+  }
+  if (value instanceof Error) {
+    return toSerializableValue(Object.fromEntries(
+      Object.getOwnPropertyNames(value).map((key) => [key, (value as unknown as Record<string, unknown>)[key]])
+    ))
+  }
+  if (typeof value === "object") {
+    const record = value as Record<string, unknown>
+    return Object.fromEntries(
+      Object.keys(record).map((key) => [key, toSerializableValue(record[key])])
+    )
+  }
+  return String(value)
+}
+export async function validateLlmProviderCredentials(
+  value: Pick<LlmProviderSnapshot, "provider" | "apiKey" | "model" | "baseUrl">
+): Promise<LlmProviderValidationResult> {
+  const snapshot = normalizeLlmProviderSnapshot(value)
+  if (!snapshot.enabled) {
+    return {
+      ok: false,
+      error: {
+        type: "config_error",
+        message: snapshot.warning ?? "LLM provider configuration is incomplete.",
+      },
+    }
+  }
+  try {
+    const client = new OpenAI({
+      apiKey: snapshot.apiKey,
+      baseURL: snapshot.resolvedBaseUrl,
+    })
+    await client.responses.create({
+      model: snapshot.model,
+      input: "Reply with ok.",
+      max_output_tokens: 5,
+    })
+    return {
+      ok: true,
+      error: null,
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      error: toSerializableValue(error),
+    }
+  }
+}