broapp 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "broapp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Build tooling and runtime for local applications made of a Bun host, a browser UI, and a Brobridge connection between them",
   "license": "MIT",

package/src/ai/host/adapter.ts

@@ -50,7 +50,10 @@ export interface ProviderAdapter {
   /** Stable id, stored in settings: `'anthropic'`, `'ollama'`, `'fake'`. */
   readonly id: string;
   readonly label: string;
-  readonly needs: { readonly apiKey: boolean; readonly baseUrl: 'required' | 'optional' | 'none' };
+  readonly needs: {
+    readonly apiKey: 'required' | 'optional' | 'none';
+    readonly baseUrl: 'required' | 'optional' | 'none';
+  };
   readonly defaultBaseUrl: string | null;
   /** Whether requests stay on this machine under this config. */
   local(config: AdapterConfig): boolean;
@@ -58,7 +61,7 @@ export interface ProviderAdapter {
   models(config: AdapterConfig, signal: AbortSignal): Promise<BroappModel[]>;
   /** Cheapest possible proof the config works. Must reject with {@link AdapterError}. */
   test(config: AdapterConfig, signal: AbortSignal): Promise<void>;
-  /** The AI SDK model. Only `broapp/ai/host` calls this. */
+  /** The AI SDK model. Only `broapp/ai/host` calls this; other host code asks `Ai.model()`. */
   model(config: AdapterConfig, modelId: string): LanguageModel;
 }
 

package/src/ai/host/create-ai.ts

@@ -10,6 +10,7 @@
  * `mount` has an implementation for every route in the contract, which it
  * insists on.
  */
+import type { LanguageModel } from 'ai';
 import type { Bridge } from 'brobridge';
 
 // Imported from the host entry point rather than from `host/app.ts` directly:
@@ -17,8 +18,8 @@ import type { Bridge } from 'brobridge';
 // is what makes a browser bundle of `broapp/ai/host` fail to build. Bun's
 // browser target polyfills `node:fs`, so the file stores alone would not stop
 // this code from being bundled into a page.
-import { createReservedHostApp } from '../../host/index.ts';
-import type { HostApp, HostLogger } from '../../host/app.ts';
+import { createPendingApprovals, createReservedHostApp } from '../../host/index.ts';
+import type { HostApp, HostLogger, StreamSink } from '../../host/app.ts';
 import { publicError } from '../../shared/errors.ts';
 import { aiContract, type AiContract } from '../shared/contract.ts';
 import type { ProviderInfo } from '../shared/types.ts';
@@ -26,15 +27,81 @@ import type { ProviderInfo } from '../shared/types.ts';
 import { AdapterError, toPublicError, type AdapterConfig, type ProviderAdapter } from './adapter.ts';
 import { createRegistry, type Registry } from './registry.ts';
 import { runChat, type RunDeps } from './run.ts';
+import type { ChatEvent } from './run-types.ts';
 import { createFileSecretStore, createMemorySecretStore } from './secrets.ts';
 import { createSettingsStore } from './settings.ts';
-import { createConfirmations, type AiContextProviders, type AiTool } from './tool.ts';
+import { openThreads, type ThreadStore } from './threads.ts';
+import { GUARDED, type AiContextProviders, type AiTool, type ContextDocument } from './tool.ts';
+
+/** How a turn went, beyond whether it ended well. */
+export interface RunEndDetail {
+  readonly usage?: { readonly inputTokens: number; readonly outputTokens: number };
+  /** Tool round trips the turn made. */
+  readonly steps: number;
+  readonly ms: number;
+}
+
+/**
+ * What one turn was given, after the budget. Documents are exactly what the
+ * model saw.
+ *
+ * Reported before the model is called, so a listener can write down the turn's
+ * inputs with the identity they had then rather than reconstruct them later
+ * from settings that may since have changed.
+ */
+export interface DeliveredContext {
+  readonly system: string;
+  readonly documents: readonly ContextDocument[];
+  /** The person's message for this turn, which the system prompt does not carry. */
+  readonly message: string;
+  /** The provider and model the turn was sent to. */
+  readonly model: { readonly provider: string; readonly id: string };
+}
+
+/** One turn run in-process by {@link Ai.turn}. */
+export interface InProcessTurn {
+  readonly runId: string;
+  readonly message: string;
+  /** The model for this turn, within the configured provider. */
+  readonly modelId?: string;
+}
+
+/** How {@link Ai.turn} is answered and stopped. */
+export interface InProcessTurnOptions {
+  /**
+   * The answer to each question the gate asks during the turn.
+   *
+   * The caller is the person's stand-in, so it decides exactly as the person
+   * would have: the gate still asks, and still records the answer.
+   */
+  readonly answer: (question: { readonly tool: string; readonly input: unknown }) => boolean;
+  /** Aborting it cancels the turn, as a browser's cancel would. */
+  readonly signal?: AbortSignal;
+  readonly onEvent?: (event: ChatEvent) => void;
+}
+
+/** How an in-process turn ended, and everything it emitted. */
+export interface InProcessTurnResult {
+  readonly status: 'succeeded' | 'failed' | 'cancelled';
+  readonly events: readonly ChatEvent[];
+  /** The reason a turn that could not start gave, such as no provider being set up. */
+  readonly error?: string;
+}
 
 /** What the application is, in the words a model is given. */
 export interface AiAppDescription {
   readonly name: string;
   readonly purpose: string;
   readonly terminology?: readonly string[];
+  /**
+   * Extra standing instructions, appended verbatim after the purpose.
+   *
+   * For an assistant whose job needs more than a sentence to describe — the
+   * shape of a workspace it edits, a sequence it has to follow, things it may
+   * not do. It is host-authored text, not anything a browser or a model
+   * supplied, and it goes in front of the documents rather than among them.
+   */
+  readonly instructions?: string;
 }
 
 /** Options for {@link createAi}. */
@@ -53,6 +120,28 @@ export interface CreateAiOptions {
   readonly maxSteps?: number;
   /** How long a `confirm` tool waits for the user. Default 300_000 ms. */
   readonly confirmTimeoutMs?: number;
+  /**
+   * Called once when a chat turn ends, however it ends.
+   *
+   * Autoapp's run store uses it to close the record the gate has been writing
+   * steps into: the browser's run identifier is the prefix of every request
+   * identifier the turn produced, so this is the one signal that ties the two
+   * together. An application that does not record runs leaves it unset.
+   */
+  readonly onRunEnd?: (
+    runId: string,
+    status: 'succeeded' | 'failed' | 'cancelled',
+    summary: string,
+    detail?: RunEndDetail,
+  ) => void;
+  /**
+   * Called once per turn, after the context budget and before the model, with
+   * what the model is about to be given.
+   *
+   * A hook that throws is logged and ignored: recording a turn is never a
+   * reason to fail it.
+   */
+  readonly onContext?: (runId: string, delivered: DeliveredContext) => void;
 }
 
 /**
@@ -68,11 +157,42 @@ const TOOL_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_.]*$/;
 export interface Ai {
   mount(bridge: Bridge): void;
   abortAll(reason: string): void;
+  /**
+   * Release what the layer holds open. Call it from the application's
+   * shutdown, beside `abortAll`.
+   *
+   * Today that is the conversation store: closing it checkpoints the WAL, so
+   * what is left on disk is one complete database rather than one that needs
+   * its sidecars. Calling it twice is harmless, and an application that never
+   * opened a conversation has nothing to close.
+   */
+  close(): void;
   readonly activeStreams: number;
   /** For tests, and for applications that read settings on the host. */
   readonly registry: Registry;
+  /**
+   * The configured model, for host code that needs one outside a chat turn.
+   *
+   * Resolved the same way a turn resolves it, so a caller is told "AI is not
+   * set up yet" in the same words, and always a model instance — never a
+   * string the AI SDK would send to its gateway.
+   */
+  model(override?: { readonly modelId?: string }): Promise<LanguageModel>;
+  /**
+   * Run one chat turn in this process, without a bridge or a browser.
+   *
+   * For scripts that drive the engineer themselves, such as a replay. It is
+   * the `ai.chat` route's own loop — the same tools, gate, context providers
+   * and hooks — with a sink that collects the events instead of writing them to
+   * a socket, and `answer` standing where the person's click would.
+   */
+  turn(turn: InProcessTurn, options: InProcessTurnOptions): Promise<InProcessTurnResult>;
 }
 
