@vellumai/assistant 0.9.0 → 0.9.1-staging.1

package/src/memory/migrations/291-contact-channels-renormalize-addresses.ts

@@ -0,0 +1,62 @@
+import { getLogger } from "../../util/logger.js";
+import { type DrizzleDb, getSqliteFrom } from "../db-connection.js";
+
+const log = getLogger("migration-291");
+
+/**
+ * Restores original platform-provided casing into address from external_user_id
+ * for channels where the raw platform ID is the canonical identity (Slack,
+ * Telegram, etc.). Phone and WhatsApp channels are excluded because their
+ * canonical form (E.164) may differ from the raw external_user_id.
+ *
+ * Idempotent: rows where address already equals external_user_id are no-ops.
+ */
+export function migrateContactChannelsRenormalizeAddresses(
+  database: DrizzleDb,
+): void {
+  const raw = getSqliteFrom(database);
+
+  // Remove rows that would block normalization due to cross-column collisions.
+  raw.run(/*sql*/ `
+    DELETE FROM contact_channels
+    WHERE external_user_id IS NULL
+      AND id IN (
+        SELECT blocker.id
+        FROM contact_channels AS blocker
+        INNER JOIN contact_channels AS normalizer
+          ON normalizer.type = blocker.type
+          AND normalizer.external_user_id = blocker.address COLLATE NOCASE
+          AND normalizer.address != normalizer.external_user_id
+          AND normalizer.external_user_id IS NOT NULL
+          AND normalizer.id != blocker.id
+      )
+  `);
+
+  // Non-phone, non-email channels: restore original platform casing from
+  // external_user_id. Phone/WhatsApp are excluded because their canonical
+  // form (E.164 with '+' prefix) may differ from the raw external_user_id.
+  const nonEmailResult = raw.run(/*sql*/ `
+    UPDATE OR IGNORE contact_channels
+    SET address = external_user_id
+    WHERE external_user_id IS NOT NULL
+      AND address != external_user_id
+      AND type NOT IN ('email', 'phone', 'whatsapp')
+  `);
+
+  // Email channels: ensure address is lowercased (canonical per RFC 5321).
+  const emailResult = raw.run(/*sql*/ `
+    UPDATE OR IGNORE contact_channels
+    SET address = LOWER(external_user_id)
+    WHERE type = 'email'
+      AND external_user_id IS NOT NULL
+      AND address != LOWER(external_user_id)
+  `);
+
+  const totalChanges = nonEmailResult.changes + emailResult.changes;
+  if (totalChanges > 0) {
+    log.info(
+      { rowsUpdated: totalChanges },
+      "Re-normalized contact_channels addresses from external_user_id",
+    );
+  }
+}

package/src/memory/migrations/__tests__/291-contact-channels-renormalize-addresses.test.ts

