@schlessera/brain-ui-server 0.4.0

package/src/agent/backend.ts

@@ -0,0 +1,308 @@
+import { createRequire } from "module";
+import {
+  createClaudeBackend,
+  defineProfiles,
+  type InferenceProfile,
+  type InferenceProfileInput,
+} from "@schlessera/brain-backend-claude";
+import type { ProviderInfo } from "@schlessera/brain-ui-sdk";
+import type {
+  AgentBackend,
+  BackendCapabilities,
+} from "@schlessera/brain-ui-sdk/server";
+
+/**
+ * Backend registry for the deployment. Claude is always available.
+ * `AGENT_BACKEND=pi` retains the legacy single-backend deployment mode when the
+ * optional pi package is installed.
+ *
+ * The old five hardcoded personal inference profiles are gone: the Claude
+ * backend ships the single "claude" default, and additional Anthropic-compatible
+ * endpoints are declared via the BRAIN_UI_CLAUDE_PROFILES env var (documented in
+ * .env.example) rather than in code.
+ */
+
+const BRAIN_PATH =
+  process.env.BRAIN_PATH || `${process.env.HOME || "/root"}/brain`;
+
+// The Claude Code native binary is not in node_modules — it is installed via
+// the official curl-bash installer (~/.local/bin/claude, symlinked to
+// /usr/local/bin/claude in the container). The Agent SDK can't always
+// auto-discover it, so hand it the explicit path; override with CLAUDE_CODE_PATH.
+const CLAUDE_CODE_PATH = process.env.CLAUDE_CODE_PATH || "/usr/local/bin/claude";
+
+interface BackendRegistry {
+  backends: AgentBackend[];
+  byId: Map<string, AgentBackend>;
+  defaultBackendId: string;
+  profileOwners: Map<string, string>;
+  profiles: Map<string, ProviderInfo[]>;
+}
+
+let cachedRegistry: Promise<BackendRegistry> | null = null;
+
+async function createRegistry(
+  backends: AgentBackend[],
+  defaultBackendId: string
+): Promise<BackendRegistry> {
+  if (backends.length === 0) {
+    throw new Error("Backend registry requires at least one backend.");
+  }
+
+  const byId = new Map(backends.map((backend) => [backend.id, backend]));
+  const resolvedDefaultId = byId.has(defaultBackendId)
+    ? defaultBackendId
+    : backends[0].id;
+  const ordered = [
+    byId.get(resolvedDefaultId)!,
+    ...backends.filter((backend) => backend.id !== resolvedDefaultId),
+  ];
+  const listedProfiles = await Promise.all(
+    ordered.map(async (backend) => ({
+      backend,
+      profiles: await backend.listProfiles(),
+    }))
+  );
+  const profileOwners = new Map<string, string>();
+  const profiles = new Map<string, ProviderInfo[]>();
+
+  for (const listed of listedProfiles) {
+    profiles.set(listed.backend.id, listed.profiles);
+    for (const profile of listed.profiles) {
+      const owner = profileOwners.get(profile.id);
+      if (owner && owner !== listed.backend.id) {
+        throw new Error(
+          `Profile id collision across backends: "${profile.id}" is exposed by "${owner}" and "${listed.backend.id}".`
+        );
+      }
+      profileOwners.set(profile.id, listed.backend.id);
+    }
+  }
+
+  return {
+    backends: ordered,
+    byId,
+    defaultBackendId: resolvedDefaultId,
+    profileOwners,
+    profiles,
+  };
+}
+
+async function buildRegistry(): Promise<BackendRegistry> {
+  const primary = (process.env.AGENT_BACKEND || "claude")
+    .trim()
+    .toLowerCase();
+
+  if (primary === "pi") {
+    const pi = buildPiBackend();
+    return createRegistry([pi], pi.id);
+  }
+
+  const claude = createClaudeBackend({
+    brainPath: BRAIN_PATH,
+    claudeCodePath: CLAUDE_CODE_PATH,
+    profiles: loadClaudeProfiles(),
+  });
+  const backends = [claude];
+
+  // AGENT_BACKEND must name a configured backend. The in-process options are
+  // "claude" (default) and "pi" (handled above). An unrecognized value is a
+  // misconfiguration — fail loudly instead of silently coercing to claude and
+  // running on the wrong backend with nothing in the logs.
+  if (process.env.AGENT_BACKEND && !backends.some((b) => b.id === primary)) {
+    throw new Error(
+      `AGENT_BACKEND="${primary}" does not match any configured backend ` +
+        `(expected "claude" or "pi").`
+    );
+  }
+  return createRegistry(backends, primary);
+}
+
+async function getRegistry(): Promise<BackendRegistry> {
+  if (!cachedRegistry) cachedRegistry = buildRegistry();
+  return cachedRegistry;
+}
+
+/** All configured backends, with the default backend first. */
+export async function getBackends(): Promise<AgentBackend[]> {
+  return (await getRegistry()).backends;
+}
+
+/** Find a configured backend by its stable id. */
+export async function getBackendById(
+  id: string
+): Promise<AgentBackend | undefined> {
+  return (await getRegistry()).byId.get(id);
+}
+
+/** The default backend used for new and legacy sessions. */
+export async function getDefaultBackend(): Promise<AgentBackend> {
+  const registry = await getRegistry();
+  return registry.byId.get(registry.defaultBackendId)!;
+}
+
+/** The stable id of the default backend. */
+export async function getDefaultBackendId(): Promise<string> {
+  return (await getRegistry()).defaultBackendId;
+}
+
+/** Resolve the backend that owns a globally unique profile id. */
+export async function getBackendForProfile(
+  profileId: string
+): Promise<AgentBackend | undefined> {
+  const registry = await getRegistry();
+  const backendId = registry.profileOwners.get(profileId);
+  return backendId ? registry.byId.get(backendId) : undefined;
+}
+
+/** Resolve a persisted backend id, falling back for legacy/unknown sessions. */
+export async function getBackendForSession(
+  backendId: string | null | undefined
+): Promise<AgentBackend> {
+  if (backendId) {
+    const backend = await getBackendById(backendId);
+    if (backend) return backend;
+  }
+  return getDefaultBackend();
+}
+
+/** List every available profile, tagged with its owning backend id. */
+export async function listAllProviders(): Promise<ProviderInfo[]> {
+  const registry = await getRegistry();
+  return registry.backends.flatMap((backend) =>
+    (registry.profiles.get(backend.id) ?? []).map((profile) => ({
+      ...profile,
+      backendId: backend.id,
+    }))
+  );
+}
+
+/** Per-backend capability metadata exposed by the providers route. */
+export async function getBackendsInfo(): Promise<
+  Record<string, { id: string; capabilities: BackendCapabilities }>
+> {
+  const backends = await getBackends();
+  return Object.fromEntries(
+    backends.map((backend) => [
+      backend.id,
+      { id: backend.id, capabilities: backend.capabilities },
+    ])
+  );
+}
+
+/** @deprecated Use getDefaultBackend() or a routing-specific accessor. */
+export async function getBackend(): Promise<AgentBackend> {
+  return getDefaultBackend();
+}
+
+/** Test seam: drop the cached registry so later access rebuilds from env. */
+export function resetBackendForTests(): void {
+  cachedRegistry = null;
+}
+
+/** Test seam: install one fake backend as the complete registry. */
+export function setBackendForTests(backend: AgentBackend): void {
+  cachedRegistry = createRegistry([backend], backend.id);
+}
+
+/** Test seam: install a complete fake registry with an explicit default. */
+export function setBackendsForTests(
+  backends: AgentBackend[],
+  defaultBackendId = backends[0]?.id ?? ""
+): void {
+  cachedRegistry = createRegistry(backends, defaultBackendId);
+}
+
+// The built-in default profile's model. The Claude backend historically pinned
+// the default to a specific model; after the SDK extraction the pin was lost and
+// resumed default-profile sessions drifted to "whatever the CLI defaults to",
+// silently changing model/behaviour/billing on every CLI bump. Re-pin it here
+// (a committed default, overridable per deploy via BRAIN_UI_CLAUDE_DEFAULT_MODEL)
+// so the default stays on a known model.
+const BUILTIN_DEFAULT_MODEL =
+  process.env.BRAIN_UI_CLAUDE_DEFAULT_MODEL?.trim() || "claude-sonnet-4-6";
+
+function builtinDefaultProfiles(): InferenceProfile[] {
+  return defineProfiles([
+    {
+      id: "claude",
+      label: "Claude",
+      vendor: "anthropic",
+      model: BUILTIN_DEFAULT_MODEL,
+      modelAliases: true,
+    },
+  ]);
+}
+
+/**
+ * The Claude roster: the pinned built-in "claude" default first, plus any extra
+ * profiles from BRAIN_UI_CLAUDE_PROFILES (a JSON array of InferenceProfileInput
+ * {id,label,model?,baseUrl?,authTokenEnv?,apiKeyEnv?,modelAliases?}).
+ *
+ * A malformed or duplicate-id roster THROWS — caught at boot by the registry
+ * fail-fast — rather than silently degrading to default-only and rebilling
+ * every pinned session to the subscription with nothing in the logs.
+ */
+function loadClaudeProfiles(): InferenceProfile[] {
+  const base = builtinDefaultProfiles();
+  const raw = process.env.BRAIN_UI_CLAUDE_PROFILES?.trim();
+  if (!raw) return base;
+
+  let inputs: unknown;
+  try {
+    inputs = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `BRAIN_UI_CLAUDE_PROFILES is not valid JSON: ${
+        err instanceof Error ? err.message : String(err)
+      }`
+    );
+  }
+  if (!Array.isArray(inputs)) {
+    throw new Error("BRAIN_UI_CLAUDE_PROFILES must be a JSON array.");
+  }
+
+  // Reject duplicate ids (including collisions with the built-in "claude"): a
+  // duplicate silently shadows and can resolve to the wrong credentials.
+  const seen = new Set(base.map((profile) => profile.id));
+  for (const input of inputs as InferenceProfileInput[]) {
+    if (!input || typeof input.id !== "string" || input.id.length === 0) {
+      throw new Error(
+        "Each BRAIN_UI_CLAUDE_PROFILES entry needs a non-empty string id."
+      );
+    }
+    if (seen.has(input.id)) {
+      throw new Error(
+        `Duplicate profile id in BRAIN_UI_CLAUDE_PROFILES: "${input.id}".`
+      );
+    }
+    seen.add(input.id);
+  }
+
+  return [...base, ...defineProfiles(inputs as InferenceProfileInput[])];
+}
+
+/**
+ * Optional pi backend. @schlessera/brain-backend-pi is NOT a hard dependency — a
+ * deployment that never opts into it does not need it (or its pi SDK peer deps)
+ * installed. Loaded lazily so the server still boots without it; when requested
+ * but absent, fail with an actionable message.
+ */
+function buildPiBackend(): AgentBackend {
+  const require = createRequire(import.meta.url);
+  let mod: { createPiBackend?: (opts: { brainPath: string }) => AgentBackend };
+  try {
+    mod = require("@schlessera/brain-backend-pi");
+  } catch {
+    throw new Error(
+      'AGENT_BACKEND=pi but "@schlessera/brain-backend-pi" is not installed. ' +
+        "Add it (with its pi SDK dependencies) or set AGENT_BACKEND=claude."
+    );
+  }
+  if (typeof mod.createPiBackend !== "function") {
+    throw new Error(
+      '"@schlessera/brain-backend-pi" does not export createPiBackend.'
+    );
+  }
+  return mod.createPiBackend({ brainPath: BRAIN_PATH });
+}