+/** How long an in-process answer waits for its question to be registered. */
+const ANSWER_ATTEMPTS = 200;
+const ANSWER_INTERVAL_MS = 5;
+
 /** How long a provider is given to answer a listing or a connection test. */
 const PROVIDER_TIMEOUT_MS = 20_000;
 
@@ -93,10 +213,19 @@ export function createAi(options: CreateAiOptions): Ai {
     }
     seen.add(adapter.id);
   }
-  for (const name of Object.keys(options.tools ?? {})) {
+  for (const [name, definition] of Object.entries(options.tools ?? {})) {
     if (!TOOL_NAME_PATTERN.test(name)) {
       throw new TypeError(`tool name ${JSON.stringify(name)} must be letters, digits, "_" or "."`);
     }
+    // A tool is host code that a model gets to trigger. Whether it asked
+    // anybody first is not visible in its type, so the brand is required
+    // rather than hoped for: an application cannot hand a model an ungated
+    // capability by forgetting one wrapper.
+    if ((definition as { [GUARDED]?: true })[GUARDED] !== true) {
+      throw new TypeError(
+        `tool ${JSON.stringify(name)} does not pass the gate; build it with guardedTool()`,
+      );
+    }
   }
 
   // Both stores are built once and kept. `remember` chooses between them, and
@@ -162,7 +291,7 @@ export function createAi(options: CreateAiOptions): Ai {
     }
   });
 
