fix: harden message aborts + bluebubbles dm create (#1751 ) (thanks @tyler6204)

fix(bluebubbles): preserve friendly display names in formatTargetDisplay
fix: prevent cross-context decoration on direct message tool sends
2026-01-25 10:02:41 +00:00 · 2026-01-25 09:47:57 +00:00 · 2026-01-25 09:47:57 +00:00 · 2026-01-25 09:47:57 +00:00 · 2026-01-25 09:47:57 +00:00 · 2026-01-25 09:47:57 +00:00
67 changed files with 2215 additions and 263 deletions
@@ -14,17 +14,21 @@ Docs: https://docs.clawd.bot
 - TTS: add auto mode enum (off/always/inbound/tagged) with per-session `/tts` override. (#1667) Thanks @sebslight. https://docs.clawd.bot/tts
 - Docs: expand FAQ (migration, scheduling, concurrency, model recommendations, OpenAI subscription auth, Pi sizing, hackable install, docs SSL workaround).
 - Docs: add verbose installer troubleshooting guidance.
+- Docs: add macOS VM guide with local/hosted options + VPS/nodes guidance. (#1693) Thanks @f-trycua.
 - Docs: update Fly.io guide notes.
 - Docs: add Bedrock EC2 instance role setup + IAM steps. (#1625) Thanks @sergical. https://docs.clawd.bot/bedrock
 - Exec approvals: forward approval prompts to chat with `/approve` for all channels (including plugins). (#1621) Thanks @czekaj. https://docs.clawd.bot/tools/exec-approvals https://docs.clawd.bot/tools/slash-commands
 - Gateway: expose config.patch in the gateway tool with safe partial updates + restart sentinel. (#1653) Thanks @Glucksberg.
+- Telegram: add `channels.telegram.linkPreview` to toggle outbound link previews. (#1700) Thanks @zerone0x. https://docs.clawd.bot/channels/telegram
 - Telegram: treat DM topics as separate sessions and keep DM history limits stable with thread suffixes. (#1597) Thanks @rohannagpal.
 - Telegram: add verbose raw-update logging for inbound Telegram updates. (#1597) Thanks @rohannagpal.

 ### Fixes
+- BlueBubbles: route phone-number targets to DMs, avoid leaking routing IDs, and auto-create missing DMs (Private API required). (#1751) Thanks @tyler6204. https://docs.clawd.bot/channels/bluebubbles
 - BlueBubbles: keep part-index GUIDs in reply tags when short IDs are missing.
 - Web UI: hide internal `message_id` hints in chat bubbles.
 - Web UI: show Stop button during active runs, swap back to New session when idle. (#1664) Thanks @ndbroadbent.
+- Web UI: clear stale disconnect banners on reconnect; allow form saves with unsupported schema paths but block missing schema. (#1707) Thanks @Glucksberg.
 - Heartbeat: normalize target identifiers for consistent routing.
 - TUI: reload history after gateway reconnect to restore session state. (#1663)
 - Telegram: use wrapped fetch for long-polling on Node to normalize AbortSignal handling. (#1639)
@@ -38,6 +42,8 @@ Docs: https://docs.clawd.bot
 - Gateway: skip Tailscale DNS probing when tailscale.mode is off. (#1671)
 - Gateway: reduce log noise for late invokes + remote node probes; debounce skills refresh. (#1607) Thanks @petter-b.
 - Gateway: clarify Control UI/WebChat auth error hints for missing tokens. (#1690)
+- Gateway: listen on IPv6 loopback when bound to 127.0.0.1 so localhost webhooks work.
+- Gateway: store lock files in the temp directory to avoid stale locks on persistent volumes. (#1676)
 - macOS: default direct-transport `ws://` URLs to port 18789; document `gateway.remote.transport`. (#1603) Thanks @ngutman.
 - Voice Call: return stream TwiML for outbound conversation calls on initial Twilio webhook. (#1634)
 - Google Chat: tighten email allowlist matching, typing cleanup, media caps, and onboarding/docs/tests. (#1635) Thanks @iHildy.
@@ -213,6 +213,7 @@ Prefer `chat_guid` for stable routing:
 - `chat_id:123`
 - `chat_identifier:...`
 - Direct handles: `+15555550123`, `user@example.com`
+  - If a direct handle does not have an existing DM chat, Clawdbot will create one via `POST /api/v1/chat/new`. This requires the BlueBubbles Private API to be enabled.

 ## Security
 - Webhook requests are authenticated by comparing `guid`/`password` query params or headers against `channels.bluebubbles.password`. Requests from `localhost` are also accepted.
@@ -17,7 +17,7 @@ read_when:
 - **Proxy:** optional `channels.telegram.proxy` uses `undici.ProxyAgent` through grammY’s `client.baseFetch`.
 - **Webhook support:** `webhook-set.ts` wraps `setWebhook/deleteWebhook`; `webhook.ts` hosts the callback with health + graceful shutdown. Gateway enables webhook mode when `channels.telegram.webhookUrl` is set (otherwise it long-polls).
 - **Sessions:** direct chats collapse into the agent main session (`agent:<agentId>:<mainKey>`); groups use `agent:<agentId>:telegram:group:<chatId>`; replies route back to the same channel.
- **Config knobs:** `channels.telegram.botToken`, `channels.telegram.dmPolicy`, `channels.telegram.groups` (allowlist + mention defaults), `channels.telegram.allowFrom`, `channels.telegram.groupAllowFrom`, `channels.telegram.groupPolicy`, `channels.telegram.mediaMaxMb`, `channels.telegram.proxy`, `channels.telegram.webhookSecret`, `channels.telegram.webhookUrl`.
+- **Config knobs:** `channels.telegram.botToken`, `channels.telegram.dmPolicy`, `channels.telegram.groups` (allowlist + mention defaults), `channels.telegram.allowFrom`, `channels.telegram.groupAllowFrom`, `channels.telegram.groupPolicy`, `channels.telegram.mediaMaxMb`, `channels.telegram.linkPreview`, `channels.telegram.proxy`, `channels.telegram.webhookSecret`, `channels.telegram.webhookUrl`.
 - **Draft streaming:** optional `channels.telegram.streamMode` uses `sendMessageDraft` in private topic chats (Bot API 9.3+). This is separate from channel block streaming.
 - **Tests:** grammy mocks cover DM + group mention gating and outbound send; more media/webhook fixtures still welcome.

@@ -525,6 +525,7 @@ Provider options:
 - `channels.telegram.replyToMode`: `off | first | all` (default: `first`).
 - `channels.telegram.textChunkLimit`: outbound chunk size (chars).
 - `channels.telegram.chunkMode`: `length` (default) or `newline` to split on newlines before length chunking.
+- `channels.telegram.linkPreview`: toggle link previews for outbound messages (default: true).
 - `channels.telegram.streamMode`: `off | partial | block` (draft streaming).
 - `channels.telegram.mediaMaxMb`: inbound/outbound media cap (MB).
 - `channels.telegram.retry`: retry policy for outbound Telegram API calls (attempts, minDelayMs, maxDelayMs, jitter).
@@ -89,6 +89,8 @@ Clawdbot ships with the pi‑ai catalog. These providers require **no**
 - Gemini CLI OAuth is shipped as a bundled plugin (`google-gemini-cli-auth`, disabled by default).
  - Enable: `clawdbot plugins enable google-gemini-cli-auth`
  - Login: `clawdbot models auth login --provider google-gemini-cli --set-default`
+  - Note: you do **not** paste a client id or secret into `clawdbot.json`. The CLI login flow stores
+    tokens in auth profiles on the gateway host.

 ### Z.AI (GLM)

@@ -1048,6 +1048,7 @@
        "pages": [
          "platforms",
          "platforms/macos",
+          "platforms/macos-vm",
          "platforms/ios",
          "platforms/android",
          "platforms/windows",
@@ -1021,6 +1021,7 @@ Set `channels.telegram.configWrites: false` to block Telegram-initiated config w
      ],
      historyLimit: 50,                     // include last N group messages as context (0 disables)
      replyToMode: "first",                 // off | first | all
+      linkPreview: true,                   // toggle outbound link previews
      streamMode: "partial",               // off | partial | block (draft streaming; separate from block streaming)
      draftChunk: {                        // optional; only for streamMode=block
        minChars: 200,
@@ -24,6 +24,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
  - [How do I try the latest bits?](#how-do-i-try-the-latest-bits)
  - [How long does install and onboarding usually take?](#how-long-does-install-and-onboarding-usually-take)
  - [Installer stuck? How do I get more feedback?](#installer-stuck-how-do-i-get-more-feedback)
+  - [Windows install says git not found or clawdbot not recognized](#windows-install-says-git-not-found-or-clawdbot-not-recognized)
  - [The docs didn’t answer my question - how do I get a better answer?](#the-docs-didnt-answer-my-question-how-do-i-get-a-better-answer)
  - [How do I install Clawdbot on Linux?](#how-do-i-install-clawdbot-on-linux)
  - [How do I install Clawdbot on a VPS?](#how-do-i-install-clawdbot-on-a-vps)
@@ -31,6 +32,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
  - [Can I ask Clawd to update itself?](#can-i-ask-clawd-to-update-itself)
  - [What does the onboarding wizard actually do?](#what-does-the-onboarding-wizard-actually-do)
  - [Do I need a Claude or OpenAI subscription to run this?](#do-i-need-a-claude-or-openai-subscription-to-run-this)
+  - [Can I use Claude Max subscription without an API key](#can-i-use-claude-max-subscription-without-an-api-key)
  - [How does Anthropic "setup-token" auth work?](#how-does-anthropic-setuptoken-auth-work)
  - [Where do I find an Anthropic setup-token?](#where-do-i-find-an-anthropic-setuptoken)
  - [Do you support Claude subscription auth (Claude Code OAuth)?](#do-you-support-claude-subscription-auth-claude-code-oauth)
@@ -38,6 +40,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
  - [Is AWS Bedrock supported?](#is-aws-bedrock-supported)
  - [How does Codex auth work?](#how-does-codex-auth-work)
  - [Do you support OpenAI subscription auth (Codex OAuth)?](#do-you-support-openai-subscription-auth-codex-oauth)
+  - [How do I set up Gemini CLI OAuth](#how-do-i-set-up-gemini-cli-oauth)
  - [Is a local model OK for casual chats?](#is-a-local-model-ok-for-casual-chats)
  - [How do I keep hosted model traffic in a specific region?](#how-do-i-keep-hosted-model-traffic-in-a-specific-region)
  - [Do I have to buy a Mac Mini to install this?](#do-i-have-to-buy-a-mac-mini-to-install-this)
@@ -53,9 +56,13 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
  - [Should I run the Gateway on my laptop or a VPS?](#should-i-run-the-gateway-on-my-laptop-or-a-vps)
  - [How important is it to run Clawdbot on a dedicated machine?](#how-important-is-it-to-run-clawdbot-on-a-dedicated-machine)
  - [What are the minimum VPS requirements and recommended OS?](#what-are-the-minimum-vps-requirements-and-recommended-os)
+  - [Can I run Clawdbot in a VM and what are the requirements](#can-i-run-clawdbot-in-a-vm-and-what-are-the-requirements)
 - [What is Clawdbot?](#what-is-clawdbot)
  - [What is Clawdbot, in one paragraph?](#what-is-clawdbot-in-one-paragraph)
  - [What’s the value proposition?](#whats-the-value-proposition)
+  - [I just set it up what should I do first](#i-just-set-it-up-what-should-i-do-first)
+  - [What are the top five everyday use cases for Clawdbot](#what-are-the-top-five-everyday-use-cases-for-clawdbot)
+  - [Can Clawdbot help with lead gen outreach ads and blogs for a SaaS](#can-clawdbot-help-with-lead-gen-outreach-ads-and-blogs-for-a-saas)
  - [What are the advantages vs Claude Code for web development?](#what-are-the-advantages-vs-claude-code-for-web-development)
 - [Skills and automation](#skills-and-automation)
  - [How do I customize skills without keeping the repo dirty?](#how-do-i-customize-skills-without-keeping-the-repo-dirty)
@@ -174,10 +181,12 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
  - [Is it safe to expose Clawdbot to inbound DMs?](#is-it-safe-to-expose-clawdbot-to-inbound-dms)
  - [Is prompt injection only a concern for public bots?](#is-prompt-injection-only-a-concern-for-public-bots)
  - [Should my bot have its own email GitHub account or phone number](#should-my-bot-have-its-own-email-github-account-or-phone-number)
+  - [Can I give it autonomy over my text messages and is that safe](#can-i-give-it-autonomy-over-my-text-messages-and-is-that-safe)
  - [Can I use cheaper models for personal assistant tasks?](#can-i-use-cheaper-models-for-personal-assistant-tasks)
  - [I ran `/start` in Telegram but didn’t get a pairing code](#i-ran-start-in-telegram-but-didnt-get-a-pairing-code)
  - [WhatsApp: will it message my contacts? How does pairing work?](#whatsapp-will-it-message-my-contacts-how-does-pairing-work)
 - [Chat commands, aborting tasks, and “it won’t stop”](#chat-commands-aborting-tasks-and-it-wont-stop)
+  - [How do I stop internal system messages from showing in chat](#how-do-i-stop-internal-system-messages-from-showing-in-chat)
  - [How do I stop/cancel a running task?](#how-do-i-stopcancel-a-running-task)
  - [How do I send a Discord message from Telegram? (“Cross-context messaging denied”)](#how-do-i-send-a-discord-message-from-telegram-crosscontext-messaging-denied)
  - [Why does it feel like the bot “ignores” rapid‑fire messages?](#why-does-it-feel-like-the-bot-ignores-rapidfire-messages)
@@ -328,7 +337,7 @@ Node **>= 22** is required. `pnpm` is recommended. Bun is **not recommended** fo

 ### Does it run on Raspberry Pi

-Yes. The Gateway is lightweight - docs list **512MB–1GB RAM**, **1 core**, and about **500MB**
+Yes. The Gateway is lightweight - docs list **512MB-1GB RAM**, **1 core**, and about **500MB**
 disk as enough for personal use, and note that a **Raspberry Pi 4 can run it**.

 If you want extra headroom (logs, media, other services), **2GB is recommended**, but it’s
@@ -504,6 +513,26 @@ curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git --verb

 More options: [Installer flags](/install/installer).

+### Windows install says git not found or clawdbot not recognized
+
+Two common Windows issues:
+
+**1) npm error spawn git / git not found**
+- Install **Git for Windows** and make sure `git` is on your PATH.
+- Close and reopen PowerShell, then re-run the installer.
+
+**2) clawdbot is not recognized after install**
+- Your npm global bin folder is not on PATH.
+- Check the path:
+  ```powershell
+  npm config get prefix
+  ```
+- Ensure `<prefix>\\bin` is on PATH (on most systems it is `%AppData%\\npm`).
+- Close and reopen PowerShell after updating PATH.
+
+If you want the smoothest Windows setup, use **WSL2** instead of native Windows.
+Docs: [Windows](/platforms/windows).
+
 ### The docs didnt answer my question how do I get a better answer

 Use the **hackable (git) install** so you have the full source and docs locally, then ask
@@ -598,6 +627,16 @@ Pro/Max or OpenAI Codex) are optional ways to authenticate those providers.
 Docs: [Anthropic](/providers/anthropic), [OpenAI](/providers/openai),
 [Local models](/gateway/local-models), [Models](/concepts/models).

+### Can I use Claude Max subscription without an API key
+
+Yes. You can authenticate with **Claude Code CLI OAuth** or a **setup-token**
+instead of an API key. This is the subscription path.
+
+Claude Pro/Max subscriptions **do not include an API key**, so this is the
+correct approach for subscription accounts. Important: you must verify with
+Anthropic that this usage is allowed under their subscription policy and terms.
+If you want the most explicit, supported path, use an Anthropic API key.
+
 ### How does Anthropic setuptoken auth work

 `claude setup-token` generates a **token string** via the Claude Code CLI (it is not available in the web console). You can run it on **any machine**. If Claude Code CLI credentials are present on the gateway host, Clawdbot can reuse them; otherwise choose **Anthropic token (paste setup-token)** and paste the string. The token is stored as an auth profile for the **anthropic** provider and used like an API key or OAuth profile. More detail: [OAuth](/concepts/oauth).
@@ -648,6 +687,16 @@ can import the CLI login or run the OAuth flow for you.

 See [OAuth](/concepts/oauth), [Model providers](/concepts/model-providers), and [Wizard](/start/wizard).

+### How do I set up Gemini CLI OAuth
+
+Gemini CLI uses a **plugin auth flow**, not a client id or secret in `clawdbot.json`.
+
+Steps:
+1) Enable the plugin: `clawdbot plugins enable google-gemini-cli-auth`
+2) Login: `clawdbot models auth login --provider google-gemini-cli --set-default`
+
+This stores OAuth tokens in auth profiles on the gateway host. Details: [Model providers](/concepts/model-providers).
+
 ### Is a local model OK for casual chats

 Usually no. Clawdbot needs large context + strong safety; small cards truncate and leak. If you must, run the **largest** MiniMax M2.1 build you can locally (LM Studio) and see [/gateway/local-models](/gateway/local-models). Smaller/quantized models increase prompt-injection risk - see [Security](/gateway/security).
@@ -815,6 +864,20 @@ OS: use **Ubuntu LTS** (or any modern Debian/Ubuntu). The Linux install path is

 Docs: [Linux](/platforms/linux), [VPS hosting](/vps).

+### Can I run Clawdbot in a VM and what are the requirements
+
+Yes. Treat a VM the same as a VPS: it needs to be always on, reachable, and have enough
+RAM for the Gateway and any channels you enable.
+
+Baseline guidance:
+- **Absolute minimum:** 1 vCPU, 1GB RAM.
+- **Recommended:** 2GB RAM or more if you run multiple channels, browser automation, or media tools.
+- **OS:** Ubuntu LTS or another modern Debian/Ubuntu.
+
+If you are on Windows, **WSL2 is the easiest VM style setup** and has the best tooling
+compatibility. See [Windows](/platforms/windows), [VPS hosting](/vps).
+If you are running macOS in a VM, see [macOS VM](/platforms/macos-vm).
+
 ## What is Clawdbot?

 ### What is Clawdbot in one paragraph
@@ -843,6 +906,37 @@ Highlights:
 Docs: [Gateway](/gateway), [Channels](/channels), [Multi‑agent](/concepts/multi-agent),
 [Memory](/concepts/memory).

+### I just set it up what should I do first
+
+Good first projects:
+- Build a website (WordPress, Shopify, or a simple static site).
+- Prototype a mobile app (outline, screens, API plan).
+- Organize files and folders (cleanup, naming, tagging).
+- Connect Gmail and automate summaries or follow ups.
+
+It can handle large tasks, but it works best when you split them into phases and
+use sub agents for parallel work.
+
+### What are the top five everyday use cases for Clawdbot
+
+Everyday wins usually look like:
+- **Personal briefings:** summaries of inbox, calendar, and news you care about.
+- **Research and drafting:** quick research, summaries, and first drafts for emails or docs.
+- **Reminders and follow ups:** cron or heartbeat driven nudges and checklists.
+- **Browser automation:** filling forms, collecting data, and repeating web tasks.
+- **Cross device coordination:** send a task from your phone, let the Gateway run it on a server, and get the result back in chat.
+
+### Can Clawdbot help with lead gen outreach ads and blogs for a SaaS
+
+Yes for **research, qualification, and drafting**. It can scan sites, build shortlists,
+summarize prospects, and write outreach or ad copy drafts.
+
+For **outreach or ad runs**, keep a human in the loop. Avoid spam, follow local laws and
+platform policies, and review anything before it is sent. The safest pattern is to let
+Clawdbot draft and you approve.
+
+Docs: [Security](/gateway/security).
+
 ### What are the advantages vs Claude Code for web development

 Clawdbot is a **personal assistant** and coordination layer, not an IDE replacement. Use
@@ -2477,6 +2571,16 @@ later if required.

 Docs: [Security](/gateway/security), [Pairing](/start/pairing).

+### Can I give it autonomy over my text messages and is that safe
+
+We do **not** recommend full autonomy over your personal messages. The safest pattern is:
+- Keep DMs in **pairing mode** or a tight allowlist.
+- Use a **separate number or account** if you want it to message on your behalf.
+- Let it draft, then **approve before sending**.
+
+If you want to experiment, do it on a dedicated account and keep it isolated. See
+[Security](/gateway/security).
+
 ### Can I use cheaper models for personal assistant tasks

 Yes, **if** the agent is chat-only and the input is trusted. Smaller tiers are
@@ -2517,6 +2621,23 @@ Wizard phone number prompt: it’s used to set your **allowlist/owner** so your

 ## Chat commands, aborting tasks, and “it won’t stop”

+### How do I stop internal system messages from showing in chat
+
+Most internal or tool messages only appear when **verbose** or **reasoning** is enabled
+for that session.
+
+Fix in the chat where you see it:
+```
+/verbose off
+/reasoning off
+```
+
+If it is still noisy, check the session settings in the Control UI and set verbose
+to **inherit**. Also confirm you are not using a bot profile with `verboseDefault` set
+to `on` in config.
+
+Docs: [Thinking and verbose](/tools/thinking), [Security](/gateway/security#reasoning--verbose-output-in-groups).
+
 ### How do I stopcancel a running task

 Send any of these **as a standalone message** (no slash):
@@ -114,3 +114,9 @@ Git requirement:

 If you choose `-InstallMethod git` and Git is missing, the installer will print the
 Git for Windows link (`https://git-scm.com/download/win`) and exit.
+
+Common Windows issues:
+
+- **npm error spawn git / ENOENT**: install Git for Windows and reopen PowerShell, then rerun the installer.
+- **"clawdbot" is not recognized**: your npm global bin folder is not on PATH. Most systems use
+  `%AppData%\\npm`. You can also run `npm config get prefix` and add `\\bin` to PATH, then reopen PowerShell.
@@ -0,0 +1,275 @@
+---
+summary: "Run Clawdbot in a sandboxed macOS VM (local or hosted) when you need isolation or iMessage"
+read_when:
+  - You want Clawdbot isolated from your main macOS environment
+  - You want iMessage integration (BlueBubbles) in a sandbox
+  - You want a resettable macOS environment you can clone
+  - You want to compare local vs hosted macOS VM options
+---
+
+# Clawdbot on macOS VMs (Sandboxing)
+
+## Recommended default (most users)
+
+- **Small Linux VPS** for an always-on Gateway and low cost. See [VPS hosting](/vps).
+- **Dedicated hardware** (Mac mini or Linux box) if you want full control and a **residential IP** for browser automation. Many sites block data center IPs, so local browsing often works better.
+- **Hybrid:** keep the Gateway on a cheap VPS, and connect your Mac as a **node** when you need browser/UI automation. See [Nodes](/nodes) and [Gateway remote](/gateway/remote).
+
+Use a macOS VM when you specifically need macOS-only capabilities (iMessage/BlueBubbles) or want strict isolation from your daily Mac.
+
+## macOS VM options
+
+### Local VM on your Apple Silicon Mac (Lume)
+
+Run Clawdbot in a sandboxed macOS VM on your existing Apple Silicon Mac using [Lume](https://cua.ai/docs/lume).
+
+This gives you:
+- Full macOS environment in isolation (your host stays clean)
+- iMessage support via BlueBubbles (impossible on Linux/Windows)
+- Instant reset by cloning VMs
+- No extra hardware or cloud costs
+
+### Hosted Mac providers (cloud)
+
+If you want macOS in the cloud, hosted Mac providers work too:
+- [MacStadium](https://www.macstadium.com/) (hosted Macs)
+- Other hosted Mac vendors also work; follow their VM + SSH docs
+
+Once you have SSH access to a macOS VM, continue at step 6 below.
+
+---
+
+## Quick path (Lume, experienced users)
+
+1. Install Lume
+2. `lume create clawdbot --os macos --ipsw latest`
+3. Complete Setup Assistant, enable Remote Login (SSH)
+4. `lume run clawdbot --no-display`
+5. SSH in, install Clawdbot, configure channels
+6. Done
+
+---
+
+## What you need (Lume)
+
+- Apple Silicon Mac (M1/M2/M3/M4)
+- macOS Sequoia or later on the host
+- ~60 GB free disk space per VM
+- ~20 minutes
+
+---
+
+## 1) Install Lume
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
+```
+
+If `~/.local/bin` isn't in your PATH:
+
+```bash
+echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc && source ~/.zshrc
+```
+
+Verify:
+
+```bash
+lume --version
+```
+
+Docs: [Lume Installation](https://cua.ai/docs/lume/guide/getting-started/installation)
+
+---
+
+## 2) Create the macOS VM
+
+```bash
+lume create clawdbot --os macos --ipsw latest
+```
+
+This downloads macOS and creates the VM. A VNC window opens automatically.
+
+Note: The download can take a while depending on your connection.
+
+---
+
+## 3) Complete Setup Assistant
+
+In the VNC window:
+1. Select language and region
+2. Skip Apple ID (or sign in if you want iMessage later)
+3. Create a user account (remember the username and password)
+4. Skip all optional features
+
+After setup completes, enable SSH:
+1. Open System Settings → General → Sharing
+2. Enable "Remote Login"
+
+---
+
+## 4) Get the VM's IP address
+
+```bash
+lume get clawdbot
+```
+
+Look for the IP address (usually `192.168.64.x`).
+
+---
+
+## 5) SSH into the VM
+
+```bash
+ssh youruser@192.168.64.X
+```
+
+Replace `youruser` with the account you created, and the IP with your VM's IP.
+
+---
+
+## 6) Install Clawdbot
+
+Inside the VM:
+
+```bash
+npm install -g clawdbot@latest
+clawdbot onboard --install-daemon
+```
+
+Follow the onboarding prompts to set up your model provider (Anthropic, OpenAI, etc.).
+
+---
+
+## 7) Configure channels
+
+Edit the config file:
+
+```bash
+nano ~/.clawdbot/clawdbot.json
+```
+
+Add your channels:
+
+```json
+{
+  "channels": {
+    "whatsapp": {
+      "dmPolicy": "allowlist",
+      "allowFrom": ["+15551234567"]
+    },
+    "telegram": {
+      "botToken": "YOUR_BOT_TOKEN"
+    }
+  }
+}
+```
+
+Then login to WhatsApp (scan QR):
+
+```bash
+clawdbot channels login
+```
+
+---
+
+## 8) Run the VM headlessly
+
+Stop the VM and restart without display:
+
+```bash
+lume stop clawdbot
+lume run clawdbot --no-display
+```
+
+The VM runs in the background. Clawdbot's daemon keeps the gateway running.
+
+To check status:
+
+```bash
+ssh youruser@192.168.64.X "clawdbot status"
+```
+
+---
+
+## Bonus: iMessage integration
+
+This is the killer feature of running on macOS. Use [BlueBubbles](https://bluebubbles.app) to add iMessage to Clawdbot.
+
+Inside the VM:
+
+1. Download BlueBubbles from bluebubbles.app
+2. Sign in with your Apple ID
+3. Enable the Web API and set a password
+4. Point BlueBubbles webhooks at your gateway (example: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`)
+
+Add to your Clawdbot config:
+
+```json
+{
+  "channels": {
+    "bluebubbles": {
+      "serverUrl": "http://localhost:1234",
+      "password": "your-api-password",
+      "webhookPath": "/bluebubbles-webhook"
+    }
+  }
+}
+```
+
+Restart the gateway. Now your agent can send and receive iMessages.
+
+Full setup details: [BlueBubbles channel](/channels/bluebubbles)
+
+---
+
+## Save a golden image
+
+Before customizing further, snapshot your clean state:
+
+```bash
+lume stop clawdbot
+lume clone clawdbot clawdbot-golden
+```
+
+Reset anytime:
+
+```bash
+lume stop clawdbot && lume delete clawdbot
+lume clone clawdbot-golden clawdbot
+lume run clawdbot --no-display
+```
+
+---
+
+## Running 24/7
+
+Keep the VM running by:
+- Keeping your Mac plugged in
+- Disabling sleep in System Settings → Energy Saver
+- Using `caffeinate` if needed
+
+For true always-on, consider a dedicated Mac mini or a small VPS. See [VPS hosting](/vps).
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Can't SSH into VM | Check "Remote Login" is enabled in VM's System Settings |
+| VM IP not showing | Wait for VM to fully boot, run `lume get clawdbot` again |
+| Lume command not found | Add `~/.local/bin` to your PATH |
+| WhatsApp QR not scanning | Ensure you're logged into the VM (not host) when running `clawdbot channels login` |
+
+---
+
+## Related docs
+
+- [VPS hosting](/vps)
+- [Nodes](/nodes)
+- [Gateway remote](/gateway/remote)
+- [BlueBubbles channel](/channels/bluebubbles)
+- [Lume Quickstart](https://cua.ai/docs/lume/guide/getting-started/quickstart)
+- [Lume CLI Reference](https://cua.ai/docs/lume/reference/cli-reference)
+- [Unattended VM Setup](https://cua.ai/docs/lume/guide/fundamentals/unattended-setup) (advanced)
+- [Docker Sandboxing](/install/docker) (alternative isolation approach)
@@ -67,6 +67,22 @@ Plugins can register:
 Plugins run **in‑process** with the Gateway, so treat them as trusted code.
 Tool authoring guide: [Plugin agent tools](/plugins/agent-tools).

+## Runtime helpers
+
+Plugins can access selected core helpers via `api.runtime`. For telephony TTS:
+
+```ts
+const result = await api.runtime.tts.textToSpeechTelephony({
+  text: "Hello from Clawdbot",
+  cfg: api.config,
+});
+```
+
+Notes:
+- Uses core `messages.tts` configuration (OpenAI or ElevenLabs).
+- Returns PCM audio buffer + sample rate. Plugins must resample/encode for providers.
+- Edge TTS is not supported for telephony.
+
 ## Discovery & precedence

 Clawdbot scans, in order:
@@ -104,6 +104,87 @@ Notes:
 - `mock` is a local dev provider (no network calls).
 - `skipSignatureVerification` is for local testing only.

+## TTS for calls
+
+Voice Call uses the core `messages.tts` configuration (OpenAI or ElevenLabs) for
+streaming speech on calls. You can override it under the plugin config with the
+**same shape** — it deep‑merges with `messages.tts`.
+
+```json5
+{
+  tts: {
+    provider: "elevenlabs",
+    elevenlabs: {
+      voiceId: "pMsXgVXv3BLzUgSXRplE",
+      modelId: "eleven_multilingual_v2"
+    }
+  }
+}
+```
+
+Notes:
+- **Edge TTS is ignored for voice calls** (telephony audio needs PCM; Edge output is unreliable).
+- Core TTS is used when Twilio media streaming is enabled; otherwise calls fall back to provider native voices.
+
+### More examples
+
+Use core TTS only (no override):
+
+```json5
+{
+  messages: {
+    tts: {
+      provider: "openai",
+      openai: { voice: "alloy" }
+    }
+  }
+}
+```
+
+Override to ElevenLabs just for calls (keep core default elsewhere):
+
+```json5
+{
+  plugins: {
+    entries: {
+      "voice-call": {
+        config: {
+          tts: {
+            provider: "elevenlabs",
+            elevenlabs: {
+              apiKey: "elevenlabs_key",
+              voiceId: "pMsXgVXv3BLzUgSXRplE",
+              modelId: "eleven_multilingual_v2"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Override only the OpenAI model for calls (deep‑merge example):
+
+```json5
+{
+  plugins: {
+    entries: {
+      "voice-call": {
+        config: {
+          tts: {
+            openai: {
+              model: "gpt-4o-mini-tts",
+              voice: "marin"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 ## Inbound calls

 Inbound policy defaults to `disabled`. To enable inbound calls, set:
@@ -16,7 +16,7 @@ and you configure everything via the `/setup` web wizard.

 ## One-click deploy

-<a href="https://railway.com/deploy/clawdbot-railway-template" target="_blank" rel="noreferrer">Deploy on Railway</a>
+<a href="https://railway.app/new/template?template=https://github.com/vignesh07/clawdbot-railway-template" target="_blank" rel="noreferrer">Deploy on Railway</a>

 After deploy, find your public URL in **Railway → your service → Settings → Domains**.

@@ -55,6 +55,7 @@ Attach a volume mounted at:
 Set these variables on the service:

 - `SETUP_PASSWORD` (required)
+- `PORT=8080` (required — must match the port in Public Networking)
 - `CLAWDBOT_STATE_DIR=/data/.clawdbot` (recommended)
 - `CLAWDBOT_WORKSPACE_DIR=/data/workspace` (recommended)
 - `CLAWDBOT_GATEWAY_TOKEN` (recommended; treat as an admin secret)
@@ -82,8 +83,9 @@ If Telegram DMs are set to pairing, the setup wizard can approve the pairing cod
 1) Go to https://discord.com/developers/applications
 2) **New Application** → choose a name
 3) **Bot** → **Add Bot**
-4) Copy the **Bot Token** and paste into `/setup`
-5) Invite the bot to your server (OAuth2 URL Generator; scopes: `bot`, `applications.commands`)
+4) **Enable MESSAGE CONTENT INTENT** under Bot → Privileged Gateway Intents (required or the bot will crash on startup)
+5) Copy the **Bot Token** and paste into `/setup`
+6) Invite the bot to your server (OAuth2 URL Generator; scopes: `bot`, `applications.commands`)

 ## Backups & migration

@@ -25,9 +25,11 @@ import { resolveBlueBubblesMessageId } from "./monitor.js";
 import { probeBlueBubbles, type BlueBubblesProbe } from "./probe.js";
 import { sendMessageBlueBubbles } from "./send.js";
 import {
+  extractHandleFromChatGuid,
  looksLikeBlueBubblesTargetId,
  normalizeBlueBubblesHandle,
  normalizeBlueBubblesMessagingTarget,
+  parseBlueBubblesTarget,
 } from "./targets.js";
 import { bluebubblesMessageActions } from "./actions.js";
 import { monitorBlueBubblesProvider, resolveWebhookPathFromConfig } from "./monitor.js";
@@ -148,6 +150,58 @@ export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
      looksLikeId: looksLikeBlueBubblesTargetId,
      hint: "<handle|chat_guid:GUID|chat_id:ID|chat_identifier:ID>",
    },
+    formatTargetDisplay: ({ target, display }) => {
+      const shouldParseDisplay = (value: string): boolean => {
+        if (looksLikeBlueBubblesTargetId(value)) return true;
+        return /^(bluebubbles:|chat_guid:|chat_id:|chat_identifier:)/i.test(value);
+      };
+
+      // Helper to extract a clean handle from any BlueBubbles target format
+      const extractCleanDisplay = (value: string | undefined): string | null => {
+        const trimmed = value?.trim();
+        if (!trimmed) return null;
+        try {
+          const parsed = parseBlueBubblesTarget(trimmed);
+          if (parsed.kind === "chat_guid") {
+            const handle = extractHandleFromChatGuid(parsed.chatGuid);
+            if (handle) return handle;
+          }
+          if (parsed.kind === "handle") {
+            return normalizeBlueBubblesHandle(parsed.to);
+          }
+        } catch {
+          // Fall through
+        }
+        // Strip common prefixes and try raw extraction
+        const stripped = trimmed
+          .replace(/^bluebubbles:/i, "")
+          .replace(/^chat_guid:/i, "")
+          .replace(/^chat_id:/i, "")
+          .replace(/^chat_identifier:/i, "");
+        const handle = extractHandleFromChatGuid(stripped);
+        if (handle) return handle;
+        // Don't return raw chat_guid formats - they contain internal routing info
+        if (stripped.includes(";-;") || stripped.includes(";+;")) return null;
+        return stripped;
+      };
+
+      // Try to get a clean display from the display parameter first
+      const trimmedDisplay = display?.trim();
+      if (trimmedDisplay) {
+        if (!shouldParseDisplay(trimmedDisplay)) {
+          return trimmedDisplay;
+        }
+        const cleanDisplay = extractCleanDisplay(trimmedDisplay);
+        if (cleanDisplay) return cleanDisplay;
+      }
+
+      // Fall back to extracting from target
+      const cleanTarget = extractCleanDisplay(target);
+      if (cleanTarget) return cleanTarget;
+
+      // Last resort: return display or target as-is
+      return display?.trim() || target?.trim() || "";
+    },
  },
  setup: {
    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
@@ -187,6 +187,47 @@ describe("send", () => {
      expect(result).toBe("iMessage;-;+15551234567");
    });

+    it("returns null when handle only exists in group chat (not DM)", async () => {
+      // This is the critical fix: if a phone number only exists as a participant in a group chat
+      // (no direct DM chat), we should NOT send to that group. Return null instead.
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              data: [
+                {
+                  guid: "iMessage;+;group-the-council",
+                  participants: [
+                    { address: "+12622102921" },
+                    { address: "+15550001111" },
+                    { address: "+15550002222" },
+                  ],
+                },
+              ],
+            }),
+        })
+        // Empty second page to stop pagination
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () => Promise.resolve({ data: [] }),
+        });
+
+      const target: BlueBubblesSendTarget = {
+        kind: "handle",
+        address: "+12622102921",
+        service: "imessage",
+      };
+      const result = await resolveChatGuidForTarget({
+        baseUrl: "http://localhost:1234",
+        password: "test",
+        target,
+      });
+
+      // Should return null, NOT the group chat GUID
+      expect(result).toBeNull();
+    });
+
    it("returns null when chat not found", async () => {
      mockFetch.mockResolvedValueOnce({
        ok: true,
@@ -344,14 +385,14 @@ describe("send", () => {
      ).rejects.toThrow("password is required");
    });

-    it("throws when chatGuid cannot be resolved", async () => {
+    it("throws when chatGuid cannot be resolved for non-handle targets", async () => {
      mockFetch.mockResolvedValue({
        ok: true,
        json: () => Promise.resolve({ data: [] }),
      });

      await expect(
-        sendMessageBlueBubbles("+15559999999", "Hello", {
+        sendMessageBlueBubbles("chat_id:999", "Hello", {
          serverUrl: "http://localhost:1234",
          password: "test",
        }),
@@ -398,6 +439,57 @@ describe("send", () => {
      expect(body.method).toBeUndefined();
    });

+    it("creates a new chat when handle target is missing", async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () => Promise.resolve({ data: [] }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          text: () =>
+            Promise.resolve(
+              JSON.stringify({
+                data: { guid: "new-msg-guid" },
+              }),
+            ),
+        });
+
+      const result = await sendMessageBlueBubbles("+15550009999", "Hello new chat", {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+
+      expect(result.messageId).toBe("new-msg-guid");
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+
+      const createCall = mockFetch.mock.calls[1];
+      expect(createCall[0]).toContain("/api/v1/chat/new");
+      const body = JSON.parse(createCall[1].body);
+      expect(body.addresses).toEqual(["+15550009999"]);
+      expect(body.message).toBe("Hello new chat");
+    });
+
+    it("throws when creating a new chat requires Private API", async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () => Promise.resolve({ data: [] }),
+        })
+        .mockResolvedValueOnce({
+          ok: false,
+          status: 403,
+          text: () => Promise.resolve("Private API not enabled"),
+        });
+
+      await expect(
+        sendMessageBlueBubbles("+15550008888", "Hello", {
+          serverUrl: "http://localhost:1234",
+          password: "test",
+        }),
+      ).rejects.toThrow("Private API must be enabled");
+    });
+
    it("uses private-api when reply metadata is present", async () => {
      mockFetch
        .mockResolvedValueOnce({
@@ -257,11 +257,17 @@ export async function resolveChatGuidForTarget(params: {
          return guid;
        }
        if (!participantMatch && guid) {
-          const participants = extractParticipantAddresses(chat).map((entry) =>
-            normalizeBlueBubblesHandle(entry),
-          );
-          if (participants.includes(normalizedHandle)) {
-            participantMatch = guid;
+          // Only consider DM chats (`;-;` separator) as participant matches.
+          // Group chats (`;+;` separator) should never match when searching by handle/phone.
+          // This prevents routing "send to +1234567890" to a group chat that contains that number.
+          const isDmChat = guid.includes(";-;");
+          if (isDmChat) {
+            const participants = extractParticipantAddresses(chat).map((entry) =>
+              normalizeBlueBubblesHandle(entry),
+            );
+            if (participants.includes(normalizedHandle)) {
+              participantMatch = guid;
+            }
          }
        }
      }
@@ -270,6 +276,55 @@ export async function resolveChatGuidForTarget(params: {
  return participantMatch;
 }

+/**
+ * Creates a new chat (DM) and optionally sends an initial message.
+ * Requires Private API to be enabled in BlueBubbles.
+ */
+async function createNewChatWithMessage(params: {
+  baseUrl: string;
+  password: string;
+  address: string;
+  message: string;
+  timeoutMs?: number;
+}): Promise<BlueBubblesSendResult> {
+  const url = buildBlueBubblesApiUrl({
+    baseUrl: params.baseUrl,
+    path: "/api/v1/chat/new",
+    password: params.password,
+  });
+  const payload = {
+    addresses: [params.address],
+    message: params.message,
+  };
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    params.timeoutMs,
+  );
+  if (!res.ok) {
+    const errorText = await res.text();
+    // Check for Private API not enabled error
+    if (res.status === 400 || res.status === 403 || errorText.toLowerCase().includes("private api")) {
+      throw new Error(
+        `BlueBubbles send failed: Cannot create new chat - Private API must be enabled. Original error: ${errorText || res.status}`,
+      );
+    }
+    throw new Error(`BlueBubbles create chat failed (${res.status}): ${errorText || "unknown"}`);
+  }
+  const body = await res.text();
+  if (!body) return { messageId: "ok" };
+  try {
+    const parsed = JSON.parse(body) as unknown;
+    return { messageId: extractMessageId(parsed) };
+  } catch {
+    return { messageId: "ok" };
+  }
+}
+
 export async function sendMessageBlueBubbles(
  to: string,
  text: string,
@@ -297,6 +352,17 @@ export async function sendMessageBlueBubbles(
    target,
  });
  if (!chatGuid) {
+    // If target is a phone number/handle and no existing chat found,
+    // auto-create a new DM chat using the /api/v1/chat/new endpoint
+    if (target.kind === "handle") {
+      return createNewChatWithMessage({
+        baseUrl,
+        password,
+        address: target.address,
+        message: trimmedText,
+        timeoutMs: opts.timeoutMs,
+      });
+    }
    throw new Error(
      "BlueBubbles send failed: chatGuid not found for target. Use a chat_guid target or ensure the chat exists.",
    );
@@ -1,5 +1,12 @@
 # Changelog

+## 2026.1.24
+
+### Changes
+- Breaking: voice-call TTS now uses core `messages.tts` (plugin TTS config deep‑merges with core).
+- Telephony TTS supports OpenAI + ElevenLabs; Edge TTS is ignored for calls.
+- Removed legacy `tts.model`/`tts.voice`/`tts.instructions` plugin fields.
+
 ## 2026.1.23

 ### Changes
@@ -75,6 +75,27 @@ Notes:
 - Twilio/Telnyx/Plivo require a **publicly reachable** webhook URL.
 - `mock` is a local dev provider (no network calls).

+## TTS for calls
+
+Voice Call uses the core `messages.tts` configuration (OpenAI or ElevenLabs) for
+streaming speech on calls. You can override it under the plugin config with the
+same shape — overrides deep-merge with `messages.tts`.
+
+```json5
+{
+  tts: {
+    provider: "openai",
+    openai: {
+      voice: "alloy"
+    }
+  }
+}
+```
+
+Notes:
+- Edge TTS is ignored for voice calls (telephony audio needs PCM; Edge output is unreliable).
+- Core TTS is used when Twilio media streaming is enabled; otherwise calls fall back to provider native voices.
+
 ## CLI

 ```bash
@@ -99,16 +99,39 @@
      "label": "Media Stream Path",
      "advanced": true
    },
-    "tts.model": {
-      "label": "TTS Model",
+    "tts.provider": {
+      "label": "TTS Provider Override",
+      "help": "Deep-merges with messages.tts (Edge is ignored for calls).",
      "advanced": true
    },
-    "tts.voice": {
-      "label": "TTS Voice",
+    "tts.openai.model": {
+      "label": "OpenAI TTS Model",
      "advanced": true
    },
-    "tts.instructions": {
-      "label": "TTS Instructions",
+    "tts.openai.voice": {
+      "label": "OpenAI TTS Voice",
+      "advanced": true
+    },
+    "tts.openai.apiKey": {
+      "label": "OpenAI API Key",
+      "sensitive": true,
+      "advanced": true
+    },
+    "tts.elevenlabs.modelId": {
+      "label": "ElevenLabs Model ID",
+      "advanced": true
+    },
+    "tts.elevenlabs.voiceId": {
+      "label": "ElevenLabs Voice ID",
+      "advanced": true
+    },
+    "tts.elevenlabs.apiKey": {
+      "label": "ElevenLabs API Key",
+      "sensitive": true,
+      "advanced": true
+    },
+    "tts.elevenlabs.baseUrl": {
+      "label": "ElevenLabs Base URL",
      "advanced": true
    },
    "publicUrl": {
@@ -370,20 +393,193 @@
        "type": "object",
        "additionalProperties": false,
        "properties": {
+          "auto": {
+            "type": "string",
+            "enum": [
+              "off",
+              "always",
+              "inbound",
+              "tagged"
+            ]
+          },
+          "enabled": {
+            "type": "boolean"
+          },
+          "mode": {
+            "type": "string",
+            "enum": [
+              "final",
+              "all"
+            ]
+          },
          "provider": {
            "type": "string",
            "enum": [
-              "openai"
+              "openai",
+              "elevenlabs",
+              "edge"
            ]
          },
-          "model": {
+          "summaryModel": {
            "type": "string"
          },
-          "voice": {
+          "modelOverrides": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "enabled": {
+                "type": "boolean"
+              },
+              "allowText": {
+                "type": "boolean"
+              },
+              "allowProvider": {
+                "type": "boolean"
+              },
+              "allowVoice": {
+                "type": "boolean"
+              },
+              "allowModelId": {
+                "type": "boolean"
+              },
+              "allowVoiceSettings": {
+                "type": "boolean"
+              },
+              "allowNormalization": {
+                "type": "boolean"
+              },
+              "allowSeed": {
+                "type": "boolean"
+              }
+            }
+          },
+          "elevenlabs": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "apiKey": {
+                "type": "string"
+              },
+              "baseUrl": {
+                "type": "string"
+              },
+              "voiceId": {
+                "type": "string"
+              },
+              "modelId": {
+                "type": "string"
+              },
+              "seed": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 4294967295
+              },
+              "applyTextNormalization": {
+                "type": "string",
+                "enum": [
+                  "auto",
+                  "on",
+                  "off"
+                ]
+              },
+              "languageCode": {
+                "type": "string"
+              },
+              "voiceSettings": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "stability": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                  },
+                  "similarityBoost": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                  },
+                  "style": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                  },
+                  "useSpeakerBoost": {
+                    "type": "boolean"
+                  },
+                  "speed": {
+                    "type": "number",
+                    "minimum": 0.5,
+                    "maximum": 2
+                  }
+                }
+              }
+            }
+          },
+          "openai": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "apiKey": {
+                "type": "string"
+              },
+              "model": {
+                "type": "string"
+              },
+              "voice": {
+                "type": "string"
+              }
+            }
+          },
+          "edge": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "enabled": {
+                "type": "boolean"
+              },
+              "voice": {
+                "type": "string"
+              },
+              "lang": {
+                "type": "string"
+              },
+              "outputFormat": {
+                "type": "string"
+              },
+              "pitch": {
+                "type": "string"
+              },
+              "rate": {
+                "type": "string"
+              },
+              "volume": {
+                "type": "string"
+              },
+              "saveSubtitles": {
+                "type": "boolean"
+              },
+              "proxy": {
+                "type": "string"
+              },
+              "timeoutMs": {
+                "type": "integer",
+                "minimum": 1000,
+                "maximum": 120000
+              }
+            }
+          },
+          "prefsPath": {
            "type": "string"
          },
-          "instructions": {
-            "type": "string"
+          "maxTextLength": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "timeoutMs": {
+            "type": "integer",
+            "minimum": 1000,
+            "maximum": 120000
          }
        }
      },
@@ -74,9 +74,26 @@ const voiceCallConfigSchema = {
    },
    "streaming.sttModel": { label: "Realtime STT Model", advanced: true },
    "streaming.streamPath": { label: "Media Stream Path", advanced: true },
-    "tts.model": { label: "TTS Model", advanced: true },
-    "tts.voice": { label: "TTS Voice", advanced: true },
-    "tts.instructions": { label: "TTS Instructions", advanced: true },
+    "tts.provider": {
+      label: "TTS Provider Override",
+      help: "Deep-merges with messages.tts (Edge is ignored for calls).",
+      advanced: true,
+    },
+    "tts.openai.model": { label: "OpenAI TTS Model", advanced: true },
+    "tts.openai.voice": { label: "OpenAI TTS Voice", advanced: true },
+    "tts.openai.apiKey": {
+      label: "OpenAI API Key",
+      sensitive: true,
+      advanced: true,
+    },
+    "tts.elevenlabs.modelId": { label: "ElevenLabs Model ID", advanced: true },
+    "tts.elevenlabs.voiceId": { label: "ElevenLabs Voice ID", advanced: true },
+    "tts.elevenlabs.apiKey": {
+      label: "ElevenLabs API Key",
+      sensitive: true,
+      advanced: true,
+    },
+    "tts.elevenlabs.baseUrl": { label: "ElevenLabs Base URL", advanced: true },
    publicUrl: { label: "Public Webhook URL", advanced: true },
    skipSignatureVerification: {
      label: "Skip Signature Verification",
@@ -161,6 +178,7 @@ const voiceCallPlugin = {
        runtimePromise = createVoiceCallRuntime({
          config: cfg,
          coreConfig: api.config as CoreConfig,
+          ttsRuntime: api.runtime.tts,
          logger: api.logger,
        });
      }
@@ -82,31 +82,82 @@ export const SttConfigSchema = z
  .default({ provider: "openai", model: "whisper-1" });
 export type SttConfig = z.infer<typeof SttConfigSchema>;

+export const TtsProviderSchema = z.enum(["openai", "elevenlabs", "edge"]);
+export const TtsModeSchema = z.enum(["final", "all"]);
+export const TtsAutoSchema = z.enum(["off", "always", "inbound", "tagged"]);
+
 export const TtsConfigSchema = z
  .object({
-    /** TTS provider (currently only OpenAI supported) */
-    provider: z.literal("openai").default("openai"),
-    /**
-     * TTS model to use:
-     * - gpt-4o-mini-tts: newest, supports instructions for tone/style control (recommended)
-     * - tts-1: lower latency
-     * - tts-1-hd: higher quality
-     */
-    model: z.string().min(1).default("gpt-4o-mini-tts"),
-    /**
-     * Voice ID. For best quality, use marin or cedar.
-     * All voices: alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer, verse, marin, cedar
-     */
-    voice: z.string().min(1).default("coral"),
-    /**
-     * Instructions for speech style (only works with gpt-4o-mini-tts).
-     * Examples: "Speak in a cheerful tone", "Talk like a sympathetic customer service agent"
-     */
-    instructions: z.string().optional(),
+    auto: TtsAutoSchema.optional(),
+    enabled: z.boolean().optional(),
+    mode: TtsModeSchema.optional(),
+    provider: TtsProviderSchema.optional(),
+    summaryModel: z.string().optional(),
+    modelOverrides: z
+      .object({
+        enabled: z.boolean().optional(),
+        allowText: z.boolean().optional(),
+        allowProvider: z.boolean().optional(),
+        allowVoice: z.boolean().optional(),
+        allowModelId: z.boolean().optional(),
+        allowVoiceSettings: z.boolean().optional(),
+        allowNormalization: z.boolean().optional(),
+        allowSeed: z.boolean().optional(),
+      })
+      .strict()
+      .optional(),
+    elevenlabs: z
+      .object({
+        apiKey: z.string().optional(),
+        baseUrl: z.string().optional(),
+        voiceId: z.string().optional(),
+        modelId: z.string().optional(),
+        seed: z.number().int().min(0).max(4294967295).optional(),
+        applyTextNormalization: z.enum(["auto", "on", "off"]).optional(),
+        languageCode: z.string().optional(),
+        voiceSettings: z
+          .object({
+            stability: z.number().min(0).max(1).optional(),
+            similarityBoost: z.number().min(0).max(1).optional(),
+            style: z.number().min(0).max(1).optional(),
+            useSpeakerBoost: z.boolean().optional(),
+            speed: z.number().min(0.5).max(2).optional(),
+          })
+          .strict()
+          .optional(),
+      })
+      .strict()
+      .optional(),
+    openai: z
+      .object({
+        apiKey: z.string().optional(),
+        model: z.string().optional(),
+        voice: z.string().optional(),
+      })
+      .strict()
+      .optional(),
+    edge: z
+      .object({
+        enabled: z.boolean().optional(),
+        voice: z.string().optional(),
+        lang: z.string().optional(),
+        outputFormat: z.string().optional(),
+        pitch: z.string().optional(),
+        rate: z.string().optional(),
+        volume: z.string().optional(),
+        saveSubtitles: z.boolean().optional(),
+        proxy: z.string().optional(),
+        timeoutMs: z.number().int().min(1000).max(120000).optional(),
+      })
+      .strict()
+      .optional(),
+    prefsPath: z.string().optional(),
+    maxTextLength: z.number().int().min(1).optional(),
+    timeoutMs: z.number().int().min(1000).max(120000).optional(),
  })
  .strict()
-  .default({ provider: "openai", model: "gpt-4o-mini-tts", voice: "coral" });
-export type TtsConfig = z.infer<typeof TtsConfigSchema>;
+  .optional();
+export type VoiceCallTtsConfig = z.infer<typeof TtsConfigSchema>;

 // -----------------------------------------------------------------------------
 // Webhook Server Configuration
@@ -307,7 +358,7 @@ export const VoiceCallConfigSchema = z
  /** STT configuration */
  stt: SttConfigSchema,

-  /** TTS configuration */
+  /** TTS override (deep-merges with core messages.tts) */
  tts: TtsConfigSchema,

  /** Store path for call logs */
@@ -2,10 +2,16 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";

+import type { VoiceCallTtsConfig } from "./config.js";
+
 export type CoreConfig = {
  session?: {
    store?: string;
  };
+  messages?: {
+    tts?: VoiceCallTtsConfig;
+  };
+  [key: string]: unknown;
 };

 type CoreAgentDeps = {
@@ -143,7 +143,7 @@ export class CallManager {
      // For notify mode with a message, use inline TwiML with <Say>
      let inlineTwiml: string | undefined;
      if (mode === "notify" && initialMessage) {
-        const pollyVoice = mapVoiceToPolly(this.config.tts.voice);
+        const pollyVoice = mapVoiceToPolly(this.config.tts?.openai?.voice);
        inlineTwiml = this.generateNotifyTwiml(initialMessage, pollyVoice);
        console.log(
          `[voice-call] Using inline TwiML for notify mode (voice: ${pollyVoice})`,
@@ -210,11 +210,13 @@ export class CallManager {
      this.addTranscriptEntry(call, "bot", text);

      // Play TTS
+      const voice =
+        this.provider?.name === "twilio" ? this.config.tts?.openai?.voice : undefined;
      await this.provider.playTts({
        callId,
        providerCallId: call.providerCallId,
        text,
-        voice: this.config.tts.voice,
+        voice,
      });

      return { success: true };
@@ -68,7 +68,7 @@ export async function initiateCall(
    // For notify mode with a message, use inline TwiML with <Say>.
    let inlineTwiml: string | undefined;
    if (mode === "notify" && initialMessage) {
-      const pollyVoice = mapVoiceToPolly(ctx.config.tts.voice);
+      const pollyVoice = mapVoiceToPolly(ctx.config.tts?.openai?.voice);
      inlineTwiml = generateNotifyTwiml(initialMessage, pollyVoice);
      console.log(`[voice-call] Using inline TwiML for notify mode (voice: ${pollyVoice})`);
    }
@@ -120,11 +120,13 @@ export async function speak(

    addTranscriptEntry(call, "bot", text);

+    const voice =
+      ctx.provider?.name === "twilio" ? ctx.config.tts?.openai?.voice : undefined;
    await ctx.provider.playTts({
      callId,
      providerCallId: call.providerCallId,
      text,
-      voice: ctx.config.tts.voice,
+      voice,
    });

    return { success: true };
@@ -244,4 +246,3 @@ export async function endCall(
    return { success: false, error: err instanceof Error ? err.message : String(err) };
  }
 }
-
@@ -15,9 +15,9 @@ import type {
  WebhookVerificationResult,
 } from "../types.js";
 import { escapeXml, mapVoiceToPolly } from "../voice-mapping.js";
+import { chunkAudio } from "../telephony-audio.js";
+import type { TelephonyTtsProvider } from "../telephony-tts.js";
 import type { VoiceCallProvider } from "./base.js";
-import type { OpenAITTSProvider } from "./tts-openai.js";
-import { chunkAudio } from "./tts-openai.js";
 import { twilioApiRequest } from "./twilio/api.js";
 import { verifyTwilioProviderWebhook } from "./twilio/webhook.js";

@@ -53,8 +53,8 @@ export class TwilioProvider implements VoiceCallProvider {
  /** Current public webhook URL (set when tunnel starts or from config) */
  private currentPublicUrl: string | null = null;

-  /** Optional OpenAI TTS provider for streaming TTS */
-  private ttsProvider: OpenAITTSProvider | null = null;
+  /** Optional telephony TTS provider for streaming TTS */
+  private ttsProvider: TelephonyTtsProvider | null = null;

  /** Optional media stream handler for sending audio */
  private mediaStreamHandler: MediaStreamHandler | null = null;
@@ -119,7 +119,7 @@ export class TwilioProvider implements VoiceCallProvider {
    return this.currentPublicUrl;
  }

-  setTTSProvider(provider: OpenAITTSProvider): void {
+  setTTSProvider(provider: TelephonyTtsProvider): void {
    this.ttsProvider = provider;
  }

@@ -454,13 +454,13 @@ export class TwilioProvider implements VoiceCallProvider {
   * Play TTS audio via Twilio.
   *
   * Two modes:
-   * 1. OpenAI TTS + Media Streams: If TTS provider and media stream are available,
-   *    generates audio via OpenAI and streams it through WebSocket (preferred).
+   * 1. Core TTS + Media Streams: If TTS provider and media stream are available,
+   *    generates audio via core TTS and streams it through WebSocket (preferred).
   * 2. TwiML <Say>: Falls back to Twilio's native TTS with Polly voices.
   *    Note: This may not work on all Twilio accounts.
   */
  async playTts(input: PlayTtsInput): Promise<void> {
-    // Try OpenAI TTS via media stream first (if configured)
+    // Try telephony TTS via media stream first (if configured)
    const streamSid = this.callStreamMap.get(input.providerCallId);
    if (this.ttsProvider && this.mediaStreamHandler && streamSid) {
      try {
@@ -468,7 +468,7 @@ export class TwilioProvider implements VoiceCallProvider {
        return;
      } catch (err) {
        console.warn(
-          `[voice-call] OpenAI TTS failed, falling back to Twilio <Say>:`,
+          `[voice-call] Telephony TTS failed, falling back to Twilio <Say>:`,
          err instanceof Error ? err.message : err,
        );
        // Fall through to TwiML <Say> fallback
@@ -484,7 +484,7 @@ export class TwilioProvider implements VoiceCallProvider {
    }

    console.warn(
-      "[voice-call] Using TwiML <Say> fallback - OpenAI TTS not configured or media stream not active",
+      "[voice-call] Using TwiML <Say> fallback - telephony TTS not configured or media stream not active",
    );

    const pollyVoice = mapVoiceToPolly(input.voice);
@@ -502,8 +502,8 @@ export class TwilioProvider implements VoiceCallProvider {
  }

  /**
-   * Play TTS via OpenAI and Twilio Media Streams.
-   * Generates audio with OpenAI TTS, converts to mu-law, and streams via WebSocket.
+   * Play TTS via core TTS and Twilio Media Streams.
+   * Generates audio with core TTS, converts to mu-law, and streams via WebSocket.
   * Uses a jitter buffer to smooth out timing variations.
   */
  private async playTtsViaStream(
@@ -514,8 +514,8 @@ export class TwilioProvider implements VoiceCallProvider {
      throw new Error("TTS provider and media stream handler required");
    }

-    // Generate audio with OpenAI TTS (returns mu-law at 8kHz)
-    const muLawAudio = await this.ttsProvider.synthesizeForTwilio(text);
+    // Generate audio with core TTS (returns mu-law at 8kHz)
+    const muLawAudio = await this.ttsProvider.synthesizeForTelephony(text);

    // Stream audio in 20ms chunks (160 bytes at 8kHz mu-law)
    const CHUNK_SIZE = 160;
@@ -6,8 +6,9 @@ import type { VoiceCallProvider } from "./providers/base.js";
 import { MockProvider } from "./providers/mock.js";
 import { PlivoProvider } from "./providers/plivo.js";
 import { TelnyxProvider } from "./providers/telnyx.js";
-import { OpenAITTSProvider } from "./providers/tts-openai.js";
 import { TwilioProvider } from "./providers/twilio.js";
+import type { TelephonyTtsRuntime } from "./telephony-tts.js";
+import { createTelephonyTtsProvider } from "./telephony-tts.js";
 import { startTunnel, type TunnelResult } from "./tunnel.js";
 import {
  cleanupTailscaleExposure,
@@ -81,9 +82,10 @@ function resolveProvider(config: VoiceCallConfig): VoiceCallProvider {
 export async function createVoiceCallRuntime(params: {
  config: VoiceCallConfig;
  coreConfig: CoreConfig;
+  ttsRuntime?: TelephonyTtsRuntime;
  logger?: Logger;
 }): Promise<VoiceCallRuntime> {
-  const { config, coreConfig, logger } = params;
+  const { config, coreConfig, ttsRuntime, logger } = params;
  const log = logger ?? {
    info: console.log,
    warn: console.warn,
@@ -149,27 +151,24 @@ export async function createVoiceCallRuntime(params: {

  if (provider.name === "twilio" && config.streaming?.enabled) {
    const twilioProvider = provider as TwilioProvider;
-    const openaiApiKey =
-      config.streaming.openaiApiKey || process.env.OPENAI_API_KEY;
-    if (openaiApiKey) {
+    if (ttsRuntime?.textToSpeechTelephony) {
      try {
-        const ttsProvider = new OpenAITTSProvider({
-          apiKey: openaiApiKey,
-          voice: config.tts.voice,
-          model: config.tts.model,
-          instructions: config.tts.instructions,
+        const ttsProvider = createTelephonyTtsProvider({
+          coreConfig,
+          ttsOverride: config.tts,
+          runtime: ttsRuntime,
        });
        twilioProvider.setTTSProvider(ttsProvider);
-        log.info("[voice-call] OpenAI TTS provider configured");
+        log.info("[voice-call] Telephony TTS provider configured");
      } catch (err) {
        log.warn(
-          `[voice-call] Failed to initialize OpenAI TTS: ${
+          `[voice-call] Failed to initialize telephony TTS: ${
            err instanceof Error ? err.message : String(err)
          }`,
        );
      }
    } else {
-      log.warn("[voice-call] OpenAI TTS key missing; streaming TTS disabled");
+      log.warn("[voice-call] Telephony TTS unavailable; streaming TTS disabled");
    }

    const mediaHandler = webhookServer.getMediaStreamHandler();
@@ -0,0 +1,88 @@
+const TELEPHONY_SAMPLE_RATE = 8000;
+
+function clamp16(value: number): number {
+  return Math.max(-32768, Math.min(32767, value));
+}
+
+/**
+ * Resample 16-bit PCM (little-endian mono) to 8kHz using linear interpolation.
+ */
+export function resamplePcmTo8k(input: Buffer, inputSampleRate: number): Buffer {
+  if (inputSampleRate === TELEPHONY_SAMPLE_RATE) return input;
+  const inputSamples = Math.floor(input.length / 2);
+  if (inputSamples === 0) return Buffer.alloc(0);
+
+  const ratio = inputSampleRate / TELEPHONY_SAMPLE_RATE;
+  const outputSamples = Math.floor(inputSamples / ratio);
+  const output = Buffer.alloc(outputSamples * 2);
+
+  for (let i = 0; i < outputSamples; i++) {
+    const srcPos = i * ratio;
+    const srcIndex = Math.floor(srcPos);
+    const frac = srcPos - srcIndex;
+
+    const s0 = input.readInt16LE(srcIndex * 2);
+    const s1Index = Math.min(srcIndex + 1, inputSamples - 1);
+    const s1 = input.readInt16LE(s1Index * 2);
+
+    const sample = Math.round(s0 + frac * (s1 - s0));
+    output.writeInt16LE(clamp16(sample), i * 2);
+  }
+
+  return output;
+}
+
+/**
+ * Convert 16-bit PCM to 8-bit mu-law (G.711).
+ */
+export function pcmToMulaw(pcm: Buffer): Buffer {
+  const samples = Math.floor(pcm.length / 2);
+  const mulaw = Buffer.alloc(samples);
+
+  for (let i = 0; i < samples; i++) {
+    const sample = pcm.readInt16LE(i * 2);
+    mulaw[i] = linearToMulaw(sample);
+  }
+
+  return mulaw;
+}
+
+export function convertPcmToMulaw8k(
+  pcm: Buffer,
+  inputSampleRate: number,
+): Buffer {
+  const pcm8k = resamplePcmTo8k(pcm, inputSampleRate);
+  return pcmToMulaw(pcm8k);
+}
+
+/**
+ * Chunk audio buffer into 20ms frames for streaming (8kHz mono mu-law).
+ */
+export function chunkAudio(
+  audio: Buffer,
+  chunkSize = 160,
+): Generator<Buffer, void, unknown> {
+  return (function* () {
+    for (let i = 0; i < audio.length; i += chunkSize) {
+      yield audio.subarray(i, Math.min(i + chunkSize, audio.length));
+    }
+  })();
+}
+
+function linearToMulaw(sample: number): number {
+  const BIAS = 132;
+  const CLIP = 32635;
+
+  const sign = sample < 0 ? 0x80 : 0;
+  if (sample < 0) sample = -sample;
+  if (sample > CLIP) sample = CLIP;
+
+  sample += BIAS;
+  let exponent = 7;
+  for (let expMask = 0x4000; (sample & expMask) === 0 && exponent > 0; exponent--) {
+    expMask >>= 1;
+  }
+
+  const mantissa = (sample >> (exponent + 3)) & 0x0f;
+  return ~(sign | (exponent << 4) | mantissa) & 0xff;
+}
@@ -0,0 +1,95 @@
+import type { CoreConfig } from "./core-bridge.js";
+import type { VoiceCallTtsConfig } from "./config.js";
+import { convertPcmToMulaw8k } from "./telephony-audio.js";
+
+export type TelephonyTtsRuntime = {
+  textToSpeechTelephony: (params: {
+    text: string;
+    cfg: CoreConfig;
+    prefsPath?: string;
+  }) => Promise<{
+    success: boolean;
+    audioBuffer?: Buffer;
+    sampleRate?: number;
+    provider?: string;
+    error?: string;
+  }>;
+};
+
+export type TelephonyTtsProvider = {
+  synthesizeForTelephony: (text: string) => Promise<Buffer>;
+};
+
+export function createTelephonyTtsProvider(params: {
+  coreConfig: CoreConfig;
+  ttsOverride?: VoiceCallTtsConfig;
+  runtime: TelephonyTtsRuntime;
+}): TelephonyTtsProvider {
+  const { coreConfig, ttsOverride, runtime } = params;
+  const mergedConfig = applyTtsOverride(coreConfig, ttsOverride);
+
+  return {
+    synthesizeForTelephony: async (text: string) => {
+      const result = await runtime.textToSpeechTelephony({
+        text,
+        cfg: mergedConfig,
+      });
+
+      if (!result.success || !result.audioBuffer || !result.sampleRate) {
+        throw new Error(result.error ?? "TTS conversion failed");
+      }
+
+      return convertPcmToMulaw8k(result.audioBuffer, result.sampleRate);
+    },
+  };
+}
+
+function applyTtsOverride(
+  coreConfig: CoreConfig,
+  override?: VoiceCallTtsConfig,
+): CoreConfig {
+  if (!override) return coreConfig;
+
+  const base = coreConfig.messages?.tts;
+  const merged = mergeTtsConfig(base, override);
+  if (!merged) return coreConfig;
+
+  return {
+    ...coreConfig,
+    messages: {
+      ...(coreConfig.messages ?? {}),
+      tts: merged,
+    },
+  };
+}
+
+function mergeTtsConfig(
+  base?: VoiceCallTtsConfig,
+  override?: VoiceCallTtsConfig,
+): VoiceCallTtsConfig | undefined {
+  if (!base && !override) return undefined;
+  if (!override) return base;
+  if (!base) return override;
+  return deepMerge(base, override);
+}
+
+function deepMerge<T>(base: T, override: T): T {
+  if (!isPlainObject(base) || !isPlainObject(override)) {
+    return override;
+  }
+  const result: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (value === undefined) continue;
+    const existing = (base as Record<string, unknown>)[key];
+    if (isPlainObject(existing) && isPlainObject(value)) {
+      result[key] = deepMerge(existing, value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result as T;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
@@ -1,5 +1,5 @@
 import crypto from "node:crypto";
-import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import path from "node:path";
 import type { AgentTool, AgentToolResult } from "@mariozechner/pi-agent-core";
 import { Type } from "@sinclair/typebox";
@@ -27,6 +27,7 @@ import {
 } from "../infra/shell-env.js";
 import { enqueueSystemEvent } from "../infra/system-events.js";
 import { logInfo, logWarn } from "../logger.js";
+import { formatSpawnError, spawnWithFallback } from "../process/spawn-utils.js";
 import {
  type ProcessSession,
  type SessionStdin,
@@ -362,23 +363,38 @@ async function runExecProcess(opts: {
  let stdin: SessionStdin | undefined;

  if (opts.sandbox) {
-    child = spawn(
-      "docker",
-      buildDockerExecArgs({
-        containerName: opts.sandbox.containerName,
-        command: opts.command,
-        workdir: opts.containerWorkdir ?? opts.sandbox.containerWorkdir,
-        env: opts.env,
-        tty: opts.usePty,
-      }),
-      {
+    const { child: spawned } = await spawnWithFallback({
+      argv: [
+        "docker",
+        ...buildDockerExecArgs({
+          containerName: opts.sandbox.containerName,
+          command: opts.command,
+          workdir: opts.containerWorkdir ?? opts.sandbox.containerWorkdir,
+          env: opts.env,
+          tty: opts.usePty,
+        }),
+      ],
+      options: {
        cwd: opts.workdir,
        env: process.env,
        detached: process.platform !== "win32",
        stdio: ["pipe", "pipe", "pipe"],
        windowsHide: true,
      },
-    ) as ChildProcessWithoutNullStreams;
+      fallbacks: [
+        {
+          label: "no-detach",
+          options: { detached: false },
+        },
+      ],
+      onFallback: (err, fallback) => {
+        const errText = formatSpawnError(err);
+        const warning = `Warning: spawn failed (${errText}); retrying with ${fallback.label}.`;
+        logWarn(`exec: spawn failed (${errText}); retrying with ${fallback.label}.`);
+        opts.warnings.push(warning);
+      },
+    });
+    child = spawned as ChildProcessWithoutNullStreams;
    stdin = child.stdin;
  } else if (opts.usePty) {
    const { shell, args: shellArgs } = getShellConfig();
@@ -422,24 +438,56 @@ async function runExecProcess(opts: {
      const warning = `Warning: PTY spawn failed (${errText}); retrying without PTY for \`${opts.command}\`.`;
      logWarn(`exec: PTY spawn failed (${errText}); retrying without PTY for "${opts.command}".`);
      opts.warnings.push(warning);
-      child = spawn(shell, [...shellArgs, opts.command], {
+      const { child: spawned } = await spawnWithFallback({
+        argv: [shell, ...shellArgs, opts.command],
+        options: {
+          cwd: opts.workdir,
+          env: opts.env,
+          detached: process.platform !== "win32",
+          stdio: ["pipe", "pipe", "pipe"],
+          windowsHide: true,
+        },
+        fallbacks: [
+          {
+            label: "no-detach",
+            options: { detached: false },
+          },
+        ],
+        onFallback: (fallbackErr, fallback) => {
+          const fallbackText = formatSpawnError(fallbackErr);
+          const fallbackWarning = `Warning: spawn failed (${fallbackText}); retrying with ${fallback.label}.`;
+          logWarn(`exec: spawn failed (${fallbackText}); retrying with ${fallback.label}.`);
+          opts.warnings.push(fallbackWarning);
+        },
+      });
+      child = spawned as ChildProcessWithoutNullStreams;
+      stdin = child.stdin;
+    }
+  } else {
+    const { shell, args: shellArgs } = getShellConfig();
+    const { child: spawned } = await spawnWithFallback({
+      argv: [shell, ...shellArgs, opts.command],
+      options: {
        cwd: opts.workdir,
        env: opts.env,
        detached: process.platform !== "win32",
        stdio: ["pipe", "pipe", "pipe"],
        windowsHide: true,
-      }) as ChildProcessWithoutNullStreams;
-      stdin = child.stdin;
-    }
-  } else {
-    const { shell, args: shellArgs } = getShellConfig();
-    child = spawn(shell, [...shellArgs, opts.command], {
-      cwd: opts.workdir,
-      env: opts.env,
-      detached: process.platform !== "win32",
-      stdio: ["pipe", "pipe", "pipe"],
-      windowsHide: true,
-    }) as ChildProcessWithoutNullStreams;
+      },
+      fallbacks: [
+        {
+          label: "no-detach",
+          options: { detached: false },
+        },
+      ],
+      onFallback: (err, fallback) => {
+        const errText = formatSpawnError(err);
+        const warning = `Warning: spawn failed (${errText}); retrying with ${fallback.label}.`;
+        logWarn(`exec: spawn failed (${errText}); retrying with ${fallback.label}.`);
+        opts.warnings.push(warning);
+      },
+    });
+    child = spawned as ChildProcessWithoutNullStreams;
    stdin = child.stdin;
  }

@@ -333,7 +333,13 @@ export function createMessageTool(options?: MessageToolOptions): AnyAgentTool {
    name: "message",
    description,
    parameters: schema,
-    execute: async (_toolCallId, args) => {
+    execute: async (_toolCallId, args, signal) => {
+      // Check if already aborted before doing any work
+      if (signal?.aborted) {
+        const err = new Error("Message send aborted");
+        err.name = "AbortError";
+        throw err;
+      }
      const params = args as Record<string, unknown>;
      const cfg = options?.config ?? loadConfig();
      const action = readStringParam(params, "action", {
@@ -366,6 +372,9 @@ export function createMessageTool(options?: MessageToolOptions): AnyAgentTool {
              currentThreadTs: options?.currentThreadTs,
              replyToMode: options?.replyToMode,
              hasRepliedRef: options?.hasRepliedRef,
+              // Direct tool invocations should not add cross-context decoration.
+              // The agent is composing a message, not forwarding from another chat.
+              skipCrossContextDecoration: true,
            }
          : undefined;

@@ -379,6 +388,7 @@ export function createMessageTool(options?: MessageToolOptions): AnyAgentTool {
        agentId: options?.agentSessionKey
          ? resolveSessionAgentId({ sessionKey: options.agentSessionKey, config: cfg })
          : undefined,
+        abortSignal: signal,
      });

      const toolResult = getToolResult(result);
@@ -1,7 +1,8 @@
-import type { ReasoningLevel } from "../thinking.js";
+import type { NoticeLevel, ReasoningLevel } from "../thinking.js";
 import {
  type ElevatedLevel,
  normalizeElevatedLevel,
+  normalizeNoticeLevel,
  normalizeReasoningLevel,
  normalizeThinkLevel,
  normalizeVerboseLevel,
@@ -112,6 +113,22 @@ export function extractVerboseDirective(body?: string): {
  };
 }

+export function extractNoticeDirective(body?: string): {
+  cleaned: string;
+  noticeLevel?: NoticeLevel;
+  rawLevel?: string;
+  hasDirective: boolean;
+} {
+  if (!body) return { cleaned: "", hasDirective: false };
+  const extracted = extractLevelDirective(body, ["notice", "notices"], normalizeNoticeLevel);
+  return {
+    cleaned: extracted.cleaned,
+    noticeLevel: extracted.level,
+    rawLevel: extracted.rawLevel,
+    hasDirective: extracted.hasDirective,
+  };
+}
+
 export function extractElevatedDirective(body?: string): {
  cleaned: string;
  elevatedLevel?: ElevatedLevel;
@@ -152,5 +169,5 @@ export function extractStatusDirective(body?: string): {
  return extractSimpleDirective(body, ["status"]);
 }

-export type { ElevatedLevel, ReasoningLevel, ThinkLevel, VerboseLevel };
+export type { ElevatedLevel, NoticeLevel, ReasoningLevel, ThinkLevel, VerboseLevel };
 export { extractExecDirective } from "./exec/directive.js";
@@ -1,5 +1,6 @@
 export type ThinkLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
 export type VerboseLevel = "off" | "on" | "full";
+export type NoticeLevel = "off" | "on" | "full";
 export type ElevatedLevel = "off" | "on" | "ask" | "full";
 export type ElevatedMode = "off" | "ask" | "full";
 export type ReasoningLevel = "off" | "on" | "stream";
@@ -93,6 +94,16 @@ export function normalizeVerboseLevel(raw?: string | null): VerboseLevel | undef
  return undefined;
 }

+// Normalize system notice flags used to toggle system notifications.
+export function normalizeNoticeLevel(raw?: string | null): NoticeLevel | undefined {
+  if (!raw) return undefined;
+  const key = raw.toLowerCase();
+  if (["off", "false", "no", "0"].includes(key)) return "off";
+  if (["full", "all", "everything"].includes(key)) return "full";
+  if (["on", "minimal", "true", "yes", "1"].includes(key)) return "on";
+  return undefined;
+}
+
 // Normalize response-usage display modes used to toggle per-response usage footers.
 export function normalizeUsageDisplay(raw?: string | null): UsageDisplayLevel | undefined {
  if (!raw) return undefined;
@@ -240,6 +240,12 @@ export type ChannelThreadingToolContext = {
  currentThreadTs?: string;
  replyToMode?: "off" | "first" | "all";
  hasRepliedRef?: { value: boolean };
+  /**
+   * When true, skip cross-context decoration (e.g., "[from X]" prefix).
+   * Use this for direct tool invocations where the agent is composing a new message,
+   * not forwarding/relaying a message from another conversation.
+   */
+  skipCrossContextDecoration?: boolean;
 };

 export type ChannelMessagingAdapter = {
@@ -59,6 +59,17 @@ export const CONFIG_PATH_CLAWDBOT = resolveConfigPath();

 export const DEFAULT_GATEWAY_PORT = 18789;

+/**
+ * Gateway lock directory (ephemeral).
+ * Default: os.tmpdir()/clawdbot-<uid> (uid suffix when available).
+ */
+export function resolveGatewayLockDir(tmpdir: () => string = os.tmpdir): string {
+  const base = tmpdir();
+  const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+  const suffix = uid != null ? `clawdbot-${uid}` : "clawdbot";
+  return path.join(base, suffix);
+}
+
 const OAUTH_FILENAME = "oauth.json";

 /**
@@ -118,6 +118,8 @@ export type TelegramAccountConfig = {
  reactionLevel?: "off" | "ack" | "minimal" | "extensive";
  /** Heartbeat visibility settings for this channel. */
  heartbeat?: ChannelHeartbeatVisibilityConfig;
+  /** Controls whether link previews are shown in outbound messages. Default: true. */
+  linkPreview?: boolean;
 };

 export type TelegramTopicConfig = {
@@ -125,6 +125,7 @@ export const TelegramAccountSchemaBase = z
    reactionNotifications: z.enum(["off", "own", "all"]).optional(),
    reactionLevel: z.enum(["off", "ack", "minimal", "extensive"]).optional(),
    heartbeat: ChannelHeartbeatVisibilitySchema,
+    linkPreview: z.boolean().optional(),
  })
  .strict();

@@ -1,77 +1,28 @@
-import { beforeEach, describe, expect, test, vi } from "vitest";
+import { describe, expect, it } from "vitest";

-const testTailnetIPv4 = { value: undefined as string | undefined };
-const testTailnetIPv6 = { value: undefined as string | undefined };
+import { resolveGatewayListenHosts } from "./net.js";

-vi.mock("../infra/tailnet.js", () => ({
-  pickPrimaryTailnetIPv4: () => testTailnetIPv4.value,
-  pickPrimaryTailnetIPv6: () => testTailnetIPv6.value,
-}));
-
-import { isLocalGatewayAddress, resolveGatewayClientIp } from "./net.js";
-
-describe("gateway net", () => {
-  beforeEach(() => {
-    testTailnetIPv4.value = undefined;
-    testTailnetIPv6.value = undefined;
-  });
-
-  test("treats loopback as local", () => {
-    expect(isLocalGatewayAddress("127.0.0.1")).toBe(true);
-    expect(isLocalGatewayAddress("127.0.1.1")).toBe(true);
-    expect(isLocalGatewayAddress("::1")).toBe(true);
-    expect(isLocalGatewayAddress("::ffff:127.0.0.1")).toBe(true);
-  });
-
-  test("treats local tailnet IPv4 as local", () => {
-    testTailnetIPv4.value = "100.64.0.1";
-    expect(isLocalGatewayAddress("100.64.0.1")).toBe(true);
-    expect(isLocalGatewayAddress("::ffff:100.64.0.1")).toBe(true);
-  });
-
-  test("ignores non-matching tailnet IPv4", () => {
-    testTailnetIPv4.value = "100.64.0.1";
-    expect(isLocalGatewayAddress("100.64.0.2")).toBe(false);
-  });
-
-  test("treats local tailnet IPv6 as local", () => {
-    testTailnetIPv6.value = "fd7a:115c:a1e0::123";
-    expect(isLocalGatewayAddress("fd7a:115c:a1e0::123")).toBe(true);
-  });
-
-  test("uses forwarded-for when remote is a trusted proxy", () => {
-    const clientIp = resolveGatewayClientIp({
-      remoteAddr: "10.0.0.2",
-      forwardedFor: "203.0.113.9, 10.0.0.2",
-      trustedProxies: ["10.0.0.2"],
+describe("resolveGatewayListenHosts", () => {
+  it("returns the input host when not loopback", async () => {
+    const hosts = await resolveGatewayListenHosts("0.0.0.0", {
+      canBindToHost: async () => {
+        throw new Error("should not be called");
+      },
    });
-    expect(clientIp).toBe("203.0.113.9");
+    expect(hosts).toEqual(["0.0.0.0"]);
  });

-  test("ignores forwarded-for from untrusted proxies", () => {
-    const clientIp = resolveGatewayClientIp({
-      remoteAddr: "10.0.0.3",
-      forwardedFor: "203.0.113.9",
-      trustedProxies: ["10.0.0.2"],
+  it("adds ::1 when IPv6 loopback is available", async () => {
+    const hosts = await resolveGatewayListenHosts("127.0.0.1", {
+      canBindToHost: async () => true,
    });
-    expect(clientIp).toBe("10.0.0.3");
+    expect(hosts).toEqual(["127.0.0.1", "::1"]);
  });

-  test("normalizes trusted proxy IPs and strips forwarded ports", () => {
-    const clientIp = resolveGatewayClientIp({
-      remoteAddr: "::ffff:10.0.0.2",
-      forwardedFor: "203.0.113.9:1234",
-      trustedProxies: ["10.0.0.2"],
+  it("keeps only IPv4 loopback when IPv6 is unavailable", async () => {
+    const hosts = await resolveGatewayListenHosts("127.0.0.1", {
+      canBindToHost: async () => false,
    });
-    expect(clientIp).toBe("203.0.113.9");
-  });
-
-  test("falls back to x-real-ip when forwarded-for is missing", () => {
-    const clientIp = resolveGatewayClientIp({
-      remoteAddr: "10.0.0.2",
-      realIp: "203.0.113.10",
-      trustedProxies: ["10.0.0.2"],
-    });
-    expect(clientIp).toBe("203.0.113.10");
+    expect(hosts).toEqual(["127.0.0.1"]);
  });
 });
@@ -97,14 +97,14 @@ export async function resolveGatewayBindHost(

  if (mode === "loopback") {
    // 127.0.0.1 rarely fails, but handle gracefully
-    if (await canBindTo("127.0.0.1")) return "127.0.0.1";
+    if (await canBindToHost("127.0.0.1")) return "127.0.0.1";
    return "0.0.0.0"; // extreme fallback
  }

  if (mode === "tailnet") {
    const tailnetIP = pickPrimaryTailnetIPv4();
-    if (tailnetIP && (await canBindTo(tailnetIP))) return tailnetIP;
-    if (await canBindTo("127.0.0.1")) return "127.0.0.1";
+    if (tailnetIP && (await canBindToHost(tailnetIP))) return tailnetIP;
+    if (await canBindToHost("127.0.0.1")) return "127.0.0.1";
    return "0.0.0.0";
  }

@@ -116,13 +116,13 @@ export async function resolveGatewayBindHost(
    const host = customHost?.trim();
    if (!host) return "0.0.0.0"; // invalid config → fall back to all

-    if (isValidIPv4(host) && (await canBindTo(host))) return host;
+    if (isValidIPv4(host) && (await canBindToHost(host))) return host;
    // Custom IP failed → fall back to LAN
    return "0.0.0.0";
  }

  if (mode === "auto") {
-    if (await canBindTo("127.0.0.1")) return "127.0.0.1";
+    if (await canBindToHost("127.0.0.1")) return "127.0.0.1";
    return "0.0.0.0";
  }

@@ -136,7 +136,7 @@ export async function resolveGatewayBindHost(
 * @param host - The host address to test
 * @returns True if we can successfully bind to this address
 */
-async function canBindTo(host: string): Promise<boolean> {
+export async function canBindToHost(host: string): Promise<boolean> {
  return new Promise((resolve) => {
    const testServer = net.createServer();
    testServer.once("error", () => {
@@ -151,6 +151,16 @@ async function canBindTo(host: string): Promise<boolean> {
  });
 }

+export async function resolveGatewayListenHosts(
+  bindHost: string,
+  opts?: { canBindToHost?: (host: string) => Promise<boolean> },
+): Promise<string[]> {
+  if (bindHost !== "127.0.0.1") return [bindHost];
+  const canBind = opts?.canBindToHost ?? canBindToHost;
+  if (await canBind("::1")) return [bindHost, "::1"];
+  return [bindHost];
+}
+
 /**
 * Validate if a string is a valid IPv4 address.
 *
@@ -28,6 +28,7 @@ export function createGatewayCloseHandler(params: {
  browserControl: { stop: () => Promise<void> } | null;
  wss: WebSocketServer;
  httpServer: HttpServer;
+  httpServers?: HttpServer[];
 }) {
  return async (opts?: { reason?: string; restartExpectedMs?: number | null }) => {
    const reasonRaw = typeof opts?.reason === "string" ? opts.reason.trim() : "";
@@ -108,14 +109,20 @@ export function createGatewayCloseHandler(params: {
      await params.browserControl.stop().catch(() => {});
    }
    await new Promise<void>((resolve) => params.wss.close(() => resolve()));
-    const httpServer = params.httpServer as HttpServer & {
-      closeIdleConnections?: () => void;
-    };
-    if (typeof httpServer.closeIdleConnections === "function") {
-      httpServer.closeIdleConnections();
+    const servers =
+      params.httpServers && params.httpServers.length > 0
+        ? params.httpServers
+        : [params.httpServer];
+    for (const server of servers) {
+      const httpServer = server as HttpServer & {
+        closeIdleConnections?: () => void;
+      };
+      if (typeof httpServer.closeIdleConnections === "function") {
+        httpServer.closeIdleConnections();
+      }
+      await new Promise<void>((resolve, reject) =>
+        httpServer.close((err) => (err ? reject(err) : resolve())),
+      );
    }
-    await new Promise<void>((resolve, reject) =>
-      params.httpServer.close((err) => (err ? reject(err) : resolve())),
-    );
  };
 }
@@ -10,6 +10,7 @@ import type { ChatAbortControllerEntry } from "./chat-abort.js";
 import type { HooksConfigResolved } from "./hooks.js";
 import { createGatewayHooksRequestHandler } from "./server/hooks.js";
 import { listenGatewayHttpServer } from "./server/http-listen.js";
+import { resolveGatewayListenHosts } from "./net.js";
 import { createGatewayPluginRequestHandler } from "./server/plugins-http.js";
 import type { GatewayWsClient } from "./server/ws-types.js";
 import { createGatewayBroadcaster } from "./server-broadcast.js";
@@ -38,11 +39,14 @@ export async function createGatewayRuntimeState(params: {
  canvasHostEnabled: boolean;
  allowCanvasHostInTests?: boolean;
  logCanvas: { info: (msg: string) => void; warn: (msg: string) => void };
+  log: { info: (msg: string) => void; warn: (msg: string) => void };
  logHooks: ReturnType<typeof createSubsystemLogger>;
  logPlugins: ReturnType<typeof createSubsystemLogger>;
 }): Promise<{
  canvasHost: CanvasHostHandler | null;
  httpServer: HttpServer;
+  httpServers: HttpServer[];
+  httpBindHosts: string[];
  wss: WebSocketServer;
  clients: Set<GatewayWsClient>;
  broadcast: (
@@ -100,30 +104,49 @@ export async function createGatewayRuntimeState(params: {
    log: params.logPlugins,
  });

-  const httpServer = createGatewayHttpServer({
-    canvasHost,
-    controlUiEnabled: params.controlUiEnabled,
-    controlUiBasePath: params.controlUiBasePath,
-    openAiChatCompletionsEnabled: params.openAiChatCompletionsEnabled,
-    openResponsesEnabled: params.openResponsesEnabled,
-    openResponsesConfig: params.openResponsesConfig,
-    handleHooksRequest,
-    handlePluginRequest,
-    resolvedAuth: params.resolvedAuth,
-    tlsOptions: params.gatewayTls?.enabled ? params.gatewayTls.tlsOptions : undefined,
-  });
-
-  await listenGatewayHttpServer({
-    httpServer,
-    bindHost: params.bindHost,
-    port: params.port,
-  });
+  const bindHosts = await resolveGatewayListenHosts(params.bindHost);
+  const httpServers: HttpServer[] = [];
+  const httpBindHosts: string[] = [];
+  for (const host of bindHosts) {
+    const httpServer = createGatewayHttpServer({
+      canvasHost,
+      controlUiEnabled: params.controlUiEnabled,
+      controlUiBasePath: params.controlUiBasePath,
+      openAiChatCompletionsEnabled: params.openAiChatCompletionsEnabled,
+      openResponsesEnabled: params.openResponsesEnabled,
+      openResponsesConfig: params.openResponsesConfig,
+      handleHooksRequest,
+      handlePluginRequest,
+      resolvedAuth: params.resolvedAuth,
+      tlsOptions: params.gatewayTls?.enabled ? params.gatewayTls.tlsOptions : undefined,
+    });
+    try {
+      await listenGatewayHttpServer({
+        httpServer,
+        bindHost: host,
+        port: params.port,
+      });
+      httpServers.push(httpServer);
+      httpBindHosts.push(host);
+    } catch (err) {
+      if (host === bindHosts[0]) throw err;
+      params.log.warn(
+        `gateway: failed to bind loopback alias ${host}:${params.port} (${String(err)})`,
+      );
+    }
+  }
+  const httpServer = httpServers[0];
+  if (!httpServer) {
+    throw new Error("Gateway HTTP server failed to start");
+  }

  const wss = new WebSocketServer({
    noServer: true,
    maxPayload: MAX_PAYLOAD_BYTES,
  });
-  attachGatewayUpgradeHandler({ httpServer, wss, canvasHost });
+  for (const server of httpServers) {
+    attachGatewayUpgradeHandler({ httpServer: server, wss, canvasHost });
+  }

  const clients = new Set<GatewayWsClient>();
  const { broadcast } = createGatewayBroadcaster({ clients });
@@ -140,6 +163,8 @@ export async function createGatewayRuntimeState(params: {
  return {
    canvasHost,
    httpServer,
+    httpServers,
+    httpBindHosts,
    wss,
    clients,
    broadcast,
@@ -7,6 +7,7 @@ import { getResolvedLoggerSettings } from "../logging.js";
 export function logGatewayStartup(params: {
  cfg: ReturnType<typeof loadConfig>;
  bindHost: string;
+  bindHosts?: string[];
  port: number;
  tlsEnabled?: boolean;
  log: { info: (msg: string, meta?: Record<string, unknown>) => void };
@@ -22,9 +23,16 @@ export function logGatewayStartup(params: {
    consoleMessage: `agent model: ${chalk.whiteBright(modelRef)}`,
  });
  const scheme = params.tlsEnabled ? "wss" : "ws";
+  const formatHost = (host: string) => (host.includes(":") ? `[${host}]` : host);
+  const hosts =
+    params.bindHosts && params.bindHosts.length > 0 ? params.bindHosts : [params.bindHost];
+  const primaryHost = hosts[0] ?? params.bindHost;
  params.log.info(
-    `listening on ${scheme}://${params.bindHost}:${params.port} (PID ${process.pid})`,
+    `listening on ${scheme}://${formatHost(primaryHost)}:${params.port} (PID ${process.pid})`,
  );
+  for (const host of hosts.slice(1)) {
+    params.log.info(`listening on ${scheme}://${formatHost(host)}:${params.port}`);
+  }
  params.log.info(`log file: ${getResolvedLoggerSettings().file}`);
  if (params.isNixMode) {
    params.log.info("gateway: running in Nix mode (config managed externally)");
@@ -263,6 +263,8 @@ export async function startGatewayServer(
  const {
    canvasHost,
    httpServer,
+    httpServers,
+    httpBindHosts,
    wss,
    clients,
    broadcast,
@@ -292,6 +294,7 @@ export async function startGatewayServer(
    canvasHostEnabled,
    allowCanvasHostInTests: opts.allowCanvasHostInTests,
    logCanvas,
+    log,
    logHooks,
    logPlugins,
  });
@@ -464,6 +467,7 @@ export async function startGatewayServer(
  logGatewayStartup({
    cfg: cfgAtStart,
    bindHost,
+    bindHosts: httpBindHosts,
    port,
    tlsEnabled: gatewayTls.enabled,
    log,
@@ -552,6 +556,7 @@ export async function startGatewayServer(
    browserControl,
    wss,
    httpServer,
+    httpServers,
  });

  return {
@@ -7,12 +7,13 @@ import path from "node:path";
 import { describe, expect, it, vi } from "vitest";

 import { acquireGatewayLock, GatewayLockError } from "./gateway-lock.js";
-import { resolveConfigPath, resolveStateDir } from "../config/paths.js";
+import { resolveConfigPath, resolveGatewayLockDir, resolveStateDir } from "../config/paths.js";

 async function makeEnv() {
  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-gateway-lock-"));
  const configPath = path.join(dir, "clawdbot.json");
  await fs.writeFile(configPath, "{}", "utf8");
+  await fs.mkdir(resolveGatewayLockDir(), { recursive: true });
  return {
    env: {
      ...process.env,
@@ -29,7 +30,8 @@ function resolveLockPath(env: NodeJS.ProcessEnv) {
  const stateDir = resolveStateDir(env);
  const configPath = resolveConfigPath(env, stateDir);
  const hash = createHash("sha1").update(configPath).digest("hex").slice(0, 8);
-  return { lockPath: path.join(stateDir, `gateway.${hash}.lock`), configPath };
+  const lockDir = resolveGatewayLockDir();
+  return { lockPath: path.join(lockDir, `gateway.${hash}.lock`), configPath };
 }

 function makeProcStat(pid: number, startTime: number) {
@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
 import fsSync from "node:fs";
 import path from "node:path";

-import { resolveConfigPath, resolveStateDir } from "../config/paths.js";
+import { resolveConfigPath, resolveGatewayLockDir, resolveStateDir } from "../config/paths.js";

 const DEFAULT_TIMEOUT_MS = 5000;
 const DEFAULT_POLL_INTERVAL_MS = 100;
@@ -150,7 +150,8 @@ function resolveGatewayLockPath(env: NodeJS.ProcessEnv) {
  const stateDir = resolveStateDir(env);
  const configPath = resolveConfigPath(env, stateDir);
  const hash = createHash("sha1").update(configPath).digest("hex").slice(0, 8);
-  const lockPath = path.join(stateDir, `gateway.${hash}.lock`);
+  const lockDir = resolveGatewayLockDir();
+  const lockPath = path.join(lockDir, `gateway.${hash}.lock`);
  return { lockPath, configPath };
 }

@@ -321,6 +321,44 @@ describe("runMessageAction context isolation", () => {
      }),
    ).rejects.toThrow(/Cross-context messaging denied/);
  });
+
+  it("aborts send when abortSignal is already aborted", async () => {
+    const controller = new AbortController();
+    controller.abort();
+
+    await expect(
+      runMessageAction({
+        cfg: slackConfig,
+        action: "send",
+        params: {
+          channel: "slack",
+          target: "#C12345678",
+          message: "hi",
+        },
+        dryRun: true,
+        abortSignal: controller.signal,
+      }),
+    ).rejects.toMatchObject({ name: "AbortError" });
+  });
+
+  it("aborts broadcast when abortSignal is already aborted", async () => {
+    const controller = new AbortController();
+    controller.abort();
+
+    await expect(
+      runMessageAction({
+        cfg: slackConfig,
+        action: "broadcast",
+        params: {
+          targets: ["channel:C12345678"],
+          channel: "slack",
+          message: "hi",
+        },
+        dryRun: true,
+        abortSignal: controller.signal,
+      }),
+    ).rejects.toMatchObject({ name: "AbortError" });
+  });
 });

 describe("runMessageAction sendAttachment hydration", () => {
@@ -64,6 +64,7 @@ export type RunMessageActionParams = {
  sessionKey?: string;
  agentId?: string;
  dryRun?: boolean;
+  abortSignal?: AbortSignal;
 };

 export type MessageActionRunResult =
@@ -507,6 +508,7 @@ type ResolvedActionContext = {
  input: RunMessageActionParams;
  agentId?: string;
  resolvedTarget?: ResolvedMessagingTarget;
+  abortSignal?: AbortSignal;
 };
 function resolveGateway(input: RunMessageActionParams): MessageActionRunnerGateway | undefined {
  if (!input.gateway) return undefined;
@@ -524,6 +526,7 @@ async function handleBroadcastAction(
  input: RunMessageActionParams,
  params: Record<string, unknown>,
 ): Promise<MessageActionRunResult> {
+  throwIfAborted(input.abortSignal);
  const broadcastEnabled = input.cfg.tools?.message?.broadcast?.enabled !== false;
  if (!broadcastEnabled) {
    throw new Error("Broadcast is disabled. Set tools.message.broadcast.enabled to true.");
@@ -548,8 +551,11 @@ async function handleBroadcastAction(
    error?: string;
    result?: MessageSendResult;
  }> = [];
+  const isAbortError = (err: unknown): boolean => err instanceof Error && err.name === "AbortError";
  for (const targetChannel of targetChannels) {
+    throwIfAborted(input.abortSignal);
    for (const target of rawTargets) {
+      throwIfAborted(input.abortSignal);
      try {
        const resolved = await resolveChannelTarget({
          cfg: input.cfg,
@@ -573,6 +579,7 @@ async function handleBroadcastAction(
          result: sendResult.kind === "send" ? sendResult.sendResult : undefined,
        });
      } catch (err) {
+        if (isAbortError(err)) throw err;
        results.push({
          channel: targetChannel,
          to: target,
@@ -592,8 +599,28 @@ async function handleBroadcastAction(
  };
 }

+function throwIfAborted(abortSignal?: AbortSignal): void {
+  if (abortSignal?.aborted) {
+    const err = new Error("Message send aborted");
+    err.name = "AbortError";
+    throw err;
+  }
+}
+
 async function handleSendAction(ctx: ResolvedActionContext): Promise<MessageActionRunResult> {
-  const { cfg, params, channel, accountId, dryRun, gateway, input, agentId, resolvedTarget } = ctx;
+  const {
+    cfg,
+    params,
+    channel,
+    accountId,
+    dryRun,
+    gateway,
+    input,
+    agentId,
+    resolvedTarget,
+    abortSignal,
+  } = ctx;
+  throwIfAborted(abortSignal);
  const action: ChannelMessageActionName = "send";
  const to = readStringParam(params, "to", { required: true });
  // Support media, path, and filePath parameters for attachments
@@ -676,6 +703,7 @@ async function handleSendAction(ctx: ResolvedActionContext): Promise<MessageActi
  }
  const mirrorMediaUrls =
    mergedMediaUrls.length > 0 ? mergedMediaUrls : mediaUrl ? [mediaUrl] : undefined;
+  throwIfAborted(abortSignal);
  const send = await executeSendAction({
    ctx: {
      cfg,
@@ -695,6 +723,7 @@ async function handleSendAction(ctx: ResolvedActionContext): Promise<MessageActi
              mediaUrls: mirrorMediaUrls,
            }
          : undefined,
+      abortSignal,
    },
    to,
    message,
@@ -718,7 +747,8 @@ async function handleSendAction(ctx: ResolvedActionContext): Promise<MessageActi
 }

 async function handlePollAction(ctx: ResolvedActionContext): Promise<MessageActionRunResult> {
-  const { cfg, params, channel, accountId, dryRun, gateway, input } = ctx;
+  const { cfg, params, channel, accountId, dryRun, gateway, input, abortSignal } = ctx;
+  throwIfAborted(abortSignal);
  const action: ChannelMessageActionName = "poll";
  const to = readStringParam(params, "to", { required: true });
  const question = readStringParam(params, "pollQuestion", {
@@ -777,7 +807,8 @@ async function handlePollAction(ctx: ResolvedActionContext): Promise<MessageActi
 }

 async function handlePluginAction(ctx: ResolvedActionContext): Promise<MessageActionRunResult> {
-  const { cfg, params, channel, accountId, dryRun, gateway, input } = ctx;
+  const { cfg, params, channel, accountId, dryRun, gateway, input, abortSignal } = ctx;
+  throwIfAborted(abortSignal);
  const action = input.action as Exclude<ChannelMessageActionName, "send" | "poll" | "broadcast">;
  if (dryRun) {
    return {
@@ -930,6 +961,7 @@ export async function runMessageAction(
      input,
      agentId: resolvedAgentId,
      resolvedTarget,
+      abortSignal: input.abortSignal,
    });
  }

@@ -942,6 +974,7 @@ export async function runMessageAction(
      dryRun,
      gateway,
      input,
+      abortSignal: input.abortSignal,
    });
  }

@@ -953,5 +986,6 @@ export async function runMessageAction(
    dryRun,
    gateway,
    input,
+    abortSignal: input.abortSignal,
  });
 }
@@ -50,6 +50,7 @@ type MessageSendParams = {
    text?: string;
    mediaUrls?: string[];
  };
+  abortSignal?: AbortSignal;
 };

 export type MessageSendResult = {
@@ -167,6 +168,7 @@ export async function sendMessage(params: MessageSendParams): Promise<MessageSen
      gifPlayback: params.gifPlayback,
      deps: params.deps,
      bestEffort: params.bestEffort,
+      abortSignal: params.abortSignal,
      mirror: params.mirror
        ? {
            ...params.mirror,
@@ -119,6 +119,8 @@ export async function buildCrossContextDecoration(params: {
  accountId?: string | null;
 }): Promise<CrossContextDecoration | null> {
  if (!params.toolContext?.currentChannelId) return null;
+  // Skip decoration for direct tool sends (agent composing, not forwarding)
+  if (params.toolContext.skipCrossContextDecoration) return null;
  if (!isCrossContextTarget(params)) return null;

  const markerConfig = params.cfg.tools?.message?.crossContext?.marker;
@@ -131,11 +133,11 @@ export async function buildCrossContextDecoration(params: {
      targetId: params.toolContext.currentChannelId,
      accountId: params.accountId ?? undefined,
    })) ?? params.toolContext.currentChannelId;
+  // Don't force group formatting here; currentChannelId can be a DM or a group.
  const originLabel = formatTargetDisplay({
    channel: params.channel,
    target: params.toolContext.currentChannelId,
    display: currentName,
-    kind: "group",
  });
  const prefixTemplate = markerConfig?.prefix ?? "[from {channel}] ";
  const suffixTemplate = markerConfig?.suffix ?? "";
@@ -32,6 +32,7 @@ export type OutboundSendContext = {
    text?: string;
    mediaUrls?: string[];
  };
+  abortSignal?: AbortSignal;
 };

 function extractToolPayload(result: AgentToolResult<unknown>): unknown {
@@ -56,6 +57,14 @@ function extractToolPayload(result: AgentToolResult<unknown>): unknown {
  return result.content ?? result;
 }

+function throwIfAborted(abortSignal?: AbortSignal): void {
+  if (abortSignal?.aborted) {
+    const err = new Error("Message send aborted");
+    err.name = "AbortError";
+    throw err;
+  }
+}
+
 export async function executeSendAction(params: {
  ctx: OutboundSendContext;
  to: string;
@@ -70,6 +79,7 @@ export async function executeSendAction(params: {
  toolResult?: AgentToolResult<unknown>;
  sendResult?: MessageSendResult;
 }> {
+  throwIfAborted(params.ctx.abortSignal);
  if (!params.ctx.dryRun) {
    const handled = await dispatchChannelMessageAction({
      channel: params.ctx.channel,
@@ -103,6 +113,7 @@ export async function executeSendAction(params: {
    }
  }

+  throwIfAborted(params.ctx.abortSignal);
  const result: MessageSendResult = await sendMessage({
    cfg: params.ctx.cfg,
    to: params.to,
@@ -117,6 +128,7 @@ export async function executeSendAction(params: {
    deps: params.ctx.deps,
    gateway: params.ctx.gateway,
    mirror: params.ctx.mirror,
+    abortSignal: params.ctx.abortSignal,
  });

  return {
@@ -100,7 +100,12 @@ export function formatTargetDisplay(params: {
  if (!trimmedTarget) return trimmedTarget;
  if (trimmedTarget.startsWith("#") || trimmedTarget.startsWith("@")) return trimmedTarget;

-  const withoutPrefix = trimmedTarget.replace(/^telegram:/i, "");
+  const channelPrefix = `${params.channel}:`;
+  const withoutProvider = trimmedTarget.toLowerCase().startsWith(channelPrefix)
+    ? trimmedTarget.slice(channelPrefix.length)
+    : trimmedTarget;
+
+  const withoutPrefix = withoutProvider.replace(/^telegram:/i, "");
  if (/^channel:/i.test(withoutPrefix)) {
    return `#${withoutPrefix.replace(/^channel:/i, "")}`;
  }
@@ -119,14 +124,23 @@ function preserveTargetCase(channel: ChannelId, raw: string, normalized: string)
  return trimmed;
 }

-function detectTargetKind(raw: string, preferred?: TargetResolveKind): TargetResolveKind {
+function detectTargetKind(
+  channel: ChannelId,
+  raw: string,
+  preferred?: TargetResolveKind,
+): TargetResolveKind {
  if (preferred) return preferred;
  const trimmed = raw.trim();
  if (!trimmed) return "group";
+
  if (trimmed.startsWith("@") || /^<@!?/.test(trimmed) || /^user:/i.test(trimmed)) return "user";
-  if (trimmed.startsWith("#") || /^channel:/i.test(trimmed)) {
-    return "group";
+  if (trimmed.startsWith("#") || /^channel:/i.test(trimmed)) return "group";
+
+  // For some channels (e.g., BlueBubbles/iMessage), bare phone numbers are almost always DM targets.
+  if ((channel === "bluebubbles" || channel === "imessage") && /^\+?\d{6,}$/.test(trimmed)) {
+    return "user";
  }
+
  return "group";
 }

@@ -282,7 +296,7 @@ export async function resolveMessagingTarget(params: {
  const plugin = getChannelPlugin(params.channel);
  const providerLabel = plugin?.meta?.label ?? params.channel;
  const hint = plugin?.messaging?.targetResolver?.hint;
-  const kind = detectTargetKind(raw, params.preferredKind);
+  const kind = detectTargetKind(params.channel, raw, params.preferredKind);
  const normalized = normalizeTargetForProvider(params.channel, raw) ?? raw;
  const looksLikeTargetId = (): boolean => {
    const trimmed = raw.trim();
@@ -291,7 +305,12 @@ export async function resolveMessagingTarget(params: {
    if (lookup) return lookup(trimmed, normalized);
    if (/^(channel|group|user):/i.test(trimmed)) return true;
    if (/^[@#]/.test(trimmed)) return true;
-    if (/^\+?\d{6,}$/.test(trimmed)) return true;
+    if (/^\+?\d{6,}$/.test(trimmed)) {
+      // BlueBubbles/iMessage phone numbers should usually resolve via the directory to a DM chat,
+      // otherwise the provider may pick an existing group containing that handle.
+      if (params.channel === "bluebubbles" || params.channel === "imessage") return false;
+      return true;
+    }
    if (trimmed.includes("@thread")) return true;
    if (/^(conversation|user):/i.test(trimmed)) return true;
    return false;
@@ -353,6 +372,24 @@ export async function resolveMessagingTarget(params: {
      candidates: match.entries,
    };
  }
+  // For iMessage-style channels, allow sending directly to the normalized handle
+  // even if the directory doesn't contain an entry yet.
+  if (
+    (params.channel === "bluebubbles" || params.channel === "imessage") &&
+    /^\+?\d{6,}$/.test(query)
+  ) {
+    const directTarget = preserveTargetCase(params.channel, raw, normalized);
+    return {
+      ok: true,
+      target: {
+        to: directTarget,
+        kind,
+        display: stripTargetPrefixes(raw),
+        source: "normalized",
+      },
+    };
+  }
+
  return {
    ok: false,
    error: unknownTargetError(providerLabel, raw, hint),
@@ -367,16 +404,32 @@ export async function lookupDirectoryDisplay(params: {
  runtime?: RuntimeEnv;
 }): Promise<string | undefined> {
  const normalized = normalizeTargetForProvider(params.channel, params.targetId) ?? params.targetId;
-  const candidates = await getDirectoryEntries({
-    cfg: params.cfg,
-    channel: params.channel,
-    accountId: params.accountId,
-    kind: "group",
-    runtime: params.runtime,
-    preferLiveOnMiss: false,
-  });
-  const entry = candidates.find(
-    (candidate) => normalizeDirectoryEntryId(params.channel, candidate) === normalized,
-  );
+
+  // Targets can resolve to either peers (DMs) or groups. Try both.
+  const [groups, users] = await Promise.all([
+    getDirectoryEntries({
+      cfg: params.cfg,
+      channel: params.channel,
+      accountId: params.accountId,
+      kind: "group",
+      runtime: params.runtime,
+      preferLiveOnMiss: false,
+    }),
+    getDirectoryEntries({
+      cfg: params.cfg,
+      channel: params.channel,
+      accountId: params.accountId,
+      kind: "user",
+      runtime: params.runtime,
+      preferLiveOnMiss: false,
+    }),
+  ]);
+
+  const findMatch = (candidates: ChannelDirectoryEntry[]) =>
+    candidates.find(
+      (candidate) => normalizeDirectoryEntryId(params.channel, candidate) === normalized,
+    );
+
+  const entry = findMatch(groups) ?? findMatch(users);
  return entry?.name ?? entry?.handle ?? undefined;
 }
@@ -124,6 +124,7 @@ import { startWebLoginWithQr, waitForWebLogin } from "../../web/login-qr.js";
 import { sendMessageWhatsApp, sendPollWhatsApp } from "../../web/outbound.js";
 import { registerMemoryCli } from "../../cli/memory-cli.js";
 import { formatNativeDependencyHint } from "./native-deps.js";
+import { textToSpeechTelephony } from "../../tts/tts.js";

 import type { PluginRuntime } from "./types.js";

@@ -162,6 +163,9 @@ export function createPluginRuntime(): PluginRuntime {
      getImageMetadata,
      resizeToJpeg,
    },
+    tts: {
+      textToSpeechTelephony,
+    },
    tools: {
      createMemoryGetTool,
      createMemorySearchTool,
@@ -16,6 +16,7 @@ type UpsertChannelPairingRequest =
  typeof import("../../pairing/pairing-store.js").upsertChannelPairingRequest;
 type FetchRemoteMedia = typeof import("../../media/fetch.js").fetchRemoteMedia;
 type SaveMediaBuffer = typeof import("../../media/store.js").saveMediaBuffer;
+type TextToSpeechTelephony = typeof import("../../tts/tts.js").textToSpeechTelephony;
 type BuildMentionRegexes = typeof import("../../auto-reply/reply/mentions.js").buildMentionRegexes;
 type MatchesMentionPatterns =
  typeof import("../../auto-reply/reply/mentions.js").matchesMentionPatterns;
@@ -173,6 +174,9 @@ export type PluginRuntime = {
    getImageMetadata: GetImageMetadata;
    resizeToJpeg: ResizeToJpeg;
  };
+  tts: {
+    textToSpeechTelephony: TextToSpeechTelephony;
+  };
  tools: {
    createMemoryGetTool: CreateMemoryGetTool;
    createMemorySearchTool: CreateMemorySearchTool;
@@ -43,6 +43,7 @@ function setup(config: Record<string, unknown>): Registered {
    source: "test",
    config: {},
    pluginConfig: config,
+    runtime: { tts: { textToSpeechTelephony: vi.fn() } },
    logger: noopLogger,
    registerGatewayMethod: (method, handler) => methods.set(method, handler),
    registerTool: (tool) => tools.push(tool),
@@ -142,6 +143,7 @@ describe("voice-call plugin", () => {
      source: "test",
      config: {},
      pluginConfig: { provider: "mock" },
+      runtime: { tts: { textToSpeechTelephony: vi.fn() } },
      logger: noopLogger,
      registerGatewayMethod: () => {},
      registerTool: () => {},
@@ -4,6 +4,7 @@ import { promisify } from "node:util";

 import { danger, shouldLogVerbose } from "../globals.js";
 import { logDebug, logError } from "../logger.js";
+import { resolveCommandStdio } from "./spawn-utils.js";

 const execFileAsync = promisify(execFile);

@@ -78,19 +79,22 @@ export async function runCommandWithTimeout(
    if (resolvedEnv.npm_config_fund == null) resolvedEnv.npm_config_fund = "false";
  }

+  const stdio = resolveCommandStdio({ hasInput, preferInherit: true });
+  const child = spawn(argv[0], argv.slice(1), {
+    stdio,
+    cwd,
+    env: resolvedEnv,
+    windowsVerbatimArguments,
+  });
  // Spawn with inherited stdin (TTY) so tools like `pi` stay interactive when needed.
  return await new Promise((resolve, reject) => {
-    const child = spawn(argv[0], argv.slice(1), {
-      stdio: [hasInput ? "pipe" : "inherit", "pipe", "pipe"],
-      cwd,
-      env: resolvedEnv,
-      windowsVerbatimArguments,
-    });
    let stdout = "";
    let stderr = "";
    let settled = false;
    const timer = setTimeout(() => {
-      child.kill("SIGKILL");
+      if (typeof child.kill === "function") {
+        child.kill("SIGKILL");
+      }
    }, timeoutMs);

    if (hasInput && child.stdin) {
@@ -0,0 +1,64 @@
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+import type { ChildProcess } from "node:child_process";
+import { describe, expect, it, vi } from "vitest";
+
+import { spawnWithFallback } from "./spawn-utils.js";
+
+function createStubChild() {
+  const child = new EventEmitter() as ChildProcess;
+  child.stdin = new PassThrough() as ChildProcess["stdin"];
+  child.stdout = new PassThrough() as ChildProcess["stdout"];
+  child.stderr = new PassThrough() as ChildProcess["stderr"];
+  child.pid = 1234;
+  child.killed = false;
+  child.kill = vi.fn(() => true) as ChildProcess["kill"];
+  queueMicrotask(() => {
+    child.emit("spawn");
+  });
+  return child;
+}
+
+describe("spawnWithFallback", () => {
+  it("retries on EBADF using fallback options", async () => {
+    const spawnMock = vi
+      .fn()
+      .mockImplementationOnce(() => {
+        const err = new Error("spawn EBADF");
+        (err as NodeJS.ErrnoException).code = "EBADF";
+        throw err;
+      })
+      .mockImplementationOnce(() => createStubChild());
+
+    const result = await spawnWithFallback({
+      argv: ["echo", "ok"],
+      options: { stdio: ["pipe", "pipe", "pipe"] },
+      fallbacks: [{ label: "safe-stdin", options: { stdio: ["ignore", "pipe", "pipe"] } }],
+      spawnImpl: spawnMock,
+    });
+
+    expect(result.usedFallback).toBe(true);
+    expect(result.fallbackLabel).toBe("safe-stdin");
+    expect(spawnMock).toHaveBeenCalledTimes(2);
+    expect(spawnMock.mock.calls[0]?.[2]?.stdio).toEqual(["pipe", "pipe", "pipe"]);
+    expect(spawnMock.mock.calls[1]?.[2]?.stdio).toEqual(["ignore", "pipe", "pipe"]);
+  });
+
+  it("does not retry on non-EBADF errors", async () => {
+    const spawnMock = vi.fn().mockImplementationOnce(() => {
+      const err = new Error("spawn ENOENT");
+      (err as NodeJS.ErrnoException).code = "ENOENT";
+      throw err;
+    });
+
+    await expect(
+      spawnWithFallback({
+        argv: ["missing"],
+        options: { stdio: ["pipe", "pipe", "pipe"] },
+        fallbacks: [{ label: "safe-stdin", options: { stdio: ["ignore", "pipe", "pipe"] } }],
+        spawnImpl: spawnMock,
+      }),
+    ).rejects.toThrow(/ENOENT/);
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+  });
+});
@@ -0,0 +1,127 @@
+import type { ChildProcess, SpawnOptions } from "node:child_process";
+import { spawn } from "node:child_process";
+
+export type SpawnFallback = {
+  label: string;
+  options: SpawnOptions;
+};
+
+export type SpawnWithFallbackResult = {
+  child: ChildProcess;
+  usedFallback: boolean;
+  fallbackLabel?: string;
+};
+
+type SpawnWithFallbackParams = {
+  argv: string[];
+  options: SpawnOptions;
+  fallbacks?: SpawnFallback[];
+  spawnImpl?: typeof spawn;
+  retryCodes?: string[];
+  onFallback?: (err: unknown, fallback: SpawnFallback) => void;
+};
+
+const DEFAULT_RETRY_CODES = ["EBADF"];
+
+export function resolveCommandStdio(params: {
+  hasInput: boolean;
+  preferInherit: boolean;
+}): ["pipe" | "inherit" | "ignore", "pipe", "pipe"] {
+  const stdin = params.hasInput ? "pipe" : params.preferInherit ? "inherit" : "pipe";
+  return [stdin, "pipe", "pipe"];
+}
+
+export function formatSpawnError(err: unknown): string {
+  if (!(err instanceof Error)) return String(err);
+  const details = err as NodeJS.ErrnoException;
+  const parts: string[] = [];
+  const message = err.message?.trim();
+  if (message) parts.push(message);
+  if (details.code && !message?.includes(details.code)) parts.push(details.code);
+  if (details.syscall) parts.push(`syscall=${details.syscall}`);
+  if (typeof details.errno === "number") parts.push(`errno=${details.errno}`);
+  return parts.join(" ");
+}
+
+function shouldRetry(err: unknown, codes: string[]): boolean {
+  const code =
+    err && typeof err === "object" && "code" in err ? String((err as { code?: unknown }).code) : "";
+  return code.length > 0 && codes.includes(code);
+}
+
+async function spawnAndWaitForSpawn(
+  spawnImpl: typeof spawn,
+  argv: string[],
+  options: SpawnOptions,
+): Promise<ChildProcess> {
+  const child = spawnImpl(argv[0], argv.slice(1), options);
+
+  return await new Promise((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => {
+      child.removeListener("error", onError);
+      child.removeListener("spawn", onSpawn);
+    };
+    const finishResolve = () => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(child);
+    };
+    const onError = (err: unknown) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(err);
+    };
+    const onSpawn = () => {
+      finishResolve();
+    };
+    child.once("error", onError);
+    child.once("spawn", onSpawn);
+    // Ensure mocked spawns that never emit "spawn" don't stall.
+    process.nextTick(() => {
+      if (typeof child.pid === "number") {
+        finishResolve();
+      }
+    });
+  });
+}
+
+export async function spawnWithFallback(
+  params: SpawnWithFallbackParams,
+): Promise<SpawnWithFallbackResult> {
+  const spawnImpl = params.spawnImpl ?? spawn;
+  const retryCodes = params.retryCodes ?? DEFAULT_RETRY_CODES;
+  const baseOptions = { ...params.options };
+  const fallbacks = params.fallbacks ?? [];
+  const attempts: Array<{ label?: string; options: SpawnOptions }> = [
+    { options: baseOptions },
+    ...fallbacks.map((fallback) => ({
+      label: fallback.label,
+      options: { ...baseOptions, ...fallback.options },
+    })),
+  ];
+
+  let lastError: unknown;
+  for (let index = 0; index < attempts.length; index += 1) {
+    const attempt = attempts[index];
+    try {
+      const child = await spawnAndWaitForSpawn(spawnImpl, params.argv, attempt.options);
+      return {
+        child,
+        usedFallback: index > 0,
+        fallbackLabel: attempt.label,
+      };
+    } catch (err) {
+      lastError = err;
+      const nextFallback = fallbacks[index];
+      if (!nextFallback || !shouldRetry(err, retryCodes)) {
+        throw err;
+      }
+      params.onFallback?.(err, nextFallback);
+    }
+  }
+
+  throw lastError;
+}
@@ -151,6 +151,7 @@ export const dispatchTelegramMessage = async ({
          tableMode,
          chunkMode,
          onVoiceRecording: sendRecordVoice,
+          linkPreview: telegramCfg.linkPreview,
        });
      },
      onError: (err, info) => {
@@ -348,6 +348,7 @@ export const registerTelegramNativeCommands = ({
                  messageThreadId: resolvedThreadId,
                  tableMode,
                  chunkMode,
+                  linkPreview: telegramCfg.linkPreview,
                });
              },
              onError: (err, info) => {
@@ -108,4 +108,60 @@ describe("deliverReplies", () => {
      }),
    );
  });
+
+  it("includes link_preview_options when linkPreview is false", async () => {
+    const runtime = { error: vi.fn(), log: vi.fn() };
+    const sendMessage = vi.fn().mockResolvedValue({
+      message_id: 3,
+      chat: { id: "123" },
+    });
+    const bot = { api: { sendMessage } } as unknown as Bot;
+
+    await deliverReplies({
+      replies: [{ text: "Check https://example.com" }],
+      chatId: "123",
+      token: "tok",
+      runtime,
+      bot,
+      replyToMode: "off",
+      textLimit: 4000,
+      linkPreview: false,
+    });
+
+    expect(sendMessage).toHaveBeenCalledWith(
+      "123",
+      expect.any(String),
+      expect.objectContaining({
+        link_preview_options: { is_disabled: true },
+      }),
+    );
+  });
+
+  it("does not include link_preview_options when linkPreview is true", async () => {
+    const runtime = { error: vi.fn(), log: vi.fn() };
+    const sendMessage = vi.fn().mockResolvedValue({
+      message_id: 4,
+      chat: { id: "123" },
+    });
+    const bot = { api: { sendMessage } } as unknown as Bot;
+
+    await deliverReplies({
+      replies: [{ text: "Check https://example.com" }],
+      chatId: "123",
+      token: "tok",
+      runtime,
+      bot,
+      replyToMode: "off",
+      textLimit: 4000,
+      linkPreview: true,
+    });
+
+    expect(sendMessage).toHaveBeenCalledWith(
+      "123",
+      expect.any(String),
+      expect.not.objectContaining({
+        link_preview_options: expect.anything(),
+      }),
+    );
+  });
 });
@@ -36,8 +36,11 @@ export async function deliverReplies(params: {
  chunkMode?: ChunkMode;
  /** Callback invoked before sending a voice message to switch typing indicator. */
  onVoiceRecording?: () => Promise<void> | void;
+  /** Controls whether link previews are shown. Default: true (previews enabled). */
+  linkPreview?: boolean;
 }) {
-  const { replies, chatId, runtime, bot, replyToMode, textLimit, messageThreadId } = params;
+  const { replies, chatId, runtime, bot, replyToMode, textLimit, messageThreadId, linkPreview } =
+    params;
  const chunkMode = params.chunkMode ?? "length";
  const threadParams = buildTelegramThreadParams(messageThreadId);
  let hasReplied = false;
@@ -85,6 +88,7 @@ export async function deliverReplies(params: {
          messageThreadId,
          textMode: "html",
          plainText: chunk.text,
+          linkPreview,
        });
        if (replyToId && !hasReplied) {
          hasReplied = true;
@@ -180,6 +184,7 @@ export async function deliverReplies(params: {
            messageThreadId,
            textMode: "html",
            plainText: chunk.text,
+            linkPreview,
          });
          if (replyToId && !hasReplied) {
            hasReplied = true;
@@ -248,17 +253,22 @@ async function sendTelegramText(
    messageThreadId?: number;
    textMode?: "markdown" | "html";
    plainText?: string;
+    linkPreview?: boolean;
  },
 ): Promise<number | undefined> {
  const baseParams = buildTelegramSendParams({
    replyToMessageId: opts?.replyToMessageId,
    messageThreadId: opts?.messageThreadId,
  });
+  // Add link_preview_options when link preview is disabled.
+  const linkPreviewEnabled = opts?.linkPreview ?? true;
+  const linkPreviewOptions = linkPreviewEnabled ? undefined : { is_disabled: true };
  const textMode = opts?.textMode ?? "markdown";
  const htmlText = textMode === "html" ? text : markdownToTelegramHtml(text);
  try {
    const res = await bot.api.sendMessage(chatId, htmlText, {
      parse_mode: "HTML",
+      ...(linkPreviewOptions ? { link_preview_options: linkPreviewOptions } : {}),
      ...baseParams,
    });
    return res.message_id;
@@ -268,6 +278,7 @@ async function sendTelegramText(
      runtime.log?.(`telegram HTML parse failed; retrying without formatting: ${errText}`);
      const fallbackText = opts?.plainText ?? text;
      const res = await bot.api.sendMessage(chatId, fallbackText, {
+        ...(linkPreviewOptions ? { link_preview_options: linkPreviewOptions } : {}),
        ...baseParams,
      });
      return res.message_id;
@@ -152,6 +152,62 @@ describe("sendMessageTelegram", () => {
    expect(res.messageId).toBe("42");
  });

+  it("adds link_preview_options when previews are disabled in config", async () => {
+    const chatId = "123";
+    const sendMessage = vi.fn().mockResolvedValue({
+      message_id: 7,
+      chat: { id: chatId },
+    });
+    const api = { sendMessage } as unknown as {
+      sendMessage: typeof sendMessage;
+    };
+
+    loadConfig.mockReturnValue({
+      channels: { telegram: { linkPreview: false } },
+    });
+
+    await sendMessageTelegram(chatId, "hi", { token: "tok", api });
+
+    expect(sendMessage).toHaveBeenCalledWith(chatId, "hi", {
+      parse_mode: "HTML",
+      link_preview_options: { is_disabled: true },
+    });
+  });
+
+  it("keeps link_preview_options on plain-text fallback when disabled", async () => {
+    const chatId = "123";
+    const parseErr = new Error(
+      "400: Bad Request: can't parse entities: Can't find end of the entity starting at byte offset 9",
+    );
+    const sendMessage = vi
+      .fn()
+      .mockRejectedValueOnce(parseErr)
+      .mockResolvedValueOnce({
+        message_id: 42,
+        chat: { id: chatId },
+      });
+    const api = { sendMessage } as unknown as {
+      sendMessage: typeof sendMessage;
+    };
+
+    loadConfig.mockReturnValue({
+      channels: { telegram: { linkPreview: false } },
+    });
+
+    await sendMessageTelegram(chatId, "_oops_", {
+      token: "tok",
+      api,
+    });
+
+    expect(sendMessage).toHaveBeenNthCalledWith(1, chatId, "<i>oops</i>", {
+      parse_mode: "HTML",
+      link_preview_options: { is_disabled: true },
+    });
+    expect(sendMessage).toHaveBeenNthCalledWith(2, chatId, "_oops_", {
+      link_preview_options: { is_disabled: true },
+    });
+  });
+
  it("uses native fetch for BAN compatibility when api is omitted", async () => {
    const originalFetch = globalThis.fetch;
    const originalBun = (globalThis as { Bun?: unknown }).Bun;
@@ -198,20 +198,25 @@ export async function sendMessageTelegram(
  });
  const renderHtmlText = (value: string) => renderTelegramHtmlText(value, { textMode, tableMode });

+  // Resolve link preview setting from config (default: enabled).
+  const linkPreviewEnabled = account.config.linkPreview ?? true;
+  const linkPreviewOptions = linkPreviewEnabled ? undefined : { is_disabled: true };
+
  const sendTelegramText = async (
    rawText: string,
    params?: Record<string, unknown>,
    fallbackText?: string,
  ) => {
    const htmlText = renderHtmlText(rawText);
-    const sendParams = params
-      ? {
-          parse_mode: "HTML" as const,
-          ...params,
-        }
-      : {
-          parse_mode: "HTML" as const,
-        };
+    const baseParams = params ? { ...params } : {};
+    if (linkPreviewOptions) {
+      baseParams.link_preview_options = linkPreviewOptions;
+    }
+    const hasBaseParams = Object.keys(baseParams).length > 0;
+    const sendParams = {
+      parse_mode: "HTML" as const,
+      ...baseParams,
+    };
    const res = await request(() => api.sendMessage(chatId, htmlText, sendParams), "message").catch(
      async (err) => {
        // Telegram rejects malformed HTML (e.g., unsupported tags or entities).
@@ -222,7 +227,7 @@ export async function sendMessageTelegram(
            console.warn(`telegram HTML parse failed, retrying as plain text: ${errText}`);
          }
          const fallback = fallbackText ?? rawText;
-          const plainParams = params && Object.keys(params).length > 0 ? { ...params } : undefined;
+          const plainParams = hasBaseParams ? baseParams : undefined;
          return await request(
            () =>
              plainParams
@@ -109,13 +109,13 @@ describe("tts", () => {
  });

  describe("isValidOpenAIModel", () => {
-    it("accepts gpt-4o-mini-tts model", () => {
+    it("accepts supported models", () => {
      expect(isValidOpenAIModel("gpt-4o-mini-tts")).toBe(true);
+      expect(isValidOpenAIModel("tts-1")).toBe(true);
+      expect(isValidOpenAIModel("tts-1-hd")).toBe(true);
    });

-    it("rejects other models", () => {
-      expect(isValidOpenAIModel("tts-1")).toBe(false);
-      expect(isValidOpenAIModel("tts-1-hd")).toBe(false);
+    it("rejects unsupported models", () => {
      expect(isValidOpenAIModel("invalid")).toBe(false);
      expect(isValidOpenAIModel("")).toBe(false);
      expect(isValidOpenAIModel("gpt-4")).toBe(false);
@@ -123,9 +123,11 @@ describe("tts", () => {
  });

  describe("OPENAI_TTS_MODELS", () => {
-    it("contains only gpt-4o-mini-tts", () => {
+    it("contains supported models", () => {
      expect(OPENAI_TTS_MODELS).toContain("gpt-4o-mini-tts");
-      expect(OPENAI_TTS_MODELS).toHaveLength(1);
+      expect(OPENAI_TTS_MODELS).toContain("tts-1");
+      expect(OPENAI_TTS_MODELS).toContain("tts-1-hd");
+      expect(OPENAI_TTS_MODELS).toHaveLength(3);
    });

    it("is a non-empty array", () => {
@@ -76,6 +76,11 @@ const DEFAULT_OUTPUT = {
  voiceCompatible: false,
 };

+const TELEPHONY_OUTPUT = {
+  openai: { format: "pcm" as const, sampleRate: 24000 },
+  elevenlabs: { format: "pcm_22050", sampleRate: 22050 },
+};
+
 const TTS_AUTO_MODES = new Set<TtsAutoMode>(["off", "always", "inbound", "tagged"]);

 export type ResolvedTtsConfig = {
@@ -180,6 +185,16 @@ export type TtsResult = {
  voiceCompatible?: boolean;
 };

+export type TtsTelephonyResult = {
+  success: boolean;
+  audioBuffer?: Buffer;
+  error?: string;
+  latencyMs?: number;
+  provider?: string;
+  outputFormat?: string;
+  sampleRate?: number;
+};
+
 type TtsStatusEntry = {
  timestamp: number;
  success: boolean;
@@ -736,7 +751,17 @@ function parseTtsDirectives(
  };
 }

-export const OPENAI_TTS_MODELS = ["gpt-4o-mini-tts"] as const;
+export const OPENAI_TTS_MODELS = ["gpt-4o-mini-tts", "tts-1", "tts-1-hd"] as const;
+
+/**
+ * Custom OpenAI-compatible TTS endpoint.
+ * When set, model/voice validation is relaxed to allow non-OpenAI models.
+ * Example: OPENAI_TTS_BASE_URL=http://localhost:8880/v1
+ */
+const OPENAI_TTS_BASE_URL = (
+  process.env.OPENAI_TTS_BASE_URL?.trim() || "https://api.openai.com/v1"
+).replace(/\/+$/, "");
+const isCustomOpenAIEndpoint = OPENAI_TTS_BASE_URL !== "https://api.openai.com/v1";
 export const OPENAI_TTS_VOICES = [
  "alloy",
  "ash",
@@ -752,10 +777,14 @@ export const OPENAI_TTS_VOICES = [
 type OpenAiTtsVoice = (typeof OPENAI_TTS_VOICES)[number];

 function isValidOpenAIModel(model: string): boolean {
+  // Allow any model when using custom endpoint (e.g., Kokoro, LocalAI)
+  if (isCustomOpenAIEndpoint) return true;
  return OPENAI_TTS_MODELS.includes(model as (typeof OPENAI_TTS_MODELS)[number]);
 }

 function isValidOpenAIVoice(voice: string): voice is OpenAiTtsVoice {
+  // Allow any voice when using custom endpoint (e.g., Kokoro Chinese voices)
+  if (isCustomOpenAIEndpoint) return true;
  return OPENAI_TTS_VOICES.includes(voice as OpenAiTtsVoice);
 }

@@ -966,7 +995,7 @@ async function openaiTTS(params: {
  apiKey: string;
  model: string;
  voice: string;
-  responseFormat: "mp3" | "opus";
+  responseFormat: "mp3" | "opus" | "pcm";
  timeoutMs: number;
 }): Promise<Buffer> {
  const { text, apiKey, model, voice, responseFormat, timeoutMs } = params;
@@ -982,7 +1011,7 @@ async function openaiTTS(params: {
  const timeout = setTimeout(() => controller.abort(), timeoutMs);

  try {
-    const response = await fetch("https://api.openai.com/v1/audio/speech", {
+    const response = await fetch(`${OPENAI_TTS_BASE_URL}/audio/speech`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
@@ -1210,6 +1239,100 @@ export async function textToSpeech(params: {
  };
 }

+export async function textToSpeechTelephony(params: {
+  text: string;
+  cfg: ClawdbotConfig;
+  prefsPath?: string;
+}): Promise<TtsTelephonyResult> {
+  const config = resolveTtsConfig(params.cfg);
+  const prefsPath = params.prefsPath ?? resolveTtsPrefsPath(config);
+
+  if (params.text.length > config.maxTextLength) {
+    return {
+      success: false,
+      error: `Text too long (${params.text.length} chars, max ${config.maxTextLength})`,
+    };
+  }
+
+  const userProvider = getTtsProvider(config, prefsPath);
+  const providers = resolveTtsProviderOrder(userProvider);
+
+  let lastError: string | undefined;
+
+  for (const provider of providers) {
+    const providerStart = Date.now();
+    try {
+      if (provider === "edge") {
+        lastError = "edge: unsupported for telephony";
+        continue;
+      }
+
+      const apiKey = resolveTtsApiKey(config, provider);
+      if (!apiKey) {
+        lastError = `No API key for ${provider}`;
+        continue;
+      }
+
+      if (provider === "elevenlabs") {
+        const output = TELEPHONY_OUTPUT.elevenlabs;
+        const audioBuffer = await elevenLabsTTS({
+          text: params.text,
+          apiKey,
+          baseUrl: config.elevenlabs.baseUrl,
+          voiceId: config.elevenlabs.voiceId,
+          modelId: config.elevenlabs.modelId,
+          outputFormat: output.format,
+          seed: config.elevenlabs.seed,
+          applyTextNormalization: config.elevenlabs.applyTextNormalization,
+          languageCode: config.elevenlabs.languageCode,
+          voiceSettings: config.elevenlabs.voiceSettings,
+          timeoutMs: config.timeoutMs,
+        });
+
+        return {
+          success: true,
+          audioBuffer,
+          latencyMs: Date.now() - providerStart,
+          provider,
+          outputFormat: output.format,
+          sampleRate: output.sampleRate,
+        };
+      }
+
+      const output = TELEPHONY_OUTPUT.openai;
+      const audioBuffer = await openaiTTS({
+        text: params.text,
+        apiKey,
+        model: config.openai.model,
+        voice: config.openai.voice,
+        responseFormat: output.format,
+        timeoutMs: config.timeoutMs,
+      });
+
+      return {
+        success: true,
+        audioBuffer,
+        latencyMs: Date.now() - providerStart,
+        provider,
+        outputFormat: output.format,
+        sampleRate: output.sampleRate,
+      };
+    } catch (err) {
+      const error = err as Error;
+      if (error.name === "AbortError") {
+        lastError = `${provider}: request timed out`;
+      } else {
+        lastError = `${provider}: ${error.message}`;
+      }
+    }
+  }
+
+  return {
+    success: false,
+    error: `TTS conversion failed: ${lastError || "no providers available"}`,
+  };
+}
+
 export async function maybeApplyTtsToPayload(params: {
  payload: ReplyPayload;
  cfg: ClawdbotConfig;
@@ -124,6 +124,7 @@ export function connectGateway(host: GatewayHost) {
    mode: "webchat",
    onHello: (hello) => {
      host.connected = true;
+      host.lastError = null;
      host.hello = hello;
      applySnapshot(host, hello);
      void loadAssistantIdentity(host as unknown as ClawdbotApp);
@@ -134,7 +135,10 @@ export function connectGateway(host: GatewayHost) {
    },
    onClose: ({ code, reason }) => {
      host.connected = false;
-      host.lastError = `disconnected (${code}): ${reason || "no reason"}`;
+      // Code 1012 = Service Restart (expected during config saves, don't show as error)
+      if (code !== 1012) {
+        host.lastError = `disconnected (${code}): ${reason || "no reason"}`;
+      }
    },
    onEvent: (evt) => handleGatewayEvent(host, evt),
    onGap: ({ expected, received }) => {
@@ -38,7 +38,7 @@ describe("config view", () => {
    onSubsectionChange: vi.fn(),
  });

-  it("disables save when form is unsafe", () => {
+  it("allows save when form is unsafe", () => {
    const container = document.createElement("div");
    render(
      renderConfig({
@@ -59,6 +59,28 @@ describe("config view", () => {
      container,
    );

+    const saveButton = Array.from(
+      container.querySelectorAll("button"),
+    ).find((btn) => btn.textContent?.trim() === "Save") as
+      | HTMLButtonElement
+      | undefined;
+    expect(saveButton).not.toBeUndefined();
+    expect(saveButton?.disabled).toBe(false);
+  });
+
+  it("disables save when schema is missing", () => {
+    const container = document.createElement("div");
+    render(
+      renderConfig({
+        ...baseProps(),
+        schema: null,
+        formMode: "form",
+        formValue: { gateway: { mode: "local" } },
+        originalValue: {},
+      }),
+      container,
+    );
+
    const saveButton = Array.from(
      container.querySelectorAll("button"),
    ).find((btn) => btn.textContent?.trim() === "Save") as
@@ -233,9 +233,10 @@ export function renderConfig(props: ConfigProps) {
  const hasRawChanges = props.formMode === "raw" && props.raw !== props.originalRaw;
  const hasChanges = props.formMode === "form" ? diff.length > 0 : hasRawChanges;

-  // Save/apply buttons require actual changes to be enabled
+  // Save/apply buttons require actual changes to be enabled.
+  // Note: formUnsafe warns about unsupported schema paths but shouldn't block saving.
  const canSaveForm =
-    Boolean(props.formValue) && !props.loading && !formUnsafe;
+    Boolean(props.formValue) && !props.loading && Boolean(analysis.schema);
  const canSave =
    props.connected &&
    !props.saving &&
Author	SHA1	Message	Date
Peter Steinberger	492c37a171	fix: harden message aborts + bluebubbles dm create (#1751 ) (thanks @tyler6204)	2026-01-25 10:02:41 +00:00
Tyler Yust	738e596c71	fix(bluebubbles): preserve friendly display names in formatTargetDisplay	2026-01-25 09:47:57 +00:00
Tyler Yust	bea6b3eb5b	fix: prevent cross-context decoration on direct message tool sends Two fixes: 1. Cross-context decoration (e.g., '[from +19257864429]' prefix) was being added to ALL messages sent to a different target, even when the agent was just composing a new message via the message tool. This decoration should only be applied when forwarding/relaying messages between chats. Fix: Added skipCrossContextDecoration flag to ChannelThreadingToolContext. The message tool now sets this flag to true, so direct sends don't get decorated. The buildCrossContextDecoration function checks this flag and returns null when set. 2. Aborted requests were still completing because the abort signal wasn't being passed through the message tool execution chain. Fix: Added abortSignal propagation from message tool → runMessageAction → executeSendAction → sendMessage → deliverOutboundPayloads. Added abort checks at key points in the chain to fail fast when aborted. Files changed: - src/channels/plugins/types.core.ts: Added skipCrossContextDecoration field - src/infra/outbound/outbound-policy.ts: Check skip flag before decorating - src/agents/tools/message-tool.ts: Set skip flag, accept and pass abort signal - src/infra/outbound/message-action-runner.ts: Pass abort signal through - src/infra/outbound/outbound-send-service.ts: Check and pass abort signal - src/infra/outbound/message.ts: Pass abort signal to delivery	2026-01-25 09:47:57 +00:00
Tyler Yust	00e00460c1	fix(bluebubbles): hide internal routing metadata in cross-context markers When sending cross-context messages via BlueBubbles, the origin marker was exposing internal chat_guid routing info like '[from bluebubbles:chat_guid:any;-;+19257864429]'. This adds a formatTargetDisplay() function to the BlueBubbles plugin that: - Extracts phone numbers from chat_guid formats (iMessage;-;+1234567890 -> +1234567890) - Normalizes handles for clean display - Avoids returning raw chat_guid formats containing internal routing metadata Now cross-context markers show clean identifiers like '[from +19257864429]' instead of exposing internal routing details to recipients.	2026-01-25 09:47:57 +00:00
Tyler Yust	64c6698ea4	feat(bluebubbles): auto-create new DM chats when sending to unknown phone numbers When sending to a phone number that doesn't have an existing chat, instead of failing with 'chatGuid not found', now automatically creates a new chat using the /api/v1/chat/new endpoint. - Added createNewChatWithMessage() helper function - When resolveChatGuidForTarget returns null for a handle target, uses the new chat endpoint with addresses array and message - Includes helpful error message if Private API isn't enabled - Only applies to handle targets (phone numbers), not group chats	2026-01-25 09:47:57 +00:00
Tyler Yust	f997a3f395	fix(bluebubbles): prevent message routing to group chats when targeting phone numbers When sending a message to a phone number like +12622102921, the resolveChatGuidForTarget function was finding and returning a GROUP CHAT containing that phone number instead of a direct DM chat. The bug was in the participantMatch fallback logic which matched ANY chat containing the phone number as a participant, including groups. This fix adds a check to ensure participantMatch only considers DM chats (identified by ';-;' separator in the chat GUID). Group chats (identified by ';+;' separator) are now explicitly excluded from handle-based matching. If a phone number only exists in a group chat (no direct DM exists), the function now correctly returns null, which causes the send to fail with a clear error rather than accidentally messaging a group. Added test case to verify this behavior.	2026-01-25 09:47:57 +00:00
Tyler Yust	626a37f1ce	fix(bluebubbles): prefer DM resolution + hide routing markers	2026-01-25 09:47:57 +00:00
Peter Steinberger	83f92e34af	refactor: align voice-call TTS with core config	2026-01-25 09:29:57 +00:00
Vignesh Natarajan	9366cbc7db	Docs: add Discord MESSAGE_CONTENT intent step to Railway guide	2026-01-25 01:26:53 -08:00
Peter Steinberger	d4f895d8f2	fix: move gateway lock to temp dir	2026-01-25 09:21:46 +00:00
Vignesh Natarajan	f08c34a73f	Docs: fix Railway deploy URL and add PORT variable	2026-01-25 01:18:12 -08:00
zhixianandzhixian	6a9301c27d	feat(tts): support custom OpenAI-compatible TTS endpoints (#1701 ) * feat(tts): support custom OpenAI-compatible TTS endpoints Add OPENAI_TTS_BASE_URL environment variable to allow using self-hosted or third-party OpenAI-compatible TTS services like Kokoro, LocalAI, or OpenedAI-Speech. Changes: - Add OPENAI_TTS_BASE_URL env var (defaults to OpenAI official API) - Relax model/voice validation when using custom endpoints - Add tts-1 and tts-1-hd to the model allowlist This enables users to: - Use local TTS for privacy and cost savings - Use models with better non-English language support (Chinese, Japanese) - Reduce latency with local inference Example usage: OPENAI_TTS_BASE_URL=http://localhost:8880/v1 Tested with Kokoro-FastAPI. * fix: strip trailing slashes from OPENAI_TTS_BASE_URL Address review feedback: normalize the base URL by removing trailing slashes to prevent double-slash paths like /v1//audio/speech which cause 404 errors on some OpenAI-compatible servers. * style: format code with oxfmt * test: update tests for expanded OpenAI TTS model list - Accept tts-1 and tts-1-hd as valid models - Update OPENAI_TTS_MODELS length expectation to 3 --------- Co-authored-by: zhixian <zhixian@bunker.local>	2026-01-25 08:04:20 +00:00
Peter Steinberger	653401774d	fix(telegram): honor linkPreview on fallback (#1730 ) * feat: add notice directive parsing * fix: honor telegram linkPreview config (#1700) (thanks @zerone0x)	2026-01-25 07:55:39 +00:00
Peter Steinberger	c6cdbb630c	fix: harden exec spawn fallback	2026-01-25 06:37:39 +00:00
Peter Steinberger	da2439f2cc	docs: clarify Claude Pro Max auth	2026-01-25 06:05:11 +00:00
zerone0xandClaude	92ab3f22dc	feat(telegram): add linkPreview config option Add channels.telegram.linkPreview config to control whether link previews are shown in outbound messages. When set to false, uses Telegram's link_preview_options.is_disabled to suppress URL previews. - Add linkPreview to TelegramAccountConfig type - Add Zod schema validation for linkPreview - Pass link_preview_options to sendMessage in send.ts and bot/delivery.ts - Propagate linkPreview config through deliverReplies callers - Add tests for link preview behavior Fixes #1675 Co-Authored-By: Claude <noreply@anthropic.com>	2026-01-25 06:00:05 +00:00
Peter Steinberger	43a6c5b77f	docs: clarify Gemini CLI OAuth	2026-01-25 05:53:25 +00:00
Peter Steinberger	495616d13e	fix(ui): refine config save guardrails (#1707 ) * fix: refine config save guardrails * docs: add changelog for config save guardrails (#1707) (thanks @Glucksberg)	2026-01-25 05:52:32 +00:00
Peter Steinberger	bac80f0886	fix: listen on ipv6 loopback for gateway	2026-01-25 05:49:48 +00:00
Peter Steinberger	ef078fec70	docs: add Windows install troubleshooting	2026-01-25 05:48:24 +00:00
GlucksbergandClaude Opus 4.5	8e3ac01db6	fix(ui): improve config save UX (#1678 ) Follow-up to #1609 fix: - Remove formUnsafe check from canSave (was blocking save even with valid changes) - Suppress disconnect message for code 1012 (service restart is expected during config save) Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-25 05:46:55 +00:00
Peter Steinberger	c3f90dd4e2	docs: add macOS VM link	2026-01-25 05:32:04 +00:00
Peter Steinberger	00c4556d7b	docs: add Claude Max FAQ	2026-01-25 05:28:01 +00:00
Peter Steinberger	a4bc69dbec	docs: add first steps FAQ	2026-01-25 05:24:47 +00:00
Peter Steinberger	3f1457de2a	docs: add new FAQ entries	2026-01-25 05:20:16 +00:00
Peter Steinberger	8507ea08bd	docs: expand macOS VM guide (#1693 ) (thanks @f-trycua)	2026-01-25 05:16:41 +00:00
f-trycua	7ae2548fc6	docs: add macOS VM (Lume) platform guide Add documentation for running Clawdbot in a sandboxed macOS VM using Lume. This provides an alternative to buying dedicated hardware or using cloud instances. The guide covers: - Installing Lume on Apple Silicon Macs - Creating and configuring a macOS VM - Installing Clawdbot inside the VM - Running headlessly for 24/7 operation - iMessage integration via BlueBubbles - Saving golden images for easy reset	2026-01-25 05:14:13 +00:00