bloby-bot 0.48.0 → 0.48.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bloby-bot",
-  "version": "0.48.0",
+  "version": "0.48.2",
   "releaseNotes": [
     "1. Something great..",
     "2. ",

package/shared/config.ts

@@ -13,6 +13,13 @@ export interface ChannelConfig {
   allowGroups?: boolean;
 }
 
+export interface AlexaChannelConfig {
+  enabled: boolean;
+  /** Per-user shared secret minted by the relay when the user first pairs an Alexa device.
+   *  Used to verify that inbound /api/channels/alexa/handle calls actually came from the relay. */
+  sharedSecret?: string;
+}
+
 export interface BotConfig {
   port: number;
   username: string;
@@ -39,6 +46,7 @@ export interface BotConfig {
   };
   channels?: {
     whatsapp?: ChannelConfig;
+    alexa?: AlexaChannelConfig;
   };
   tunnelUrl?: string;
 }

package/supervisor/channels/alexa.ts

@@ -0,0 +1,219 @@
+/**
+ * Alexa channel provider.
+ *
+ * Unlike WhatsApp, this channel has no socket, no QR, no auth state of its own.
+ * It's a degenerate provider whose `sendMessage` resolves a promise held by an
+ * inbound HTTP handler. The relay (api.bloby.bot) is the public entry point that
+ * verifies Amazon's signature, then forwards the parsed utterance to this Pi
+ * via POST /api/channels/alexa/handle. That route waits for the agent's reply
+ * and returns it as the HTTP response, which the relay then formats as the
+ * Alexa-flavored JSON envelope.
+ *
+ * The promise-resolution flow is per-conversation FIFO, mirroring the same
+ * anti-bleed contract WhatsApp uses: each pushed utterance reserves a resolver
+ * slot, each bot:response consumes the head slot.
+ */
+
+import { loadConfig } from '../../shared/config.js';
+import { log } from '../../shared/logger.js';
+import type { ChannelProvider, ChannelStatus, ChannelType } from './types.js';
+
+/** Credentials + state needed to fire Progressive Response for a single Alexa turn. */
+export interface AlexaTurnState {
+  apiEndpoint: string;
+  apiAccessToken: string;
+  requestId: string;
+  /** Wall-clock start of the turn — used for log timing. */
+  startedAt: number;
+  /** Static-fallback timer that fires "Working on it" if no preamble text arrives in time. */
+  fallbackTimer: ReturnType<typeof setTimeout> | null;
+  /** True once we've sent at least one Progressive Response for this turn. */
+  sentAny: boolean;
+}
+
+interface PendingSlot {
+  resolve: (text: string) => void;
+  reject: (err: Error) => void;
+  createdAt: number;
+  turn: AlexaTurnState | null;
+}
+
+const STATIC_FALLBACK_MS = 1_500;  // Fire early enough to extend Alexa's budget on cold start
+const MAX_PROGRESSIVE_SPEECH = 600;
+
+export class AlexaChannel implements ChannelProvider {
+  readonly type: ChannelType = 'alexa';
+
+  /** Per-conversation FIFO of pending HTTP-response resolvers + turn state.
+   *  Each inbound Alexa utterance enqueues one slot; each bot:response (or
+   *  turn-complete safety net) dequeues one. */
+  private pending = new Map<string, PendingSlot[]>();
+
+  /** Reserve a resolver slot. The caller pushes the user utterance into the
+   *  live conversation IMMEDIATELY after this returns, so the FIFO order on
+   *  this map matches the FIFO order the routing queue uses.
+   *
+   *  If `creds` are provided (apiEndpoint + apiAccessToken + requestId), this
+   *  also schedules a static "Working on it" Progressive Response to fire if
+   *  the agent emits no preamble text within STATIC_FALLBACK_MS. The fallback
+   *  is cancelled the moment any Progressive Response is sent for this turn. */
+  reservePending(
+    convId: string,
+    creds: { apiEndpoint: string; apiAccessToken: string; requestId: string } | null,
+    timeoutMs = 25_000,
+  ): Promise<string> {
+    return new Promise<string>((resolve, reject) => {
+      const turn: AlexaTurnState | null = creds ? {
+        apiEndpoint: creds.apiEndpoint,
+        apiAccessToken: creds.apiAccessToken,
+        requestId: creds.requestId,
+        startedAt: Date.now(),
+        fallbackTimer: null,
+        sentAny: false,
+      } : null;
+
+      const slot: PendingSlot = { resolve, reject, createdAt: Date.now(), turn };
+      let q = this.pending.get(convId);
+      if (!q) {
+        q = [];
+        this.pending.set(convId, q);
+      }
+      q.push(slot);
+
+      // NOTE: the relay fires an immediate "On it." Progressive Response on
+      // every AgentIntent turn (see relay's sendImmediateProgressive), so the
+      // budget is already extended by the time we get here. We DON'T schedule
+      // a static fallback on the Pi side — it would double up and the user
+      // would hear "On it. Working on it." If the agent emits a preamble, we
+      // still flush it as a Progressive in `tryFlushProgressive`.
+
+      // Hard safety timeout — if the agent never responds at all, the HTTP
+      // handler unblocks so the relay can return a friendly fallback. The
+      // slot is removed so a late bot:response doesn't resolve a dead promise.
+      setTimeout(() => {
+        const list = this.pending.get(convId);
+        if (!list) return;
+        const idx = list.indexOf(slot);
+        if (idx >= 0) {
+          if (slot.turn?.fallbackTimer) clearTimeout(slot.turn.fallbackTimer);
+          list.splice(idx, 1);
+          if (list.length === 0) this.pending.delete(convId);
+          reject(new Error('alexa-timeout'));
+        }
+      }, timeoutMs);
+    });
+  }
+
+  /** Resolve the head resolver for a conversation. Called by the channel
+   *  manager when bot:response (or turn-complete with no response) fires for
+   *  an alexa-surface turn. */
+  resolveHead(convId: string, text: string): boolean {
+    const q = this.pending.get(convId);
+    if (!q || q.length === 0) return false;
+    const slot = q.shift()!;
+    if (q.length === 0) this.pending.delete(convId);
+    if (slot.turn?.fallbackTimer) clearTimeout(slot.turn.fallbackTimer);
+    slot.resolve(text);
+    return true;
+  }
+
+  /** Drop the head resolver (used when a turn ends without a bot:response). */
+  rejectHead(convId: string, reason: string): boolean {
+    const q = this.pending.get(convId);
+    if (!q || q.length === 0) return false;
+    const slot = q.shift()!;
+    if (q.length === 0) this.pending.delete(convId);
+    if (slot.turn?.fallbackTimer) clearTimeout(slot.turn.fallbackTimer);
+    slot.reject(new Error(reason));
+    return true;
+  }
+
+  /** Try to flush a buffered preamble chunk as Progressive Response on the
+   *  head turn. Called by the channel manager on bot:tool events when the
+   *  routing target's surface is 'alexa' and there's buffered text. */
+  tryFlushProgressive(convId: string, text: string): boolean {
+    const q = this.pending.get(convId);
+    if (!q || q.length === 0) return false;
+    const turn = q[0].turn;
+    if (!turn) return false;
+    this.sendProgressive(turn, text).catch(() => {});
+    return true;
+  }
+
+  /** Fire a single Progressive Response directive to Amazon's Directive Service.
+   *  Best-effort: failures are logged but don't break the agent's stream. */
+  private async sendProgressive(turn: AlexaTurnState, speech: string): Promise<void> {
+    const trimmed = String(speech || '').trim();
+    if (!trimmed) return;
+    const fireOffset = Date.now() - turn.startedAt;
+    try {
+      const r = await fetch(`${turn.apiEndpoint}/v1/directives`, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${turn.apiAccessToken}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          header: { requestId: turn.requestId },
+          directive: {
+            type: 'VoicePlayer.Speak',
+            speech: trimmed.slice(0, MAX_PROGRESSIVE_SPEECH),
+          },
+        }),
+      });
+      if (r.ok) {
+        turn.sentAny = true;
+        if (turn.fallbackTimer) {
+          clearTimeout(turn.fallbackTimer);
+          turn.fallbackTimer = null;
+        }
+        log.info(`[alexa/progressive] sent at +${fireOffset}ms (status ${r.status}) — "${trimmed.slice(0, 60)}"`);
+      } else {
+        const body = await r.text().catch(() => '');
+        log.warn(`[alexa/progressive] REJECTED at +${fireOffset}ms — status ${r.status} body=${body.slice(0, 200)}`);
+      }
+    } catch (err: any) {
+      log.warn(`[alexa/progressive] FAILED at +${fireOffset}ms — ${err.message}`);
+    }
+  }
+
+  // ── ChannelProvider implementation ──
+
+  async connect(): Promise<void> {
+    // No-op. Alexa is a passive HTTP receiver.
+    log.info('[alexa] Channel ready (passive HTTP receiver)');
+  }
+
+  async disconnect(): Promise<void> {
+    // Reject any in-flight resolvers so HTTP handlers don't hang forever,
+    // and cancel any pending fallback timers to avoid late progressive calls.
+    for (const [, q] of this.pending) {
+      for (const slot of q) {
+        if (slot.turn?.fallbackTimer) clearTimeout(slot.turn.fallbackTimer);
+        slot.reject(new Error('alexa-disconnected'));
+      }
+    }
+    this.pending.clear();
+  }
+
+  async sendMessage(_to: string, _text: string): Promise<void> {
+    // Alexa is request/response. Replies are delivered by resolving the
+    // pending HTTP response, not by calling this method. ChannelManager
+    // routes alexa-surface turns through `resolveHead`, not `sendMessage`.
+    log.warn('[alexa] sendMessage called on Alexa channel — ignored (use resolveHead)');
+  }
+
+  getStatus(): ChannelStatus {
+    const cfg = loadConfig().channels?.alexa;
+    return {
+      channel: 'alexa',
+      connected: !!cfg?.enabled,
+      info: {
+        linked: !!cfg?.sharedSecret,
+      },
+    };
+  }
+
+  getQrCode(): string | null { return null; }
+  hasCredentials(): boolean { return !!loadConfig().channels?.alexa?.sharedSecret; }
+}

