mercury-agent 0.4.26 → 0.4.28

package/resources/templates/mercury.example.yaml

@@ -1,84 +1,84 @@
-# Copy to mercury.yaml in your project root (optional).
-# Precedence: MERCURY_* env vars override this file when the env key is set.
-# Secrets (API keys, tokens, MERCURY_API_SECRET, etc.) belong in .env only — not here.
-
-# server:
-#   port: 8787
-#   bot_username: mercury
-
-# model:
-#   chain:
-#     - provider: anthropic
-#       model: claude-sonnet-4-20250514
-#   # Legacy single primary + optional fallback (when chain is omitted):
-#   # provider: anthropic
-#   # model: claude-sonnet-4-20250514
-#   # fallback_provider: openai
-#   # fallback: gpt-4o-mini
-#   # max_retries_per_leg: 2
-#   # chain_budget_ms: 120000
-#   # capabilities: { tools: false }
-
-# Top-level alias for model.chain (optional; model.chain wins if both are set):
-# model_chain:
-#   - provider: google
-#     model: gemini-2.5-flash
-
-# ingress:
-#   discord: false
-#   slack: false
-#   teams: false
-#   whatsapp: false
-#   telegram: false
-
-# runtime:
-#   data_dir: .mercury
-#   # auth_path: ...
-#   # whatsapp_auth_dir: .mercury/whatsapp-auth
-#   max_concurrency: 2
-#   log_level: info
-#   log_format: text
-#   rate_limit_per_user: 10
-#   rate_limit_window_ms: 60000
-#   rate_limit_daily_member: 0     # 0 = unlimited; global daily message cap for members
-#   rate_limit_daily_admin: 0      # 0 = unlimited; global daily message cap for admins
-
-# trigger:
-#   patterns: "@Mercury,Mercury"
-#   match: mention
-
-# conditional_context:
-#   enabled: true
-#   classifier: heuristic
-#   # classifier_provider: groq
-#   # classifier_model: llama-3.3-70b-versatile
-
-# compaction:
-#   keep_recent_tokens: 20000
-#   # After each full-session run, auto-compact if the pi session has more than this many entries (10–10000). Omit to disable.
-#   # auto_compact_threshold: 50
-
-# agent:
-#   image: ghcr.io/avishai-tsabari/mercury-agent:latest
-#   container_timeout_ms: 300000
-#   container_bwrap_docker_compat: false
-
-# discord:
-#   gateway_duration_ms: 600000
-
-# telegram:
-#   format_enabled: true
-
-# media:
-#   enabled: true
-#   max_size_mb: 10
-
-# permissions:
-#   admins: ""
-
-# dm_auto_space:
-#   enabled: false
-#   admin_numbers:                              # auto-link to "main" space
-#     - "972501234567"
-#   default_system_prompt: ""                   # seeded into auto-created customer spaces
-#   default_member_permissions: "prompt,prefs.get"  # restrict customers to chat only
+# Copy to mercury.yaml in your project root (optional).
+# Precedence: MERCURY_* env vars override this file when the env key is set.
+# Secrets (API keys, tokens, MERCURY_API_SECRET, etc.) belong in .env only — not here.
+
+# server:
+#   port: 8787
+#   bot_username: mercury
+
+# model:
+#   chain:
+#     - provider: anthropic
+#       model: claude-sonnet-4-20250514
+#   # Legacy single primary + optional fallback (when chain is omitted):
+#   # provider: anthropic
+#   # model: claude-sonnet-4-20250514
+#   # fallback_provider: openai
+#   # fallback: gpt-4o-mini
+#   # max_retries_per_leg: 2
+#   # chain_budget_ms: 120000
+#   # capabilities: { tools: false }
+
+# Top-level alias for model.chain (optional; model.chain wins if both are set):
+# model_chain:
+#   - provider: google
+#     model: gemini-2.5-flash
+
+# ingress:
+#   discord: false
+#   slack: false
+#   teams: false
+#   whatsapp: false
+#   telegram: false
+
+# runtime:
+#   data_dir: .mercury
+#   # auth_path: ...
+#   # whatsapp_auth_dir: .mercury/whatsapp-auth
+#   max_concurrency: 2
+#   log_level: info
+#   log_format: text
+#   rate_limit_per_user: 10
+#   rate_limit_window_ms: 60000
+#   rate_limit_daily_member: 0     # 0 = unlimited; global daily message cap for members
+#   rate_limit_daily_admin: 0      # 0 = unlimited; global daily message cap for admins
+
+# trigger:
+#   patterns: "@Mercury,Mercury"
+#   match: mention
+
+# conditional_context:
+#   enabled: true
+#   classifier: heuristic
+#   # classifier_provider: groq
+#   # classifier_model: llama-3.3-70b-versatile
+
+# compaction:
+#   keep_recent_tokens: 20000
+#   # After each full-session run, auto-compact if the pi session has more than this many entries (10–10000). Omit to disable.
+#   # auto_compact_threshold: 50
+
+# agent:
+#   image: ghcr.io/avishai-tsabari/mercury-agent:latest
+#   container_timeout_ms: 300000
+#   container_bwrap_docker_compat: false
+
+# discord:
+#   gateway_duration_ms: 600000
+
+# telegram:
+#   format_enabled: true
+
+# media:
+#   enabled: true
+#   max_size_mb: 10
+
+# permissions:
+#   admins: ""
+
+# dm_auto_space:
+#   enabled: false
+#   admin_ids:                              # auto-link to "main" space
+#     - "972501234567"
+#   default_system_prompt: ""                   # seeded into auto-created customer spaces
+#   default_member_permissions: "prompt,prefs.get"  # restrict customers to chat only

