@vellumai/assistant 0.11.1 → 0.11.2-staging.2

package/src/notifications/notification-utils.ts

@@ -1,11 +1,13 @@
 /**
  * Shared leaf utilities for the notification pipeline.
  *
- * This module has no intra-pipeline imports — it depends only on Node
- * stdlib — so any notification module can import it without creating
+ * This module has no intra-pipeline imports (only Node stdlib and leaf
+ * utilities), so any notification module can import it without creating
  * circular dependencies.
  */
 
+import { isPlainObject } from "../util/object.js";
+
 // ── String helpers ──────────────────────────────────────────────────────────
 
 /** Return `value` trimmed, or `undefined` when blank/nullish. */
@@ -26,13 +28,29 @@ export function readPayloadString(
   payload: unknown,
   key: string,
 ): string | undefined {
-  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+  if (!isPlainObject(payload)) {
     return undefined;
   }
-  const value = (payload as Record<string, unknown>)[key];
+  const value = payload[key];
   return typeof value === "string" ? value : undefined;
 }
 
+/**
+ * Safely read a plain-object property from an unknown-typed payload object.
+ * Returns `undefined` when the payload is not an object or the key does not
+ * hold a plain object (arrays and `null` are rejected).
+ */
+export function readPayloadObject(
+  payload: unknown,
+  key: string,
+): Record<string, unknown> | undefined {
+  if (!isPlainObject(payload)) {
+    return undefined;
+  }
+  const value = payload[key];
+  return isPlainObject(value) ? value : undefined;
+}
+
 /** Truncate `text` to `maxLength`, appending "…" when exceeded. */
 export function truncate(text: string, maxLength: number): string {
   if (text.length <= maxLength) {
@@ -68,3 +86,20 @@ export const MESSAGE_PREVIEW_MAX_LENGTH = 200;
 export function sanitizeMessagePreview(value: string): string {
   return sanitize(value, MESSAGE_PREVIEW_MAX_LENGTH);
 }
+
+/** Character budget every notification title shares. */
+export const NOTIFICATION_TITLE_MAX_LENGTH = 60;
+
+/**
+ * Flatten an untrusted notification title onto a single line, stripping control
+ * characters and newlines and bounding it at `NOTIFICATION_TITLE_MAX_LENGTH`.
+ *
+ * The newline flattening is the load-bearing part: downstream consumers re-run
+ * the value through `normalizeTitle`, whose prose guard discards any string
+ * containing a newline outright, so a multi-line conversation title would be
+ * thrown away wholesale instead of salvaged. The length bound is a backstop;
+ * `normalizeTitle`'s tighter 40-character budget is what callers observe.
+ */
+export function sanitizeNotificationTitle(value: string): string {
+  return sanitize(value, NOTIFICATION_TITLE_MAX_LENGTH);
+}

package/src/notifications/signal.ts

@@ -122,6 +122,11 @@ export const NOTIFICATION_SOURCE_EVENT_NAMES = [
     description:
       "OAuth credential health issue detected (expired, revoked, missing scopes)",
   },
+  {
+    id: "chat.assistant_reply",
+    description:
+      "Assistant finished replying to a user-initiated turn the user is no longer watching",
+  },
   {
     id: "telegram.webhook_health_alert",
     description:
@@ -231,6 +236,11 @@ export interface NotificationSignal<TEventName extends string = string> {
   sourceEventName: TEventName; // free-form: 'reminder_fired', 'guardian_question', etc.
   contextPayload: NotificationContextPayload<TEventName>;
   attentionHints: AttentionHints;
+  /**
+   * Producer-supplied deduplication key. Deterministic decision paths reuse it
+   * as the decision's dedupeKey so the decision row matches the event row.
+   */
+  dedupeKey?: string;
   /** Routing intent from the source (e.g. reminder). Controls post-decision channel enforcement. */
   routingIntent?: RoutingIntent;
   /** Free-form hints from the source for the decision engine (e.g. preferred channels). */

package/src/notifications/types.ts

@@ -58,6 +58,10 @@ export const DeliveryResultSchema = z.object({
   success: z.boolean(),
   error: z.string().optional(),
   messageId: z.string().optional(),
+  /** Set only by the platform push adapter: true when the platform accepted
+   *  at least one device push for delivery (not proof of device receipt). */
+  remotePushAccepted: z.boolean().optional(),
+  remotePushPlatforms: z.array(z.enum(["ios", "android"])).optional(),
 });
 export type DeliveryResult = z.infer<typeof DeliveryResultSchema>;
 
@@ -95,6 +99,7 @@ export type RenderedChannelCopy = z.infer<typeof RenderedChannelCopySchema>;
 
 export const ChannelDeliveryPayloadSchema = z.object({
   deliveryId: z.string().optional(),
+  correlationId: z.string().optional(),
   sourceEventName: z.string(),
   copy: RenderedChannelCopySchema,
   deepLinkTarget: z.record(z.string(), z.unknown()).optional(),
@@ -106,6 +111,11 @@ export const ChannelDeliveryPayloadSchema = z.object({
    *  broadcaster so channel adapters render it without re-parsing
    *  `contextPayload`. */
   toolApprovalSource: ToolApprovalSourceViewSchema.optional(),
+  /** True when the platform (APNs) channel accepted a remote push for this
+   *  delivery. Set only on the vellum channel's payload so clients can avoid
+   *  double-bannering. */
+  remotePushDispatched: z.boolean().optional(),
+  remotePushPlatforms: z.array(z.enum(["ios", "android"])).optional(),
 });
 export type ChannelDeliveryPayload = z.infer<
   typeof ChannelDeliveryPayloadSchema
@@ -119,11 +129,16 @@ export interface ChannelUpdatePayload {
 // -- Channel adapter interface ------------------------------------------------
 
 /** Interface that each channel adapter must implement. */
+export type ChannelDeliveryObserver = {
+  onRemotePushPlatforms(platforms: ("ios" | "android")[]): void;
+};
+
 export interface ChannelAdapter {
   channel: NotificationChannel;
   send(
     payload: ChannelDeliveryPayload,
     destination: ChannelDestination,
+    observer?: ChannelDeliveryObserver,
   ): Promise<DeliveryResult>;
   update?(
     delivery: ChannelUpdateContext,
@@ -183,5 +198,7 @@ export interface NotificationDecision {
   dedupeKey: string;
   confidence: number;
   fallbackUsed: boolean;
+  /** Set by deterministic pass-through branches whose copy is producer-supplied verbatim; exempts the copy from the event-name-collision quality check. */
+  verbatimCopy?: boolean;
   persistedDecisionId?: string;
 }

package/src/persistence/bookmark-crud.ts

@@ -1,4 +1,4 @@
-import { desc, eq } from "drizzle-orm";
+import { and, desc, eq, type SQL } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
 import type { DrizzleDb } from "./db-connection.js";
@@ -79,21 +79,30 @@ function rowToSummary(row: BookmarkJoinRow): BookmarkSummary {
   };
 }
 
-function selectBookmarkJoin(db: DrizzleDb) {
+/**
+ * CROSS JOIN constrains SQLite's join order to start from message_bookmarks,
+ * which the planner would otherwise skip in favor of a full messages scan
+ * because an empty table never has statistics. The join predicates live in
+ * WHERE with identical semantics; callers pass extra conditions through
+ * `filter` because chaining `.where()` would replace the predicates.
+ */
+function selectBookmarkJoin(db: DrizzleDb, filter?: SQL) {
+  const joinMatch = and(
+    eq(messages.id, messageBookmarks.messageId),
+    eq(conversations.id, messageBookmarks.conversationId),
+  );
   return db
     .select(BOOKMARK_JOIN_COLUMNS)
     .from(messageBookmarks)
-    .innerJoin(messages, eq(messages.id, messageBookmarks.messageId))
-    .innerJoin(
-      conversations,
-      eq(conversations.id, messageBookmarks.conversationId),
-    );
+    .crossJoin(messages)
+    .crossJoin(conversations)
+    .where(filter ? and(joinMatch, filter) : joinMatch);
 }
 
 /**
  * List all bookmarks newest-first, joined against `messages` and
  * `conversations`. Bookmarks whose parent message or conversation has
- * been deleted are naturally excluded by the inner-join semantics; the
+ * been deleted are naturally excluded by the join predicates; the
  * `ON DELETE CASCADE` on the FKs means rows should never end up in this
  * orphan state, but the join provides a defense-in-depth guarantee.
  */
@@ -179,7 +188,7 @@ function readBookmarkSummaryOrThrow(
   db: DrizzleDb,
   id: string,
 ): BookmarkSummary {
-  const row = selectBookmarkJoin(db).where(eq(messageBookmarks.id, id)).get();
+  const row = selectBookmarkJoin(db, eq(messageBookmarks.id, id)).get();
   if (!row) {
     // Unreachable: caller just observed (or inserted) this id.
     throw new Error(`Bookmark ${id} disappeared between insert and read`);

package/src/persistence/conversation-attention-store.ts

@@ -61,6 +61,32 @@ export interface AttentionState {
   updatedAt: number;
 }
 
+/**
+ * True when the latest assistant cursor is ahead of the last-seen cursor.
+ *
+ * The single definition of "unseen" for the sidebar indicator
+ * (`buildAssistantAttention` in `runtime/services/conversation-serializer.ts`)
+ * and the assistant-reply push producer, so the badge and the notification
+ * cannot disagree. An absent state row reads as seen.
+ */
+export function hasUnseenLatestAssistantMessage(
+  state:
+    | Pick<
+        AttentionState,
+        "latestAssistantMessageAt" | "lastSeenAssistantMessageAt"
+      >
+    | null
+    | undefined,
+): boolean {
+  if (!state || state.latestAssistantMessageAt == null) {
+    return false;
+  }
+  return (
+    state.lastSeenAssistantMessageAt == null ||
+    state.lastSeenAssistantMessageAt < state.latestAssistantMessageAt
+  );
+}
+
 // ── Row mappers ──────────────────────────────────────────────────────
 
 function rowToEvent(

package/src/persistence/conversation-crud.ts

@@ -74,6 +74,7 @@ import { deleteConversationRowsInBatches } from "./conversation-row-batch-delete
 import {
   BACKGROUND_CONVERSATION_TYPES,
   type ConversationCreateType,
+  isHiddenMessageMetadata,
 } from "./conversation-types.js";
 import { runAsyncSqlite } from "./db-async-query.js";
 import {
@@ -297,14 +298,35 @@ export const messageMetadataSchema = z
      * treat message text as organic user input.
      */
     hidden: z.boolean().optional(),
+    /**
+     * Marks a role-`"user"` row that opened a live phone or in-app voice turn.
+     * Test with {@link isVoiceSessionUserMessage}, which documents why the
+     * channel/interface fields cannot stand in for it.
+     */
+    voiceSessionTurn: z.boolean().optional(),
     /**
      * Discriminates daemon-authored rows from ordinary turns.
      * `"system_card"` marks pre-composed status cards (the /compact, /clean,
      * and summarize-up-to results); see {@link SYSTEM_CARD_MESSAGE_KIND}.
-     * Kept as a plain string so unknown future kinds never fail metadata
-     * validation.
+     * `"provider_error"` marks the synthetic assistant row the agent loop
+     * persists when a turn dies on the provider-error path; see
+     * {@link PROVIDER_ERROR_MESSAGE_KIND}. Kept as a plain string so unknown
+     * future kinds never fail metadata validation.
      */
     messageKind: z.string().optional(),
+    /**
+     * Stable classified error code (`ClassifiedConversationError.code`, e.g.
+     * `"PROVIDER_BILLING"`) stamped alongside
+     * `messageKind: "provider_error"` on persisted provider-failure rows.
+     */
+    providerErrorCode: z.string().optional(),
+    /**
+     * Classified error category (`ClassifiedConversationError.errorCategory`,
+     * e.g. `"credits_exhausted"`) stamped alongside
+     * `messageKind: "provider_error"`. Clients switch on this to pick a
+     * themed rendering for the row.
+     */
+    providerErrorCategory: z.string().optional(),
     /**
      * Structured terminal record stamped onto a `<background_event
      * source="background-tool">` wake so the web can rebuild the inline
@@ -348,17 +370,17 @@ export const messageMetadataSchema = z
 export type MessageMetadata = z.infer<typeof messageMetadataSchema>;
 
 /**
- * Shared predicate for the transcript-suppression flag on user-message
- * metadata (see the `hidden` field on {@link messageMetadataSchema}). One
- * definition so the sites that must agree — echo suppression, list-messages
- * filtering, queued-snapshot filtering, indexing exclusion, and downstream
- * consumers of message text — cannot drift.
+ * Pure predicates over the `metadata` record above. They live in the
+ * `conversation-types` leaf so a caller that only classifies a row does not
+ * pull in this module's DB graph, and are re-exported here alongside the
+ * schema they read.
  */
-export function isHiddenMessageMetadata(
-  metadata: Record<string, unknown> | null | undefined,
-): boolean {
-  return metadata?.hidden === true;
-}
+export {
+  isBackgroundEventMetadata,
+  isEchoSuppressedUserMessage,
+  isHiddenMessageMetadata,
+  isVoiceSessionUserMessage,
+} from "./conversation-types.js";
 
 /**
  * `messageKind` value marking a daemon-authored system card — a pre-composed
@@ -369,6 +391,16 @@ export function isHiddenMessageMetadata(
  */
 export const SYSTEM_CARD_MESSAGE_KIND = "system_card";
 
+/**
+ * `messageKind` value marking the synthetic assistant row the agent loop
+ * persists when a turn terminates on the provider-error path (see the
+ * `persistProviderErrorAsAssistantMessage` branch). The row's text stays in
+ * LLM history like any assistant message; the marker (plus the
+ * `providerErrorCode`/`providerErrorCategory` fields stamped next to it) lets
+ * clients render the row as a themed notice instead of persona speech.
+ */
+export const PROVIDER_ERROR_MESSAGE_KIND = "provider_error";
+
 /**
  * Shared predicate for the system-card marker on assistant-message metadata
  * (see the `messageKind` field on {@link messageMetadataSchema}). One
@@ -382,11 +414,24 @@ export function isSystemCardMetadata(
 }
 
 /**
- * Row-level variant of {@link isSystemCardMetadata} for callers holding the
- * raw persisted `metadata` JSON string. The single place the parse lives so
- * display merging and turn grouping agree on what a card is.
+ * Shared predicate for the provider-error marker on assistant-message
+ * metadata (see the `messageKind` field on {@link messageMetadataSchema}).
+ * One definition so persistence stamping and wire projection cannot drift.
+ */
+export function isProviderErrorMetadata(
+  metadata: Record<string, unknown> | null | undefined,
+): boolean {
+  return metadata?.messageKind === PROVIDER_ERROR_MESSAGE_KIND;
+}
+
+/**
+ * True when an assistant row is a standalone display turn: a system card or
+ * a provider-error notice. Standalone rows never merge with adjacent
+ * assistant rows, and turn grouping closes on them, so display merging and
+ * the turn resolver agree on boundaries. Takes the raw persisted `metadata`
+ * JSON string; malformed JSON and non-assistant roles are never standalone.
  */
-export function isSystemCardMessage(
+export function isStandaloneAssistantMessage(
   role: string,
   metadata: string | null,
 ): boolean {
@@ -394,9 +439,8 @@ export function isSystemCardMessage(
     return false;
   }
   try {
-    return isSystemCardMetadata(
-      JSON.parse(metadata) as Record<string, unknown>,
-    );
+    const parsed = JSON.parse(metadata) as Record<string, unknown>;
+    return isSystemCardMetadata(parsed) || isProviderErrorMetadata(parsed);
   } catch {
     return false;
   }
@@ -4209,8 +4253,10 @@ export function getTurnTimeBounds(
 /**
  * Resolve all assistant message IDs that belong to the same agent turn
  * as the given `messageId`. A "turn" is bounded by:
- *   - The start of the conversation, or
- *   - A user message whose content is NOT a tool_result array.
+ *   - The start of the conversation,
+ *   - A user message whose content is NOT a tool_result array, or
+ *   - A standalone assistant row (see {@link isStandaloneAssistantMessage}),
+ *     which always forms its own single-row turn.
  *
  * Within a multi-step agent loop, the pattern is:
  *   user msg → assistant A1 → user (tool_result) → assistant A2 → ...
@@ -4229,9 +4275,10 @@ export function getAssistantMessageIdsInTurn(messageId: string): string[] {
     return [messageId];
   }
 
-  // A system card is its own single-row group — its linked calls (e.g. the
-  // summarize-up-to compaction call) never mix into a neighbouring turn.
-  if (isSystemCardMessage(target.role, target.metadata)) {
+  // A standalone row (system card or provider-error notice) is its own
+  // single-row group: its linked calls (e.g. the summarize-up-to compaction
+  // call) never mix into a neighbouring turn.
+  if (isStandaloneAssistantMessage(target.role, target.metadata)) {
     return [target.id];
   }
 
@@ -4261,9 +4308,9 @@ export function getAssistantMessageIdsInTurn(messageId: string): string[] {
 
   for (const row of backwardRows) {
     if (row.role === "assistant") {
-      if (isSystemCardMessage(row.role, row.metadata)) {
-        // A system card closes the groups on either side of it — rows
-        // before the card belong to an earlier display group.
+      if (isStandaloneAssistantMessage(row.role, row.metadata)) {
+        // A standalone row closes the groups on either side of it: rows
+        // before it belong to an earlier display group.
         boundaryCreatedAt = row.createdAt;
         break;
       }
@@ -4303,10 +4350,10 @@ export function getAssistantMessageIdsInTurn(messageId: string): string[] {
 
   for (const row of forwardRows) {
     if (row.role === "assistant") {
-      if (isSystemCardMessage(row.role, row.metadata)) {
-        // A card that is the queried user message's only reply (e.g. the
-        // /compact result) IS the turn's response; otherwise the card
-        // closes the group.
+      if (isStandaloneAssistantMessage(row.role, row.metadata)) {
+        // A standalone row that is the queried user message's only reply
+        // (e.g. the /compact result card, or a provider-error notice) IS
+        // the turn's response; otherwise it closes the group.
         if (assistantIds.length === 0) {
           assistantIds.push(row.id);
         }
@@ -4350,7 +4397,7 @@ export function getAssistantMessageIdsInTurn(messageId: string): string[] {
     for (const row of gapRows) {
       if (
         row.role === "assistant" &&
-        !isSystemCardMessage(row.role, row.metadata) &&
+        !isStandaloneAssistantMessage(row.role, row.metadata) &&
         !assistantIds.includes(row.id)
       ) {
         assistantIds.push(row.id);

package/src/persistence/conversation-queries.ts

@@ -902,16 +902,16 @@ function buildExcerptWithExternalContentMode(
 
   if (externalContentMode === "display") {
     text = unwrapExternalContentForDisplay(text);
-  } else {
-    const envelope = parseExternalContentEnvelope(text);
-    if (envelope) {
-      const innerExcerpt = buildExcerptFromText(envelope.content, query);
-      return wrapRecallEvidenceExcerpt(
-        innerExcerpt,
-        envelope.source,
-        envelope.origin,
-      );
-    }
+    return buildExcerptFromText(text, query, DISPLAY_EXCERPT_LEADING_CHARS);
+  }
+  const envelope = parseExternalContentEnvelope(text);
+  if (envelope) {
+    const innerExcerpt = buildExcerptFromText(envelope.content, query);
+    return wrapRecallEvidenceExcerpt(
+      innerExcerpt,
+      envelope.source,
+      envelope.origin,
+    );
   }
 
   return buildExcerptFromText(text, query);
@@ -985,19 +985,34 @@ function findEarliestMatch(
   return match ? { index: match.index, length: match[0].length } : null;
 }
 
-function buildExcerptFromText(text: string, query: string): string {
-  const WINDOW = 100;
+const EXCERPT_WINDOW = 100;
+
+/**
+ * Leading context for palette display excerpts. The result row truncates
+ * from the right, so a wide leading window can push the match past the
+ * visible cutoff; recall evidence keeps the full window.
+ */
+const DISPLAY_EXCERPT_LEADING_CHARS = 30;
+
+function buildExcerptFromText(
+  text: string,
+  query: string,
+  leadingChars: number = EXCERPT_WINDOW,
+): string {
   const match = findEarliestMatch(text, query);
   if (!match) {
     // Neither the query nor any of its tokens is present (e.g. the lexical
     // index matched JSON structure instead); fall back to the text start.
     return text
-      .slice(0, WINDOW * 2)
+      .slice(0, EXCERPT_WINDOW * 2)
       .replace(/\s+/g, " ")
       .trim();
   }
-  const start = Math.max(0, match.index - WINDOW);
-  const end = Math.min(text.length, match.index + match.length + WINDOW);
+  const start = Math.max(0, match.index - leadingChars);
+  const end = Math.min(
+    text.length,
+    match.index + match.length + EXCERPT_WINDOW,
+  );
   const excerpt =
     (start > 0 ? "\u2026" : "") +
     text.slice(start, end).replace(/\s+/g, " ").trim() +