mercury-agent 0.4.5

package/src/cli/whatsapp-auth.ts

@@ -0,0 +1,260 @@
+#!/usr/bin/env bun
+
+/**
+ * WhatsApp Authentication Script
+ *
+ * Run this during setup to authenticate with WhatsApp.
+ * Displays QR code, waits for scan, saves credentials, then exits.
+ *
+ * Usage:
+ *   mercury auth whatsapp                             # QR code mode
+ *   mercury auth whatsapp --pairing-code --phone 14155551234  # Pairing code mode
+ */
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import makeWASocket, {
+  Browsers,
+  DisconnectReason,
+  fetchLatestWaWebVersion,
+  makeCacheableSignalKeyStore,
+  useMultiFileAuthState,
+} from "@whiskeysockets/baileys";
+import qrcode from "qrcode-terminal";
+import { loadConfig, resolveProjectPath } from "../config.js";
+
+export interface WhatsAppAuthOptions {
+  authDir: string;
+  statusDir: string;
+  usePairingCode?: boolean;
+  phoneNumber?: string;
+}
+
+const STATUS_FILE_NAME = "whatsapp-status.txt";
+const QR_FILE_NAME = "whatsapp-qr.txt";
+
+// Silent logger for Baileys
+const silentLogger = {
+  level: "silent",
+  child: () => silentLogger,
+  trace: () => undefined,
+  debug: () => undefined,
+  info: () => undefined,
+  warn: () => undefined,
+  error: () => undefined,
+  fatal: () => undefined,
+};
+
+function askQuestion(prompt: string): Promise<string> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function writeStatus(statusDir: string, status: string): void {
+  const statusPath = path.join(statusDir, STATUS_FILE_NAME);
+  fs.writeFileSync(statusPath, status);
+}
+
+function writeQrData(statusDir: string, qr: string): void {
+  const qrPath = path.join(statusDir, QR_FILE_NAME);
+  fs.writeFileSync(qrPath, qr);
+}
+
+function clearQrData(statusDir: string): void {
+  const qrPath = path.join(statusDir, QR_FILE_NAME);
+  try {
+    fs.unlinkSync(qrPath);
+  } catch {
+    // Ignore if file doesn't exist
+  }
+}
+
+async function connectSocket(
+  options: WhatsAppAuthOptions,
+  isReconnect = false,
+): Promise<void> {
+  const { authDir, statusDir, usePairingCode, phoneNumber } = options;
+
+  const { state, saveCreds } = await useMultiFileAuthState(authDir);
+
+  if (state.creds.registered && !isReconnect) {
+    writeStatus(statusDir, "already_authenticated");
+    console.log("✓ Already authenticated with WhatsApp");
+    console.log(`  To re-authenticate, delete ${authDir} and run again.`);
+    process.exit(0);
+  }
+
+  const { version } = await fetchLatestWaWebVersion({}).catch(() => {
+    console.warn("Failed to fetch latest WA Web version, using default");
+    return { version: undefined };
+  });
+
+  const sock = makeWASocket({
+    version,
+    auth: {
+      creds: state.creds,
+      keys: makeCacheableSignalKeyStore(state.keys, silentLogger),
+    },
+    printQRInTerminal: false,
+    logger: silentLogger,
+    browser: Browsers.macOS("Chrome"),
+  });
+
+  if (usePairingCode && phoneNumber && !state.creds.me) {
+    // Request pairing code after a short delay for connection to initialize
+    // Only on first connect (not reconnect after 515)
+    setTimeout(async () => {
+      try {
+        const code = await sock.requestPairingCode(phoneNumber);
+        console.log(`\n🔗 Your pairing code: ${code}\n`);
+        console.log("  1. Open WhatsApp on your phone");
+        console.log("  2. Tap Settings → Linked Devices → Link a Device");
+        console.log('  3. Tap "Link with phone number instead"');
+        console.log(`  4. Enter this code: ${code}\n`);
+        writeStatus(statusDir, `pairing_code:${code}`);
+      } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error("Failed to request pairing code:", message);
+        writeStatus(statusDir, `failed:pairing_code_error`);
+        process.exit(1);
+      }
+    }, 3000);
+  }
+
+  sock.ev.on("connection.update", (update) => {
+    const { connection, lastDisconnect, qr } = update;
+
+    if (qr) {
+      // Write raw QR data to file so external tools can render it
+      writeQrData(statusDir, qr);
+      writeStatus(statusDir, "waiting_qr");
+      console.log("Scan this QR code with WhatsApp:\n");
+      console.log("  1. Open WhatsApp on your phone");
+      console.log("  2. Tap Settings → Linked Devices → Link a Device");
+      console.log("  3. Point your camera at the QR code below\n");
+      qrcode.generate(qr, { small: true });
+    }
+
+    if (connection === "close") {
+      const reason = (
+        lastDisconnect?.error as { output?: { statusCode?: number } }
+      )?.output?.statusCode;
+
+      if (reason === DisconnectReason.loggedOut) {
+        writeStatus(statusDir, "failed:logged_out");
+        clearQrData(statusDir);
+        console.log("\n✗ Logged out. Delete auth folder and try again.");
+        process.exit(1);
+      } else if (reason === DisconnectReason.timedOut) {
+        writeStatus(statusDir, "failed:qr_timeout");
+        clearQrData(statusDir);
+        console.log("\n✗ QR code timed out. Please try again.");
+        process.exit(1);
+      } else if (reason === 515) {
+        // 515 = stream error, often happens after pairing succeeds but before
+        // registration completes. Reconnect to finish the handshake.
+        console.log("\n⟳ Stream error (515) after pairing — reconnecting...");
+        connectSocket(options, true);
+      } else {
+        writeStatus(statusDir, `failed:${reason || "unknown"}`);
+        clearQrData(statusDir);
+        console.log("\n✗ Connection failed. Please try again.");
+        process.exit(1);
+      }
+    }
+
+    if (connection === "open") {
+      writeStatus(statusDir, "authenticated");
+      clearQrData(statusDir);
+      console.log("\n✓ Successfully authenticated with WhatsApp!");
+      const myJid = sock.user?.id;
+      if (myJid) {
+        console.log(`\n  Your WhatsApp ID: whatsapp:${myJid}`);
+        console.log(
+          "  Add to MERCURY_ADMINS in .env to make yourself admin.\n",
+        );
+      }
+      console.log(`  Credentials saved to ${authDir}/`);
+      console.log(
+        "  You can now start mercury with 'mercury service install'.\n",
+      );
+
+      // Give it a moment to save credentials, then exit
+      setTimeout(() => process.exit(0), 1000);
+    }
+  });
+
+  sock.ev.on("creds.update", saveCreds);
+}
+
+export async function authenticate(
+  options: WhatsAppAuthOptions,
+): Promise<void> {
+  const { authDir, statusDir, usePairingCode } = options;
+  let { phoneNumber } = options;
+
+  // Ensure directories exist
+  fs.mkdirSync(authDir, { recursive: true });
+  fs.mkdirSync(statusDir, { recursive: true });
+
+  // Clean up any stale QR/status files from previous runs
+  clearQrData(statusDir);
+  try {
+    fs.unlinkSync(path.join(statusDir, STATUS_FILE_NAME));
+  } catch {
+    // Ignore
+  }
+
+  if (usePairingCode && !phoneNumber) {
+    phoneNumber = await askQuestion(
+      "Enter your phone number (with country code, no + or spaces, e.g. 14155551234): ",
+    );
+  }
+
+  console.log("Starting WhatsApp authentication...\n");
+
+  await connectSocket({ ...options, phoneNumber });
+}
+
+// CLI entry point when run directly
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  const usePairingCode = args.includes("--pairing-code");
+  const phoneIndex = args.findIndex((_, i, arr) => arr[i - 1] === "--phone");
+  const phoneNumber = phoneIndex >= 0 ? args[phoneIndex] : undefined;
+  const authDirIndex = args.findIndex(
+    (_, i, arr) => arr[i - 1] === "--auth-dir",
+  );
+  const statusDirIndex = args.findIndex(
+    (_, i, arr) => arr[i - 1] === "--status-dir",
+  );
+
+  const cfg = loadConfig();
+  const authDir =
+    authDirIndex >= 0
+      ? args[authDirIndex]
+      : resolveProjectPath(cfg.whatsappAuthDir);
+  const statusDir =
+    statusDirIndex >= 0
+      ? args[statusDirIndex]
+      : resolveProjectPath(cfg.dataDir);
+
+  authenticate({
+    authDir,
+    statusDir,
+    usePairingCode,
+    phoneNumber,
+  }).catch((err: unknown) => {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error("Authentication failed:", message);
+    process.exit(1);
+  });
+}

