mercury-agent 0.5.19 → 0.7.0-beta.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/configuration.md

@@ -41,6 +41,21 @@ Per-space overrides via `mrctl config set context.<key> <value>` always win over
 
 You may also set a top-level **`model_chain`** array as an alias for `model.chain`.
 
+## Extension config defaults (`extensions:`)
+
+Deployment-wide defaults for extension config keys, applied to **every space** (including auto-created DM spaces) at read time:
+
+```yaml
+extensions:
+  voice-transcribe:
+    provider: openai
+    model: whisper-large-v3
+    base_url: https://api.groq.com/openai/v1
+    language: he
+```
+
+Resolution order for an extension config key: per-space value (`mrctl config set`) → `@global` scope (set from the dashboard **Features** page) → this YAML section (env: `MERCURY_EXTENSION_DEFAULTS` as flat JSON, e.g. `{"voice-transcribe.provider":"openai"}`) → the extension's registered default. Changing a global or YAML value takes effect for all existing and future spaces immediately (YAML on restart) — nothing is copied into per-space rows.
+
 ## Model chain
 
 In YAML, use a list of `{ provider, model }` objects under `model.chain` (max 4 legs). The same rules apply as for `MERCURY_MODEL_CHAIN` JSON.

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/docs/dashboard.md

@@ -64,6 +64,8 @@ Manage API keys for supported model providers (Anthropic, OpenAI, Google Gemini,
 
 Extension management through the UI. Shows installed extensions with their capabilities (CLI / skill / widget) and a remove button. Lists available catalog extensions with a one-click install button. Installing or removing an extension triggers a container image rebuild and restart.
 
+Also hosts the **Global config defaults** panel: set deployment-wide values for any registered extension config key (the `@global` scope). These apply to every space — including auto-created DM spaces — unless a space overrides them, and win over the `extensions:` section in `mercury.yaml`. See [configuration.md](configuration.md#extension-config-defaults-extensions).
+
 ## Real-time Updates
 
 The dashboard uses Server-Sent Events (SSE) for live updates:

package/docs/extensions.md

@@ -95,10 +95,12 @@ Declare an environment variable this extension needs. Only injected into contain
 ```typescript
 mercury.env({ from: "MERCURY_GH_TOKEN" });                    // injected as GH_TOKEN
 mercury.env({ from: "MERCURY_GH_TOKEN", as: "GITHUB_TOKEN" }); // custom container name
+mercury.env({ from: "MERCURY_STT_API_KEY", hostOnly: true }); // host-side only
 ```
 
 - `from` — env var name as set in `.env` (e.g. `MERCURY_GH_TOKEN`)
 - `as` — (optional) name inside the container. Defaults to `from` with `MERCURY_` prefix stripped
+- `hostOnly` — (optional) claim the var (kept out of the blind `MERCURY_*` passthrough) but **never inject it into any container**. Use for secrets consumed only by host-side hooks/jobs (e.g. an STT API key used in `before_container`).
 
 Can be called multiple times for multiple env vars.
 
@@ -223,6 +225,8 @@ mercury.config("enabled", {
 
 Keys are namespaced to the extension: the above registers `napkin.enabled`. Users set it via `mrctl config set napkin.enabled false`.
 
+In hooks and jobs, read values with `ctx.getConfig(spaceId, "napkin.enabled")` instead of `ctx.db.getSpaceConfig(...) ?? default`. It resolves the full chain: per-space value → `@global` scope (dashboard **Features** page) → `extensions:` section in `mercury.yaml` → the registered default. This makes deployment-wide defaults work for auto-created spaces without any per-space setup.
+
 ### `mercury.widget(def)`
 
 Register a dashboard widget.
@@ -262,9 +266,38 @@ interface MercuryExtensionContext {
   readonly config: AppConfig; // Mercury configuration
   readonly log: Logger;      // Logger scoped to the extension
   hasCallerPermission(spaceId: string, callerId: string, permission: string): boolean;
+  getConfig(spaceId: string, key: string): string | null;
+  send(opts: { to: string; text: string }): Promise<{ spaceId: string }>;
 }
 ```
 
+### `ctx.send(opts)` — deterministic direct send
+
+Delivers a message straight to the adapter outbox — no agent run, no LLM in the path. Use it from jobs and capability handlers when the message text must arrive exactly as composed (reminders, notifications):
+
+```typescript
+mercury.job("appointment-reminders", {
+  cron: "*/15 * * * *",
+  run: async (ctx) => {
+    for (const r of dueReminders(ctx)) {
+      try {
+        await ctx.send({ to: r.callerId, text: r.text });
+      } catch (err) {
+        ctx.log.warn("reminder send failed — retrying next sweep", {
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  },
+});
+```
+
+`to` resolves callerId-first: an exact space id, a raw WhatsApp caller id (phone JID or opaque LID — same normalization that keys DM auto-spaces), a platform-qualified id (`whatsapp:123@lid`), or a phone with leading `+`. It never creates spaces — sending to someone without an existing conversation fails.
+
+Failures throw `DirectSendError` with a `reason` you can branch on: `sender_not_ready` (adapters not up yet, or the context has no delivery path — e.g. connection status probes), `unknown_recipient` (no existing space matches), `invalid_text` (empty or over 4096 chars).
+
+The same delivery path is exposed to ops scripts as `POST /api/send` (Bearer `MERCURY_API_SECRET`, global-admin caller, body `{ "recipient": "...", "text": "..." }`). Like `/api/broadcast`, it is host-side only — never member-callable from containers.
+
 ## Container Integration
 
 ### Skill Files

package/docs/media/overview.md

@@ -132,8 +132,12 @@ Check out this sunset!
 Voice and audio attachments are not playable inside pi. Install the **`voice-transcribe`** extension (see dashboard catalog or `examples/extensions/voice-transcribe/`) to append a text transcript before the agent runs.
 
 - **Default (`voice-transcribe.provider=local`)**: runs Python on the Mercury host; install deps from the extension’s `requirements.txt`. Set `voice-transcribe.local_engine` to `transformers` (default, e.g. [mike249/whisper-tiny-he-2](https://huggingface.co/mike249/whisper-tiny-he-2)) or `faster_whisper` for [CTranslate2](https://github.com/OpenNMT/CTranslate2) models on the Hub (e.g. [ivrit-ai](https://huggingface.co/ivrit-ai) `*-ct2` repos). See the extension skill for `MERCURY_VOICE_FW_COMPUTE_TYPE` and `MERCURY_VOICE_LANGUAGE`.
+- **OpenAI-compatible (`voice-transcribe.provider=openai`)**: cloud `POST /audio/transcriptions` with `MERCURY_STT_API_KEY` (host-only). Works with OpenAI (default) or Groq via `voice-transcribe.base_url=https://api.groq.com/openai/v1`. No Python/GPU on the host — best for small VPS deployments.
+- **Gemini (`voice-transcribe.provider=gemini`)**: Google Gemini audio understanding with `MERCURY_STT_GEMINI_API_KEY` (host-only, plain API key).
 - **API (`voice-transcribe.provider=api`)**: uses the [Hugging Face Inference API](https://huggingface.co/docs/api-inference) with `MERCURY_HF_TOKEN` — choose a model that has a Hub Inference Provider.
 
+Config keys resolve per space with deployment-wide fallbacks — see [Extension config defaults](../configuration.md#extension-config-defaults-extensions) for the `extensions:` YAML section and the dashboard `@global` scope.
+
 ## Future Enhancements
 
 - [ ] Video frame extraction

package/docs/media/whatsapp.md

@@ -155,7 +155,7 @@ Unknown MIME types default to `.bin`.
 
 1. **No re-download** — Media is downloaded once when the message arrives. If the file is deleted, it's gone.
 
-2. **No transcription** — Voice notes are saved as audio files. pi cannot play them. Future: add Whisper transcription.
+2. **No built-in transcription** — Voice notes are saved as audio files; pi cannot play them. Install the **voice-transcribe** extension (local Whisper or cloud OpenAI/Groq/Gemini) to prepend a text transcript — see [overview.md](overview.md#voice-transcription).
 
 3. **Reply context doesn't include file** — When replying to a media message, we include metadata but not the actual file path. The original attachment would need to be looked up.
 

package/examples/extensions/voice-transcribe/index.ts

@@ -13,6 +13,16 @@ const DEFAULT_PROVIDER = "local";
 const DEFAULT_LOCAL_ENGINE = "transformers";
 /** Classic HF Inference API (serverless). */
 const HF_INFERENCE_BASE = "https://api-inference.huggingface.co/models";
+/** OpenAI-compatible /audio/transcriptions root; override via base_url for Groq etc. */
+const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1";
+/** Sensible model when provider=openai and the configured model is not an OpenAI/Groq one. */
+const DEFAULT_OPENAI_MODEL = "gpt-4o-mini-transcribe";
+const GEMINI_API_BASE =
+  "https://generativelanguage.googleapis.com/v1beta/models";
+/** Sensible model when provider=gemini and the configured model is not a Gemini one. */
+const DEFAULT_GEMINI_MODEL = "gemini-2.5-flash";
+const PROVIDERS = ["local", "api", "openai", "gemini"] as const;
+type Provider = (typeof PROVIDERS)[number];
 
 const SCRIPT_PATH = path.join(
   path.dirname(fileURLToPath(import.meta.url)),
@@ -63,6 +73,95 @@ async function transcribeWithApi(
   return parseTranscriptionJson(raw);
 }
 
+/**
+ * OpenAI-compatible transcription (OpenAI, Groq, or any host implementing
+ * `POST {base}/audio/transcriptions`).
+ */
+async function transcribeWithOpenAi(
+  filePath: string,
+  mimeType: string,
+  modelId: string,
+  baseUrl: string,
+  language: string,
+  token: string,
+): Promise<string> {
+  const body = await readFile(filePath);
+  const form = new FormData();
+  form.append(
+    "file",
+    new Blob([body], { type: mimeType.split(";")[0].trim() || "audio/ogg" }),
+    path.basename(filePath) || "audio.ogg",
+  );
+  form.append("model", modelId);
+  form.append("response_format", "json");
+  if (language) form.append("language", language);
+
+  const url = `${baseUrl.replace(/\/+$/, "")}/audio/transcriptions`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}` },
+    body: form,
+  });
+  const raw = await res.text();
+  if (!res.ok) {
+    throw new Error(`OpenAI-compatible STT ${res.status}: ${raw.slice(0, 240)}`);
+  }
+  return parseTranscriptionJson(raw);
+}
+
+/** Gemini audio understanding via generateContent (API key, no GCP project). */
+async function transcribeWithGemini(
+  filePath: string,
+  mimeType: string,
+  modelId: string,
+  language: string,
+  apiKey: string,
+): Promise<string> {
+  const body = await readFile(filePath);
+  const langHint = language ? ` The audio language is "${language}".` : "";
+  const url = `${GEMINI_API_BASE}/${encodeURIComponent(modelId)}:generateContent`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "x-goog-api-key": apiKey,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      contents: [
+        {
+          parts: [
+            {
+              text: `Transcribe this audio verbatim.${langHint} Output only the transcript text, nothing else.`,
+            },
+            {
+              inline_data: {
+                mime_type: mimeType.split(";")[0].trim() || "audio/ogg",
+                data: body.toString("base64"),
+              },
+            },
+          ],
+        },
+      ],
+    }),
+  });
+  const raw = await res.text();
+  if (!res.ok) {
+    throw new Error(`Gemini STT ${res.status}: ${raw.slice(0, 240)}`);
+  }
+  try {
+    const data = JSON.parse(raw) as {
+      candidates?: Array<{ content?: { parts?: Array<{ text?: string }> } }>;
+    };
+    const parts = data.candidates?.[0]?.content?.parts ?? [];
+    return parts
+      .map((p) => p.text ?? "")
+      .join("")
+      .trim();
+  } catch {
+    return "";
+  }
+}
+
 function parseLastJsonLine(stdout: string): {
   text?: string;
   error?: string;
@@ -207,9 +306,33 @@ function localTimeoutMs(): number {
   return 300_000;
 }
 
+type HookCtx = {
+  db: { getSpaceConfig: (spaceId: string, key: string) => string | null };
+  log: {
+    info: (msg: string, extra?: unknown) => void;
+    warn: (msg: string, extra?: unknown) => void;
+    error: (msg: string, extra?: unknown) => void;
+  };
+  hasCallerPermission: (
+    spaceId: string,
+    callerId: string,
+    permission: string,
+  ) => boolean;
+  /** Host-resolved config (space → @global → mercury.yaml → default). Optional for older hosts. */
+  getConfig?: (spaceId: string, key: string) => string | null;
+};
+
+/** Resolve a config value via ctx.getConfig when the host supports it. */
+function readConfig(ctx: HookCtx, spaceId: string, key: string): string {
+  const resolved = ctx.getConfig
+    ? ctx.getConfig(spaceId, `${EXT}.${key}`)
+    : ctx.db.getSpaceConfig(spaceId, `${EXT}.${key}`);
+  return resolved?.trim() ?? "";
+}
+
 export default function (mercury: {
   permission(opts: { defaultRoles: string[] }): void;
-  env(def: { from: string }): void;
+  env(def: { from: string; hostOnly?: boolean }): void;
   config(
     key: string,
     def: {
@@ -230,33 +353,29 @@ export default function (mercury: {
         containerWorkspace: string;
         attachments?: Attachment[];
       },
-      ctx: {
-        db: { getSpaceConfig: (spaceId: string, key: string) => string | null };
-        log: {
-          info: (msg: string, extra?: unknown) => void;
-          warn: (msg: string, extra?: unknown) => void;
-          error: (msg: string, extra?: unknown) => void;
-        };
-        hasCallerPermission: (
-          spaceId: string,
-          callerId: string,
-          permission: string,
-        ) => boolean;
-      },
+      ctx: HookCtx,
     ) => Promise<{ promptAppend?: string } | undefined>,
   ): void;
 }) {
   mercury.permission({ defaultRoles: ["admin", "member"] });
-  mercury.env({ from: "MERCURY_HF_TOKEN" });
+  // All STT keys are consumed host-side in before_container — never inject
+  // them into agent containers (customers in DM auto-spaces hold the
+  // voice-transcribe permission).
+  mercury.env({ from: "MERCURY_HF_TOKEN", hostOnly: true });
+  // NOTE: MERCURY_GEMINI_API_KEY (model-chain key) is intentionally not
+  // reused — claiming it hostOnly would strip GEMINI_API_KEY from containers
+  // whose model chain runs on Gemini.
+  mercury.env({ from: "MERCURY_STT_API_KEY", hostOnly: true });
+  mercury.env({ from: "MERCURY_STT_GEMINI_API_KEY", hostOnly: true });
   mercury.config("provider", {
     description:
-      '"local" = Python+transformers on Mercury host (see skill); "api" = Hugging Face Inference API (needs MERCURY_HF_TOKEN)',
+      '"local" = Python+transformers on Mercury host (see skill); "api" = Hugging Face Inference API (MERCURY_HF_TOKEN); "openai" = OpenAI-compatible /audio/transcriptions incl. Groq (MERCURY_STT_API_KEY, see base_url); "gemini" = Google Gemini audio (MERCURY_STT_GEMINI_API_KEY)',
     default: DEFAULT_PROVIDER,
-    validate: (v) => v === "local" || v === "api",
+    validate: (v) => (PROVIDERS as readonly string[]).includes(v),
   });
   mercury.config("model", {
     description:
-      "Hugging Face model id (e.g. mike249/whisper-tiny-he-2 for local Hebrew; openai/whisper-large-v3 for api)",
+      "Model id per provider: HF id for local/api (e.g. mike249/whisper-tiny-he-2), e.g. gpt-4o-mini-transcribe or whisper-large-v3 for openai, gemini-2.5-flash for gemini",
     default: DEFAULT_MODEL,
   });
   mercury.config("local_engine", {
@@ -265,6 +384,17 @@ export default function (mercury: {
     default: DEFAULT_LOCAL_ENGINE,
     validate: (v) => v === "transformers" || v === "faster_whisper",
   });
+  mercury.config("base_url", {
+    description:
+      "openai provider only: API root implementing /audio/transcriptions (default OpenAI; use https://api.groq.com/openai/v1 for Groq)",
+    default: DEFAULT_OPENAI_BASE_URL,
+    validate: (v) => /^https:\/\//.test(v),
+  });
+  mercury.config("language", {
+    description:
+      'ISO-639-1 hint passed to cloud STT (e.g. "he"). Improves accuracy on short voice notes. Empty = auto-detect.',
+    default: "",
+  });
   mercury.skill("./skill");
 
   mercury.on("before_container", async (event, ctx) => {
@@ -277,19 +407,21 @@ export default function (mercury: {
     );
     if (!atts?.length) return undefined;
 
-    const provider =
-      ctx.db.getSpaceConfig(event.spaceId, `${EXT}.provider`)?.trim() ||
-      DEFAULT_PROVIDER;
-    const model =
-      ctx.db.getSpaceConfig(event.spaceId, `${EXT}.model`)?.trim() ||
-      DEFAULT_MODEL;
-    const rawLocalEngine = ctx.db
-      .getSpaceConfig(event.spaceId, `${EXT}.local_engine`)
-      ?.trim();
+    const providerRaw = readConfig(ctx, event.spaceId, "provider");
+    const provider: Provider = (PROVIDERS as readonly string[]).includes(
+      providerRaw,
+    )
+      ? (providerRaw as Provider)
+      : DEFAULT_PROVIDER;
+    const model = readConfig(ctx, event.spaceId, "model") || DEFAULT_MODEL;
+    const rawLocalEngine = readConfig(ctx, event.spaceId, "local_engine");
     const localEngine =
       rawLocalEngine === "faster_whisper" || rawLocalEngine === "transformers"
         ? rawLocalEngine
         : DEFAULT_LOCAL_ENGINE;
+    const baseUrl =
+      readConfig(ctx, event.spaceId, "base_url") || DEFAULT_OPENAI_BASE_URL;
+    const language = readConfig(ctx, event.spaceId, "language");
 
     let token: string | undefined;
     if (provider === "api") {
@@ -301,6 +433,24 @@ export default function (mercury: {
         );
         return undefined;
       }
+    } else if (provider === "openai") {
+      token = process.env.MERCURY_STT_API_KEY?.trim();
+      if (!token) {
+        ctx.log.warn(
+          "MERCURY_STT_API_KEY not set; skipping voice transcription (openai provider)",
+          { extension: EXT },
+        );
+        return undefined;
+      }
+    } else if (provider === "gemini") {
+      token = process.env.MERCURY_STT_GEMINI_API_KEY?.trim();
+      if (!token) {
+        ctx.log.warn(
+          "MERCURY_STT_GEMINI_API_KEY not set; skipping voice transcription (gemini provider)",
+          { extension: EXT },
+        );
+        return undefined;
+      }
     } else if (provider === "local") {
       if (!existsSync(SCRIPT_PATH)) {
         ctx.log.error("Local transcribe script missing", {
@@ -311,6 +461,18 @@ export default function (mercury: {
       }
     }
 
+    // The registered `model` default is an HF id for local/api. When the
+    // provider is cloud and the model was never changed from that default,
+    // use a provider-native model instead of sending the HF id upstream.
+    const cloudModel =
+      model !== DEFAULT_MODEL
+        ? model
+        : provider === "openai"
+          ? DEFAULT_OPENAI_MODEL
+          : provider === "gemini"
+            ? DEFAULT_GEMINI_MODEL
+            : model;
+
     const lines: string[] = [];
     const timeoutMs = localTimeoutMs();
     const pythonBin = defaultPython();
@@ -326,6 +488,23 @@ export default function (mercury: {
             model,
             token as string,
           );
+        } else if (provider === "openai") {
+          text = await transcribeWithOpenAi(
+            hostPath,
+            att.mimeType,
+            cloudModel,
+            baseUrl,
+            language,
+            token as string,
+          );
+        } else if (provider === "gemini") {
+          text = await transcribeWithGemini(
+            hostPath,
+            att.mimeType,
+            cloudModel,
+            language,
+            token as string,
+          );
         } else {
           ctx.log.info("Voice transcription starting (local)", {
             extension: EXT,

package/examples/extensions/voice-transcribe/skill/SKILL.md

@@ -1,19 +1,23 @@
 ---
 name: voice-transcribe
-description: Voice notes are transcribed to text before the agent runs (local Python or Hugging Face Inference API).
+description: Voice notes are transcribed to text before the agent runs (local Python, OpenAI-compatible cloud, Gemini, or Hugging Face Inference API).
 ---
 
 # Voice transcription
 
 When a user sends a **voice note** or **audio** attachment, Mercury runs the `voice-transcribe` extension **before** the container starts. The transcript is appended to the user message as a `[Voice transcript]` block. You receive normal text — you do not need to read or play audio files for intent.
 
-## Configuration (per space)
+## Configuration
+
+Keys resolve per space, then fall back to deployment-wide defaults (`@global` scope set from the dashboard Features page, or the `extensions:` section of `mercury.yaml`), then to the extension defaults.
 
 | Key | Purpose |
 |-----|---------|
-| `voice-transcribe.provider` | `local` (default) or `api` |
-| `voice-transcribe.model` | Hugging Face model id (see below) |
+| `voice-transcribe.provider` | `local` (default), `openai`, `gemini`, or `api` |
+| `voice-transcribe.model` | Model id for the chosen provider (see below) |
 | `voice-transcribe.local_engine` | Local only: `transformers` (default) or `faster_whisper` (CTranslate2 Hub repos) |
+| `voice-transcribe.base_url` | `openai` only: API root (default `https://api.openai.com/v1`; Groq: `https://api.groq.com/openai/v1`) |
+| `voice-transcribe.language` | Cloud providers: ISO-639-1 hint (e.g. `he`). Improves accuracy on short voice notes |
 
 ### Local provider (`local`)
 
@@ -44,6 +48,20 @@ Hub messages like *Xet Storage… hf_xet* are warnings only, not the cause of fa
 
 First run downloads the model into the Hugging Face cache (size depends on the model). **Each voice note spawns a new Python process**, so the first transcription after Mercury starts can be slow while the model loads (no in-process reuse yet).
 
+### OpenAI-compatible provider (`openai`)
+
+POSTs audio to `{base_url}/audio/transcriptions` (multipart). Requires `MERCURY_STT_API_KEY` on the host (the key never enters agent containers). Works with:
+
+- **OpenAI** (default `base_url`) — models `gpt-4o-mini-transcribe` (default), `gpt-4o-transcribe`, `whisper-1`
+- **Groq** — set `voice-transcribe.base_url=https://api.groq.com/openai/v1`, model `whisper-large-v3`
+- Any other host implementing the same endpoint
+
+No Python, ffmpeg, or GPU on the host — ideal for small VPS deployments. Set `voice-transcribe.language` (e.g. `he`) for better accuracy on short notes.
+
+### Gemini provider (`gemini`)
+
+Sends audio inline to the Gemini API (`generateContent`) with a transcription instruction. Requires `MERCURY_STT_GEMINI_API_KEY` on the host (a plain API key — no GCP project setup; deliberately separate from the model-chain `MERCURY_GEMINI_API_KEY`, which must keep flowing into containers). Default model `gemini-2.5-flash`. Also host-only, no local dependencies.
+
 ### API provider (`api`)
 
 POSTs audio to `https://api-inference.huggingface.co/models/<model>`. Requires `MERCURY_HF_TOKEN` on the host. Pick a model that has an [Inference Provider](https://huggingface.co/docs/api-inference) on its Hub page (e.g. `openai/whisper-large-v3`). Hebrew-tuned models such as [mike249/whisper-tiny-he-2](https://huggingface.co/mike249/whisper-tiny-he-2) often have **no** hosted provider — use **`local`** for those. CT2 / Faster-Whisper Hub repos are for the **local** engine only, not this API.

package/package.json

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

package/resources/templates/AGENTS.md

@@ -2,24 +2,6 @@
 
 You are a helpful AI assistant running inside a chat platform (WhatsApp, Slack, or Discord).
 
-## Destructive Operations — Confirmation Required
-
-Before deleting, trashing, or permanently removing any data, you MUST stop and confirm with the user first:
-
-1. **List exactly what will be affected** — names, count, and location
-2. **Ask explicitly** — e.g. "This will permanently delete 12 files from your Google Drive. Reply YES to confirm."
-3. **Wait for an unambiguous "yes"** — do not proceed until you have it
-
-This applies to **all personal data**, regardless of where it lives:
-- Connected accounts: Google Drive, Gmail, Google Photos, Yahoo Mail, and any other connected service
-- Filesystem: any `rm`, `rmdir`, file deletion, or bulk removal from the user's files
-
-**Always prefer the reversible option** — move to trash instead of permanent delete, archive instead of delete, move to a folder instead of remove. If the user hasn't explicitly asked for permanent deletion, choose the reversible path by default.
-
-**Exception**: temp files the agent created during the current task (e.g., scratch files in `/tmp`) may be cleaned up without confirmation.
-
-This rule applies even when the request implies deletion (e.g., "clean up", "organize", "clear out", "remove duplicates"). When in doubt, ask.
-
 ## Guidelines
 
 1. **Be concise** — Chat messages should be readable on mobile
@@ -32,18 +14,6 @@ This rule applies even when the request implies deletion (e.g., "clean up", "org
 - Running in a container with limited resources
 - Long-running tasks may time out
 
-## Presenting tool results
-
-After running any command or tool, never send raw output to the user. Always translate into plain conversational language before responding.
-
-- **Names only** — show the human-readable name; never show file IDs, message IDs, or thread IDs
-- **Plain types** — say "Google Doc", "spreadsheet", "folder", "PDF"; never show MIME type strings
-- **Simple lists** — numbered or bulleted with name + one-word type hint; no tables of raw fields
-- **Errors** — explain what went wrong in plain terms; never show exit codes, stack traces, or raw error strings
-- **Never show** — JSON blobs, bash code blocks, command flags, or API parameter objects in replies
-
-This rule applies to all tools: Google Workspace, TradeStation, web search, and any future extension.
-
 ## Mercury Control (mrctl)
 
 Full command reference for managing Mercury from inside the container:

package/resources/templates/env.template

@@ -5,6 +5,8 @@ MERCURY_ANTHROPIC_API_KEY=
 # MERCURY_GEMINI_API_KEY=
 # MERCURY_GROQ_API_KEY=
 # MERCURY_HF_TOKEN=   # Hugging Face token (voice-transcribe.provider=api only)
+# MERCURY_STT_API_KEY=   # OpenAI/Groq key for voice-transcribe.provider=openai (host-only, never enters containers)
+# MERCURY_STT_GEMINI_API_KEY=   # Gemini key for voice-transcribe.provider=gemini (host-only)
 # MERCURY_VOICE_PYTHON=   # Optional: python exe for voice-transcribe.provider=local
 # MERCURY_VOICE_TRANSCRIBE_TIMEOUT_MS=300000
 

package/resources/templates/mercury.example.yaml

@@ -83,6 +83,16 @@
 #   default_system_prompt: ""                   # seeded into auto-created user spaces
 #   default_member_permissions: "prompt,prefs.get"  # restrict users to chat only
 
+# ─── Extension config defaults ──────────────────────────────────────────────
+# Deployment-wide defaults for extension config keys, applied to every space
+# (incl. auto-created DM spaces) unless overridden per-space or in the
+# dashboard's global scope. See docs/configuration.md.
+# extensions:
+#   voice-transcribe:
+#     provider: openai            # local | api | openai | gemini
+#     model: gpt-4o-mini-transcribe
+#     language: he
+
 # ─── Applicative profile ────────────────────────────────────────────────────
 # A profile wraps raw capabilities with deterministic business logic and scopes
 # what members may do. Apply one with `mercury profile apply <name|path|git-url>`