@vellumai/assistant 0.9.1-staging.1 → 0.10.0-staging.2

package/src/notifications/signal.ts

@@ -2,8 +2,13 @@
  * NotificationSignal -- the flexible input from producers.
  * Uses free-form event names and structured attention hints that let the
  * decision engine route contextually.
+ *
+ * All data shapes are defined as Zod schemas — types are derived via
+ * `z.infer` so runtime validation and compile-time types stay in sync.
  */
 
+import { z } from "zod";
+
 import type { ConversationCreateType } from "../memory/conversation-crud.js";
 import type { GuardianQuestionPayload } from "./guardian-question-mode.js";
 
@@ -14,7 +19,11 @@ export const NOTIFICATION_SOURCE_CHANNELS = [
   { id: "vellum", description: "Vellum native client (macOS/iOS)" },
   { id: "phone", description: "Phone call pipeline" },
   { id: "telegram", description: "Telegram channel" },
+  { id: "whatsapp", description: "WhatsApp channel" },
   { id: "slack", description: "Slack channel" },
+  { id: "email", description: "Email channel" },
+  { id: "platform", description: "Platform-managed channel" },
+  { id: "a2a", description: "Agent-to-agent protocol channel" },
   { id: "scheduler", description: "Scheduled task runner (reminders, cron)" },
   { id: "watcher", description: "File/event watcher subsystem" },
 ] as const;
