@audiofool/moondog 0.2.0-beta.6 → 0.2.0

package/src/integrations/netease/ncm-cli-player.mjs

@@ -21,14 +21,11 @@ const KNOWN_SONGS = 300;
 
 const failure = (code, message) => Object.assign(new Error(message), { code });
 
-const searchPath = (environment) => [...new Set([
-  ...String(environment.PATH ?? "").split(path.delimiter).filter((folder) => path.isAbsolute(folder)),
-  ...EXTRA_FOLDERS,
-])];
+const folders = (value) => String(value ?? "").split(path.delimiter).filter((folder) => path.isAbsolute(folder));
+const searchPath = (environment) => [...new Set([...folders(environment.PATH), ...EXTRA_FOLDERS])];
 
-/** The ncm-cli executable on PATH or in Homebrew's folders, or null. */
-export async function findNcmCli({ environment = process.env } = {}) {
-  for (const folder of searchPath(environment)) {
+async function findIn(places) {
+  for (const folder of places) {
     const file = path.join(folder, "ncm-cli");
     try {
       if (!(await stat(file)).isFile()) continue;
@@ -39,18 +36,37 @@ export async function findNcmCli({ environment = process.env } = {}) {
   return null;
 }
 
+// Opened from Finder, the app has its login shell's PATH, which lacks the folders ~/.zshrc adds,
+// such as nvm's for npm's global commands. There, the listener's shell as Terminal opens it says.
+function terminalPath(environment) {
+  return new Promise((resolve) => {
+    execFile(environment.SHELL || "/bin/zsh", ["-ilc", 'printf "\\n__MOONDOG_PATH__%s\\n" "$PATH"'], { env: environment, timeout: 5_000 },
+      (_error, stdout) => resolve(folders(String(stdout ?? "").match(/__MOONDOG_PATH__(.+)/u)?.[1])));
+  });
+}
+
+/** ncm-cli and the PATH to run it with, which has the node it runs on, or null. */
+async function findNcmCli(environment) {
+  const places = searchPath(environment);
+  const file = await findIn(places);
+  if (file) return { file, places };
+  const terminal = await terminalPath(environment);
+  const found = await findIn(terminal);
+  return found ? { file: found, places: [...new Set([...terminal, ...places])] } : null;
+}
+
 // Runs one ncm-cli command and parses its JSON. ncm-cli reports most failures as
 // { success: false, message } with exit status 0. play prints no JSON when it starts a song,
 // so its answer is {}; the player's state says whether the song started.
 function cliRunner({ environment }) {
-  let found;
+  // Kept once found. The listener may install ncm-cli while Moondog runs, so a miss is looked for again.
+  let found = null;
   return async (args) => {
-    found ??= findNcmCli({ environment });
-    const command = await found;
-    if (!command) throw failure("netease_cli_missing", "ncm-cli is not installed. Install it with: npm install -g @music163/ncm-cli");
-    const env = { ...environment, PATH: searchPath(environment).join(path.delimiter) };
+    found ??= await findNcmCli(environment);
+    if (!found) throw failure("netease_cli_missing", "ncm-cli is not installed. Install it with: npm install -g @music163/ncm-cli");
+    const env = { ...environment, PATH: found.places.join(path.delimiter) };
     const stdout = await new Promise((resolve, reject) => {
-      execFile(command, args, { env, timeout: COMMAND_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024 }, (error, out) =>
+      execFile(found.file, args, { env, timeout: COMMAND_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024 }, (error, out) =>
         (error && !out ? reject(failure("netease_failed", `ncm-cli ${args[0]} failed: ${String(error.message).slice(0, 200)}`)) : resolve(String(out ?? ""))));
     });
     const start = stdout.indexOf("{");

package/src/memory/reflection-worker.mjs

@@ -16,7 +16,7 @@ function reflectionErrorCode(error) {
 function offlineRuntimeError(reason) {
   if (reason === "provider_authentication_required") {
     return new Error(
-      "The Memory Agent requires OpenAI Codex authentication. Run moondog auth login openai-codex first.",
+      "The Memory Agent's model needs a sign-in. Run /auth, or moondog auth login <provider>, first.",
     );
   }
   return new Error(

package/src/runtime/pi/authentication.mjs

@@ -1,10 +1,12 @@
-import { access } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
+import path from "node:path";
 
 import { createModels } from "@earendil-works/pi-ai";
 
-import { createPersistentCredentialStore, serviceApiKeyIds } from "./persistent-credential-store.mjs";
-import { apiKeyPiProviderIds, loadPiProvider } from "./provider-registry.mjs";
+import { createPersistentCredentialStore, resolveMoondogAuthFile, serviceApiKeyIds } from "./persistent-credential-store.mjs";
+import { apiKeyPiProviderIds, chatgptProviderId, loadPiProvider } from "./provider-registry.mjs";
 
 // Keys for services that are not models share the same sign-in and private store;
 // each one also needs its id in the store's serviceApiKeyIds.
@@ -13,11 +15,25 @@ export const serviceKeyProviders = Object.freeze([
 ]);
 
 export const supportedAuthProviderIds = Object.freeze([
-  "openai-codex",
   ...apiKeyPiProviderIds,
   ...serviceApiKeyIds,
 ]);
 
+// Sign in with ChatGPT names this installation to OpenAI by a lasting random ID, kept beside auth.json.
+async function installationId(directory) {
+  const file = path.join(directory, "installation-id");
+  try {
+    const saved = (await readFile(file, "utf8")).trim();
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(saved)) return saved;
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  const id = randomUUID();
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  await writeFile(file, `${id}\n`, { encoding: "utf8", mode: 0o600 });
+  return id;
+}
+
 export function createPiAuthContext(environment = process.env) {
   return {
     async env(name) {
@@ -104,7 +120,8 @@ export async function createPiAuthentication({
   };
 
   return {
-    async login(providerId, interaction) {
+    // method "oauth" signs in with ChatGPT, for OpenAI only; any other login saves an API key.
+    async login(providerId, interaction, { method = "api_key" } = {}) {
       const entry = service(providerId);
       if (entry) {
         interaction.signal?.throwIfAborted();
@@ -113,12 +130,16 @@ export async function createPiAuthentication({
         await credentials.modify(entry.id, async () => ({ type: "api_key", key: typeof key === "string" ? key.trim() : key }));
         return serviceStatus(entry);
       }
+      if (method === "oauth" && providerId !== chatgptProviderId) {
+        const error = new Error("Only OpenAI signs in with ChatGPT.");
+        error.code = "auth_provider_unsupported";
+        throw error;
+      }
       await ensureProvider(providerId);
-      await models.login(
-        providerId,
-        providerId === "openai-codex" ? "oauth" : "api_key",
-        interaction,
-      );
+      const deviceId = method === "oauth"
+        ? await installationId(credentials.directory ?? path.dirname(resolveMoondogAuthFile(environment))) : null;
+      await models.login(providerId, method === "oauth" ? "oauth" : "api_key", interaction,
+        method === "oauth" ? { getDeviceId: () => deviceId } : undefined);
       return status(providerId);
     },
 

package/src/runtime/pi/configured-runtime.mjs

@@ -1,10 +1,10 @@
-import { clampThinkingLevel, getSupportedThinkingLevels } from "@earendil-works/pi-ai";
+import { getSupportedThinkingLevels } from "@earendil-works/pi-ai";
 
 import { PiAgentRuntime } from "./agent-runtime.mjs";
 import { createPiAuthContext } from "./authentication.mjs";
 import { getPublicPiModelCatalog } from "./public-model-catalog.mjs";
 import { createPersistentCredentialStore } from "./persistent-credential-store.mjs";
-import { EFFORT_LEVELS, readPiRuntimeSelection } from "./runtime-settings.mjs";
+import { clampEffort, EFFORT_LEVELS, readPiRuntimeSelection } from "./runtime-settings.mjs";
 
 export class OfflineAgentRuntime {
   constructor(reason = "model_not_configured", selection) {
@@ -108,7 +108,7 @@ export async function createConfiguredRuntime(
     // Without a saved effort, keep Pi's default and send no effort setting.
     effort,
     effortLevels: getSupportedThinkingLevels(model),
-    thinkingLevel: effort ? clampThinkingLevel(model, effort) : undefined,
+    thinkingLevel: effort ? clampEffort(model, effort) : undefined,
     ...(toolTrace ? { toolTrace } : {}),
   });
 }

package/src/runtime/pi/custom-endpoints.mjs

@@ -0,0 +1,229 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { createProvider } from "@earendil-works/pi-ai";
+import { anthropicMessagesApi } from "@earendil-works/pi-ai/api/anthropic-messages.lazy";
+import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
+import { builtinModels } from "@earendil-works/pi-ai/providers/all";
+
+import { acquirePrivateFileLock, resolveMoondogAuthFile } from "./persistent-credential-store.mjs";
+
+// Endpoints the listener adds by address: any service that speaks OpenAI's Chat Completions or
+// Anthropic's Messages, such as DeepSeek, Kimi, GLM, OpenRouter, a company gateway or a model on
+// this Mac. Their keys stay in this private file. auth.json is read with a fixed set of providers
+// by older Moondogs, which would refuse the whole store with an entry they don't know.
+const DOCUMENT_VERSION = 1;
+const MAX_ENDPOINTS = 20;
+const MAX_MODELS = 500;
+const MAX_LISTING_BYTES = 2 * 1024 * 1024;
+const PREFIX = "endpoint-";
+export const ENDPOINT_FORMATS = Object.freeze(["openai", "anthropic"]);
+const apis = { openai: "openai-completions", anthropic: "anthropic-messages" };
+const transports = { openai: openAICompletionsApi, anthropic: anthropicMessagesApi };
+// Local servers often take no key, but the SDKs under Pi always send one.
+const NO_KEY = "moondog-no-key";
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+const printable = (value, max) => typeof value === "string" && value.length > 0 && value.length <= max && !/[\p{C}]/u.test(value);
+const plainId = (value, max) => printable(value, max) && !/\s/u.test(value);
+
+function endpointError(code, message, cause) {
+  const error = new Error(message, cause ? { cause } : undefined);
+  error.name = "MoondogRuntimeSettingsError";
+  error.code = code;
+  return error;
+}
+
+export const isEndpointProvider = (providerId) => typeof providerId === "string" && providerId.startsWith(PREFIX);
+
+// The address as the listener copied it, down to the base its format's SDK adds paths to: an
+// operation's own URL loses that operation, and Anthropic's SDK adds /v1 itself.
+export function normalizeBaseUrl(value, format) {
+  let url;
+  try { url = new URL(String(value ?? "").trim()); } catch { throw endpointError("endpoint_url_invalid", "Enter the endpoint's address, starting with https://."); }
+  if (url.username || url.password || url.search || url.hash) {
+    throw endpointError("endpoint_url_invalid", "Enter the address without a key, a query or a fragment in it.");
+  }
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && LOOPBACK.has(url.hostname))) {
+    throw endpointError("endpoint_url_invalid", "Use https://, or http:// only for a server on this Mac.");
+  }
+  url.pathname = url.pathname.replace(/\/(?:chat\/completions|responses|messages|models)\/?$/u, "").replace(/\/+$/u, "");
+  if (format === "anthropic") url.pathname = url.pathname.replace(/\/v1$/u, "");
+  return url.href.replace(/\/$/u, "");
+}
+
+export function parseModelIds(value) {
+  const ids = Array.isArray(value) ? value : String(value ?? "").split(/[\s,]+/u);
+  const kept = [...new Set(ids.map((id) => String(id).trim()).filter(Boolean))];
+  if (kept.some((id) => !plainId(id, 200))) throw endpointError("endpoint_models_invalid", "A model ID has spaces or characters an endpoint can't take.");
+  if (kept.length > MAX_MODELS) throw endpointError("endpoint_models_invalid", `An endpoint can list at most ${MAX_MODELS} models.`);
+  return kept;
+}
+
+function validEndpoint(value) {
+  if (!value || typeof value !== "object" || !isEndpointProvider(value.id) || !plainId(value.id, 60) ||
+      !printable(value.name, 60) || !ENDPOINT_FORMATS.includes(value.format) || typeof value.baseUrl !== "string" ||
+      (value.key !== undefined && !plainId(value.key, 8192)) || !Array.isArray(value.models)) {
+    throw endpointError("endpoint_store_invalid", "Moondog's endpoint file has an entry it can't read. Remove it in Settings, or delete endpoints.json.");
+  }
+  return { id: value.id, name: value.name, format: value.format, baseUrl: normalizeBaseUrl(value.baseUrl, value.format),
+    ...(value.key ? { key: value.key } : {}), models: parseModelIds(value.models) };
+}
+
+export function resolveEndpointsFile(environment = process.env) {
+  return path.join(path.dirname(resolveMoondogAuthFile(environment)), "endpoints.json");
+}
+
+export async function readEndpoints(environment = process.env) {
+  let source;
+  try {
+    source = await readFile(resolveEndpointsFile(environment), "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw endpointError("endpoint_store_invalid", "Moondog could not read its endpoints.", error);
+  }
+  let document;
+  try { document = JSON.parse(source); } catch (error) { throw endpointError("endpoint_store_invalid", "Moondog's endpoint file is not valid JSON.", error); }
+  if (!document || document.version !== DOCUMENT_VERSION || !Array.isArray(document.endpoints) || document.endpoints.length > MAX_ENDPOINTS) {
+    throw endpointError("endpoint_store_invalid", "Moondog's endpoint file uses an unsupported shape.");
+  }
+  return document.endpoints.map(validEndpoint);
+}
+
+// What a window may see of an endpoint: never its key.
+export function publicEndpoint({ key, ...shown }) {
+  return { ...shown, keySaved: Boolean(key) };
+}
+
+async function writeEndpoints(file, endpoints) {
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify({ version: DOCUMENT_VERSION, endpoints }, null, 2)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    await rename(temporary, file);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+
+const slug = (name) => name.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "").slice(0, 40) || "endpoint";
+
+// Adds an endpoint, or changes the one with input.id. A key left blank keeps the saved one only while
+// the address stays the same, so a key never travels to an address it wasn't entered for. Without
+// model IDs, the endpoint is asked for its list.
+export async function saveEndpoint(input, environment = process.env, { discover = discoverModels } = {}) {
+  const format = ENDPOINT_FORMATS.includes(input?.format) ? input.format : "openai";
+  const name = String(input?.name ?? "").trim();
+  if (!printable(name, 60)) throw endpointError("endpoint_name_invalid", "Give the endpoint a short name.");
+  const baseUrl = normalizeBaseUrl(input?.baseUrl, format);
+  const typedKey = String(input?.key ?? "").trim();
+  if (typedKey && !plainId(typedKey, 8192)) throw endpointError("endpoint_key_invalid", "The key has spaces or characters a key can't have.");
+  const typedModels = parseModelIds(input?.models);
+
+  const file = resolveEndpointsFile(environment);
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const release = await acquirePrivateFileLock(file);
+  try {
+    const endpoints = await readEndpoints(environment);
+    const previous = input?.id ? endpoints.find((endpoint) => endpoint.id === input.id) : undefined;
+    if (input?.id && !previous) throw endpointError("endpoint_unknown", "That endpoint is no longer saved.");
+    if (!previous && endpoints.length >= MAX_ENDPOINTS) throw endpointError("endpoint_limit", `Moondog keeps at most ${MAX_ENDPOINTS} endpoints.`);
+    const key = typedKey || (previous && previous.baseUrl === baseUrl && previous.format === format ? previous.key : undefined);
+    const models = typedModels.length ? typedModels : await discover({ format, baseUrl, key });
+    if (!models.length) throw endpointError("endpoint_models_missing", "The endpoint listed no models. Enter their IDs.");
+    let id = previous?.id;
+    if (!id) {
+      const base = `${PREFIX}${slug(name)}`;
+      id = base;
+      for (let count = 2; endpoints.some((endpoint) => endpoint.id === id); count++) id = `${base}-${count}`;
+    }
+    const saved = { id, name, format, baseUrl, ...(key ? { key } : {}), models };
+    const next = previous ? endpoints.map((endpoint) => (endpoint.id === id ? saved : endpoint)) : [...endpoints, saved];
+    await writeEndpoints(file, next);
+    return { endpoint: publicEndpoint(saved), typedModels: typedModels.length > 0 };
+  } finally {
+    await release();
+  }
+}
+
+export async function removeEndpoint(id, environment = process.env) {
+  const file = resolveEndpointsFile(environment);
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const release = await acquirePrivateFileLock(file);
+  try {
+    const endpoints = await readEndpoints(environment);
+    if (!endpoints.some((endpoint) => endpoint.id === id)) return false;
+    await writeEndpoints(file, endpoints.filter((endpoint) => endpoint.id !== id));
+    return true;
+  } finally {
+    await release();
+  }
+}
+
+// The model list an endpoint publishes, in its order: OpenAI's /models or Anthropic's /v1/models.
+// Its body and errors never reach the window; only whether it worked.
+export async function discoverModels({ format, baseUrl, key }, { fetchImpl = globalThis.fetch, timeoutMs = 8000 } = {}) {
+  const url = format === "anthropic" ? `${baseUrl}/v1/models?limit=1000` : `${baseUrl}/models`;
+  const headers = format === "anthropic"
+    ? { Accept: "application/json", "anthropic-version": "2023-06-01", ...(key ? { "x-api-key": key } : {}) }
+    : { Accept: "application/json", ...(key ? { Authorization: `Bearer ${key}` } : {}) };
+  let ids;
+  try {
+    const response = await fetchImpl(url, { headers, redirect: "error", credentials: "omit", signal: AbortSignal.timeout(timeoutMs) });
+    if (!response.ok || Number(response.headers.get("content-length")) > MAX_LISTING_BYTES) throw new Error(`HTTP ${response.status}`);
+    const text = await response.text();
+    if (text.length > MAX_LISTING_BYTES) throw new Error("oversized");
+    const document = JSON.parse(text);
+    ids = (Array.isArray(document?.data) ? document.data : Array.isArray(document?.models) ? document.models : [])
+      .map((entry) => (typeof entry === "string" ? entry : entry?.id)).filter((id) => typeof id === "string");
+  } catch (error) {
+    throw endpointError("endpoint_models_unavailable", "The endpoint didn't list its models. Check the address and key, or enter the model IDs.", error);
+  }
+  return parseModelIds(ids.slice(0, MAX_MODELS));
+}
+
+// A model Pi already knows by the same ID, such as deepseek-chat or anthropic/claude-sonnet-5, keeps
+// its name and limits; through the same kind of API it also keeps its thinking levels and request
+// details. Any other model is plain text without thinking, which every compatible server takes.
+let known;
+function knownModels() {
+  if (!known) {
+    known = new Map();
+    for (const model of builtinModels().getModels()) {
+      const list = known.get(model.id) ?? [];
+      list.push(model);
+      known.set(model.id, list);
+    }
+  }
+  return known;
+}
+
+function endpointModel(endpoint, id) {
+  const api = apis[endpoint.format];
+  const matches = knownModels().get(id) ?? [];
+  const same = matches.find((model) => model.api === api);
+  const match = same ?? matches[0];
+  return {
+    id, name: match?.name ?? id, provider: endpoint.id, api, baseUrl: endpoint.baseUrl,
+    reasoning: same?.reasoning === true,
+    input: match?.input ? [...match.input] : ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: match?.contextWindow ?? 128_000,
+    maxTokens: match?.maxTokens ?? 8192,
+    ...(same?.thinkingLevelMap ? { thinkingLevelMap: structuredClone(same.thinkingLevelMap) } : {}),
+    ...(same?.compat ? { compat: structuredClone(same.compat) } : {}),
+  };
+}
+
+export function addEndpoints(models, endpoints = []) {
+  for (const endpoint of endpoints) {
+    models.setProvider(createProvider({
+      id: endpoint.id, name: endpoint.name, baseUrl: endpoint.baseUrl,
+      models: endpoint.models.map((id) => endpointModel(endpoint, id)),
+      auth: { apiKey: { name: `${endpoint.name} key`, resolve: async () => ({ auth: { apiKey: endpoint.key ?? NO_KEY }, source: "stored credential" }) } },
+      api: transports[endpoint.format](),
+    }));
+  }
+  return models;
+}

package/src/runtime/pi/model-catalog.mjs

@@ -4,11 +4,10 @@ import { zaiProvider } from "@earendil-works/pi-ai/providers/zai";
 
 const zaiApiBaseUrl = "https://api.z.ai/api/paas/v4";
 const providerDisplayNames = {
-  anthropic: "Anthropic (Claude)",
+  anthropic: "Anthropic",
   moonshotai: "Moonshot AI (Kimi)",
   "moonshotai-cn": "Moonshot AI China (Kimi)",
-  openai: "OpenAI (GPT)",
-  xai: "xAI (Grok)",
+  xai: "xAI",
 };
 
 export function zaiApiProvider() {
@@ -28,6 +27,9 @@ export function zaiApiProvider() {
   });
 }
 
+// Saved selections may still name these; lists offer the canonical model instead.
+export const LEGACY_MODEL_ALIASES = Object.freeze(["deepseek-v4-flash", "deepseek-v4-flash-vision-exp"]);
+
 // Pi supplies canonical Flash metadata. Keep legacy IDs as aliases so saved
 // Moondog selections continue to resolve without rewriting the listener's settings.
 function currentDeepSeekModels(nativeModels) {
@@ -39,6 +41,8 @@ function currentDeepSeekModels(nativeModels) {
 
 export function createPiModels({ catalogModels, ...options } = {}) {
   const models = builtinModels(options);
+  // ChatGPT signs in through OpenAI's own provider now; Pi's older Codex route is not offered.
+  models.deleteProvider("openai-codex");
   models.setProvider(zaiApiProvider());
   for (const native of models.getProviders()) {
     if (native.id !== "deepseek" && !catalogModels?.has(native.id)) continue;

package/src/runtime/pi/model-list.mjs

@@ -0,0 +1,122 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+
+import { resolveMoondogAuthFile } from "./persistent-credential-store.mjs";
+
+// The models the listener keeps at hand: the window's model menu shows these, flat, in this order.
+// Which one answers by default stays in settings.json, which older Moondogs read with a fixed shape,
+// so the list lives in its own file beside it.
+const LIST_VERSION = 1;
+const MAX_MODELS = 40;
+const printable = (value, max) => typeof value === "string" && value.length > 0 && value.length <= max && !/[\p{C}\s]/u.test(value);
+
+function listError(message, cause) {
+  const error = new Error(message, cause ? { cause } : undefined);
+  error.name = "MoondogRuntimeSettingsError";
+  error.code = "model_list_invalid";
+  return error;
+}
+
+export const sameModel = (left, right) => Boolean(left && right) && left.provider === right.provider && left.model === right.model;
+
+export function normalizeModelList(value) {
+  if (!Array.isArray(value)) throw listError("Moondog's model list must be a list.");
+  const models = [];
+  for (const entry of value) {
+    const provider = typeof entry?.provider === "string" ? entry.provider.trim().toLowerCase() : "";
+    const model = typeof entry?.model === "string" ? entry.model.trim() : "";
+    if (!printable(provider, 80) || !printable(model, 200)) throw listError("Moondog's model list has an entry without a provider and model.");
+    if (!models.some((kept) => sameModel(kept, { provider, model }))) models.push({ provider, model });
+  }
+  if (models.length > MAX_MODELS) throw listError(`Moondog keeps at most ${MAX_MODELS} models in its list.`);
+  return models;
+}
+
+export function resolveModelListFile(environment = process.env) {
+  return path.join(path.dirname(resolveMoondogAuthFile(environment)), "models.json");
+}
+
+// Undefined until the listener first changes the list; the window then starts it from the default.
+export async function readModelList(environment = process.env) {
+  let source;
+  try {
+    source = await readFile(resolveModelListFile(environment), "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return undefined;
+    throw listError("Moondog could not read its model list.", error);
+  }
+  let document;
+  try {
+    document = JSON.parse(source);
+  } catch (error) {
+    throw listError("Moondog's model list is not valid JSON.", error);
+  }
+  if (!document || typeof document !== "object" || document.version !== LIST_VERSION) {
+    throw listError("Moondog's model list uses an unsupported shape.");
+  }
+  return normalizeModelList(document.models);
+}
+
+export async function writeModelList(models, environment = process.env) {
+  const normalized = normalizeModelList(models);
+  const file = resolveModelListFile(environment);
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  // Another Moondog may read the list at any moment, so it never sees half a file.
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify({ version: LIST_VERSION, models: normalized }, null, 2)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    await rename(temporary, file);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+  return normalized;
+}
+
+// The model each conversation was given in the window's menu, by conversation id, so a conversation
+// keeps its own model across launches; every other one answers with the default. The oldest go first
+// past a few hundred.
+const MAX_CONVERSATIONS = 500;
+const resolveConversationModelsFile = (environment) => path.join(path.dirname(resolveMoondogAuthFile(environment)), "conversation-models.json");
+
+export async function readConversationModels(environment = process.env) {
+  let document;
+  try {
+    document = JSON.parse(await readFile(resolveConversationModelsFile(environment), "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return {};
+    throw listError("Moondog could not read the models chosen for conversations.", error);
+  }
+  if (!document || document.version !== LIST_VERSION || !document.conversations || typeof document.conversations !== "object") {
+    throw listError("Moondog's conversation models use an unsupported shape.");
+  }
+  const kept = {};
+  for (const [session, value] of Object.entries(document.conversations).slice(-MAX_CONVERSATIONS)) {
+    if (!printable(session, 100)) continue;
+    const [entry] = normalizeModelList([value]);
+    kept[session] = { ...entry, ...(typeof value.effort === "string" && printable(value.effort, 20) ? { effort: value.effort } : {}) };
+  }
+  return kept;
+}
+
+// One change at a time, so two quick choices never lose either.
+let writing = Promise.resolve();
+export function writeConversationModel(session, selection, environment = process.env) {
+  const next = writing.then(async () => {
+    const saved = await readConversationModels(environment).catch(() => ({}));
+    delete saved[session];
+    if (selection) saved[session] = { provider: selection.provider, model: selection.model, ...(selection.effort ? { effort: selection.effort } : {}) };
+    const conversations = Object.fromEntries(Object.entries(saved).slice(-MAX_CONVERSATIONS));
+    const file = resolveConversationModelsFile(environment);
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+      await writeFile(temporary, `${JSON.stringify({ version: LIST_VERSION, conversations }, null, 2)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+      await rename(temporary, file);
+    } finally {
+      await rm(temporary, { force: true });
+    }
+  });
+  writing = next.catch(() => {});
+  return next;
+}