package/src/app.ts

@@ -0,0 +1,159 @@
+import { Hono } from "hono";
+import type { Context } from "hono";
+import { logger } from "hono/logger";
+import { cors } from "hono/cors";
+import { serveStatic } from "hono/bun";
+import { join } from "path";
+import { healthRoutes, statusRoutes } from "./routes/health.js";
+import { brainRoutes } from "./routes/brain.js";
+import { sessionRoutes } from "./routes/sessions.js";
+import { voiceRoutes } from "./routes/voice.js";
+import { filesRoutes } from "./routes/files.js";
+import { createRenderRoutes, type AppRenderer } from "./routes/render.js";
+import { providerRoutes } from "./routes/providers.js";
+import {
+  resolveAuthMode,
+  assertAuthConfig,
+  authGuard,
+  authRoutes,
+  isWsAuthorized,
+} from "./middleware/auth.js";
+import {
+  passkeyPublicRoutes,
+  passkeyManagementRoutes,
+  passwordLoginDisabled,
+  assertPasskeyConfig,
+} from "./middleware/passkeys.js";
+import { configureDb } from "./db/client.js";
+import { configureWsHost, wsUpgrade, websocket } from "./ws/handler.js";
+
+export type { AppRenderer };
+
+export interface CreateAppOptions {
+  /**
+   * Directory of a built SPA to serve at `/*` with an index.html fallback.
+   * The deployment shell decides whether (and what) to serve — the package
+   * has no client build of its own and no NODE_ENV heuristics.
+   */
+  staticRoot?: string;
+  /** Display name used in connection/status copy. Default "Brain UI". */
+  appName?: string;
+  /** SQLite path override; falls back to DB_PATH, then ./brain-ui.db. */
+  dbPath?: string;
+  /**
+   * PNG/PDF renderer for `POST /api/render`. The deployment owns the actual
+   * renderer instance (e.g. @schlessera/brain-render-puppeteer) — without one
+   * the route answers 501.
+   */
+  renderer?: AppRenderer;
+  /** Per-turn timeout in ms (default 10 minutes). */
+  turnTimeoutMs?: number;
+}
+
+// Cross-site WebSocket hijacking (CSWSH) defense. CORS does not apply to the WS
+// handshake and browsers do not enforce same-origin on `new WebSocket()`, so
+// rejecting a cross-site upgrade is entirely the server's job. A browser always
+// sends `Origin` on a WS handshake; a non-browser client (no Origin) is allowed
+// through here and still gated by isWsAuthorized. When ALLOWED_ORIGINS is set we
+// use it; otherwise we require the Origin's host to match the request host
+// (same-origin). Applied in every auth mode.
+function isAllowedWsOrigin(c: Context, allowedOrigins: string[]): boolean {
+  const origin = c.req.header("origin");
+  if (!origin) return true;
+  if (allowedOrigins.length > 0) return allowedOrigins.includes(origin);
+  try {
+    const host = c.req.header("host");
+    return !!host && new URL(origin).host === host;
+  } catch {
+    return false;
+  }
+}
+
+export function createApp(options: CreateAppOptions = {}) {
+  const app = new Hono();
+  const authMode = resolveAuthMode();
+  // Validate inside the factory, not the bin entry: every consumer of the app
+  // (a deployment bin, tests, another embedder) gets the same refuse-to-boot
+  // guarantee on an unsafe auth configuration.
+  assertAuthConfig(authMode);
+  assertPasskeyConfig();
+
+  if (options.dbPath) configureDb(options.dbPath);
+  configureWsHost({
+    ...(options.appName ? { appName: options.appName } : {}),
+    ...(options.turnTimeoutMs ? { turnTimeoutMs: options.turnTimeoutMs } : {}),
+  });
+
+  // Middleware
+  app.use("*", logger());
+
+  // CORS is only needed for a SPLIT topology where the client is served from a
+  // different origin than the API. ALLOWED_ORIGINS is a comma-separated
+  // allowlist; empty/unset means same-origin (the default), so the CORS
+  // middleware is skipped entirely.
+  const allowedOrigins = (process.env.ALLOWED_ORIGINS ?? "")
+    .split(",")
+    .map((origin) => origin.trim())
+    .filter(Boolean);
+  if (allowedOrigins.length > 0) {
+    app.use(
+      "/api/*",
+      cors({
+        origin: allowedOrigins,
+        allowMethods: ["GET", "POST", "PUT", "DELETE"],
+        allowHeaders: ["Content-Type"],
+        credentials: true,
+      })
+    );
+  }
+
+  // Public routes, registered BEFORE the auth guard: only the minimal liveness
+  // probe and the login/logout routes are reachable without a session.
+  // /api/status is intentionally NOT here — it leaks the git SHA, cron errors,
+  // and a session oracle, so it lives behind the guard below.
+  app.route("/api", healthRoutes);
+  app.route("/api", authRoutes(authMode, { passwordDisabled: passwordLoginDisabled }));
+  app.route("/api", passkeyPublicRoutes(authMode));
+
+  // Auth guard for every other /api/* route. The probe below is intentionally
+  // behind it: an unauthenticated client gets 401 (password/proxy) or 403
+  // (tailscale) from /api/vpn-check and shows the login / VPN screen.
+  app.use("/api/*", authGuard(authMode));
+  app.get("/api/vpn-check", (c) => c.json({ vpn: true }));
+  // Passkey registration/management: after the guard, so a session is required
+  // by mount position (the public assertion routes are registered above).
+  app.route("/api", passkeyManagementRoutes(authMode));
+  app.route("/api", statusRoutes);
+  app.route("/api", brainRoutes);
+  app.route("/api", sessionRoutes);
+  app.route("/api", voiceRoutes);
+  app.route("/api", filesRoutes);
+  app.route("/api", createRenderRoutes(options.renderer));
+  app.route("/api", providerRoutes);
+
+  // WebSocket endpoint. Browsers can't set headers on the WS handshake, so the
+  // upgrade authenticates via the session cookie (or IP/proxy header) INSIDE
+  // the handler — no header-modifying middleware may sit on this route.
+  app.get("/ws", async (c, next) => {
+    if (!isAllowedWsOrigin(c, allowedOrigins)) {
+      return c.json({ error: "Cross-origin WebSocket rejected" }, 403);
+    }
+    if (!(await isWsAuthorized(c, authMode))) {
+      return c.json({ error: "Authentication required" }, 401);
+    }
+    return wsUpgrade(c, next);
+  });
+
+  // Static files: the deployment shell passes its built client explicitly.
+  if (options.staticRoot) {
+    const staticRoot = options.staticRoot;
+    app.use("/*", serveStatic({ root: staticRoot }));
+    // SPA fallback
+    app.get("*", serveStatic({ path: join(staticRoot, "index.html") }));
+  }
+
+  return {
+    fetch: app.fetch,
+    websocket,
+  };
+}

