broapp 0.4.5 → 0.4.7

package/src/ai/shared/model-ref.ts

@@ -0,0 +1,139 @@
+/**
+ * A model reference: one string that names a model and, optionally, the
+ * provider that runs it.
+ *
+ * Written `<providerId>:<modelId>` — `ollama:qwen3:27b`,
+ * `openrouter:anthropic/claude-opus-5` — and split on the **first** colon,
+ * the convention the AI SDK's provider registry uses. The part before it
+ * qualifies the reference only when it is the id of a provider this build
+ * has; anything else is the whole string, a model of the provider in use,
+ * exactly as a bare id always was. So `qwen3:27b` with Ollama in use is still
+ * Ollama's `qwen3:27b`, and nothing stored before references existed changes
+ * meaning.
+ *
+ * One consequence, stated rather than hidden: a model of the provider in use
+ * whose own id begins with another provider's id and a colon cannot be reached
+ * by its bare id, because the prefix is read as that other provider. Written
+ * qualified — `<its own provider>:<id>` — it is reached, since only the first
+ * colon splits.
+ *
+ * Shared code, importing nothing, so the browser's pickers and the host's
+ * resolver read a reference the same way.
+ */
+
+/** A reference, split. `provider` is null when the reference names none. */
+export interface ModelRef {
+  provider: string | null;
+  modelId: string;
+}
+
+/**
+ * Split a reference into the provider it names and the provider's own model
+ * id. `providerIds` are the ids of the providers this build has; a prefix that
+ * is not one of them, or an empty half on either side of the colon, leaves the
+ * reference unqualified and whole.
+ */
+export function parseModelRef(ref: string, providerIds: readonly string[]): ModelRef {
+  const colon = ref.indexOf(':');
+  if (colon <= 0 || colon === ref.length - 1) return { provider: null, modelId: ref };
+  const provider = ref.slice(0, colon);
+  if (!providerIds.includes(provider)) return { provider: null, modelId: ref };
+  return { provider, modelId: ref.slice(colon + 1) };
+}
+
+/** Write a reference that names its provider. `parseModelRef` reads it back. */
+export function formatModelRef(provider: string, modelId: string): string {
+  return `${provider}:${modelId}`;
+}
+
+/** What {@link findModel} found for a reference. */
+export interface FoundModel<M> {
+  /** The provider the reference runs on: the one it names, else the one in use. */
+  provider: string | null;
+  /** The provider's own id for the model. */
+  modelId: string;
+  /** The listed model, or `null` when the list does not offer it. */
+  model: M | null;
+}
+
+/**
+ * Find a stored reference in a model list.
+ *
+ * Qualified, it matches that provider's model; bare, it matches the provider
+ * in use — the one in use *now*, so a bare id stored while another provider
+ * was in use never matches that other provider's model by accident. Every
+ * place that shows a stored reference goes through here, so a picker, a tier
+ * row and a task row cannot disagree about what it names.
+ *
+ * `providerIds` are every provider in the build, so a reference to one that is
+ * off (and so absent from the list) still reads as naming it. Without them,
+ * the providers the list and the one in use name are all that is known.
+ */
+export function findModel<M extends { provider: string; modelId: string }>(
+  ref: string,
+  models: readonly M[],
+  activeProvider: string | null,
+  providerIds: readonly string[] = [],
+): FoundModel<M> {
+  const known = new Set(providerIds);
+  for (const model of models) known.add(model.provider);
+  if (activeProvider !== null) known.add(activeProvider);
+  const parsed = parseModelRef(ref, [...known]);
+  const provider = parsed.provider ?? activeProvider;
+  const model = models.find((entry) => entry.provider === provider && entry.modelId === parsed.modelId) ?? null;
+  return { provider, modelId: parsed.modelId, model };
+}
+
+/** Where a provider runs, as the browser learns it from `ai.providersList`. */
+export interface ProviderPlace {
+  id: string;
+  label: string;
+  local: boolean;
+}
+
+/**
+ * The words that say where a provider runs: `on this computer`, or
+ * `sent to <label>`. Words, not a colour or an icon alone, wherever a model is
+ * chosen or named.
+ */
+export function whereItRuns(provider: Pick<ProviderPlace, 'label' | 'local'>): string {
+  return provider.local ? 'on this computer' : `sent to ${provider.label}`;
+}
+
+/** A stored reference, described for a person. */
+export interface ModelDescription {
+  /** The model's name when the list has it, else the reference's own model id. */
+  name: string;
+  /** `on this computer` or `sent to <label>`, or `null` when the provider is not known. */
+  where: string | null;
+  /** Said after the name when it cannot run: `not offered`, or `<label> is off`. */
+  problem: string | null;
+}
+
+/**
+ * Describe a stored reference: its name, where it runs, and what is wrong with
+ * it, if anything. `enabled` lists the providers turned on in Settings.
+ */
+export function describeModel<M extends { provider: string; modelId: string; label: string }>(
+  ref: string,
+  context: {
+    readonly models: readonly M[];
+    readonly providers: readonly ProviderPlace[];
+    readonly enabled: readonly string[];
+    readonly activeProvider: string | null;
+  },
+): ModelDescription {
+  const found = findModel(
+    ref,
+    context.models,
+    context.activeProvider,
+    context.providers.map((provider) => provider.id),
+  );
+  const place = context.providers.find((provider) => provider.id === found.provider) ?? null;
+  const name = found.model?.label ?? found.modelId;
+  const where = place === null ? null : whereItRuns(place);
+  if (place !== null && !context.enabled.includes(place.id)) {
+    return { name, where, problem: `${place.label} is off` };
+  }
+  return { name, where, problem: found.model === null ? 'not offered' : null };
+}

