@olares/lares-core 0.15.0

package/router/catalog-sync.js

@@ -0,0 +1,87 @@
+import { createInFlightCoalescer } from "../tools/async.js";
+import {
+  LLM_SETTINGS_NS,
+  ROUTER_PROVIDER_ID,
+  catalogSettingsOps,
+  defaultNeedsRepair,
+  fetchChatModels,
+  listedCatalog,
+  parseDefaultModelRequest,
+  pickDefaultModel,
+  unregisteredRouterFailure,
+} from "./models.js";
+
+function messageOf(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * @param {{
+ *   mutateSettings: (ns: string, ops: unknown[]) => Promise<void>,
+ *   currentSelection: () => { provider: string, model: string },
+ *   saveSelection: (next: { provider: string, model: string }) => Promise<void>,
+ * }} ports
+ */
+async function performRefresh(ports) {
+  const models = await fetchChatModels();
+  await ports.mutateSettings(LLM_SETTINGS_NS, catalogSettingsOps(models));
+  const current = ports.currentSelection();
+  if (defaultNeedsRepair(current, models)) {
+    await ports.saveSelection({ provider: ROUTER_PROVIDER_ID, model: pickDefaultModel(models).id });
+  }
+  return models;
+}
+
+const coalesceRefresh = createInFlightCoalescer();
+
+export function refreshCatalog(ports) {
+  return coalesceRefresh(() => performRefresh(ports));
+}
+
+/**
+ * @param {{
+ *   listProviders: () => { id: string, name: string }[],
+ *   listModels: (provider: string) => Promise<{ id: string, name: string, description?: string }[]>,
+ * }} ports
+ */
+export async function listCatalog(ports) {
+  const provider = ports.listProviders().find((entry) => entry.id === ROUTER_PROVIDER_ID);
+  if (!provider) {
+    return { models: [], failures: unregisteredRouterFailure() };
+  }
+  try {
+    return { models: listedCatalog(provider, await ports.listModels(ROUTER_PROVIDER_ID)), failures: [] };
+  } catch (err) {
+    return {
+      models: [],
+      failures: [{ provider: ROUTER_PROVIDER_ID, name: provider.name, message: messageOf(err) }],
+    };
+  }
+}
+
+export function currentDefault(ports) {
+  const { provider, model } = ports.currentSelection();
+  return { provider, model };
+}
+
+/**
+ * @param {{
+ *   resolveCallConfig: (asked: { provider: string, model: string }) => Promise<{ provider: string, model: string }>,
+ *   saveSelection: (next: { provider: string, model: string }) => Promise<void>,
+ * }} ports
+ */
+export async function saveDefault(ports, request) {
+  const asked = parseDefaultModelRequest(request);
+  let resolved;
+  try {
+    resolved = await ports.resolveCallConfig(asked);
+  } catch (err) {
+    throw Object.assign(new Error(messageOf(err)), { code: "model_unavailable", status: 400 });
+  }
+  await ports.saveSelection({ provider: resolved.provider, model: resolved.model });
+  return { provider: resolved.provider, model: resolved.model };
+}
+
+export function catalogState(ports, listed) {
+  return { default: currentDefault(ports), models: listed.models, failures: listed.failures };
+}

package/router/catalog.d.ts

@@ -0,0 +1,15 @@
+export interface RouterCatalogRow {
+  id: string;
+  name: string;
+  mode: string | null;
+  /** Whether Router declares native image input for this chat model. */
+  supportsVision: boolean;
+  /** pi-ai level → Router wire spelling, or null when the model takes no effort. */
+  reasoningEfforts: Record<string, string> | null;
+  /** Tokens one request may span, or null when Router states none. */
+  contextWindow: number | null;
+  /** Longest reply the model can produce, or null when Router states none. */
+  maxTokens: number | null;
+}
+
+export function routerCatalogRows(payload: unknown): RouterCatalogRow[];

package/router/catalog.js

@@ -0,0 +1,73 @@
+const SAFE_MODEL_ID = /^[^\u0000-\u001f\u007f]{1,512}$/;
+/** pi-ai's thinking vocabulary; a Router level outside it has no wire spelling to declare. */
+const THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+
+/**
+ * The capability flags one catalog row declares, named without Router's
+ * `supports_` prefix. Router spells them differently per surface — the gateway
+ * catalog lists bare tokens (`vision`), its admin API a `supports_*`-keyed
+ * dict — and both spellings mean the same flag.
+ */
+function capabilities(item) {
+  const declared = Array.isArray(item.supports)
+    ? item.supports
+    : item.supports && typeof item.supports === "object"
+      ? Object.keys(item.supports).filter((key) => item.supports[key] === true)
+      : [];
+  const flags = new Set();
+  for (const entry of declared) {
+    const flag = String(entry ?? "").trim().toLowerCase().replace(/^supports_/, "");
+    if (flag) flags.add(flag);
+  }
+  if (item.supports_vision === true) flags.add("vision");
+  return flags;
+}
+
+/**
+ * The effort levels Router advertises for one model, keyed by pi-ai level with
+ * Router's own spelling as the wire value. A dict offering nothing beyond `off`
+ * is no capability at all, and pi-ai rejects it.
+ */
+function reasoningEfforts(item, flags) {
+  if (!flags.has("reasoning_effort")) return null;
+  const options = Array.isArray(item.reasoning_effort?.options) ? item.reasoning_effort.options : [];
+  const efforts = {};
+  for (const option of options) {
+    const level = String(option ?? "").trim().toLowerCase();
+    if (THINKING_LEVELS.has(level)) efforts[level] = level;
+  }
+  return Object.keys(efforts).some((level) => level !== "off") ? efforts : null;
+}
+
+/**
+ * A token count Router states, or null when it states none. Router omits the
+ * key rather than sending a zero, so anything non-positive here is a payload
+ * that disagrees with its own contract and is treated as silence — a window of
+ * zero would fail pi-ai's own validation on the way in.
+ */
+function tokenCount(value) {
+  return Number.isInteger(value) && value > 0 ? value : null;
+}
+
+export function routerCatalogRows(payload) {
+  if (!payload || typeof payload !== "object" || !Array.isArray(payload.data)) return [];
+  const rows = [];
+  const seen = new Set();
+  for (const item of payload.data) {
+    if (!item || typeof item !== "object") continue;
+    const id = String(item.id ?? "").trim();
+    if (!SAFE_MODEL_ID.test(id) || seen.has(id)) continue;
+    seen.add(id);
+    const flags = capabilities(item);
+    rows.push({
+      id,
+      name: id,
+      mode: String(item.mode ?? "").trim().toLowerCase() || null,
+      supportsVision: flags.has("vision"),
+      reasoningEfforts: reasoningEfforts(item, flags),
+      contextWindow: tokenCount(item.context_size),
+      maxTokens: tokenCount(item.max_output_tokens),
+    });
+  }
+  return rows;
+}

package/router/gateway.d.ts

@@ -0,0 +1,4 @@
+export function routerGatewayUrl(env?: NodeJS.ProcessEnv): string;
+export function routerShimBaseUrl(env?: NodeJS.ProcessEnv): string;
+export function routerAuthHeaders(apiKey: string | null | undefined, olaresAppId: string | null | undefined): Record<string, string>;
+export function routerHeaders(env?: NodeJS.ProcessEnv): Record<string, string>;

package/router/gateway.js

@@ -0,0 +1,21 @@
+export function routerGatewayUrl(env = process.env) {
+  return (env.LLM_GATEWAY_URL ?? "http://router-svc.router-shared/v1").replace(/\/+$/, "");
+}
+
+export function routerShimBaseUrl(env = process.env) {
+  const configured = env.LARES_LLM_BASE_URL?.trim();
+  if (configured) return configured.replace(/\/+$/, "");
+  return `http://127.0.0.1:${env.PORT ?? 8080}/llm/v1`;
+}
+
+export function routerAuthHeaders(apiKey, olaresAppId) {
+  if (apiKey?.trim()) return { authorization: `Bearer ${apiKey.trim()}` };
+  return { "x-caller-appid": olaresAppId?.trim() || "lares" };
+}
+
+export function routerHeaders(env = process.env) {
+  return {
+    ...routerAuthHeaders(env.LARES_ROUTER_API_KEY, env.OLARES_APP_ID),
+    accept: "application/json",
+  };
+}

package/router/models-client.js

@@ -0,0 +1,39 @@
+import { createSnapshotStore } from "../tools/async.js";
+
+export const API = "/api/lares/models";
+
+const settings = createSnapshotStore();
+
+async function readPayload(res, path) {
+  const payload = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(payload?.error?.message ?? payload?.error?.code ?? `${path} → ${res.status}`);
+  }
+  return payload;
+}
+
+export function rememberedModelSettings() {
+  return settings.peek();
+}
+
+export async function loadModelSettings(options = {}) {
+  return settings.load(fetchState, options);
+}
+
+export async function fetchState() {
+  return readPayload(await fetch(API), "/");
+}
+
+export async function refreshModels() {
+  return settings.remember(await readPayload(await fetch(`${API}/refresh`, { method: "POST" }), "/refresh"));
+}
+
+/** @param {{ provider: string, model: string }} selection */
+export async function setDefaultModel(selection) {
+  const res = await fetch(`${API}/default`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(selection),
+  });
+  return settings.remember(await readPayload(res, "/default"));
+}

