broapp 0.1.0 → 0.2.0

package/README.md

@@ -22,10 +22,18 @@ Full documentation lives in the
 | `broapp/client` | The framework-agnostic browser client. |
 | `broapp/react` | `BroappProvider`, `useOperation`, `useStream`, `useConnection`. |
 | `broapp/build` | `buildPage`, `buildBinary`, `defineConfig`. |
+| `broapp/ai` | The AI contract and its types. Safe for both sides. |
+| `broapp/ai/host` | `createAi`, `fromContract`, the secret stores, `createFakeAdapter`. Host only. |
+| `broapp/ai/react` | `AiProvider`, `useAiChat`, `useAiSettings`, `useAiModels`, `<AiSettings/>`, `<AiChat/>`. |
 
-Never import `broapp/host` from browser code: it pulls in `node:fs` and
-`Bun.spawn`, and a browser bundle that reaches it fails the build — which is the
-intended outcome.
+Never import `broapp/host` or `broapp/ai/host` from browser code: they pull in
+`node:fs`, `Bun.spawn` and the AI SDK, and a browser bundle that reaches either
+fails the build — which is the intended outcome.
+
+The AI layer is optional. `broapp/ai/host` needs the `ai` peer dependency and
+at least one provider package (`broapp-ai-anthropic`, `broapp-ai-compatible`);
+an application that never imports it carries none of that. See
+[docs/ai.md](https://github.com/praveenvijayan/broapp/blob/main/docs/ai.md).
 
 ## The command
 
@@ -39,7 +47,8 @@ broapp build --all-targets    Every supported target
 ## Requirements
 
 Bun 1.2 or newer. Peer dependency on React 18 or newer, and only if you use
-`broapp/react`.
+`broapp/react`. Peer dependency on `ai@7.0.93`, and only if you use
+`broapp/ai/host`.
 
 ## Licence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "broapp",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -38,6 +38,10 @@
   "exports": {
     ".": "./src/shared/index.ts",
     "./shared": "./src/shared/index.ts",
+    "./ai": "./src/ai/shared/index.ts",
+    "./ai/host": "./src/ai/host/index.ts",
+    "./ai/react": "./src/ai/react/index.tsx",
+    "./ai/react/ai.css": "./src/ai/react/ai.css",
     "./host": "./src/host/index.ts",
     "./client": "./src/client/index.ts",
     "./react": "./src/react/index.ts",
@@ -50,11 +54,15 @@
     "brobridge": "^0.2.1"
   },
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "ai": "7.0.93"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
+    },
+    "ai": {
+      "optional": true
     }
   },
   "devDependencies": {

package/src/ai/host/adapter.ts

@@ -0,0 +1,106 @@
+/**
+ * What a provider package has to implement.
+ *
+ * An adapter is the only place in the AI layer that knows a provider exists.
+ * It answers four questions — what do you need, what models do you have, does
+ * this configuration work, and give me a model — and Broapp's host code is
+ * written entirely against those four.
+ *
+ * Every adapter takes its `fetch` from {@link AdapterConfig} rather than
+ * reaching for the global one. That is what makes a test able to prove no
+ * request left the machine, and what makes the AI SDK's gateway trap
+ * (see `reports/01-spike.md`) impossible to fall into by accident.
+ */
+import type { LanguageModel } from 'ai';
+
+import { PublicError, publicError } from '../../shared/errors.ts';
+import type { BroappModel } from '../shared/types.ts';
+
+/** Everything an adapter needs to reach its provider. */
+export interface AdapterConfig {
+  readonly apiKey: string | null;
+  readonly baseUrl: string | null;
+  /** Injected so tests never touch the network. Defaults to `globalThis.fetch`. */
+  readonly fetch: typeof fetch;
+}
+
+/** Why an adapter call failed, in terms the layer above can act on. */
+export type AdapterErrorCode = 'auth' | 'network' | 'not_found' | 'rate_limited' | 'provider';
+
+/**
+ * A failure an adapter reports deliberately.
+ *
+ * `message` is shown to the user, so it must name the problem in plain words
+ * and never include a key, a URL with credentials, or a raw provider response
+ * body. Anything an adapter cannot describe safely should be thrown as an
+ * ordinary error instead, and the host's error boundary will reduce it.
+ */
+export class AdapterError extends Error {
+  readonly code: AdapterErrorCode;
+
+  constructor(code: AdapterErrorCode, message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = 'AdapterError';
+    this.code = code;
+  }
+}
+
+/** One provider, as Broapp's host uses it. */
+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 defaultBaseUrl: string | null;
+  /** Whether requests stay on this machine under this config. */
+  local(config: AdapterConfig): boolean;
+  /** List models. Must reject with {@link AdapterError} on failure. */
+  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. */
+  model(config: AdapterConfig, modelId: string): LanguageModel;
+}
+
+/** Hosts that mean "this machine". */
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+
+/**
+ * True when a URL points at this machine.
+ *
+ * Used to tell the user whether their prompts leave the computer. An address
+ * that cannot be parsed is not loopback: an unknown destination is exactly the
+ * case where the honest answer is "no".
+ */
+export function isLoopbackUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    // `URL.hostname` strips the brackets from an IPv6 literal, so both spellings
+    // are in the set above.
+    return LOOPBACK_HOSTS.has(parsed.hostname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Translate an adapter failure into something the browser may see.
+ *
+ * Anything that is not an `AdapterError` is rethrown unchanged, so the host's
+ * existing boundary logs it with its stack and the browser gets the fixed
+ * internal sentence. An adapter that wants a message shown has to say so by
+ * choosing an `AdapterError` code.
+ */
+export function toPublicError(cause: unknown): PublicError {
+  if (!(cause instanceof AdapterError)) throw cause;
+  switch (cause.code) {
+    case 'auth':
+      return publicError.rejected(cause.message);
+    case 'not_found':
+      return publicError.notFound(cause.message);
+    case 'network':
+    case 'rate_limited':
+    case 'provider':
+      return publicError.unavailable(cause.message);
+  }
+}

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

@@ -0,0 +1,200 @@
+/**
+ * The AI layer's host runtime.
+ *
+ * `createAi(...)` builds a second `HostApp` — over Broapp's own AI contract —
+ * that an application mounts on the same bridge as its own. Keeping them
+ * separate means an application's route table never grows Broapp's routes, and
+ * an application that does not call `createAi` carries none of this.
+ *
+ * Chat arrives in the next layer up; the routes are registered here so that
+ * `mount` has an implementation for every route in the contract, which it
+ * insists on.
+ */
+import type { Bridge } from 'brobridge';
+
+// Imported from the host entry point rather than from `host/app.ts` directly:
+// the AI layer is part of the host runtime, and depending on that entry point
+// 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 { publicError } from '../../shared/errors.ts';
+import { aiContract, type AiContract } from '../shared/contract.ts';
+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 { createFileSecretStore, createMemorySecretStore } from './secrets.ts';
+import { createSettingsStore } from './settings.ts';
+import { createConfirmations, 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[];
+}
+
+/** Options for {@link createAi}. */
+export interface CreateAiOptions {
+  readonly dataDir: string;
+  readonly providers: readonly ProviderAdapter[];
+  readonly app: AiAppDescription;
+  /** Defaults to `globalThis.fetch`. Tests inject a fake. */
+  readonly fetch?: typeof fetch;
+  readonly logger?: HostLogger;
+  readonly context?: AiContextProviders;
+  readonly tools?: Record<string, AiTool>;
+  /** Character budget for context documents in one turn. Default 40_000. */
+  readonly contextBudgetChars?: number;
+  /** Max model steps (tool round trips) per turn. Default 8. */
+  readonly maxSteps?: number;
+  /** How long a `confirm` tool waits for the user. Default 300_000 ms. */
+  readonly confirmTimeoutMs?: number;
+}
+
+/**
+ * What a tool may be called.
+ *
+ * Dots are allowed so that a contract route can be its own tool name, which is
+ * what `fromContract` does. Anything else risks a provider rejecting the whole
+ * request over a name the application chose carelessly.
+ */
+const TOOL_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_.]*$/;
+
+/** The AI layer, ready to mount. */
+export interface Ai {
+  mount(bridge: Bridge): void;
+  abortAll(reason: string): void;
+  readonly activeStreams: number;
+  /** For tests, and for applications that read settings on the host. */
+  readonly registry: Registry;
+}
+
+/** How long a provider is given to answer a listing or a connection test. */
+const PROVIDER_TIMEOUT_MS = 20_000;
+
+/** Defaults for the run loop, all overridable per application. */
+const DEFAULT_CONTEXT_BUDGET_CHARS = 40_000;
+const DEFAULT_MAX_STEPS = 8;
+const DEFAULT_CONFIRM_TIMEOUT_MS = 300_000;
+
+/** Build the AI layer for one application. */
+export function createAi(options: CreateAiOptions): Ai {
+  if (options.providers.length === 0) {
+    throw new TypeError('createAi needs at least one provider adapter');
+  }
+  const seen = new Set<string>();
+  for (const adapter of options.providers) {
+    if (seen.has(adapter.id)) {
+      throw new TypeError(`two provider adapters share the id ${JSON.stringify(adapter.id)}`);
+    }
+    seen.add(adapter.id);
+  }
+  for (const name of Object.keys(options.tools ?? {})) {
+    if (!TOOL_NAME_PATTERN.test(name)) {
+      throw new TypeError(`tool name ${JSON.stringify(name)} must be letters, digits, "_" or "."`);
+    }
+  }
+
+  // Both stores are built once and kept. `remember` chooses between them, and
+  // switching has to move a key from one to the other rather than construct a
+  // new store and lose what the old one held.
+  const registry = createRegistry({
+    adapters: options.providers,
+    settingsStore: createSettingsStore(options.dataDir),
+    fileSecrets: createFileSecretStore(options.dataDir),
+    memorySecrets: createMemorySecretStore(),
+    fetch: options.fetch ?? globalThis.fetch,
+  });
+
+  const host: HostApp<AiContract> = createReservedHostApp<AiContract>(aiContract, {
+    ...(options.logger === undefined ? {} : { logger: options.logger }),
+  });
+
+  host.operation('ai.settingsGet', () => registry.settings());
+  host.operation('ai.settingsUpdate', (input) => registry.update(input));
+
+  host.operation('ai.providersList', () => ({
+    providers: options.providers.map((adapter): ProviderInfo => {
+      // Deliberately computed without the key: whether requests leave this
+      // machine is a property of the address, and the user is entitled to the
+      // answer before they have entered anything.
+      const config = registry.configFor(adapter);
+      return {
+        id: adapter.id,
+        label: adapter.label,
+        local: adapter.local(config),
+        needs: { apiKey: adapter.needs.apiKey, baseUrl: adapter.needs.baseUrl },
+        defaultBaseUrl: adapter.defaultBaseUrl,
+      };
+    }),
+  }));
+
+  host.operation('ai.modelsList', async () => {
+    const { adapter, config } = await requireConfig();
+    try {
+      const models = await adapter.models(config, AbortSignal.timeout(PROVIDER_TIMEOUT_MS));
+      return { models };
+    } catch (cause) {
+      throw toPublicError(cause);
+    }
+  });
+
+  host.operation('ai.connectionTest', async () => {
+    // `resolve()` rather than `currentConfig()`: testing a connection that is
+    // missing its key would just ask the provider to reject it, and the layer
+    // already knows the answer and can say it in better words.
+    const { adapter, config } = await registry.resolve();
+    const started = Bun.nanoseconds();
+    const elapsed = (): number => Math.round((Bun.nanoseconds() - started) / 1_000_000);
+    try {
+      await adapter.test(config, AbortSignal.timeout(PROVIDER_TIMEOUT_MS));
+      return { ok: true, message: `Connected to ${adapter.label}.`, latencyMs: elapsed() };
+    } catch (cause) {
+      // A failed connection test is the answer to the question, not a failure
+      // of the route: the UI shows the reason next to the button. Anything
+      // that is not a deliberate adapter failure is still a fault.
+      if (!(cause instanceof AdapterError)) throw cause;
+      return { ok: false, message: cause.message, latencyMs: elapsed() };
+    }
+  });
+
+  const confirmations = createConfirmations();
+  const runDeps: RunDeps = {
+    registry,
+    app: options.app,
+    context: options.context ?? {},
+    tools: options.tools ?? {},
+    contextBudgetChars: options.contextBudgetChars ?? DEFAULT_CONTEXT_BUDGET_CHARS,
+    maxSteps: options.maxSteps ?? DEFAULT_MAX_STEPS,
+    confirmTimeoutMs: options.confirmTimeoutMs ?? DEFAULT_CONFIRM_TIMEOUT_MS,
+    confirmations,
+    logger: options.logger ?? console,
+  };
+
+  host.stream('ai.chat', (params, sink) => runChat(params, sink, runDeps));
+  host.operation('ai.chatConfirm', ({ runId, callId, approve }) => ({
+    accepted: confirmations.answer(runId, callId, approve),
+  }));
+
+  /** The current provider config, or the "not set up" error. */
+  async function requireConfig(): Promise<{ adapter: ProviderAdapter; config: AdapterConfig }> {
+    const current = await registry.currentConfig();
+    if (current === null) {
+      throw publicError.unavailable('AI is not set up yet. Open Settings to choose a provider.');
+    }
+    return current;
+  }
+
+  return {
+    mount: (bridge: Bridge) => host.mount(bridge),
+    abortAll: (reason: string) => host.abortAll(reason),
+    get activeStreams() {
+      return host.activeStreams;
+    },
+    registry,
+  };
+}