package/src/config-file.ts

@@ -0,0 +1,397 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+import {
+  MAX_MODEL_CHAIN_LEGS,
+  parseModelLegsArray,
+} from "./config-model-chain.js";
+
+/** Env-only: never loaded from mercury.yaml (secrets). */
+const SECRET_SCHEMA_KEYS = new Set([
+  "apiSecret",
+  "chatApiKey",
+  "consoleUrl",
+  "consoleInternalSecret",
+  "discordGatewaySecret",
+  "azureSpeechKey",
+]);
+
+const modelLegYamlSchema = z.object({
+  provider: z.string().min(1),
+  model: z.string().min(1),
+});
+
+const mercuryFileSchema = z
+  .object({
+    server: z
+      .object({
+        port: z.number().int().min(1).max(65535).optional(),
+        bot_username: z.string().optional(),
+      })
+      .strict()
+      .optional(),
+
+    model: z
+      .object({
+        chain: z.array(modelLegYamlSchema).max(MAX_MODEL_CHAIN_LEGS).optional(),
+        provider: z.string().optional(),
+        model: z.string().optional(),
+        fallback_provider: z.string().optional(),
+        fallback: z.string().optional(),
+        max_retries_per_leg: z.number().int().min(0).max(5).optional(),
+        chain_budget_ms: z
+          .number()
+          .int()
+          .min(5000)
+          .max(55 * 60 * 1000)
+          .optional(),
+        capabilities: z.record(z.string(), z.unknown()).optional(),
+      })
+      .strict()
+      .optional(),
+
+    /** Top-level alias for `model.chain` */
+    model_chain: z
+      .array(modelLegYamlSchema)
+      .max(MAX_MODEL_CHAIN_LEGS)
+      .optional(),
+
+    ingress: z
+      .object({
+        discord: z.boolean().optional(),
+        slack: z.boolean().optional(),
+        teams: z.boolean().optional(),
+        whatsapp: z.boolean().optional(),
+        telegram: z.boolean().optional(),
+      })
+      .strict()
+      .optional(),
+
+    runtime: z
+      .object({
+        data_dir: z.string().optional(),
+        auth_path: z.string().optional(),
+        whatsapp_auth_dir: z.string().optional(),
+        max_concurrency: z.number().int().min(1).max(32).optional(),
+        log_level: z
+          .enum(["debug", "info", "warn", "error", "silent"])
+          .optional(),
+        log_format: z.enum(["text", "json"]).optional(),
+        rate_limit_per_user: z.number().int().min(1).max(1000).optional(),
+        rate_limit_window_ms: z
+          .number()
+          .int()
+          .min(1000)
+          .max(60 * 60 * 1000)
+          .optional(),
+      })
+      .strict()
+      .optional(),
+
+    scheduling: z
+      .object({
+        default_timezone: z.string().optional(),
+      })
+      .strict()
+      .optional(),
+
+    trigger: z
+      .object({
+        patterns: z.string().optional(),
+        match: z.string().optional(),
+      })
+      .strict()
+      .optional(),
+
+    context: z
+      .object({
+        mode: z.enum(["clear", "context"]).optional(),
+        window_size: z.number().int().min(1).max(50).optional(),
+        reply_chain_depth: z.number().int().min(1).max(50).optional(),
+      })
+      .strict()
+      .optional(),
+
+    agent: z
+      .object({
+        image: z.string().optional(),
+        container_timeout_ms: z
+          .number()
+          .int()
+          .min(10_000)
+          .max(60 * 60 * 1000)
+          .optional(),
+        container_bwrap_docker_compat: z.boolean().optional(),
+        override_pi_system_prompt: z.boolean().optional(),
+      })
+      .strict()
+      .optional(),
+
+    discord: z
+      .object({
+        gateway_duration_ms: z
+          .number()
+          .int()
+          .min(60_000)
+          .max(60 * 60 * 1000)
+          .optional(),
+      })
+      .strict()
+      .optional(),
+
+    telegram: z
+      .object({
+        format_enabled: z.boolean().optional(),
+      })
+      .strict()
+      .optional(),
+
+    media: z
+      .object({
+        enabled: z.boolean().optional(),
+        max_size_mb: z.number().min(1).max(100).optional(),
+      })
+      .strict()
+      .optional(),
+
+    permissions: z
+      .object({
+        admins: z.string().optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+type MercuryFile = z.infer<typeof mercuryFileSchema>;
+
+export type RawMercuryConfigInput = Record<string, unknown>;
+
+function resolveConfigPath(cwd: string): string | null {
+  const explicit = process.env.MERCURY_CONFIG_FILE;
+  if (explicit !== undefined) {
+    const t = explicit.trim();
+    if (t === "" || t.toLowerCase() === "none") return null;
+    return path.isAbsolute(t) ? t : path.join(cwd, t);
+  }
+  const yml = path.join(cwd, "mercury.yaml");
+  if (existsSync(yml)) return yml;
+  const yml2 = path.join(cwd, "mercury.yml");
+  if (existsSync(yml2)) return yml2;
+  return null;
+}
+
+function flattenMercuryFile(f: MercuryFile): RawMercuryConfigInput {
+  const o: RawMercuryConfigInput = {};
+
+  if (f.server?.port != null) o.port = f.server.port;
+  if (f.server?.bot_username != null) o.botUsername = f.server.bot_username;
+
+  const chainFromModel = f.model?.chain;
+  const chainTop = f.model_chain;
+  const chainRaw = chainFromModel ?? chainTop;
+  if (chainRaw != null && chainRaw.length > 0) {
+    const legs = parseModelLegsArray(chainRaw, "mercury.yaml model chain");
+    o.modelChain = JSON.stringify(legs);
+  }
+  if (f.model?.provider != null) o.modelProvider = f.model.provider;
+  if (f.model?.model != null) o.model = f.model.model;
+  if (f.model?.fallback_provider != null) {
+    o.modelFallbackProvider = f.model.fallback_provider;
+  }
+  if (f.model?.fallback != null) o.modelFallback = f.model.fallback;
+  if (f.model?.max_retries_per_leg != null) {
+    o.modelMaxRetriesPerLeg = f.model.max_retries_per_leg;
+  }
+  if (f.model?.chain_budget_ms != null) {
+    o.modelChainBudgetMs = f.model.chain_budget_ms;
+  }
+  if (f.model?.capabilities != null) {
+    o.modelCapabilitiesEnv = JSON.stringify(f.model.capabilities);
+  }
+
+  if (f.ingress?.discord != null) o.enableDiscord = f.ingress.discord;
+  if (f.ingress?.slack != null) o.enableSlack = f.ingress.slack;
+  if (f.ingress?.teams != null) o.enableTeams = f.ingress.teams;
+  if (f.ingress?.whatsapp != null) o.enableWhatsApp = f.ingress.whatsapp;
+  if (f.ingress?.telegram != null) o.enableTelegram = f.ingress.telegram;
+
+  if (f.runtime?.data_dir != null) o.dataDir = f.runtime.data_dir;
+  if (f.runtime?.auth_path != null) o.authPath = f.runtime.auth_path;
+  if (f.runtime?.whatsapp_auth_dir != null) {
+    o.whatsappAuthDir = f.runtime.whatsapp_auth_dir;
+  }
+  if (f.runtime?.max_concurrency != null) {
+    o.maxConcurrency = f.runtime.max_concurrency;
+  }
+  if (f.runtime?.log_level != null) o.logLevel = f.runtime.log_level;
+  if (f.runtime?.log_format != null) o.logFormat = f.runtime.log_format;
+  if (f.runtime?.rate_limit_per_user != null) {
+    o.rateLimitPerUser = f.runtime.rate_limit_per_user;
+  }
+  if (f.runtime?.rate_limit_window_ms != null) {
+    o.rateLimitWindowMs = f.runtime.rate_limit_window_ms;
+  }
+
+  if (f.scheduling?.default_timezone != null) {
+    o.defaultTimezone = f.scheduling.default_timezone;
+  }
+
+  if (f.trigger?.patterns != null) o.triggerPatterns = f.trigger.patterns;
+  if (f.trigger?.match != null) o.triggerMatch = f.trigger.match;
+
+  if (f.context?.mode != null) o.contextMode = f.context.mode;
+  if (f.context?.window_size != null) {
+    o.contextWindowSize = f.context.window_size;
+  }
+  if (f.context?.reply_chain_depth != null) {
+    o.contextReplyChainDepth = f.context.reply_chain_depth;
+  }
+
+  if (f.agent?.image != null) o.agentContainerImage = f.agent.image;
+  if (f.agent?.container_timeout_ms != null) {
+    o.containerTimeoutMs = f.agent.container_timeout_ms;
+  }
+  if (f.agent?.container_bwrap_docker_compat != null) {
+    o.containerBwrapDockerCompat = f.agent.container_bwrap_docker_compat;
+  }
+  if (f.agent?.override_pi_system_prompt != null) {
+    o.overridePiSystemPrompt = f.agent.override_pi_system_prompt;
+  }
+
+  if (f.discord?.gateway_duration_ms != null) {
+    o.discordGatewayDurationMs = f.discord.gateway_duration_ms;
+  }
+
+  if (f.telegram?.format_enabled != null) {
+    o.telegramFormatEnabled = f.telegram.format_enabled;
+  }
+
+  if (f.media?.enabled != null) o.mediaEnabled = f.media.enabled;
+  if (f.media?.max_size_mb != null) o.mediaMaxSizeMb = f.media.max_size_mb;
+
+  if (f.permissions?.admins != null) o.admins = f.permissions.admins;
+
+  return o;
+}
+
+/** camelCase schema key → MERCURY_* env name */
+const CAMEL_TO_ENV: Record<string, string> = {
+  logLevel: "MERCURY_LOG_LEVEL",
+  logFormat: "MERCURY_LOG_FORMAT",
+  modelProvider: "MERCURY_MODEL_PROVIDER",
+  model: "MERCURY_MODEL",
+  modelFallbackProvider: "MERCURY_MODEL_FALLBACK_PROVIDER",
+  modelFallback: "MERCURY_MODEL_FALLBACK",
+  modelChain: "MERCURY_MODEL_CHAIN",
+  modelMaxRetriesPerLeg: "MERCURY_MODEL_MAX_RETRIES_PER_LEG",
+  modelChainBudgetMs: "MERCURY_MODEL_CHAIN_BUDGET_MS",
+  modelCapabilitiesEnv: "MERCURY_MODEL_CAPABILITIES",
+  triggerPatterns: "MERCURY_TRIGGER_PATTERNS",
+  triggerMatch: "MERCURY_TRIGGER_MATCH",
+  contextMode: "MERCURY_CONTEXT_MODE",
+  contextWindowSize: "MERCURY_CONTEXT_WINDOW_SIZE",
+  contextReplyChainDepth: "MERCURY_CONTEXT_REPLY_CHAIN_DEPTH",
+  dataDir: "MERCURY_DATA_DIR",
+  maxDiskMb: "MERCURY_MAX_DISK_MB",
+  inboxTtlDays: "MERCURY_INBOX_TTL_DAYS",
+  outboxTtlDays: "MERCURY_OUTBOX_TTL_DAYS",
+  cleanupIntervalMs: "MERCURY_CLEANUP_INTERVAL_MS",
+  authPath: "MERCURY_AUTH_PATH",
+  whatsappAuthDir: "MERCURY_WHATSAPP_AUTH_DIR",
+  agentContainerImage: "MERCURY_AGENT_IMAGE",
+  containerTimeoutMs: "MERCURY_CONTAINER_TIMEOUT_MS",
+  containerRuntime: "MERCURY_CONTAINER_RUNTIME",
+  containerNetwork: "MERCURY_CONTAINER_NETWORK",
+  containerApiHost: "MERCURY_CONTAINER_API_HOST",
+  containerBwrapDockerCompat: "MERCURY_CONTAINER_BWRAP_DOCKER_COMPAT",
+  overridePiSystemPrompt: "MERCURY_OVERRIDE_PI_SYSTEM_PROMPT",
+  maxConcurrency: "MERCURY_MAX_CONCURRENCY",
+  rateLimitPerUser: "MERCURY_RATE_LIMIT_PER_USER",
+  rateLimitWindowMs: "MERCURY_RATE_LIMIT_WINDOW_MS",
+  port: "MERCURY_PORT",
+  botUsername: "MERCURY_BOT_USERNAME",
+  enableDiscord: "MERCURY_ENABLE_DISCORD",
+  discordGatewayDurationMs: "MERCURY_DISCORD_GATEWAY_DURATION_MS",
+  discordGatewaySecret: "MERCURY_DISCORD_GATEWAY_SECRET",
+  enableSlack: "MERCURY_ENABLE_SLACK",
+  enableTeams: "MERCURY_ENABLE_TEAMS",
+  enableWhatsApp: "MERCURY_ENABLE_WHATSAPP",
+  enableTelegram: "MERCURY_ENABLE_TELEGRAM",
+  telegramFormatEnabled: "MERCURY_TELEGRAM_FORMAT_ENABLED",
+  mediaEnabled: "MERCURY_MEDIA_ENABLED",
+  mediaMaxSizeMb: "MERCURY_MEDIA_MAX_SIZE_MB",
+  admins: "MERCURY_ADMINS",
+  apiSecret: "MERCURY_API_SECRET",
+  chatApiKey: "MERCURY_CHAT_API_KEY",
+  consoleUrl: "MERCURY_CONSOLE_URL",
+  consoleUserId: "MERCURY_CONSOLE_USER_ID",
+  consoleInternalSecret: "MERCURY_CONSOLE_INTERNAL_SECRET",
+  tsAllowLiveOrders: "MERCURY_TS_ALLOW_LIVE_ORDERS",
+  ttsProvider: "MERCURY_TTS_PROVIDER",
+  azureSpeechKey: "MERCURY_AZURE_SPEECH_KEY",
+  azureSpeechRegion: "MERCURY_AZURE_SPEECH_REGION",
+  googleApplicationCredentials: "MERCURY_GOOGLE_APPLICATION_CREDENTIALS",
+  ttsMaxChars: "MERCURY_TTS_MAX_CHARS",
+  defaultTimezone: "MERCURY_DEFAULT_TIMEZONE",
+};
+
+function envValueForSchema(
+  env: NodeJS.ProcessEnv,
+  envKey: string,
+): string | undefined {
+  if (!Object.hasOwn(env, envKey)) return undefined;
+  return env[envKey];
+}
+
+/**
+ * Merge optional mercury.yaml with process.env. Env wins whenever the MERCURY_*
+ * key is present (even if empty). File values are ignored for secret keys.
+ */
+export function mergeRawMercuryConfig(
+  env: NodeJS.ProcessEnv = process.env,
+  cwd: string = process.cwd(),
+): RawMercuryConfigInput {
+  const configPath = resolveConfigPath(cwd);
+  let fromFile: RawMercuryConfigInput = {};
+
+  if (configPath) {
+    let rawYaml: unknown;
+    try {
+      rawYaml = parseYaml(readFileSync(configPath, "utf-8"));
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new Error(`Failed to read mercury config ${configPath}: ${msg}`);
+    }
+    const parsed = mercuryFileSchema.safeParse(rawYaml);
+    if (!parsed.success) {
+      const issues = parsed.error.issues
+        .map((i) => `${i.path.join(".")}: ${i.message}`)
+        .join("; ");
+      throw new Error(`Invalid mercury.yaml at ${configPath}: ${issues}`);
+    }
+    fromFile = flattenMercuryFile(parsed.data);
+    for (const secretKey of SECRET_SCHEMA_KEYS) {
+      delete fromFile[secretKey];
+    }
+  }
+
+  const merged: RawMercuryConfigInput = { ...fromFile };
+
+  for (const [camel, envKey] of Object.entries(CAMEL_TO_ENV)) {
+    if (envValueForSchema(env, envKey) !== undefined) {
+      merged[camel] = env[envKey];
+    }
+  }
+
+  // Standard GCP env (when MERCURY_GOOGLE_APPLICATION_CREDENTIALS not set)
+  if (
+    merged.googleApplicationCredentials == null &&
+    envValueForSchema(env, "GOOGLE_APPLICATION_CREDENTIALS") !== undefined
+  ) {
+    merged.googleApplicationCredentials = env.GOOGLE_APPLICATION_CREDENTIALS;
+  }
+
+  return merged;
+}

package/src/config-model-chain.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+
+export const MAX_MODEL_CHAIN_LEGS = 7;
+
+export const modelLegSchema = z.object({
+  provider: z.string().min(1),
+  model: z.string().min(1),
+});
+
+/** Validate YAML/JSON model chain legs (same rules as MERCURY_MODEL_CHAIN). */
+export function parseModelLegsArray(
+  parsed: unknown,
+  label: string,
+): { provider: string; model: string }[] {
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    throw new Error(
+      `${label} must be a non-empty array of { provider, model }`,
+    );
+  }
+  const legs = parsed.map((item, i) => {
+    const r = modelLegSchema.safeParse(item);
+    if (!r.success) {
+      throw new Error(
+        `${label}[${i}] must be { provider, model } non-empty strings`,
+      );
+    }
+    return r.data;
+  });
+  return legs.slice(0, MAX_MODEL_CHAIN_LEGS);
+}