package/router/models.d.ts

@@ -0,0 +1,16 @@
+import type { RouterCatalogRow } from "./catalog.js";
+
+export type RouterModelEntry = RouterCatalogRow;
+export function isChatModelId(id: string): boolean;
+export function isChatModel(model: RouterModelEntry): boolean;
+export function modelsFromRouterCatalog(payload: unknown): RouterModelEntry[];
+export function pickChatModelId(catalog: RouterModelEntry[]): string | null;
+export function isPlaceholderModelId(id: string | null | undefined): boolean;
+export function chatModelsFromRouterCatalog(payload: unknown): Array<Record<string, unknown> & { id: string; name: string }>;
+export function pickDefaultModel<T extends { id: string }>(models: T[]): T | null;
+export function fetchChatModels(): Promise<Array<Record<string, unknown> & { id: string; name: string }>>;
+export function fetchRouterModels(env: {
+  routerUrl?: string | null;
+  routerApiKey?: string | null;
+  olaresAppId?: string | null;
+}): Promise<RouterModelEntry[]>;

package/router/models.js

@@ -0,0 +1,133 @@
+import { routerCatalogRows } from "./catalog.js";
+import { routerAuthHeaders, routerGatewayUrl, routerShimBaseUrl } from "./gateway.js";
+
+export const ROUTER_PROVIDER_ID = "olares-router";
+export const LLM_SETTINGS_NS = "llm-pi-ai";
+
+const NON_CHAT_HINTS = /embed|whisper|tts|speech|ocr|clip|stt|asr|transcri/i;
+const PLACEHOLDER_MODEL = /^(?:default|deepseek-v4-(?:flash|pro))$/i;
+
+export function isChatModelId(id) {
+  return !NON_CHAT_HINTS.test(id);
+}
+
+export function isChatModel(model) {
+  return model.mode ? model.mode === "chat" : isChatModelId(model.id);
+}
+
+export function modelsFromRouterCatalog(payload) {
+  return routerCatalogRows(payload);
+}
+
+function isMtpModelId(id) {
+  return /\bmtp\b/i.test(id);
+}
+
+export function pickChatModelId(catalog) {
+  const chat = catalog.filter(isChatModel);
+  return chat.find((model) => isMtpModelId(model.id))?.id ?? chat[0]?.id ?? null;
+}
+
+export function isPlaceholderModelId(id) {
+  if (!id) return true;
+  const trimmed = id.trim();
+  return !trimmed || PLACEHOLDER_MODEL.test(trimmed);
+}
+
+export function chatModelsFromRouterCatalog(payload) {
+  return routerCatalogRows(payload)
+    .filter(isChatModel)
+    .map(({ id, name, supportsVision, reasoningEfforts, contextWindow, maxTokens }) => ({
+      id,
+      name,
+      ...(supportsVision ? { input: ["text", "image"] } : {}),
+      ...(reasoningEfforts === null ? {} : { reasoningEfforts }),
+      ...(contextWindow === null ? {} : { contextWindow }),
+      ...(maxTokens === null ? {} : { maxTokens }),
+    }));
+}
+
+export function pickDefaultModel(models) {
+  return models.find((model) => isMtpModelId(model.id)) ?? models[0] ?? null;
+}
+
+export function catalogFailure(code, status, message) {
+  return Object.assign(new Error(message), { code, status });
+}
+
+export async function fetchChatModels() {
+  const response = await fetch(`${routerShimBaseUrl()}/models`, {
+    headers: { accept: "application/json" },
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!response.ok) {
+    throw catalogFailure("router_unavailable", 503, `Router /models returned ${response.status}`);
+  }
+  return chatModelsFromRouterCatalog(await response.json());
+}
+
+/**
+ * GET ${LLM_GATEWAY_URL}/models with in-cluster app identity.
+ * @param {{ routerUrl?: string | null, routerApiKey?: string | null, olaresAppId?: string | null }} env
+ */
+export async function fetchRouterModels(env) {
+  const routerUrl = String(env.routerUrl ?? "").replace(/\/+$/, "") || routerGatewayUrl();
+  const res = await fetch(`${routerUrl}/models`, {
+    method: "GET",
+    headers: {
+      ...routerAuthHeaders(env.routerApiKey, env.olaresAppId),
+      accept: "application/json",
+    },
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) throw new Error(`Router /models returned ${res.status}`);
+  return modelsFromRouterCatalog(await res.json());
+}
+
+export function parseDefaultModelRequest(request) {
+  const model = typeof request?.model === "string" ? request.model.trim() : "";
+  if (!model) throw catalogFailure("bad_request", 400, "model is required");
+  const asked = typeof request?.provider === "string" ? request.provider.trim() : "";
+  if (asked && asked !== ROUTER_PROVIDER_ID) {
+    throw catalogFailure("bad_request", 400, "provider must be olares-router");
+  }
+  if (isPlaceholderModelId(model)) {
+    throw catalogFailure("model_unavailable", 400, "Router has no configured chat model");
+  }
+  return { provider: ROUTER_PROVIDER_ID, model };
+}
+
+export function defaultNeedsRepair(current, models) {
+  return models.length > 0
+    && (current.provider !== ROUTER_PROVIDER_ID || !models.some((model) => model.id === current.model));
+}
+
+export function listedCatalogModel(provider, model) {
+  if (isPlaceholderModelId(model.id)) return null;
+  return {
+    provider: ROUTER_PROVIDER_ID,
+    providerName: provider.name,
+    id: model.id,
+    name: model.name || model.id,
+    ...(model.description ? { description: model.description } : {}),
+    ...(model.reasoningEfforts ? { reasoningEfforts: model.reasoningEfforts } : {}),
+    ...(model.reasoning ? { reasoning: model.reasoning } : {}),
+  };
+}
+
+export function catalogSettingsOps(models) {
+  return [{ op: "set", path: ["providers", ROUTER_PROVIDER_ID, "models"], value: models }];
+}
+
+export function unregisteredRouterFailure() {
+  return [{ provider: ROUTER_PROVIDER_ID, name: "Olares Router", message: "provider is not registered" }];
+}
+
+export function listedCatalog(provider, models) {
+  const listed = [];
+  for (const model of models) {
+    const entry = listedCatalogModel(provider, model);
+    if (entry) listed.push(entry);
+  }
+  return listed;
+}

package/router/search.js

@@ -0,0 +1,142 @@
+import { routerCatalogRows } from "./catalog.js";
+import { routerGatewayUrl, routerHeaders } from "./gateway.js";
+
+export class SearchError extends Error {
+  constructor(message, code, options) {
+    super(message, options);
+    this.code = code;
+  }
+}
+
+export const SEARCH_WEB_CODES = {
+  no_model: "WEB_PROVIDER_CONFIGURED_UNAVAILABLE",
+  empty_query: "WEB_PROVIDER_ERROR",
+  aborted: "WEB_ABORTED",
+  timeout: "WEB_PROVIDER_ERROR",
+  credential: "WEB_PROVIDER_CREDENTIAL_MISSING",
+  failed: "WEB_PROVIDER_ERROR",
+};
+
+export function searchWebErrorCode(code) {
+  return SEARCH_WEB_CODES[code] ?? "WEB_PROVIDER_ERROR";
+}
+
+export function searchModelsFromRouterCatalog(payload) {
+  return routerCatalogRows(payload)
+    .filter((model) => model.mode === "search")
+    .map(({ id, name }) => ({ id, name }));
+}
+
+export function searchSourcesFromRouter(payload) {
+  if (!payload || typeof payload !== "object" || !Array.isArray(payload.results)) return [];
+  const sources = [];
+  for (const item of payload.results) {
+    if (sources.length >= 10) break;
+    if (!item || typeof item !== "object") continue;
+    const url = String(item.url ?? "").trim();
+    if (!url || url.length > 2_048) continue;
+    try {
+      const parsed = new URL(url);
+      if (!["http:", "https:"].includes(parsed.protocol)) continue;
+    } catch {
+      continue;
+    }
+    const title = String(item.title ?? "").trim().slice(0, 500);
+    const snippet = String(item.snippet ?? item.content ?? "").trim().slice(0, 5_000);
+    const publishedAt = String(item.publishedAt ?? item.published_at ?? "").trim().slice(0, 100);
+    sources.push({
+      url,
+      ...(title ? { title } : {}),
+      ...(snippet ? { snippet } : {}),
+      ...(publishedAt ? { publishedAt } : {}),
+    });
+  }
+  return sources;
+}
+
+const DEFAULT_TIMEOUT_MS = 20_000;
+
+export async function fetchRouterSearchModels() {
+  const response = await fetch(`${routerGatewayUrl()}/models`, {
+    method: "GET",
+    headers: routerHeaders(),
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!response.ok) {
+    throw Object.assign(new Error(`Router /models returned ${response.status}`), {
+      code: "router_unavailable",
+      status: 503,
+    });
+  }
+  return searchModelsFromRouterCatalog(await response.json());
+}
+
+/**
+ * @param {string} model
+ * @param {string} query
+ * @param {{ maxResults?: number, signal?: AbortSignal, timeoutMs?: number }} [opts]
+ */
+export async function routerSearch(model, query, opts = {}) {
+  const selectedModel = model.trim();
+  const q = query.trim();
+  if (!selectedModel) {
+    throw new SearchError("No Router search service selected", "no_model");
+  }
+  if (!q) throw new SearchError("query is required", "empty_query");
+
+  const controller = new AbortController();
+  let timedOut = false;
+  const timeoutMs = Number.isFinite(opts.timeoutMs)
+    ? Math.max(1, Number(opts.timeoutMs))
+    : DEFAULT_TIMEOUT_MS;
+  const onAbort = () => controller.abort(opts.signal?.reason);
+  if (opts.signal) {
+    if (opts.signal.aborted) {
+      throw new SearchError("Router search aborted", "aborted", { cause: opts.signal.reason });
+    }
+    opts.signal.addEventListener("abort", onAbort, { once: true });
+  }
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort(new Error("timeout"));
+  }, timeoutMs);
+
+  try {
+    const response = await fetch(`${routerGatewayUrl()}/search`, {
+      method: "POST",
+      redirect: "error",
+      headers: {
+        ...routerHeaders(),
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        model: selectedModel,
+        query: q,
+        max_results: Math.max(1, Math.min(Number(opts.maxResults ?? 5) || 5, 10)),
+      }),
+      signal: controller.signal,
+    });
+    if (response.status === 401 || response.status === 403) {
+      throw new SearchError("Router rejected Lares search access", "credential");
+    }
+    if (!response.ok) {
+      throw new SearchError(`Router search returned ${response.status}`, "failed");
+    }
+    return {
+      sources: searchSourcesFromRouter(await response.json()),
+      truncated: false,
+    };
+  } catch (err) {
+    if (err instanceof SearchError) throw err;
+    if (opts.signal?.aborted) {
+      throw new SearchError("Router search aborted", "aborted", { cause: err });
+    }
+    if (timedOut) {
+      throw new SearchError("Router search timed out", "timeout", { cause: err });
+    }
+    throw new SearchError(`Router search request failed: ${String(err)}`, "failed", { cause: err });
+  } finally {
+    clearTimeout(timer);
+    opts.signal?.removeEventListener("abort", onAbort);
+  }
+}

