@vellumai/assistant 0.11.1 → 0.11.2-staging.2

package/src/notifications/adapters/platform.ts

@@ -1,17 +1,14 @@
 /**
- * Platform push adapter — delivers notifications to iOS/web clients via
- * the platform's APNs dispatch endpoint.
+ * Platform push adapter for native mobile notification delivery.
  *
  * POSTs a `notification_intent` payload to
  * `/v1/assistants/{id}/push/dispatch/`. The platform endpoint fans the
- * notification out to all registered device tokens for the bound user and
- * gates on the `ios-remote-push-enabled` feature flag server-side (returning 202
- * with `{ skipped: "flag_off" }` when the flag is OFF — no action needed
- * from the daemon).
+ * notification out to registered device tokens for the bound user. Provider
+ * feature gates return 202 with `{ skipped: "flag_off" }` when no provider runs.
  *
  * Guardian-sensitive notifications (approval requests, access requests)
  * are annotated with `targetGuardianPrincipalId` so the platform can
- * scope APNs fan-out to guardian-bound devices, mirroring the macOS adapter.
+ * scope native fan-out to guardian-bound devices, mirroring the macOS adapter.
  */
 
 import { VellumPlatformClient } from "../../platform/client.js";
@@ -23,6 +20,7 @@ import {
 } from "../../util/retry.js";
 import type {
   ChannelAdapter,
+  ChannelDeliveryObserver,
   ChannelDeliveryPayload,
   ChannelDestination,
   DeliveryResult,
@@ -35,6 +33,17 @@ const log = getLogger("notif-adapter-platform");
 // Exponential backoff delays for 5xx/timeout retries: 250ms → 1s → 4s
 const RETRY_DELAYS_MS = [250, 1_000, 4_000] as const;
 
+// Per-attempt abort timeout. The underlying platform fetch has no timeout of
+// its own, and the broadcaster defers the urgent local banner on this
+// dispatch's outcome -- a hung platform must fail the attempt, not stall it.
+const ATTEMPT_TIMEOUT_MS = 5_000;
+
+/** Whether a fetch error is the per-attempt abort timeout firing. */
+function isAttemptTimeout(err: unknown): boolean {
+  const name = (err as { name?: unknown } | null)?.name;
+  return name === "TimeoutError" || name === "AbortError";
+}
+
 interface DispatchBody {
   delivery_id?: string;
   source_event_name: string;
@@ -45,12 +54,29 @@ interface DispatchBody {
   target_guardian_principal_id?: string;
 }
 
+type RemotePushPlatform = "ios" | "android";
+
+function acceptedPlatforms(body: unknown): RemotePushPlatform[] | undefined {
+  if (typeof body !== "object" || body === null) {
+    return undefined;
+  }
+  const value = (body as { accepted_platforms?: unknown }).accepted_platforms;
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  return value.filter(
+    (platform): platform is RemotePushPlatform =>
+      platform === "ios" || platform === "android",
+  );
+}
+
 export class PlatformPushAdapter implements ChannelAdapter {
   readonly channel: NotificationChannel = "platform";
 
   async send(
     payload: ChannelDeliveryPayload,
     destination: ChannelDestination,
+    observer?: ChannelDeliveryObserver,
   ): Promise<DeliveryResult> {
     const client = await VellumPlatformClient.create();
     if (!client) {
@@ -80,7 +106,7 @@ export class PlatformPushAdapter implements ChannelAdapter {
         : undefined;
 
     const body: DispatchBody = {
-      delivery_id: payload.deliveryId,
+      delivery_id: payload.correlationId ?? payload.deliveryId,
       source_event_name: payload.sourceEventName,
       title: payload.copy.title,
       body: payload.copy.body,
@@ -90,6 +116,10 @@ export class PlatformPushAdapter implements ChannelAdapter {
     };
 
     const path = `/v1/assistants/${encodeURIComponent(client.platformAssistantId)}/push/dispatch/`;
+    const accumulatedPlatforms = new Set<RemotePushPlatform>();
+    let platformsReported = false;
+    const remotePushPlatforms = () =>
+      platformsReported ? [...accumulatedPlatforms] : undefined;
 
     for (let attempt = 0; attempt <= RETRY_DELAYS_MS.length; attempt++) {
       let response: Response;
@@ -98,9 +128,13 @@ export class PlatformPushAdapter implements ChannelAdapter {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify(body),
+          signal: AbortSignal.timeout(ATTEMPT_TIMEOUT_MS),
         });
       } catch (err) {
-        if (attempt < RETRY_DELAYS_MS.length && isRetryableNetworkError(err)) {
+        if (
+          attempt < RETRY_DELAYS_MS.length &&
+          (isAttemptTimeout(err) || isRetryableNetworkError(err))
+        ) {
           log.warn(
             {
               attempt,
@@ -117,20 +151,62 @@ export class PlatformPushAdapter implements ChannelAdapter {
           { attempt, sourceEventName: payload.sourceEventName, err },
           "Failed to dispatch platform push notification",
         );
-        return { success: false, error: message };
+        return {
+          success: false,
+          error: message,
+          remotePushPlatforms: remotePushPlatforms(),
+        };
+      }
+
+      const responseText = await response.text().catch(() => "");
+      let responseBody: unknown = null;
+      try {
+        responseBody = JSON.parse(responseText) as unknown;
+      } catch {
+        responseBody = null;
+      }
+      const responsePlatforms = acceptedPlatforms(responseBody);
+      if (responsePlatforms) {
+        platformsReported = true;
+        for (const platform of responsePlatforms) {
+          accumulatedPlatforms.add(platform);
+        }
+        observer?.onRemotePushPlatforms(remotePushPlatforms()!);
       }
 
       if (response.ok) {
+        // A 2xx does not mean a push went out: the server returns
+        // 202 {"skipped": ...} when the feature flag is off or no tokens
+        // are registered, and 200 with tokens_sent: 0 on idempotent
+        // replays. Only report acceptance when the body confirms at least
+        // one device push was dispatched; an unparseable or ambiguous body
+        // counts as not accepted (a duplicate client banner beats a lost
+        // notification).
+        const parsedBody = responseBody as {
+          accepted_platforms?: unknown;
+          skipped?: unknown;
+          tokens_sent?: unknown;
+        } | null;
+        const remotePushAccepted =
+          parsedBody != null &&
+          !parsedBody.skipped &&
+          typeof parsedBody.tokens_sent === "number" &&
+          parsedBody.tokens_sent > 0;
         log.info(
           {
             sourceEventName: payload.sourceEventName,
             title: payload.copy.title,
             guardianScoped: targetGuardianPrincipalId != null,
             status: response.status,
+            remotePushAccepted,
           },
           "Platform push dispatched",
         );
-        return { success: true };
+        return {
+          success: true,
+          remotePushAccepted,
+          remotePushPlatforms: remotePushPlatforms(),
+        };
       }
 
       if (
@@ -149,18 +225,18 @@ export class PlatformPushAdapter implements ChannelAdapter {
         continue;
       }
 
-      const errorText = await response.text().catch(() => "");
       log.error(
         {
           status: response.status,
           sourceEventName: payload.sourceEventName,
-          body: errorText.slice(0, 256),
+          body: responseText.slice(0, 256),
         },
         "Non-retryable error from push dispatch endpoint",
       );
       return {
         success: false,
-        error: `HTTP ${response.status}: ${errorText.slice(0, 128)}`,
+        error: `HTTP ${response.status}: ${responseText.slice(0, 128)}`,
+        remotePushPlatforms: remotePushPlatforms(),
       };
     }
 

package/src/notifications/adapters/telegram.ts

@@ -49,14 +49,16 @@ export class TelegramAdapter implements ChannelAdapter {
         // Attempt rich delivery with inline keyboard buttons.
         // On failure, fall back to plain text below.
         try {
-          await sendTelegramReply(chatId, messageText, approval);
+          const sent = await sendTelegramReply(chatId, messageText, approval);
 
           log.info(
             { sourceEventName: payload.sourceEventName, chatId },
             "Telegram approval notification delivered with inline buttons",
           );
 
-          return { success: true };
+          // The message id lets the delivery row address the card later
+          // (in-place withdrawal when the request resolves elsewhere).
+          return { success: true, messageId: sent.lastMessageId };
         } catch (richErr) {
           log.warn(
             { err: richErr, sourceEventName: payload.sourceEventName, chatId },
@@ -73,14 +75,14 @@ export class TelegramAdapter implements ChannelAdapter {
           ? `${messageText}\n\n${approval.plainTextFallback}`
           : messageText;
 
-      await sendTelegramReply(chatId, fallbackText);
+      const sent = await sendTelegramReply(chatId, fallbackText);
 
       log.info(
         { sourceEventName: payload.sourceEventName, chatId },
         "Telegram notification delivered",
       );
 
-      return { success: true };
+      return { success: true, messageId: sent.lastMessageId };
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       // A missing bot token means the operator simply hasn't configured

package/src/notifications/assistant-reply-producer.ts

@@ -0,0 +1,219 @@
+/**
+ * `chat.assistant_reply` producer: an APNs push for a finished reply the user
+ * is no longer looking at.
+ *
+ * Called at the end of a user-initiated turn (see
+ * `daemon/conversation-turn-finalize.ts`) and best-effort throughout: every
+ * failure is logged and swallowed, because a notification hiccup must never
+ * escalate a reply the client already received into a turn-level throw.
+ */
+
+import type pino from "pino";
+
+import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
+import { getAttachmentMetadataForMessage } from "../persistence/attachments-store.js";
+import {
+  getAttentionStateByConversationIds,
+  hasUnseenLatestAssistantMessage,
+} from "../persistence/conversation-attention-store.js";
+import {
+  type ConversationRow,
+  getConversation,
+  getMessageById,
+  parseMessageMetadata,
+} from "../persistence/conversation-crud.js";
+import {
+  isReplyPushIneligibleUserMessage,
+  resolveConversationKind,
+} from "../persistence/conversation-types.js";
+import { stringifyMessageContent } from "../persistence/message-content.js";
+import { safeParseRecord } from "../util/json.js";
+import { emitNotificationSignal } from "./emit-signal.js";
+import {
+  sanitizeMessagePreview,
+  sanitizeNotificationTitle,
+} from "./notification-utils.js";
+
+/** Kill switch for this producer, on by default. */
+const ASSISTANT_REPLY_PUSH_FLAG = "assistant-reply-push" as const;
+
+/**
+ * Collapse whitespace runs ahead of the sanitizers' truncation: blank lines and
+ * list indentation would otherwise eat into the copy's length budget.
+ */
+function collapseWhitespace(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Body for a reply whose only user-visible output is attachments. Generated
+ * files and images are linked to the assistant row by
+ * `resolveAssistantAttachments` before the turn's terminal SSE, and are
+ * exposed separately from the row's content blocks, so a file-generation reply
+ * reaches this producer with no text to preview. Reads attachment metadata
+ * only (no base64), and only once the text preview has already come up empty.
+ *
+ * Returns an empty string when the row has no attachments either, which is the
+ * genuinely-empty reply the caller suppresses.
+ */
+function describeAttachmentOnlyReply(assistantMessageId: string): string {
+  const attachments = getAttachmentMetadataForMessage(assistantMessageId);
+  if (attachments.length === 0) {
+    return "";
+  }
+  if (attachments.length > 1) {
+    return `Sent ${attachments.length} attachments`;
+  }
+  // Filenames are model- and tool-authored, so one is sanitized before it can
+  // reach the lock screen. A filename that sanitizes away leaves generic copy
+  // rather than a dangling "Sent ".
+  const filename = sanitizeMessagePreview(
+    collapseWhitespace(attachments[0].originalFilename),
+  );
+  return filename ? `Sent ${filename}` : "Sent an attachment";
+}
+
+/**
+ * Read the markers the eligibility gate below consults off a persisted
+ * message's metadata column.
+ *
+ * `parseMessageMetadata` validates the whole column and yields nothing when
+ * any single field fails, so one unrecognized value would otherwise present
+ * here as "no metadata" and open every gate at once. The gate is a plain-record
+ * predicate, so a permissive read of the same JSON keeps it answering over
+ * whichever fields are intact.
+ */
+function readSuppressionMarkers(
+  metadataJson: string | null,
+): Record<string, unknown> | undefined {
+  const validated = parseMessageMetadata(metadataJson);
+  if (validated) {
+    return validated;
+  }
+  return metadataJson ? safeParseRecord(metadataJson) : undefined;
+}
+
+export async function emitAssistantReplyNotification(params: {
+  conversationId: string;
+  assistantMessageId: string;
+  /**
+   * The row that opened the turn, threaded from the agent loop. Reading it by
+   * id rather than scanning back from the assistant row keeps a hidden or
+   * queued user message that landed mid-turn from being mistaken for the
+   * prompt this reply answers.
+   */
+  userMessageId: string | undefined;
+  /**
+   * True when this turn's reply streams to the app and nowhere else, so the
+   * initiating row's channel and voice markers no longer describe where the
+   * reply lands. See {@link isReplyPushIneligibleUserMessage}.
+   */
+  replyDeliveredInAppOnly?: boolean;
+  rlog: pino.Logger;
+  /** Row the caller already holds; re-read when omitted. */
+  conversation?: ConversationRow | null;
+}): Promise<void> {
+  const { conversationId, assistantMessageId, userMessageId, rlog } = params;
+  try {
+    if (!isAssistantFeatureFlagEnabled(ASSISTANT_REPLY_PUSH_FLAG)) {
+      return;
+    }
+    if (!userMessageId) {
+      return;
+    }
+    const conversation = params.conversation ?? getConversation(conversationId);
+    if (!conversation) {
+      return;
+    }
+    // The other three kinds (memory consolidation, background, scheduled) each
+    // already have their own notification producer.
+    const kind = resolveConversationKind(
+      conversation.source,
+      conversation.conversationType,
+    );
+    if (kind !== "user") {
+      return;
+    }
+    const attention = getAttentionStateByConversationIds([conversationId]).get(
+      conversationId,
+    );
+    if (!hasUnseenLatestAssistantMessage(attention)) {
+      return;
+    }
+
+    const assistantRow = getMessageById(assistantMessageId, conversationId);
+    if (!assistantRow) {
+      return;
+    }
+
+    const initiatingMessage = getMessageById(userMessageId, conversationId);
+    if (!initiatingMessage) {
+      return;
+    }
+    const initiatingMetadata = readSuppressionMarkers(
+      initiatingMessage.metadata,
+    );
+    if (
+      isReplyPushIneligibleUserMessage(initiatingMetadata, {
+        replyDeliveredInAppOnly: params.replyDeliveredInAppOnly,
+      })
+    ) {
+      return;
+    }
+
+    // A reply whose output is entirely attachments has no text to preview, so
+    // fall back to naming them rather than suppressing a real reply. A reply
+    // with neither text nor attachments stays silent.
+    const preview =
+      sanitizeMessagePreview(
+        collapseWhitespace(stringifyMessageContent(assistantRow.content)),
+      ) ||
+      sanitizeMessagePreview(describeAttachmentOnlyReply(assistantMessageId));
+    if (!preview) {
+      return;
+    }
+
+    // Conversation titles are user-controlled and unbounded (renames, imports),
+    // so the title gets the same treatment as the body before it reaches the
+    // lock screen. Absent `requestedTitle` lets the decision branch derive a
+    // title from the body, which reads better than an empty or placeholder
+    // conversation title.
+    const requestedTitle = sanitizeNotificationTitle(
+      collapseWhitespace(conversation.title ?? ""),
+    );
+
+    await emitNotificationSignal({
+      sourceEventName: "chat.assistant_reply",
+      sourceChannel: "vellum",
+      // Deep-link target; the broadcaster validates it and merges it into
+      // `deepLinkTarget.conversationId`.
+      sourceContextId: conversationId,
+      attentionHints: {
+        requiresAction: false,
+        // Load-bearing for the iOS-only scope: `emit-signal.ts` force-adds the
+        // vellum channel for high/critical signals, which would widen this into
+        // an in-app banner on every client. Raising the urgency is the same as
+        // opting into v2.
+        urgency: "medium",
+        isAsyncBackground: false,
+        // The daemon cannot tell "still viewing" from "just left" at turn end.
+        // The viewing-on-iPhone case is covered by iOS suppressing remote
+        // pushes while the app is foregrounded.
+        visibleInSourceNow: false,
+      },
+      contextPayload: {
+        ...(requestedTitle ? { requestedTitle } : {}),
+        requestedMessage: preview,
+      },
+      // The pipeline dedupe window is a flat hour keyed on this alone, so it
+      // has to carry the message id or a second reply within the hour is
+      // silently dropped.
+      dedupeKey: `chat.assistant_reply:${conversationId}:${assistantMessageId}`,
+    });
+  } catch (err) {
+    rlog.warn(
+      { err, conversationId, messageId: assistantMessageId },
+      "Failed to emit assistant reply notification (non-fatal)",
+    );
+  }
+}