@@ -22,6 +31,18 @@ export const NOTIFICATION_SOURCE_CHANNELS = [
 export type NotificationSourceChannel =
   (typeof NOTIFICATION_SOURCE_CHANNELS)[number]["id"];
 
+/** Typed tuple of all source channel IDs — usable with `z.enum()`. */
+export const NOTIFICATION_SOURCE_CHANNEL_IDS = NOTIFICATION_SOURCE_CHANNELS.map(
+  (c) => c.id,
+) as unknown as readonly [
+  NotificationSourceChannel,
+  ...NotificationSourceChannel[],
+];
+
+export const NotificationSourceChannelSchema = z.enum(
+  NOTIFICATION_SOURCE_CHANNEL_IDS,
+);
+
 export function isNotificationSourceChannel(
   value: unknown,
 ): value is NotificationSourceChannel {
@@ -114,15 +135,24 @@ export type NotificationSourceEventName =
 
 // ── Attention hints & routing ──────────────────────────────────────────
 
-export interface AttentionHints {
-  requiresAction: boolean;
-  urgency: "low" | "medium" | "high" | "critical";
-  deadlineAt?: number; // epoch ms
-  isAsyncBackground: boolean;
-  visibleInSourceNow: boolean;
-}
+export const UrgencySchema = z.enum(["low", "medium", "high", "critical"]);
+export type Urgency = z.infer<typeof UrgencySchema>;
 
-export type RoutingIntent = "single_channel" | "multi_channel" | "all_channels";
+export const AttentionHintsSchema = z.object({
+  requiresAction: z.boolean(),
+  urgency: UrgencySchema,
+  deadlineAt: z.number().optional(),
+  isAsyncBackground: z.boolean(),
+  visibleInSourceNow: z.boolean(),
+});
+export type AttentionHints = z.infer<typeof AttentionHintsSchema>;
+
+export const RoutingIntentSchema = z.enum([
+  "single_channel",
+  "multi_channel",
+  "all_channels",
+]);
+export type RoutingIntent = z.infer<typeof RoutingIntentSchema>;
 
 // ── Typed context payloads ──────────────────────────────────────────────
 
@@ -140,42 +170,48 @@ export type RoutingIntent = "single_channel" | "multi_channel" | "all_channels";
  * This is channel-agnostic by design — any channel's access request that
  * resolves to a non-source-channel guardian gets the same treatment.
  */
-export type GuardianResolutionSource =
-  | "source-channel-contact"
-  | "vellum-anchor"
-  | "none";
-
-export interface AccessRequestContextPayload {
-  requestId: string;
-  requestCode: string;
-  sourceChannel: string;
-  conversationExternalId: string;
-  actorExternalId: string;
-  actorDisplayName: string | null;
-  actorUsername: string | null;
-  senderIdentifier: string;
-  guardianBindingChannel: string | null;
-  guardianResolutionSource: GuardianResolutionSource;
-  previousMemberStatus: string | null;
-  /** Preview of the requester's original message (first ~200 chars). */
-  messagePreview: string | null;
-  /** Slack-specific: user is from an external workspace (Slack Connect). */
-  isStranger?: boolean;
-  /** Slack-specific: user is a guest / restricted account. */
-  isRestricted?: boolean;
-  /** Slack message timestamp (e.g. "1234567890.123456") for permalink construction. */
-  messageTs?: string;
-}
+export const GuardianResolutionSourceSchema = z.enum([
+  "source-channel-contact",
+  "vellum-anchor",
+  "none",
+]);
+export type GuardianResolutionSource = z.infer<
+  typeof GuardianResolutionSourceSchema
+>;
 
-export interface GuardianChannelActivationPayload {
-  verificationCode: string;
-  sourceChannel: string;
-  actorExternalId: string;
-  actorDisplayName: string | null;
-  actorUsername: string | null;
-  sessionId: string;
-  expiresAt: number;
-}
+export const AccessRequestContextPayloadSchema = z.object({
+  requestId: z.string(),
+  requestCode: z.string(),
+  sourceChannel: z.string(),
+  conversationExternalId: z.string(),
+  actorExternalId: z.string(),
+  actorDisplayName: z.string().nullable(),
+  actorUsername: z.string().nullable(),
+  senderIdentifier: z.string(),
+  guardianBindingChannel: z.string().nullable(),
+  guardianResolutionSource: GuardianResolutionSourceSchema,
+  previousMemberStatus: z.string().nullable(),
+  messagePreview: z.string().nullable(),
+  isStranger: z.boolean().optional(),
+  isRestricted: z.boolean().optional(),
+  messageTs: z.string().optional(),
+});
+export type AccessRequestContextPayload = z.infer<
+  typeof AccessRequestContextPayloadSchema
+>;
+
+export const GuardianChannelActivationPayloadSchema = z.object({
+  verificationCode: z.string(),
+  sourceChannel: z.string(),
+  actorExternalId: z.string(),
+  actorDisplayName: z.string().nullable(),
+  actorUsername: z.string().nullable(),
+  sessionId: z.string(),
+  expiresAt: z.number(),
+});
+export type GuardianChannelActivationPayload = z.infer<
+  typeof GuardianChannelActivationPayloadSchema
+>;
 
 export interface NotificationEventContextPayloadMap {
   "guardian.question": GuardianQuestionPayload;

package/src/notifications/types.ts

@@ -1,15 +1,19 @@
 /**
  * Core domain types for the unified notification system.
  *
- * Defines the channel-adapter interfaces that the broadcaster and adapters
- * depend on, plus the decision engine output contract.
+ * Data shapes are defined as Zod schemas — types derived via `z.infer`
+ * so runtime validation and compile-time types stay in sync.
+ *
+ * Behavioral interfaces (ChannelAdapter) remain as TypeScript interfaces.
  */
 
+import { ApprovalUIMetadataSchema } from "@vellumai/gateway-client";
+import { z } from "zod";
+
 import type { ChannelPolicies } from "../channels/config.js";
 import type { ChannelId } from "../channels/types.js";
-import type { ApprovalUIMetadata } from "../runtime/channel-approval-types.js";
-import type { ParsedAccessRequestPayload } from "./access-request-copy.js";
-import type { AttentionHints } from "./signal.js";
+import { AccessRequestPayloadSchema } from "./access-request-copy.js";
+import { UrgencySchema } from "./signal.js";
 
 /**
  * Derived from the channel policy registry: only channels whose
@@ -22,38 +26,39 @@ export type NotificationChannel = {
 }[keyof ChannelPolicies] &
   ChannelId;
 
-export type NotificationDeliveryStatus =
-  | "pending"
-  | "sent"
-  | "failed"
-  | "skipped";
-
-/** Result of attempting to deliver a notification to a single channel. */
-export interface NotificationDeliveryResult {
-  channel: NotificationChannel;
-  destination: string;
-  status: NotificationDeliveryStatus;
-  errorCode?: string;
-  errorMessage?: string;
-  sentAt?: number;
-  conversationId?: string;
-  messageId?: string;
-  conversationStrategy?: string;
-}
-
-// -- Channel adapter interfaces -----------------------------------------------
-
-/** Result returned by a channel adapter after attempting to send. */
-export interface DeliveryResult {
-  success: boolean;
-  error?: string;
-  /**
-   * Channel-native message identifier captured at send time (e.g. Slack `ts`).
-   * Persisted onto `notification_deliveries.messageId` so later edits can
-   * target the same message via `ChannelAdapter.update()`.
-   */
-  messageId?: string;
-}
+export const NotificationDeliveryStatusSchema = z.enum([
+  "pending",
+  "sent",
+  "failed",
+  "skipped",
+]);
+export type NotificationDeliveryStatus = z.infer<
+  typeof NotificationDeliveryStatusSchema
+>;
+
+export const NotificationDeliveryResultSchema = z.object({
+  channel: z.string(),
+  destination: z.string(),
+  status: NotificationDeliveryStatusSchema,
+  errorCode: z.string().optional(),
+  errorMessage: z.string().optional(),
+  sentAt: z.number().optional(),
+  conversationId: z.string().optional(),
+  messageId: z.string().optional(),
+  conversationStrategy: z.string().optional(),
+});
+export type NotificationDeliveryResult = z.infer<
+  typeof NotificationDeliveryResultSchema
+>;
+
+// -- Channel adapter data shapes ----------------------------------------------
+
+export const DeliveryResultSchema = z.object({
+  success: z.boolean(),
+  error: z.string().optional(),
+  messageId: z.string().optional(),
+});
+export type DeliveryResult = z.infer<typeof DeliveryResultSchema>;
 
 /** Resolved destination for a specific channel. */
 export interface ChannelDestination {
@@ -70,58 +75,44 @@ export interface ChannelDestination {
  * conversations keyed by (sourceChannel, externalChatId).
  */
 export interface DestinationBindingContext {
-  /** The channel this binding belongs to (e.g. "telegram", "slack"). */
   sourceChannel: NotificationChannel;
-  /** The channel-specific chat/conversation identifier (e.g. Telegram chat ID, phone number). */
   externalChatId: string;
-  /** Optional external user identifier within the chat. */
   externalUserId?: string;
 }
 
-/**
- * Delivery payload assembled from the decision engine's rendered copy
- * plus contextual fields the adapters need for formatting and routing.
- */
-export interface ChannelDeliveryPayload {
-  /** Delivery audit record ID — passed through to the client for ack correlation. */
-  deliveryId?: string;
-  sourceEventName: string;
-  copy: RenderedChannelCopy;
-  deepLinkTarget?: Record<string, unknown>;
-  /** Original signal context payload — available for channel-specific structured rendering. */
-  contextPayload?: Record<string, unknown>;
-  /**
-   * Forwarded from the originating signal so adapters can make
-   * urgency-aware decisions (e.g. the vellum adapter suppresses the OS
-   * banner for non-urgent intents while still emitting the conversation
-   * pairing side effects).
-   */
-  urgency: AttentionHints["urgency"];
-  /**
-   * Structured approval context for notifications that require guardian
-   * action buttons (approve/reject). Built centrally by the broadcaster
-   * so adapters can render channel-native approval UI without re-parsing
-   * `contextPayload`.
-   */
-  approvalContext?: ApprovalUIMetadata;
-  /**
-   * Pre-parsed access request context for `ingress.access_request` signals.
-   * Built centrally by the broadcaster so adapters can render structured
-   * access-request cards without re-parsing `contextPayload`.
-   */
-  accessRequestContext?: ParsedAccessRequestPayload;
-}
+// -- Rendered copy & delivery payload -----------------------------------------
+
+export const RenderedChannelCopySchema = z.object({
+  title: z.string(),
+  body: z.string(),
+  deliveryText: z.string().optional(),
+  conversationTitle: z.string().optional(),
+  conversationSeedMessage: z.string().optional(),
+  seedContentBlocks: z.array(z.unknown()).optional(),
+});
+export type RenderedChannelCopy = z.infer<typeof RenderedChannelCopySchema>;
+
+export const ChannelDeliveryPayloadSchema = z.object({
+  deliveryId: z.string().optional(),
+  sourceEventName: z.string(),
+  copy: RenderedChannelCopySchema,
+  deepLinkTarget: z.record(z.string(), z.unknown()).optional(),
+  contextPayload: z.record(z.string(), z.unknown()).optional(),
+  urgency: UrgencySchema,
+  approvalContext: ApprovalUIMetadataSchema.optional(),
+  accessRequestContext: AccessRequestPayloadSchema.optional(),
+});
+export type ChannelDeliveryPayload = z.infer<
+  typeof ChannelDeliveryPayloadSchema
+>;
 
-/**
- * Patch supplied when an already-delivered notification is edited.
- * Adapters only need to act on `title` and `body` — feed-only fields
- * like `urgency` and `status` are handled by the home-feed patch.
- */
 export interface ChannelUpdatePayload {
   title?: string;
   body?: string;
 }
 
+// -- Channel adapter interface ------------------------------------------------
+
 /** Interface that each channel adapter must implement. */
 export interface ChannelAdapter {
   channel: NotificationChannel;
@@ -129,77 +120,57 @@ export interface ChannelAdapter {
     payload: ChannelDeliveryPayload,
     destination: ChannelDestination,
   ): Promise<DeliveryResult>;
-  /**
-   * Optional: edit a previously-sent message in place. Channels that
-   * cannot edit (push, email, SMS) omit this and the router treats
-   * them as `"unsupported"`. Adapters that implement it use
-   * `delivery.messageId` (captured at send time) as the channel-native
-   * handle for the in-place update.
-   */
   update?(
     delivery: ChannelUpdateContext,
     patch: ChannelUpdatePayload,
   ): Promise<DeliveryResult>;
 }
 
-/** Per-delivery state an adapter needs to update a previously-sent message. */
 export interface ChannelUpdateContext {
-  /** notification_deliveries.id */
   deliveryId: string;
-  /** Channel-native destination (e.g. Slack chat id). */
   destination: string;
-  /** Channel-native message identifier captured at send time. */
   messageId: string | null;
 }
 
-// -- Decision engine output ---------------------------------------------------
-
-/** Rendered notification copy for a single channel. */
-export interface RenderedChannelCopy {
-  title: string;
-  body: string;
-  /** Channel-native delivery text (e.g. Telegram chat message body). */
-  deliveryText?: string;
-  conversationTitle?: string;
-  conversationSeedMessage?: string;
-  /**
-   * Structured content blocks for the seed message. When present,
-   * conversation pairing stores `JSON.stringify(seedContentBlocks)` as the
-   * message content instead of the plain-text seed, enabling Surface
-   * rendering in the web/macOS/iOS apps.
-   *
-   * Typically includes a `ui_surface` block (rendered as an interactive
-   * card) followed by a `text` block (plain-text fallback for search,
-   * backward-compatible clients, and CLI display).
-   */
-  seedContentBlocks?: unknown[];
-}
-
 // -- Conversation action types ------------------------------------------------
 
-/** Start a new conversation for the notification delivery. */
-export interface ConversationActionStartNew {
-  action: "start_new";
-}
+export const ConversationActionSchema = z.discriminatedUnion("action", [
+  z.object({ action: z.literal("start_new") }),
+  z.object({
+    action: z.literal("reuse_existing"),
+    conversationId: z.string(),
+  }),
+]);
+export type ConversationAction = z.infer<typeof ConversationActionSchema>;
 
-/** Reuse an existing conversation identified by conversationId. */
-export interface ConversationActionReuseExisting {
-  action: "reuse_existing";
-  conversationId: string;
-}
+// -- Decision engine output ---------------------------------------------------
 
-/** Per-channel conversation action — either start a new conversation or reuse an existing one. */
-export type ConversationAction =
-  | ConversationActionStartNew
-  | ConversationActionReuseExisting;
+export const NotificationDecisionSchema = z.object({
+  shouldNotify: z.boolean(),
+  selectedChannels: z.array(z.string()),
+  reasoningSummary: z.string(),
+  renderedCopy: z.record(z.string(), RenderedChannelCopySchema),
+  conversationActions: z
+    .record(z.string(), ConversationActionSchema)
+    .optional(),
+  deepLinkTarget: z.record(z.string(), z.unknown()).optional(),
+  dedupeKey: z.string(),
+  confidence: z.number(),
+  fallbackUsed: z.boolean(),
+  persistedDecisionId: z.string().optional(),
+});
 
-/** Output produced by the notification decision engine for a given signal. */
+/**
+ * Decision engine output. `selectedChannels` and `renderedCopy` are keyed
+ * by `NotificationChannel` — narrower than the Zod schema's `string` since
+ * `NotificationChannel` is a computed type derived from the channel config
+ * registry and cannot be expressed as a Zod enum.
+ */
 export interface NotificationDecision {
   shouldNotify: boolean;
   selectedChannels: NotificationChannel[];
   reasoningSummary: string;
   renderedCopy: Partial<Record<NotificationChannel, RenderedChannelCopy>>;
-  /** Per-channel conversation actions decided by the model. Absent channels default to start_new. */
   conversationActions?: Partial<
     Record<NotificationChannel, ConversationAction>
   >;
@@ -207,6 +178,5 @@ export interface NotificationDecision {
   dedupeKey: string;
   confidence: number;
   fallbackUsed: boolean;
-  /** UUID of the persisted decision row (set after persistence in the decision engine). */
   persistedDecisionId?: string;
 }

package/src/permissions/checker.test.ts

@@ -125,6 +125,16 @@ mock.module("../ipc/gateway-client.js", () => ({
 
 // ── Import the module under test AFTER mocks are set up ──────────────────────
 
+import {
+  mkdtempSync,
+  rmSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
 import {
   check,
   classifyRisk,
@@ -231,6 +241,47 @@ describe("Permission Checker (gateway IPC)", () => {
       expect(result2.reason).toBe("Cached test");
     });
 
+    test("file-tool cache misses when a symlink target is retargeted", async () => {
+      // File risk depends on filesystem state: the cache key folds in the
+      // symlink-resolved target, so the same raw input must NOT return a stale
+      // cached result after the symlink is pointed somewhere new.
+      const dir = mkdtempSync(join(tmpdir(), "risk-cache-symlink-"));
+      try {
+        const benign = join(dir, "benign.txt");
+        const other = join(dir, "other.txt");
+        writeFileSync(benign, "ok");
+        writeFileSync(other, "ok");
+        const link = join(dir, "link.txt");
+        symlinkSync(benign, link);
+
+        mockIpcClassifyRiskResult = {
+          risk: "low",
+          reason: "benign",
+          matchType: "registry",
+          scopeOptions: [],
+        };
+        const first = await classifyRisk("file_read", { path: link });
+        expect(first.level).toBe(RiskLevel.Low);
+
+        // Retarget the symlink to a different real file; raw input unchanged.
+        unlinkSync(link);
+        symlinkSync(other, link);
+
+        mockIpcClassifyRiskResult = {
+          risk: "high",
+          reason: "now sensitive",
+          matchType: "registry",
+          scopeOptions: [],
+        };
+        const second = await classifyRisk("file_read", { path: link });
+        // Cache must have missed and re-classified against the new target.
+        expect(second.level).toBe(RiskLevel.High);
+        expect(second.reason).toBe("now sensitive");
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+
     test("preserves commandCandidates from gateway response", async () => {
       mockIpcClassifyRiskResult = {
         risk: "low",