@vellumai/assistant 0.10.1 → 0.10.2-dev.202606241651.2d2b40d

package/src/memory/v2/skill-store.ts

@@ -16,8 +16,11 @@
 //
 // Skill entries are kept in a small in-process cache so the render path can
 // fetch a `SkillEntry` synchronously by id without round-tripping to Qdrant.
-// The cache is replaced atomically at the end of a successful seed run; on
-// error the prior cache stays intact (skills are best-effort).
+// The cache is replaced atomically from the local catalog at the end of a seed
+// run — including when the dense embedding backend is unavailable, in which
+// case only the dense Qdrant write is deferred so the cache (and the v3 needle
+// lane it feeds) still reflects the current skills. An unexpected error in
+// another step leaves the prior cache intact (skills are best-effort).
 
 import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import { getConfig } from "../../config/loader.js";
@@ -228,26 +231,26 @@ async function runSeedV2SkillEntries(generation: number): Promise<void> {
       );
     }
 
-    // Embed all content strings in one batched call when there is anything to
-    // embed. Skipping the call when `seeds` is empty avoids throwing on an
-    // unavailable embedding backend in the all-disabled case, so pruning and
-    // cache replacement still run and clear stale state.
+    // Build the dense + sparse vectors for the Qdrant write. Sparse (BM25/TF)
+    // encoding is computed locally and needs no backend; only the dense vectors
+    // require `embedWithBackend`, which is unconfigured during the cold-start
+    // window before a managed-proxy embedding credential is provisioned.
+    //
+    // A dense-embed failure is non-fatal to the in-memory cache: the v3 needle
+    // finder lane and always-candidate skill pinning read skills from `entries`
+    // / the page index, NOT from Qdrant, so the cache is populated from the
+    // local catalog regardless of backend state and skills stay discoverable
+    // from first boot. Only the dense Qdrant upsert is skipped; the managed-
+    // credential reseed (`maybeReseedCapabilitiesAfterManagedCredential`) and
+    // the v3 maintain pass backfill the dense vectors once the backend recovers.
     const nextEntries = new Map<string, SkillEntry>();
     let denseVectors: number[][] = [];
+    let denseAvailable = false;
+    let denseError: unknown = null;
     let encodeSparse: (
       input: string,
     ) => ReturnType<typeof generateSparseEmbedding> = generateSparseEmbedding;
     if (seeds.length > 0) {
-      const embedded = await embedWithBackend(
-        config,
-        seeds.map((s) => s.content),
-      );
-      denseVectors = await Promise.all(
-        embedded.vectors.map((v) =>
-          applyCorrectionIfCalibrated(v, embedded.provider, embedded.model),
-        ),
-      );
-
       // Skills share the concept-page Qdrant collection, so the sparse vector
       // must use the same stemmed BM25 encoding the concept-page documents
       // carry — otherwise the stemmed BM25 query vectors used by callers (see
@@ -263,6 +266,24 @@ async function runSeedV2SkillEntries(generation: number): Promise<void> {
               b: config.memory.v2.bm25_b,
             })
           : generateSparseEmbedding(input);
