mercury-agent 0.5.0 → 0.5.2

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

@@ -1,38 +1,38 @@
----
-name: voice-synth
-description: Cloud text-to-speech (Google or Azure) for English and Hebrew — on-demand via mrctl or optional auto voice attachments per space.
----
-
-# Voice synthesis (TTS)
-
-**`mrctl tts synthesize` is available in this environment.** When the user asks for a voice message, audio reply, or TTS, you MUST run the command below. Do not assume it is unavailable — always try it and report any error verbatim.
-
-**Do not paste** `mrctl`, shell snippets, or JSON tool-call blobs into your **visible** reply — use the **bash tool** only for the command. The user sees normal text plus the audio attachment.
-
-## How to send a voice message
-
-```bash
-mrctl tts synthesize --text "Your spoken reply here" --out outbox/reply.mp3
-```
-
-This writes an MP3 file to `outbox/` which Mercury automatically attaches to your reply. Do **not** create `.txt` files or use misleading names — chat apps decide how to render attachments from the file extension and MIME type.
-
-Optional flags:
-
-- `--language` — `auto` (default), `he-IL`, or `en-US`. `auto` picks Hebrew if the text contains Hebrew script.
-- `--provider` — `google`, `azure`, or `auto` (host default).
-
-Requires the caller to have **`tts.synthesize`** permission (admins have it by default).
-
-### Telegram / WhatsApp delivery
-
-**Telegram** uses `sendAudio` for MP3 (in-chat player) and `sendVoice` for OGG voice notes. **WhatsApp** treats audio as a voice note when the filename matches **`voice-*.ogg`** (case-insensitive); otherwise it sends as normal audio (`ptt: false`).
-
-## Automatic mode (optional)
-
-| Setting | Behavior |
-|--------|----------|
-| **`voice-synth.mode=on_demand`** (default) | TTS runs only when you call `mrctl tts synthesize`. |
-| **`voice-synth.mode=auto`** | The host attaches a TTS MP3 to every assistant reply automatically. |
-
-Set with `mrctl config set voice-synth.mode on_demand` or `auto`.
+---
+name: voice-synth
+description: Cloud text-to-speech (Google or Azure) for English and Hebrew — on-demand via mrctl or optional auto voice attachments per space.
+---
+
+# Voice synthesis (TTS)
+
+**`mrctl tts synthesize` is available in this environment.** When the user asks for a voice message, audio reply, or TTS, you MUST run the command below. Do not assume it is unavailable — always try it and report any error verbatim.
+
+**Do not paste** `mrctl`, shell snippets, or JSON tool-call blobs into your **visible** reply — use the **bash tool** only for the command. The user sees normal text plus the audio attachment.
+
+## How to send a voice message
+
+```bash
+mrctl tts synthesize --text "Your spoken reply here" --out outbox/reply.mp3
+```
+
+This writes an MP3 file to `outbox/` which Mercury automatically attaches to your reply. Do **not** create `.txt` files or use misleading names — chat apps decide how to render attachments from the file extension and MIME type.
+
+Optional flags:
+
+- `--language` — `auto` (default), `he-IL`, or `en-US`. `auto` picks Hebrew if the text contains Hebrew script.
+- `--provider` — `google`, `azure`, or `auto` (host default).
+
+Requires the caller to have **`tts.synthesize`** permission (admins have it by default).
+
+### Telegram / WhatsApp delivery
+
+**Telegram** uses `sendAudio` for MP3 (in-chat player) and `sendVoice` for OGG voice notes. **WhatsApp** treats audio as a voice note when the filename matches **`voice-*.ogg`** (case-insensitive); otherwise it sends as normal audio (`ptt: false`).
+
+## Automatic mode (optional)
+
+| Setting | Behavior |
+|--------|----------|
+| **`voice-synth.mode=on_demand`** (default) | TTS runs only when you call `mrctl tts synthesize`. |
+| **`voice-synth.mode=auto`** | The host attaches a TTS MP3 to every assistant reply automatically. |
+
+Set with `mrctl config set voice-synth.mode on_demand` or `auto`.

package/examples/extensions/voice-transcribe/requirements.txt

