broapp 0.1.0 → 0.3.0

package/src/ai/shared/contract.ts

@@ -0,0 +1,247 @@
+/**
+ * The AI contract.
+ *
+ * It is a contract like any application's, with one difference: it owns the
+ * reserved `ai` route group, and it is mounted as a *second* host app on the
+ * same bridge rather than merged into the application's own contract. That
+ * keeps an application's route table free of Broapp's routes and lets the AI
+ * layer be absent entirely when it is not enabled.
+ *
+ * Every bound here is a limit on what a browser may send. They are deliberate:
+ * an unbounded `message` or `history` is a way to make the host allocate.
+ */
+import { defineContract } from '../../shared/contract.ts';
+import { s } from '../../shared/schema.ts';
+
+/** A run identifier, chosen by the browser and echoed on every event. */
+const runId = s.string({ pattern: /[A-Za-z0-9_-]{8,64}/ });
+
+const capabilities = s.object({
+  tools: s.boolean(),
+  vision: s.boolean(),
+  structuredOutput: s.boolean(),
+});
+
+const model = s.object({
+  provider: s.string(),
+  modelId: s.string(),
+  label: s.string(),
+  capabilities,
+});
+
+const providerInfo = s.object({
+  id: s.string(),
+  label: s.string(),
+  local: s.boolean(),
+  needs: s.object({
+    apiKey: s.enum(['required', 'optional', 'none']),
+    baseUrl: s.enum(['required', 'optional', 'none']),
+  }),
+  defaultBaseUrl: s.nullable(s.string()),
+});
+
+const settings = s.object({
+  provider: s.nullable(s.string()),
+  modelId: s.nullable(s.string()),
+  baseUrl: s.nullable(s.string()),
+  hasKey: s.boolean(),
+  keyHint: s.nullable(s.string()),
+  remember: s.boolean(),
+  configured: s.boolean(),
+});
+
+const chatTurn = s.object({
+  role: s.enum(['user', 'assistant']),
+  content: s.string({ max: 20_000 }),
+});
+
+/**
+ * One image on a turn. `data` is base64 without the `data:` prefix.
+ *
+ * The bounds are the browser's contract as much as the host's: the panel
+ * downscales before it sends, and four images of two million characters still
+ * fit inside one Brobridge frame with room to spare.
+ */
+const chatFile = s.object({
+  name: s.string({ max: 200 }),
+  mediaType: s.string({ pattern: /image\/(png|jpeg|gif|webp)/ }),
+  data: s.string({ min: 1, max: 2_000_000 }),
+});
+
+/** A conversation identifier. The host chooses it; the browser only echoes it. */
+const threadId = s.string({ pattern: /[A-Za-z0-9_-]{8,64}/ });
+
+/** A conversation, without its messages. */
+const thread = s.object({
+  id: threadId,
+  title: s.string({ max: 120 }),
+  /** Null means "whatever Settings says". */
+  modelId: s.nullable(s.string({ max: 200 })),
+  createdAt: s.number(),
+  updatedAt: s.number(),
+  messageCount: s.number({ int: true, min: 0 }),
+});
+
+/**
+ * One stored UI message. Parts are the AI SDK's; the host stores, never
+ * interprets.
+ *
+ * `s.unknown()` is normally forbidden on an input, because the point of an
+ * input schema is that browser-supplied data is untrusted. It is right here
+ * for the one reason that exempts it: nothing on the host ever reads inside a
+ * part. They are written to SQLite as JSON and handed back to the same browser
+ * that sent them, so the shape the host would be validating is a shape only
+ * the AI SDK understands and only the AI SDK consumes. What is still bounded
+ * is the *amount*: 200 parts to a message, 200 messages to a save, and a byte
+ * ceiling on the whole save in `threads.ts`.
+ */
+const storedMessage = s.object({
+  id: s.string({ max: 200 }),
+  role: s.enum(['user', 'assistant', 'system']),
+  parts: s.array(s.unknown(), { max: 200 }),
+  metadata: s.optional(s.unknown()),
+});
+
+/**
+ * One stream event, flat because the validator has no unions.
+ *
+ * `input` and `output` are `unknown`: they carry whatever an application's own
+ * operation takes and returns, which this layer cannot describe in advance.
+ * They are host-controlled on the way out, which is the only place `unknown`
+ * is safe.
+ */
+const chatEvent = s.object({
+  type: s.enum(['text', 'tool-call', 'confirm', 'tool-result', 'usage', 'done', 'error']),
+  text: s.optional(s.string()),
+  callId: s.optional(s.string()),
+  tool: s.optional(s.string()),
+  input: s.optional(s.unknown()),
+  output: s.optional(s.unknown()),
+  denied: s.optional(s.boolean()),
+  permission: s.optional(s.enum(['read', 'confirm'])),
+  requestId: s.optional(s.string()),
+  releaseId: s.optional(s.string()),
+  argumentsHash: s.optional(s.string()),
+  expiresAt: s.optional(s.number()),
+  inputTokens: s.optional(s.number()),
+  outputTokens: s.optional(s.number()),
+  code: s.optional(s.string()),
+  message: s.optional(s.string()),
+});
+
+/** Broapp's AI routes. Applications may not declare the `ai` group themselves. */
+export const aiContract = defineContract({
+  operations: {
+    'ai.settingsGet': {
+      input: s.void(),
+      output: settings,
+      summary: 'The current AI settings. Never includes the API key itself.',
+    },
+    'ai.settingsUpdate': {
+      input: s.object({
+        provider: s.optional(s.string({ max: 64 })),
+        modelId: s.optional(s.string({ max: 200 })),
+        baseUrl: s.optional(s.nullable(s.string({ max: 2000 }))),
+        // Null clears the stored key; a string replaces it. It goes to the
+        // secret store and is never read back out to the browser.
+        apiKey: s.optional(s.nullable(s.string({ max: 4000 }))),
+        remember: s.optional(s.boolean()),
+      }),
+      output: settings,
+      summary: 'Change one or more settings and return the result.',
+    },
+    'ai.providersList': {
+      input: s.void(),
+      output: s.object({ providers: s.array(providerInfo, { max: 50 }) }),
+      summary: 'The providers compiled into this application.',
+    },
+    'ai.modelsList': {
+      input: s.void(),
+      output: s.object({ models: s.array(model, { max: 1000 }) }),
+      summary: 'The models the configured provider offers.',
+    },
+    'ai.connectionTest': {
+      input: s.void(),
+      output: s.object({ ok: s.boolean(), message: s.string(), latencyMs: s.number() }),
+      summary: 'Try the configured provider once and report what happened.',
+    },
+    'ai.chatConfirm': {
+      input: s.object({ runId, callId: s.string({ max: 200 }), approve: s.boolean() }),
+      output: s.object({ accepted: s.boolean() }),
+      summary: 'Answer a confirm event. `accepted` is false when no run is waiting on that call.',
+    },
+    // Conversations are the user's own data, so every route below answers even
+    // when no provider is configured: somebody who has just removed their key
+    // is still entitled to read and delete what they wrote.
+    'ai.threadsList': {
+      input: s.void(),
+      output: s.object({ threads: s.array(thread, { max: 500 }) }),
+      summary: 'Every stored conversation, most recently changed first.',
+    },
+    'ai.threadsCreate': {
+      input: s.object({
+        title: s.optional(s.string({ max: 120 })),
+        modelId: s.optional(s.nullable(s.string({ max: 200 }))),
+      }),
+      output: thread,
+      summary: 'Start a conversation. Without a title it is named after its first message.',
+    },
+    'ai.threadsGet': {
+      input: s.object({ id: threadId }),
+      output: s.object({ thread, messages: s.array(storedMessage, { max: 200 }) }),
+      summary: 'One conversation and its messages.',
+    },
+    'ai.threadsSave': {
+      input: s.object({
+        id: threadId,
+        messages: s.array(storedMessage, { max: 200 }),
+        title: s.optional(s.string({ max: 120 })),
+      }),
+      output: thread,
+      summary: 'Replace the messages of a conversation, whole.',
+    },
+    'ai.threadsUpdate': {
+      input: s.object({
+        id: threadId,
+        title: s.optional(s.string({ max: 120 })),
+        // Null puts the conversation back on whatever Settings says.
+        modelId: s.optional(s.nullable(s.string({ max: 200 }))),
+      }),
+      output: thread,
+      summary: 'Rename a conversation, or give it a model of its own.',
+    },
+    'ai.threadsDelete': {
+      input: s.object({ id: threadId }),
+      output: s.object({ deleted: s.boolean() }),
+      summary: 'Delete one conversation and its messages.',
+    },
+    'ai.threadsClear': {
+      input: s.void(),
+      output: s.object({ deleted: s.number({ int: true, min: 0 }) }),
+      summary: 'Delete every conversation.',
+    },
+  },
+  streams: {
+    'ai.chat': {
+      params: s.object({
+        runId,
+        message: s.string({ min: 1, max: 20_000 }),
+        refs: s.array(s.string({ max: 200 }), { max: 50 }),
+        history: s.array(chatTurn, { max: 100 }),
+        // Images travel with the turn they arrive on. History keeps a
+        // placeholder instead, because a transcript of base64 would not fit.
+        files: s.optional(s.array(chatFile, { max: 4 })),
+        // The model for this turn only, and only *within* the configured
+        // provider. A provider is never overridden per turn: a different
+        // provider means a different key and a different answer to "does this
+        // leave my computer", and that stays a Settings decision.
+        modelId: s.optional(s.string({ max: 200 })),
+      }),
+      event: chatEvent,
+      summary: 'One chat turn. Emits text, tool calls, confirmations and usage.',
+    },
+  },
+});
+
+/** The AI contract's type, for `HostApp` and client generics. */
+export type AiContract = typeof aiContract;