+      try {
+        const embedded = await embedWithBackend(
+          config,
+          seeds.map((s) => s.content),
+        );
+        denseVectors = await Promise.all(
+          embedded.vectors.map((v) =>
+            applyCorrectionIfCalibrated(v, embedded.provider, embedded.model),
+          ),
+        );
+        denseAvailable = true;
+      } catch (err) {
+        denseError = err;
+        log.warn(
+          { err },
+          "Embedding backend unavailable — seeding skill cache without dense Qdrant vectors; the needle lane surfaces skills from the cache and the dense lane backfills when the backend recovers",
+        );
+      }
     }
 
     if (generation !== requestedSeedGeneration) {
@@ -274,7 +295,17 @@ async function runSeedV2SkillEntries(generation: number): Promise<void> {
       return;
     }
 
-    if (seeds.length > 0) {
+    // Populate the in-memory cache (and therefore the page index / needle lane)
+    // from the local catalog regardless of dense availability.
+    for (const seed of seeds) {
+      nextEntries.set(seed.id, seed);
+    }
+
+    // Write Qdrant points only when dense vectors were produced. In the
+    // degraded (backend-unavailable) path we skip Qdrant mutation entirely —
+    // both the upsert and the prune below — so we never write half-formed
+    // points or reconcile the collection against a set we did not persist.
+    if (seeds.length > 0 && denseAvailable) {
       const now = Date.now();
       await Promise.all(
         seeds.map((seed, i) =>
@@ -287,16 +318,15 @@ async function runSeedV2SkillEntries(generation: number): Promise<void> {
           }),
         ),
       );
-      for (const seed of seeds) {
-        nextEntries.set(seed.id, seed);
-      }
     }
 
-    // Prune stale skill slugs. When the catalog is unavailable (empty array
-    // from network failure or cold cache), we cannot enumerate which
-    // uninstalled catalog skills should exist, so skip pruning entirely to
-    // avoid aggressively removing previously-seeded catalog skill embeddings.
-    if (catalogAvailable) {
+    // Prune stale skill slugs. Skip when the catalog is unavailable (empty array
+    // from network failure or cold cache — we cannot enumerate which uninstalled
+    // catalog skills should exist) OR when dense vectors were not written this
+    // run (don't reconcile Qdrant against points we did not refresh). The
+    // `seeds.length === 0` branch still prunes under an available catalog so the
+    // all-disabled case clears stale rows.
+    if (catalogAvailable && (denseAvailable || seeds.length === 0)) {
       // Tag legacy skill points missing `payload.kind` before pruning so the
       // kind-scoped prune can see them. Once-per-process; the backfill is
       // idempotent (server-side `is_empty` filter), so a partial failure
@@ -321,19 +351,26 @@ async function runSeedV2SkillEntries(generation: number): Promise<void> {
         seeds.map((s) => s.id),
         { kind: SKILL_PAYLOAD_KIND },
       );
-    } else {
+    } else if (!catalogAvailable) {
       log.info(
         "Catalog unavailable — skipping skill pruning to preserve prior catalog embeddings",
       );
     }
 
-    // Atomically replace the cache only after every step above succeeds.
-    entries = nextEntries;
-    // Drop the page-index cache so the next router invocation observes the
-    // freshly seeded skill set (skill entries share the unified concept-page
+    // Atomically replace the cache from the freshly enumerated skills. The local
+    // resolution (`resolveSkillStates`) is authoritative, so a skill the config
+    // just disabled or removed drops out here even when the remote catalog is
+    // unavailable. Drop the page-index cache so the next router invocation
+    // observes the new skill set (skill entries share the unified concept-page
     // collection and surface in the same index).
+    entries = nextEntries;
     invalidatePageIndex();
-    lastSeedError = null;
+
+    // Surface a dense-embed failure to `throwOnError` callers (the managed-
+    // credential reseed and the operator reembed route) so the existing retry +
+    // maintain machinery backfills the dense lane. The in-memory cache is
+    // already updated above, so the needle lane is fixed regardless.
+    lastSeedError = denseError;
   } catch (err) {
     lastSeedError = err;
     log.warn({ err }, "Failed to seed v2 skill entries");

package/src/memory/watchdog-events-store.ts

@@ -0,0 +1,87 @@
+import { and, asc, eq, gt, or } from "drizzle-orm";
+import { v4 as uuid } from "uuid";
+
+import { getCachedShareAnalytics } from "../platform/consent-cache.js";
+import { getTelemetryDb } from "./db-connection.js";
+import { watchdogEvents } from "./schema.js";
+
+/**
+ * Input for one `watchdog` telemetry event. Metadata only — never conversation
+ * content. `value` and `detail` are optional; omitting both yields the minimal
+ * event (check_name only). `detail` is a JSON bag serialized to text on persist
+ * and forwarded verbatim on flush.
+ */
+export interface WatchdogEventRecord {
+  checkName: string;
+  /** Measured magnitude (block ms, idle ms, ...). Null when the check carries no scalar. */
+  value?: number | null;
+  /** Open JSON bag for extra fields (reason codes, secondary numbers, ...). */
+  detail?: Record<string, unknown> | null;
+}
+
+/** A persisted watchdog event row. */
+export interface WatchdogEvent {
+  id: string;
+  createdAt: number;
+  checkName: string;
+  value: number | null;
+  /** Raw `detail` JSON text from the row, or null. Parsed by the reporter on flush. */
+  detail: string | null;
+}
+
+/**
+ * Record a `watchdog` telemetry event for a watchdog check firing. No-ops when
+ * usage data collection is disabled (the event is dropped to honor the opt-out,
+ * matching the rest of telemetry) — so opt-out rows never exist and the
+ * reporter's standard 0 watermark default is safe.
+ */
+export function recordWatchdogEvent(record: WatchdogEventRecord): void {
+  if (!getCachedShareAnalytics()) return;
+  const db = getTelemetryDb();
+  if (!db) return;
+  db.insert(watchdogEvents)
+    .values({
+      id: uuid(),
+      createdAt: Date.now(),
+      checkName: record.checkName,
+      value: record.value ?? null,
+      detail: record.detail != null ? JSON.stringify(record.detail) : null,
+    })
+    .run();
+}
+
+/**
+ * Query watchdog events that haven't been reported to telemetry yet.
+ * Uses a compound cursor (createdAt + id) for reliable watermarking.
+ */
+export function queryUnreportedWatchdogEvents(
+  afterCreatedAt: number,
+  afterId: string | undefined,
+  limit: number,
+): WatchdogEvent[] {
+  const db = getTelemetryDb();
+  if (!db) return [];
+  return db
+    .select({
+      id: watchdogEvents.id,
+      createdAt: watchdogEvents.createdAt,
+      checkName: watchdogEvents.checkName,
+      value: watchdogEvents.value,
+      detail: watchdogEvents.detail,
+    })
+    .from(watchdogEvents)
+    .where(
+      afterId
+        ? or(
+            gt(watchdogEvents.createdAt, afterCreatedAt),
+            and(
+              eq(watchdogEvents.createdAt, afterCreatedAt),
+              gt(watchdogEvents.id, afterId),
+            ),
+          )
+        : gt(watchdogEvents.createdAt, afterCreatedAt),
+    )
+    .orderBy(asc(watchdogEvents.createdAt), asc(watchdogEvents.id))
+    .limit(limit)
+    .all();
+}

package/src/memory/worker-control.ts

@@ -0,0 +1,118 @@
+/**
+ * Shared control surface for the memory jobs worker *process* — the detached
+ * OS process whose entry point is `worker-process.ts`.
+ *
+ * Both the `assistant memory worker` CLI and the daemon lifecycle (when
+ * `memory.worker.enabled` is set) need to probe, spawn, and stop this process,
+ * so the PID-file bookkeeping lives here in one place.
+ */
+
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+
+import { getMemoryWorkerPidPath } from "../util/platform.js";
+
+export interface MemoryWorkerStatus {
+  status: "running" | "not_running";
+  pid?: number;
+}
+
+/**
+ * Inspect the PID file to determine whether the worker process is alive.
+ * A stale PID file (pointing at a dead process) is cleaned up and reported
+ * as not_running.
+ */
+export function probeMemoryWorker(): MemoryWorkerStatus {
+  const pidPath = getMemoryWorkerPidPath();
+  if (!existsSync(pidPath)) return { status: "not_running" };
+
+  const raw = readFileSync(pidPath, "utf-8").trim();
+  const pid = parseInt(raw, 10);
+  if (!Number.isFinite(pid) || pid <= 0) return { status: "not_running" };
+
+  try {
+    process.kill(pid, 0);
+    return { status: "running", pid };
+  } catch (err: unknown) {
+    if (
+      err &&
+      typeof err === "object" &&
+      "code" in err &&
+      err.code === "ESRCH"
+    ) {
+      // Stale PID file — clean it up.
+      try {
+        unlinkSync(pidPath);
+      } catch {
+        // best-effort
+      }
+      return { status: "not_running" };
+    }
+    throw err;
+  }
+}
+
+export class MemoryWorkerSpawnError extends Error {}
+
+/**
+ * Spawn the memory worker as a detached background process.
+ *
+ * If a worker is already running, returns its PID with `alreadyRunning: true`
+ * rather than spawning a second one. Throws {@link MemoryWorkerSpawnError} if
+ * the child is spawned but never writes its PID file (i.e. failed to start).
+ */
+export async function spawnMemoryWorkerProcess(): Promise<{
+  pid: number;
+  alreadyRunning: boolean;
+}> {
+  const current = probeMemoryWorker();
+  if (current.status === "running" && current.pid != null) {
+    return { pid: current.pid, alreadyRunning: true };
+  }
+
+  const pidPath = getMemoryWorkerPidPath();
+  const entry = new URL("./worker-process.ts", import.meta.url);
+
+  // Spawn detached so the worker survives the spawning process exiting.
+  const child = Bun.spawn({
+    cmd: ["bun", "run", entry.pathname],
+    stdio: ["ignore", "ignore", "ignore"],
+    detached: true,
+  });
+
+  // Unreference so the spawning process doesn't wait for the child.
+  child.unref();
+
+  // Wait briefly for the PID file to appear (the worker writes it on startup).
+  let pidWritten = false;
+  for (let i = 0; i < 10; i++) {
+    await Bun.sleep(100);
+    if (existsSync(pidPath)) {
+      pidWritten = true;
+      break;
+    }
+  }
+
+  if (!pidWritten) {
+    throw new MemoryWorkerSpawnError(
+      "Memory worker was spawned but PID file did not appear within 1s",
+    );
+  }
+
+  const pid = parseInt(readFileSync(pidPath, "utf-8").trim(), 10);
+  return { pid, alreadyRunning: false };
+}
+
+/**
+ * Send SIGTERM to the worker process if it is actually running.
+ *
+ * Returns the status observed before signalling, so callers can report
+ * whether anything was stopped. Only throws if `process.kill` itself fails
+ * (e.g. EPERM) — a not-running worker is a no-op.
+ */
+export function stopMemoryWorkerProcess(): MemoryWorkerStatus {
+  const current = probeMemoryWorker();
+  if (current.status === "running" && current.pid != null) {
+    process.kill(current.pid, "SIGTERM");
+  }
+  return current;
+}

package/src/memory/worker-process.ts

@@ -0,0 +1,72 @@
+/**
+ * Standalone entry point for the memory jobs worker as its own OS process.
+ *
+ * Spawned by `assistant memory worker start`. Loads config, starts the
+ * worker loop, writes a PID file, and stays alive until SIGTERM/SIGINT.
+ *
+ * The worker's internal `setTimeout` calls `.unref()`, which is correct
+ * inside the daemon (don't keep the daemon alive for the worker) but would
+ * cause this standalone process to exit immediately. A ref'd keep-alive
+ * interval prevents that.
+ */
+
+import { existsSync, unlinkSync, writeFileSync } from "node:fs";
+
+import { getConfig } from "../config/loader.js";
+import { getLogger } from "../util/logger.js";
+import { getMemoryWorkerPidPath } from "../util/platform.js";
+import { startInProcessMemoryJobsWorker } from "./jobs-worker.js";
+
+const log = getLogger("memory-worker-process");
+
+function cleanupPidFile(): void {
+  const pidPath = getMemoryWorkerPidPath();
+  try {
+    if (existsSync(pidPath)) unlinkSync(pidPath);
+  } catch {
+    // best-effort
+  }
+}
+
+async function main(): Promise<void> {
+  const config = getConfig();
+  const pidPath = getMemoryWorkerPidPath();
+
+  if (config.memory.enabled === false) {
+    log.info("Memory is disabled in config; worker process exiting");
+    process.exit(0);
+  }
+
+  // Write PID file so `status` and `stop` can find us.
+  writeFileSync(pidPath, String(process.pid), { flag: "w" });
+  log.info({ pid: process.pid, pidPath }, "Memory worker process started");
+
+  const worker = startInProcessMemoryJobsWorker();
+
+  // Keep-alive: the worker's setTimeout timers are unref'd, so without
+  // this interval the process would exit immediately.
+  const keepAlive = setInterval(() => {}, 60_000);
+
+  const shutdown = (signal: string) => {
+    log.info({ signal }, "Memory worker process shutting down");
+    worker.stop();
+    clearInterval(keepAlive);
+    cleanupPidFile();
+    process.exit(0);
+  };
+
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+
+  // Clean up if the process exits unexpectedly through any other path.
+  process.on("exit", () => {
+    worker.stop();
+    cleanupPidFile();
+  });
+}
+
+void main().catch((err) => {
+  log.error({ err }, "Memory worker process failed to start");
+  cleanupPidFile();
+  process.exit(1);
+});

package/src/notifications/__tests__/broadcaster.test.ts

@@ -27,14 +27,22 @@ mock.module("../copy-composer.js", () => ({
   composeFallbackCopy: () => composeFallbackReturn,
 }));
 
-mock.module("../destination-resolver.js", () => ({
-  resolveDestinations: (channels: string[]) => {
-    const map = new Map<string, ChannelDestination>();
-    for (const ch of channels) {
-      map.set(ch, { channel: ch as ChannelDestination["channel"] });
-    }
-    return map;
-  },
+// Stub only getGuardianDelivery; keep the real selectors so this mock is
+// harmless if it leaks into destination-resolver.test.ts under a shared run.
+const realGuardianReader = await import(
+  "../../contacts/guardian-delivery-reader.js"
+);
+mock.module("../../contacts/guardian-delivery-reader.js", () => ({
+  ...realGuardianReader,
+  getGuardianDelivery: async () => null,
+}));
+
+// Use the real destination-resolver (DB-free via the local-read stub below)
+// so this mock does not leak into destination-resolver.test.ts under a shared
+// bun-test invocation. With no guardian, the resolver still yields a vellum
+// destination, which is all these tests exercise.
+mock.module("../../contacts/contact-store.js", () => ({
+  findGuardianForChannel: () => null,
 }));
 
 mock.module("../conversation-pairing.js", () => ({

package/src/notifications/__tests__/connected-channels.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Tests for getConnectedChannels connectivity resolution.
+ *
+ * Connectivity must mirror destination-resolver's `resolveGuardian`:
+ * gateway-first, with a LOCAL contacts fallback on ANY per-channel no-match
+ * (gateway list null OR no active gateway entry for the channel). This keeps a
+ * channel from being marked connected when it can't be delivered (and
+ * vice-versa).
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { GuardianDelivery } from "@vellumai/gateway-client";
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, { get: () => () => {} }),
+  truncateForLog: (value: string) => value,
+}));
+
+let deliverableChannels: string[] = [];
+let gatewayGuardians: GuardianDelivery[] | null = null;
+let localChatId: string | null = null;
+
+const realConfig = await import("../../channels/config.js");
+
+mock.module("../../channels/config.js", () => ({
+  ...realConfig,
+  getDeliverableChannels: () => deliverableChannels,
+}));
+
+const realReader = await import("../../contacts/guardian-delivery-reader.js");
+
+mock.module("../../contacts/guardian-delivery-reader.js", () => ({
+  ...realReader,
+  getGuardianDelivery: async () => gatewayGuardians,
+}));
+
+const realContactStore = await import("../../contacts/contact-store.js");
+
+mock.module("../../contacts/contact-store.js", () => ({
+  ...realContactStore,
+  findGuardianForChannel: (_channelType: string) =>
+    localChatId === null
+      ? null
+      : { contact: { principalId: "p1" }, channel: { externalChatId: localChatId } },
+}));
+
+const { getConnectedChannels } = await import("../emit-signal.js");
+
+function gatewayBinding(channelType: string, externalChatId: string): GuardianDelivery {
+  return { channelType, contactId: "c1", address: "addr", externalChatId, status: "active" };
+}
+
+beforeEach(() => {
+  deliverableChannels = [];
+  gatewayGuardians = null;
+  localChatId = null;
+});
+
+describe("getConnectedChannels gateway-first-then-local connectivity", () => {
+  test("marks telegram connected from a gateway-only binding", async () => {
+    deliverableChannels = ["telegram"];
+    gatewayGuardians = [gatewayBinding("telegram", "123")];
+    localChatId = null;
+
+    expect(await getConnectedChannels()).toContain("telegram");
+  });
+
+  test("falls back to a local binding when the gateway is unreachable (null)", async () => {
+    deliverableChannels = ["telegram"];
+    gatewayGuardians = null;
+    localChatId = "456";
+
+    expect(await getConnectedChannels()).toContain("telegram");
+  });
+
+  test("marks telegram disconnected when neither source has a binding", async () => {
+    deliverableChannels = ["telegram"];
+    gatewayGuardians = null;
+    localChatId = null;
+
+    expect(await getConnectedChannels()).not.toContain("telegram");
+  });
+
+  test("falls back to local when the gateway responds without that channel", async () => {
+    // Gateway present but with no active telegram entry ⇒ per-channel no-match,
+    // so connectivity falls back to the local mirror (mirrors
+    // destination-resolver's per-channel fallback).
+    deliverableChannels = ["telegram"];
+    gatewayGuardians = [];
+    localChatId = "789";
+
+    expect(await getConnectedChannels()).toContain("telegram");
+  });
+
+  test("only marks slack connected for D-prefixed (DM) chat IDs", async () => {
+    deliverableChannels = ["slack"];
+    gatewayGuardians = [gatewayBinding("slack", "C-public")];
+    expect(await getConnectedChannels()).not.toContain("slack");
+
+    gatewayGuardians = [gatewayBinding("slack", "D-dm")];
+    expect(await getConnectedChannels()).toContain("slack");
+  });
+
+  test("always reports vellum and platform connected", async () => {
+    deliverableChannels = ["vellum", "platform"];
+    gatewayGuardians = null;
+
+    const connected = await getConnectedChannels();
+    expect(connected).toContain("vellum");
+    expect(connected).toContain("platform");
+  });
+});

package/src/notifications/__tests__/decision-engine.test.ts

@@ -34,19 +34,38 @@ mock.module("../../prompts/system-prompt.js", () => ({
   buildCoreIdentityContext: () => null,
 }));
 
+// Guardian binding (ACL) is resolved via the gateway pull; notes (INFO) are
+// joined locally by contactId. Tests drive both via mutable slots.
+let guardianDeliveryFixture: Array<{ contactId: string }> = [];
+let contactInfoFixture: Record<string, { notes: string | null } | null> = {};
+
+mock.module("../../contacts/guardian-delivery-reader.js", () => ({
+  getGuardianDelivery: async () => guardianDeliveryFixture,
+  anyGuardian: (list: Array<{ contactId: string }>) => list[0],
+}));
+
 mock.module("../../contacts/contact-store.js", () => ({
-  listGuardianChannels: () => null,
+  findContactInfoById: (contactId: string) =>
+    contactInfoFixture[contactId] ?? null,
 }));
 
-// Provider mock — if `getConfiguredProvider` is ever called by the
-// assistant_tool pass-through path, this throw makes the test fail
-// loudly instead of silently exercising the LLM path.
+// Provider mock. By default `sendMessage` throws so the assistant_tool
+// pass-through path (which must skip the LLM) fails loudly if it reaches the
+// provider. LLM-path tests override `providerSendMessage` to capture inputs.
+let providerSendMessage: (
+  messages: unknown[],
+  opts: { systemPrompt?: string },
+) => Promise<unknown> = () => {
+  throw new Error(
+    "provider.sendMessage should NOT be invoked for assistant_tool pass-through",
+  );
+};
+
 mock.module("../../providers/provider-send-message.js", () => ({
-  getConfiguredProvider: async () => {
-    throw new Error(
-      "getConfiguredProvider should NOT be invoked for assistant_tool pass-through",
-    );
-  },
+  getConfiguredProvider: async () => ({
+    sendMessage: (messages: unknown[], opts: { systemPrompt?: string }) =>
+      providerSendMessage(messages, opts),
+  }),
   createTimeout: () => ({
     signal: new AbortController().signal,
     cleanup: () => {},
@@ -281,3 +300,53 @@ describe("assistant_tool pass-through in notification decision engine", () => {
     expect(decision.renderedCopy.vellum?.body).toBe("fyi");
   });
 });
+
+describe("recipient notes injection (ACL from gateway, notes joined locally)", () => {
+  function makeLlmSignal(): NotificationSignal {
+    return {
+      signalId: "sig-llm-notes-1",
+      createdAt: Date.now(),
+      sourceChannel: "scheduler",
+      sourceContextId: "schedule-1",
+      sourceEventName: "schedule.notify",
+      contextPayload: {},
+      attentionHints: {
+        requiresAction: false,
+        urgency: "low",
+        isAsyncBackground: false,
+        visibleInSourceNow: false,
+      },
+    };
+  }
+
+  test("injects the guardian's local notes, resolved via the gateway contactId", async () => {
+    guardianDeliveryFixture = [{ contactId: "contact-42" }];
+    contactInfoFixture = { "contact-42": { notes: "Prefers terse updates." } };
+
+    let capturedSystemPrompt: string | undefined;
+    providerSendMessage = async (_messages, opts) => {
+      capturedSystemPrompt = opts.systemPrompt;
+      return {};
+    };
+
+    await evaluateSignal(makeLlmSignal(), ["vellum"] as NotificationChannel[]);
+
+    expect(capturedSystemPrompt).toContain("<recipient-context>");
+    expect(capturedSystemPrompt).toContain("Prefers terse updates.");
+  });
+
+  test("omits recipient context when no guardian is bound", async () => {
+    guardianDeliveryFixture = [];
+    contactInfoFixture = {};
+
+    let capturedSystemPrompt: string | undefined;
+    providerSendMessage = async (_messages, opts) => {
+      capturedSystemPrompt = opts.systemPrompt;
+      return {};
+    };
+
+    await evaluateSignal(makeLlmSignal(), ["vellum"] as NotificationChannel[]);
+
+    expect(capturedSystemPrompt).not.toContain("<recipient-context>");
+  });
+});