mulmoclaude 0.1.0

package/server/system/config.ts

@@ -0,0 +1,243 @@
+// Workspace-scoped user settings, loaded fresh on every agent
+// invocation so the UI can change things without a server restart.
+//
+// Layout under <workspace>/config/ (post-#284):
+//   settings.json   ← AppSettings (this file)
+//   mcp.json        ← user-defined MCP servers
+//
+// All helpers tolerate missing / malformed files by falling back to
+// defaults. Writers perform an atomic replace (tmp + rename) so a
+// reader never observes a half-written file.
+
+import fs from "fs";
+import path from "path";
+import { log } from "./logger/index.js";
+import { WORKSPACE_PATHS } from "../workspace/paths.js";
+import { writeFileAtomicSync } from "../utils/files/atomic.js";
+import { readTextSafeSync } from "../utils/files/safe.js";
+import { isRecord, isStringArray, isStringRecord } from "../utils/types.js";
+
+export interface AppSettings {
+  // Extra tool names appended to BASE_ALLOWED_TOOLS in
+  // server/agent/config.ts#buildCliArgs. Typical entries are
+  // Claude Code built-in MCP prefixes like
+  //   "mcp__claude_ai_Gmail"
+  //   "mcp__claude_ai_Google_Calendar"
+  extraAllowedTools: string[];
+}
+
+const DEFAULT_SETTINGS: AppSettings = { extraAllowedTools: [] };
+
+export const SETTINGS_FILE_NAME = "settings.json";
+export const MCP_FILE_NAME = "mcp.json";
+
+export function configsDir(): string {
+  return WORKSPACE_PATHS.configs;
+}
+
+export function settingsPath(): string {
+  return path.join(configsDir(), SETTINGS_FILE_NAME);
+}
+
+export function mcpConfigPath(): string {
+  return path.join(configsDir(), MCP_FILE_NAME);
+}
+
+export function ensureConfigsDir(): void {
+  fs.mkdirSync(configsDir(), { recursive: true });
+}
+
+export function isAppSettings(value: unknown): value is AppSettings {
+  if (!isRecord(value)) return false;
+  return isStringArray(value.extraAllowedTools);
+}
+
+export function loadSettings(): AppSettings {
+  const file = settingsPath();
+  const raw = readTextSafeSync(file);
+  if (raw === null) return { ...DEFAULT_SETTINGS };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    log.warn("config", "settings.json is not valid JSON — using defaults", {
+      file,
+      error: String(err),
+    });
+    return { ...DEFAULT_SETTINGS };
+  }
+  if (!isAppSettings(parsed)) {
+    log.warn("config", "settings.json does not match AppSettings schema — using defaults", { file });
+    return { ...DEFAULT_SETTINGS };
+  }
+  // Defensive copy — callers shouldn't be able to mutate the file on
+  // disk via the returned object.
+  return { extraAllowedTools: [...parsed.extraAllowedTools] };
+}
+
+export function saveSettings(settings: AppSettings): void {
+  if (!isAppSettings(settings)) {
+    throw new Error("saveSettings: invalid AppSettings shape");
+  }
+  ensureConfigsDir();
+  const serialised = JSON.stringify({ extraAllowedTools: [...settings.extraAllowedTools] }, null, 2);
+  writeFileAtomicSync(settingsPath(), `${serialised}\n`, { mode: 0o600 });
+}
+
+// ── MCP user-defined servers ────────────────────────────────────
+//
+// Stored under <workspace>/config/mcp.json in the Claude CLI's
+// standard `--mcp-config` shape so the file is portable:
+//   { "mcpServers": { "<id>": <McpServerSpec> } }
+//
+// A server is either HTTP (remote, always Docker-safe) or stdio
+// (local command). See plans/done/feat-web-settings-ui.md for Phase 2a /
+// 2b scope notes.
+
+export interface McpHttpSpec {
+  type: "http";
+  url: string;
+  headers?: Record<string, string>;
+  enabled?: boolean;
+}
+
+export interface McpStdioSpec {
+  type: "stdio";
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  enabled?: boolean;
+}
+
+export type McpServerSpec = McpHttpSpec | McpStdioSpec;
+
+// UI-friendly flat array form. Storage uses the record form; conversion
+// helpers below keep the two in sync.
+export interface McpServerEntry {
+  id: string;
+  spec: McpServerSpec;
+}
+
+export interface McpConfigFile {
+  mcpServers: Record<string, McpServerSpec>;
+}
+
+const DEFAULT_MCP: McpConfigFile = { mcpServers: {} };
+
+// Accepts only allow-listed commands for stdio servers — user input
+// that asks Claude to spawn arbitrary binaries (eg. a shell one-liner)
+// is rejected upstream. Anything that needs more tools should go in
+// the sandbox image (see #162), not here.
+const STDIO_COMMAND_ALLOWLIST = new Set(["npx", "node", "tsx"]);
+
+// Accept only http: / https: URLs. Rejects malformed strings, other
+// protocols (ftp:, file:, javascript:, ...), and empty values so bad
+// endpoints can't be persisted even if a client bypasses the UI.
+function isHttpUrl(value: string): boolean {
+  try {
+    const parsed = new URL(value);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+export function isMcpHttpSpec(value: unknown): value is McpHttpSpec {
+  if (!isRecord(value)) return false;
+
+  if (value.type !== "http") return false;
+  if (typeof value.url !== "string" || !isHttpUrl(value.url)) return false;
+  if (value.headers !== undefined && !isStringRecord(value.headers)) return false;
+  if (value.enabled !== undefined && typeof value.enabled !== "boolean") return false;
+  return true;
+}
+
+export function isMcpStdioSpec(value: unknown): value is McpStdioSpec {
+  if (!isRecord(value)) return false;
+
+  if (value.type !== "stdio") return false;
+  if (typeof value.command !== "string" || value.command.length === 0) return false;
+  if (!STDIO_COMMAND_ALLOWLIST.has(value.command)) return false;
+  if (value.args !== undefined && !isStringArray(value.args)) return false;
+  if (value.env !== undefined && !isStringRecord(value.env)) return false;
+  if (value.enabled !== undefined && typeof value.enabled !== "boolean") return false;
+  return true;
+}
+
+export function isMcpServerSpec(value: unknown): value is McpServerSpec {
+  return isMcpHttpSpec(value) || isMcpStdioSpec(value);
+}
+
+// Workspace id must be slug-shaped so it survives being used as the
+// mcpServers map key and in the `mcp__<id>__<tool>` tool naming.
+const MCP_ID_RE = /^[a-z][a-z0-9_-]{0,63}$/;
+
+export function isMcpServerId(value: unknown): value is string {
+  return typeof value === "string" && MCP_ID_RE.test(value);
+}
+
+export function isMcpConfigFile(value: unknown): value is McpConfigFile {
+  if (!isRecord(value)) return false;
+
+  const servers = value.mcpServers;
+  if (!isRecord(servers)) return false;
+  for (const [id, spec] of Object.entries(servers)) {
+    if (!isMcpServerId(id)) return false;
+    if (!isMcpServerSpec(spec)) return false;
+  }
+  return true;
+}
+
+export function loadMcpConfig(): McpConfigFile {
+  const file = mcpConfigPath();
+  const raw = readTextSafeSync(file);
+  if (raw === null) return { mcpServers: { ...DEFAULT_MCP.mcpServers } };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    log.warn("config", "mcp.json is not valid JSON — using defaults", {
+      file,
+      error: String(err),
+    });
+    return { mcpServers: {} };
+  }
+  if (!isMcpConfigFile(parsed)) {
+    log.warn("config", "mcp.json does not match McpConfigFile schema — using defaults", { file });
+    return { mcpServers: {} };
+  }
+  return parsed;
+}
+
+export function saveMcpConfig(cfg: McpConfigFile): void {
+  if (!isMcpConfigFile(cfg)) {
+    throw new Error("saveMcpConfig: invalid McpConfigFile shape");
+  }
+  ensureConfigsDir();
+  const serialised = JSON.stringify(cfg, null, 2);
+  writeFileAtomicSync(mcpConfigPath(), `${serialised}\n`, { mode: 0o600 });
+}
+
+// Flatten storage form to UI-friendly array.
+export function toMcpEntries(cfg: McpConfigFile): McpServerEntry[] {
+  return Object.entries(cfg.mcpServers).map(([id, spec]) => ({ id, spec }));
+}
+
+// Re-inflate UI-friendly array to storage form. Duplicate ids are
+// rejected so the record shape stays lossless.
+export function fromMcpEntries(entries: McpServerEntry[]): McpConfigFile {
+  const out: Record<string, McpServerSpec> = {};
+  for (const { id, spec } of entries) {
+    if (!isMcpServerId(id)) {
+      throw new Error(`invalid MCP server id: ${JSON.stringify(id)}`);
+    }
+    if (id in out) {
+      throw new Error(`duplicate MCP server id: ${id}`);
+    }
+    if (!isMcpServerSpec(spec)) {
+      throw new Error(`invalid MCP server spec for id ${id}`);
+    }
+    out[id] = spec;
+  }
+  return { mcpServers: out };
+}

package/server/system/credentials.ts

@@ -0,0 +1,220 @@
+import { execFile } from "child_process";
+import { writeFile } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+import { promisify } from "util";
+import { log } from "./logger/index.js";
+import { ONE_SECOND_MS, ONE_MINUTE_MS } from "../utils/time.js";
+
+const execFileAsync = promisify(execFile);
+
+const CREDENTIALS_PATH = join(homedir(), ".claude", ".credentials.json");
+const KEYCHAIN_SERVICE = "Claude Code-credentials";
+
+/** Safety margin — treat tokens as expired 60s before actual expiry. */
+const EXPIRY_MARGIN_MS = ONE_MINUTE_MS;
+/** Maximum time to wait for the claude CLI to respond. */
+const PTY_TIMEOUT_MS = 30 * ONE_SECOND_MS;
+/** Delay before sending input to the claude CLI. */
+const PTY_INPUT_DELAY_MS = 3 * ONE_SECOND_MS;
+
+interface CredentialsJson {
+  claudeAiOauth?: {
+    accessToken?: string;
+    refreshToken?: string;
+    expiresAt?: string;
+  };
+}
+
+/**
+ * Read the raw credentials string from macOS Keychain.
+ */
+async function readFromKeychain(): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync("security", ["find-generic-password", "-s", KEYCHAIN_SERVICE, "-w"]);
+    const credentials = stdout.trim();
+    return credentials || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check whether the access token in the credentials JSON is expired.
+ */
+function isTokenExpired(raw: string): boolean {
+  try {
+    const creds: CredentialsJson = JSON.parse(raw);
+    const expiresAt = creds.claudeAiOauth?.expiresAt;
+    if (!expiresAt) return true; // no expiry info — treat as expired
+
+    const expiresMs = new Date(expiresAt).getTime();
+    if (isNaN(expiresMs)) return true;
+
+    return Date.now() >= expiresMs - EXPIRY_MARGIN_MS;
+  } catch {
+    log.error("credentials", "Failed to parse credentials JSON from Keychain");
+    return true;
+  }
+}
+
+/**
+ * Spawn `claude` interactively via a PTY to force the CLI to refresh its
+ * OAuth token. The CLI handles the refresh internally and writes the new
+ * token back to the macOS Keychain.
+ */
+async function renewTokenViaPty(): Promise<boolean> {
+  // Dynamic import — node-pty is a native module that may not be present
+  // on all platforms. Guard with try/catch.
+  let pty: typeof import("node-pty");
+  try {
+    pty = await import("node-pty");
+  } catch {
+    log.error("credentials", "node-pty not available, cannot renew token");
+    return false;
+  }
+
+  return new Promise((resolve) => {
+    const proc = pty.spawn("claude", [], {
+      name: "xterm-color",
+      cols: 80,
+      rows: 30,
+      cwd: process.cwd(),
+    });
+
+    let responded = false;
+    let buffer = "";
+    let settled = false;
+
+    const finish = (success: boolean) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      proc.kill();
+      resolve(success);
+    };
+
+    const timeout = setTimeout(() => {
+      log.error("credentials", `Token renewal timed out after ${PTY_TIMEOUT_MS / ONE_SECOND_MS}s`);
+      finish(false);
+    }, PTY_TIMEOUT_MS);
+
+    // Match "hi" as a whole token so unrelated output containing those
+    // bytes (e.g. ANSI sequences, words like "This" or "high") can't
+    // false-positive the echo detection.
+    const ECHO_RE = /\bhi\b/;
+
+    // After the echo, only treat output as a successful renewal when
+    // it looks like a real Claude response — a conversational opener
+    // (Hello / Hi / I'm / …) AND a non-trivial amount of text. Error
+    // chunks ("Please log in", "Invalid credentials", network blips)
+    // don't match both conditions, so they fall through to the
+    // 30-second timeout and we treat the renewal as failed. A final
+    // safety net: `refreshCredentials()` re-reads the Keychain and
+    // calls `isTokenExpired()` before writing, so even a false
+    // positive here can't persist a stale token.
+    const RESPONSE_PATTERN_RE = /\b(Hello|Hi|I['’]m|I can|How can)\b/i;
+    const MIN_RESPONSE_CHARS = 20;
+    let echoEndIdx = -1;
+
+    proc.onData((data: string) => {
+      buffer += data;
+
+      if (!responded) {
+        const m = ECHO_RE.exec(buffer);
+        if (m) {
+          // Claude echoed our "hi" — remember where the response
+          // window starts so the success check looks only at bytes
+          // that arrived AFTER the echo.
+          responded = true;
+          echoEndIdx = m.index + m[0].length;
+        }
+        return;
+      }
+
+      const response = buffer.slice(echoEndIdx);
+      if (response.length >= MIN_RESPONSE_CHARS && RESPONSE_PATTERN_RE.test(response)) {
+        finish(true);
+      }
+    });
+
+    // Wait for initial prompt before sending input
+    setTimeout(() => {
+      if (!settled) {
+        proc.write("hi\r");
+      }
+    }, PTY_INPUT_DELAY_MS);
+  });
+}
+
+/**
+ * Extract the current OAuth credentials from the macOS Keychain and write them
+ * to ~/.claude/.credentials.json so that the Docker-based sandbox can read them.
+ *
+ * If the access token is expired, spawns `claude` interactively via a PTY to
+ * force the CLI to refresh its token, then re-reads the fresh credentials.
+ *
+ * Returns true if credentials were successfully refreshed, false otherwise.
+ * Only works on macOS (darwin).
+ */
+export async function refreshCredentials(): Promise<boolean> {
+  if (process.platform !== "darwin") return false;
+
+  try {
+    let credentials = await readFromKeychain();
+    if (!credentials) {
+      log.error("credentials", "No credentials found in macOS Keychain");
+      return false;
+    }
+
+    if (isTokenExpired(credentials)) {
+      // Extract expiry for logging
+      try {
+        const creds: CredentialsJson = JSON.parse(credentials);
+        const expiresAt = creds.claudeAiOauth?.expiresAt ?? "unknown";
+        log.warn("credentials", `Access token expired at ${expiresAt}, launching claude CLI to renew...`);
+      } catch {
+        log.warn("credentials", "Access token expired (could not parse expiry), launching claude CLI to renew...");
+      }
+
+      const renewed = await renewTokenViaPty();
+      if (!renewed) {
+        log.error("credentials", "Token renewal via claude CLI failed");
+        return false;
+      }
+
+      log.info("credentials", "Token renewed successfully via claude CLI");
+
+      // Re-read the now-fresh credentials from Keychain
+      credentials = await readFromKeychain();
+      if (!credentials) {
+        log.error("credentials", "No credentials in Keychain after renewal — unexpected");
+        return false;
+      }
+      // Guard against writing a still-expired token as "fresh": the PTY
+      // echo check is a proxy for "Claude responded", not proof that the
+      // Keychain entry was actually refreshed.
+      if (isTokenExpired(credentials)) {
+        log.error("credentials", "Token still expired after renewal — Keychain was not refreshed");
+        return false;
+      }
+    } else {
+      try {
+        const creds: CredentialsJson = JSON.parse(credentials);
+        const expiresAt = creds.claudeAiOauth?.expiresAt ?? "unknown";
+        log.info("credentials", `Access token is valid, expires at ${expiresAt}`);
+      } catch {
+        log.info("credentials", "Access token appears valid");
+      }
+    }
+
+    await writeFile(CREDENTIALS_PATH, credentials + "\n", { mode: 0o600 });
+    log.info("credentials", "Fresh credentials written to ~/.claude/.credentials.json");
+    return true;
+  } catch (err) {
+    log.error("credentials", "Failed to refresh credentials from Keychain", {
+      error: String(err),
+    });
+    return false;
+  }
+}

package/server/system/docker.ts

@@ -0,0 +1,97 @@
+import { execFile, spawn } from "child_process";
+import { promisify } from "util";
+import { createHash } from "crypto";
+import { readFileSync, statSync } from "fs";
+import { homedir } from "os";
+import { join, resolve as resolvePath } from "path";
+import { log } from "./logger/index.js";
+import { env } from "./env.js";
+import { SUBPROCESS_PROBE_TIMEOUT_MS } from "../utils/time.js";
+
+const execFileAsync = promisify(execFile);
+
+const IMAGE_NAME = "mulmoclaude-sandbox";
+const DOCKERFILE = "Dockerfile.sandbox";
+const LABEL_KEY = "mulmoclaude.dockerfile.sha256";
+
+let _dockerEnabled: boolean | null = null;
+
+function assertClaudeFiles(): void {
+  const claudeDir = join(homedir(), ".claude");
+  const claudeJson = join(homedir(), ".claude.json");
+
+  try {
+    if (!statSync(claudeDir).isDirectory()) {
+      log.error("sandbox", `${claudeDir} exists but is not a directory.`);
+      process.exit(1);
+    }
+  } catch {
+    log.error("sandbox", `${claudeDir} not found. Run 'claude' once to initialize.`);
+    process.exit(1);
+  }
+
+  try {
+    if (!statSync(claudeJson).isFile()) {
+      log.error("sandbox", `${claudeJson} exists but is not a file.`);
+      process.exit(1);
+    }
+  } catch {
+    log.error("sandbox", `${claudeJson} not found. Run 'claude' once to initialize.`);
+    process.exit(1);
+  }
+}
+
+export async function isDockerAvailable(): Promise<boolean> {
+  if (env.disableSandbox) return false;
+  if (_dockerEnabled !== null) return _dockerEnabled;
+  assertClaudeFiles();
+  try {
+    await execFileAsync("docker", ["ps", "-q"], {
+      timeout: SUBPROCESS_PROBE_TIMEOUT_MS,
+    });
+    _dockerEnabled = true;
+  } catch {
+    _dockerEnabled = false;
+  }
+  return _dockerEnabled;
+}
+
+function getDockerfileSha256(): string {
+  const content = readFileSync(resolvePath(process.cwd(), DOCKERFILE));
+  return createHash("sha256").update(content).digest("hex");
+}
+
+async function buildImage(sha: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("docker", ["build", "-t", IMAGE_NAME, "--label", `${LABEL_KEY}=${sha}`, "-f", DOCKERFILE, "--load", "."], {
+      cwd: process.cwd(),
+      stdio: ["ignore", "inherit", "inherit"],
+    });
+    proc.on("error", reject);
+    proc.on("close", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`docker build exited with code ${code}`));
+    });
+  });
+}
+
+export async function ensureSandboxImage(): Promise<void> {
+  const expectedSha = getDockerfileSha256();
+
+  let needsBuild = false;
+  try {
+    const { stdout } = await execFileAsync("docker", ["image", "inspect", IMAGE_NAME, "--format", `{{index .Config.Labels "${LABEL_KEY}"}}`]);
+    if (stdout.trim() !== expectedSha) {
+      log.info("sandbox", "Dockerfile.sandbox changed, rebuilding sandbox image...");
+      needsBuild = true;
+    }
+  } catch {
+    log.info("sandbox", "Building sandbox image (first time only, may take a minute)...");
+    needsBuild = true;
+  }
+
+  if (needsBuild) {
+    await buildImage(expectedSha);
+    log.info("sandbox", "Sandbox image built.");
+  }
+}