package/src/ai/shared/index.ts

@@ -0,0 +1,19 @@
+/**
+ * `broapp/ai` — the AI layer's shared surface.
+ *
+ * Shared code only: the contract, the types derived from it, and nothing that
+ * knows how a provider is reached. The host half is `broapp/ai/host`.
+ */
+export { aiContract } from './contract.ts';
+export type { AiContract } from './contract.ts';
+export type {
+  AiSettings,
+  BroappModel,
+  ChatEvent,
+  ChatFile,
+  ChatTurn,
+  ProviderInfo,
+  StoredMessage,
+  Thread,
+  ToolPermission,
+} from './types.ts';

package/src/ai/shared/types.check.ts

@@ -0,0 +1,71 @@
+/**
+ * Type-level proof that the contract and the hand-written types agree.
+ *
+ * Nothing here runs. It exists so that changing a schema in `contract.ts`
+ * without changing the matching interface in `types.ts` fails `tsc` instead of
+ * failing later, in the browser, as a shape that is almost right.
+ */
+import type {
+  OperationInput,
+  OperationOutput,
+  StreamEvent,
+  StreamParams,
+} from '../../shared/contract.ts';
+import type { AiContract } from './contract.ts';
+import type {
+  AiSettings,
+  BroappModel,
+  ChatEvent,
+  ChatFile,
+  ProviderInfo,
+  StoredMessage,
+  Thread,
+} from './types.ts';
+
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+  ? true
+  : false;
+
+const settingsMatch: Equal<OperationOutput<AiContract, 'ai.settingsGet'>, AiSettings> = true;
+void settingsMatch;
+
+const settingsUpdateReturnsSettings: Equal<
+  OperationOutput<AiContract, 'ai.settingsUpdate'>,
+  AiSettings
+> = true;
+void settingsUpdateReturnsSettings;
+
+const modelMatch: Equal<
+  OperationOutput<AiContract, 'ai.modelsList'>['models'][number],
+  BroappModel
+> = true;
+void modelMatch;
+
+const providerMatch: Equal<
+  OperationOutput<AiContract, 'ai.providersList'>['providers'][number],
+  ProviderInfo
+> = true;
+void providerMatch;
+
+const chatEventMatch: Equal<StreamEvent<AiContract, 'ai.chat'>, ChatEvent> = true;
+void chatEventMatch;
+
+const chatFileMatch: Equal<
+  NonNullable<StreamParams<AiContract, 'ai.chat'>['files']>[number],
+  ChatFile
+> = true;
+void chatFileMatch;
+
+const threadMatch: Equal<OperationOutput<AiContract, 'ai.threadsCreate'>, Thread> = true;
+void threadMatch;
+
+const storedMessageMatch: Equal<
+  OperationOutput<AiContract, 'ai.threadsGet'>['messages'][number],
+  StoredMessage
+> = true;
+void storedMessageMatch;
+
+// The update route is the only one that takes a partial: every field optional,
+// so a browser can change one setting without restating the rest.
+const updateAcceptsNothing: OperationInput<AiContract, 'ai.settingsUpdate'> = {};
+void updateAcceptsNothing;

