mercury-agent 0.5.19 → 0.6.0

package/README.md

@@ -460,6 +460,30 @@ curl -X POST http://localhost:8787/api/broadcast \
 
 Returns `{ total, delivered, failed, errors }`. Only global admins (`admins` or `dm_auto_space.admin_ids`) may broadcast. Messages are sent as literal text — no LLM processing.
 
+#### Bot Character
+
+Global admins can set a bot-wide character (tone, greeting style, personality) that applies to all spaces — including every DM auto-space. Stored in the database; survives profile deploys.
+
+The recommended flow is conversational: tell the bot to change its character, it drafts the update, confirms with you, then saves via `mrctl character set --file <path>`. Programmatic access:
+
+```bash
+# Set
+curl -X PUT http://localhost:8787/api/character \
+  -H "Authorization: Bearer $API_SECRET" \
+  -H "X-Mercury-Caller: <admin-id>" \
+  -H "X-Mercury-Space: main" \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Be warm and professional. Greet with שלום וברכה."}'
+
+# Get current character
+curl http://localhost:8787/api/character ...
+
+# Clear
+curl -X DELETE http://localhost:8787/api/character ...
+```
+
+Only global admins may set the character (same gate as broadcast). Per-space tone adjustments use the existing per-space `system_prompt` in dashboard settings.
+
 ### Per-space Config
 
 Conversations are discovered from incoming traffic. Unlinked conversations stay idle until you attach them to a space via `mercury link <conversation-id> <space-id>` or the dashboard.

package/docs/authoring-profiles.md

@@ -44,7 +44,7 @@ env:
     default: "09:00-18:00"
 
 # Project-wide agent persona, injected into every container's system prompt.
-system_prompt: |
+profile_prompt: |
   You are a meeting room booking assistant. Help each user book, view, and
   cancel ONLY their own reservations. Never reveal other users' bookings.
 

package/docs/context-architecture.md

@@ -45,15 +45,31 @@ Every request runs with `--no-session` (no pi session file). Continuity across r
 
 The session boundary (`chat_state.min_message_id`) excludes messages older than the last `compact` call from the sliding window. Run `mrctl compact` to reset the boundary and start fresh.
 
