@schlessera/brain-ui-server 0.33.0 → 0.34.0

package/src/app.ts

@@ -170,7 +170,8 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
   assertPasskeyConfig(config.webauthn);
   // A missing (or unrecognized) agent backend refuses to boot HERE, not on the
   // first turn — otherwise /api/health reports healthy while every turn is
-  // guaranteed to fail. Resolution only; the module still loads lazily.
+  // guaranteed to fail. Descriptor loading and profile validation happen here;
+  // backend construction and model discovery remain lazy.
   // Skipped when the embedder injects its own registry.
   if (!options.registry) assertBackendResolvable(config.agent);
 

package/src/bin/brain-ui-cron.ts

@@ -27,7 +27,7 @@ function isRegularFile(path: string): boolean {
   }
 }
 
-export const USAGE = `usage: brain-ui-cron run <job-name> -- <command...>
+export const USAGE = `usage: brain-ui-cron run [--subprocess-env-extra <names>] <job-name> -- <command...>
        brain-ui-cron digest
        brain-ui-cron crontab [--wrapper-command <command>] [--digest-command <command>] [--path-line <line>] [--user <user>]
        brain-ui-cron environment`;
@@ -72,6 +72,24 @@ function crontabOptions(args: string[]): {
   };
 }
 
+function runOptions(args: string[]): {
+  jobName: string;
+  command: string[];
+  subprocessEnvExtraNames: string[];
+} {
+  let remaining = args;
+  let subprocessEnvExtraNames: string[] = [];
+  if (remaining[0] === "--subprocess-env-extra") {
+    const value = remaining[1];
+    if (value === undefined || value === "") usage();
+    subprocessEnvExtraNames = value.split(",");
+    remaining = remaining.slice(2);
+  }
+  const [jobName, separator, ...command] = remaining;
+  if (!jobName || separator !== "--" || command.length === 0) usage();
+  return { jobName, command, subprocessEnvExtraNames };
+}
+
 async function readModuleList(
   brainPath: string,
   env: Record<string, string | undefined>
@@ -104,11 +122,10 @@ async function readModuleList(
 }
 
 const [subcommand, ...args] = process.argv.slice(2);
-const config = resolveCronConfig();
 
 if (subcommand === "run") {
-  const [jobName, separator, ...command] = args;
-  if (!jobName || separator !== "--" || command.length === 0) usage();
+  const { jobName, command, subprocessEnvExtraNames } = runOptions(args);
+  const config = resolveCronConfig(undefined, subprocessEnvExtraNames);
   process.exit(
     await runJob({
       jobName,
@@ -120,16 +137,22 @@ if (subcommand === "run") {
 }
 
 if (subcommand === "digest" && args.length === 0) {
+  const config = resolveCronConfig();
   process.exit(runDigest({ dbPath: config.dbPath }));
 }
 
 if (subcommand === "crontab") {
+  const config = resolveCronConfig();
   const options = crontabOptions(args);
-  const modules = await readModuleList(config.brainPath, config.childEnv);
+  const modules = await readModuleList(
+    config.brainPath,
+    config.moduleDiscoveryEnv
+  );
   process.stdout.write(
     emitCrontab({
       ...options,
       modules,
+      subprocessEnvExtraNames: config.subprocessEnvExtraNames,
       legacyScraperPresent: isRegularFile(
         join(config.brainPath, "scripts", "jobs", "scrape-all.ts")
       ),
@@ -139,8 +162,11 @@ if (subcommand === "crontab") {
 }
 
 if (subcommand === "environment" && args.length === 0) {
+  const config = resolveCronConfig();
   try {
-    process.stdout.write(emitEnvironment(config.childEnv));
+    process.stdout.write(
+      emitEnvironment(config.childEnv, config.subprocessEnvExtraNames)
+    );
     process.exit(0);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

package/src/brain/client.ts

@@ -114,7 +114,7 @@ export function probeBrainCliVersion(brainPath: string, log: Logger): void {
       cwd: brainPath,
       stdout: "pipe",
       stderr: "pipe",
-      env: subprocessEnv({ NO_COLOR: "1" }),
+      env: subprocessEnv("brainCli", { NO_COLOR: "1" }),
       timeout: 5_000,
     });
   } catch (error) {
@@ -166,7 +166,7 @@ export function createBrainClient(opts: { brainPath: string }): BrainClient {
       stdout: "pipe",
       stderr: "pipe",
       // Force JSON output when not a TTY
-      env: subprocessEnv({ NO_COLOR: "1" }),
+      env: subprocessEnv("brainCli", { NO_COLOR: "1" }),
     });
 
     const [stdout, stderr] = await Promise.all([

package/src/config/env.ts

@@ -21,6 +21,8 @@ import { SEVERITIES, type Severity } from "../observability/types.js";
 import { envFlag } from "./env-core.js";
 import {
   filterSubprocessEnv,
+  parseSubprocessEnvExtra,
+  type SubprocessEnvAudience,
   WEB_SEARCH_PROVIDERS,
 } from "@schlessera/brain-ui-sdk/server";
 
@@ -69,6 +71,16 @@ export const ENV_VARS: readonly EnvVarDescriptor[] = [
     default: "/root",
     required: false,
   },
+  {
+    name: "BRAIN_UI_SUBPROCESS_ENV_EXTRA",
+    description:
+      "Comma-separated environment variable names to admit to every child " +
+      "audience when an operator integration needs a variable outside the " +
+      "shipped allowlist. Names are trimmed; malformed entries are ignored; " +
+      "the control variable itself is never forwarded.",
+    default: "(empty)",
+    required: false,
+  },
   {
     name: "PI_CODING_AGENT_DIR",
     description:
@@ -435,12 +447,12 @@ export interface AgentConfig {
   confirmBashPatterns: string[] | null;
   claudeCodePath: string;
   defaultModel: string;
-  /** Raw BRAIN_UI_CLAUDE_PROFILES JSON, parsed lazily by the registry. */
+  /** Raw BRAIN_UI_CLAUDE_PROFILES JSON, parsed at boot and again by the registry. */
   profilesJson: string | null;
   /**
-   * Raw BRAIN_UI_PI_PROFILES JSON, parsed by the registry. When set, the pi
-   * backend runs alongside the Claude backend and these profiles join the
-   * picker.
+   * Raw BRAIN_UI_PI_PROFILES JSON, parsed at boot and again by the registry.
+   * When set, the pi backend runs alongside the Claude backend and these
+   * profiles join the picker.
    */
   piProfilesJson: string | null;
   modelDiscovery: boolean;
@@ -503,8 +515,12 @@ export interface CronConfig {
   brainPath: string;
   /** The deployment database; unlike createApp(), the bin defaults to the container path. */
   dbPath: string;
-  /** Exact inherited environment for the scheduled child, before the span sink is added. */
+  /** Allowlisted brain CLI environment used only to discover module cron entries. */
+  moduleDiscoveryEnv: EnvRecord;
+  /** Allowlisted environment for the scheduled child, before the span sink is added. */
   childEnv: EnvRecord;
+  /** Valid operator-added names, also used when emitting /etc/environment. */
+  subprocessEnvExtraNames: string[];
 }
 
 function list(raw: string | undefined): string[] {
@@ -676,27 +692,63 @@ export function resolveServerConfig(env: EnvRecord = process.env): ServerConfig
 }
 
 /**
- * Resolve the standalone cron bin's environment without applying the server's
- * subprocess secret filter. Scheduled jobs inherit the same environment they
- * did before this behavior moved out of the deployment shell; narrowing that
- * environment belongs to the later least-privilege release.
+ * Resolve the standalone cron bin's paths and allowlisted scheduled-job
+ * environment. The escape hatch is parsed here, at this package's sole env
+ * chokepoint, and its control variable is held back from the child.
  */
-export function resolveCronConfig(env: EnvRecord = process.env): CronConfig {
+export function resolveCronConfig(
+  env: EnvRecord = process.env,
+  admittedNames: readonly string[] = []
+): CronConfig {
+  const subprocessEnvExtraNames = parseSubprocessEnvExtra(
+    [env.BRAIN_UI_SUBPROCESS_ENV_EXTRA, ...admittedNames].join(",")
+  );
   return {
     brainPath: env.BRAIN_PATH || "/data/brain",
     dbPath: env.DB_PATH || "/data/db/brain-ui.db",
-    childEnv: { ...env },
+    moduleDiscoveryEnv: filterPackageSubprocessEnv(
+      env,
+      "brainCli",
+      subprocessEnvExtraNames
+    ),
+    childEnv: filterPackageSubprocessEnv(
+      env,
+      "cron",
+      subprocessEnvExtraNames
+    ),
+    subprocessEnvExtraNames,
+  };
+}
+
+/**
+ * Build a package-owned child environment from an environment value.
+ */
+function filterPackageSubprocessEnv(
+  env: EnvRecord,
+  audience: SubprocessEnvAudience,
+  extraNames: readonly string[] = [],
+  extra: Record<string, string> = {}
+): EnvRecord {
+  const operatorNames = parseSubprocessEnvExtra(
+    env.BRAIN_UI_SUBPROCESS_ENV_EXTRA
+  );
+  return {
+    ...filterSubprocessEnv(env, audience, [...operatorNames, ...extraNames]),
+    ...extra,
   };
 }
 
 /**
- * The filtered parent environment for spawned subprocesses (brain CLI,
- * whatsup), plus explicit overrides. The shared descriptor strips server-only
- * material while retaining all known subprocess capabilities and unknown
- * variables. This reads `process.env`, so it lives behind this chokepoint.
+ * The allowlisted parent environment for a spawned subprocess, plus explicit
+ * overrides. The agent default preserves this exported helper's historical
+ * no-argument use; every ui-server spawn names its actual audience.
  */
-export function subprocessEnv(extra: Record<string, string> = {}): EnvRecord {
-  return { ...filterSubprocessEnv(process.env), ...extra };
+export function subprocessEnv(
+  audience: SubprocessEnvAudience = "agent",
+  extra: Record<string, string> = {},
+  extraNames: readonly string[] = []
+): EnvRecord {
+  return filterPackageSubprocessEnv(process.env, audience, extraNames, extra);
 }
 
 /**

package/src/cron/emit.ts

@@ -1,4 +1,5 @@
 import {
+  parseSubprocessEnvExtra,
   SUBPROCESS_ENV,
   type SubprocessEnvAudience,
 } from "@schlessera/brain-ui-sdk/server";
@@ -46,6 +47,8 @@ export interface EmitCrontabOptions {
   user: string;
   /** Whether `scripts/jobs/scrape-all.ts` exists in the brain repository. */
   legacyScraperPresent: boolean;
+  /** Valid names carried into each wrapper so the run process re-admits them. */
+  subprocessEnvExtraNames?: readonly string[];
 }
 
 const MODULE_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
@@ -92,6 +95,7 @@ export function emitCrontab(options: EmitCrontabOptions): string {
     pathLine,
     user,
     legacyScraperPresent,
+    subprocessEnvExtraNames = [],
   } = options;
 
   assertSingleLine("wrapperCommand", wrapperCommand);
@@ -99,15 +103,23 @@ export function emitCrontab(options: EmitCrontabOptions): string {
   assertSingleLine("pathLine", pathLine);
   assertSingleLine("user", user);
 
+  const validatedExtraNames = parseSubprocessEnvExtra(
+    subprocessEnvExtraNames.join(",")
+  );
+  const wrapper =
+    validatedExtraNames.length === 0
+      ? wrapperCommand
+      : `${wrapperCommand} --subprocess-env-extra ${validatedExtraNames.join(",")}`;
+
   const lines = [
     "# Generated by entrypoint.sh — regenerated on each container start.",
     pathLine,
     "",
     "# Base jobs",
-    `0 2 * * * ${user} cd /data/brain && ${wrapperCommand} sync -- sh -c 'brain sync && brain index' 2>&1 | logger -t brain-sync`,
-    `0 3 * * * ${user} cd /data/brain && ${wrapperCommand} validate -- brain validate 2>&1 | logger -t brain-validate`,
-    `0 7 * * * ${user} cd /data/brain && ${wrapperCommand} maintain -- brain maintain 2>&1 | logger -t brain-maintain`,
-    `30 7 * * * ${user} cd /data/brain && ${wrapperCommand} digest -- ${digestCommand} 2>&1 | logger -t brain-digest`,
+    `0 2 * * * ${user} cd /data/brain && ${wrapper} sync -- sh -c 'brain sync && brain index' 2>&1 | logger -t brain-sync`,
+    `0 3 * * * ${user} cd /data/brain && ${wrapper} validate -- brain validate 2>&1 | logger -t brain-validate`,
+    `0 7 * * * ${user} cd /data/brain && ${wrapper} maintain -- brain maintain 2>&1 | logger -t brain-maintain`,
+    `30 7 * * * ${user} cd /data/brain && ${wrapper} digest -- ${digestCommand} 2>&1 | logger -t brain-digest`,
     "",
     "# Module jobs (from enabled modules' cron manifests, when exposed)",
   ];
@@ -123,7 +135,7 @@ export function emitCrontab(options: EmitCrontabOptions): string {
         if (!validCronEntry(entry)) continue;
         const jobName = `${module.name}-${entry.name}`;
         lines.push(
-          `${entry.schedule} ${user} cd /data/brain && ${wrapperCommand} ${jobName} -- brain ${entry.command} 2>&1 | logger -t brain-${jobName}`
+          `${entry.schedule} ${user} cd /data/brain && ${wrapper} ${jobName} -- brain ${entry.command} 2>&1 | logger -t brain-${jobName}`
         );
       }
     }
@@ -140,7 +152,7 @@ export function emitCrontab(options: EmitCrontabOptions): string {
   // that have not moved their jobs workflow to an enabled module.
   if (!jobsModuleEnabled && legacyScraperPresent) {
     lines.push(
-      `0 4 * * * ${user} cd /data/brain && ${wrapperCommand} jobs -- bun scripts/jobs/scrape-all.ts --api-only 2>&1 | logger -t brain-jobs`
+      `0 4 * * * ${user} cd /data/brain && ${wrapper} jobs -- bun scripts/jobs/scrape-all.ts --api-only 2>&1 | logger -t brain-jobs`
     );
   }
 
@@ -153,8 +165,8 @@ export function emitCrontab(options: EmitCrontabOptions): string {
  * every child spawned by the server. Scheduled jobs take a different path:
  * they historically receive their environment through pam_env without
  * NODE_ENV, and adding it would change which brain-repo env file their Bun
- * commands load. Revisit this explicit subtraction in the 0.33.1
- * subprocess-environment allowlist unit.
+ * commands load. The 0.33.1 allowlist keeps that historical behavior while
+ * widening the explicitly approved capability settings below.
  */
 export const CRON_ENV_EXCLUSIONS: ReadonlySet<string> = new Set(["NODE_ENV"]);
 
@@ -172,10 +184,21 @@ export const CRON_ENV_EXCLUSIONS: ReadonlySet<string> = new Set(["NODE_ENV"]);
 const CRON_ENV_ORDER: readonly string[] = [
   "PATH",
   "BRAIN_PATH",
+  "BRAIN_ROOT",
   "TZ",
+  "XDG_BIN_HOME",
   "DB_PATH",
+  "BRAIN_RERANK_MODE",
+  "SCRAPE_CHROME_URL",
+  "CHROME_CDP_URL",
+  "SCRAPE_CHROME_PATH",
+  "SCRAPE_CHROME_NO_SANDBOX",
+  "SCRAPE_USER_AGENT",
+  "SCRAPE_RESPECT_ROBOTS",
   "GEMINI_API_KEY",
+  "GEMINI_BASE_URL",
   "OPENAI_API_KEY",
+  "OPENAI_BASE_URL",
   "GITHUB_TOKEN",
   "BRAIN_UI_SYNC_GITHUB_TOKEN",
   "CLAUDE_CODE_OAUTH_TOKEN",
@@ -213,9 +236,18 @@ export const CRON_ENV_NAMES = Object.freeze(
 );
 
 /** Emit the pam_env input consumed by scheduled jobs. */
-export function emitEnvironment(env: Record<string, string | undefined>): string {
+export function emitEnvironment(
+  env: Record<string, string | undefined>,
+  extraNames: readonly string[] = []
+): string {
   const lines: string[] = [];
-  for (const name of CRON_ENV_NAMES) {
+  const names = [
+    ...CRON_ENV_NAMES,
+    ...parseSubprocessEnvExtra(extraNames.join(",")).filter(
+      (name) => !CRON_ENV_NAMES.includes(name)
+    ),
+  ];
+  for (const name of names) {
     const value = env[name];
     // Match the shell's `[ -n ]`: both unset and empty values are omitted.
     if (!value) continue;

package/src/middleware/origin.ts

@@ -1,5 +1,25 @@
 import type { Context, MiddlewareHandler } from "hono";
 
+/**
+ * The scheme a browser would put in an `Origin` header for a connection this
+ * proxy describes.
+ *
+ * A browser's Origin is always http/https — never ws/wss, even for a
+ * WebSocket. Reverse proxies do not agree on that: several report the
+ * *connection* scheme in `X-Forwarded-Proto` and send `ws` / `wss` on an
+ * upgrade while sending `https` on ordinary requests. Comparing that verbatim
+ * builds an expected origin of `wss://host`, which no browser can ever match,
+ * so every WebSocket handshake that falls back to the Origin comparison is
+ * refused while HTTP keeps working. Browsers that send `Sec-Fetch-Site` on the
+ * handshake never reach this path, which is what made it look like a
+ * client-specific failure.
+ */
+function webOriginProtocol(forwarded: string): string {
+  if (forwarded === "wss") return "https:";
+  if (forwarded === "ws") return "http:";
+  return `${forwarded}:`;
+}
+
 /**
  * Compare the browser's Origin with the request's externally visible origin.
  *
@@ -20,7 +40,7 @@ function originMatchesRequest(
 
   const forwarded = c.req.header("x-forwarded-proto")?.split(",", 1)[0]?.trim();
   const protocol = forwarded
-    ? `${forwarded.toLowerCase()}:`
+    ? webOriginProtocol(forwarded.toLowerCase())
     : new URL(c.req.url).protocol;
 
   return parsedOrigin.origin === new URL(`${protocol}//${host}`).origin;

package/src/routes/brain.ts

@@ -117,7 +117,7 @@ export function createBrainRoutes(deps: BrainRoutesDeps): Hono {
           cwd: brainPath,
           stdout: "pipe",
           stderr: "pipe",
-          env: subprocessEnv({ NO_COLOR: "1" }),
+          env: subprocessEnv("brainCli", { NO_COLOR: "1" }),
         });
 
         // Start draining stderr NOW, not after the process exits.
@@ -233,7 +233,7 @@ export function createBrainRoutes(deps: BrainRoutesDeps): Hono {
           cwd: brainPath,
           stdout: "pipe",
           stderr: "pipe",
-          env: subprocessEnv({ NO_COLOR: "1" }),
+          env: subprocessEnv("brainCli", { NO_COLOR: "1" }),
         }
       );
 

package/src/routes/pi-auth.ts

@@ -16,7 +16,7 @@
 
 import { Hono } from "hono";
 import type { AgentConfig } from "../config/env.js";
-import { loadBackendModule, parsePiProfiles } from "../agent/backend.js";
+import { loadBackendDescriptor, loadBackendModule } from "../agent/backend.js";
 import { readJsonBody } from "../middleware/body-limit.js";
 import { requireJson } from "../middleware/origin.js";
 
@@ -64,10 +64,15 @@ export function createPiAuthRoutes(deps: PiAuthRoutesDeps): Hono {
    * Vendors the deployment actually configured — the only providers this
    * surface may touch. Empty when pi is not in play at all.
    */