-  const confirmations = createConfirmations();
+  const approvals = createPendingApprovals(options.logger);
   const runDeps: RunDeps = {
     registry,
     app: options.app,
@@ -171,15 +300,36 @@ export function createAi(options: CreateAiOptions): Ai {
     contextBudgetChars: options.contextBudgetChars ?? DEFAULT_CONTEXT_BUDGET_CHARS,
     maxSteps: options.maxSteps ?? DEFAULT_MAX_STEPS,
     confirmTimeoutMs: options.confirmTimeoutMs ?? DEFAULT_CONFIRM_TIMEOUT_MS,
-    confirmations,
+    approvals,
+    ...(options.onRunEnd === undefined ? {} : { onRunEnd: options.onRunEnd }),
+    ...(options.onContext === undefined ? {} : { onContext: options.onContext }),
     logger: options.logger ?? console,
   };
 
   host.stream('ai.chat', (params, sink) => runChat(params, sink, runDeps));
+  // The wire shape is unchanged: a run and a call name the question, and
+  // `accepted` says whether anybody was waiting on it. What changed is where
+  // the answer goes — into the same approval table the gate asks.
   host.operation('ai.chatConfirm', ({ runId, callId, approve }) => ({
-    accepted: confirmations.answer(runId, callId, approve),
+    accepted:
+      approvals.answer({ requestId: `${runId}:${callId}`, approved: approve }) === 'accepted',
   }));
 
+  // Opened on the first conversation route and not before: an application
+  // whose user never opens the panel should not find a database in its data
+  // directory, and `createAi` is built unconditionally by every application
+  // that offers AI at all.
+  let threads: ThreadStore | null = null;
+  const threadStore = (): ThreadStore => (threads ??= openThreads(options.dataDir));
+
+  host.operation('ai.threadsList', () => ({ threads: threadStore().list() }));
+  host.operation('ai.threadsCreate', (input) => threadStore().create(input));
+  host.operation('ai.threadsGet', ({ id }) => threadStore().get(id));
+  host.operation('ai.threadsSave', (input) => threadStore().save(input));
+  host.operation('ai.threadsUpdate', (input) => threadStore().update(input));
+  host.operation('ai.threadsDelete', ({ id }) => ({ deleted: threadStore().remove(id) }));
+  host.operation('ai.threadsClear', () => ({ deleted: threadStore().clear() }));
+
   /** The current provider config, or the "not set up" error. */
   async function requireConfig(): Promise<{ adapter: ProviderAdapter; config: AdapterConfig }> {
     const current = await registry.currentConfig();
@@ -192,9 +342,87 @@ export function createAi(options: CreateAiOptions): Ai {
   return {
     mount: (bridge: Bridge) => host.mount(bridge),
     abortAll: (reason: string) => host.abortAll(reason),
+    close: () => {
+      threads?.close();
+      threads = null;
+    },
     get activeStreams() {
       return host.activeStreams;
     },
     registry,
+    model: async (override) => {
+      const { adapter, config, modelId } = await registry.resolve(override);
+      return adapter.model(config, modelId);
+    },
+    turn: async (turn, turnOptions) => {
+      const controller = new AbortController();
+      const relay = (): void => controller.abort(turnOptions.signal?.reason);
+      turnOptions.signal?.addEventListener('abort', relay, { once: true });
+      if (turnOptions.signal?.aborted === true) relay();
+
+      const events: ChatEvent[] = [];
+      /**
+       * Answer a question once the approval table holds it.
+       *
+       * The `confirm` event is emitted, and awaited, before the run's approver
+       * registers the question, so an answer given inside `emit` would find
+       * nobody waiting. This waits for it, briefly, the way a person's click
+       * necessarily arrives later.
+       */
+      const settle = async (requestId: string, approved: boolean): Promise<void> => {
+        for (let attempt = 0; attempt < ANSWER_ATTEMPTS; attempt += 1) {
+          if (approvals.answer({ requestId, approved }) !== 'unknown') return;
+          await Bun.sleep(ANSWER_INTERVAL_MS);
+        }
+      };
+      const sink: StreamSink<ChatEvent> = {
+        signal: controller.signal,
+        sessionId: 'in-process',
+        emit(event) {
+          if (controller.signal.aborted) return Promise.reject(new Error('stream is no longer open'));
+          events.push(event);
+          turnOptions.onEvent?.(event);
+          if (event.type === 'confirm') {
+            // The gate's request id is `<runId>:<callId>`, which is what an
+            // event without one would have named.
+            const requestId = event.requestId ?? `${turn.runId}:${event.callId}`;
+            void settle(requestId, turnOptions.answer({ tool: event.tool ?? '', input: event.input }));
+          }
+          return Promise.resolve();
+        },
+      };
+
+      let status: InProcessTurnResult['status'] | null = null;
+      const onRunEnd = runDeps.onRunEnd;
+      try {
+        await runChat(
+          {
+            runId: turn.runId,
+            message: turn.message,
+            refs: [],
+            history: [],
+            ...(turn.modelId === undefined ? {} : { modelId: turn.modelId }),
+          },
+          sink,
+          {
+            ...runDeps,
+            // The turn's own ending is what this returns; whoever the layer
+            // was built to tell is still told.
+            onRunEnd: (runId, ended, summary, detail) => {
+              status = ended;
+              onRunEnd?.(runId, ended, summary, detail);
+            },
+          },
+        );
+        return { status: status ?? 'succeeded', events };
+      } catch (cause) {
+        // A turn that could not start — no provider set up, most often — ends
+        // failed with the sentence the browser would have been shown.
+        const error = String(cause instanceof Error ? cause.message : cause);
+        return { status: status ?? 'failed', events, error };
+      } finally {
+        turnOptions.signal?.removeEventListener('abort', relay);
+      }
+    },
   };
 }

package/src/ai/host/fake.ts

@@ -48,6 +48,13 @@ export interface FakeAdapterOptions {
   readonly script?: readonly FakeStep[];
   /** Delay between chunks, so a cancel test can catch a stream mid-flight. */
   readonly chunkDelayMs?: number;
+  /**
+   * Whether the default model says it can read images. Default `false`.
+   *
+   * The default stays `false` so a test that does not mention images keeps
+   * proving that a turn with images is refused by a model that cannot see.
+   */
+  readonly vision?: boolean;
 }
 
 /** A fake adapter, plus what the test wants to know about it afterwards. */
@@ -60,12 +67,12 @@ export interface FakeAdapter extends ProviderAdapter {
   readonly aborted: number;
 }
 
-function defaultModel(providerId: string): BroappModel {
+function defaultModel(providerId: string, vision: boolean): BroappModel {
   return {
     provider: providerId,
     modelId: 'fake-1',
     label: 'Fake 1',
-    capabilities: { tools: true, vision: false, structuredOutput: true },
+    capabilities: { tools: true, vision, structuredOutput: true },
   };
 }
 
@@ -127,7 +134,7 @@ function chunksFor(step: FakeStep, callIndex: number): StreamPart[] {
 /** Build an adapter that needs no provider. */
 export function createFakeAdapter(options: FakeAdapterOptions = {}): FakeAdapter {
   const id = options.id ?? 'fake';
-  const models = options.models ?? [defaultModel(id)];
+  const models = options.models ?? [defaultModel(id, options.vision === true)];
   const script = options.script ?? [{ kind: 'text', chunks: ['fake reply'] } as const];
   const steps = flatten(script);
   const delay = options.chunkDelayMs ?? 0;
@@ -140,7 +147,7 @@ export function createFakeAdapter(options: FakeAdapterOptions = {}): FakeAdapter
   const adapter: FakeAdapter = {
     id,
     label: 'Fake provider',
-    needs: { apiKey: options.needsKey === true, baseUrl: 'none' },
+    needs: { apiKey: options.needsKey === true ? 'required' : 'none', baseUrl: 'none' },
     defaultBaseUrl: null,
     // Nothing leaves the process, so this is true whatever the configuration.
     local: () => true,

package/src/ai/host/from-contract.ts

@@ -7,17 +7,20 @@
  * that does not exist, and a change to an operation's input reaches the tool
  * description without anybody remembering to update it.
  *
- * The permission split is the important part. `read` operations run as soon as
- * the model asks; `confirm` operations wait for the user. Nothing is a tool
- * unless it is named here, so the default for an application's surface is that
- * the model cannot reach it.
+ * The lists here *select*; they no longer decide. What a call is allowed to do
+ * is the route's own `effect`, and the gate reads it from the contract. The
+ * list a route sits in has to agree with what it declares, and a route that
+ * declares nothing takes the list's word for it — which is how an application
+ * written before effects existed still says what it meant. Nothing is a tool
+ * unless it is named here, so the default for an application's surface is
+ * still that the model cannot reach it.
  */
 import type { HostApp } from '../../host/app.ts';
+import type { Effect } from '../../shared/contract.ts';
 import type { AnyContract, OperationName } from '../../shared/contract.ts';
 import type { JsonSchema } from '../../shared/schema.ts';
-import type { ToolPermission } from '../shared/types.ts';
 
-import type { AiTool } from './tool.ts';
+import { GUARDED, type GuardedTool } from './tool.ts';
 
 /** Which operations a model may call, and how much ceremony each needs. */
 export interface ContractToolAllowList<C extends AnyContract> {
@@ -25,12 +28,15 @@ export interface ContractToolAllowList<C extends AnyContract> {
   readonly confirm?: readonly OperationName<C>[];
 }
 
+/** What each list means about a route that does not declare an effect. */
+const IMPLIED: Record<'read' | 'confirm', Effect> = { read: 'read', confirm: 'write' };
+
 /** Build tools from operations the contract already describes. */
 export function fromContract<C extends AnyContract>(
   contract: C,
   app: HostApp<C>,
   allow: ContractToolAllowList<C>,
-): Record<string, AiTool> {
+): Record<string, GuardedTool> {
   const read = allow.read ?? [];
   const confirm = allow.confirm ?? [];
 
@@ -41,12 +47,12 @@ export function fromContract<C extends AnyContract>(
     );
   }
 
-  const tools: Record<string, AiTool> = {};
-  const groups: readonly (readonly [readonly OperationName<C>[], ToolPermission])[] = [
+  const tools: Record<string, GuardedTool> = {};
+  const groups: readonly (readonly [readonly OperationName<C>[], 'read' | 'confirm'])[] = [
     [read, 'read'],
     [confirm, 'confirm'],
   ];
-  for (const [routes, permission] of groups) {
+  for (const [routes, list] of groups) {
     for (const route of routes) {
       const spec = contract.operations[route];
       if (spec === undefined) {
@@ -59,6 +65,17 @@ export function fromContract<C extends AnyContract>(
           `operation ${JSON.stringify(route)} needs a summary before it can be offered to a model`,
         );
       }
+      const declared = spec.effect;
+      // A list that disagrees with the contract is a misunderstanding about
+      // what an operation does, and the two readings differ in exactly the way
+      // that matters: one asks the user and the other does not. Neither is
+      // safe to guess at, so it is refused where a developer can see it.
+      if (declared !== undefined && declared !== IMPLIED[list] && !(list === 'confirm' && declared === 'external')) {
+        throw new TypeError(
+          `operation ${JSON.stringify(route)} is listed as a ${list} tool but declares effect ${JSON.stringify(declared)}`,
+        );
+      }
+      const effect: Effect = declared ?? IMPLIED[list];
       const describe = (spec.input as { toJsonSchema?: () => JsonSchema }).toJsonSchema;
       if (typeof describe !== 'function') {
         throw new TypeError(
@@ -71,13 +88,16 @@ export function fromContract<C extends AnyContract>(
       // lost by turning it back into "no argument" here.
       const takesNothing = spec.input.kind === 'void';
       tools[route] = {
+        [GUARDED]: true,
         description: spec.summary,
         inputSchema: describe.call(spec.input),
-        permission,
-        // `invoke` validates the input and applies the same error boundary a
-        // call from the browser gets, so a model's arguments are no more
-        // trusted than a tab's.
-        execute: (input) => app.invoke(route, takesNothing ? undefined : input),
+        effect,
+        // `invoke` validates the input, guards it and applies the same error
+        // boundary a call from the browser gets, so a model's arguments are no
+        // more trusted than a tab's. The hint is what the list decided, and it
+        // only applies where the contract itself is silent.
+        execute: (input, envelope) =>
+          app.invoke(route, takesNothing ? undefined : input, { ...envelope, effectHint: effect }),
       };
     }
   }

package/src/ai/host/index.ts

@@ -7,7 +7,17 @@
  * follows this import fails loudly instead.
  */
 export { createAi } from './create-ai.ts';
-export type { Ai, AiAppDescription, CreateAiOptions } from './create-ai.ts';
+export type {
+  Ai,
+  AiAppDescription,
+  CreateAiOptions,
+  DeliveredContext,
+  InProcessTurn,
+  InProcessTurnOptions,
+  InProcessTurnResult,
+  RunEndDetail,
+} from './create-ai.ts';
+export type { ChatEvent } from './run-types.ts';
 
 export { AdapterError, isLoopbackUrl, toPublicError } from './adapter.ts';
 export type { AdapterConfig, AdapterErrorCode, ProviderAdapter } from './adapter.ts';
@@ -18,15 +28,20 @@ export type { FakeAdapter, FakeAdapterOptions, FakeStep } from './fake.ts';
 export { fromContract } from './from-contract.ts';
 export type { ContractToolAllowList } from './from-contract.ts';
 
+export { GUARDED, guardedTool } from './tool.ts';
 export type {
   AiContextProviders,
   AiTool,
-  Confirmations,
   ContextDocument,
   ContextRef,
+  GuardedTool,
+  GuardedToolDefinition,
 } from './tool.ts';
 
 export { apiKeySecretName, createFileSecretStore, createMemorySecretStore } from './secrets.ts';
 export type { SecretStore } from './secrets.ts';
 
 export type { Registry, ResolvedModel, UpdatePatch } from './registry.ts';
+
+export { DEFAULT_THREAD_TITLE, openThreads } from './threads.ts';
+export type { ThreadStore } from './threads.ts';

package/src/ai/host/registry.ts

@@ -7,7 +7,7 @@
  * "would `resolve()` succeed", rather than a second copy of the same
  * conditions that can drift from the first.
  */
-import { PublicError, publicError } from '../../shared/errors.ts';
+import { isPublicError, publicError } from '../../shared/errors.ts';
 import type { AiSettings } from '../shared/types.ts';
 
 import type { AdapterConfig, ProviderAdapter } from './adapter.ts';
@@ -36,8 +36,15 @@ export interface Registry {
   adapter(id: string): ProviderAdapter | null;
   /** Current settings plus the key, for adapter calls. */
   currentConfig(): Promise<{ adapter: ProviderAdapter; config: AdapterConfig } | null>;
-  /** Everything needed to run a chat, or a `PublicError` explaining what is missing. */
-  resolve(): Promise<ResolvedModel>;
+  /**
+   * Everything needed to run a chat, or a `PublicError` explaining what is
+   * missing.
+   *
+   * `override.modelId` replaces the model Settings names, for this call only
+   * and only within the configured provider — a conversation may pin a model,
+   * never a vendor.
+   */
+  resolve(override?: { readonly modelId?: string | undefined }): Promise<ResolvedModel>;
   /** The public view: settings without the key. */
   settings(): Promise<AiSettings>;
   update(patch: UpdatePatch): Promise<AiSettings>;
@@ -112,7 +119,7 @@ export function createRegistry(options: RegistryOptions): Registry {
       return { adapter, config: configFrom(settings, adapter, apiKey) };
     },
 
-    async resolve() {
+    async resolve(override) {
       const settings = options.settingsStore.read();
       if (settings.provider === null) throw publicError.unavailable(NOT_SET_UP);
       const adapter = byId.get(settings.provider);
@@ -123,20 +130,24 @@ export function createRegistry(options: RegistryOptions): Registry {
       // models is fetched *from* the provider, so telling a user to choose one
       // before they can see any is an instruction they cannot follow.
       const apiKey = await keyFor(settings, adapter.id);
-      if (adapter.needs.apiKey && (apiKey === null || apiKey === '')) {
+      if (adapter.needs.apiKey === 'required' && (apiKey === null || apiKey === '')) {
         throw publicError.unavailable(`An API key is required for ${adapter.label}.`);
       }
       const config = configFrom(settings, adapter, apiKey);
       if (adapter.needs.baseUrl === 'required' && (config.baseUrl === null || config.baseUrl === '')) {
         throw publicError.unavailable(`A server address is required for ${adapter.label}.`);
       }
-      if (settings.modelId === null) {
+      // Read after the provider, the key and the address, so a conversation
+      // carrying its own model still hears "AI is not set up yet" first: the
+      // model is the last thing missing, never the first.
+      const modelId = override?.modelId ?? settings.modelId;
+      if (modelId === null) {
         // Distinct from "not set up": the user is looking at the settings panel
         // with a provider selected, and being told to choose a provider is an
         // instruction they have already followed.
         throw publicError.unavailable(`Choose a model for ${adapter.label}.`);
       }
-      return { adapter, config, modelId: settings.modelId };
+      return { adapter, config, modelId };
     },
 
     async settings() {
@@ -149,7 +160,7 @@ export function createRegistry(options: RegistryOptions): Registry {
       } catch (cause) {
         // Anything that is not a deliberate "not configured" is a real fault
         // and must not be reported as merely unconfigured.
-        if (!(cause instanceof PublicError)) throw cause;
+        if (!isPublicError(cause)) throw cause;
         configured = false;
       }
       return {