bloby-bot 0.47.14 → 0.48.1

package/package.json

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

package/shared/config.ts

@@ -13,6 +13,22 @@ 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;
+  /** Optional Home Assistant fallback for replies that exceed Alexa's ~25s budget. */
+  overflow?: {
+    mode: 'ha-announce' | 'chat-only';
+    ha?: {
+      url: string;
+      token: string;
+      device: string;
+    };
+  };
+}
+
 export interface BotConfig {
   port: number;
   username: string;
@@ -39,6 +55,7 @@ export interface BotConfig {
   };
   channels?: {
     whatsapp?: ChannelConfig;
+    alexa?: AlexaChannelConfig;
   };
   tunnelUrl?: string;
 }

package/supervisor/channels/alexa.ts

@@ -0,0 +1,117 @@
+/**
+ * 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';
+
+export class AlexaChannel implements ChannelProvider {
+  readonly type: ChannelType = 'alexa';
+
+  /** Per-conversation FIFO of pending HTTP-response resolvers. Each inbound
+   *  Alexa utterance enqueues one; each bot:response (or turn-complete safety
+   *  net) dequeues one. */
+  private pending = new Map<string, Array<{ resolve: (text: string) => void; reject: (err: Error) => void; createdAt: number }>>();
+
+  /** 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. */
+  reservePending(convId: string, timeoutMs = 25_000): Promise<string> {
+    return new Promise<string>((resolve, reject) => {
+      const slot = { resolve, reject, createdAt: Date.now() };
+      let q = this.pending.get(convId);
+      if (!q) {
+        q = [];
+        this.pending.set(convId, q);
+      }
+      q.push(slot);
+
+      // Safety timeout — if the agent never responds, the HTTP handler still
+      // unblocks and the relay can return an Alexa-friendly "I'll get back to
+      // you" message. The slot is also removed so a late bot:response doesn't
+      // try to resolve a dead promise.
+      setTimeout(() => {
+        const list = this.pending.get(convId);
+        if (!list) return;
+        const idx = list.indexOf(slot);
+        if (idx >= 0) {
+          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);
+    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);
+    slot.reject(new Error(reason));
+    return true;
+  }
+
+  // ── 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.
+    for (const [, q] of this.pending) {
+      for (const slot of q) 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,
+        overflow: cfg?.overflow?.mode || 'chat-only',
+      },
+    };
+  }
+
+  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,30 @@ 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 = '';
+      // Alexa can only deliver a single final reply per turn — keep buffering and
+      // let bot:response send everything at once.
+      if (this.peekRoute(convId)?.surface !== 'alexa') {
+        this.sendStreamChunk(this.peekRoute(convId), 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 +494,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 +898,119 @@ 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;
+    timeoutMs?: number;
+  }): Promise<string> {
+    const { text, alexaUserId, alexaSessionId, 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.
+    const pending = alexa.reservePending(convId, timeoutMs);
+
+    const channelContext = `[Alexa | ${alexaUserId}${alexaSessionId ? ` | session=${alexaSessionId.slice(-6)}` : ''}]\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 {
@@ -71,7 +71,7 @@ export interface ChannelStatus {
  */
 export interface RoutingTarget {
   /** Which surface triggered this turn. Drives whether the WA reply carries a "🤖 Bot:" prefix. */
-  surface: 'chat' | 'whatsapp';
+  surface: 'chat' | 'whatsapp' | 'alexa';
   /** 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}

package/supervisor/index.ts

@@ -376,6 +376,7 @@ export async function startSupervisor() {
     'POST /api/channels/whatsapp/pairing-code',
     'POST /api/channels/whatsapp/react',
     'POST /api/channels/send',
+    'POST /api/channels/alexa/handle',
   ];
 
   function isExemptRoute(method: string, url: string): boolean {
@@ -813,6 +814,188 @@ ${!connected ? `<script>
         return;
       }
 
+      // POST /api/channels/alexa/handle — relay-forwarded Alexa utterance.
+      // Authed via x-bloby-alexa-secret (per-user shared secret minted at pair time).
+      // Returns plain text the relay then formats as Alexa SSML.
+      if (req.method === 'POST' && channelPath === '/api/channels/alexa/handle') {
+        let body = '';
+        req.on('data', (chunk: Buffer) => { body += chunk.toString(); });
+        req.on('end', async () => {
+          try {
+            const cfg = loadConfig();
+            const expected = cfg.channels?.alexa?.sharedSecret;
+            const provided = req.headers['x-bloby-alexa-secret'];
+            if (!expected || !provided || provided !== expected) {
+              res.writeHead(401);
+              res.end(JSON.stringify({ ok: false, error: 'alexa-auth-failed' }));
+              return;
+            }
+            if (!cfg.channels?.alexa?.enabled) {
+              res.writeHead(503);
+              res.end(JSON.stringify({ ok: false, error: 'alexa-disabled' }));
+              return;
+            }
+
+            const { text, alexaUserId, sessionId, kind } = JSON.parse(body || '{}') as {
+              text?: string; alexaUserId?: string; sessionId?: string; kind?: string;
+            };
+
+            // Launch / Stop / Help intents don't need to hit the agent — the relay
+            // can short-circuit, but we accept them here too for symmetry.
+            if (kind === 'launch') {
+              res.writeHead(200);
+              res.end(JSON.stringify({ ok: true, reply: 'Bloby here, what can I help with?', endSession: false }));
+              return;
+            }
+            if (kind === 'stop' || kind === 'cancel') {
+              res.writeHead(200);
+              res.end(JSON.stringify({ ok: true, reply: 'Goodbye.', endSession: true }));
+              return;
+            }
+
+            if (!text || !alexaUserId) {
+              res.writeHead(400);
+              res.end(JSON.stringify({ ok: false, error: 'text and alexaUserId required' }));
+              return;
+            }
+
+            try {
+              const reply = await channelManager.handleAlexaInbound({ text, alexaUserId, alexaSessionId: sessionId });
+              res.writeHead(200);
+              res.end(JSON.stringify({ ok: true, reply, endSession: false }));
+            } catch (err: any) {
+              // Timeout or aborted turn — agent will still finish and the result lands
+              // in the shared conversation. Tell Alexa we'll get back to them.
+              const overflow = cfg.channels?.alexa?.overflow?.mode || 'chat-only';
+              const fallback = overflow === 'ha-announce'
+                ? "I'll let you know in a moment."
+                : "I'll reply in your chat when ready.";
+              res.writeHead(200);
+              res.end(JSON.stringify({ ok: true, reply: fallback, endSession: false, overflow: true }));
+            }
+          } catch (err: any) {
+            res.writeHead(500);
+            res.end(JSON.stringify({ ok: false, error: err.message }));
+          }
+        });
+        return;
+      }
+
+      // POST /api/channels/alexa/pair — dashboard mints a pairing code via the relay.
+      // Body: optional { ttlSeconds }. Returns: { code, expiresAt, sharedSecret }.
+      // We persist sharedSecret locally so future /handle calls can authenticate.
+      if (req.method === 'POST' && channelPath === '/api/channels/alexa/pair') {
+        (async () => {
+          try {
+            const cfg = loadConfig();
+            if (!cfg.relay?.token) {
+              res.writeHead(400);
+              res.end(JSON.stringify({ ok: false, error: 'no-relay-token' }));
+              return;
+            }
+            const relayBase = cfg.relay.url || 'https://api.bloby.bot';
+            const resp = await fetch(`${relayBase.replace(/\/$/, '')}/api/alexa/pair`, {
+              method: 'POST',
+              headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${cfg.relay.token}`,
+              },
+              body: '{}',
+            });
+            const data = await resp.json() as { code?: string; expiresAt?: string; sharedSecret?: string; error?: string };
+            if (!resp.ok || !data.code || !data.sharedSecret) {
+              res.writeHead(resp.status || 500);
+              res.end(JSON.stringify({ ok: false, error: data.error || 'pair-failed' }));
+              return;
+            }
+
+            // Persist the shared secret + mark channel enabled so handleInbound is gated.
+            if (!cfg.channels) cfg.channels = {};
+            cfg.channels.alexa = {
+              ...(cfg.channels.alexa || {}),
+              enabled: true,
+              sharedSecret: data.sharedSecret,
+            };
+            saveConfig(cfg);
+            // Initialize the channel if it wasn't already running.
+            await channelManager.init().catch(() => {});
+
+            res.writeHead(200);
+            res.end(JSON.stringify({ ok: true, code: data.code, expiresAt: data.expiresAt }));
+          } catch (err: any) {
+            log.warn(`[alexa/pair] ${err.message}`);
+            res.writeHead(500);
+            res.end(JSON.stringify({ ok: false, error: err.message }));
+          }
+        })();
+        return;
+      }
+
+      // GET /api/channels/alexa/pair-page — inline HTML page showing the code with countdown.
+      // The chat surface auto-converts URLs ending in /pair-page into a button (see MessageBubble).
+      if (req.method === 'GET' && channelPath === '/api/channels/alexa/pair-page') {
+        res.setHeader('Content-Type', 'text/html');
+        res.writeHead(200);
+        res.end(`<!DOCTYPE html><html><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Connect Alexa | Bloby</title>
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+body{font-family:'Inter',system-ui,sans-serif;background:#0a0a0b;color:#e4e4e7;display:flex;align-items:center;justify-content:center;min-height:100vh;padding:1.5rem}
+.c{text-align:center;max-width:460px}
+h1{font-size:1.5rem;font-weight:700;margin-bottom:.5rem}
+p{color:#a1a1aa;line-height:1.6;margin-bottom:1rem;font-size:.95rem}
+.code{font-family:'JetBrains Mono','SF Mono',monospace;font-size:3rem;font-weight:700;letter-spacing:.5rem;color:#fff;background:#18181b;border:1px solid #27272a;border-radius:1rem;padding:1.5rem;margin:1.5rem 0;display:inline-block;min-width:280px}
+.countdown{font-size:.85rem;color:#71717a;margin-top:.5rem}
+.btn{display:inline-flex;align-items:center;justify-content:center;background:linear-gradient(135deg,#04D1FE,#AF27E3,#FB4072);border:none;border-radius:9999px;padding:.55rem 1.4rem;color:#fff;font-size:.875rem;font-weight:500;cursor:pointer;height:2.25rem;margin-top:.6rem}
+.btn:hover{opacity:.9}
+.hint{color:#52525b;font-size:.8rem;margin-top:1rem;font-style:italic}
+.err{color:#ef4444;margin-top:1rem}
+</style>
+</head><body><div class="c">
+<h1>Connect Alexa</h1>
+<p>Open the Alexa app on your phone and enable the <strong>Bloby</strong> skill. Then say:</p>
+<div class="code" id="code">— — — — — —</div>
+<p style="font-size:1rem;color:#e4e4e7">"Alexa, ask Bloby to link with code <span id="codeSpoken">———</span>"</p>
+<div class="countdown" id="cd"></div>
+<button class="btn" onclick="mint()">New code</button>
+<p class="hint">Once linked, you can say "Alexa, ask Bloby anything." Codes expire after 10 minutes.</p>
+<p class="err" id="err"></p>
+</div>
+<script>
+let expiresAt=0,timer=null;
+async function mint(){
+  document.getElementById('err').textContent='';
+  document.getElementById('code').textContent='— — — — — —';
+  document.getElementById('codeSpoken').textContent='———';
+  try{
+    const r=await fetch('/api/channels/alexa/pair',{method:'POST',headers:{'Content-Type':'application/json'},body:'{}'});
+    const d=await r.json();
+    if(!d.ok){document.getElementById('err').textContent=d.error||'Failed to mint code';return}
+    document.getElementById('code').textContent=d.code.split('').join(' ');
+    document.getElementById('codeSpoken').textContent=d.code;
+    expiresAt=new Date(d.expiresAt).getTime();
+    if(timer)clearInterval(timer);
+    timer=setInterval(tick,1000);tick();
+  }catch(e){document.getElementById('err').textContent=e.message}
+}
+function tick(){
+  const s=Math.max(0,Math.round((expiresAt-Date.now())/1000));
+  document.getElementById('cd').textContent=s>0?('Expires in '+Math.floor(s/60)+':'+String(s%60).padStart(2,'0')):'Expired — generate a new code';
+  if(s<=0&&timer){clearInterval(timer);timer=null}
+}
+mint();
+</script>
+</body></html>`);
+        return;
+      }
+
+      // GET /api/channels/alexa/status — current alexa channel status
+      if (req.method === 'GET' && channelPath === '/api/channels/alexa/status') {
+        const status = channelManager.getStatus('alexa');
+        res.writeHead(200);
+        res.end(JSON.stringify(status || { channel: 'alexa', connected: false }));
+        return;
+      }
+
       // Fallback for unknown channel routes
       res.writeHead(404);
       res.end(JSON.stringify({ error: 'Not found' }));