package/src/ai/shared/types.check.ts

@@ -18,8 +18,10 @@ import type {
   ChatEvent,
   ChatFile,
   ProviderInfo,
+  ProviderSettings,
   StoredMessage,
   Thread,
+  UnavailableProvider,
 } from './types.ts';
 
 type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
@@ -29,6 +31,12 @@ type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ?
 const settingsMatch: Equal<OperationOutput<AiContract, 'ai.settingsGet'>, AiSettings> = true;
 void settingsMatch;
 
+const providerSettingsMatch: Equal<
+  OperationOutput<AiContract, 'ai.settingsGet'>['providers'][number],
+  ProviderSettings
+> = true;
+void providerSettingsMatch;
+
 const settingsUpdateReturnsSettings: Equal<
   OperationOutput<AiContract, 'ai.settingsUpdate'>,
   AiSettings
@@ -41,6 +49,12 @@ const modelMatch: Equal<
 > = true;
 void modelMatch;
 
+const unavailableMatch: Equal<
+  OperationOutput<AiContract, 'ai.modelsList'>['unavailable'][number],
+  UnavailableProvider
+> = true;
+void unavailableMatch;
+
 const providerMatch: Equal<
   OperationOutput<AiContract, 'ai.providersList'>['providers'][number],
   ProviderInfo

package/src/ai/shared/types.ts

@@ -25,6 +25,15 @@ export interface BroappModel {
   };
 }
 
+/**
+ * A provider whose models are missing from `ai.modelsList`, or cut short, and
+ * why, in a sentence a person can read.
+ */
+export interface UnavailableProvider {
+  provider: string;
+  message: string;
+}
+
 /** A provider compiled into this application, as the browser sees it. */
 export interface ProviderInfo {
   id: string;
@@ -38,7 +47,33 @@ export interface ProviderInfo {
   defaultBaseUrl: string | null;
 }
 
-/** What the settings route returns. Never contains the key itself. */
+/**
+ * One provider's own settings, whether or not it is the one in use. Never
+ * contains the key itself.
+ */
+export interface ProviderSettings {
+  id: string;
+  baseUrl: string | null;
+  modelId: string | null;
+  /** Whether it may be sent anything. The provider in use always may. */
+  enabled: boolean;
+  hasKey: boolean;
+  keyHint: string | null;
+  /**
+   * True when its key and address are what it needs: a model reference naming
+   * it would run, given a model, once it is enabled. Neither the model nor
+   * `enabled` is part of this; each has its own field.
+   */
+  configured: boolean;
+}
+
+/**
+ * What the settings route returns. Never contains a key itself.
+ *
+ * The top-level fields are the provider in use — the one a turn runs on when
+ * nothing names another — so an application written against one provider
+ * reads what it always read.
+ */
 export interface AiSettings {
   provider: string | null;
   modelId: string | null;
@@ -46,10 +81,12 @@ export interface AiSettings {
   hasKey: boolean;
   /** Last four characters of the key, for the UI to show which key is set. */
   keyHint: string | null;
-  /** False means the key is held in memory only and forgotten on exit. */
+  /** False means every key is held in memory only and forgotten on exit. */
   remember: boolean;
   /** True when provider and model are both set and the provider's needs are met. */
   configured: boolean;
+  /** Every provider in this build, in the build's order. */
+  providers: ProviderSettings[];
 }
 
 /** How much ceremony a tool call needs before it runs. */
@@ -86,10 +123,13 @@ export interface ChatFile {
 /**
  * A stored conversation, without its messages.
  *
- * `modelId` is null for a conversation that follows Settings, and a model id
- * for one that has been pinned to a model of its own. The provider is never
- * part of a conversation: it is a Settings decision, because changing it
- * changes which key is used and whether anything leaves the computer.
+ * `modelId` is null for a conversation that follows Settings, and a model
+ * reference for one that has been pinned to a model of its own: bare, a model
+ * of the provider in use; `<provider>:<model>`, a model of any provider the
+ * person turned on (see `model-ref.ts`). It once could not name a provider,
+ * because changing provider changes which key is used and whether anything
+ * leaves the computer. That reason stands, and is why wherever a model is
+ * chosen the person must be told whether it runs on this computer.
  */
 export interface Thread {
   id: string;