broapp 0.1.0 → 0.2.0

package/src/ai/react/use-ai-chat.ts

@@ -0,0 +1,309 @@
+/**
+ * One conversation.
+ *
+ * `useStream` is not used here: it keeps only the most recent event, and a
+ * chat needs every one of them in order. What it does copy exactly is
+ * `useStream`'s unmount behaviour — cancelling the subscription — because the
+ * producer is a process on the user's own machine and a stream nobody cancels
+ * goes on running the model.
+ */
+import * as React from 'react';
+
+import type { Subscription } from '../../client/client.ts';
+import { BroappError } from '../../shared/errors.ts';
+import type { ChatEvent, ChatTurn } from '../shared/types.ts';
+
+import { useAiContext } from './provider.tsx';
+
+/** What one tool call is doing. */
+export interface ToolCallState {
+  readonly callId: string;
+  readonly tool: string;
+  readonly input: unknown;
+  readonly status: 'running' | 'awaiting-confirmation' | 'done' | 'denied';
+  readonly output?: unknown;
+}
+
+/** One message in the transcript. */
+export type ChatMessage =
+  | { readonly id: string; readonly role: 'user'; readonly content: string }
+  | {
+      readonly id: string;
+      readonly role: 'assistant';
+      readonly content: string;
+      readonly toolCalls: ToolCallState[];
+      readonly pending: boolean;
+    };
+
+/** What {@link useAiChat} returns. */
+export interface AiChatHook {
+  readonly messages: ChatMessage[];
+  readonly status: 'idle' | 'streaming' | 'awaiting-confirmation' | 'error';
+  readonly error: string | null;
+  readonly usage: { inputTokens: number; outputTokens: number } | null;
+  send(text: string): Promise<void>;
+  cancel(): void;
+  confirm(callId: string, approve: boolean): Promise<void>;
+  clear(): void;
+}
+
+/** The contract caps history at 100 turns; the oldest are dropped. */
+const MAX_HISTORY = 100;
+
+/** A run id matching the contract's pattern. */
+function newRunId(): string {
+  return crypto.randomUUID().replace(/-/g, '');
+}
+
+/** Every completed turn, as the model should see it. */
+function toHistory(messages: readonly ChatMessage[]): ChatTurn[] {
+  const turns: ChatTurn[] = [];
+  for (const message of messages) {
+    if (message.role === 'assistant' && (message.pending || message.content === '')) continue;
+    turns.push({ role: message.role, content: message.content });
+  }
+  return turns.slice(-MAX_HISTORY);
+}
+
+/** Options for {@link useAiChat}. */
+export interface AiChatOptions {
+  /** Records the user is looking at, sent with every message. */
+  readonly refs?: readonly string[];
+  /**
+   * Called when a tool call settles.
+   *
+   * An application uses it to refetch whatever the model just changed. It is
+   * called for denied calls too, so a panel can stop showing them as pending.
+   */
+  onToolResult?(call: ToolCallState): void;
+}
+
+export function useAiChat(options: AiChatOptions = {}): AiChatHook {
+  const shared = useAiContext();
+  const [messages, setMessages] = React.useState<ChatMessage[]>([]);
+  const [status, setStatus] = React.useState<AiChatHook['status']>('idle');
+  const [error, setError] = React.useState<string | null>(null);
+  const [usage, setUsage] = React.useState<AiChatHook['usage']>(null);
+  const active = React.useRef<Subscription | null>(null);
+  const runId = React.useRef<string>('');
+  const mounted = React.useRef(true);
+  const refs = options.refs ?? [];
+  // Read inside the subscription callbacks, which are created once per send.
+  const refsRef = React.useRef<readonly string[]>(refs);
+  refsRef.current = refs;
+  const onToolResult = React.useRef<AiChatOptions['onToolResult']>(undefined);
+  onToolResult.current = options.onToolResult;
+  // The tool calls of the turn in progress, by call id. A state updater cannot
+  // be used to find one: React runs it when it chooses, so anything read out
+  // of it is read too late to hand to a callback.
+  const calls = React.useRef(new Map<string, ToolCallState>());
+
+  React.useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+      active.current?.cancel();
+      active.current = null;
+    };
+  }, []);
+
+  /** Change the assistant message this turn is writing into. */
+  const patchPending = React.useCallback(
+    (change: (message: Extract<ChatMessage, { role: 'assistant' }>) => ChatMessage): void => {
+      setMessages((current) => {
+        const index = current.length - 1;
+        const last = current[index];
+        if (last === undefined || last.role !== 'assistant') return current;
+        const next = [...current];
+        next[index] = change(last);
+        return next;
+      });
+    },
+    [],
+  );
+
+  const apply = React.useCallback(
+    (event: ChatEvent): void => {
+      switch (event.type) {
+        case 'text':
+          patchPending((message) => ({ ...message, content: message.content + (event.text ?? '') }));
+          break;
+        case 'tool-call':
+          calls.current.set(event.callId ?? '', {
+            callId: event.callId ?? '',
+            tool: event.tool ?? '',
+            input: event.input,
+            status: 'running',
+          });
+          patchPending((message) => ({
+            ...message,
+            toolCalls: [
+              ...message.toolCalls,
+              {
+                callId: event.callId ?? '',
+                tool: event.tool ?? '',
+                input: event.input,
+                status: 'running',
+              },
+            ],
+          }));
+          break;
+        case 'confirm':
+          setStatus('awaiting-confirmation');
+          patchPending((message) => ({
+            ...message,
+            toolCalls: message.toolCalls.map((call) =>
+              call.callId === event.callId ? { ...call, status: 'awaiting-confirmation' } : call,
+            ),
+          }));
+          break;
+        case 'tool-result': {
+          setStatus((current) => (current === 'awaiting-confirmation' ? 'streaming' : current));
+          const started = calls.current.get(event.callId ?? '');
+          const settled: ToolCallState = {
+            callId: event.callId ?? '',
+            tool: event.tool ?? started?.tool ?? '',
+            input: started?.input,
+            status: event.denied === true ? 'denied' : 'done',
+            output: event.output,
+          };
+          calls.current.set(settled.callId, settled);
+          patchPending((message) => ({
+            ...message,
+            toolCalls: message.toolCalls.map((call) =>
+              call.callId === settled.callId ? settled : call,
+            ),
+          }));
+          // The application refetches whatever the model just changed.
+          onToolResult.current?.(settled);
+          break;
+        }
+        case 'usage':
+          setUsage({
+            inputTokens: event.inputTokens ?? 0,
+            outputTokens: event.outputTokens ?? 0,
+          });
+          break;
+        case 'done':
+          active.current = null;
+          setStatus('idle');
+          patchPending((message) => ({ ...message, pending: false }));
+          break;
+        case 'error':
+          active.current = null;
+          setStatus('error');
+          setError(event.message ?? 'The AI provider returned an error.');
+          patchPending((message) => ({ ...message, pending: false }));
+          break;
+      }
+    },
+    [patchPending],
+  );
+
+  const send = React.useCallback(
+    async (text: string): Promise<void> => {
+      // A second question while the first is still being answered would need a
+      // second run and a second transcript. Ignored rather than queued.
+      if (active.current !== null || status === 'streaming' || status === 'awaiting-confirmation') {
+        return;
+      }
+      const trimmed = text.trim();
+      if (trimmed === '') return;
+
+      const history = toHistory(messages);
+      calls.current.clear();
+      const id = newRunId();
+      runId.current = id;
+      setError(null);
+      setUsage(null);
+      setStatus('streaming');
+      setMessages((current) => [
+        ...current,
+        { id: `${id}-user`, role: 'user', content: trimmed },
+        { id: `${id}-assistant`, role: 'assistant', content: '', toolCalls: [], pending: true },
+      ]);
+
+      try {
+        const connected = await shared.client();
+        if (!mounted.current) return;
+        const subscription = await connected.subscribe(
+          'ai.chat',
+          { runId: id, message: trimmed, refs: [...refsRef.current], history },
+          {
+            onEvent: (event) => {
+              if (mounted.current) apply(event);
+            },
+            onDone: () => {
+              if (!mounted.current) return;
+              active.current = null;
+              setStatus((current) => (current === 'error' ? current : 'idle'));
+              patchPending((message) => ({ ...message, pending: false }));
+            },
+            onError: (cause) => {
+              if (!mounted.current) return;
+              active.current = null;
+              setStatus('error');
+              setError(cause.message);
+              patchPending((message) => ({ ...message, pending: false }));
+            },
+          },
+        );
+        if (!mounted.current) {
+          subscription.cancel();
+          return;
+        }
+        active.current = subscription;
+      } catch (cause) {
+        if (!mounted.current) return;
+        active.current = null;
+        setStatus('error');
+        setError(
+          cause instanceof BroappError ? cause.message : 'The conversation could not be started.',
+        );
+        patchPending((message) => ({ ...message, pending: false }));
+      }
+    },
+    [shared, status, messages, apply, patchPending],
+  );
+
+  const cancel = React.useCallback((): void => {
+    if (active.current === null) return;
+    active.current.cancel();
+    active.current = null;
+    setStatus('idle');
+    // The text so far is kept: the user asked to stop, not to undo.
+    patchPending((message) => ({ ...message, pending: false }));
+  }, [patchPending]);
+
+  const confirm = React.useCallback(
+    async (callId: string, approve: boolean): Promise<void> => {
+      try {
+        const connected = await shared.client();
+        const result = await connected.call('ai.chatConfirm', {
+          runId: runId.current,
+          callId,
+          approve,
+        });
+        if (!result.accepted) {
+          // Nobody was waiting: the turn timed out or was cancelled while the
+          // question was on screen.
+          setError('That request has expired.');
+        }
+      } catch (cause) {
+        setError(cause instanceof BroappError ? cause.message : 'That answer could not be sent.');
+      }
+    },
+    [shared],
+  );
+
+  const clear = React.useCallback((): void => {
+    active.current?.cancel();
+    active.current = null;
+    setMessages([]);
+    setStatus('idle');
+    setError(null);
+    setUsage(null);
+  }, []);
+
+  return { messages, status, error, usage, send, cancel, confirm, clear };
+}