package/src/ai/shared/types.ts

@@ -0,0 +1,147 @@
+/**
+ * The types the browser sees.
+ *
+ * Everything here is shared code: it names what the AI layer exchanges over
+ * the bridge and nothing about how a provider is reached. No file in this
+ * directory may import the AI SDK packages — the browser bundle follows these
+ * imports, and the page's CSP forbids it from talking to a provider anyway.
+ *
+ * The fields are not marked `readonly`. These interfaces must be *identical*
+ * to what `Infer` derives from the contract in `contract.ts`, which
+ * `types.check.ts` asserts at compile time; a `readonly` here would make the
+ * two types merely compatible instead, and the drift check would stop
+ * catching drift.
+ */
+
+/** A model a provider offers, as the browser sees it. */
+export interface BroappModel {
+  provider: string;
+  modelId: string;
+  label: string;
+  capabilities: {
+    tools: boolean;
+    vision: boolean;
+    structuredOutput: boolean;
+  };
+}
+
+/** A provider compiled into this application, as the browser sees it. */
+export interface ProviderInfo {
+  id: string;
+  label: string;
+  /** True when requests stay on this machine with the current settings. */
+  local: boolean;
+  needs: {
+    apiKey: 'required' | 'optional' | 'none';
+    baseUrl: 'required' | 'optional' | 'none';
+  };
+  defaultBaseUrl: string | null;
+}
+
+/** What the settings route returns. Never contains the key itself. */
+export interface AiSettings {
+  provider: string | null;
+  modelId: string | null;
+  baseUrl: string | null;
+  hasKey: boolean;
+  /** Last four characters of the key, for the UI to show which key is set. */
+  keyHint: string | null;
+  /** False means the key is held in memory only and forgotten on exit. */
+  remember: boolean;
+  /** True when provider and model are both set and the provider's needs are met. */
+  configured: boolean;
+}
+
+/** How much ceremony a tool call needs before it runs. */
+export type ToolPermission = 'read' | 'confirm';
+
+/** One turn of prior conversation the browser sends back with each message. */
+export interface ChatTurn {
+  role: 'user' | 'assistant';
+  content: string;
+}
+
+/**
+ * One image sent with a chat turn.
+ *
+ * `data` is base64 with no `data:` prefix, at most 2,000,000 characters, and
+ * `mediaType` is one of `image/png`, `image/jpeg`, `image/gif`, `image/webp`.
+ * At most four travel with one message, and they travel only with the message
+ * they arrive on: a later turn's `history` keeps the line
+ * `[image: <name>]` in place of the image itself, because a transcript of
+ * base64 would not fit inside the contract's bound on a turn.
+ */
+export interface ChatFile {
+  name: string;
+  mediaType: string;
+  data: string;
+}
+
+/**
+ * A stored conversation, without its messages.
+ *
+ * `modelId` is null for a conversation that follows Settings, and a model id
+ * for one that has been pinned to a model of its own. The provider is never
+ * part of a conversation: it is a Settings decision, because changing it
+ * changes which key is used and whether anything leaves the computer.
+ */
+export interface Thread {
+  id: string;
+  title: string;
+  modelId: string | null;
+  createdAt: number;
+  updatedAt: number;
+  messageCount: number;
+}
+
+/**
+ * One message as it is stored.
+ *
+ * `parts` are the AI SDK's own message parts. The host writes them as JSON and
+ * hands them back unread — it has no opinion about what a part is, which is
+ * why the type is `unknown[]` rather than a copy of the SDK's union that would
+ * drift from it. One thing the host *does* change on the way in: a `file` part
+ * becomes the text `[image: name]`, because a data URL in SQLite would be a
+ * copy of the image nobody asked to keep.
+ */
+export interface StoredMessage {
+  id: string;
+  role: 'user' | 'assistant' | 'system';
+  parts: unknown[];
+  metadata?: unknown;
+}
+
+/**
+ * One event on the `ai.chat` stream. Flat on purpose: the `s` validator has
+ * no unions, so the discriminant is `type` and the other fields are
+ * optional. Which fields are present for which type:
+ *
+ *   text        text
+ *   tool-call   callId, tool, input, permission
+ *   confirm     callId, tool, input, requestId, releaseId, argumentsHash,
+ *               expiresAt                    (waits for ai.chatConfirm)
+ *   tool-result callId, tool, output, denied?
+ *   usage       inputTokens, outputTokens
+ *   done        —
+ *   error       code, message
+ */
+export interface ChatEvent {
+  type: 'text' | 'tool-call' | 'confirm' | 'tool-result' | 'usage' | 'done' | 'error';
+  text?: string;
+  callId?: string;
+  tool?: string;
+  input?: unknown;
+  output?: unknown;
+  denied?: boolean;
+  permission?: ToolPermission;
+  /** On `confirm`: what the gate is waiting on, so an answer can name it. */
+  requestId?: string;
+  releaseId?: string;
+  argumentsHash?: string;
+  /** On `confirm`: when the question stops waiting, so the card can count down. */
+  expiresAt?: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  code?: string;
+  message?: string;
+}