bloby-bot 0.48.1 → 0.48.3

package/package.json

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

package/shared/config.ts

@@ -18,15 +18,6 @@ export interface AlexaChannelConfig {
   /** 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 {

package/supervisor/channels/alexa.ts

@@ -18,20 +18,61 @@ 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. 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 }>>();
+  /** 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. */
-  reservePending(convId: string, timeoutMs = 25_000): Promise<string> {
+   *  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 slot = { resolve, reject, createdAt: Date.now() };
+      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 = [];
@@ -39,15 +80,22 @@ export class AlexaChannel implements ChannelProvider {
       }
       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.
+      // 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'));
@@ -64,6 +112,7 @@ export class AlexaChannel implements ChannelProvider {
     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;
   }
@@ -74,10 +123,60 @@ export class AlexaChannel implements ChannelProvider {
     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> {
@@ -86,9 +185,13 @@ export class AlexaChannel implements ChannelProvider {
   }
 
   async disconnect(): Promise<void> {
-    // Reject any in-flight resolvers so HTTP handlers don't hang forever.
+    // 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) slot.reject(new Error('alexa-disconnected'));
+      for (const slot of q) {
+        if (slot.turn?.fallbackTimer) clearTimeout(slot.turn.fallbackTimer);
+        slot.reject(new Error('alexa-disconnected'));
+      }
     }
     this.pending.clear();
   }
@@ -107,7 +210,6 @@ export class AlexaChannel implements ChannelProvider {
       connected: !!cfg?.enabled,
       info: {
         linked: !!cfg?.sharedSecret,
-        overflow: cfg?.overflow?.mode || 'chat-only',
       },
     };
   }

package/supervisor/channels/manager.ts

@@ -454,10 +454,16 @@ 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.
-      // 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);
+      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;
@@ -908,9 +914,17 @@ export class ChannelManager {
     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, timeoutMs = 25_000 } = opts;
+    const { text, alexaUserId, alexaSessionId, deviceId, locale, apiEndpoint, apiAccessToken, requestId, timeoutMs = 25_000 } = opts;
     const { workerApi, broadcastBloby, getModel } = this.opts;
     const model = getModel();
 
@@ -998,9 +1012,19 @@ export class ChannelManager {
 
     // 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`;
+    // 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,

package/supervisor/channels/types.ts

@@ -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' | 'alexa';
+  /** 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.