package/src/brain/client.ts

@@ -0,0 +1,186 @@
+import { existsSync } from "fs";
+import { join } from "path";
+import type {
+  BrainSearchResult,
+  BrainSearchResponse,
+  BrainDocument,
+  BrainStats,
+  BrainSyncResult,
+} from "./types.js";
+
+const BRAIN_PATH = process.env.BRAIN_PATH || join(process.env.HOME || "/root", "brain");
+
+/**
+ * argv prefix for invoking the brain CLI inside BRAIN_PATH.
+ *
+ * Two brain-repo layouts exist and both must work: a repo that depends on
+ * `@schlessera/brain` gets a real bin at `node_modules/.bin/brain`, while the
+ * legacy layout vendors `scripts/brain-cli.ts`. Prefer the packaged bin.
+ *
+ * Resolved per call (a bare `existsSync` stat) rather than at import time: in
+ * the container the brain repo is cloned and `bun install`ed by entrypoint.sh,
+ * and a repo can gain the dependency without restarting this server. The same
+ * preference order is mirrored in `scripts/entrypoint.sh`, which links whichever
+ * it finds onto PATH for cron.
+ */
+export function brainCliCommand(): string[] {
+  const packaged = join(BRAIN_PATH, "node_modules", ".bin", "brain");
+  if (existsSync(packaged)) return [packaged];
+  return ["bun", "scripts/brain-cli.ts"];
+}
+
+interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+async function execBrain(args: string[]): Promise<ExecResult> {
+  const proc = Bun.spawn([...brainCliCommand(), ...args], {
+    cwd: BRAIN_PATH,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: {
+      ...process.env,
+      // Force JSON output when not a TTY
+      NO_COLOR: "1",
+    },
+  });
+
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const exitCode = await proc.exited;
+
+  return { stdout, stderr, exitCode };
+}
+
+function parseJsonOutput<T>(result: ExecResult): T {
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `brain CLI failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`
+    );
+  }
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    // Some commands output plain text, not JSON
+    return result.stdout as unknown as T;
+  }
+}
+
+export async function brainSearch(
+  query: string,
+  opts?: { type?: string; tag?: string; limit?: number; mode?: string }
+): Promise<BrainSearchResponse> {
+  const args = ["search", query];
+  if (opts?.type) args.push("--type", opts.type);
+  if (opts?.tag) args.push("--tag", opts.tag);
+  if (opts?.limit) args.push("--limit", String(opts.limit));
+  if (opts?.mode) args.push("--mode", opts.mode);
+
+  const result = await execBrain(args);
+  const parsed = parseJsonOutput<BrainSearchResponse | BrainSearchResult[]>(result);
+  // brain returns {results, warnings} since 22e82e1; tolerate the old bare array
+  return Array.isArray(parsed) ? { results: parsed, warnings: [] } : parsed;
+}
+
+export async function brainBriefing(): Promise<string> {
+  const result = await execBrain(["briefing"]);
+  if (result.exitCode !== 0) {
+    throw new Error(`brain briefing failed: ${result.stderr}`);
+  }
+  return result.stdout;
+}
+
+export async function brainStats(): Promise<BrainStats> {
+  const result = await execBrain(["stats"]);
+  return parseJsonOutput(result);
+}
+
+export async function brainList(opts?: {
+  type?: string;
+  tag?: string;
+  status?: string;
+  relevance?: string;
+  limit?: number;
+}): Promise<BrainDocument[]> {
+  const args = ["list"];
+  if (opts?.type) args.push("--type", opts.type);
+  if (opts?.tag) args.push("--tag", opts.tag);
+  if (opts?.status) args.push("--status", opts.status);
+  if (opts?.relevance) args.push("--relevance", opts.relevance);
+  if (opts?.limit) args.push("--limit", String(opts.limit));
+
+  const result = await execBrain(args);
+  return parseJsonOutput(result);
+}
+
+export async function brainRead(path: string): Promise<string> {
+  const result = await execBrain(["read", path]);
+  if (result.exitCode !== 0) {
+    throw new Error(`brain read failed: ${result.stderr}`);
+  }
+  return result.stdout;
+}
+
+export async function brainSync(): Promise<BrainSyncResult> {
+  // Note: brain sync spawns Claude Code internally via the /sync skill.
+  // For cron jobs, we use a simpler git-based sync instead.
+  const result = await execBrain(["sync"]);
+  if (result.exitCode !== 0) {
+    return {
+      success: false,
+      commits: 0,
+      conflicts: 0,
+      message: result.stderr || result.stdout,
+    };
+  }
+  try {
+    return parseJsonOutput(result);
+  } catch {
+    return {
+      success: true,
+      commits: 0,
+      conflicts: 0,
+      message: result.stdout,
+    };
+  }
+}
+
+export async function brainAdd(
+  content: string,
+  opts?: { type?: string; title?: string; tags?: string[] }
+): Promise<void> {
+  const args = ["add", content];
+  if (opts?.type) args.push("--type", opts.type);
+  if (opts?.title) args.push("--title", opts.title);
+  if (opts?.tags) args.push("--tags", opts.tags.join(","));
+
+  const result = await execBrain(args);
+  if (result.exitCode !== 0) {
+    throw new Error(`brain add failed: ${result.stderr}`);
+  }
+}
+
+export async function brainIndex(opts?: {
+  /** Full rebuild; indexing is incremental by default since brain 22e82e1. */
+  force?: boolean;
+}): Promise<void> {
+  const args = ["index"];
+  if (opts?.force) args.push("--force");
+
+  const result = await execBrain(args);
+  if (result.exitCode !== 0) {
+    throw new Error(`brain index failed: ${result.stderr}`);
+  }
+}
+
+export async function brainValidate(): Promise<string> {
+  const result = await execBrain(["validate"]);
+  if (result.exitCode !== 0) {
+    throw new Error(`brain validate failed: ${result.stderr}`);
+  }
+  return result.stdout;
+}

package/src/brain/types.ts

@@ -0,0 +1,44 @@
+export interface BrainSearchResult {
+  path: string;
+  title: string;
+  type: string;
+  relevance: string;
+  score: number;
+  snippet: string;
+}
+
+export interface BrainSearchResponse {
+  results: BrainSearchResult[];
+  /** Degraded-mode notices from the CLI, e.g. vector search unavailable so results are FTS-only. */
+  warnings: string[];
+}
+
+export interface BrainDocument {
+  path: string;
+  title: string;
+  type: string;
+  status: string;
+  relevance: string;
+  tags: string[];
+  created: string;
+  updated: string;
+  summary?: string;
+}
+
+export interface BrainStats {
+  documents: number;
+  byType: Record<string, number>;
+  byStatus: Record<string, number>;
+  byRelevance: Record<string, number>;
+  tags: number;
+  links: number;
+  brokenLinks: number;
+  chunks: number;
+}
+
+export interface BrainSyncResult {
+  success: boolean;
+  commits: number;
+  conflicts: number;
+  message: string;
+}