@vellumai/assistant 0.12.3-staging.1 → 0.12.3-staging.2

package/src/notifications/emit-signal.ts

@@ -31,6 +31,10 @@ import {
   type ConversationCreatedInfo,
   NotificationBroadcaster,
 } from "./broadcaster.js";
+import {
+  intersectChannelAllowlist,
+  readChannelAllowlist,
+} from "./channel-allowlist.js";
 import { enforceRoutingIntent, evaluateSignal } from "./decision-engine.js";
 import { updateDecision } from "./decisions-store.js";
 import {
@@ -51,6 +55,7 @@ import type {
 import type {
   NotificationChannel,
   NotificationDeliveryResult,
+  NotificationReceiptClass,
 } from "./types.js";
 
 const log = getLogger("emit-signal");
@@ -69,20 +74,27 @@ export function getBroadcaster(): NotificationBroadcaster {
       new PlatformPushAdapter(),
     ]);
 
-    // Wire the conversation-created callback so the macOS client is notified
-    // immediately when a vellum notification conversation is paired — before
-    // slower channel deliveries (e.g. Telegram) delay the push.
+    // Wire the conversation-created callback so the event goes out as soon
+    // as a vellum notification conversation is paired, before slower channel
+    // deliveries (e.g. Telegram) run.
+    // A guardian-sensitive conversation's title reaches only the guardian's
+    // own connections, the same scoping the vellum adapter applies to the
+    // notification itself.
     broadcasterInstance.setOnConversationCreated((info) => {
-      broadcastMessage({
-        type: "notification_conversation_created",
-        conversationId: info.conversationId,
-        title: info.title,
-        sourceEventName: info.sourceEventName,
-        targetGuardianPrincipalId: info.targetGuardianPrincipalId,
-        groupId: info.groupId,
-        source: info.source,
-        silent: info.silent,
-      });
+      broadcastMessage(
+        {
+          type: "notification_conversation_created",
+          conversationId: info.conversationId,
+          title: info.title,
+          sourceEventName: info.sourceEventName,
+          targetGuardianPrincipalId: info.targetGuardianPrincipalId,
+          groupId: info.groupId,
+          source: info.source,
+          silent: info.silent,
+        },
+        undefined,
+        { targetActorPrincipalId: info.targetGuardianPrincipalId },
+      );
       log.info(
         {
           conversationId: info.conversationId,
@@ -240,7 +252,9 @@ export interface EmitSignalResult {
   deduplicated: boolean;
   dispatched: boolean;
   reason: string;
+  selectedChannels: NotificationChannel[];
   deliveryResults: NotificationDeliveryResult[];
+  receiptClass: NotificationReceiptClass;
   /**
    * True when the pipeline threw before reaching a verdict. Dispatch, dedupe,
    * suppression, and a blocked deterministic check are all verdicts. Callers
@@ -250,6 +264,55 @@ export interface EmitSignalResult {
   pipelineFailed: boolean;
 }
 
+const PROVIDER_RECEIPT_CHANNELS = new Set(["telegram", "slack", "discord"]);
+
+/**
+ * Strongest proof the emit path can report from adapter results. A vellum
+ * `sent` row means the assistant broadcast a `notification_intent`; it is
+ * not a client ACK that the OS posted a banner.
+ */
+export function classifyNotificationReceipt(
+  results: readonly NotificationDeliveryResult[],
+): NotificationReceiptClass {
+  const accepted = results.filter((result) => {
+    return result.status === "sent" || result.status === "pending";
+  });
+  if (
+    accepted.some((result) => {
+      return PROVIDER_RECEIPT_CHANNELS.has(result.channel);
+    })
+  ) {
+    return "provider_accepted";
+  }
+  if (
+    accepted.some((result) => {
+      return result.channel === "platform";
+    })
+  ) {
+    return "gateway_accepted";
+  }
+  return "unknown";
+}
+
+function emitOutcome(
+  partial: Omit<
+    EmitSignalResult,
+    "deliveryResults" | "selectedChannels" | "receiptClass"
+  > & {
+    deliveryResults?: NotificationDeliveryResult[];
+    selectedChannels?: NotificationChannel[];
+  },
+): EmitSignalResult {
+  const deliveryResults = partial.deliveryResults ?? [];
+  const selectedChannels = partial.selectedChannels ?? [];
+  return {
+    ...partial,
+    selectedChannels,
+    deliveryResults,
+    receiptClass: classifyNotificationReceipt(deliveryResults),
+  };
+}
+
 /**
  * True when at least one channel adapter has already been handed the signal.
  * `sent` is a completed delivery; `pending` is the platform push that passed
@@ -333,14 +396,13 @@ export async function emitNotificationSignal<TEventName extends string>(
         { signalId, dedupeKey: params.dedupeKey },
         "Signal deduplicated at event store level",
       );
-      return {
+      return emitOutcome({
         signalId,
         deduplicated: true,
         dispatched: false,
         reason: "Signal deduplicated at event store level",
-        deliveryResults: [],
         pipelineFailed: false,
-      };
+      });
     }
     eventPersisted = true;
 
@@ -357,14 +419,13 @@ export async function emitNotificationSignal<TEventName extends string>(
         { signalId, reason: sourceActiveCheck.reason },
         "Signal suppressed before decision stage (source-active)",
       );
-      return {
+      return emitOutcome({
         signalId,
         deduplicated: false,
         dispatched: false,
         reason: `Signal suppressed: ${sourceActiveCheck.reason}`,
-        deliveryResults: [],
         pipelineFailed: false,
-      };
+      });
     }
 
     // Step 2: Evaluate the signal through the decision engine
@@ -398,8 +459,31 @@ export async function emitNotificationSignal<TEventName extends string>(
     // dispatch rank, so selection order only matters to single_channel
     // enforcement's first-selected fallback (step 2.5b), which must keep
     // the in-app banner rather than a push the server may skip.
+    const exclusiveAllowlist = readChannelAllowlist(signal.contextPayload);
     const urgency = signal.attentionHints.urgency;
-    if (
+    if (exclusiveAllowlist) {
+      // Exclusive allowlist wins over the default set, urgent force, and
+      // routing-intent expansion. Delivery is the allowlist intersected
+      // with connected channels.
+      const allowed = intersectChannelAllowlist(
+        exclusiveAllowlist,
+        connectedChannels,
+      );
+      const alreadyMatches =
+        allowed.length === decision.selectedChannels.length &&
+        allowed.every((channel) => {
+          return decision.selectedChannels.includes(channel);
+        }) &&
+        decision.shouldNotify === allowed.length > 0;
+      if (!alreadyMatches) {
+        decision = {
+          ...decision,
+          selectedChannels: allowed,
+          shouldNotify: allowed.length > 0,
+          reasoningSummary: `${decision.reasoningSummary} (channelAllowlist: ${allowed.join(", ") || "none available"})`,
+        };
+      }
+    } else if (
       (urgency === "high" || urgency === "critical") &&
       decision.shouldNotify
     ) {
@@ -427,13 +511,16 @@ export async function emitNotificationSignal<TEventName extends string>(
       }
     }
 
-    // Step 2.5b: Enforce routing intent policy (fire-time guard)
-    decision = enforceRoutingIntent(
-      decision,
-      signal.routingIntent,
-      connectedChannels,
-      signal.sourceChannel,
-    );
+    // Step 2.5b: Enforce routing intent policy (fire-time guard).
+    // An exclusive allowlist already closed the channel set.
+    if (!exclusiveAllowlist) {
+      decision = enforceRoutingIntent(
+        decision,
+        signal.routingIntent,
+        connectedChannels,
+        signal.sourceChannel,
+      );
+    }
 
     // Step 2.5c: Access-request signals carry a decisionable canonical
     // guardian request created before this emit, and that row suppresses
@@ -509,22 +596,21 @@ export async function emitNotificationSignal<TEventName extends string>(
           { signalId, reason: checkResult.reason },
           "Signal blocked by deterministic checks",
         );
-        return {
+        return emitOutcome({
           signalId,
           deduplicated: false,
           dispatched: false,
           reason: `Signal blocked by deterministic checks: ${checkResult.reason}`,
-          deliveryResults: [],
           pipelineFailed: false,
-        };
+        });
       }
     }
 
     // Step 4: Dispatch through the broadcaster
     // Note: notification_conversation_created events are emitted eagerly inside
     // the broadcaster as soon as vellum conversation pairing succeeds, rather
-    // than after all channel deliveries complete. This avoids a race where
-    // slow Telegram delivery delays the push past the macOS deep-link retry.
+    // than after all channel deliveries complete, so a slow Telegram delivery
+    // cannot delay it.
     const broadcaster = getBroadcaster();
     const dispatchResult = await dispatchDecision(
       signal,
@@ -562,14 +648,15 @@ export async function emitNotificationSignal<TEventName extends string>(
       },
       "Signal pipeline complete",
     );
-    return {
+    return emitOutcome({
       signalId,
       deduplicated: false,
       dispatched: dispatchResult.dispatched,
       reason: dispatchResult.reason,
+      selectedChannels: decision.selectedChannels,
       deliveryResults: dispatchResult.deliveryResults,
       pipelineFailed: false,
-    };
+    });
   } catch (err) {
     const errMsg = err instanceof Error ? err.message : String(err);
     log.error(
@@ -599,13 +686,12 @@ export async function emitNotificationSignal<TEventName extends string>(
     if (params.throwOnError) {
       throw err instanceof Error ? err : new Error(errMsg);
     }
-    return {
+    return emitOutcome({
       signalId,
       deduplicated: false,
       dispatched: false,
       reason: `Signal pipeline failed: ${errMsg}`,
-      deliveryResults: [],
       pipelineFailed: true,
-    };
+    });
   }
 }

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

@@ -30,6 +30,7 @@ import {
 import { publishConversationMessagesChanged } from "../runtime/sync/resource-sync-events.js";
 import { getLogger } from "../util/logger.js";
 import { normalizeTitle, stripMarkdown } from "../util/short-title.js";
+import { readChannelAllowlist } from "./channel-allowlist.js";
 import { isConversationSeedSane } from "./conversation-seed-composer.js";
 import { deriveTitle } from "./copy-composer.js";
 import {
@@ -459,12 +460,10 @@ const EVENT_CATEGORY_MAP: Record<string, FeedItemCategory> = {
 
 /**
  * Map a signal's source event to a feed category, or nothing when the event
- * has no entry. An unmapped event used to land in `system`, a bucket named
- * for our architecture rather than the user's world, and every deliberate
- * assistant notification (`user.send_notification`) ended up there. The
- * category is optional on the wire, so an event without a home simply
- * carries none: readers that filter by category skip it, and nothing has
- * to guess.
+ * has no entry. An unmapped event, such as a deliberate assistant
+ * notification (`assistant.share`), carries no category rather than a
+ * catch-all bucket named for our architecture: readers that filter by
+ * category skip it, and nothing has to guess.
  */
 function deriveCategory(
   signal: NotificationSignal,
@@ -558,7 +557,10 @@ function resolveHomeFeedMirror(
     signal.sourceChannel === "assistant_tool" ||
     signal.sourceEventName === "chat.assistant_reply"
   ) {
-    return { mirror: true, sourceConversationId, sourceScheduleJobId };
+    const allowlist = readChannelAllowlist(signal.contextPayload);
+    if (!allowlist || allowlist.includes("vellum")) {
+      return { mirror: true, sourceConversationId, sourceScheduleJobId };
+    }
   }
   if (signal.attentionHints.isAsyncBackground) {
     return { mirror: true, sourceConversationId, sourceScheduleJobId };

package/src/notifications/notification-utils.ts

@@ -71,6 +71,25 @@ export function readPayloadObject(
   return isPlainObject(value) ? value : undefined;
 }
 
+/**
+ * Safely read a string-array property from an unknown-typed payload object.
+ * Non-string entries are dropped. Returns `undefined` when the payload is
+ * not an object or the key does not hold an array.
+ */
+export function readPayloadStringArray(
+  payload: unknown,
+  key: string,
+): string[] | undefined {
+  if (!isPlainObject(payload)) {
+    return undefined;
+  }
+  const value = payload[key];
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  return value.filter((entry): entry is string => typeof entry === "string");
+}
+
 /** Truncate `text` to `maxLength`, appending "…" when exceeded. */
 export function truncate(text: string, maxLength: number): string {
   if (text.length <= maxLength) {

package/src/notifications/signal.ts

@@ -59,8 +59,9 @@ export function isNotificationSourceChannel(
 
 export const NOTIFICATION_SOURCE_EVENT_NAMES = [
   {
-    id: "user.send_notification",
-    description: "User-initiated notification via assistant tool",
+    id: "assistant.share",
+    description:
+      "Assistant chose to tell the user something (`assistant notifications send`)",
   },
   {
     id: "schedule.notify",
@@ -113,28 +114,12 @@ export const NOTIFICATION_SOURCE_EVENT_NAMES = [
     id: "watcher.notification",
     description: "Watcher detected a notable event",
   },
-  {
-    id: "watcher.escalation",
-    description: "Watcher event requiring immediate attention",
-  },
-  {
-    id: "tool_confirmation.required_action",
-    description: "Tool requires user confirmation before executing",
-  },
   { id: "activity.complete", description: "Background activity finished" },
   {
     id: "activity.failed",
     description:
       "Background job execution failed (model_provider, exception, or timeout)",
   },
-  {
-    id: "quick_chat.response_ready",
-    description: "Quick chat response ready for review",
-  },
-  {
-    id: "voice.response_ready",
-    description: "Voice response ready for playback",
-  },
   {
     id: "credential.health_alert",
     description:
@@ -251,7 +236,7 @@ export interface NotificationSignal<TEventName extends string = string> {
   createdAt: number; // epoch ms
   sourceChannel: NotificationSourceChannel; // see NOTIFICATION_SOURCE_CHANNELS registry
   sourceContextId: string;
-  sourceEventName: TEventName; // free-form: 'reminder_fired', 'guardian_question', etc.
+  sourceEventName: TEventName; // free-form; see NOTIFICATION_SOURCE_EVENT_NAMES
   contextPayload: NotificationContextPayload<TEventName>;
   attentionHints: AttentionHints;
   /**

package/src/notifications/types.ts

@@ -46,6 +46,21 @@ export type NotificationDeliveryResult = z.infer<
   typeof NotificationDeliveryResultSchema
 >;
 
+/**
+ * Strongest delivery proof the emit path can report. These are receipts,
+ * not intents: `client_os_posted` is reserved for a client ACK that the
+ * OS banner was posted, which this return path does not observe.
+ */
+export const NotificationReceiptClassSchema = z.enum([
+  "provider_accepted",
+  "gateway_accepted",
+  "client_os_posted",
+  "unknown",
+]);
+export type NotificationReceiptClass = z.infer<
+  typeof NotificationReceiptClassSchema
+>;
+
 // -- Channel adapter data shapes ----------------------------------------------
 
 export const DeliveryResultSchema = z.object({

package/src/oauth/connection-resolver.ts

@@ -467,12 +467,11 @@ async function fetchPlatformConnections(options: {
   }
 
   const body = (await response.json()) as unknown;
-  const connections = (
+  return (
     Array.isArray(body)
       ? body
       : ((body as Record<string, unknown>).results ?? [])
   ) as PlatformConnectionEntry[];
-  return connections;
 }
 
 /**

package/src/oauth/oauth-store.ts

@@ -678,8 +678,6 @@ export async function upsertApp(
     );
   }
 
-  const defaultCredPath = (appId: string) => oauthAppClientSecretPath(appId);
-
   // Verify the credential path points to an existing secret.
   if (clientSecretCredentialPath) {
     const existing = await getSecureKeyAsync(clientSecretCredentialPath);
@@ -739,7 +737,7 @@ export async function upsertApp(
 
   const now = Date.now();
   const id = uuid();
-  const credPath = clientSecretCredentialPath ?? defaultCredPath(id);
+  const credPath = clientSecretCredentialPath ?? oauthAppClientSecretPath(id);
 
   const row = {
     id,

package/src/oauth/provider-serializer.ts

@@ -19,6 +19,7 @@ export type SerializedProvider = ReturnType<typeof serializeProvider> &
   Record<string, unknown>;
 
 import { isChannelBotProvider } from "@vellumai/service-contracts/channels";
+import type { IntegrationCategory } from "@vellumai/service-contracts/integration-categories";
 
 import { PROVIDER_SEED_DATA } from "./seed-providers.js";
 
@@ -38,6 +39,11 @@ export interface SerializedProviderSummary {
   supports_managed_mode: boolean;
   managed_service_is_paid: boolean;
   feature_flag: string | null;
+  /**
+   * Where the integrations catalog files the provider. `null` for a row with
+   * no seed entry, such as a provider a user registered by hand.
+   */
+  category: IntegrationCategory | null;
   /**
    * Per-tenant providers only (Shopify): what a client must collect before
    * starting a managed connect, since the provider's OAuth endpoints live on
@@ -173,6 +179,7 @@ export function serializeProviderSummary(
     supports_managed_mode: !!row.managedServiceConfigKey,
     managed_service_is_paid: !!row.managedServiceIsPaid,
     feature_flag: row.featureFlag ?? null,
+    category: PROVIDER_SEED_DATA[row.provider]?.category ?? null,
     tenant_host: PROVIDER_SEED_DATA[row.provider]?.tenantHost ?? null,
     acts_as: isChannelBotProvider(row.provider) ? "assistant" : "user",
   };