broapp 0.1.0 → 0.3.0

package/src/ai/react/provider.tsx

@@ -0,0 +1,97 @@
+/**
+ * Shared AI state for everything below it.
+ *
+ * The settings panel and the chat panel both need to know whether AI is
+ * configured, and they must not disagree — a chat that says "not set up" next
+ * to a panel that just saved a key is worse than either alone. So the settings
+ * are fetched once, here, and both read them from the same place.
+ */
+import * as React from 'react';
+
+import type { BroappClient } from '../../client/client.ts';
+import { BroappError } from '../../shared/errors.ts';
+import { useBroapp, useBroappContract, useBroappReady, useConnection } from '../../react/hooks.tsx';
+import type { AiContract } from '../shared/contract.ts';
+import type { AiSettings } from '../shared/types.ts';
+
+/** The AI client: the same connection, typed against the AI contract. */
+export type AiClient = BroappClient<AiContract>;
+
+interface AiContextValue {
+  readonly settings: AiSettings | null;
+  readonly error: BroappError | null;
+  readonly loading: boolean;
+  refresh(): Promise<void>;
+  /** Write the settings other hooks just fetched, so one round trip serves all. */
+  put(settings: AiSettings): void;
+  client(): Promise<AiClient>;
+}
+
+const AiContext = React.createContext<AiContextValue | null>(null);
+
+/** The route every installation of the AI contract has. */
+const PROBE_ROUTE = 'ai.settingsGet';
+
+const MISSING_CONTRACT =
+  'AiProvider needs the AI contract: <BroappProvider contract={contract} extensions={[aiContract]}>';
+
+/** Owns the AI settings for the components below it. */
+export function AiProvider({ children }: { children: React.ReactNode }): React.ReactElement {
+  const contract = useBroappContract();
+  if (!Object.prototype.hasOwnProperty.call(contract.operations, PROBE_ROUTE)) {
+    // Thrown at render rather than at the first call: the mistake is in the
+    // provider setup, and that is where a developer should be sent.
+    throw new Error(MISSING_CONTRACT);
+  }
+
+  const broapp = useBroapp<AiContract>();
+  const ready = useBroappReady<AiContract>();
+  const connection = useConnection();
+  const [settings, setSettings] = React.useState<AiSettings | null>(null);
+  const [error, setError] = React.useState<BroappError | null>(null);
+  const [loading, setLoading] = React.useState(false);
+
+  const client = React.useCallback(
+    async (): Promise<AiClient> => broapp ?? (await ready),
+    [broapp, ready],
+  );
+
+  const refresh = React.useCallback(async (): Promise<void> => {
+    setLoading(true);
+    try {
+      const connected = await client();
+      setSettings(await connected.call('ai.settingsGet', undefined));
+      setError(null);
+    } catch (cause) {
+      setError(
+        cause instanceof BroappError
+          ? cause
+          : new BroappError('internal', 'The AI settings could not be read.', cause),
+      );
+    } finally {
+      setLoading(false);
+    }
+  }, [client]);
+
+  // Once, when there is something to talk to. A settings read before the
+  // connection settles would only fail and have to be retried.
+  const fetched = React.useRef(false);
+  React.useEffect(() => {
+    if (connection.phase !== 'ready' || fetched.current) return;
+    fetched.current = true;
+    void refresh();
+  }, [connection.phase, refresh]);
+
+  const value = React.useMemo<AiContextValue>(
+    () => ({ settings, error, loading, refresh, put: setSettings, client }),
+    [settings, error, loading, refresh, client],
+  );
+  return <AiContext.Provider value={value}>{children}</AiContext.Provider>;
+}
+
+/** The shared AI state. Throws outside {@link AiProvider}. */
+export function useAiContext(): AiContextValue {
+  const value = React.useContext(AiContext);
+  if (value === null) throw new Error('This hook must be used inside <AiProvider>');
+  return value;
+}

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

@@ -0,0 +1,317 @@
+/**
+ * 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;
+  /** While awaiting confirmation: when the question stops waiting. */
+  readonly expiresAt?: number;
+}
+
+/** 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',
+                    ...(event.expiresAt === undefined ? {} : { expiresAt: event.expiresAt }),
+                  }
+                : 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,
+  };
+}