-### Prompt structure (inside container)
+### System prompt layering (broadest → most specific)
 
 ```
-<system>
-  [identity: AGENTS.md + capabilities + memory guidance]
-</system>
+1. pi built-in prompt (Claude Code identity, tool definitions)
+   — or Mercury's override when OVERRIDE_PI_SYSTEM_PROMPT is set
 
-<caller>…</caller>
+2. Mercury platform additions (buildMercuryAdditions)
+   — identity, inbox/outbox, permissions, moderation, capabilities, memory guidance
+
+3. MERCURY_EXT_SYSTEM_PROMPT (assembled on host, passed as env var):
+   a. Extension before_container fragments
+   b. profile_prompt           (capability playbook — deploy-owned)
+   c. Bot Character            (global voice — owner-owned, via project_config DB)
+   d. Per-space system_prompt  (space refinement — space-admin-owned)
+
+4. AGENTS.md files (pi auto-discovers from PI_CODING_AGENT_DIR + workspace cwd)
+   — global (:ro) + per-space
+```
+
+### User prompt structure (inside container)
+
+```
+<caller id="…" name="…" role="…" space="…" />
 <episodic_memory>…</episodic_memory>   ← MEMORY.md (if present)
+<active_episodes>…</active_episodes>   ← relevance-scored episode snippets
 <history>                               ← sliding window from DB
   <turn timestamp="…">
     <user>…</user>
@@ -64,6 +80,7 @@ The session boundary (`chat_state.min_message_id`) excludes messages older than
 <ambient_messages>…</ambient_messages>
 <preferences>…</preferences>
 <attachments>…</attachments>
+<reply_anchor>…</reply_anchor>          ← only on replies
 
 [user prompt text]
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercury-agent",
-  "version": "0.5.19",
+  "version": "0.6.0",
   "description": "Personal AI assistant for chat platforms (WhatsApp, Slack, Discord, Telegram)",
   "license": "MIT",
   "author": "Avishai Tsabari",

package/resources/templates/AGENTS.md

@@ -155,3 +155,22 @@ You can delegate tasks to specialized sub-agents:
 
 ### Chained Workflow
 "Use a chain: first have explore find the code, then have worker implement the fix"
+
+## Character
+
+The system prompt may include a "Bot Character" section — the owner-defined voice for
+all conversations. Always follow it.
+
+When a user asks you to change your personality, tone, greeting style, or character:
+1. Read the current character: `mrctl character get`
+2. Draft the FULL updated character text — merge their request with the existing
+   character into one coherent text. Do not append contradictory fragments.
+3. Show the draft and ask for explicit confirmation.
+4. On confirmation, write the draft to a temp file and run:
+   `mrctl character set --file <path>`
+5. Relay the result. If the API returns 403, tell the user that only the bot owner
+   can change the global character.
+
+Only global admins (configured on the host) can change the character — the API
+enforces this. Per-space tone adjustments go in this space's `system_prompt`,
+which is set from the dashboard (Spaces settings).

package/src/agent/container-entry.ts

@@ -266,7 +266,7 @@ function buildCapabilitySection(
  * lines plus all Mercury platform content. This is appended after pi's own default system prompt.
  *
  * In override mode (skipIdentity=true): omits the "You are Claude Code" preamble since the outer
- * wrapper in buildSystemPrompt provides the identity. Mercury identity ("You are Mercury") and all
+ * wrapper in buildSystemPrompt provides the identity. Bot identity (from BOT_USERNAME env) and all
  * platform content (inbox/outbox, docs reference, permissions, moderation) are retained.
  */
 function buildMercuryAdditions(
@@ -279,9 +279,12 @@ function buildMercuryAdditions(
   const claudeCodePreamble = `You are Claude Code, Anthropic's official CLI for Claude.
 Prioritize practical outputs and explicit assumptions.`;
 
+  const raw = process.env.BOT_USERNAME || "Mercury";
+  const botName = raw.charAt(0).toUpperCase() + raw.slice(1);
+
   const mercuryPlatform = `Files received from users (images, documents, voice notes) are saved to the \`inbox/\` directory in the current workspace. To send files back with your reply, write them to the \`outbox/\` directory — any files created or modified there during this run will be automatically attached to your response.
 
-You are Mercury, built from https://github.com/Avishai-Tsabari/mercury. When users ask about Mercury — what it can do, how to configure it, scheduling, permissions, extensions, or anything about the platform — you MUST read from \`/docs/mercury/\` before answering. Start with \`/docs/mercury/README.md\` for an overview, then check \`/docs/mercury/docs/\` for detailed guides.
+You are ${botName}. You run on the Mercury platform (https://github.com/Avishai-Tsabari/mercury). When users ask about the platform — what it can do, how to configure it, scheduling, permissions, extensions, or anything about Mercury — you MUST read from \`/docs/mercury/\` before answering. Start with \`/docs/mercury/README.md\` for an overview, then check \`/docs/mercury/docs/\` for detailed guides.
 
 ## Permissions & Security
 Each run is triggered by a specific caller with a role (admin or member). The caller's identity and role are provided in the user prompt as a <caller /> tag.
@@ -707,6 +710,9 @@ function buildBwrapArgs(
     "--bind",
     "/home/mercury",
     "/home/mercury",
+    "--ro-bind",
+    "/home/mercury/.pi/agent",
+    "/home/mercury/.pi/agent",
     "--proc",
     "/proc",
     "--dev",

package/src/agent/container-runner.ts

@@ -871,6 +871,7 @@ export class AgentContainerRunner {
         key: "OVERRIDE_PI_SYSTEM_PROMPT",
         value: this.config.overridePiSystemPrompt ? "true" : "false",
       },
+      { key: "BOT_USERNAME", value: this.config.botUsername },
     ].filter((x): x is { key: string; value: string } => Boolean(x.value));
 
     const containerName = this.generateContainerName();
@@ -965,7 +966,7 @@ export class AgentContainerRunner {
       "-v",
       `${innerSpaceDir}:/spaces/${input.spaceId}`,
       "-v",
-      `${innerGlobalDir}:/home/mercury/.pi/agent`,
+      `${innerGlobalDir}:/home/mercury/.pi/agent:ro`,
       "-v",
       `${readmePath}:/docs/mercury/README.md:ro`,
       "-v",

package/src/cli/mrctl.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import type { StorageResponse } from "../core/routes/storage.js";
 import { buildRequestInit } from "./mrctl-http.js";
@@ -96,6 +96,7 @@ Built-in commands:
   mrctl compact
   mrctl clear
   mrctl recall <search text> [--limit N]
+  mrctl character get|set|clear
   mrctl capability <name> <action> [json-body]
   mrctl tts synthesize --text "Hello" --out outbox/reply.mp3 \\
       [--language auto|he-IL|en-US] [--provider google|azure|auto]
@@ -133,6 +134,46 @@ async function main() {
       break;
     }
 
+    case "character": {
+      if (!sub) usage();
+      switch (sub) {
+        case "get": {
+          const data = (await api("GET", "/api/character")) as {
+            character: string | null;
+          };
+          if (data.character === null) {
+            process.stdout.write("(not set)\n");
+          } else {
+            process.stdout.write(`${data.character}\n`);
+          }
+          break;
+        }
+        case "set": {
+          const filePath = parseFlag(args, "--file");
+          let text: string;
+          if (filePath) {
+            text = readFileSync(filePath, "utf-8");
+          } else {
+            const fileIdx = args.indexOf("--file");
+            const words = args.slice(2).filter((_, i) => {
+              const absIdx = i + 2;
+              return absIdx !== fileIdx && absIdx !== fileIdx + 1;
+            });
+            if (words.length === 0) fatal("Missing text or --file <path>");
+            text = words.join(" ");
+          }
+          print(await api("PUT", "/api/character", { text }));
+          break;
+        }
+        case "clear":
+          print(await api("DELETE", "/api/character"));
+          break;
+        default:
+          fatal(`Unknown character subcommand: ${sub}`);
+      }
+      break;
+    }
+
     case "capability": {
       // mrctl capability <name> <action> [json-body]
       const name = requireArg(args, 1, "capability name");

package/src/core/api.ts

@@ -6,6 +6,7 @@ import { resolveRole } from "./permissions.js";
 import {
   broadcast,
   capability,
+  character,
   config,
   connections,
   control,
@@ -113,6 +114,7 @@ export function createApiApp(apiCtx: ApiContext): Hono<Env> {
   app.route("/tts", tts);
   app.route("/capability", capability);
   app.route("/broadcast", broadcast);
+  app.route("/character", character);
 
   // ─── Fallback ───────────────────────────────────────────────────────────
 

package/src/core/global-admin.ts

@@ -0,0 +1,36 @@
+/**
+ * Check if a caller is a global admin (configured in mercury.yaml / env).
+ * Global admins are identified by `config.admins` and `config.dmAutoSpaceAdminIds`.
+ * Platform-specific ID prefixes, + signs, and @domain suffixes are normalized.
+ */
+export function isGlobalAdmin(
+  callerId: string,
+  config: { admins?: string; dmAutoSpaceAdminIds?: string },
+): boolean {
+  const globalAdmins = [
+    ...(config.admins
+      ? config.admins
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : []),
+    ...(config.dmAutoSpaceAdminIds
+      ? config.dmAutoSpaceAdminIds
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : []),
+  ];
+
+  const normalize = (s: string) =>
+    s
+      .replace(/^[^:]+:/, "")
+      .replace(/^[+]+/, "")
+      .replace(/@.*$/, "");
+
+  const callerNormalized = normalize(callerId);
+
+  return globalAdmins.some(
+    (id) => id === callerId || normalize(id) === callerNormalized,
+  );
+}

package/src/core/profiles.ts

@@ -68,7 +68,7 @@ export const profileSchema = z.object({
    */
   member_permissions: z.array(z.string()).optional(),
   /** Profile-specific agent persona, injected into the container. */
-  system_prompt: z.string().optional(),
+  profile_prompt: z.string().optional(),
 });
 
 export type MercuryProfile = z.infer<typeof profileSchema>;
@@ -178,7 +178,7 @@ export interface ActiveProfile {
   /** Exhaustive member permission set, or null when the profile doesn't scope members. */
   memberPermissions: string[] | null;
   /** Profile agent persona, or null. */
-  systemPrompt: string | null;
+  profilePrompt: string | null;
 }
 
 const ACTIVE_PROFILE_FILE = "active-profile.json";
@@ -191,7 +191,7 @@ export function persistActiveProfile(
   const activation: ActiveProfile = {
     name: profile.name,
     memberPermissions: profile.member_permissions ?? null,
-    systemPrompt: profile.system_prompt ?? null,
+    profilePrompt: profile.profile_prompt ?? null,
   };
   mkdirSync(dataDir, { recursive: true });
   writeFileSync(
@@ -205,7 +205,12 @@ export function loadActiveProfile(dataDir: string): ActiveProfile | null {
   const file = join(dataDir, ACTIVE_PROFILE_FILE);
   if (!existsSync(file)) return null;
   try {
-    return JSON.parse(readFileSync(file, "utf-8")) as ActiveProfile;
+    const raw = JSON.parse(readFileSync(file, "utf-8"));
+    return {
+      name: raw.name,
+      memberPermissions: raw.memberPermissions ?? null,
+      profilePrompt: raw.profilePrompt ?? raw.systemPrompt ?? null,
+    };
   } catch {
     return null;
   }
@@ -216,16 +221,16 @@ export function loadActiveProfile(dataDir: string): ActiveProfile | null {
  * every container's system prompt. Held here so the runtime can read it without
  * re-reading the manifest per message.
  */
-let activeProfileSystemPrompt: string | null = null;
+let activeProfilePromptValue: string | null = null;
 
-/** Set (or clear, with null) the active profile's system prompt. */
-export function setActiveProfileSystemPrompt(prompt: string | null): void {
-  activeProfileSystemPrompt = prompt;
+/** Set (or clear, with null) the active profile's prompt. */
+export function setActiveProfilePrompt(prompt: string | null): void {
+  activeProfilePromptValue = prompt;
 }
 
-/** The active profile's system prompt, or null when no profile scopes it. */
-export function getActiveProfileSystemPrompt(): string | null {
-  return activeProfileSystemPrompt;
+/** The active profile's prompt, or null when no profile scopes it. */
+export function getActiveProfilePrompt(): string | null {
+  return activeProfilePromptValue;
 }
 
 /**

package/src/core/routes/broadcast.ts

@@ -1,6 +1,7 @@
 import { Hono } from "hono";
 import { logger } from "../../logger.js";
 import { type Env, getApiCtx, getAuth } from "../api-types.js";
+import { isGlobalAdmin } from "../global-admin.js";
 
 export const broadcast = new Hono<Env>();
 
@@ -12,34 +13,7 @@ broadcast.post("/", async (c) => {
     return c.json({ error: "dm_auto_space is not enabled" }, 503);
   }
 
-  const globalAdmins = [
-    ...(config.admins
-      ? config.admins
-          .split(",")
-          .map((s) => s.trim())
-          .filter(Boolean)
-      : []),
-    ...(config.dmAutoSpaceAdminIds
-      ? config.dmAutoSpaceAdminIds
-          .split(",")
-          .map((s) => s.trim())
-          .filter(Boolean)
-      : []),
-  ];
-
-  const normalize = (s: string) =>
-    s
-      .replace(/^[^:]+:/, "")
-      .replace(/^[+]+/, "")
-      .replace(/@.*$/, "");
-
-  const callerNormalized = normalize(callerId);
-
-  const isAdmin = globalAdmins.some(
-    (id) => id === callerId || normalize(id) === callerNormalized,
-  );
-
-  if (!isAdmin) {
+  if (!isGlobalAdmin(callerId, config)) {
     logger.warn("Broadcast denied — caller is not a global admin", {
       callerId,
     });

package/src/core/routes/character.ts

@@ -0,0 +1,69 @@
+import { Hono } from "hono";
+import { logger } from "../../logger.js";
+import { type Env, getApiCtx, getAuth } from "../api-types.js";
+import { isGlobalAdmin } from "../global-admin.js";
+
+const MAX_CHARACTER_LENGTH = 4000;
+
+export const character = new Hono<Env>();
+
+character.get("/", (c) => {
+  const { callerId } = getAuth(c);
+  const { config, db } = getApiCtx(c);
+
+  if (!isGlobalAdmin(callerId, config)) {
+    logger.warn("Character get denied — caller is not a global admin", {
+      callerId,
+    });
+    return c.json({ error: "Forbidden: requires global admin" }, 403);
+  }
+
+  const value = db.getProjectConfig("character");
+  const updatedBy = db.getProjectConfigUpdatedBy("character");
+
+  return c.json({ character: value, updatedBy });
+});
+
+character.put("/", async (c) => {
+  const { callerId } = getAuth(c);
+  const { config, db } = getApiCtx(c);
+
+  if (!isGlobalAdmin(callerId, config)) {
+    logger.warn("Character set denied — caller is not a global admin", {
+      callerId,
+    });
+    return c.json({ error: "Forbidden: requires global admin" }, 403);
+  }
+
+  const body = (await c.req.json().catch(() => ({}))) as { text?: string };
+  const text = typeof body.text === "string" ? body.text.trim() : "";
+
+  if (!text) {
+    return c.json({ error: "Missing or empty 'text' field" }, 400);
+  }
+
+  if (text.length > MAX_CHARACTER_LENGTH) {
+    return c.json(
+      { error: `Text exceeds ${MAX_CHARACTER_LENGTH} character limit` },
+      400,
+    );
+  }
+
+  db.setProjectConfig("character", text, callerId);
+  return c.json({ ok: true });
+});
+
+character.delete("/", (c) => {
+  const { callerId } = getAuth(c);
+  const { config, db } = getApiCtx(c);
+
+  if (!isGlobalAdmin(callerId, config)) {
+    logger.warn("Character clear denied — caller is not a global admin", {
+      callerId,
+    });
+    return c.json({ error: "Forbidden: requires global admin" }, 403);
+  }
+
+  db.deleteProjectConfig("character");
+  return c.json({ ok: true });
+});

package/src/core/routes/dashboard.ts

@@ -1030,6 +1030,14 @@ export function createDashboardRoutes(ctx: DashboardContext) {
         </div>
       </div>
 
+      ${raw(
+        (() => {
+          const charText = core.db.getProjectConfig("character");
+          if (!charText) return "";
+          return `<div class="panel"><div class="panel-header">Bot Character</div><div class="panel-body"><pre style="white-space:pre-wrap;word-break:break-word;margin:0;font-family:inherit;font-size:13px;color:var(--fg-muted)">${escapeHtml(charText)}</pre></div></div>`;
+        })(),
+      )}
+
       ${raw(renderExtensionWidgets())}
     `);
   });