package/src/ai/host/fake.ts

@@ -0,0 +1,223 @@
+/**
+ * An adapter that answers without a provider.
+ *
+ * It exists for Broapp's own tests and for the tests of applications built on
+ * Broapp: the AI layer is a lot of behaviour that has nothing to do with any
+ * particular vendor, and none of it should need a key or a network to test.
+ *
+ * The model it returns is the AI SDK's own `MockLanguageModelV4` from
+ * `ai/test`, so `streamText` runs its real loop — tool calls, steps, finish
+ * reasons and all — over a scripted set of chunks.
+ */
+import { simulateReadableStream } from 'ai';
+import type { LanguageModel } from 'ai';
+import { MockLanguageModelV4 } from 'ai/test';
+
+import type { BroappModel } from '../shared/types.ts';
+
+import { AdapterError, type AdapterConfig, type ProviderAdapter } from './adapter.ts';
+
+/**
+ * The provider-level stream types, taken from the mock rather than imported.
+ *
+ * `@ai-sdk/provider` is not a dependency of `broapp` — it arrives under `ai` —
+ * so the shapes are read off the class that has to accept them. A change in
+ * the AI SDK then shows up here as a type error rather than a wrong chunk.
+ */
+type StreamResult = Awaited<ReturnType<MockLanguageModelV4['doStream']>>;
+type StreamPart = StreamResult['stream'] extends ReadableStream<infer P> ? P : never;
+type CallOptions = Parameters<MockLanguageModelV4['doStream']>[0];
+
+/** One scripted model step. */
+export type FakeStep =
+  | { readonly kind: 'text'; readonly chunks: readonly string[] }
+  /** `then` runs after the tool result comes back. */
+  | { readonly kind: 'tool'; readonly name: string; readonly input: unknown; readonly then: readonly FakeStep[] };
+
+/** How to shape a fake adapter for one test. */
+export interface FakeAdapterOptions {
+  /** Default `'fake'`. */
+  readonly id?: string;
+  /** Default: one model, `fake-1`. */
+  readonly models?: readonly BroappModel[];
+  /** Default `false`. */
+  readonly needsKey?: boolean;
+  /** When set, `test()` rejects with it. */
+  readonly failTestWith?: AdapterError;
+  /** What the model says, step by step. Default: one text step. */
+  readonly script?: readonly FakeStep[];
+  /** Delay between chunks, so a cancel test can catch a stream mid-flight. */
+  readonly chunkDelayMs?: number;
+}
+
+/** A fake adapter, plus what the test wants to know about it afterwards. */
+export interface FakeAdapter extends ProviderAdapter {
+  /** Every prompt the model was given, in order. */
+  readonly calls: readonly unknown[];
+  /** How many times `model()` was called. Proves no string model id was used. */
+  readonly modelCalls: number;
+  /** How many times a call was abandoned because its signal aborted. */
+  readonly aborted: number;
+}
+
+function defaultModel(providerId: string): BroappModel {
+  return {
+    provider: providerId,
+    modelId: 'fake-1',
+    label: 'Fake 1',
+    capabilities: { tools: true, vision: false, structuredOutput: true },
+  };
+}
+
+/** The usage every fake step reports. Small and constant, so tests can assert it. */
+const USAGE = {
+  inputTokens: { total: 11, noCache: 11, cacheRead: 0, cacheWrite: 0 },
+  outputTokens: { total: 7, text: 7, reasoning: 0 },
+} as const;
+
+/**
+ * Flatten a script into the sequence of steps `streamText` will ask for.
+ *
+ * `doStream` is called once per step of the agent loop, so a `tool` step's
+ * `then` steps are simply the ones that follow it. Nesting is how a test
+ * writes "and after the tool comes back, say this".
+ */
+function flatten(script: readonly FakeStep[]): FakeStep[] {
+  const out: FakeStep[] = [];
+  for (const step of script) {
+    out.push(step);
+    if (step.kind === 'tool') out.push(...flatten(step.then));
+  }
+  return out;
+}
+
+/** The chunks for one step. */
+function chunksFor(step: FakeStep, callIndex: number): StreamPart[] {
+  if (step.kind === 'text') {
+    const parts: StreamPart[] = [{ type: 'text-start', id: String(callIndex) }];
+    for (const chunk of step.chunks) {
+      parts.push({ type: 'text-delta', id: String(callIndex), delta: chunk });
+    }
+    parts.push({ type: 'text-end', id: String(callIndex) });
+    parts.push({
+      type: 'finish',
+      finishReason: { unified: 'stop', raw: 'stop' },
+      usage: USAGE,
+    });
+    return parts;
+  }
+  // A tool call arrives whole: this mock has no reason to dribble the input
+  // out in deltas, and the loop under test does not care if it did.
+  const toolCallId = `call-${String(callIndex)}`;
+  return [
+    {
+      type: 'tool-call',
+      toolCallId,
+      toolName: step.name,
+      input: JSON.stringify(step.input),
+    },
+    {
+      type: 'finish',
+      finishReason: { unified: 'tool-calls', raw: 'tool_calls' },
+      usage: USAGE,
+    },
+  ];
+}
+
+/** 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 script = options.script ?? [{ kind: 'text', chunks: ['fake reply'] } as const];
+  const steps = flatten(script);
+  const delay = options.chunkDelayMs ?? 0;
+
+  const calls: unknown[] = [];
+  let callIndex = 0;
+  let modelCalls = 0;
+  let aborted = 0;
+
+  const adapter: FakeAdapter = {
+    id,
+    label: 'Fake provider',
+    needs: { apiKey: options.needsKey === true, baseUrl: 'none' },
+    defaultBaseUrl: null,
+    // Nothing leaves the process, so this is true whatever the configuration.
+    local: () => true,
+
+    models: (_config: AdapterConfig, _signal: AbortSignal) => Promise.resolve([...models]),
+
+    test: (_config: AdapterConfig, _signal: AbortSignal) =>
+      options.failTestWith === undefined ? Promise.resolve() : Promise.reject(options.failTestWith),
+
+    get calls() {
+      return calls;
+    },
+    get modelCalls() {
+      return modelCalls;
+    },
+    get aborted() {
+      return aborted;
+    },
+
+    model(_config: AdapterConfig, modelId: string): LanguageModel {
+      modelCalls += 1;
+      return new MockLanguageModelV4({
+        provider: id,
+        modelId,
+        doStream: (callOptions: CallOptions): Promise<StreamResult> => {
+          calls.push(callOptions.prompt);
+          if (callOptions.abortSignal?.aborted === true) {
+            aborted += 1;
+            // The name is what `streamText` checks for, so a cancelled turn
+            // looks like a cancelled turn rather than a provider failure.
+            const error = new Error('aborted');
+            error.name = 'AbortError';
+            return Promise.reject(error);
+          }
+          const step = steps[callIndex] ?? { kind: 'text' as const, chunks: [''] };
+          const parts = chunksFor(step, callIndex);
+          callIndex += 1;
+          const stream = simulateReadableStream<StreamPart>({
+            initialDelayInMs: delay === 0 ? 0 : delay,
+            chunkDelayInMs: delay,
+            chunks: parts,
+          });
+          // The signal has to reach the stream too: a cancel that arrives
+          // while chunks are still being delivered must stop them, not wait
+          // for the script to run out.
+          return Promise.resolve({ stream: withAbort(stream, callOptions.abortSignal, () => {
+            aborted += 1;
+          }) });
+        },
+      });
+    },
+  };
+  return adapter;
+}
+
+/** Wrap a stream so an aborted signal ends it instead of letting it run on. */
+function withAbort<T>(
+  stream: ReadableStream<T>,
+  signal: AbortSignal | undefined,
+  onAbort: () => void,
+): ReadableStream<T> {
+  if (signal === undefined) return stream;
+  const reader = stream.getReader();
+  return new ReadableStream<T>({
+    async pull(controller) {
+      if (signal.aborted) {
+        onAbort();
+        await reader.cancel().catch(() => undefined);
+        controller.close();
+        return;
+      }
+      const { done, value } = await reader.read();
+      if (done) controller.close();
+      else controller.enqueue(value);
+    },
+    async cancel(reason) {
+      await reader.cancel(reason).catch(() => undefined);
+    },
+  });
+}

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

@@ -0,0 +1,85 @@
+/**
+ * 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 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.
+ */
+import type { HostApp } from '../../host/app.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';
+
+/** 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>[];
+}
+
+/** 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> {
+  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, AiTool> = {};
+  const groups: readonly (readonly [readonly OperationName<C>[], ToolPermission])[] = [
+    [read, 'read'],
+    [confirm, 'confirm'],
+  ];
+  for (const [routes, permission] 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 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] = {
+        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),
+      };
+    }
+  }
+  return tools;
+}