broapp 0.1.0 → 0.3.0

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

@@ -0,0 +1,105 @@
+/**
+ * Turning an application's own operations into tools a model may call.
+ *
+ * The contract already says what each operation takes, what it returns and,
+ * in its `summary`, what it is for — which is exactly what a tool definition
+ * needs. Deriving tools from it means a model cannot be offered an operation
+ * that does not exist, and a change to an operation's input reaches the tool
+ * description without anybody remembering to update 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 { GUARDED, type GuardedTool } from './tool.ts';
+
+/** Which operations a model may call, and how much ceremony each needs. */
+export interface ContractToolAllowList<C extends AnyContract> {
+  readonly read?: readonly OperationName<C>[];
+  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, GuardedTool> {
+  const read = allow.read ?? [];
+  const confirm = allow.confirm ?? [];
+
+  const both = read.filter((route) => (confirm as readonly string[]).includes(route));
+  if (both.length > 0) {
+    throw new TypeError(
+      `operation ${JSON.stringify(both[0])} is listed as both a read tool and a confirm tool`,
+    );
+  }
+
+  const tools: Record<string, GuardedTool> = {};
+  const groups: readonly (readonly [readonly OperationName<C>[], 'read' | 'confirm'])[] = [
+    [read, 'read'],
+    [confirm, 'confirm'],
+  ];
+  for (const [routes, list] of groups) {
+    for (const route of routes) {
+      const spec = contract.operations[route];
+      if (spec === undefined) {
+        throw new TypeError(`operation ${JSON.stringify(route)} is not declared in the contract`);
+      }
+      if (spec.summary === undefined || spec.summary === '') {
+        // Without a summary the model is told a name and nothing else, and it
+        // will guess. Better to refuse at startup than to guess in production.
+        throw new TypeError(
+          `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(
+          `operation ${JSON.stringify(route)} uses a validator with no toJsonSchema(); pass a hand-written tool for it instead`,
+        );
+      }
+      // An operation taking `s.void()` is described to the model as an object
+      // with no properties, because that is what a tool's arguments have to
+      // be. The model then sends `{}`, which `s.void()` refuses. Nothing is
+      // 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),
+        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 }),
+      };
+    }
+  }
+  return tools;
+}

package/src/ai/host/index.ts

@@ -0,0 +1,37 @@
+/**
+ * `broapp/ai/host` — the AI layer's host runtime.
+ *
+ * This is the only entry point that reaches the AI SDK. Never import it from
+ * browser code: the page's CSP allows `connect-src 'self'` and loopback only,
+ * so a browser that could reach a provider would be a bug, and a bundler that
+ * follows this import fails loudly instead.
+ */
+export { createAi } from './create-ai.ts';
+export type { Ai, AiAppDescription, CreateAiOptions } from './create-ai.ts';
+
+export { AdapterError, isLoopbackUrl, toPublicError } from './adapter.ts';
+export type { AdapterConfig, AdapterErrorCode, ProviderAdapter } from './adapter.ts';
+
+export { createFakeAdapter } from './fake.ts';
+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,
+  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

@@ -0,0 +1,232 @@
+/**
+ * Settings plus adapters, resolved into "the model to use right now".
+ *
+ * Every route that needs a provider goes through here, so the rules about what
+ * counts as configured are written once. `resolve()` is the single source of
+ * that truth: `configured` in the settings the browser sees is literally
+ * "would `resolve()` succeed", rather than a second copy of the same
+ * conditions that can drift from the first.
+ */
+import { isPublicError, publicError } from '../../shared/errors.ts';
+import type { AiSettings } from '../shared/types.ts';
+
+import type { AdapterConfig, ProviderAdapter } from './adapter.ts';
+import { apiKeySecretName, type SecretStore } from './secrets.ts';
+import type { SettingsStore, StoredSettings } from './settings.ts';
+
+/** Everything needed to run one chat turn. */
+export interface ResolvedModel {
+  readonly adapter: ProviderAdapter;
+  readonly config: AdapterConfig;
+  readonly modelId: string;
+}
+
+/** The fields `ai.settings.update` may change. */
+export interface UpdatePatch {
+  readonly provider?: string | undefined;
+  readonly modelId?: string | undefined;
+  readonly baseUrl?: string | null | undefined;
+  readonly apiKey?: string | null | undefined;
+  readonly remember?: boolean | undefined;
+}
+
+/** The adapters this build has, and the settings pointing at one of them. */
+export interface Registry {
+  readonly adapters: readonly ProviderAdapter[];
+  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.
+   *
+   * `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>;
+  /** The config an adapter would get today, ignoring which one is selected. */
+  configFor(adapter: ProviderAdapter): AdapterConfig;
+}
+
+/** What {@link createRegistry} needs from its surroundings. */
+export interface RegistryOptions {
+  readonly adapters: readonly ProviderAdapter[];
+  readonly settingsStore: SettingsStore;
+  readonly fileSecrets: SecretStore;
+  readonly memorySecrets: SecretStore;
+  readonly fetch: typeof fetch;
+}
+
+const NOT_SET_UP = 'AI is not set up yet. Open Settings to choose a provider.';
+
+/**
+ * A key is hinted by its last four characters, and only when it is long
+ * enough that four characters are a small fraction of it. A short key would
+ * be half-published by its own hint.
+ */
+function hint(key: string | null): string | null {
+  if (key === null || key.length < 8) return null;
+  return key.slice(-4);
+}
+
+export function createRegistry(options: RegistryOptions): Registry {
+  const byId = new Map(options.adapters.map((adapter) => [adapter.id, adapter]));
+
+  /** The store the key currently lives in, which `remember` decides. */
+  function store(settings: StoredSettings): SecretStore {
+    return settings.remember ? options.fileSecrets : options.memorySecrets;
+  }
+
+  async function keyFor(settings: StoredSettings, providerId: string): Promise<string | null> {
+    return store(settings).get(apiKeySecretName(providerId));
+  }
+
+  function configFrom(settings: StoredSettings, adapter: ProviderAdapter, apiKey: string | null): AdapterConfig {
+    return {
+      apiKey,
+      baseUrl: settings.baseUrl ?? adapter.defaultBaseUrl,
+      fetch: options.fetch,
+    };
+  }
+
+  const registry: Registry = {
+    adapters: options.adapters,
+
+    adapter: (id) => byId.get(id) ?? null,
+
+    configFor(adapter) {
+      const settings = options.settingsStore.read();
+      // The stored base URL belongs to the *selected* provider. Applying it to
+      // the others would have told the user that Anthropic runs on their
+      // computer, simply because they had Ollama selected a moment ago.
+      const scoped: StoredSettings =
+        settings.provider === adapter.id ? settings : { ...settings, baseUrl: null };
+      // No key either: whether a provider stays on this machine is a property
+      // of the address, and the answer must not depend on what is stored.
+      return configFrom(scoped, adapter, null);
+    },
+
+    async currentConfig() {
+      const settings = options.settingsStore.read();
+      if (settings.provider === null) return null;
+      const adapter = byId.get(settings.provider);
+      if (adapter === undefined) return null;
+      const apiKey = await keyFor(settings, adapter.id);
+      return { adapter, config: configFrom(settings, adapter, apiKey) };
+    },
+
+    async resolve(override) {
+      const settings = options.settingsStore.read();
+      if (settings.provider === null) throw publicError.unavailable(NOT_SET_UP);
+      const adapter = byId.get(settings.provider);
+      if (adapter === undefined) {
+        throw publicError.unavailable('The configured AI provider is not available in this build.');
+      }
+      // The key and the address come before the model on purpose: the list of
+      // 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 === '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}.`);
+      }
+      // 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 };
+    },
+
+    async settings() {
+      const settings = options.settingsStore.read();
+      const apiKey =
+        settings.provider === null ? null : await keyFor(settings, settings.provider);
+      let configured = true;
+      try {
+        await registry.resolve();
+      } catch (cause) {
+        // Anything that is not a deliberate "not configured" is a real fault
+        // and must not be reported as merely unconfigured.
+        if (!isPublicError(cause)) throw cause;
+        configured = false;
+      }
+      return {
+        provider: settings.provider,
+        modelId: settings.modelId,
+        baseUrl: settings.baseUrl,
+        hasKey: apiKey !== null && apiKey !== '',
+        keyHint: hint(apiKey),
+        remember: settings.remember,
+        configured,
+      };
+    },
+
+    async update(patch) {
+      const before = options.settingsStore.read();
+      const next: StoredSettings = { ...before };
+
+      if (patch.provider !== undefined) {
+        if (!byId.has(patch.provider)) throw publicError.invalidInput('Unknown provider.');
+        if (patch.provider !== before.provider) {
+          next.provider = patch.provider;
+          // A model id belongs to the provider that offers it, and a base URL
+          // points at that provider's server. Carrying either across a change
+          // would leave the settings describing something that does not exist.
+          next.modelId = null;
+          next.baseUrl = byId.get(patch.provider)?.defaultBaseUrl ?? null;
+        }
+      }
+      if (patch.modelId !== undefined) next.modelId = patch.modelId;
+      if (patch.baseUrl !== undefined) next.baseUrl = patch.baseUrl;
+
+      if (patch.remember !== undefined && patch.remember !== before.remember) {
+        next.remember = patch.remember;
+        await moveKeys(before, next);
+      }
+
+      if (patch.apiKey !== undefined && next.provider !== null) {
+        const name = apiKeySecretName(next.provider);
+        const value = patch.apiKey === null || patch.apiKey === '' ? null : patch.apiKey;
+        if (value === null) await store(next).delete(name);
+        else await store(next).set(name, value);
+      }
+
+      options.settingsStore.write(next);
+      return registry.settings();
+    },
+  };
+
+  /**
+   * Move every stored key to the store `after` selects.
+   *
+   * Turning `remember` off must not merely stop future writes: the key already
+   * on disk has to leave the disk, or the setting would be a promise the
+   * layer does not keep.
+   */
+  async function moveKeys(before: StoredSettings, after: StoredSettings): Promise<void> {
+    const from = store(before);
+    const to = store(after);
+    for (const adapter of options.adapters) {
+      const name = apiKeySecretName(adapter.id);
+      const value = await from.get(name);
+      if (value === null) continue;
+      await to.set(name, value);
+      await from.delete(name);
+    }
+  }
+
+  return registry;
+}

package/src/ai/host/run-types.ts

@@ -0,0 +1,14 @@
+/**
+ * The two shapes the run loop shares with `create-ai.ts`.
+ *
+ * They are derived from the contract rather than restated, so a change to the
+ * contract is a type error here instead of a mismatch at runtime.
+ */
+import type { StreamEvent, StreamParams } from '../../shared/contract.ts';
+import type { AiContract } from '../shared/contract.ts';
+
+/** What the browser sends to start a turn. */
+export type StreamChatParams = StreamParams<AiContract, 'ai.chat'>;
+
+/** One event on the way back. */
+export type ChatEvent = StreamEvent<AiContract, 'ai.chat'>;