package/src/ai/react/use-ai-models.ts

@@ -0,0 +1,70 @@
+/**
+ * The models the configured provider offers.
+ *
+ * Refetched whenever something that would change the answer changes — the
+ * provider, its address, or whether a key is set. Not on every settings write:
+ * choosing a model must not send the application back to the provider to ask
+ * what the models are.
+ */
+import * as React from 'react';
+
+import { BroappError } from '../../shared/errors.ts';
+import type { BroappModel } from '../shared/types.ts';
+
+import { useAiContext } from './provider.tsx';
+
+/** What {@link useAiModels} returns. */
+export interface AiModelsHook {
+  readonly models: BroappModel[];
+  readonly pending: boolean;
+  readonly error: BroappError | null;
+  refresh(): Promise<void>;
+}
+
+export function useAiModels(): AiModelsHook {
+  const shared = useAiContext();
+  const [models, setModels] = React.useState<BroappModel[]>([]);
+  const [pending, setPending] = React.useState(false);
+  const [error, setError] = React.useState<BroappError | null>(null);
+  const generation = React.useRef(0);
+
+  const provider = shared.settings?.provider ?? null;
+  const baseUrl = shared.settings?.baseUrl ?? null;
+  const hasKey = shared.settings?.hasKey ?? false;
+
+  const refresh = React.useCallback(async (): Promise<void> => {
+    if (provider === null) {
+      setModels([]);
+      return;
+    }
+    const mine = (generation.current += 1);
+    setPending(true);
+    setError(null);
+    try {
+      const connected = await shared.client();
+      const result = await connected.call('ai.modelsList', undefined);
+      // A slow answer for a provider the user has since changed must not
+      // replace the list they are looking at now.
+      if (generation.current !== mine) return;
+      setModels(result.models);
+    } catch (cause) {
+      if (generation.current !== mine) return;
+      setModels([]);
+      setError(
+        cause instanceof BroappError
+          ? cause
+          : new BroappError('internal', 'The model list could not be read.', cause),
+      );
+    } finally {
+      if (generation.current === mine) setPending(false);
+    }
+  }, [shared, provider]);
+
+  React.useEffect(() => {
+    void refresh();
+    // `baseUrl` and `hasKey` are not used inside `refresh`; they are here
+    // because changing either changes what the provider will answer.
+  }, [refresh, baseUrl, hasKey]);
+
+  return { models, pending, error, refresh };
+}