@@ -0,0 +1,311 @@
+import { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+
+import { drizzle } from "drizzle-orm/bun-sqlite";
+
+import { getSqliteFrom } from "../../db-connection.js";
+import * as schema from "../../schema.js";
+import { migrateContactChannelsRenormalizeAddresses } from "../291-contact-channels-renormalize-addresses.js";
+
+interface ChannelRow {
+  id: string;
+  contact_id: string;
+  type: string;
+  address: string;
+  external_user_id: string | null;
+  status: string;
+}
+
+function createTestDb() {
+  const sqlite = new Database(":memory:");
+  sqlite.exec("PRAGMA journal_mode=WAL");
+  sqlite.exec("PRAGMA foreign_keys = ON");
+  return drizzle(sqlite, { schema });
+}
+
+function bootstrap(db: ReturnType<typeof createTestDb>): void {
+  const raw = getSqliteFrom(db);
+  raw.exec(/*sql*/ `
+    CREATE TABLE contacts (
+      id TEXT PRIMARY KEY,
+      display_name TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      role TEXT NOT NULL DEFAULT 'contact',
+      contact_type TEXT NOT NULL DEFAULT 'human'
+    )
+  `);
+  raw.exec(/*sql*/ `
+    CREATE TABLE contact_channels (
+      id TEXT PRIMARY KEY,
+      contact_id TEXT NOT NULL REFERENCES contacts(id) ON DELETE CASCADE,
+      type TEXT NOT NULL,
+      address TEXT NOT NULL,
+      is_primary INTEGER NOT NULL DEFAULT 0,
+      external_user_id TEXT,
+      external_chat_id TEXT,
+      status TEXT NOT NULL DEFAULT 'unverified',
+      policy TEXT NOT NULL DEFAULT 'allow',
+      interaction_count INTEGER NOT NULL DEFAULT 0,
+      updated_at INTEGER,
+      created_at INTEGER NOT NULL
+    )
+  `);
+  raw.exec(/*sql*/ `
+    CREATE UNIQUE INDEX idx_contact_channels_type_address
+      ON contact_channels(type, address)
+  `);
+}
+
+function insertContact(raw: Database, id: string): void {
+  const now = Date.now();
+  raw
+    .query(
+      `INSERT INTO contacts (id, display_name, created_at, updated_at) VALUES (?, ?, ?, ?)`,
+    )
+    .run(id, `Contact ${id}`, now, now);
+}
+
+function insertChannel(
+  raw: Database,
+  opts: {
+    id: string;
+    contactId: string;
+    type: string;
+    address: string;
+    externalUserId: string | null;
+    status: string;
+  },
+): void {
+  const now = Date.now();
+  raw
+    .query(
+      `INSERT INTO contact_channels (id, contact_id, type, address, external_user_id, status, updated_at, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .run(
+      opts.id,
+      opts.contactId,
+      opts.type,
+      opts.address,
+      opts.externalUserId,
+      opts.status,
+      now,
+      now,
+    );
+}
+
+describe("migration 291 — renormalize addresses", () => {
+  test("restores Slack address casing from external_user_id", () => {
+    const db = createTestDb();
+    bootstrap(db);
+    const raw = getSqliteFrom(db);
+
+    insertContact(raw, "c1");
+    insertChannel(raw, {
+      id: "ch1",
+      contactId: "c1",
+      type: "slack",
+      address: "u12345abc",
+      externalUserId: "U12345ABC",
+      status: "active",
+    });
+
+    migrateContactChannelsRenormalizeAddresses(db);
+
+    const rows = raw
+      .prepare("SELECT * FROM contact_channels")
+      .all() as ChannelRow[];
+    expect(rows).toHaveLength(1);
+    expect(rows[0].address).toBe("U12345ABC");
+  });
+
+  test("preserves lowercase email addresses (does not overwrite with mixed-case external_user_id)", () => {
+    const db = createTestDb();
+    bootstrap(db);
+    const raw = getSqliteFrom(db);
+
+    insertContact(raw, "c1");
+    insertChannel(raw, {
+      id: "ch1",
+      contactId: "c1",
+      type: "email",
+      address: "user@example.com",
+      // generic-examples:ignore-next-line — reason: testing mixed-case email normalization
+      externalUserId: "User@Example.com",
+      status: "active",
+    });
+
+    migrateContactChannelsRenormalizeAddresses(db);
+
+    const rows = raw
+      .prepare("SELECT * FROM contact_channels")
+      .all() as ChannelRow[];
+    expect(rows).toHaveLength(1);
+    expect(rows[0].address).toBe("user@example.com");
+  });
+
+  test("lowercases email address if it was stored incorrectly", () => {
+    const db = createTestDb();
+    bootstrap(db);
+    const raw = getSqliteFrom(db);
+
+    insertContact(raw, "c1");
+    insertChannel(raw, {
+      id: "ch1",
+      contactId: "c1",
+      type: "email",
+      // generic-examples:ignore-next-line — reason: testing mixed-case email stored incorrectly
+      address: "User@Example.com",
+      // generic-examples:ignore-next-line — reason: testing mixed-case email stored incorrectly
+      externalUserId: "User@Example.com",
+      status: "active",
+    });
+
+    migrateContactChannelsRenormalizeAddresses(db);
+
+    const rows = raw
+      .prepare("SELECT * FROM contact_channels")
+      .all() as ChannelRow[];
+    expect(rows).toHaveLength(1);
+    expect(rows[0].address).toBe("user@example.com");
+  });
+
+  test("removes cross-column blocker before normalization", () => {
+    const db = createTestDb();
+    bootstrap(db);
+    const raw = getSqliteFrom(db);
+
+    insertContact(raw, "c1");
+    insertContact(raw, "c2");
+    // Blocker: NULL external_user_id, address matches normalizer's external_user_id
+    insertChannel(raw, {
+      id: "blocker",
+      contactId: "c1",
+      type: "slack",
+      address: "u12345abc",
+      externalUserId: null,
+      status: "unverified",
+    });
+    // Normalizer: has external_user_id that will become its address
+    insertChannel(raw, {
+      id: "normalizer",
+      contactId: "c2",
+      type: "slack",
+      address: "old-address",
+      externalUserId: "U12345ABC",
+      status: "active",
+    });
+
+    migrateContactChannelsRenormalizeAddresses(db);
+
+    const rows = raw
+      .prepare("SELECT * FROM contact_channels ORDER BY id")
+      .all() as ChannelRow[];
+    expect(rows).toHaveLength(1);
+    expect(rows[0].id).toBe("normalizer");
+    expect(rows[0].address).toBe("U12345ABC");
+  });
+
+  test("idempotent — safe to run twice", () => {
+    const db = createTestDb();
+    bootstrap(db);
+    const raw = getSqliteFrom(db);
+
+    insertContact(raw, "c1");
+    insertChannel(raw, {
+      id: "ch1",
+      contactId: "c1",
+      type: "slack",
+      address: "u12345abc",
+      externalUserId: "U12345ABC",
+      status: "active",
+    });
+
+    migrateContactChannelsRenormalizeAddresses(db);
+    migrateContactChannelsRenormalizeAddresses(db);
+
+    const rows = raw
+      .prepare("SELECT * FROM contact_channels")
+      .all() as ChannelRow[];
+    expect(rows).toHaveLength(1);
+    expect(rows[0].address).toBe("U12345ABC");
+  });
+
+  test("does not overwrite canonical E.164 phone address with raw external_user_id", () => {
+    const db = createTestDb();
+    bootstrap(db);
+    const raw = getSqliteFrom(db);
+
+    insertContact(raw, "c1");
+    // Phone channel whose address was canonicalized to E.164 (+1 prefix)
+    // but external_user_id still holds the raw 10-digit number.
+    insertChannel(raw, {
+      id: "ch1",
+      contactId: "c1",
+      type: "phone",
+      // generic-examples:ignore-next-line — reason: testing E.164 canonicalization preservation
+      address: "+15550101234",
+      // generic-examples:ignore-next-line — reason: testing raw 10-digit phone before E.164 normalization
+      externalUserId: "5550101234",
+      status: "active",
+    });
+
+    migrateContactChannelsRenormalizeAddresses(db);
+
+    const rows = raw
+      .prepare("SELECT * FROM contact_channels")
+      .all() as ChannelRow[];
+    expect(rows).toHaveLength(1);
+    // generic-examples:ignore-next-line — reason: verifying E.164 address preserved
+    expect(rows[0].address).toBe("+15550101234");
+  });
+
+  test("does not overwrite canonical WhatsApp address with raw external_user_id", () => {
+    const db = createTestDb();
+    bootstrap(db);
+    const raw = getSqliteFrom(db);
+
+    insertContact(raw, "c1");
+    insertChannel(raw, {
+      id: "ch1",
+      contactId: "c1",
+      type: "whatsapp",
+      address: "+447911123456",
+      externalUserId: "447911123456",
+      status: "active",
+    });
+
+    migrateContactChannelsRenormalizeAddresses(db);
+
+    const rows = raw
+      .prepare("SELECT * FROM contact_channels")
+      .all() as ChannelRow[];
+    expect(rows).toHaveLength(1);
+    expect(rows[0].address).toBe("+447911123456");
+  });
+
+  test("no-op when address already matches external_user_id", () => {
+    const db = createTestDb();
+    bootstrap(db);
+    const raw = getSqliteFrom(db);
+
+    insertContact(raw, "c1");
+    insertChannel(raw, {
+      id: "ch1",
+      contactId: "c1",
+      type: "slack",
+      address: "U12345ABC",
+      externalUserId: "U12345ABC",
+      status: "active",
+    });
+
+    migrateContactChannelsRenormalizeAddresses(db);
+
+    const rows = raw
+      .prepare("SELECT * FROM contact_channels")
+      .all() as ChannelRow[];
+    expect(rows).toHaveLength(1);
+    expect(rows[0].address).toBe("U12345ABC");
+  });
+});

package/src/memory/migrations/__tests__/run-migrations.test.ts

@@ -0,0 +1,52 @@
+import { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+
+import { drizzle } from "drizzle-orm/bun-sqlite";
+
+import * as schema from "../../schema.js";
+import { type MigrationStep, runMigrationSteps } from "../run-migrations.js";
+
+function createTestDb() {
+  const sqlite = new Database(":memory:");
+  sqlite.exec("PRAGMA journal_mode=WAL");
+  sqlite.exec("PRAGMA foreign_keys = ON");
+  return drizzle(sqlite, { schema });
+}
+
+describe("runMigrationSteps — checkpointing", () => {
+  // Skipped: documents the post-checkpointing contract and fails against the
+  // current behavior, which re-runs every forward step on every boot. Promote
+  // to `test` when true checkpointing of initial migrations lands.
+  test.skip("does not re-execute a step that was already applied on a prior run", () => {
+    /**
+     * Booting an already-migrated database must not re-run forward migration
+     * steps. With true checkpointing each step's body executes at most once
+     * across boots; without it every step re-runs on every startup — the
+     * ~200-step re-probe that floors daemon startup at ~30s.
+     */
+
+    // GIVEN three dummy migration steps that count how often their body runs
+    const calls = { a: 0, b: 0, c: 0 };
+    const steps: MigrationStep[] = [
+      function dummyMigrationA() {
+        calls.a++;
+      },
+      function dummyMigrationB() {
+        calls.b++;
+      },
+      function dummyMigrationC() {
+        calls.c++;
+      },
+    ];
+
+    // AND a database that has already been migrated once
+    const db = createTestDb();
+    runMigrationSteps(db, steps);
+
+    // WHEN the same steps run again against the already-migrated database
+    runMigrationSteps(db, steps);
+
+    // THEN no step body executes a second time
+    expect(calls).toEqual({ a: 1, b: 1, c: 1 });
+  });
+});

package/src/memory/migrations/index.ts

@@ -282,6 +282,7 @@ export { migrateConversationOriginChannelIndex } from "./287-conversation-origin
 export { migrateBackfillOriginChannelFromBindings } from "./288-backfill-origin-channel-from-bindings.js";
 export { migrateContactChannelsUniqueExtUser } from "./289-contact-channels-unique-ext-user.js";
 export { migrateScheduleCapabilities } from "./290-schedule-capabilities.js";
+export { migrateContactChannelsRenormalizeAddresses } from "./291-contact-channels-renormalize-addresses.js";
 export {
   MIGRATION_REGISTRY,
   type MigrationRegistryEntry,

package/src/memory/migrations/run-migrations.ts

@@ -0,0 +1,41 @@
+import { getLogger } from "../../util/logger.js";
+import type { DrizzleDb } from "../db-connection.js";
+
+const log = getLogger("db-init");
+
+/** A single forward migration step, identified for logging by its `.name`. */
+export type MigrationStep = (database: DrizzleDb) => void;
+
+export interface MigrationRunResult {
+  /** Steps whose body threw. */
+  failed: string[];
+}
+
+/**
+ * Run the ordered list of forward migration steps against the database.
+ *
+ * Individual step failures are caught and logged so one broken migration does
+ * not prevent independent later ones from succeeding.
+ */
+export function runMigrationSteps(
+  database: DrizzleDb,
+  steps: MigrationStep[],
+): MigrationRunResult {
+  const failed: string[] = [];
+
+  for (const step of steps) {
+    try {
+      log.debug({ migration: step.name }, `Starting migration: ${step.name}`);
+      step(database);
+      log.debug({ migration: step.name }, `Migration succeeded: ${step.name}`);
+    } catch (err) {
+      failed.push(step.name);
+      log.error(
+        { err, migration: step.name },
+        `Migration failed: ${step.name}`,
+      );
+    }
+  }
+
+  return { failed };
+}

package/src/memory/migrations/validate-migration-state.ts

@@ -220,7 +220,7 @@ export function validateMigrationState(
   // registry entry — these are from a newer version of the daemon.
   //
   // The memory_checkpoints table is a general-purpose key-value store also
-  // used by non-migration subsystems (e.g., "identity:intro:text",
+  // used by non-migration subsystems (e.g., "empty_state:greeting:text",
   // "conversation_starters:item_count_at_last_gen"). Filter to only keys
   // that follow migration naming conventions before comparing against the
   // registry to avoid false-positive warnings.

package/src/memory/schema/contacts.ts

@@ -42,10 +42,6 @@ export const contactChannels = sqliteTable(
     createdAt: integer("created_at").notNull(),
   },
   (table) => [
-    index("idx_contact_channels_type_ext_user").on(
-      table.type,
-      table.externalUserId,
-    ),
     index("idx_contact_channels_type_ext_chat").on(
       table.type,
       table.externalChatId,

package/src/messaging/providers/slack/adapter.ts

@@ -246,7 +246,7 @@ async function resolveUserInfoUncached(
   try {
     const result = findContactChannel({
       channelType: "slack",
-      externalUserId: userId,
+      address: userId,
     });
     if (result) {
       contactDisplayName = result.contact.displayName;

package/src/notifications/adapters/shared.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared adapter utilities — functions used by multiple channel adapters.
+ */
+
+import { isConversationSeedSane } from "../conversation-seed-composer.js";
+import { nonEmpty } from "../notification-utils.js";
+import type { ChannelDeliveryPayload } from "../types.js";
+
+/**
+ * Resolve the primary message text for a notification delivery.
+ *
+ * Cascade: deliveryText → conversationSeedMessage → body → title → event name.
+ */
+export function resolveMessageText(payload: ChannelDeliveryPayload): string {
+  const deliveryText = nonEmpty(payload.copy.deliveryText);
+  if (deliveryText) return deliveryText;
+
+  if (isConversationSeedSane(payload.copy.conversationSeedMessage)) {
+    return payload.copy.conversationSeedMessage.trim();
+  }
+
+  const body = nonEmpty(payload.copy.body);
+  if (body) return body;
+
+  const title = nonEmpty(payload.copy.title);
+  if (title) return title;
+
+  return payload.sourceEventName.replace(/[._]/g, " ");
+}

package/src/notifications/adapters/slack.ts

@@ -20,14 +20,13 @@ import {
   buildAccessRequestWarnings,
   buildSlackMessagePermalink,
   isSlackDmConversation,
-  parseAccessRequestPayload,
   type ParsedAccessRequestPayload,
 } from "../access-request-copy.js";
-import { isConversationSeedSane } from "../conversation-seed-composer.js";
 import {
   nonEmpty,
   sanitizeIdentityField,
   sanitizeMessagePreview,
+  truncate,
 } from "../notification-utils.js";
 import type {
   ChannelAdapter,
@@ -38,36 +37,10 @@ import type {
   DeliveryResult,
   NotificationChannel,
 } from "../types.js";
+import { resolveMessageText } from "./shared.js";
 
 const log = getLogger("notif-adapter-slack");
 
-// ---------------------------------------------------------------------------
-// Text resolution
-// ---------------------------------------------------------------------------
-
-function resolveSlackMessageText(payload: ChannelDeliveryPayload): string {
-  const deliveryText = nonEmpty(payload.copy.deliveryText);
-  if (deliveryText) return deliveryText;
-
-  if (isConversationSeedSane(payload.copy.conversationSeedMessage)) {
-    return payload.copy.conversationSeedMessage.trim();
-  }
-
-  const body = nonEmpty(payload.copy.body);
-  if (body) return body;
-
-  const title = nonEmpty(payload.copy.title);
-  if (title) return title;
-
-  return payload.sourceEventName.replace(/[._]/g, " ");
-}
-
-/** Truncate to `maxLength`, appending "…" when exceeded. */
-function truncate(text: string, maxLength: number): string {
-  if (text.length <= maxLength) return text;
-  return text.slice(0, maxLength - 1) + "…";
-}
-
 // ---------------------------------------------------------------------------
 // Slack Card block builders for approval notifications
 // ---------------------------------------------------------------------------
@@ -193,7 +166,7 @@ function buildAccessRequestCardBlocks(
   payload: ChannelDeliveryPayload,
 ): unknown[] {
   const approval = payload.approvalContext!;
-  const p = parseAccessRequestPayload(payload.contextPayload!);
+  const p = payload.accessRequestContext!;
   const blocks: unknown[] = [];
 
   const subtitle = buildAccessRequestSubtitle(p);
@@ -314,7 +287,7 @@ function buildApprovalNotificationBlocks(
 ): unknown[] {
   if (
     payload.sourceEventName === "ingress.access_request" &&
-    payload.contextPayload != null
+    payload.accessRequestContext != null
   ) {
     return buildAccessRequestCardBlocks(payload);
   }
@@ -345,7 +318,7 @@ export class SlackAdapter implements ChannelAdapter {
       };
     }
 
-    const messageText = resolveSlackMessageText(payload);
+    const messageText = resolveMessageText(payload);
 
     try {
       const result = payload.approvalContext

package/src/notifications/adapters/telegram.ts

@@ -11,8 +11,6 @@
 import { sendTelegramReply } from "../../messaging/providers/telegram-bot/send.js";
 import { ConfigError } from "../../util/errors.js";
 import { getLogger } from "../../util/logger.js";
-import { isConversationSeedSane } from "../conversation-seed-composer.js";
-import { nonEmpty } from "../notification-utils.js";
 import type {
   ChannelAdapter,
   ChannelDeliveryPayload,
@@ -20,26 +18,10 @@ import type {
   DeliveryResult,
   NotificationChannel,
 } from "../types.js";
+import { resolveMessageText } from "./shared.js";
 
 const log = getLogger("notif-adapter-telegram");
 
-function resolveTelegramMessageText(payload: ChannelDeliveryPayload): string {
-  const deliveryText = nonEmpty(payload.copy.deliveryText);
-  if (deliveryText) return deliveryText;
-
-  if (isConversationSeedSane(payload.copy.conversationSeedMessage)) {
-    return payload.copy.conversationSeedMessage.trim();
-  }
-
-  const body = nonEmpty(payload.copy.body);
-  if (body) return body;
-
-  const title = nonEmpty(payload.copy.title);
-  if (title) return title;
-
-  return payload.sourceEventName.replace(/[._]/g, " ");
-}
-
 export class TelegramAdapter implements ChannelAdapter {
   readonly channel: NotificationChannel = "telegram";
 
@@ -59,7 +41,7 @@ export class TelegramAdapter implements ChannelAdapter {
       };
     }
 
-    const messageText = resolveTelegramMessageText(payload);
+    const messageText = resolveMessageText(payload);
     const approval = payload.approvalContext;
 
     try {