broapp 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "broapp",
-  "version": "0.2.0",
+  "version": "0.3.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;

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

@@ -17,7 +17,7 @@ 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 { createPendingApprovals, createReservedHostApp } from '../../host/index.ts';
 import type { HostApp, HostLogger } from '../../host/app.ts';
 import { publicError } from '../../shared/errors.ts';
 import { aiContract, type AiContract } from '../shared/contract.ts';
@@ -28,13 +28,23 @@ import { createRegistry, type Registry } from './registry.ts';
 import { runChat, type RunDeps } from './run.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 } from './tool.ts';
 
 /** 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 +63,19 @@ 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,
+  ) => void;
 }
 
 /**
@@ -68,6 +91,16 @@ 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;
@@ -93,10 +126,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 +204,7 @@ export function createAi(options: CreateAiOptions): Ai {
     }
   });
 
-  const confirmations = createConfirmations();
+  const approvals = createPendingApprovals(options.logger);
   const runDeps: RunDeps = {
     registry,
     app: options.app,
@@ -171,15 +213,35 @@ 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 }),
     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,6 +254,10 @@ 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;
     },

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

@@ -18,15 +18,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 {