package/src/config-file.ts

@@ -29,7 +29,7 @@ const mercuryFileSchema = z
         port: z.number().int().min(1).max(65535).optional(),
         bot_username: z.string().optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     model: z
@@ -48,7 +48,7 @@ const mercuryFileSchema = z
           .optional(),
         capabilities: z.record(z.string(), z.unknown()).optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     /** Top-level alias for `model.chain` */
@@ -65,7 +65,7 @@ const mercuryFileSchema = z
         whatsapp: z.boolean().optional(),
         telegram: z.boolean().optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     runtime: z
@@ -88,14 +88,14 @@ const mercuryFileSchema = z
         rate_limit_daily_member: z.number().int().min(0).max(10000).optional(),
         rate_limit_daily_admin: z.number().int().min(0).max(10000).optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     scheduling: z
       .object({
         default_timezone: z.string().optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     trigger: z
@@ -103,7 +103,7 @@ const mercuryFileSchema = z
         patterns: z.string().optional(),
         match: z.string().optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     context: z
@@ -112,7 +112,7 @@ const mercuryFileSchema = z
         window_size: z.number().int().min(1).max(50).optional(),
         reply_chain_depth: z.number().int().min(1).max(50).optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     agent: z
@@ -127,7 +127,7 @@ const mercuryFileSchema = z
         container_bwrap_docker_compat: z.boolean().optional(),
         override_pi_system_prompt: z.boolean().optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     discord: z
@@ -139,14 +139,14 @@ const mercuryFileSchema = z
           .max(60 * 60 * 1000)
           .optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     telegram: z
       .object({
         format_enabled: z.boolean().optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     media: z
@@ -154,32 +154,126 @@ const mercuryFileSchema = z
         enabled: z.boolean().optional(),
         max_size_mb: z.number().min(1).max(100).optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     permissions: z
       .object({
         admins: z.string().optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     dm_auto_space: z
       .object({
         enabled: z.boolean().optional(),
-        admin_numbers: z.array(z.string()).optional(),
+        admin_ids: z.array(z.string()).optional(),
         default_system_prompt: z.string().optional(),
         default_member_permissions: z.string().optional(),
       })
-      .strict()
+      .strip()
       .optional(),
   })
-  .strict();
+  .strip();
 
 type MercuryFile = z.infer<typeof mercuryFileSchema>;
 
 export type RawMercuryConfigInput = Record<string, unknown>;
 
+const KNOWN_TOP_KEYS = new Set([
+  "server",
+  "model",
+  "model_chain",
+  "ingress",
+  "runtime",
+  "scheduling",
+  "trigger",
+  "context",
+  "agent",
+  "discord",
+  "telegram",
+  "media",
+  "permissions",
+  "dm_auto_space",
+]);
+
+const KNOWN_SECTION_KEYS: Record<string, Set<string>> = {
+  server: new Set(["port", "bot_username"]),
+  model: new Set([
+    "chain",
+    "provider",
+    "model",
+    "fallback_provider",
+    "fallback",
+    "max_retries_per_leg",
+    "chain_budget_ms",
+    "capabilities",
+  ]),
+  ingress: new Set(["discord", "slack", "teams", "whatsapp", "telegram"]),
+  runtime: new Set([
+    "data_dir",
+    "auth_path",
+    "whatsapp_auth_dir",
+    "max_concurrency",
+    "log_level",
+    "log_format",
+    "rate_limit_per_user",
+    "rate_limit_window_ms",
+    "rate_limit_daily_member",
+    "rate_limit_daily_admin",
+  ]),
+  scheduling: new Set(["default_timezone"]),
+  trigger: new Set(["patterns", "match"]),
+  context: new Set(["mode", "window_size", "reply_chain_depth"]),
+  agent: new Set([
+    "image",
+    "container_timeout_ms",
+    "container_bwrap_docker_compat",
+    "override_pi_system_prompt",
+  ]),
+  discord: new Set(["gateway_duration_ms"]),
+  telegram: new Set(["format_enabled"]),
+  media: new Set(["enabled", "max_size_mb"]),
+  permissions: new Set(["admins"]),
+  dm_auto_space: new Set([
+    "enabled",
+    "admin_ids",
+    "default_system_prompt",
+    "default_member_permissions",
+  ]),
+};
+
+function warnUnknownKeys(
+  rawYaml: Record<string, unknown>,
+  configPath: string,
+  log: (msg: string) => void,
+): void {
+  for (const key of Object.keys(rawYaml)) {
+    if (!KNOWN_TOP_KEYS.has(key)) {
+      log(
+        `[WARN] Unknown key "${key}" in ${configPath} — ignored. Check spelling or update mercury-agent.`,
+      );
+      continue;
+    }
+    const section = rawYaml[key];
+    const knownKeys = KNOWN_SECTION_KEYS[key];
+    if (
+      knownKeys &&
+      section != null &&
+      typeof section === "object" &&
+      !Array.isArray(section)
+    ) {
+      for (const subKey of Object.keys(section)) {
+        if (!knownKeys.has(subKey)) {
+          log(
+            `[WARN] Unknown key "${key}.${subKey}" in ${configPath} — ignored. Check spelling or update mercury-agent.`,
+          );
+        }
+      }
+    }
+  }
+}
+
 function resolveConfigPath(cwd: string): string | null {
   const explicit = process.env.MERCURY_CONFIG_FILE;
   if (explicit !== undefined) {
@@ -294,8 +388,8 @@ function flattenMercuryFile(f: MercuryFile): RawMercuryConfigInput {
   if (f.dm_auto_space?.enabled != null) {
     o.dmAutoSpaceEnabled = f.dm_auto_space.enabled;
   }
-  if (f.dm_auto_space?.admin_numbers != null) {
-    o.dmAutoSpaceAdminNumbers = f.dm_auto_space.admin_numbers.join(",");
+  if (f.dm_auto_space?.admin_ids != null) {
+    o.dmAutoSpaceAdminIds = f.dm_auto_space.admin_ids.join(",");
   }
   if (f.dm_auto_space?.default_system_prompt != null) {
     o.dmAutoSpaceDefaultSystemPrompt = f.dm_auto_space.default_system_prompt;
@@ -370,7 +464,7 @@ const CAMEL_TO_ENV: Record<string, string> = {
   rateLimitDailyMember: "MERCURY_RATE_LIMIT_DAILY_MEMBER",
   rateLimitDailyAdmin: "MERCURY_RATE_LIMIT_DAILY_ADMIN",
   dmAutoSpaceEnabled: "MERCURY_DM_AUTO_SPACE_ENABLED",
-  dmAutoSpaceAdminNumbers: "MERCURY_DM_AUTO_SPACE_ADMIN_NUMBERS",
+  dmAutoSpaceAdminIds: "MERCURY_DM_AUTO_SPACE_ADMIN_IDS",
   dmAutoSpaceDefaultSystemPrompt: "MERCURY_DM_AUTO_SPACE_DEFAULT_SYSTEM_PROMPT",
   dmAutoSpaceDefaultMemberPermissions:
     "MERCURY_DM_AUTO_SPACE_DEFAULT_MEMBER_PERMISSIONS",
@@ -391,6 +485,7 @@ function envValueForSchema(
 export function mergeRawMercuryConfig(
   env: NodeJS.ProcessEnv = process.env,
   cwd: string = process.cwd(),
+  log: (msg: string) => void = console.warn,
 ): RawMercuryConfigInput {
   const configPath = resolveConfigPath(cwd);
   let fromFile: RawMercuryConfigInput = {};
@@ -404,6 +499,11 @@ export function mergeRawMercuryConfig(
       throw new Error(`Failed to read mercury config ${configPath}: ${msg}`);
     }
     if (rawYaml == null) rawYaml = {};
+
+    if (typeof rawYaml === "object" && !Array.isArray(rawYaml)) {
+      warnUnknownKeys(rawYaml as Record<string, unknown>, configPath, log);
+    }
+
     const parsed = mercuryFileSchema.safeParse(rawYaml);
     if (!parsed.success) {
       const issues = parsed.error.issues

package/src/config.ts

@@ -252,7 +252,7 @@ const schema = z.object({
 
   // ─── DM Auto-Space ─────────────────────────────────────────────────
   dmAutoSpaceEnabled: booleanFromEnv.default(false),
-  dmAutoSpaceAdminNumbers: z.string().default(""),
+  dmAutoSpaceAdminIds: z.string().default(""),
   dmAutoSpaceDefaultSystemPrompt: z.string().default(""),
   dmAutoSpaceDefaultMemberPermissions: z.string().default("prompt,prefs.get"),
 });

package/src/core/conversation.ts

@@ -9,7 +9,7 @@ export interface ConversationResolution {
 
 export interface AutoSpaceConfig {
   enabled: boolean;
-  adminNumbers: string[];
+  adminIds: string[];
   defaultSystemPrompt: string;
   defaultMemberPermissions: string;
   rateLimitDailyMember: number;
@@ -61,7 +61,7 @@ export function resolveConversation(
   if (!autoSpace?.enabled || kind !== "dm") return null;
 
   const senderNormalized = normalizePhone(externalId);
-  const isAdmin = autoSpace.adminNumbers.some(
+  const isAdmin = autoSpace.adminIds.some(
     (n) => normalizePhone(n) === senderNormalized,
   );
 

package/src/core/handler.ts

@@ -28,7 +28,7 @@ export function createMessageHandler(opts: MessageHandlerOptions) {
   const autoSpaceConfig: AutoSpaceConfig | undefined = config.dmAutoSpaceEnabled
     ? {
         enabled: true,
-        adminNumbers: config.dmAutoSpaceAdminNumbers
+        adminIds: config.dmAutoSpaceAdminIds
           .split(",")
           .map((s) => s.trim())
           .filter(Boolean),

package/src/core/routes/console.ts

@@ -275,6 +275,38 @@ export function createConsoleApp(opts: {
     return c.json({ connections });
   });
 
+  /* ── Credential injection ────────────────────────────────────── */
+
+  app.post("/credentials", async (c) => {
+    const body = (await c.req.json().catch(() => ({}))) as {
+      envVar?: string;
+      value?: string;
+      restart?: boolean;
+    };
+
+    const envVar = typeof body.envVar === "string" ? body.envVar.trim() : "";
+    const value = typeof body.value === "string" ? body.value : "";
+    const shouldRestart = body.restart !== false;
+
+    if (!envVar || !/^[A-Z_][A-Z0-9_]*$/.test(envVar)) {
+      return c.json(
+        { error: "envVar must be a valid SCREAMING_SNAKE_CASE name" },
+        400,
+      );
+    }
+
+    const envPath = path.join(opts.projectRoot, ".env");
+    updateDotEnv(envPath, { [envVar]: value || null });
+    logger.info(`Console: credential written`, { envVar, removed: !value });
+
+    if (shouldRestart && value) {
+      setTimeout(() => process.kill(process.pid, "SIGTERM"), 500);
+      return c.json({ ok: true, envVar, restarting: true });
+    }
+
+    return c.json({ ok: true, envVar, restarting: false });
+  });
+
   /* ── Adapter management ──────────────────────────────────────── */
 
   /** Return current adapter enable/disable state and credential presence. */