package/src/core/routes/index.ts

@@ -1,5 +1,6 @@
 export { broadcast } from "./broadcast.js";
 export { capability } from "./capability.js";
+export { character } from "./character.js";
 export { config } from "./config.js";
 export { connections } from "./connections.js";
 export { control } from "./control.js";

package/src/core/runtime.ts

@@ -25,7 +25,7 @@ import type {
 } from "../types.js";
 import { formatCategoryHelp, formatHelp } from "./commands.js";
 import { hasPermission, resolveRole } from "./permissions.js";
-import { getActiveProfileSystemPrompt } from "./profiles.js";
+import { getActiveProfilePrompt } from "./profiles.js";
 import { RateLimiter } from "./rate-limiter.js";
 import { type RouteResult, routeInput } from "./router.js";
 import { SpaceQueue } from "./space-queue.js";
@@ -1290,7 +1290,7 @@ export class MercuryCoreRuntime {
 
       // Inject the active applicative profile persona (project-wide), ahead of
       // any per-space system prompt so a space-specific prompt refines it.
-      const profilePrompt = getActiveProfileSystemPrompt();
+      const profilePrompt = getActiveProfilePrompt();
       if (profilePrompt) {
         const existing = extraEnv?.MERCURY_EXT_SYSTEM_PROMPT;
         extraEnv = {
@@ -1301,6 +1301,19 @@ export class MercuryCoreRuntime {
         };
       }
 
+      // Inject global character (owner-set voice, deploy-safe, global-admin gated).
+      const characterPrompt = this.db.getProjectConfig("character");
+      if (characterPrompt) {
+        const existing = extraEnv?.MERCURY_EXT_SYSTEM_PROMPT;
+        const block = `## Bot Character (set by the owner — applies to all conversations)\n${characterPrompt}`;
+        extraEnv = {
+          ...extraEnv,
+          MERCURY_EXT_SYSTEM_PROMPT: existing
+            ? `${existing}\n\n${block}`
+            : block,
+        };
+      }
+
       // Inject per-space system prompt (set via console Spaces settings or at provision time).
       const spacePrompt = this.db.getSpaceConfig(spaceId, "system_prompt");
       if (spacePrompt) {

package/src/main.ts

@@ -35,10 +35,7 @@ import { createChatShim } from "./chat-shim.js";
 import { loadConfig, resolveProjectPath } from "./config.js";
 import { createMessageHandler } from "./core/handler.js";
 import { setActiveProfileMemberPermissions } from "./core/permissions.js";
-import {
-  loadActiveProfile,
-  setActiveProfileSystemPrompt,
-} from "./core/profiles.js";
+import { loadActiveProfile, setActiveProfilePrompt } from "./core/profiles.js";
 import { MercuryCoreRuntime } from "./core/runtime.js";
 import { runStorageCleanup } from "./core/storage-cleanup.js";
 import { isOverQuota } from "./core/storage-guard.js";
@@ -225,7 +222,7 @@ async function main() {
   const activeProfile = loadActiveProfile(resolveProjectPath(config.dataDir));
   if (activeProfile) {
     setActiveProfileMemberPermissions(activeProfile.memberPermissions ?? null);
-    setActiveProfileSystemPrompt(activeProfile.systemPrompt ?? null);
+    setActiveProfilePrompt(activeProfile.profilePrompt ?? null);
     logger.info("Applicative profile active", {
       profile: activeProfile.name,
       memberPermissions:

package/src/storage/db.ts

@@ -206,6 +206,14 @@ export class Db {
         updated_at INTEGER NOT NULL,
         PRIMARY KEY (space_id, platform_user_id, date)
       );
+
+      CREATE TABLE IF NOT EXISTS project_config (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        updated_by TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
     `);
     this.ensureMessagesRunMetaColumn();
     this.ensureChatStateClearBoundaryColumn();
@@ -1327,6 +1335,41 @@ export class Db {
     return res.changes > 0;
   }
 
+  // --- Project Config (global, not tied to any space) ---
+
+  getProjectConfig(key: string): string | null {
+    const row = this.db
+      .query("SELECT value FROM project_config WHERE key = ?")
+      .get(key) as { value: string } | null;
+    return row?.value ?? null;
+  }
+
+  getProjectConfigUpdatedBy(key: string): string | null {
+    const row = this.db
+      .query("SELECT updated_by FROM project_config WHERE key = ?")
+      .get(key) as { updated_by: string } | null;
+    return row?.updated_by ?? null;
+  }
+
+  setProjectConfig(key: string, value: string, updatedBy: string): void {
+    const now = Date.now();
+    this.db
+      .query(
+        `INSERT INTO project_config(key, value, updated_by, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(key)
+         DO UPDATE SET value = excluded.value, updated_by = excluded.updated_by, updated_at = excluded.updated_at`,
+      )
+      .run(key, value, updatedBy, now, now);
+  }
+
+  deleteProjectConfig(key: string): boolean {
+    const res = this.db
+      .query("DELETE FROM project_config WHERE key = ?")
+      .run(key);
+    return res.changes > 0;
+  }
+
   // --- Space preferences (chat-managed) ---
 
   getSpacePreference(spaceId: string, key: string): string | null {