-  function allowedProviders(): string[] {
-    const fromProfiles = parsePiProfiles(agent.piProfilesJson, agent.profilesJson).map(
-      (profile) => profile.vendor
-    );
+  async function allowedProviders(): Promise<string[]> {
+    const descriptor = await loadBackendDescriptor("pi", deps.importer);
+    const parsed = descriptor.profileSchema.parse(agent.piProfilesJson, {
+      occupiedProfiles: [],
+    });
+    if (!parsed.ok) throw new Error(parsed.errors[0]?.message ?? "Invalid pi profiles.");
+    const fromProfiles = parsed.profiles
+      .map((profile) => profile.vendor)
+      .filter((vendor): vendor is string => typeof vendor === "string");
     return [...new Set(fromProfiles)];
   }
 
@@ -101,7 +106,7 @@ export function createPiAuthRoutes(deps: PiAuthRoutesDeps): Hono {
       // Not-configured is a normal state, not an error: the client hides the
       // whole card on an empty list.
       if (!piConfigured()) return c.json({ providers: [] });
-      const providers = allowedProviders();
+      const providers = await allowedProviders();
       if (providers.length === 0) return c.json({ providers: [] });
       const auth = await getAuth();
       return c.json({ providers: await auth.status(providers) });
@@ -116,7 +121,7 @@ export function createPiAuthRoutes(deps: PiAuthRoutesDeps): Hono {
       if (!piConfigured()) {
         return c.json({ error: "The pi backend is not configured." }, 409);
       }
-      if (!providerId || !allowedProviders().includes(providerId)) {
+      if (!providerId || !(await allowedProviders()).includes(providerId)) {
         return c.json({ error: "Unknown provider." }, 400);
       }
       const auth = await getAuth();
@@ -149,7 +154,7 @@ export function createPiAuthRoutes(deps: PiAuthRoutesDeps): Hono {
         providerId?: unknown;
       } | null;
       const providerId = typeof body?.providerId === "string" ? body.providerId : "";
-      if (!providerId || !allowedProviders().includes(providerId)) {
+      if (!providerId || !(await allowedProviders()).includes(providerId)) {
         return c.json({ error: "Unknown provider." }, 400);
       }
       const auth = await getAuth();

package/src/routes/web-search.ts

@@ -44,7 +44,7 @@ import {
 } from "@schlessera/brain-ui-sdk/server";
 import type { AgentConfig } from "../config/env.js";
 import { resolveWebSearchEnv } from "../config/env.js";
-import { loadBackendModule, parsePiProfiles } from "../agent/backend.js";
+import { loadBackendDescriptor, loadBackendModule } from "../agent/backend.js";
 
 /** One toggleable provider, as the Settings UI renders it. */
 export interface WebSearchProviderView {
@@ -142,17 +142,19 @@ export function createWebSearchRoutes(deps: WebSearchRoutesDeps): Hono {
    * createApp refuses to boot on it — but a throw would take the whole
    * settings card down over a label, so it degrades to an empty list.
    */
-  const appliesTo = (): string[] => {
+  const appliesTo = async (): Promise<string[]> => {
     try {
-      return parsePiProfiles(agent.piProfilesJson ?? null, agent.profilesJson ?? null).map(
-        (p) => p.label
-      );
+      const descriptor = await loadBackendDescriptor("pi", deps.importer);
+      const parsed = descriptor.profileSchema.parse(agent.piProfilesJson ?? null, {
+        occupiedProfiles: [],
+      });
+      return parsed.ok ? parsed.profiles.map((profile) => profile.label) : [];
     } catch {
       return [];
     }
   };
 
-  function view(): WebSearchConfigView {
+  async function view(): Promise<WebSearchConfigView> {
     const config = readConfig(configPath());
     const override = readWebSearchOverride(config);
     const order = orderByCost(readWebSearchRouting(config));
@@ -161,7 +163,7 @@ export function createWebSearchRoutes(deps: WebSearchRoutesDeps): Hono {
       configured: true,
       order,
       overriddenBy: override,
-      appliesTo: appliesTo(),
+      appliesTo: await appliesTo(),
       providers: WEB_SEARCH_PROVIDERS.map((p) => ({
         id: p.id,
         label: p.label,
@@ -180,13 +182,13 @@ export function createWebSearchRoutes(deps: WebSearchRoutesDeps): Hono {
   }
 
   return new Hono()
-    .get("/web-search", (c) => {
+    .get("/web-search", async (c) => {
       // Not-configured is a normal state, not an error: the client hides the
       // whole card (same convention as /pi-auth/providers).
       if (!piConfigured()) {
         return c.json({ configured: false, order: [], overriddenBy: null, appliesTo: [], providers: [] });
       }
-      return c.json(view());
+      return c.json(await view());
     })
     .put("/web-search", requireJson(), async (c) => {
       if (!piConfigured()) {
@@ -317,6 +319,6 @@ export function createWebSearchRoutes(deps: WebSearchRoutesDeps): Hono {
         /* config written; cache clearing is an optimization */
       }
 
-      return c.json(view());
+      return c.json(await view());
     });
 }