broapp 0.1.0 → 0.2.0

package/src/ai/host/secrets.ts

@@ -0,0 +1,118 @@
+/**
+ * Where the API key lives.
+ *
+ * `<dataDir>/ai/secrets.json` is a plain file, owned by the user, with mode
+ * 0600 — the same posture as `~/.aws/credentials` and `~/.npmrc`. It is not
+ * encrypted. What it protects against is another *user* on the machine and a
+ * backup that copies world-readable files. What it does not protect against is
+ * another process running as the same user: that process can read the file,
+ * and no scheme that runs unattended on the same account can prevent it.
+ *
+ * A user who does not want the key on disk can turn `remember` off, and the
+ * key is kept in memory for the life of the process instead.
+ */
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** A place to keep secrets by name. */
+export interface SecretStore {
+  get(name: string): Promise<string | null>;
+  set(name: string, value: string): Promise<void>;
+  delete(name: string): Promise<void>;
+}
+
+/** The secret name the layer uses for a provider's key. */
+export function apiKeySecretName(providerId: string): string {
+  return `provider:${providerId}:apiKey`;
+}
+
+/** A store that forgets everything when the process exits. */
+export function createMemorySecretStore(): SecretStore {
+  const values = new Map<string, string>();
+  return {
+    get: (name) => Promise.resolve(values.get(name) ?? null),
+    set: (name, value) => {
+      values.set(name, value);
+      return Promise.resolve();
+    },
+    delete: (name) => {
+      values.delete(name);
+      return Promise.resolve();
+    },
+  };
+}
+
+interface StoredSecrets {
+  version: 1;
+  secrets: Record<string, string>;
+}
+
+/** A store backed by `<dataDir>/ai/secrets.json`. */
+export function createFileSecretStore(dataDir: string): SecretStore {
+  const directory = join(dataDir, 'ai');
+  const file = join(directory, 'secrets.json');
+  const temporary = `${file}.tmp`;
+  let warned = false;
+
+  function read(): StoredSecrets {
+    let text: string;
+    try {
+      text = readFileSync(file, 'utf8');
+    } catch {
+      return { version: 1, secrets: {} };
+    }
+    try {
+      const parsed = JSON.parse(text) as unknown;
+      if (typeof parsed !== 'object' || parsed === null) throw new Error('not an object');
+      const secrets = (parsed as { secrets?: unknown }).secrets;
+      if (typeof secrets !== 'object' || secrets === null) throw new Error('no secrets');
+      const out: Record<string, string> = {};
+      for (const [name, value] of Object.entries(secrets as Record<string, unknown>)) {
+        if (typeof value === 'string') out[name] = value;
+      }
+      return { version: 1, secrets: out };
+    } catch {
+      // Warned once: a corrupt file would otherwise print on every read, and
+      // the layer reads settings often.
+      if (!warned) {
+        warned = true;
+        console.warn(`[broapp] ignoring unreadable AI secrets at ${file}`);
+      }
+      return { version: 1, secrets: {} };
+    }
+  }
+
+  function write(next: StoredSecrets): void {
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    writeFileSync(temporary, `${JSON.stringify(next, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    renameSync(temporary, file);
+    try {
+      chmodSync(file, 0o600);
+    } catch {
+      // Windows has no POSIX mode bits. The call is made anyway so that every
+      // platform that does have them gets them, and the one that does not is
+      // not a special case in the caller.
+    }
+  }
+
+  return {
+    get: (name) => Promise.resolve(read().secrets[name] ?? null),
+    set: (name, value) => {
+      const current = read();
+      write({ version: 1, secrets: { ...current.secrets, [name]: value } });
+      return Promise.resolve();
+    },
+    delete: (name) => {
+      const current = read();
+      if (!(name in current.secrets)) return Promise.resolve();
+      const { [name]: _removed, ...rest } = current.secrets;
+      if (Object.keys(rest).length === 0) {
+        // An empty file is worse than none: it still says a key was here.
+        rmSync(file, { force: true });
+        return Promise.resolve();
+      }
+      write({ version: 1, secrets: rest });
+      return Promise.resolve();
+    },
+  };
+}

package/src/ai/host/settings.ts

@@ -0,0 +1,83 @@
+/**
+ * Where the AI layer's non-secret settings live.
+ *
+ * `<dataDir>/ai/settings.json` holds which provider and model the user chose
+ * and where to reach them. It never holds the API key — that is
+ * `secrets.ts` — and a test asserts the string does not appear in the file,
+ * because "we do not write it there" is the kind of promise that quietly
+ * stops being true.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** The settings file's shape. `version` exists so a later format can migrate. */
+export interface StoredSettings {
+  version: 1;
+  provider: string | null;
+  modelId: string | null;
+  baseUrl: string | null;
+  /** False means the key is held in memory only and forgotten on exit. */
+  remember: boolean;
+}
+
+/** Reads and writes {@link StoredSettings}. */
+export interface SettingsStore {
+  read(): StoredSettings;
+  write(next: StoredSettings): void;
+}
+
+/** What a fresh installation has. No provider, so the layer is off. */
+export function defaultSettings(): StoredSettings {
+  return { version: 1, provider: null, modelId: null, baseUrl: null, remember: true };
+}
+
+function coerce(value: unknown): StoredSettings | null {
+  if (typeof value !== 'object' || value === null) return null;
+  const raw = value as Record<string, unknown>;
+  const text = (key: string): string | null => (typeof raw[key] === 'string' ? (raw[key] as string) : null);
+  return {
+    version: 1,
+    provider: text('provider'),
+    modelId: text('modelId'),
+    baseUrl: text('baseUrl'),
+    remember: raw['remember'] !== false,
+  };
+}
+
+/** Open the settings store for one data directory. */
+export function createSettingsStore(dataDir: string): SettingsStore {
+  const directory = join(dataDir, 'ai');
+  const file = join(directory, 'settings.json');
+  const temporary = `${file}.tmp`;
+
+  return {
+    read() {
+      let text: string;
+      try {
+        text = readFileSync(file, 'utf8');
+      } catch {
+        // No file yet is the ordinary case on a first run, not a failure.
+        return defaultSettings();
+      }
+      try {
+        const parsed = coerce(JSON.parse(text) as unknown);
+        if (parsed === null) throw new Error('not an object');
+        return parsed;
+      } catch {
+        // A file the user or another tool mangled should not stop the
+        // application from starting, and should not be deleted either — they
+        // may want to repair it.
+        console.warn(`[broapp] ignoring unreadable AI settings at ${file}`);
+        return defaultSettings();
+      }
+    },
+
+    write(next) {
+      mkdirSync(directory, { recursive: true, mode: 0o700 });
+      // Written to a sibling and renamed, so a crash mid-write leaves the
+      // previous settings intact rather than a truncated file.
+      writeFileSync(temporary, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+      renameSync(temporary, file);
+    },
+  };
+}

package/src/ai/host/tool.ts

@@ -0,0 +1,89 @@
+/**
+ * What the AI layer can offer a model, and how a confirmation is answered.
+ *
+ * Kept apart from `create-ai.ts` so that `from-contract.ts` and `run.ts` can
+ * share these without either importing the other's module graph.
+ */
+import type { JsonSchema } from '../../shared/schema.ts';
+import type { ToolPermission } from '../shared/types.ts';
+
+/** One thing a model may do. */
+export interface AiTool {
+  readonly description: string;
+  /** JSON Schema for the input. Use `schema.toJsonSchema()` or write it by hand. */
+  readonly inputSchema: JsonSchema;
+  /** `read` runs immediately; `confirm` asks the user first. */
+  readonly permission: ToolPermission;
+  execute(input: unknown, signal: AbortSignal): Promise<unknown>;
+}
+
+/** A record the model may be shown, named but not loaded. */
+export interface ContextRef {
+  readonly ref: string;
+  readonly title: string;
+  readonly snippet?: string;
+}
+
+/** A record the model is shown in full. */
+export interface ContextDocument {
+  readonly ref: string;
+  readonly title: string;
+  readonly content: string;
+}
+
+/** Where the model's knowledge of the application's data comes from. */
+export interface AiContextProviders {
+  /** Records relevant to a query. Return refs and short snippets, not full content. */
+  search?(query: { text: string; limit: number }, signal: AbortSignal): Promise<ContextRef[]>;
+  /** Full content for named refs. Unknown refs are skipped, not errors. */
+  resolve?(refs: readonly string[], signal: AbortSignal): Promise<ContextDocument[]>;
+}
+
+/**
+ * The table a waiting tool call and `ai.chatConfirm` meet in.
+ *
+ * One per `Ai`, because a confirmation belongs to a run, and a run belongs to
+ * a stream that may be one of several open at once.
+ */
+export interface Confirmations {
+  wait(runId: string, callId: string, timeoutMs: number, signal: AbortSignal): Promise<boolean>;
+  /** Called by `ai.chatConfirm`. Returns false when nobody is waiting. */
+  answer(runId: string, callId: string, approve: boolean): boolean;
+}
+
+/** Build the confirmation table. */
+export function createConfirmations(): Confirmations {
+  const waiting = new Map<string, (approved: boolean) => void>();
+  const key = (runId: string, callId: string): string => `${runId} ${callId}`;
+
+  return {
+    wait(runId, callId, timeoutMs, signal) {
+      const id = key(runId, callId);
+      return new Promise<boolean>((resolve) => {
+        let settled = false;
+        const finish = (approved: boolean): void => {
+          if (settled) return;
+          settled = true;
+          waiting.delete(id);
+          clearTimeout(timer);
+          signal.removeEventListener('abort', onAbort);
+          resolve(approved);
+        };
+        // A question nobody answers is a denial, not a hung stream: the user
+        // may have closed the tab, and the tool must not run unattended.
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        const onAbort = (): void => finish(false);
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted) finish(false);
+        else waiting.set(id, finish);
+      });
+    },
+
+    answer(runId, callId, approve) {
+      const resolve = waiting.get(key(runId, callId));
+      if (resolve === undefined) return false;
+      resolve(approve);
+      return true;
+    },
+  };
+}

package/src/ai/react/AiChat.tsx

@@ -0,0 +1,194 @@
+/**
+ * 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 { 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'];
+}
+
+function ToolCall({
+  call,
+  onConfirm,
+}: {
+  call: ToolCallState;
+  onConfirm: (callId: string, approve: boolean) => void;
+}): React.ReactElement {
+  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" role="group" aria-label={`Allow ${call.tool}?`}>
+          <span>Allow this?</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,
+}: 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';
+
+  // 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>
+  );
+}