package/supervisor/channels/manager.ts

@@ -25,6 +25,7 @@ import { WORKSPACE_DIR } from '../../shared/paths.js';
 import { log } from '../../shared/logger.js';
 import { startBlobyAgentQuery, startConversation, pushMessage, hasConversation, type RecentMessage } from '../bloby-agent.js';
 import { WhatsAppChannel } from './whatsapp.js';
+import { AlexaChannel } from './alexa.js';
 import type { ChannelConfig, ChannelProvider, ChannelStatus, ChannelType, InboundMessage, InboundMessageAttachment, RoutingTarget, SenderRole } from './types.js';
 import type { AgentAttachment } from '../bloby-agent.js';
 import { saveAttachment, type SavedFile } from '../file-saver.js';
@@ -106,34 +107,41 @@ export class ChannelManager {
     this.opts = opts;
   }
 
-  /** Initialize channels based on config */
+  /** Initialize channels based on config. Idempotent — calling repeatedly
+   *  initializes any newly-enabled channel without disturbing ones already up. */
   async init(): Promise<void> {
     const config = loadConfig();
     const channelConfigs = config.channels;
 
-    if (!channelConfigs?.whatsapp?.enabled) {
+    if (channelConfigs?.whatsapp?.enabled && !this.providers.has('whatsapp')) {
+      log.info('[channels] Initializing WhatsApp channel...');
+      const whatsapp = new WhatsAppChannel(
+        (sender, senderName, text, fromMe, isSelfChat, chatJid, isGroup, images, inboundKey) => {
+          const attachments = images?.map((img) => ({ type: 'image' as const, mediaType: img.mediaType, data: img.data }));
+          this.handleInboundMessage('whatsapp', sender, senderName, text, fromMe, isSelfChat, chatJid, isGroup, attachments, inboundKey);
+        },
+        (status) => this.handleStatusChange(status),
+        (audioBase64) => this.transcribeAudio(audioBase64),
+      );
+      this.providers.set('whatsapp', whatsapp);
+
+      // Auto-connect if credentials exist (previously linked)
+      if (whatsapp.hasCredentials()) {
+        try {
+          await whatsapp.connect();
+        } catch (err: any) {
+          log.warn(`[channels] WhatsApp auto-connect failed: ${err.message}`);
+        }
+      }
+    } else if (!channelConfigs?.whatsapp?.enabled && !this.providers.has('whatsapp')) {
       log.info('[channels] WhatsApp not enabled — skipping');
-      return;
     }
 
-    log.info('[channels] Initializing WhatsApp channel...');
-    const whatsapp = new WhatsAppChannel(
-      (sender, senderName, text, fromMe, isSelfChat, chatJid, isGroup, images, inboundKey) => {
-        const attachments = images?.map((img) => ({ type: 'image' as const, mediaType: img.mediaType, data: img.data }));
-        this.handleInboundMessage('whatsapp', sender, senderName, text, fromMe, isSelfChat, chatJid, isGroup, attachments, inboundKey);
-      },
-      (status) => this.handleStatusChange(status),
-      (audioBase64) => this.transcribeAudio(audioBase64),
-    );
-    this.providers.set('whatsapp', whatsapp);
-
-    // Auto-connect if credentials exist (previously linked)
-    if (whatsapp.hasCredentials()) {
-      try {
-        await whatsapp.connect();
-      } catch (err: any) {
-        log.warn(`[channels] WhatsApp auto-connect failed: ${err.message}`);
-      }
+    if (channelConfigs?.alexa?.enabled && !this.providers.has('alexa')) {
+      log.info('[channels] Initializing Alexa channel...');
+      const alexa = new AlexaChannel();
+      this.providers.set('alexa', alexa);
+      await alexa.connect();
     }
   }
 
@@ -446,17 +454,36 @@ export class ChannelManager {
       // Agent paused for a tool call — flush streamed text so the user sees progress
       // before the tool result lands. Peek (don't consume) — the final bot:response
       // is what closes out the turn.
-      this.sendStreamChunk(this.peekRoute(convId), state.chunkBuf.trim(), botName);
-      state.chunkBuf = '';
+      const head = this.peekRoute(convId);
+      if (head?.surface === 'alexa') {
+        // For Alexa, send the preamble as a Progressive Response so the user
+        // hears the agent's actual "I'll do X..." line. Final bot:response is
+        // still what closes the turn with the agent's last words.
+        const alexa = this.providers.get('alexa') as AlexaChannel | undefined;
+        alexa?.tryFlushProgressive(convId, state.chunkBuf.trim());
+        state.chunkBuf = '';
+      } else {
+        this.sendStreamChunk(head, state.chunkBuf.trim(), botName);
+        state.chunkBuf = '';
+      }
       return;
     }
 
     if (type === 'bot:response' && eventData?.content && convId) {
       const target = this.consumeRoute(convId);
       const remaining = state.chunkBuf.trim();
-      if (remaining) this.sendStreamChunk(target, remaining, botName);
       state.chunkBuf = '';
 
+      if (target?.surface === 'alexa') {
+        // Resolve the HTTP handler's promise with the full reply text.
+        const alexa = this.providers.get('alexa') as AlexaChannel | undefined;
+        if (!alexa || !alexa.resolveHead(convId, eventData.content)) {
+          log.warn(`[channels] bot:response for alexa surface but no pending resolver (conv=${convId})`);
+        }
+      } else if (remaining) {
+        this.sendStreamChunk(target, remaining, botName);
+      }
+
       // Append the assistant's reply into the per-chat context buffer so the next
       // trigger in that chat sees it as conversation history.
       if (target?.assistantBufferKey) {
@@ -473,9 +500,14 @@ export class ChannelManager {
     // doesn't bleed into the next turn's reply. The SDK guarantees one response per
     // pushed input; this safety net covers aborts, empty turns, and provider errors.
     if ((type === 'bot:turn-complete' || type === 'bot:error') && convId) {
-      if (this.peekRoute(convId)) {
+      const head = this.peekRoute(convId);
+      if (head) {
         const dropped = this.consumeRoute(convId);
         log.warn(`[channels] ${type} without bot:response — dropping pending route (surface=${dropped?.surface}, to=${dropped?.waSendTo || 'none'})`);
+        if (dropped?.surface === 'alexa') {
+          const alexa = this.providers.get('alexa') as AlexaChannel | undefined;
+          alexa?.rejectHead(convId, type);
+        }
       }
       state.chunkBuf = '';
     }
@@ -872,6 +904,137 @@ export class ChannelManager {
     this.pushWithRouting(convId, target, channelContent, agentAttachments, savedFiles);
   }
 
+  /** Synchronously handle an Alexa utterance: push into the shared conversation,
+   *  await the agent's reply, return it. Used by /api/channels/alexa/handle.
+   *
+   *  Returns the final reply text. Throws on timeout / aborted turn so the HTTP
+   *  handler can fall back to "I'll get back to you in chat" (or HA announce).
+   */
+  async handleAlexaInbound(opts: {
+    text: string;
+    alexaUserId: string;
+    alexaSessionId?: string;
+    deviceId?: string;
+    locale?: string;
+    /** Alexa Directive Service base URL — passed through from the relay. */
+    apiEndpoint?: string;
+    /** Alexa apiAccessToken for the current request — required to fire Progressive Response. */
+    apiAccessToken?: string;
+    /** Original Alexa requestId — required to fire Progressive Response. */
+    requestId?: string;
+    timeoutMs?: number;
+  }): Promise<string> {
+    const { text, alexaUserId, alexaSessionId, deviceId, locale, apiEndpoint, apiAccessToken, requestId, timeoutMs = 25_000 } = opts;
+    const { workerApi, broadcastBloby, getModel } = this.opts;
+    const model = getModel();
+
+    const alexa = this.providers.get('alexa') as AlexaChannel | undefined;
+    if (!alexa) throw new Error('alexa-channel-not-initialized');
+
+    // Get or create the shared conversation (same one chat + WhatsApp use).
+    let convId: string | undefined;
+    try {
+      const ctx = await workerApi('/api/context/current');
+      if (ctx.conversationId) {
+        convId = ctx.conversationId;
+      } else {
+        const conv = await workerApi('/api/conversations', 'POST', { title: 'Alexa', model });
+        convId = conv.id;
+        await workerApi('/api/context/set', 'POST', { conversationId: convId });
+      }
+    } catch (err: any) {
+      log.warn(`[channels/alexa] Failed to get/create conversation: ${err.message}`);
+      throw err;
+    }
+    if (!convId) throw new Error('no-conversation');
+
+    // Persist + mirror to dashboard so the user sees the Alexa utterance in chat.
+    workerApi(`/api/conversations/${convId}/messages`, 'POST', {
+      role: 'user',
+      content: text,
+      meta: { model, channel: 'alexa' },
+    }).catch((err: any) => log.warn(`[channels/alexa] DB persist error: ${err.message}`));
+    broadcastBloby('chat:sync', {
+      conversationId: convId,
+      message: { role: 'user', content: text, timestamp: new Date().toISOString() },
+    });
+
+    // Make sure a live conversation exists (mirrors handleAdminMessage's setup).
+    if (!hasConversation(convId)) {
+      log.info(`[channels/alexa] Starting live conversation: ${convId}`);
+      let botName = 'Bloby', humanName = 'Human';
+      let recentMessages: RecentMessage[] = [];
+      try {
+        const [status, recentRaw] = await Promise.all([
+          workerApi('/api/onboard/status'),
+          workerApi(`/api/conversations/${convId}/messages/recent?limit=20`),
+        ]);
+        botName = status.agentName || 'Bloby';
+        humanName = status.userName || 'Human';
+        if (Array.isArray(recentRaw)) {
+          const filtered = recentRaw.filter((m: any) => m.role === 'user' || m.role === 'assistant');
+          if (filtered.length > 0) {
+            recentMessages = filtered.slice(0, -1).map((m: any) => ({
+              role: m.role as 'user' | 'assistant',
+              content: m.content,
+            }));
+          }
+        }
+      } catch {}
+
+      const waState = this.createWaStreamState();
+      await startConversation(convId, model, (type, eventData) => {
+        // Same routing as WhatsApp — alexa surface branch lives inside this method.
+        this.routeWaStreamEvent(waState, type, eventData, botName);
+
+        if (type === 'bot:response' && eventData.content) {
+          workerApi(`/api/conversations/${convId}/messages`, 'POST', {
+            role: 'assistant',
+            content: eventData.content,
+            meta: { model },
+          }).catch(() => {});
+        }
+
+        if (type === 'bot:turn-complete') {
+          if (eventData.usedFileTools) this.opts.restartBackend();
+          broadcastBloby('bot:idle', { conversationId: convId });
+          return;
+        }
+
+        if (type === 'bot:conversation-ended') {
+          this.clearRoutes(convId);
+          return;
+        }
+
+        broadcastBloby(type, eventData);
+      }, { botName, humanName }, recentMessages);
+    }
+
+    // Reserve the resolver slot FIRST — the agent may respond very quickly and
+    // we don't want the bot:response to arrive before the resolver is in the FIFO.
+    // Also pass the Alexa Directive Service credentials so the channel can fire
+    // Progressive Response on every preamble chunk the agent emits before tool calls.
+    const creds = (apiEndpoint && apiAccessToken && requestId)
+      ? { apiEndpoint, apiAccessToken, requestId }
+      : null;
+    const pending = alexa.reservePending(convId, creds, timeoutMs);
+
+    // Compact device id so the tag stays readable — agent can correlate the
+    // last 8 chars with its memory of "device XYZ = kitchen / office / ..."
+    const deviceTag = deviceId ? ` | device=${deviceId.slice(-8)}` : '';
+    const sessionTag = alexaSessionId ? ` | session=${alexaSessionId.slice(-6)}` : '';
+    const localeTag = locale ? ` | ${locale}` : '';
+    const channelContext = `[Alexa | user=${alexaUserId.slice(-8)}${deviceTag}${sessionTag}${localeTag}]\n`;
+    const target: RoutingTarget = {
+      surface: 'alexa',
+      isSelfChat: false,
+      isGroup: false,
+    };
+    this.pushWithRouting(convId, target, channelContext + text);
+
+    return pending; // resolves with the reply text (or rejects on timeout)
+  }
+
   /** Handle message from a customer — runs support agent in parallel with conversation context */
   private async handleCustomerMessage(msg: InboundMessage, channelConfig: ChannelConfig) {
     const agentKey = `${msg.channel}:${msg.sender}`;

package/supervisor/channels/types.ts

@@ -2,7 +2,7 @@
  * Shared types for the multi-channel messaging system.
  */
 
-export type ChannelType = 'whatsapp' | 'telegram';
+export type ChannelType = 'whatsapp' | 'telegram' | 'alexa';
 export type SenderRole = 'admin' | 'customer' | 'assistant';
 
 export interface ChannelConfig {
@@ -70,8 +70,10 @@ export interface ChannelStatus {
  * the turn ends without a response (error / empty turn).
  */
 export interface RoutingTarget {
-  /** Which surface triggered this turn. Drives whether the WA reply carries a "🤖 Bot:" prefix. */
-  surface: 'chat' | 'whatsapp';
+  /** Which surface triggered this turn. Drives whether the WA reply carries a "🤖 Bot:" prefix.
+   *  'workspace' is a dashboard surface like 'chat' (broadcast-driven, optional WA self-chat mirror)
+   *  but isolated for telemetry / future per-surface routing. */
+  surface: 'chat' | 'whatsapp' | 'alexa' | 'workspace';
   /** WhatsApp JID to deliver the reply to.
    *  - 'whatsapp' surface → the originating chat JID (group or peer).
    *  - 'chat' surface     → optionally the user's own number (self-chat mirror), or undefined.

package/supervisor/chat/src/components/Chat/MessageBubble.tsx

@@ -29,18 +29,27 @@ function formatTime(iso: string): string {
   }
 }
 
-/** Convert WhatsApp QR URL (any format) into a markdown link so the button renders */
+/** Convert channel-pair URLs (any format) into markdown links so the buttons render */
 function preprocessContent(text: string): string {
-  const link = '[pair-whatsapp](/api/channels/whatsapp/qr-page)';
-  // Already a properly formatted markdown link — skip
-  if (text.includes(link)) return text;
-  // Backtick-wrapped full URL: `http://localhost:7400/api/channels/whatsapp/qr-page`
-  // Full URL in plain text: http://localhost:7400/api/channels/whatsapp/qr-page
-  // Bare relative path: /api/channels/whatsapp/qr-page
-  return text.replace(
-    /`?(?:http:\/\/localhost:\d+)?\/api\/channels\/whatsapp\/qr-page`?/g,
-    link,
-  );
+  let out = text;
+
+  const waLink = '[pair-whatsapp](/api/channels/whatsapp/qr-page)';
+  if (!out.includes(waLink)) {
+    out = out.replace(
+      /`?(?:http:\/\/localhost:\d+)?\/api\/channels\/whatsapp\/qr-page`?/g,
+      waLink,
+    );
+  }
+
+  const alexaLink = '[connect-alexa](/api/channels/alexa/pair-page)';
+  if (!out.includes(alexaLink)) {
+    out = out.replace(
+      /`?(?:http:\/\/localhost:\d+)?\/api\/channels\/alexa\/pair-page`?/g,
+      alexaLink,
+    );
+  }
+
+  return out;
 }
 
 type ContentSegment = { type: 'text'; value: string } | { type: 'env'; group: EnvGroupData } | { type: 'bloby-image'; src: string; alt: string } | { type: 'bloby-text'; title: string; content: string };
@@ -263,6 +272,27 @@ export default function MessageBubble({ role, content, timestamp, hasAttachments
               </a>
             );
           }
+          if (href?.includes('/api/channels/alexa/pair-page')) {
+            return (
+              <a
+                href={href}
+                target="_blank"
+                rel="noopener noreferrer"
+                className="flex items-center gap-3 my-2 px-3.5 py-2.5 rounded-xl bg-[#00CAFF]/10 border border-[#00CAFF]/20 hover:bg-[#00CAFF]/15 transition-colors no-underline"
+              >
+                <div className="flex items-center justify-center w-8 h-8 rounded-lg bg-[#00CAFF] shrink-0">
+                  <svg viewBox="0 0 24 24" className="w-4 h-4 fill-white">
+                    <path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8zm-1-13h2v6h-2zm0 8h2v2h-2z"/>
+                  </svg>
+                </div>
+                <div className="flex flex-col min-w-0">
+                  <span className="text-[#00CAFF] font-medium text-sm">Click here to connect Alexa</span>
+                  <span className="text-muted-foreground text-xs">Generates a one-time linking code</span>
+                </div>
+                <ExternalLink className="w-3.5 h-3.5 text-muted-foreground/50 ml-auto shrink-0" />
+              </a>
+            );
+          }
           return (
             <a
               href={href}