@@ -1,8 +1,8 @@
-# Local transcription (voice-transcribe.provider=local). Install on the Mercury host:
-#   pip install -r requirements.txt
-transformers>=4.40.0
-torch>=2.0.0
-# Optional local engine when voice-transcribe.local_engine=faster_whisper (CTranslate2 models on Hub).
-faster-whisper>=1.0.0
-# Ships a platform ffmpeg binary when the `ffmpeg` command is missing (Telegram .ogg / Opus).
-imageio-ffmpeg>=0.4.9
+# Local transcription (voice-transcribe.provider=local). Install on the Mercury host:
+#   pip install -r requirements.txt
+transformers>=4.40.0
+torch>=2.0.0
+# Optional local engine when voice-transcribe.local_engine=faster_whisper (CTranslate2 models on Hub).
+faster-whisper>=1.0.0
+# Ships a platform ffmpeg binary when the `ffmpeg` command is missing (Telegram .ogg / Opus).
+imageio-ffmpeg>=0.4.9

package/examples/extensions/voice-transcribe/scripts/transcribe.py

@@ -1,179 +1,179 @@
-#!/usr/bin/env python3
-"""Transcribe a single audio file; print one JSON line to stdout: {\"text\":\"...\"} or {\"error\":\"...\"}."""
-
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import shutil
-import sys
-import tempfile
-
-
-def _ensure_ffmpeg_on_path() -> None:
-    """
-    Transformers and faster-whisper decode via ffmpeg on PATH.
-    imageio-ffmpeg ships a versioned .exe (e.g. ffmpeg-win-x86_64-v7.1.exe). On Windows,
-    Popen([...]) without shell=True will not run a .bat shim — it needs a real `ffmpeg.exe`
-    on PATH. We hardlink (or copy) the vendored binary to `<temp>/mercury-voice-ffmpeg/ffmpeg.exe`.
-    """
-    if shutil.which("ffmpeg"):
-        return
-    try:
-        import imageio_ffmpeg
-    except ImportError:
-        return
-    src = imageio_ffmpeg.get_ffmpeg_exe()
-    if not src or not os.path.isfile(src):
-        return
-
-    shim_root = os.path.join(tempfile.gettempdir(), "mercury-voice-ffmpeg")
-    os.makedirs(shim_root, exist_ok=True)
-    dst = os.path.join(shim_root, "ffmpeg.exe" if sys.platform == "win32" else "ffmpeg")
-
-    if not os.path.exists(dst):
-        try:
-            os.link(src, dst)
-        except OSError:
-            try:
-                shutil.copy2(src, dst)
-            except OSError:
-                return
-    elif sys.platform != "win32":
-        try:
-            os.chmod(dst, 0o755)
-        except OSError:
-            pass
-
-    os.environ["PATH"] = f"{shim_root}{os.pathsep}{os.environ.get('PATH', '')}"
-
-
-def _asr_device_torch():
-    """Resolve torch device for Transformers. Env: MERCURY_VOICE_ASR_DEVICE=cpu|cuda|auto (default auto)."""
-    import torch
-
-    raw = (os.environ.get("MERCURY_VOICE_ASR_DEVICE") or "").strip().lower()
-    if not raw or raw == "auto":
-        # Windows often reports CUDA but inference fails (drivers, OOM); CPU is the reliable default.
-        if sys.platform == "win32":
-            raw = "cpu"
-        else:
-            raw = "cuda" if torch.cuda.is_available() else "cpu"
-    if raw in ("cpu", "-1"):
-        return torch.device("cpu")
-    if raw in ("cuda", "gpu", "cuda:0", "0"):
-        if torch.cuda.is_available():
-            return torch.device("cuda:0")
-        return torch.device("cpu")
-    return torch.device("cpu")
-
-
-def _cuda_available() -> bool:
-    try:
-        import torch
-
-        return bool(torch.cuda.is_available())
-    except ImportError:
-        return False
-
-
-def _fw_device_str() -> str:
-    """faster-whisper device string: cpu | cuda. Same MERCURY_VOICE_ASR_DEVICE semantics as Transformers."""
-    raw = (os.environ.get("MERCURY_VOICE_ASR_DEVICE") or "").strip().lower()
-    if not raw or raw == "auto":
-        if sys.platform == "win32":
-            return "cpu"
-        return "cuda" if _cuda_available() else "cpu"
-    if raw in ("cpu", "-1"):
-        return "cpu"
-    if raw in ("cuda", "gpu", "cuda:0", "0"):
-        return "cuda" if _cuda_available() else "cpu"
-    return "cpu"
-
-
-def _fw_compute_type(device: str) -> str:
-    override = (os.environ.get("MERCURY_VOICE_FW_COMPUTE_TYPE") or "").strip()
-    if override:
-        return override
-    return "int8" if device == "cuda" else "float32"
-
-
-def _fw_language() -> str | None:
-    lang = (os.environ.get("MERCURY_VOICE_LANGUAGE") or "").strip()
-    return lang if lang else None
-
-
-def _run_transformers(audio_path: str, model_id: str) -> str:
-    try:
-        from transformers import pipeline
-    except ImportError as e:
-        raise ImportError(f"transformers import failed: {e}") from e
-
-    _ensure_ffmpeg_on_path()
-    device = _asr_device_torch()
-    pipe = pipeline(
-        "automatic-speech-recognition",
-        model=model_id,
-        device=device,
-    )
-    result = pipe(audio_path, return_timestamps=True)
-    if isinstance(result, dict):
-        return (result.get("text") or "").strip()
-    return str(result).strip()
-
-
-def _run_faster_whisper(audio_path: str, model_id: str) -> str:
-    try:
-        from faster_whisper import WhisperModel
-    except ImportError as e:
-        raise ImportError(
-            "faster-whisper is required when local_engine=faster_whisper. "
-            "Install: pip install faster-whisper"
-        ) from e
-
-    _ensure_ffmpeg_on_path()
-    device = _fw_device_str()
-    compute_type = _fw_compute_type(device)
-    lang = _fw_language()
-
-    model = WhisperModel(model_id, device=device, compute_type=compute_type)
-    kwargs: dict = {}
-    if lang:
-        kwargs["language"] = lang
-    segments, _info = model.transcribe(audio_path, **kwargs)
-    parts: list[str] = []
-    for seg in segments:
-        parts.append(seg.text)
-    return "".join(parts).strip()
-
-
-def main() -> None:
-    ap = argparse.ArgumentParser(description="ASR for Mercury voice-transcribe (local provider)")
-    ap.add_argument("--audio", required=True, help="Path to audio file on disk")
-    ap.add_argument("--model", required=True, help="Hugging Face model id")
-    ap.add_argument(
-        "--local-engine",
-        choices=("transformers", "faster_whisper"),
-        default="transformers",
-        help="Local ASR backend (default: transformers)",
-    )
-    args = ap.parse_args()
-
-    try:
-        if args.local_engine == "faster_whisper":
-            text = _run_faster_whisper(args.audio, args.model)
-        else:
-            text = _run_transformers(args.audio, args.model)
-    except ImportError as e:
-        print(json.dumps({"error": str(e)}))
-        sys.exit(2)
-    except Exception as e:
-        print(json.dumps({"error": str(e)}))
-        sys.exit(1)
-
-    print(json.dumps({"text": text}))
-
-
-if __name__ == "__main__":
-    main()
+#!/usr/bin/env python3
+"""Transcribe a single audio file; print one JSON line to stdout: {\"text\":\"...\"} or {\"error\":\"...\"}."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sys
+import tempfile
+
+
+def _ensure_ffmpeg_on_path() -> None:
+    """
+    Transformers and faster-whisper decode via ffmpeg on PATH.
+    imageio-ffmpeg ships a versioned .exe (e.g. ffmpeg-win-x86_64-v7.1.exe). On Windows,
+    Popen([...]) without shell=True will not run a .bat shim — it needs a real `ffmpeg.exe`
+    on PATH. We hardlink (or copy) the vendored binary to `<temp>/mercury-voice-ffmpeg/ffmpeg.exe`.
+    """
+    if shutil.which("ffmpeg"):
+        return
+    try:
+        import imageio_ffmpeg
+    except ImportError:
+        return
+    src = imageio_ffmpeg.get_ffmpeg_exe()
+    if not src or not os.path.isfile(src):
+        return
+
+    shim_root = os.path.join(tempfile.gettempdir(), "mercury-voice-ffmpeg")
+    os.makedirs(shim_root, exist_ok=True)
+    dst = os.path.join(shim_root, "ffmpeg.exe" if sys.platform == "win32" else "ffmpeg")
+
+    if not os.path.exists(dst):
+        try:
+            os.link(src, dst)
+        except OSError:
+            try:
+                shutil.copy2(src, dst)
+            except OSError:
+                return
+    elif sys.platform != "win32":
+        try:
+            os.chmod(dst, 0o755)
+        except OSError:
+            pass
+
+    os.environ["PATH"] = f"{shim_root}{os.pathsep}{os.environ.get('PATH', '')}"
+
+
+def _asr_device_torch():
+    """Resolve torch device for Transformers. Env: MERCURY_VOICE_ASR_DEVICE=cpu|cuda|auto (default auto)."""
+    import torch
+
+    raw = (os.environ.get("MERCURY_VOICE_ASR_DEVICE") or "").strip().lower()
+    if not raw or raw == "auto":
+        # Windows often reports CUDA but inference fails (drivers, OOM); CPU is the reliable default.
+        if sys.platform == "win32":
+            raw = "cpu"
+        else:
+            raw = "cuda" if torch.cuda.is_available() else "cpu"
+    if raw in ("cpu", "-1"):
+        return torch.device("cpu")
+    if raw in ("cuda", "gpu", "cuda:0", "0"):
+        if torch.cuda.is_available():
+            return torch.device("cuda:0")
+        return torch.device("cpu")
+    return torch.device("cpu")
+
+
+def _cuda_available() -> bool:
+    try:
+        import torch
+
+        return bool(torch.cuda.is_available())
+    except ImportError:
+        return False
+
+
+def _fw_device_str() -> str:
+    """faster-whisper device string: cpu | cuda. Same MERCURY_VOICE_ASR_DEVICE semantics as Transformers."""
+    raw = (os.environ.get("MERCURY_VOICE_ASR_DEVICE") or "").strip().lower()
+    if not raw or raw == "auto":
+        if sys.platform == "win32":
+            return "cpu"
+        return "cuda" if _cuda_available() else "cpu"
+    if raw in ("cpu", "-1"):
+        return "cpu"
+    if raw in ("cuda", "gpu", "cuda:0", "0"):
+        return "cuda" if _cuda_available() else "cpu"
+    return "cpu"
+
+
+def _fw_compute_type(device: str) -> str:
+    override = (os.environ.get("MERCURY_VOICE_FW_COMPUTE_TYPE") or "").strip()
+    if override:
+        return override
+    return "int8" if device == "cuda" else "float32"
+
+
+def _fw_language() -> str | None:
+    lang = (os.environ.get("MERCURY_VOICE_LANGUAGE") or "").strip()
+    return lang if lang else None
+
+
+def _run_transformers(audio_path: str, model_id: str) -> str:
+    try:
+        from transformers import pipeline
+    except ImportError as e:
+        raise ImportError(f"transformers import failed: {e}") from e
+
+    _ensure_ffmpeg_on_path()
+    device = _asr_device_torch()
+    pipe = pipeline(
+        "automatic-speech-recognition",
+        model=model_id,
+        device=device,
+    )
+    result = pipe(audio_path, return_timestamps=True)
+    if isinstance(result, dict):
+        return (result.get("text") or "").strip()
+    return str(result).strip()
+
+
+def _run_faster_whisper(audio_path: str, model_id: str) -> str:
+    try:
+        from faster_whisper import WhisperModel
+    except ImportError as e:
+        raise ImportError(
+            "faster-whisper is required when local_engine=faster_whisper. "
+            "Install: pip install faster-whisper"
+        ) from e
+
+    _ensure_ffmpeg_on_path()
+    device = _fw_device_str()
+    compute_type = _fw_compute_type(device)
+    lang = _fw_language()
+
+    model = WhisperModel(model_id, device=device, compute_type=compute_type)
+    kwargs: dict = {}
+    if lang:
+        kwargs["language"] = lang
+    segments, _info = model.transcribe(audio_path, **kwargs)
+    parts: list[str] = []
+    for seg in segments:
+        parts.append(seg.text)
+    return "".join(parts).strip()
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="ASR for Mercury voice-transcribe (local provider)")
+    ap.add_argument("--audio", required=True, help="Path to audio file on disk")
+    ap.add_argument("--model", required=True, help="Hugging Face model id")
+    ap.add_argument(
+        "--local-engine",
+        choices=("transformers", "faster_whisper"),
+        default="transformers",
+        help="Local ASR backend (default: transformers)",
+    )
+    args = ap.parse_args()
+
+    try:
+        if args.local_engine == "faster_whisper":
+            text = _run_faster_whisper(args.audio, args.model)
+        else:
+            text = _run_transformers(args.audio, args.model)
+    except ImportError as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(2)
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+    print(json.dumps({"text": text}))
+
+
+if __name__ == "__main__":
+    main()

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

@@ -1,53 +1,53 @@
----
-name: voice-transcribe
-description: Voice notes are transcribed to text before the agent runs (local Python 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)
-
-| Key | Purpose |
-|-----|---------|
-| `voice-transcribe.provider` | `local` (default) or `api` |
-| `voice-transcribe.model` | Hugging Face model id (see below) |
-| `voice-transcribe.local_engine` | Local only: `transformers` (default) or `faster_whisper` (CTranslate2 Hub repos) |
-
-### Local provider (`local`)
-
-Runs `scripts/transcribe.py` on the **Mercury host**.
-
-**Transformers (default)** — `voice-transcribe.local_engine=transformers` uses [Transformers](https://huggingface.co/docs/transformers) `pipeline("automatic-speech-recognition", model=...)`. Use standard PyTorch Whisper / compatible Hub ids (e.g. [mike249/whisper-tiny-he-2](https://huggingface.co/mike249/whisper-tiny-he-2)).
-
-**Faster-Whisper** — set `voice-transcribe.local_engine=faster_whisper` and [faster-whisper](https://github.com/SYSTRAN/faster-whisper) loads **CTranslate2** checkpoints from the Hub. Set `voice-transcribe.model` to a **CT2** repo (not plain PyTorch Whisper weights). Examples for Hebrew: [ivrit-ai/faster-whisper-v2-d4](https://huggingface.co/ivrit-ai/faster-whisper-v2-d4), [ivrit-ai/whisper-large-v3-turbo-ct2](https://huggingface.co/ivrit-ai/whisper-large-v3-turbo-ct2).
-
-1. Install on the same machine that runs Mercury:
-
-   ```bash
-   pip install -r /path/to/.mercury/extensions/voice-transcribe/requirements.txt
-   ```
-
-   Or: `pip install "transformers>=4.40.0" "torch>=2.0.0" "faster-whisper>=1.0.0" "imageio-ffmpeg>=0.4.9"`
-
-   **Telegram voice** is usually `.ogg` (Opus). Both backends shell out to an executable named `ffmpeg`; `transcribe.py` uses `imageio-ffmpeg`’s binary and exposes it as `ffmpeg` / `ffmpeg.exe` on `PATH` (hardlink or copy under `%TEMP%\\mercury-voice-ffmpeg` on Windows). Installing system ffmpeg on `PATH` also works (e.g. `winget install Gyan.FFmpeg`).
-
-2. Optional host `.env`:
-   - `MERCURY_VOICE_PYTHON` — Python executable (default: `python` on Windows, `python3` elsewhere)
-   - `MERCURY_VOICE_TRANSCRIBE_TIMEOUT_MS` — subprocess timeout in ms (default `300000`)
-   - `MERCURY_VOICE_ASR_DEVICE` — `cpu`, `cuda`, or `auto`. Used by **both** local engines. On Windows the default is **CPU** (CUDA often looks available but fails at inference). Set `cuda` if you have a working GPU stack.
-   - `MERCURY_VOICE_FW_COMPUTE_TYPE` — **Faster-Whisper only**: e.g. `int8`, `float16`, `float32`. If unset: `int8` on CUDA, `float32` on CPU.
-   - `MERCURY_VOICE_LANGUAGE` — **Faster-Whisper only**: ISO code passed to `transcribe(..., language=...)` (e.g. `he`). If unset, language is auto-detected.
-
-Hub messages like *Xet Storage… hf_xet* are warnings only, not the cause of failures.
-
-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).
-
-### 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.
-
-## RBAC
-
-Only callers with the `voice-transcribe` permission (default: admin + member) get transcription. Others keep the raw message without an appended transcript.
+---
+name: voice-transcribe
+description: Voice notes are transcribed to text before the agent runs (local Python 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)
+
+| Key | Purpose |
+|-----|---------|
+| `voice-transcribe.provider` | `local` (default) or `api` |
+| `voice-transcribe.model` | Hugging Face model id (see below) |
+| `voice-transcribe.local_engine` | Local only: `transformers` (default) or `faster_whisper` (CTranslate2 Hub repos) |
+
+### Local provider (`local`)
+
+Runs `scripts/transcribe.py` on the **Mercury host**.
+
+**Transformers (default)** — `voice-transcribe.local_engine=transformers` uses [Transformers](https://huggingface.co/docs/transformers) `pipeline("automatic-speech-recognition", model=...)`. Use standard PyTorch Whisper / compatible Hub ids (e.g. [mike249/whisper-tiny-he-2](https://huggingface.co/mike249/whisper-tiny-he-2)).
+
+**Faster-Whisper** — set `voice-transcribe.local_engine=faster_whisper` and [faster-whisper](https://github.com/SYSTRAN/faster-whisper) loads **CTranslate2** checkpoints from the Hub. Set `voice-transcribe.model` to a **CT2** repo (not plain PyTorch Whisper weights). Examples for Hebrew: [ivrit-ai/faster-whisper-v2-d4](https://huggingface.co/ivrit-ai/faster-whisper-v2-d4), [ivrit-ai/whisper-large-v3-turbo-ct2](https://huggingface.co/ivrit-ai/whisper-large-v3-turbo-ct2).
+
+1. Install on the same machine that runs Mercury:
+
+   ```bash
+   pip install -r /path/to/.mercury/extensions/voice-transcribe/requirements.txt
+   ```
+
+   Or: `pip install "transformers>=4.40.0" "torch>=2.0.0" "faster-whisper>=1.0.0" "imageio-ffmpeg>=0.4.9"`
+
+   **Telegram voice** is usually `.ogg` (Opus). Both backends shell out to an executable named `ffmpeg`; `transcribe.py` uses `imageio-ffmpeg`’s binary and exposes it as `ffmpeg` / `ffmpeg.exe` on `PATH` (hardlink or copy under `%TEMP%\\mercury-voice-ffmpeg` on Windows). Installing system ffmpeg on `PATH` also works (e.g. `winget install Gyan.FFmpeg`).
+
+2. Optional host `.env`:
+   - `MERCURY_VOICE_PYTHON` — Python executable (default: `python` on Windows, `python3` elsewhere)
+   - `MERCURY_VOICE_TRANSCRIBE_TIMEOUT_MS` — subprocess timeout in ms (default `300000`)
+   - `MERCURY_VOICE_ASR_DEVICE` — `cpu`, `cuda`, or `auto`. Used by **both** local engines. On Windows the default is **CPU** (CUDA often looks available but fails at inference). Set `cuda` if you have a working GPU stack.
+   - `MERCURY_VOICE_FW_COMPUTE_TYPE` — **Faster-Whisper only**: e.g. `int8`, `float16`, `float32`. If unset: `int8` on CUDA, `float32` on CPU.
+   - `MERCURY_VOICE_LANGUAGE` — **Faster-Whisper only**: ISO code passed to `transcribe(..., language=...)` (e.g. `he`). If unset, language is auto-detected.
+
+Hub messages like *Xet Storage… hf_xet* are warnings only, not the cause of failures.
+
+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).
+
+### 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.
+
+## RBAC
+
+Only callers with the `voice-transcribe` permission (default: admin + member) get transcription. Others keep the raw message without an appended transcript.

package/examples/extensions/yahoo-mail/cli/package.json

@@ -1,13 +1,13 @@
-{
-  "name": "ymail",
-  "version": "1.0.0",
-  "private": true,
-  "type": "module",
-  "bin": {
-    "ymail": "./ymail.mjs"
-  },
-  "dependencies": {
-    "imapflow": "^1.0.171",
-    "nodemailer": "^8.0.5"
-  }
-}
+{
+  "name": "ymail",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "bin": {
+    "ymail": "./ymail.mjs"
+  },
+  "dependencies": {
+    "imapflow": "^1.0.171",
+    "nodemailer": "^8.0.5"
+  }
+}