@vellumai/assistant 0.8.0 → 0.8.2

package/src/notifications/__tests__/home-feed-side-effect.test.ts

@@ -0,0 +1,199 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { FeedItem } from "../../home/feed-types.js";
+import type { NotificationSignal } from "../signal.js";
+import type {
+  NotificationDecision,
+  NotificationDeliveryResult,
+} from "../types.js";
+
+// ── Module mocks ───────────────────────────────────────────────────────
+//
+// `mock.module` is hoisted, so these intercepts apply before the module
+// under test resolves its imports. Closures over the module-scoped
+// arrays/flag below let each test reset state via `beforeEach` and
+// inspect captured calls afterwards.
+
+const appendCalls: FeedItem[] = [];
+const conversationLookups: string[] = [];
+let conversationRow: { conversationType: string } | null = null;
+let conversationLookupShouldThrow = false;
+
+mock.module("../../home/feed-writer.js", () => ({
+  appendFeedItem: async (item: FeedItem) => {
+    appendCalls.push(item);
+  },
+}));
+
+mock.module("../../memory/conversation-crud.js", () => ({
+  getConversation: (id: string) => {
+    conversationLookups.push(id);
+    if (conversationLookupShouldThrow) {
+      throw new Error("simulated conversation lookup failure");
+    }
+    return conversationRow;
+  },
+}));
+
+const { writeHomeFeedItemForSignal } =
+  await import("../home-feed-side-effect.js");
+
+// ── Test fixtures ──────────────────────────────────────────────────────
+
+function makeSignal(
+  overrides: Partial<NotificationSignal> = {},
+): NotificationSignal {
+  return {
+    signalId: "sig-test-1",
+    createdAt: 1700000000000,
+    sourceChannel: "scheduler",
+    sourceContextId: "conv-source-1",
+    sourceEventName: "schedule.notify",
+    contextPayload: {},
+    attentionHints: {
+      requiresAction: false,
+      urgency: "medium",
+      isAsyncBackground: false,
+      visibleInSourceNow: false,
+    },
+    ...overrides,
+  };
+}
+
+function makeDecision(
+  overrides: Partial<NotificationDecision> = {},
+): NotificationDecision {
+  return {
+    shouldNotify: true,
+    selectedChannels: [],
+    reasoningSummary: "test",
+    renderedCopy: {},
+    dedupeKey: "dk-1",
+    confidence: 1,
+    fallbackUsed: false,
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  appendCalls.length = 0;
+  conversationLookups.length = 0;
+  conversationRow = null;
+  conversationLookupShouldThrow = false;
+});
+
+describe("writeHomeFeedItemForSignal", () => {
+  test("background conversation signal writes a feed item with rendered copy", async () => {
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal();
+    const decision = makeDecision({
+      renderedCopy: {
+        vellum: {
+          title: "Background job done",
+          body: "Summary of what happened.",
+        },
+      },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, decision, []);
+
+    expect(conversationLookups).toEqual(["conv-source-1"]);
+    expect(item).not.toBeNull();
+    expect(appendCalls).toHaveLength(1);
+    const appended = appendCalls[0]!;
+    expect(appended.id).toBe("notif:sig-test-1");
+    expect(appended.type).toBe("notification");
+    // v2 dropped source/author — the side effect must construct items
+    // without those fields.
+    expect((appended as { source?: unknown }).source).toBeUndefined();
+    expect((appended as { author?: unknown }).author).toBeUndefined();
+    expect(appended.priority).toBe(50);
+    expect(appended.status).toBe("new");
+    expect(appended.title).toBe("Background job done");
+    expect(appended.summary).toBe("Summary of what happened.");
+    expect(appended.urgency).toBe("medium");
+    expect(typeof appended.timestamp).toBe("string");
+    expect(appended.createdAt).toBe(appended.timestamp);
+  });
+
+  test("non-background conversation with no async hint returns null and does not write", async () => {
+    conversationRow = { conversationType: "standard" };
+    const signal = makeSignal({
+      attentionHints: {
+        requiresAction: false,
+        urgency: "low",
+        isAsyncBackground: false,
+        visibleInSourceNow: true,
+      },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+
+    expect(item).toBeNull();
+    expect(appendCalls).toHaveLength(0);
+  });
+
+  test("isAsyncBackground hint writes even when sourceContextId does not resolve", async () => {
+    // No conversation row matches; the conversation lookup is bypassed
+    // entirely because the hint short-circuits the filter.
+    conversationLookupShouldThrow = true;
+    const signal = makeSignal({
+      sourceContextId: "not-a-conversation-id",
+      attentionHints: {
+        requiresAction: false,
+        urgency: "high",
+        isAsyncBackground: true,
+        visibleInSourceNow: false,
+      },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+
+    expect(item).not.toBeNull();
+    expect(appendCalls).toHaveLength(1);
+    expect(appendCalls[0]!.urgency).toBe("high");
+    // The async-background short-circuit must not consult the conversation store.
+    expect(conversationLookups).toHaveLength(0);
+  });
+
+  test("vellum delivery result conversationId propagates onto the feed item", async () => {
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal();
+    const deliveryResults: NotificationDeliveryResult[] = [
+      {
+        channel: "telegram",
+        destination: "chat-1",
+        status: "sent",
+        conversationId: "conv-telegram-1",
+      },
+      {
+        channel: "vellum",
+        destination: "vellum-client",
+        status: "sent",
+        conversationId: "conv-vellum-1",
+      },
+    ];
+
+    const item = await writeHomeFeedItemForSignal(
+      signal,
+      makeDecision(),
+      deliveryResults,
+    );
+
+    expect(item?.conversationId).toBe("conv-vellum-1");
+    expect(appendCalls[0]!.conversationId).toBe("conv-vellum-1");
+  });
+
+  test("falls back to sourceEventName when no rendered copy or payload title is present", async () => {
+    conversationRow = { conversationType: "scheduled" };
+    const signal = makeSignal({
+      sourceEventName: "watcher.notification",
+      contextPayload: {},
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+
+    expect(item?.title).toBe("watcher.notification");
+    expect(item?.summary).toBe("watcher.notification");
+  });
+});

package/src/notifications/__tests__/signal-registry.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from "bun:test";
+
+import { NOTIFICATION_SOURCE_EVENT_NAMES } from "../signal.js";
+
+describe("NOTIFICATION_SOURCE_EVENT_NAMES", () => {
+  test("includes activity.failed", () => {
+    expect(
+      NOTIFICATION_SOURCE_EVENT_NAMES.some((e) => e.id === "activity.failed"),
+    ).toBe(true);
+  });
+
+  test("still includes activity.complete (regression guard)", () => {
+    expect(
+      NOTIFICATION_SOURCE_EVENT_NAMES.some((e) => e.id === "activity.complete"),
+    ).toBe(true);
+  });
+});

package/src/notifications/adapters/platform.ts

@@ -0,0 +1,171 @@
+/**
+ * Platform push adapter — delivers notifications to iOS/web clients via
+ * the platform's APNs dispatch endpoint.
+ *
+ * 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` LD flag server-side (returning 202
+ * with `{ skipped: "flag_off" }` when the flag is OFF — no action needed
+ * from the daemon).
+ *
+ * Guardian-sensitive notifications (approval requests, escalation alerts)
+ * are annotated with `targetGuardianPrincipalId` so the platform can
+ * scope APNs fan-out to guardian-bound devices, mirroring the macOS adapter.
+ */
+
+import { VellumPlatformClient } from "../../platform/client.js";
+import { getLogger } from "../../util/logger.js";
+import {
+  isRetryableNetworkError,
+  isRetryableStatus,
+  sleep,
+} from "../../util/retry.js";
+import type {
+  ChannelAdapter,
+  ChannelDeliveryPayload,
+  ChannelDestination,
+  DeliveryResult,
+  NotificationChannel,
+} from "../types.js";
+import { isGuardianSensitiveEvent } from "./macos.js";
+
+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;
+
+interface DispatchBody {
+  delivery_id?: string;
+  source_event_name: string;
+  title: string;
+  body: string;
+  deep_link_metadata?: Record<string, unknown>;
+  context_payload?: Record<string, unknown>;
+  target_guardian_principal_id?: string;
+}
+
+export class PlatformPushAdapter implements ChannelAdapter {
+  readonly channel: NotificationChannel = "platform";
+
+  async send(
+    payload: ChannelDeliveryPayload,
+    destination: ChannelDestination,
+  ): Promise<DeliveryResult> {
+    const client = await VellumPlatformClient.create();
+    if (!client) {
+      log.warn(
+        { sourceEventName: payload.sourceEventName },
+        "Platform client unavailable — skipping push dispatch",
+      );
+      return { success: false, error: "platform client unavailable" };
+    }
+
+    if (!client.platformAssistantId) {
+      log.warn(
+        { sourceEventName: payload.sourceEventName },
+        "Platform assistant ID not configured — skipping push dispatch",
+      );
+      return { success: false, error: "platform assistant ID not configured" };
+    }
+
+    const guardianPrincipalId =
+      typeof destination.metadata?.guardianPrincipalId === "string"
+        ? destination.metadata.guardianPrincipalId
+        : undefined;
+
+    const targetGuardianPrincipalId =
+      guardianPrincipalId &&
+      isGuardianSensitiveEvent(payload.sourceEventName)
+        ? guardianPrincipalId
+        : undefined;
+
+    const body: DispatchBody = {
+      delivery_id: payload.deliveryId,
+      source_event_name: payload.sourceEventName,
+      title: payload.copy.title,
+      body: payload.copy.body,
+      deep_link_metadata: payload.deepLinkTarget,
+      context_payload: payload.contextPayload,
+      target_guardian_principal_id: targetGuardianPrincipalId,
+    };
+
+    const path = `/v1/assistants/${encodeURIComponent(client.platformAssistantId)}/push/dispatch/`;
+
+    for (let attempt = 0; attempt <= RETRY_DELAYS_MS.length; attempt++) {
+      let response: Response;
+      try {
+        response = await client.fetch(path, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(body),
+        });
+      } catch (err) {
+        if (
+          attempt < RETRY_DELAYS_MS.length &&
+          isRetryableNetworkError(err)
+        ) {
+          log.warn(
+            {
+              attempt,
+              sourceEventName: payload.sourceEventName,
+              err: err instanceof Error ? err.message : String(err),
+            },
+            "Network error dispatching push — retrying",
+          );
+          await sleep(RETRY_DELAYS_MS[attempt]!);
+          continue;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        log.error(
+          { attempt, sourceEventName: payload.sourceEventName, err },
+          "Failed to dispatch platform push notification",
+        );
+        return { success: false, error: message };
+      }
+
+      if (response.ok) {
+        log.info(
+          {
+            sourceEventName: payload.sourceEventName,
+            title: payload.copy.title,
+            guardianScoped: targetGuardianPrincipalId != null,
+            status: response.status,
+          },
+          "Platform push dispatched",
+        );
+        return { success: true };
+      }
+
+      if (attempt < RETRY_DELAYS_MS.length && isRetryableStatus(response.status)) {
+        log.warn(
+          {
+            attempt,
+            status: response.status,
+            sourceEventName: payload.sourceEventName,
+          },
+          "Retryable status from push dispatch endpoint",
+        );
+        await sleep(RETRY_DELAYS_MS[attempt]!);
+        continue;
+      }
+
+      const errorText = await response.text().catch(() => "");
+      log.error(
+        {
+          status: response.status,
+          sourceEventName: payload.sourceEventName,
+          body: errorText.slice(0, 256),
+        },
+        "Non-retryable error from push dispatch endpoint",
+      );
+      return {
+        success: false,
+        error: `HTTP ${response.status}: ${errorText.slice(0, 128)}`,
+      };
+    }
+
+    // Unreachable — loop always returns or continues, but TypeScript needs this.
+    return { success: false, error: "retry exhausted" };
+  }
+}

package/src/notifications/conversation-pairing.ts

@@ -103,11 +103,11 @@ export async function pairDeliveryWithConversation(
   try {
     const strategy = getConversationStrategy(channel as ChannelId);
 
-    if (strategy === "not_deliverable") {
+    if (strategy === "not_deliverable" || strategy === "push_only") {
       return {
         conversationId: null,
         messageId: null,
-        strategy: "not_deliverable",
+        strategy,
         createdNewConversation: false,
         conversationFallbackUsed: false,
       };
@@ -120,7 +120,8 @@ export async function pairDeliveryWithConversation(
     // Channels with continue_existing_conversation reuse bound external conversations
     // and mark them as background so they don't clutter the sidebar UI.
     const conversationType =
-      strategy === "start_new_conversation" ? "standard" : "background";
+      signal.conversationMetadata?.conversationType ??
+      (strategy === "start_new_conversation" ? "standard" : "background");
 
     // Prefer model-provided conversationSeedMessage when present and sane;
     // fall back to the runtime composer which adapts verbosity to the

package/src/notifications/copy-composer.ts

@@ -562,6 +562,21 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
     body: str(payload.summary, "An activity has completed"),
   }),
 
+  "activity.failed": (payload) => {
+    const jobName = str(payload.jobName, "background job");
+    const errorKind = str(payload.errorKind, "exception");
+    const rawMessage =
+      typeof payload.errorMessage === "string"
+        ? payload.errorMessage
+        : "no message";
+    const truncated =
+      rawMessage.length > 200 ? rawMessage.slice(0, 200) + "…" : rawMessage;
+    return {
+      title: `Background job failed: ${jobName}`,
+      body: `${errorKind}: ${truncated}`,
+    };
+  },
+
   "quick_chat.response_ready": (payload) => ({
     title: "Response Ready",
     body: str(payload.preview, "Your quick chat response is ready"),

package/src/notifications/decision-engine.ts

@@ -326,8 +326,9 @@ function buildFallbackDecision(
   signal: NotificationSignal,
   availableChannels: NotificationChannel[],
 ): NotificationDecision {
+  const urgency = signal.attentionHints.urgency;
   const isHighUrgencyAction =
-    signal.attentionHints.urgency === "high" &&
+    (urgency === "high" || urgency === "critical") &&
     signal.attentionHints.requiresAction;
 
   // Always include the vellum channel in the fallback — it's a local

package/src/notifications/destination-resolver.ts

@@ -126,6 +126,27 @@ export function resolveDestinations(
         );
         break;
       }
+      case "platform": {
+        // Platform delivery goes through the daemon's VellumPlatformClient —
+        // no external binding needed. Include guardianPrincipalId so the
+        // adapter can scope guardian-sensitive notifications.
+        const platformGuardian = findGuardianForChannel("vellum");
+        const platformMeta: Record<string, unknown> = {};
+        if (platformGuardian) {
+          platformMeta.guardianPrincipalId =
+            platformGuardian.contact.principalId;
+        }
+        result.set("platform", {
+          channel: "platform",
+          metadata:
+            Object.keys(platformMeta).length > 0 ? platformMeta : undefined,
+        });
+        log.debug(
+          { channel: "platform", source: "contacts", hasEndpoint: false },
+          "destination resolved",
+        );
+        break;
+      }
       default: {
         // Future deliverable channels without a resolver — skip silently.
         break;

package/src/notifications/emit-signal.ts

@@ -13,8 +13,10 @@ import { v4 as uuid } from "uuid";
 
 import { getDeliverableChannels } from "../channels/config.js";
 import { findGuardianForChannel } from "../contacts/contact-store.js";
+import type { ConversationCreateType } from "../memory/conversation-crud.js";
 import { getLogger } from "../util/logger.js";
 import { type BroadcastFn, VellumAdapter } from "./adapters/macos.js";
+import { PlatformPushAdapter } from "./adapters/platform.js";
 import { SlackAdapter } from "./adapters/slack.js";
 import { TelegramAdapter } from "./adapters/telegram.js";
 import {
@@ -28,6 +30,7 @@ import {
   runDeterministicChecks,
 } from "./deterministic-checks.js";
 import { createEvent, updateEventDedupeKey } from "./events-store.js";
+import { writeHomeFeedItemForSignal } from "./home-feed-side-effect.js";
 import { dispatchDecision } from "./runtime-dispatch.js";
 import type {
   AttentionHints,
@@ -61,7 +64,11 @@ export function registerBroadcastFn(fn: BroadcastFn): void {
 
 function getBroadcaster(): NotificationBroadcaster {
   if (!broadcasterInstance) {
-    const adapters = [new TelegramAdapter(), new SlackAdapter()];
+    const adapters = [
+      new TelegramAdapter(),
+      new SlackAdapter(),
+      new PlatformPushAdapter(),
+    ];
     if (registeredBroadcastFn) {
       adapters.unshift(new VellumAdapter(registeredBroadcastFn));
     }
@@ -110,6 +117,16 @@ function getConnectedChannels(): NotificationChannel[] {
         // always available when the daemon is running).
         channels.push(channel);
         break;
+      case "platform":
+        // Platform push is connected when the daemon has a registered
+        // broadcast function — i.e., full daemon mode where platform
+        // credentials are also available. Mirrors the vellum gate so
+        // the decision engine doesn't route to platform in standalone
+        // CLI contexts where VellumPlatformClient.create() returns null.
+        if (registeredBroadcastFn) {
+          channels.push(channel);
+        }
+        break;
       case "telegram": {
         // A binding-based channel is connected when the guardian has an
         // active channel entry with a valid delivery endpoint. The
@@ -188,6 +205,7 @@ export interface EmitSignalParams<TEventName extends string = string> {
     groupId?: string;
     scheduleJobId?: string;
     source?: string;
+    conversationType?: ConversationCreateType;
   };
 }
 
@@ -264,7 +282,24 @@ export async function emitNotificationSignal<TEventName extends string>(
 
     let decision = await evaluateSignal(signal, connectedChannels);
 
-    // Step 2.5: Enforce routing intent policy (fire-time guard)
+    // Step 2.5a: High/critical urgency signals always get a system
+    // notification via the vellum channel, regardless of what the
+    // decision engine selected. This ensures macOS surfaces a banner
+    // even when the app is focused.
+    const urgency = signal.attentionHints.urgency;
+    if (
+      (urgency === "high" || urgency === "critical") &&
+      decision.shouldNotify &&
+      !decision.selectedChannels.includes("vellum")
+    ) {
+      decision = {
+        ...decision,
+        selectedChannels: ["vellum", ...decision.selectedChannels],
+        reasoningSummary: `${decision.reasoningSummary} (vellum forced: ${urgency} urgency)`,
+      };
+    }
+
+    // Step 2.5b: Enforce routing intent policy (fire-time guard)
     const preEnforcementDecision = decision;
     decision = enforceRoutingIntent(
       decision,
@@ -349,6 +384,17 @@ export async function emitNotificationSignal<TEventName extends string>(
         : undefined,
     );
 
+    // Step 5: Mirror background-origin signals into the home activity feed.
+    // The helper itself decides whether to write (background filter); we
+    // catch and log so a feed-write failure cannot poison the dispatch result.
+    await writeHomeFeedItemForSignal(
+      signal,
+      decision,
+      dispatchResult.deliveryResults,
+    ).catch((err) => {
+      log.warn({ err, signalId }, "writeHomeFeedItemForSignal threw");
+    });
+
     log.info(
       {
         signalId,