package/server/system/env.ts

@@ -0,0 +1,109 @@
+// Single source of truth for environment-variable reads.
+//
+// Before this module existed, `process.env.X` calls were sprinkled
+// across 8 files with each call site doing its own type coercion
+// (`Number(process.env.PORT) || 3001`, `process.env.X === "1"`, …).
+// Renaming an env var, changing a default, or auditing what we read
+// from the environment all required grepping the codebase.
+//
+// All env-var reads should now go through `env.*`. The exception is
+// `server/logger/config.ts` which has its own self-contained env
+// reader (`resolveConfig(env)`) — that subsystem stays independent
+// because it's loaded at extremely early bootstrap and accepts an
+// arbitrary `env`-shaped object for testability.
+//
+// `docs/developer.md` lists every env var and what it does; this
+// module is the runtime side of that table.
+
+// ── Type coercion helpers ───────────────────────────────────────────
+
+function asInt(value: string | undefined, fallback: number, opts: { min?: number; max?: number } = {}): number {
+  if (value === undefined || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isInteger(n)) return fallback;
+  if (opts.min !== undefined && n < opts.min) return fallback;
+  if (opts.max !== undefined && n > opts.max) return fallback;
+  return n;
+}
+
+function asFlag(value: string | undefined): boolean {
+  // Established convention in this project: env flags are "1"
+  // (truthy) vs anything else (falsy). Avoids the trap of
+  // `process.env.FOO === "false"` evaluating truthy as a string.
+  return value === "1";
+}
+
+function asCsv(value: string | undefined): readonly string[] {
+  return Object.freeze(
+    (value ?? "")
+      .split(",")
+      .map((part) => part.trim())
+      .filter(Boolean),
+  );
+}
+
+// ── Snapshot ────────────────────────────────────────────────────────
+
+/**
+ * Frozen snapshot of every env var the app reads, with type coercion
+ * and defaults baked in. Read at module load time so tests can
+ * import a stable view without re-reading process.env on every
+ * access.
+ */
+export const env = Object.freeze({
+  // HTTP server
+  port: asInt(process.env.PORT, 3001, { min: 0, max: 65_535 }),
+  nodeEnv: process.env.NODE_ENV ?? "development",
+  isProduction: process.env.NODE_ENV === "production",
+
+  // Sandbox / Docker
+  disableSandbox: asFlag(process.env.DISABLE_SANDBOX),
+  // Host-credential opt-ins for the Docker sandbox (#259). Both off
+  // by default. See docs/sandbox-credentials.md for the contract.
+  sandboxSshAgentForward: asFlag(process.env.SANDBOX_SSH_AGENT_FORWARD),
+  sandboxSshAllowedHosts: process.env.SANDBOX_SSH_ALLOWED_HOSTS || "github.com",
+  sandboxMountConfigs: asCsv(process.env.SANDBOX_MOUNT_CONFIGS),
+
+  // API credentials (undefined when not configured)
+  geminiApiKey: process.env.GEMINI_API_KEY,
+  xBearerToken: process.env.X_BEARER_TOKEN,
+
+  // Bearer auth token (#272, #316): if set, the server uses this
+  // verbatim instead of generating a fresh random token at startup.
+  // Matches the env var already honoured by `bridges/_lib/token.ts`
+  // and the Vite dev plugin, so pinning on both sides survives a
+  // server restart. Undefined / empty → random-per-startup path.
+  authTokenOverride: process.env.MULMOCLAUDE_AUTH_TOKEN,
+
+  // Sessions index API
+  sessionsListWindowDays: asInt(process.env.SESSIONS_LIST_WINDOW_DAYS, 90, {
+    min: 0,
+  }),
+
+  // Debug-only force-run flags. Off by default; `=1` triggers an
+  // immediate run on startup instead of waiting for the scheduled
+  // interval.
+  journalForceRunOnStartup: asFlag(process.env.JOURNAL_FORCE_RUN_ON_STARTUP),
+  chatIndexForceRunOnStartup: asFlag(process.env.CHAT_INDEX_FORCE_RUN_ON_STARTUP),
+
+  // MulmoBridge Relay (#520). Optional — when both are set the server
+  // connects to the Relay via WebSocket and forwards bridge messages.
+  relayUrl: process.env.RELAY_URL,
+  relayToken: process.env.RELAY_TOKEN,
+
+  // MCP subprocess: set by the parent server when spawning
+  // mcp-server.ts. The MCP process reads them via this same module —
+  // OS-level env vars are shared across both processes.
+  mcpSessionId: process.env.SESSION_ID ?? "",
+  mcpHost: process.env.MCP_HOST ?? "localhost",
+  mcpPluginNames: asCsv(process.env.PLUGIN_NAMES),
+  mcpRoleIds: asCsv(process.env.ROLE_IDS),
+});
+
+// ── Derived helpers ─────────────────────────────────────────────────
+
+/** True iff a Gemini API key is configured. Drives the "image
+ *  generation available" hint in the UI. */
+export function isGeminiAvailable(): boolean {
+  return env.geminiApiKey !== undefined && env.geminiApiKey !== "";
+}