package/src/ai/react/use-ai-settings.ts

@@ -0,0 +1,105 @@
+/**
+ * Reading and changing the AI settings.
+ *
+ * Every change is written straight through: there is no Save button, because
+ * there is nothing to batch and a half-saved provider configuration is a state
+ * worth not having. The result of each write replaces the shared settings, so
+ * the rest of the interface updates without a second round trip.
+ */
+import * as React from 'react';
+
+import type { OperationInput } from '../../shared/contract.ts';
+import { BroappError } from '../../shared/errors.ts';
+import type { AiContract } from '../shared/contract.ts';
+import type { AiSettings, ProviderInfo } from '../shared/types.ts';
+
+import { useAiContext } from './provider.tsx';
+
+/** What `ai.settingsUpdate` accepts. */
+export type UpdatePatch = OperationInput<AiContract, 'ai.settingsUpdate'>;
+
+/** The result of a connection test. */
+export interface ConnectionResult {
+  readonly ok: boolean;
+  readonly message: string;
+  readonly latencyMs: number;
+}
+
+/** What {@link useAiSettings} returns. */
+export interface AiSettingsHook {
+  readonly settings: AiSettings | null;
+  readonly providers: ProviderInfo[];
+  readonly pending: boolean;
+  readonly error: BroappError | null;
+  update(patch: UpdatePatch): Promise<void>;
+  test(): Promise<ConnectionResult | null>;
+  refresh(): Promise<void>;
+}
+
+function asBroappError(cause: unknown, fallback: string): BroappError {
+  return cause instanceof BroappError ? cause : new BroappError('internal', fallback, cause);
+}
+
+/** The settings, the providers this build has, and the two ways to change them. */
+export function useAiSettings(): AiSettingsHook {
+  const shared = useAiContext();
+  const [providers, setProviders] = React.useState<ProviderInfo[]>([]);
+  const [pending, setPending] = React.useState(false);
+  const [error, setError] = React.useState<BroappError | null>(null);
+
+  // The provider list cannot change while the application runs — it is what
+  // was compiled in — so it is fetched once.
+  const fetched = React.useRef(false);
+  React.useEffect(() => {
+    if (fetched.current) return;
+    fetched.current = true;
+    void (async () => {
+      try {
+        const connected = await shared.client();
+        setProviders((await connected.call('ai.providersList', undefined)).providers);
+      } catch (cause) {
+        setError(asBroappError(cause, 'The provider list could not be read.'));
+      }
+    })();
+  }, [shared]);
+
+  const update = React.useCallback(
+    async (patch: UpdatePatch): Promise<void> => {
+      setPending(true);
+      setError(null);
+      try {
+        const connected = await shared.client();
+        shared.put(await connected.call('ai.settingsUpdate', patch));
+      } catch (cause) {
+        setError(asBroappError(cause, 'That setting could not be saved.'));
+      } finally {
+        setPending(false);
+      }
+    },
+    [shared],
+  );
+
+  const test = React.useCallback(async (): Promise<ConnectionResult | null> => {
+    setPending(true);
+    setError(null);
+    try {
+      const connected = await shared.client();
+      return await connected.call('ai.connectionTest', undefined);
+    } catch (cause) {
+      setError(asBroappError(cause, 'The connection could not be tested.'));
+      return null;
+    } finally {
+      setPending(false);
+    }
+  }, [shared]);
+
+  return {
+    settings: shared.settings,
+    providers,
+    pending: pending || shared.loading,
+    error: error ?? shared.error,
+    update,
+    test,
+    refresh: shared.refresh,
+  };
+}

package/src/ai/shared/contract.ts

@@ -0,0 +1,138 @@
+/**
+ * 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.boolean(),
+    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 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'])),
+  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.',
+    },
+  },
+  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 }),
+      }),
+      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,16 @@
+/**
+ * `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,
+  ChatTurn,
+  ProviderInfo,
+  ToolPermission,
+} from './types.ts';

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

@@ -0,0 +1,43 @@
+/**
+ * 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 } from '../../shared/contract.ts';
+import type { AiContract } from './contract.ts';
+import type { AiSettings, BroappModel, ChatEvent, ProviderInfo } 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;
+
+// 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;