broapp 0.1.0 → 0.3.0

package/src/ai/react/AiChat.tsx

@@ -0,0 +1,242 @@
+/**
+ * The chat panel.
+ *
+ * The assistant's text is rendered as text. No markdown library, no
+ * `dangerouslySetInnerHTML`: the content is written by a model that has just
+ * been shown documents from the user's own machine, and a renderer that turns
+ * some of that into markup is a way for a document to reach the page. A
+ * `<pre>` with `white-space: pre-wrap` keeps the line breaks, which is most of
+ * what markdown would have been used for anyway.
+ */
+import * as React from 'react';
+
+import { countdown, isUrgent } from '../../shared/countdown.ts';
+
+import { useAiChat, type AiChatOptions, type ToolCallState } from './use-ai-chat.ts';
+import { useAiSettings } from './use-ai-settings.ts';
+
+/** Props for {@link AiChat}. */
+export interface AiChatProps {
+  /** Records the user is looking at, sent with every message. */
+  readonly refs?: readonly string[];
+  readonly placeholder?: string;
+  readonly emptyText?: string;
+  /** Called when a tool call settles, so the application can refetch. */
+  readonly onToolResult?: AiChatOptions['onToolResult'];
+  /**
+   * How many tool calls are waiting for the person, whenever that changes.
+   *
+   * The panel does not act on this itself: a tab that renamed itself or raised
+   * a notification without being asked would do it in every application that
+   * embeds a chat. The launcher asks, because its questions arrive after ten
+   * minutes of silence and the person is not looking at the tab.
+   */
+  readonly onAwaiting?: (pending: number) => void;
+}
+
+/** Re-render once a second while `active`, so a countdown counts. */
+function useTick(active: boolean): number {
+  const [now, setNow] = React.useState(() => Date.now());
+  React.useEffect(() => {
+    if (!active) return undefined;
+    setNow(Date.now());
+    const timer = setInterval(() => setNow(Date.now()), 1_000);
+    return () => clearInterval(timer);
+  }, [active]);
+  return now;
+}
+
+function ToolCall({
+  call,
+  onConfirm,
+}: {
+  call: ToolCallState;
+  onConfirm: (callId: string, approve: boolean) => void;
+}): React.ReactElement {
+  const waiting = call.status === 'awaiting-confirmation' && call.expiresAt !== undefined;
+  const now = useTick(waiting);
+  const urgent = call.expiresAt !== undefined && waiting && isUrgent(call.expiresAt, now);
+  return (
+    <div className="ai-chat__tool">
+      <details>
+        <summary>
+          {call.status === 'denied' ? 'Declined' : 'Used'} {call.tool}
+        </summary>
+        <pre className="ai-chat__json">{JSON.stringify(call.input, null, 2)}</pre>
+        {call.output === undefined ? null : (
+          <pre className="ai-chat__json">{JSON.stringify(call.output, null, 2)}</pre>
+        )}
+      </details>
+      {call.status !== 'awaiting-confirmation' ? null : (
+        <div
+          className={`ai-chat__confirm${urgent ? ' ai-chat__confirm--urgent' : ''}`}
+          role="group"
+          aria-label={`Allow ${call.tool}?`}
+        >
+          <span>Allow this?</span>
+          {call.expiresAt === undefined ? null : (
+            <span className="ai-chat__expires">expires in {countdown(call.expiresAt, now)}</span>
+          )}
+          <button
+            className="button button--primary"
+            type="button"
+            onClick={() => onConfirm(call.callId, true)}
+          >
+            Allow
+          </button>
+          <button className="button" type="button" onClick={() => onConfirm(call.callId, false)}>
+            Decline
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export function AiChat({
+  refs,
+  placeholder,
+  emptyText,
+  onToolResult,
+  onAwaiting,
+}: AiChatProps): React.ReactElement {
+  const { settings } = useAiSettings();
+  const chat = useAiChat({
+    ...(refs === undefined ? {} : { refs }),
+    ...(onToolResult === undefined ? {} : { onToolResult }),
+  });
+  const [draft, setDraft] = React.useState('');
+  const input = React.useRef<HTMLTextAreaElement | null>(null);
+  const busy = chat.status === 'streaming' || chat.status === 'awaiting-confirmation';
+
+  const waiting = chat.messages.reduce(
+    (count, message) =>
+      message.role === 'assistant'
+        ? count +
+          message.toolCalls.filter((call) => call.status === 'awaiting-confirmation').length
+        : count,
+    0,
+  );
+  const announce = React.useRef(onAwaiting);
+  announce.current = onAwaiting;
+  React.useEffect(() => {
+    announce.current?.(waiting);
+  }, [waiting]);
+
+  // Back to the box when the turn ends, so a conversation can be carried on
+  // without reaching for the mouse.
+  React.useEffect(() => {
+    if (chat.status === 'idle') input.current?.focus();
+  }, [chat.status]);
+
+  if (settings === null || settings.configured !== true) {
+    return (
+      <section className="card ai-chat" aria-labelledby="ai-chat-title">
+        <h2 className="card__title" id="ai-chat-title">
+          Assistant
+        </h2>
+        <p className="form__hint">
+          {/* Until the first settings read returns there is nothing to say yet,
+              and saying "not set up" would be a guess that is wrong as often as
+              it is right. */}
+          {settings === null
+            ? 'Checking the AI settings…'
+            : 'AI is not set up. Open Settings to choose a provider.'}
+        </p>
+      </section>
+    );
+  }
+
+  const submit = (): void => {
+    const text = draft;
+    setDraft('');
+    void chat.send(text);
+  };
+
+  return (
+    <section className="card ai-chat" aria-labelledby="ai-chat-title">
+      <h2 className="card__title" id="ai-chat-title">
+        Assistant
+      </h2>
+
+      <div className="ai-chat__messages" role="log" aria-live="polite">
+        {chat.messages.length === 0 ? (
+          <p className="form__hint">{emptyText ?? 'Ask a question about what you are looking at.'}</p>
+        ) : null}
+        {chat.messages.map((message) =>
+          message.role === 'user' ? (
+            <div className="ai-chat__message ai-chat__message--user" key={message.id}>
+              <pre className="ai-chat__text">{message.content}</pre>
+            </div>
+          ) : (
+            <div className="ai-chat__message ai-chat__message--assistant" key={message.id}>
+              {message.toolCalls.map((call) => (
+                <ToolCall
+                  call={call}
+                  key={call.callId}
+                  onConfirm={(callId, approve) => void chat.confirm(callId, approve)}
+                />
+              ))}
+              <pre className="ai-chat__text">{message.content}</pre>
+              {message.pending ? <span className="ai-chat__typing">…</span> : null}
+            </div>
+          ),
+        )}
+      </div>
+
+      {chat.error === null ? null : (
+        <p className="message message--error" role="alert">
+          {chat.error}
+        </p>
+      )}
+      {chat.usage === null ? null : (
+        <p className="form__hint ai-chat__usage">
+          {chat.usage.inputTokens} tokens in, {chat.usage.outputTokens} out
+        </p>
+      )}
+
+      <div className="ai-chat__composer">
+        <label className="form__label" htmlFor="ai-chat-input">
+          Message
+        </label>
+        <textarea
+          className="input ai-chat__input"
+          id="ai-chat-input"
+          ref={input}
+          rows={3}
+          placeholder={placeholder ?? 'Ask about these notes'}
+          value={draft}
+          onChange={(event) => setDraft(event.target.value)}
+          onKeyDown={(event) => {
+            // Enter sends; Shift+Enter is a newline. Anything with a modifier
+            // is left alone, so the platform shortcuts still work.
+            if (event.key !== 'Enter' || event.shiftKey || event.metaKey || event.ctrlKey) return;
+            event.preventDefault();
+            if (!busy) submit();
+          }}
+        />
+        <div className="ai-chat__actions">
+          <button
+            className="button button--primary"
+            type="button"
+            disabled={busy || draft.trim() === ''}
+            onClick={submit}
+          >
+            Send
+          </button>
+          <button className="button" type="button" disabled={!busy} onClick={chat.cancel}>
+            Stop
+          </button>
+          <button
+            className="button"
+            type="button"
+            disabled={chat.messages.length === 0}
+            onClick={chat.clear}
+          >
+            Clear
+          </button>
+        </div>
+      </div>
+    </section>
+  );
+}

package/src/ai/react/AiSettings.tsx

@@ -0,0 +1,228 @@
+/**
+ * The settings panel.
+ *
+ * Two things here are deliberate and worth keeping. The key input is
+ * write-only — it starts empty, is never filled in from the host, and is
+ * cleared after a save — because a key that can be read back out of the
+ * interface is a key that can be read by anything that can reach the
+ * interface. And the data notice is always visible once a provider is chosen,
+ * because "where do my notes go" is not a question a user should have to open
+ * a menu to answer.
+ */
+import * as React from 'react';
+
+import { useAiModels } from './use-ai-models.ts';
+import { useAiSettings, type ConnectionResult } from './use-ai-settings.ts';
+
+/** Shown while nothing is chosen. */
+const NOT_SET_UP = 'Not set up';
+
+export function AiSettings(): React.ReactElement {
+  const { settings, providers, pending, error, update, test } = useAiSettings();
+  const models = useAiModels();
+  const [key, setKey] = React.useState('');
+  const [baseUrl, setBaseUrl] = React.useState<string | null>(null);
+  const [result, setResult] = React.useState<ConnectionResult | null>(null);
+
+  const provider = providers.find((entry) => entry.id === settings?.provider) ?? null;
+  // The input tracks the saved value until the user types, at which point
+  // their draft wins until it is saved on blur.
+  const urlValue = baseUrl ?? settings?.baseUrl ?? '';
+
+  const onProvider = async (id: string): Promise<void> => {
+    setResult(null);
+    setBaseUrl(null);
+    setKey('');
+    await update(id === '' ? { provider: undefined } : { provider: id });
+  };
+
+  const onSaveKey = async (): Promise<void> => {
+    if (key === '') return;
+    await update({ apiKey: key });
+    setKey('');
+  };
+
+  return (
+    <section className="card ai-settings" aria-labelledby="ai-settings-title">
+      <h2 className="card__title" id="ai-settings-title">
+        AI
+      </h2>
+
+      {error !== null ? (
+        <p className="message message--error" role="alert">
+          {error.message}
+        </p>
+      ) : null}
+
+      <div className="form__row">
+        <label className="form__label" htmlFor="ai-provider">
+          Provider
+        </label>
+        <select
+          className="input input--select"
+          id="ai-provider"
+          disabled={pending}
+          value={settings?.provider ?? ''}
+          onChange={(event) => void onProvider(event.target.value)}
+        >
+          <option value="">{NOT_SET_UP}</option>
+          {providers.map((entry) => (
+            <option key={entry.id} value={entry.id}>
+              {entry.label}
+            </option>
+          ))}
+        </select>
+      </div>
+
+      {provider === null ? null : (
+        <>
+          {provider.needs.baseUrl === 'none' ? null : (
+            <div className="form__row">
+              <label className="form__label" htmlFor="ai-base-url">
+                Server address{provider.needs.baseUrl === 'required' ? ' (required)' : ''}
+              </label>
+              <input
+                className="input"
+                id="ai-base-url"
+                type="url"
+                autoComplete="off"
+                spellCheck={false}
+                disabled={pending}
+                placeholder={provider.defaultBaseUrl ?? 'http://127.0.0.1:11434/v1'}
+                value={urlValue}
+                onChange={(event) => setBaseUrl(event.target.value)}
+                onBlur={() => {
+                  if (baseUrl === null) return;
+                  const next = baseUrl.trim();
+                  setBaseUrl(null);
+                  void update({ baseUrl: next === '' ? null : next });
+                }}
+              />
+            </div>
+          )}
+
+          {provider.needs.apiKey === 'none' ? null : (
+            <div className="form__row">
+              <label className="form__label" htmlFor="ai-key">
+                API key{provider.needs.apiKey === 'optional' ? ' (optional)' : ''}
+              </label>
+              {provider.needs.apiKey === 'optional' ? (
+                <p className="form__hint">
+                  Needed for a hosted service such as OpenRouter. Leave empty for a server on this
+                  computer that does not ask for one.
+                </p>
+              ) : null}
+              <div className="ai-settings__key">
+                <input
+                  className="input"
+                  id="ai-key"
+                  type="password"
+                  autoComplete="off"
+                  spellCheck={false}
+                  disabled={pending}
+                  placeholder={settings?.hasKey === true ? 'Replace the saved key' : 'Paste the key'}
+                  value={key}
+                  onChange={(event) => setKey(event.target.value)}
+                  onBlur={() => void onSaveKey()}
+                />
+                <button
+                  className="button button--primary"
+                  type="button"
+                  disabled={pending || key === ''}
+                  onClick={() => void onSaveKey()}
+                >
+                  Save key
+                </button>
+              </div>
+              {settings?.hasKey === true ? (
+                <p className="form__hint">
+                  A key ending in {settings.keyHint ?? '…'} is saved.{' '}
+                  <button
+                    className="button"
+                    type="button"
+                    disabled={pending}
+                    onClick={() => void update({ apiKey: null })}
+                  >
+                    Remove key
+                  </button>
+                </p>
+              ) : null}
+              <label className="form__label ai-settings__remember" htmlFor="ai-remember">
+                <input
+                  id="ai-remember"
+                  type="checkbox"
+                  disabled={pending}
+                  checked={settings?.remember ?? true}
+                  onChange={(event) => void update({ remember: event.target.checked })}
+                />
+                Remember key on this computer
+              </label>
+              <p className="form__hint">
+                Stored in this application&rsquo;s data folder, readable by your user account. Turn
+                off to keep it only until the app closes.
+              </p>
+            </div>
+          )}
+
+          <div className="form__row">
+            <label className="form__label" htmlFor="ai-model">
+              Model
+            </label>
+            <div className="ai-settings__key">
+              <select
+                className="input input--select"
+                id="ai-model"
+                disabled={pending || models.pending}
+                value={settings?.modelId ?? ''}
+                onChange={(event) => void update({ modelId: event.target.value })}
+              >
+                <option value="">{models.pending ? 'Loading…' : 'Choose a model'}</option>
+                {models.models.map((model) => (
+                  <option key={model.modelId} value={model.modelId}>
+                    {model.label}
+                  </option>
+                ))}
+              </select>
+              <button
+                className="button"
+                type="button"
+                disabled={models.pending}
+                onClick={() => void models.refresh()}
+              >
+                Refresh
+              </button>
+            </div>
+            {models.error === null ? null : (
+              <p className="message message--error" role="alert">
+                {models.error.message}
+              </p>
+            )}
+          </div>
+
+          <p className="ai-settings__notice" role="status">
+            {provider.local
+              ? 'Runs on this computer. Nothing is sent over the internet.'
+              : `Messages, the documents you are viewing, and search results are sent to ${provider.label} to generate answers.`}
+          </p>
+
+          <div className="form__row">
+            <button
+              className="button button--primary"
+              type="button"
+              disabled={pending}
+              onClick={() => void test().then(setResult)}
+            >
+              Test connection
+            </button>
+            {result === null ? null : (
+              <p className={`message ${result.ok ? 'message--ok' : 'message--error'}`} role="status">
+                {result.message}
+                {result.ok ? ` (${String(result.latencyMs)} ms)` : ''}
+              </p>
+            )}
+          </div>
+        </>
+      )}
+    </section>
+  );
+}

package/src/ai/react/ai.css

@@ -0,0 +1,166 @@
+/*
+ * Styles for the AI panels.
+ *
+ * Ordinary CSS, no framework, no web font, no `@import` and no `url()`: a
+ * Broapp page loads nothing from off-origin, and `broapp build` fails the
+ * build if it finds anything that would. The custom properties are the ones an
+ * application already defines for its own interface, so these panels take on
+ * its colours rather than imposing their own; the fallbacks are there so the
+ * components are still legible in an application that defines none.
+ */
+
+.ai-settings__key {
+  display: flex;
+  gap: 0.5rem;
+  align-items: center;
+}
+
+.ai-settings__key .input {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.ai-settings__remember {
+  display: flex;
+  gap: 0.5rem;
+  align-items: center;
+  margin-top: 0.75rem;
+  font-weight: 400;
+}
+
+/*
+ * Always visible once a provider is chosen. "Where do my notes go" is not a
+ * question a user should have to open a menu to answer.
+ */
+.ai-settings__notice {
+  margin: 0.75rem 0;
+  padding: 0.6rem 0.75rem;
+  border: 1px solid var(--border, #e3e2df);
+  border-radius: var(--radius, 10px);
+  color: var(--text-muted, #6b6862);
+  font-size: 0.9rem;
+}
+
+.ai-chat__messages {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  max-height: 24rem;
+  overflow-y: auto;
+  padding: 0.25rem;
+}
+
+.ai-chat__message {
+  padding: 0.6rem 0.75rem;
+  border-radius: var(--radius, 10px);
+  max-width: 90%;
+}
+
+.ai-chat__message--user {
+  align-self: flex-end;
+  background: var(--accent, #1f5f4f);
+  color: var(--accent-contrast, #ffffff);
+}
+
+.ai-chat__message--assistant {
+  align-self: flex-start;
+  background: var(--surface, #ffffff);
+  border: 1px solid var(--border, #e3e2df);
+  color: var(--text, #1b1a18);
+}
+
+/*
+ * A `<pre>` rather than a markdown renderer. The text was written by a model
+ * that has just been shown documents from this machine; turning parts of it
+ * into markup would be a way for a document to reach the page.
+ */
+.ai-chat__text {
+  margin: 0;
+  font: inherit;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+.ai-chat__tool {
+  margin-bottom: 0.5rem;
+  font-size: 0.9rem;
+  color: var(--text-muted, #6b6862);
+}
+
+.ai-chat__json {
+  margin: 0.4rem 0 0;
+  padding: 0.5rem;
+  border-radius: var(--radius, 10px);
+  background: var(--bg, #fbfbfa);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 0.8rem;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+.ai-chat__confirm {
+  display: flex;
+  gap: 0.5rem;
+  align-items: center;
+  margin-top: 0.4rem;
+  padding: 0.5rem;
+  border: 1px solid var(--pending, #8a6a12);
+  border-radius: var(--radius, 10px);
+  color: var(--text, #1b1a18);
+}
+
+/* Under a minute left. Amber and a little heavier, so a card that is about to
+   expire is not the same shape as one with nine minutes on it. */
+.ai-chat__confirm--urgent {
+  border-color: var(--warning, #b4690e);
+  background: var(--warning-bg, #fdf3e3);
+}
+
+.ai-chat__expires {
+  margin-left: auto;
+  color: var(--text-muted, #6b6862);
+  font-size: 0.8rem;
+  font-variant-numeric: tabular-nums;
+}
+
+.ai-chat__typing {
+  display: inline-block;
+  margin-left: 0.25rem;
+  color: var(--text-muted, #6b6862);
+  animation: ai-chat-pulse 1.2s ease-in-out infinite;
+}
+
+@keyframes ai-chat-pulse {
+  0%,
+  100% {
+    opacity: 0.35;
+  }
+  50% {
+    opacity: 1;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ai-chat__typing {
+    animation: none;
+  }
+}
+
+.ai-chat__usage {
+  margin: 0.5rem 0 0;
+}
+
+.ai-chat__composer {
+  margin-top: 0.75rem;
+}
+
+.ai-chat__input {
+  width: 100%;
+  resize: vertical;
+}
+
+.ai-chat__actions {
+  display: flex;
+  gap: 0.5rem;
+  margin-top: 0.5rem;
+}

package/src/ai/react/index.tsx

@@ -0,0 +1,38 @@
+/**
+ * `broapp/ai/react` — the AI layer's interface.
+ *
+ * Shared code: nothing here imports the AI SDK, and a browser bundle that
+ * follows these imports gets the contract and the components and nothing else.
+ * Pair it with `ai.css`, or write your own using the class names these
+ * components emit.
+ */
+export { AiProvider, useAiContext } from './provider.tsx';
+export type { AiClient } from './provider.tsx';
+
+export { useAiSettings } from './use-ai-settings.ts';
+export type { AiSettingsHook, ConnectionResult, UpdatePatch } from './use-ai-settings.ts';
+
+export { useAiModels } from './use-ai-models.ts';
+export type { AiModelsHook } from './use-ai-models.ts';
+
+export { useAiChat } from './use-ai-chat.ts';
+export type { AiChatHook, AiChatOptions, ChatMessage, ToolCallState } from './use-ai-chat.ts';
+
+export { AiSettings } from './AiSettings.tsx';
+export { AiChat } from './AiChat.tsx';
+export type { AiChatProps } from './AiChat.tsx';
+
+// Re-exported so an application needs one import to install the extension.
+export { aiContract } from '../shared/index.ts';
+export type {
+  AiContract,
+  AiSettings as AiSettingsValue,
+  BroappModel,
+  ChatEvent,
+  ChatFile,
+  ChatTurn,
+  ProviderInfo,
+  StoredMessage,
+  Thread,
+  ToolPermission,
+} from '../shared/index.ts';