package/router/session-model.js

@@ -0,0 +1,143 @@
+export function isComposerModelAvailable(subagentAddress) {
+  return subagentAddress === undefined;
+}
+
+export function bindComposerModelDirectory(directory, available) {
+  return {
+    available,
+    directory: directory.store,
+    load() {
+      if (!available) return Promise.resolve();
+      return directory.load().catch(() => {});
+    },
+    select(selection) {
+      if (!available) return Promise.resolve(false);
+      return directory.select(selection).then(
+        () => true,
+        () => false,
+      );
+    },
+  };
+}
+
+export function findListedModel(groups, current) {
+  if (!current) return undefined;
+  for (const group of groups) {
+    for (const model of group.models) {
+      if (group.id === current.provider && model.id === current.model) return model;
+    }
+  }
+  return undefined;
+}
+
+export function isSameSessionModel(current, group, model) {
+  return Boolean(current && current.provider === group.id && current.model === model.id);
+}
+
+export function currentEffortId(current, reasoning) {
+  return current?.reasoningEffort ?? reasoning?.defaultEffort;
+}
+
+const EFFORT_ORDER = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+
+/** Router catalog dict `{ low: "low" }` → the effort menu shape the switcher already uses. */
+export function reasoningFromEfforts(raw) {
+  if (!raw || typeof raw !== "object") return undefined;
+  if (Array.isArray(raw.efforts)) {
+    return raw.efforts.length ? raw : undefined;
+  }
+  const efforts = [];
+  for (const id of EFFORT_ORDER) {
+    if (raw[id] != null) efforts.push({ id, name: id });
+  }
+  if (!efforts.length) {
+    for (const id of Object.keys(raw)) {
+      if (typeof id === "string" && id) efforts.push({ id, name: id });
+    }
+  }
+  if (!efforts.length) return undefined;
+  return {
+    efforts,
+    defaultEffort: efforts.find((row) => row.id !== "off")?.id ?? efforts[0].id,
+  };
+}
+
+export function reasoningOfModel(model) {
+  return reasoningFromEfforts(model?.reasoning ?? model?.reasoningEfforts);
+}
+
+export function modelSwitchSelection(group, model) {
+  return {
+    provider: group.id,
+    model: model.id,
+    ...(model.reasoning?.defaultEffort === undefined ? {} : { reasoningEffort: model.reasoning.defaultEffort }),
+  };
+}
+
+export function effortSwitchSelection(current, level) {
+  return {
+    provider: current.provider,
+    model: current.model,
+    ...(level === undefined ? {} : { reasoningEffort: level }),
+  };
+}
+
+export function effortDisplayLabel(reasoning, effortId, defaultLabel) {
+  if (reasoning === undefined) return undefined;
+  if (effortId === undefined) return defaultLabel;
+  return reasoning.efforts.find((level) => level.id === effortId)?.name ?? effortId;
+}
+
+export function sessionModelLabel(currentModel, current, selectLabel) {
+  return currentModel?.name ?? current?.model ?? selectLabel;
+}
+
+export function effortMenuRows(reasoning, defaultLabel) {
+  return effortMenuItems(reasoning).map((item) =>
+    item.providerDefault
+      ? { key: "provider-default", id: undefined, name: defaultLabel }
+      : { key: `effort:${item.id}`, id: item.id, name: item.name, description: item.description },
+  );
+}
+
+export function effortMenuItems(reasoning) {
+  if (reasoning === undefined) return [];
+  const items = [];
+  if (reasoning.defaultEffort === undefined) {
+    items.push({ id: undefined, providerDefault: true });
+  }
+  for (const effort of reasoning.efforts) {
+    items.push({
+      id: effort.id,
+      providerDefault: false,
+      name: effort.name,
+      description: effort.description,
+    });
+  }
+  return items;
+}
+
+export function selectionKey(selection) {
+  return `${selection.provider}\u0000${selection.model ?? selection.id}`;
+}
+
+export function groupModelsByProvider(models) {
+  const groups = [];
+  const index = new Map();
+  for (const model of models) {
+    let group = index.get(model.provider);
+    if (group === undefined) {
+      group = { provider: model.provider, models: [] };
+      index.set(model.provider, group);
+      groups.push(group);
+    }
+    group.models.push(model);
+  }
+  return groups;
+}
+
+export function catalogDefaultReady(models, defaultSelection) {
+  if (!defaultSelection) return false;
+  const current = selectionKey(defaultSelection);
+  return models.some((model) => selectionKey({ provider: model.provider, model: model.id }) === current);
+}