@schlessera/brain-ui-server 0.13.1 → 0.14.0

package/dist/config/env.js

@@ -0,0 +1,296 @@
+/**
+ * The package's ONLY `process.env` reader.
+ *
+ * Everything `@schlessera/brain-ui-server` can be configured with is declared
+ * here twice: once as a runtime descriptor ({@link ENV_VARS}, the artifact the
+ * env-parity gate diffs against the documentation) and once as the resolver
+ * ({@link resolveServerConfig}) that turns an environment into a plain,
+ * fully-resolved {@link ServerConfig}.
+ *
+ * `createApp()` resolves the environment ONCE, at the edge; every consumer
+ * inside the package receives the resolved object (or a slice of it) and never
+ * touches `process.env` itself. Tests vary configuration by passing their own
+ * env record to the resolver — no global mutation required.
+ */
+import { join } from "path";
+/**
+ * Every environment variable this package reads. Order groups by concern.
+ * The env-parity gate (G4) asserts this list equals the package's env
+ * documentation in both directions — add here and to the docs together.
+ */
+export const ENV_VARS = [
+    // core paths / identity
+    {
+        name: "BRAIN_PATH",
+        description: "Path to the brain repo the server operates on.",
+        default: "$HOME/brain",
+        required: false,
+    },
+    {
+        name: "HOME",
+        description: "Fallback anchor for the BRAIN_PATH default only.",
+        default: "/root",
+        required: false,
+    },
+    {
+        name: "DB_PATH",
+        description: "SQLite file for the UI's own database (sessions, passkeys, settings).",
+        default: "./brain-ui.db",
+        required: false,
+    },
+    {
+        name: "HOST",
+        description: "Bind host; consulted by the auth validation to decide whether AUTH_MODE=none is loopback-safe.",
+        default: "(empty)",
+        required: false,
+    },
+    {
+        name: "SOURCE_COMMIT",
+        description: "Git SHA reported by /api/status (baked at image build time).",
+        default: "dev",
+        required: false,
+    },
+    {
+        name: "ALLOWED_ORIGINS",
+        description: "Comma-separated cross-origin allowlist for a split client/API topology; empty means same-origin only.",
+        default: "(empty)",
+        required: false,
+    },
+    {
+        name: "MAX_CONCURRENT_SESSIONS",
+        description: "Cap on concurrently RUNNING agent sessions.",
+        default: "3",
+        required: false,
+    },
+    // auth
+    {
+        name: "AUTH_MODE",
+        description: "Authentication mode: password | tailscale | proxy | none. Unset auto-detects (password when a hash is set, else tailscale).",
+        default: "(auto-detect)",
+        required: false,
+    },
+    {
+        name: "BRAIN_UI_PASSWORD_HASH",
+        description: "Bun.password argon2id hash of the shared password.",
+        default: null,
+        required: "AUTH_MODE=password",
+    },
+    {
+        name: "COOKIE_SECRET",
+        description: "Secret signing the session cookie.",
+        default: null,
+        required: "AUTH_MODE=password",
+    },
+    {
+        name: "TRUST_PROXY",
+        description: 'Set "1" to trust x-forwarded-for/x-real-ip and the proxy auth header; only safe behind a trusted reverse proxy.',
+        default: "0",
+        required: "AUTH_MODE=proxy",
+    },
+    {
+        name: "TRUST_PROXY_HOPS",
+        description: "How many trusted proxies front the app (x-forwarded-for parse depth).",
+        default: "1",
+        required: false,
+    },
+    {
+        name: "PROXY_AUTH_HEADER",
+        description: "Header a fronting auth proxy sets for AUTH_MODE=proxy.",
+        default: "x-forwarded-user",
+        required: false,
+    },
+    {
+        name: "BRAIN_UI_DANGEROUSLY_DISABLE_AUTH",
+        description: 'Set "1" to allow AUTH_MODE=none on a non-loopback host. Every network peer gets full agent access.',
+        default: "0",
+        required: false,
+    },
+    {
+        name: "BRAIN_UI_ALLOW_PASSWORD",
+        description: 'Set "1" to keep password login enabled after a passkey exists for the RP (break-glass recovery).',
+        default: "0",
+        required: false,
+    },
+    // WebAuthn / passkeys
+    {
+        name: "WEBAUTHN_RP_NAME",
+        description: "Relying-party display name shown by authenticators.",
+        default: "Brain UI",
+        required: false,
+    },
+    {
+        name: "WEBAUTHN_USER_NAME",
+        description: "WebAuthn user name shown by authenticators.",
+        default: "owner",
+        required: false,
+    },
+    {
+        name: "WEBAUTHN_USER_ID",
+        description: "Stable WebAuthn user handle (wire contract — burned into every resident credential; max 64 bytes; never change it after the first passkey).",
+        default: "brain-ui-owner",
+        required: false,
+    },
+    {
+        name: "WEBAUTHN_RP_ID",
+        description: "Relying-party id override for proxies that rewrite Host.",
+        default: "(derived from the request origin)",
+        required: false,
+    },
+    {
+        name: "WEBAUTHN_ORIGINS",
+        description: "Comma-separated extra origins allowed for WebAuthn ceremonies.",
+        default: "(empty)",
+        required: false,
+    },
+    {
+        name: "BRAIN_UI_ALLOW_LOOPBACK_ORIGIN",
+        description: 'Set "1" to accept loopback Origins for WebAuthn regardless of Host (dev-only, for the vite proxy).',
+        default: "0",
+        required: false,
+    },
+    // agent backend
+    {
+        name: "AGENT_BACKEND",
+        description: 'Primary agent backend: "claude" (default) or "pi".',
+        default: "claude",
+        required: false,
+    },
+    {
+        name: "CLAUDE_CODE_PATH",
+        description: "Path to the Claude Code native binary handed to the Agent SDK.",
+        default: "/usr/local/bin/claude",
+        required: false,
+    },
+    {
+        name: "BRAIN_UI_CLAUDE_DEFAULT_MODEL",
+        description: "Model the built-in default Claude profile is pinned to.",
+        default: "claude-sonnet-4-6",
+        required: false,
+    },
+    {
+        name: "BRAIN_UI_CLAUDE_PROFILES",
+        description: "JSON array of extra Anthropic-compatible inference profiles ({id,label,model?,baseUrl?,authTokenEnv?,apiKeyEnv?,modelAliases?}).",
+        default: "(none)",
+        required: false,
+    },
+    {
+        name: "BRAIN_UI_MODEL_DISCOVERY",
+        description: 'Model discovery against the Anthropic Models API; "0"/"off"/"false" disables. Defaults ON, except under a test runner (NODE_ENV=test) where it defaults OFF.',
+        default: "on (off under NODE_ENV=test)",
+        required: false,
+    },
+    {
+        name: "BRAIN_UI_MODEL_TTL_HOURS",
+        description: "How long a model-discovery result stays fresh, in hours.",
+        default: "24",
+        required: false,
+    },
+    {
+        name: "NODE_ENV",
+        description: "Only consulted for test-runner detection: flips the model-discovery default to off under bun test. Never gates any security behavior.",
+        default: "(unset)",
+        required: false,
+    },
+    // voice
+    {
+        name: "DEEPGRAM_API_KEY",
+        description: "Deepgram API key for streaming ASR (short-lived tokens are minted from it).",
+        default: null,
+        required: "VOICE_PROVIDER=deepgram (or any voice use without VOICE_PROVIDER=webspeech)",
+    },
+    {
+        name: "VOICE_PROVIDER",
+        description: 'Speech provider: "deepgram" or "webspeech" (opt-in only — Chromium streams audio to Google). Unset auto-detects deepgram when its key is present.',
+        default: "(auto-detect)",
+        required: false,
+    },
+    {
+        name: "VOICE_KEYTERM_LIMIT",
+        description: "Maximum custom-vocabulary terms built from the brain database.",
+        default: "500",
+        required: false,
+    },
+    {
+        name: "VOICE_CACHE_DIR",
+        description: "Directory holding the keyterm cache JSON.",
+        default: "$BRAIN_PATH/.brain-ui",
+        required: false,
+    },
+];
+function list(raw) {
+    return (raw ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function flag(raw) {
+    return raw === "1";
+}
+const AUTH_MODES = ["password", "tailscale", "proxy", "none"];
+/**
+ * Resolve an environment into a {@link ServerConfig}. Defaults to the real
+ * process environment; tests pass their own record instead of mutating it.
+ */
+export function resolveServerConfig(env = process.env) {
+    const brainPath = env.BRAIN_PATH || join(env.HOME || "/root", "brain");
+    const rawAuthMode = env.AUTH_MODE?.trim().toLowerCase() || null;
+    const validMode = AUTH_MODES.find((mode) => mode === rawAuthMode) ?? null;
+    const rawDiscovery = env.BRAIN_UI_MODEL_DISCOVERY?.trim().toLowerCase();
+    const modelDiscovery = rawDiscovery
+        ? !(rawDiscovery === "0" || rawDiscovery === "off" || rawDiscovery === "false")
+        : env.NODE_ENV !== "test";
+    const rawTtl = Number(env.BRAIN_UI_MODEL_TTL_HOURS);
+    const ttlHours = Number.isFinite(rawTtl) && rawTtl > 0 ? rawTtl : 24;
+    return {
+        brainPath,
+        dbPath: env.DB_PATH || join(process.cwd(), "brain-ui.db"),
+        host: env.HOST ?? "",
+        sourceCommit: env.SOURCE_COMMIT ?? "dev",
+        allowedOrigins: list(env.ALLOWED_ORIGINS),
+        maxConcurrentSessions: Math.max(1, Number(env.MAX_CONCURRENT_SESSIONS) || 3),
+        auth: {
+            mode: validMode,
+            invalidMode: validMode ? null : rawAuthMode,
+            passwordHash: env.BRAIN_UI_PASSWORD_HASH || null,
+            cookieSecret: env.COOKIE_SECRET || null,
+            trustProxy: flag(env.TRUST_PROXY),
+            trustProxyHops: Math.max(1, Number(env.TRUST_PROXY_HOPS) || 1),
+            proxyAuthHeader: (env.PROXY_AUTH_HEADER || "x-forwarded-user").toLowerCase(),
+            dangerouslyDisableAuth: flag(env.BRAIN_UI_DANGEROUSLY_DISABLE_AUTH),
+            allowPassword: flag(env.BRAIN_UI_ALLOW_PASSWORD),
+        },
+        webauthn: {
+            rpName: env.WEBAUTHN_RP_NAME || "Brain UI",
+            userName: env.WEBAUTHN_USER_NAME || "owner",
+            userId: env.WEBAUTHN_USER_ID || "brain-ui-owner",
+            rpId: env.WEBAUTHN_RP_ID || null,
+            origins: list(env.WEBAUTHN_ORIGINS),
+            allowLoopbackOrigin: flag(env.BRAIN_UI_ALLOW_LOOPBACK_ORIGIN),
+        },
+        agent: {
+            backend: env.AGENT_BACKEND?.trim().toLowerCase() || null,
+            claudeCodePath: env.CLAUDE_CODE_PATH || "/usr/local/bin/claude",
+            defaultModel: env.BRAIN_UI_CLAUDE_DEFAULT_MODEL?.trim() || "claude-sonnet-4-6",
+            profilesJson: env.BRAIN_UI_CLAUDE_PROFILES?.trim() || null,
+            modelDiscovery,
+            modelTtlMs: ttlHours * 60 * 60 * 1000,
+        },
+        voice: {
+            provider: env.VOICE_PROVIDER?.trim().toLowerCase() || null,
+            deepgramApiKey: env.DEEPGRAM_API_KEY || null,
+            keytermLimit: Number(env.VOICE_KEYTERM_LIMIT || 500),
+            cacheDir: env.VOICE_CACHE_DIR || join(brainPath, ".brain-ui"),
+        },
+    };
+}
+/**
+ * The parent environment for spawned subprocesses (brain CLI, whatsup), plus
+ * overrides. Child processes legitimately inherit the whole environment
+ * (PATH, credentials for the tools they run) — that is process plumbing, not
+ * configuration, but it still reads `process.env`, so it lives behind this
+ * chokepoint.
+ */
+export function subprocessEnv(extra = {}) {
+    return { ...process.env, ...extra };
+}
+//# sourceMappingURL=env.js.map

package/dist/config/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"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"}

package/dist/cron/scheduler.d.ts

@@ -1,9 +1,17 @@
-export declare function getCronStatus(): {
-    name: string;
-    lastRunAt: any;
-    lastStatus: any;
-    lastDurationMs: any;
-    lastError: any;
-}[];
-export declare function triggerJob(name: string): Promise<boolean>;
+import type { Database } from "bun:sqlite";
+import type { BrainClient } from "../brain/client.js";
+export interface CronScheduler {
+    getCronStatus(): Array<{
+        name: string;
+        lastRunAt: number | null;
+        lastStatus: string | null;
+        lastDurationMs: number | null;
+        lastError: string | null;
+    }>;
+    triggerJob(name: string): Promise<boolean>;
+}
+export declare function createCronScheduler(deps: {
+    db: Database;
+    brain: BrainClient;
+}): CronScheduler;
 //# sourceMappingURL=scheduler.d.ts.map

package/dist/cron/scheduler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/cron/scheduler.ts"],"names":[],"mappings":"AAsDA,wBAAgB,aAAa;;;;;;IAiB5B;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAM/D"}
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/cron/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAOtD,MAAM,WAAW,aAAa;IAC5B,aAAa,IAAI,KAAK,CAAC;QACrB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;KAC1B,CAAC,CAAC;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5C;AAOD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,EAAE,EAAE,QAAQ,CAAC;IACb,KAAK,EAAE,WAAW,CAAC;CACpB,GAAG,aAAa,CAsEhB"}

package/dist/cron/scheduler.js

@@ -1,58 +1,59 @@
-import { getDb } from "../db/client.js";
-import { brainSync, brainIndex, brainValidate } from "../brain/client.js";
-const jobs = [
-    {
-        name: "sync",
-        handler: async () => {
-            await brainSync();
-            await brainIndex();
+export function createCronScheduler(deps) {
+    const { db, brain } = deps;
+    const jobs = [
+        {
+            name: "sync",
+            handler: async () => {
+                await brain.sync();
+                await brain.index();
+            },
         },
-    },
-    {
-        name: "validate",
-        handler: async () => {
-            await brainValidate();
+        {
+            name: "validate",
+            handler: async () => {
+                await brain.validate();
+            },
         },
-    },
-];
-async function runJob(job) {
-    const db = getDb();
-    const startedAt = Date.now();
-    db.prepare("INSERT INTO cron_runs (job_name, started_at, status) VALUES (?, ?, 'running')").run(job.name, startedAt);
-    try {
-        await job.handler();
-        const durationMs = Date.now() - startedAt;
-        db.prepare("UPDATE cron_runs SET status = 'success', finished_at = ?, duration_ms = ? WHERE job_name = ? AND started_at = ?").run(Date.now(), durationMs, job.name, startedAt);
-        console.log(`[cron] ${job.name} completed in ${durationMs}ms`);
+    ];
+    async function runJob(job) {
+        const startedAt = Date.now();
+        db.prepare("INSERT INTO cron_runs (job_name, started_at, status) VALUES (?, ?, 'running')").run(job.name, startedAt);
+        try {
+            await job.handler();
+            const durationMs = Date.now() - startedAt;
+            db.prepare("UPDATE cron_runs SET status = 'success', finished_at = ?, duration_ms = ? WHERE job_name = ? AND started_at = ?").run(Date.now(), durationMs, job.name, startedAt);
+            console.log(`[cron] ${job.name} completed in ${durationMs}ms`);
+        }
+        catch (err) {
+            const durationMs = Date.now() - startedAt;
+            const message = err instanceof Error ? err.message : String(err);
+            db.prepare("UPDATE cron_runs SET status = 'error', finished_at = ?, duration_ms = ?, error_message = ? WHERE job_name = ? AND started_at = ?").run(Date.now(), durationMs, message, job.name, startedAt);
+            console.error(`[cron] ${job.name} failed: ${message}`);
+        }
     }
-    catch (err) {
-        const durationMs = Date.now() - startedAt;
-        const message = err instanceof Error ? err.message : String(err);
-        db.prepare("UPDATE cron_runs SET status = 'error', finished_at = ?, duration_ms = ?, error_message = ? WHERE job_name = ? AND started_at = ?").run(Date.now(), durationMs, message, job.name, startedAt);
-        console.error(`[cron] ${job.name} failed: ${message}`);
-    }
-}
-export function getCronStatus() {
-    const db = getDb();
-    return jobs.map((job) => {
-        const lastRun = db
-            .query("SELECT * FROM cron_runs WHERE job_name = ? ORDER BY started_at DESC LIMIT 1")
-            .get(job.name);
-        return {
-            name: job.name,
-            lastRunAt: lastRun?.started_at ?? null,
-            lastStatus: lastRun?.status ?? null,
-            lastDurationMs: lastRun?.duration_ms ?? null,
-            lastError: lastRun?.error_message ?? null,
-        };
-    });
-}
-export async function triggerJob(name) {
-    const job = jobs.find((j) => j.name === name);
-    if (!job)
-        return false;
-    // Run async (don't await - let it run in background)
-    runJob(job);
-    return true;
+    return {
+        getCronStatus() {
+            return jobs.map((job) => {
+                const lastRun = db
+                    .query("SELECT * FROM cron_runs WHERE job_name = ? ORDER BY started_at DESC LIMIT 1")
+                    .get(job.name);
+                return {
+                    name: job.name,
+                    lastRunAt: lastRun?.started_at ?? null,
+                    lastStatus: lastRun?.status ?? null,
+                    lastDurationMs: lastRun?.duration_ms ?? null,
+                    lastError: lastRun?.error_message ?? null,
+                };
+            });
+        },
+        async triggerJob(name) {
+            const job = jobs.find((j) => j.name === name);
+            if (!job)
+                return false;
+            // Run async (don't await - let it run in background)
+            runJob(job);
+            return true;
+        },
+    };
 }
 //# sourceMappingURL=scheduler.js.map

package/dist/cron/scheduler.js.map

@@ -1 +1 @@
-{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../../src/cron/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAY1E,MAAM,IAAI,GAAc;IACtB;QACE,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,KAAK,IAAI,EAAE;YAClB,MAAM,SAAS,EAAE,CAAC;YAClB,MAAM,UAAU,EAAE,CAAC;QACrB,CAAC;KACF;IACD;QACE,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,KAAK,IAAI,EAAE;YAClB,MAAM,aAAa,EAAE,CAAC;QACxB,CAAC;KACF;CACF,CAAC;AAEF,KAAK,UAAU,MAAM,CAAC,GAAY;IAChC,MAAM,EAAE,GAAG,KAAK,EAAE,CAAC;IACnB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,EAAE,CAAC,OAAO,CACR,+EAA+E,CAChF,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAE3B,IAAI,CAAC;QACH,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QAC1C,EAAE,CAAC,OAAO,CACR,iHAAiH,CAClH,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACnD,OAAO,CAAC,GAAG,CAAC,UAAU,GAAG,CAAC,IAAI,iBAAiB,UAAU,IAAI,CAAC,CAAC;IACjE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QAC1C,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,EAAE,CAAC,OAAO,CACR,kIAAkI,CACnI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC5D,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,IAAI,YAAY,OAAO,EAAE,CAAC,CAAC;IACzD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,MAAM,EAAE,GAAG,KAAK,EAAE,CAAC;IACnB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACtB,MAAM,OAAO,GAAG,EAAE;aACf,KAAK,CACJ,6EAA6E,CAC9E;aACA,GAAG,CAAC,GAAG,CAAC,IAAI,CAAQ,CAAC;QAExB,OAAO;YACL,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,SAAS,EAAE,OAAO,EAAE,UAAU,IAAI,IAAI;YACtC,UAAU,EAAE,OAAO,EAAE,MAAM,IAAI,IAAI;YACnC,cAAc,EAAE,OAAO,EAAE,WAAW,IAAI,IAAI;YAC5C,SAAS,EAAE,OAAO,EAAE,aAAa,IAAI,IAAI;SAC1C,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY;IAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAC9C,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACvB,qDAAqD;IACrD,MAAM,CAAC,GAAG,CAAC,CAAC;IACZ,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../../src/cron/scheduler.ts"],"names":[],"mappings":"AAwBA,MAAM,UAAU,mBAAmB,CAAC,IAGnC;IACC,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;IAE3B,MAAM,IAAI,GAAc;QACtB;YACE,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE,KAAK,IAAI,EAAE;gBAClB,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;gBACnB,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;YACtB,CAAC;SACF;QACD;YACE,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,KAAK,IAAI,EAAE;gBAClB,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAC;YACzB,CAAC;SACF;KACF,CAAC;IAEF,KAAK,UAAU,MAAM,CAAC,GAAY;QAChC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,EAAE,CAAC,OAAO,CACR,+EAA+E,CAChF,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAE3B,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAC1C,EAAE,CAAC,OAAO,CACR,iHAAiH,CAClH,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YACnD,OAAO,CAAC,GAAG,CAAC,UAAU,GAAG,CAAC,IAAI,iBAAiB,UAAU,IAAI,CAAC,CAAC;QACjE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAC1C,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,EAAE,CAAC,OAAO,CACR,kIAAkI,CACnI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YAC5D,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,IAAI,YAAY,OAAO,EAAE,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;IAED,OAAO;QACL,aAAa;YACX,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;gBACtB,MAAM,OAAO,GAAG,EAAE;qBACf,KAAK,CACJ,6EAA6E,CAC9E;qBACA,GAAG,CAAC,GAAG,CAAC,IAAI,CAAQ,CAAC;gBAExB,OAAO;oBACL,IAAI,EAAE,GAAG,CAAC,IAAI;oBACd,SAAS,EAAE,OAAO,EAAE,UAAU,IAAI,IAAI;oBACtC,UAAU,EAAE,OAAO,EAAE,MAAM,IAAI,IAAI;oBACnC,cAAc,EAAE,OAAO,EAAE,WAAW,IAAI,IAAI;oBAC5C,SAAS,EAAE,OAAO,EAAE,aAAa,IAAI,IAAI;iBAC1C,CAAC;YACJ,CAAC,CAAC,CAAC;QACL,CAAC;QAED,KAAK,CAAC,UAAU,CAAC,IAAY;YAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;YAC9C,IAAI,CAAC,GAAG;gBAAE,OAAO,KAAK,CAAC;YACvB,qDAAqD;YACrD,MAAM,CAAC,GAAG,CAAC,CAAC;YACZ,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/db/brain-db.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The one place ui-server opens the BRAIN database (`$BRAIN_PATH/brain.db`).
+ *
+ * core owns that schema and versions it independently, so every reader on this
+ * side of the package boundary must check `schema_version` before trusting the
+ * shape — a reader without the gate breaks at some later `brain index` with an
+ * error pointing nowhere near the cause. A repo-level lint bans `new Database(`
+ * in ui-server/src outside src/db/, so a new reader cannot skip this wrapper.
+ *
+ * (src/db/client.ts is unrelated: that is the UI's OWN database — sessions,
+ * passkeys, settings — whose schema this package owns and migrates itself.)
+ */
+import { Database } from "bun:sqlite";
+/**
+ * The oldest brain.db schema the SQL in this package is written against:
+ * v3 added `documents.asset_type`, which both the graph reader and the
+ * keyterm extractor select on.
+ */
+export declare const MIN_BRAIN_SCHEMA_VERSION = 3;
+export type BrainDbUnavailableReason = "missing" | "schema";
+/** brain.db cannot be read: absent, or older than the caller's floor. */
+export declare class BrainDbUnavailableError extends Error {
+    readonly reason: BrainDbUnavailableReason;
+    readonly schemaVersion: number;
+    constructor(reason: BrainDbUnavailableReason, schemaVersion: number);
+}
+export interface OpenBrainDbOptions {
+    /**
+     * Refuse (throw {@link BrainDbUnavailableError}) below this schema_version.
+     * Defaults to {@link MIN_BRAIN_SCHEMA_VERSION}. Callers with a newer floor
+     * (the graph tables arrived in v8) still gate per-feature on the returned
+     * `schemaVersion` — degrading, not throwing, where a partial read is useful.
+     */
+    minSchemaVersion?: number;
+}
+export interface BrainDbHandle {
+    db: Database;
+    /** schema_version from index_metadata; 0 when unreadable. */
+    schemaVersion: number;
+}
+/**
+ * Open brain.db read-only and assert its schema_version. Opened per call, not
+ * cached (the keyterm-builder precedent): WAL makes concurrent readers cheap,
+ * and a short-lived handle means a `brain sync` swapping the file underneath
+ * can never leave the server on a stale page cache.
+ */
+export declare function openBrainDb(brainPath: string, options?: OpenBrainDbOptions): BrainDbHandle;
+/** Open, run `fn`, close — the shape every per-request reader wants. */
+export declare function withBrainDb<T>(brainPath: string, options: OpenBrainDbOptions, fn: (db: Database, schemaVersion: number) => T): T;
+//# sourceMappingURL=brain-db.d.ts.map

package/dist/db/brain-db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-db.d.ts","sourceRoot":"","sources":["../../src/db/brain-db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAItC;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE5D,yEAAyE;AACzE,qBAAa,uBAAwB,SAAQ,KAAK;IAE9C,QAAQ,CAAC,MAAM,EAAE,wBAAwB;IACzC,QAAQ,CAAC,aAAa,EAAE,MAAM;gBADrB,MAAM,EAAE,wBAAwB,EAChC,aAAa,EAAE,MAAM;CAKjC;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,QAAQ,CAAC;IACb,6DAA6D;IAC7D,aAAa,EAAE,MAAM,CAAC;CACvB;AAgBD;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,kBAAuB,GAC/B,aAAa,CAaf;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,CAAC,EAC3B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kBAAkB,EAC3B,EAAE,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC,GAC7C,CAAC,CAOH"}

package/dist/db/brain-db.js

@@ -0,0 +1,75 @@
+/**
+ * The one place ui-server opens the BRAIN database (`$BRAIN_PATH/brain.db`).
+ *
+ * core owns that schema and versions it independently, so every reader on this
+ * side of the package boundary must check `schema_version` before trusting the
+ * shape — a reader without the gate breaks at some later `brain index` with an
+ * error pointing nowhere near the cause. A repo-level lint bans `new Database(`
+ * in ui-server/src outside src/db/, so a new reader cannot skip this wrapper.
+ *
+ * (src/db/client.ts is unrelated: that is the UI's OWN database — sessions,
+ * passkeys, settings — whose schema this package owns and migrates itself.)
+ */
+import { Database } from "bun:sqlite";
+import { existsSync } from "fs";
+import { join } from "path";
+/**
+ * The oldest brain.db schema the SQL in this package is written against:
+ * v3 added `documents.asset_type`, which both the graph reader and the
+ * keyterm extractor select on.
+ */
+export const MIN_BRAIN_SCHEMA_VERSION = 3;
+/** brain.db cannot be read: absent, or older than the caller's floor. */
+export class BrainDbUnavailableError extends Error {
+    reason;
+    schemaVersion;
+    constructor(reason, schemaVersion) {
+        super(`brain_db_unavailable: ${reason} (schema_version=${schemaVersion})`);
+        this.reason = reason;
+        this.schemaVersion = schemaVersion;
+        this.name = "BrainDbUnavailableError";
+    }
+}
+function readSchemaVersion(db) {
+    try {
+        const row = db
+            .query("SELECT value FROM index_metadata WHERE key = 'schema_version'")
+            .get();
+        const parsed = Number.parseInt(row?.value ?? "", 10);
+        return Number.isFinite(parsed) ? parsed : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Open brain.db read-only and assert its schema_version. Opened per call, not
+ * cached (the keyterm-builder precedent): WAL makes concurrent readers cheap,
+ * and a short-lived handle means a `brain sync` swapping the file underneath
+ * can never leave the server on a stale page cache.
+ */
+export function openBrainDb(brainPath, options = {}) {
+    const min = options.minSchemaVersion ?? MIN_BRAIN_SCHEMA_VERSION;
+    const dbPath = join(brainPath, "brain.db");
+    if (!existsSync(dbPath)) {
+        throw new BrainDbUnavailableError("missing", 0);
+    }
+    const db = new Database(dbPath, { readonly: true });
+    const schemaVersion = readSchemaVersion(db);
+    if (schemaVersion < min) {
+        db.close();
+        throw new BrainDbUnavailableError("schema", schemaVersion);
+    }
+    return { db, schemaVersion };
+}
+/** Open, run `fn`, close — the shape every per-request reader wants. */
+export function withBrainDb(brainPath, options, fn) {
+    const { db, schemaVersion } = openBrainDb(brainPath, options);
+    try {
+        return fn(db, schemaVersion);
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=brain-db.js.map

package/dist/db/brain-db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-db.js","sourceRoot":"","sources":["../../src/db/brain-db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAI1C,yEAAyE;AACzE,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAErC;IACA;IAFX,YACW,MAAgC,EAChC,aAAqB;QAE9B,KAAK,CAAC,yBAAyB,MAAM,oBAAoB,aAAa,GAAG,CAAC,CAAC;QAHlE,WAAM,GAAN,MAAM,CAA0B;QAChC,kBAAa,GAAb,aAAa,CAAQ;QAG9B,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAkBD,SAAS,iBAAiB,CAAC,EAAY;IACrC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,EAAE;aACX,KAAK,CACJ,+DAA+D,CAChE;aACA,GAAG,EAAE,CAAC;QACT,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,KAAK,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QACrD,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CACzB,SAAiB,EACjB,UAA8B,EAAE;IAEhC,MAAM,GAAG,GAAG,OAAO,CAAC,gBAAgB,IAAI,wBAAwB,CAAC;IACjE,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAC3C,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,uBAAuB,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,aAAa,GAAG,iBAAiB,CAAC,EAAE,CAAC,CAAC;IAC5C,IAAI,aAAa,GAAG,GAAG,EAAE,CAAC;QACxB,EAAE,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,uBAAuB,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,aAAa,EAAE,CAAC;AAC/B,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,WAAW,CACzB,SAAiB,EACjB,OAA2B,EAC3B,EAA8C;IAE9C,MAAM,EAAE,EAAE,EAAE,aAAa,EAAE,GAAG,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,EAAE,EAAE,aAAa,CAAC,CAAC;IAC/B,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/db/client.d.ts

@@ -1,10 +1,12 @@
 import { Database } from "bun:sqlite";
 /**
- * Override the database path before the first `getDb()` call (used by
- * `createApp({ dbPath })`). Configuring after the handle exists would silently
- * split state across two files — refuse instead.
+ * The UI's OWN SQLite database (sessions, passkeys, settings, cron runs) —
+ * distinct from the brain database, which is opened read-only via
+ * src/db/brain-db.ts.
+ *
+ * No module-level handle: `createApp()` opens one per app instance and threads
+ * it to every consumer, so two apps with different configuration can coexist
+ * in one process and a test gets an isolated database by construction.
  */
-export declare function configureDb(dbPath: string): void;
-export declare function getDb(): Database;
-export declare function closeDb(): void;
+export declare function createUiDb(dbPath: string): Database;
 //# sourceMappingURL=client.d.ts.map

package/dist/db/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/db/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAOtC;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAOhD;AAED,wBAAgB,KAAK,IAAI,QAAQ,CAUhC;AAED,wBAAgB,OAAO,SAKtB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/db/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAItC;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAMnD"}