broapp 0.4.6 → 0.4.7

package/src/ai/react/ai.css

@@ -337,6 +337,54 @@
   }
 }
 
+/*
+ * The two parts of the panel, "In use" and "Providers". Each provider is a
+ * `<details>` whose summary says where it runs and whether it is on, so the
+ * list reads without opening anything.
+ */
+.ai-settings__section {
+  display: flex;
+  flex-direction: column;
+  gap: 0.9rem;
+}
+
+.ai-settings__section-title {
+  margin: 0;
+  font-size: var(--ai-label-size);
+  font-weight: var(--ai-label-weight);
+  color: var(--text, #1b1a18);
+}
+
+.ai-settings__providers {
+  display: flex;
+  flex-direction: column;
+  border: var(--ai-border-width) solid var(--border, #e3e2df);
+  border-radius: var(--ai-control-radius);
+}
+
+.ai-settings__provider + .ai-settings__provider {
+  border-top: var(--ai-border-width) solid var(--border, #e3e2df);
+}
+
+.ai-settings__provider-summary {
+  padding: 0.6rem 0.75rem;
+  font-size: var(--ai-control-size);
+  color: var(--text, #1b1a18);
+  cursor: pointer;
+}
+
+.ai-settings__provider-summary:focus-visible {
+  outline: var(--ai-focus-ring-width) solid var(--ai-focus-ring);
+  outline-offset: var(--ai-focus-ring-offset);
+}
+
+.ai-settings__provider-body {
+  display: flex;
+  flex-direction: column;
+  gap: 0.9rem;
+  padding: 0.25rem 0.75rem 0.9rem;
+}
+
 /*
  * Always visible once a provider is chosen. "Where do my notes go" is not a
  * question a user should have to open a menu to answer.

package/src/ai/react/use-ai-models.ts

@@ -1,21 +1,23 @@
 /**
- * The models the configured provider offers.
+ * The models every provider turned on in Settings offers, in one list.
  *
- * Refetched whenever something that would change the answer changes — the
- * provider, its address, or whether a key is set. Not on every settings write:
- * choosing a model must not send the application back to the provider to ask
- * what the models are.
+ * Refetched whenever something that would change the answer changes — which
+ * providers are on, any of their addresses, or whether each has a key. Not on
+ * every settings write: choosing a model must not send the application back to
+ * every provider to ask what the models are.
  */
 import * as React from 'react';
 
 import { BroappError } from '../../shared/errors.ts';
-import type { BroappModel } from '../shared/types.ts';
+import type { BroappModel, UnavailableProvider } from '../shared/types.ts';
 
 import { useAiContext } from './provider.tsx';
 
 /** What {@link useAiModels} returns. */
 export interface AiModelsHook {
   readonly models: BroappModel[];
+  /** The providers that could not be read, or were cut short, each with its sentence. */
+  readonly unavailable: UnavailableProvider[];
   readonly pending: boolean;
   readonly error: BroappError | null;
   refresh(): Promise<void>;
@@ -24,17 +26,24 @@ export interface AiModelsHook {
 export function useAiModels(): AiModelsHook {
   const shared = useAiContext();
   const [models, setModels] = React.useState<BroappModel[]>([]);
+  const [unavailable, setUnavailable] = React.useState<UnavailableProvider[]>([]);
   const [pending, setPending] = React.useState(false);
   const [error, setError] = React.useState<BroappError | null>(null);
   const generation = React.useRef(0);
 
   const provider = shared.settings?.provider ?? null;
-  const baseUrl = shared.settings?.baseUrl ?? null;
-  const hasKey = shared.settings?.hasKey ?? false;
+  // One string for everything the answer depends on, so the effect runs when
+  // one of them changes and not when a model is chosen.
+  const reach = JSON.stringify(
+    (shared.settings?.providers ?? [])
+      .filter((entry) => entry.enabled)
+      .map((entry) => [entry.id, entry.baseUrl, entry.hasKey]),
+  );
 
   const refresh = React.useCallback(async (): Promise<void> => {
     if (provider === null) {
       setModels([]);
+      setUnavailable([]);
       return;
     }
     const mine = (generation.current += 1);
@@ -43,13 +52,15 @@ export function useAiModels(): AiModelsHook {
     try {
       const connected = await shared.client();
       const result = await connected.call('ai.modelsList', undefined);
-      // A slow answer for a provider the user has since changed must not
+      // A slow answer for providers the user has since changed must not
       // replace the list they are looking at now.
       if (generation.current !== mine) return;
       setModels(result.models);
+      setUnavailable(result.unavailable);
     } catch (cause) {
       if (generation.current !== mine) return;
       setModels([]);
+      setUnavailable([]);
       setError(
         cause instanceof BroappError
           ? cause
@@ -62,9 +73,9 @@ export function useAiModels(): AiModelsHook {
 
   React.useEffect(() => {
     void refresh();
-    // `baseUrl` and `hasKey` are not used inside `refresh`; they are here
-    // because changing either changes what the provider will answer.
-  }, [refresh, baseUrl, hasKey]);
+    // `reach` is not used inside `refresh`; it is here because changing it
+    // changes what the providers will answer.
+  }, [refresh, reach]);
 
-  return { models, pending, error, refresh };
+  return { models, unavailable, pending, error, refresh };
 }

package/src/ai/react/use-ai-settings.ts

@@ -32,7 +32,8 @@ export interface AiSettingsHook {
   readonly pending: boolean;
   readonly error: BroappError | null;
   update(patch: UpdatePatch): Promise<void>;
-  test(): Promise<ConnectionResult | null>;
+  /** Test the provider in use, or, given an id, that provider with its own address and key. */
+  test(provider?: string): Promise<ConnectionResult | null>;
   refresh(): Promise<void>;
 }
 
@@ -47,21 +48,25 @@ export function useAiSettings(): AiSettingsHook {
   const [pending, setPending] = React.useState(false);
   const [error, setError] = React.useState<BroappError | null>(null);
 
-  // The provider list cannot change while the application runs — it is what
-  // was compiled in — so it is fetched once.
-  const fetched = React.useRef(false);
+  // The providers cannot change while the application runs — they are what
+  // was compiled in — but whether each runs on this computer is a property of
+  // its address, so the list is read again when an address changes.
+  const addresses = JSON.stringify((shared.settings?.providers ?? []).map((entry) => [entry.id, entry.baseUrl]));
   React.useEffect(() => {
-    if (fetched.current) return;
-    fetched.current = true;
+    let current = true;
     void (async () => {
       try {
         const connected = await shared.client();
-        setProviders((await connected.call('ai.providersList', undefined)).providers);
+        const listed = (await connected.call('ai.providersList', undefined)).providers;
+        if (current) setProviders(listed);
       } catch (cause) {
-        setError(asBroappError(cause, 'The provider list could not be read.'));
+        if (current) setError(asBroappError(cause, 'The provider list could not be read.'));
       }
     })();
-  }, [shared]);
+    return () => {
+      current = false;
+    };
+  }, [shared, addresses]);
 
   const update = React.useCallback(
     async (patch: UpdatePatch): Promise<void> => {
@@ -79,12 +84,14 @@ export function useAiSettings(): AiSettingsHook {
     [shared],
   );
 
-  const test = React.useCallback(async (): Promise<ConnectionResult | null> => {
+  const test = React.useCallback(async (provider?: string): Promise<ConnectionResult | null> => {
     setPending(true);
     setError(null);
     try {
       const connected = await shared.client();
-      return await connected.call('ai.connectionTest', undefined);
+      return provider === undefined
+        ? await connected.call('ai.connectionTest', undefined)
+        : await connected.call('ai.providerTest', { provider });
     } catch (cause) {
       setError(asBroappError(cause, 'The connection could not be tested.'));
       return null;

package/src/ai/shared/contract.ts

@@ -40,6 +40,21 @@ const providerInfo = s.object({
   defaultBaseUrl: s.nullable(s.string()),
 });
 
+/** A provider whose models are missing from the list, and the sentence that says why. */
+const unavailableProvider = s.object({ provider: s.string(), message: s.string() });
+
+const connectionResult = s.object({ ok: s.boolean(), message: s.string(), latencyMs: s.number() });
+
+const providerSettings = s.object({
+  id: s.string(),
+  baseUrl: s.nullable(s.string()),
+  modelId: s.nullable(s.string()),
+  enabled: s.boolean(),
+  hasKey: s.boolean(),
+  keyHint: s.nullable(s.string()),
+  configured: s.boolean(),
+});
+
 const settings = s.object({
   provider: s.nullable(s.string()),
   modelId: s.nullable(s.string()),
@@ -48,6 +63,7 @@ const settings = s.object({
   keyHint: s.nullable(s.string()),
   remember: s.boolean(),
   configured: s.boolean(),
+  providers: s.array(providerSettings, { max: 50 }),
 });
 
 const chatTurn = s.object({
@@ -145,12 +161,18 @@ export const aiContract = defineContract({
     },
     'ai.settingsUpdate': {
       input: s.object({
+        // Makes this provider the one in use. Sent with `target`, only the same.
         provider: s.optional(s.string({ max: 64 })),
+        // The provider the fields below apply to; absent, the one in use.
+        target: s.optional(s.string({ max: 64 })),
         modelId: s.optional(s.string({ max: 200 })),
         baseUrl: s.optional(s.nullable(s.string({ max: 2000 }))),
         // Null clears the stored key; a string replaces it. It goes to the
         // secret store and is never read back out to the browser.
         apiKey: s.optional(s.nullable(s.string({ max: 4000 }))),
+        // Whether the target may be sent anything. The one in use cannot be
+        // turned off.
+        enabled: s.optional(s.boolean()),
         remember: s.optional(s.boolean()),
       }),
       output: settings,
@@ -163,14 +185,24 @@ export const aiContract = defineContract({
     },
     'ai.modelsList': {
       input: s.void(),
-      output: s.object({ models: s.array(model, { max: 1000 }) }),
-      summary: 'The models the configured provider offers.',
+      output: s.object({
+        // Every enabled provider's models, in the build's provider order.
+        models: s.array(model, { max: 1000 }),
+        // The providers that could not be read, or were cut short, and why.
+        unavailable: s.array(unavailableProvider, { max: 50 }),
+      }),
+      summary: 'The models every provider turned on in Settings offers.',
     },
     'ai.connectionTest': {
       input: s.void(),
-      output: s.object({ ok: s.boolean(), message: s.string(), latencyMs: s.number() }),
+      output: connectionResult,
       summary: 'Try the configured provider once and report what happened.',
     },
+    'ai.providerTest': {
+      input: s.object({ provider: s.string({ max: 64 }) }),
+      output: connectionResult,
+      summary: 'Try one provider with its own address and key, whether or not it is turned on.',
+    },
     'ai.chatConfirm': {
       input: s.object({ runId, callId: s.string({ max: 200 }), approve: s.boolean() }),
       output: s.object({ accepted: s.boolean() }),
@@ -237,10 +269,10 @@ export const aiContract = defineContract({
         // Images travel with the turn they arrive on. History keeps a
         // placeholder instead, because a transcript of base64 would not fit.
         files: s.optional(s.array(chatFile, { max: 4 })),
-        // The model for this turn only, and only *within* the configured
-        // provider. A provider is never overridden per turn: a different
-        // provider means a different key and a different answer to "does this
-        // leave my computer", and that stays a Settings decision.
+        // The model for this turn only, as a model reference: bare, a model
+        // of the provider in use; `<provider>:<model>`, a model of a provider
+        // the person turned on in Settings, with that provider's own key and
+        // address. A provider that is off is sent nothing.
         modelId: s.optional(s.string({ max: 200 })),
       }),
       event: chatEvent,

package/src/ai/shared/index.ts

@@ -6,6 +6,8 @@
  */
 export { aiContract } from './contract.ts';
 export type { AiContract } from './contract.ts';
+export { describeModel, findModel, formatModelRef, parseModelRef, whereItRuns } from './model-ref.ts';
+export type { FoundModel, ModelDescription, ModelRef, ProviderPlace } from './model-ref.ts';
 export type {
   AiSettings,
   BroappModel,
@@ -13,7 +15,9 @@ export type {
   ChatFile,
   ChatTurn,
   ProviderInfo,
+  ProviderSettings,
   StoredMessage,
   Thread,
   ToolPermission,
+  UnavailableProvider,
 } from './types.ts';

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;