@vellumai/assistant 0.8.0 → 0.8.1

package/src/runtime/__tests__/background-job-runner.test.ts

@@ -0,0 +1,357 @@
+/**
+ * Tests for `runBackgroundJob()`.
+ *
+ * Strategy: stub `bootstrapConversation`, `processMessage`, and
+ * `emitNotificationSignal` via `mock.module()` and inspect the recorded
+ * calls. We do NOT exercise the real conversation runtime here — the unit
+ * under test is the wrapper's contract:
+ *  - bootstrap is called once
+ *  - processMessage is awaited (or raced against a timeout)
+ *  - failure paths emit `activity.failed` (unless suppressed)
+ *  - the result is always a structured value, never a thrown error
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { TrustContext } from "../../daemon/trust-context.js";
+
+// ── Module mocks ─────────────────────────────────────────────────────
+
+let bootstrapCalls = 0;
+let bootstrapLastArgs: Record<string, unknown> | null = null;
+const STUB_CONVERSATION_ID = "conv-test-1";
+
+mock.module("../../memory/conversation-bootstrap.js", () => ({
+  bootstrapConversation: (opts: Record<string, unknown>) => {
+    bootstrapCalls += 1;
+    bootstrapLastArgs = opts;
+    return { id: STUB_CONVERSATION_ID };
+  },
+}));
+
+const addMessageCalls: Array<{
+  conversationId: string;
+  role: string;
+  content: string;
+}> = [];
+
+mock.module("../../memory/conversation-crud.js", () => ({
+  addMessage: async (conversationId: string, role: string, content: string) => {
+    addMessageCalls.push({ conversationId, role, content });
+    return { id: `msg-${addMessageCalls.length}` };
+  },
+}));
+
+let processMessageImpl: (
+  conversationId: string,
+  content: string,
+  attachmentIds: string[] | undefined,
+  options: Record<string, unknown> | undefined,
+) => Promise<{ messageId: string }> = async () => ({ messageId: "msg-1" });
+const processMessageCalls: Array<{
+  conversationId: string;
+  content: string;
+  options: Record<string, unknown> | undefined;
+}> = [];
+
+mock.module("../../daemon/process-message.js", () => ({
+  processMessage: async (
+    conversationId: string,
+    content: string,
+    attachmentIds: string[] | undefined,
+    options: Record<string, unknown> | undefined,
+  ) => {
+    processMessageCalls.push({ conversationId, content, options });
+    return processMessageImpl(conversationId, content, attachmentIds, options);
+  },
+}));
+
+const emitCalls: Array<Record<string, unknown>> = [];
+let emitImpl: (
+  params: Record<string, unknown>,
+) => Promise<unknown> = async () => ({
+  signalId: "sig-1",
+  deduplicated: false,
+  dispatched: true,
+  reason: "ok",
+  deliveryResults: [],
+});
+
+mock.module("../../notifications/emit-signal.js", () => ({
+  emitNotificationSignal: (params: Record<string, unknown>) => {
+    emitCalls.push(params);
+    return emitImpl(params);
+  },
+}));
+
+// Stub the pre-first-message gate. Default OPEN — every pre-existing
+// test assumes a fully-onboarded daemon. The dedicated "gate closed"
+// test flips this to false.
+let preFirstMessageGateOpen = true;
+mock.module("../pre-first-message-gate.js", () => ({
+  hasReceivedUserMessage: () => preFirstMessageGateOpen,
+}));
+
+// Import after mocks are in place.
+const { runBackgroundJob } = await import("../background-job-runner.js");
+
+// ── Shared fixtures ──────────────────────────────────────────────────
+
+const TRUST_CONTEXT: TrustContext = {
+  sourceChannel: "vellum",
+  trustClass: "guardian",
+};
+
+function baseOpts(overrides: Record<string, unknown> = {}) {
+  return {
+    jobName: "test-job",
+    source: "test-source",
+    prompt: "do the test",
+    trustContext: TRUST_CONTEXT,
+    callSite: "heartbeatAgent" as const,
+    timeoutMs: 5_000,
+    origin: "heartbeat" as const,
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  bootstrapCalls = 0;
+  bootstrapLastArgs = null;
+  processMessageCalls.length = 0;
+  emitCalls.length = 0;
+  addMessageCalls.length = 0;
+  preFirstMessageGateOpen = true;
+  processMessageImpl = async () => ({ messageId: "msg-1" });
+  emitImpl = async () => ({
+    signalId: "sig-1",
+    deduplicated: false,
+    dispatched: true,
+    reason: "ok",
+    deliveryResults: [],
+  });
+});
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe("runBackgroundJob", () => {
+  test("success path: returns ok=true and emits no notification", async () => {
+    processMessageImpl = async () => ({ messageId: "msg-success" });
+
+    const result = await runBackgroundJob(baseOpts());
+
+    expect(result.ok).toBe(true);
+    expect(result.conversationId).toBe(STUB_CONVERSATION_ID);
+    expect(result.error).toBeUndefined();
+    expect(result.errorKind).toBeUndefined();
+    expect(bootstrapCalls).toBe(1);
+    expect(bootstrapLastArgs).toMatchObject({
+      conversationType: "background",
+      source: "test-source",
+      origin: "heartbeat",
+      systemHint: "do the test",
+      groupId: "system:background",
+    });
+    expect(processMessageCalls).toHaveLength(1);
+    expect(processMessageCalls[0].options).toMatchObject({
+      trustContext: TRUST_CONTEXT,
+      callSite: "heartbeatAgent",
+    });
+    expect(emitCalls).toHaveLength(0);
+  });
+
+  test("generic exception: returns ok=false with errorKind=exception and emits activity.failed with dedupeKey", async () => {
+    processMessageImpl = async () => {
+      throw new Error("boom");
+    };
+
+    const result = await runBackgroundJob(baseOpts());
+
+    expect(result.ok).toBe(false);
+    expect(result.errorKind).toBe("exception");
+    expect(result.error).toBeInstanceOf(Error);
+    expect(result.error?.message).toBe("boom");
+    expect(result.conversationId).toBe(STUB_CONVERSATION_ID);
+
+    expect(emitCalls).toHaveLength(1);
+    const emitted = emitCalls[0];
+    expect(emitted.sourceEventName).toBe("activity.failed");
+    expect(emitted.sourceChannel).toBe("assistant_tool");
+    expect(emitted.sourceContextId).toBe(STUB_CONVERSATION_ID);
+    expect(emitted.contextPayload).toMatchObject({
+      jobName: "test-job",
+      errorMessage: "boom",
+      errorKind: "exception",
+    });
+    expect(emitted.attentionHints).toMatchObject({
+      requiresAction: false,
+      urgency: "medium",
+      isAsyncBackground: true,
+      visibleInSourceNow: false,
+    });
+    // Dedupe key collapses repeated failures of the same job per UTC day.
+    expect(typeof emitted.dedupeKey).toBe("string");
+    expect(emitted.dedupeKey as string).toMatch(
+      /^activity-failed:test-job:\d{4}-\d{2}-\d{2}$/,
+    );
+  });
+
+  test("timeout: returns ok=false with errorKind=timeout and emits activity.failed", async () => {
+    // Never resolve — force timeout to win the race.
+    processMessageImpl = () => new Promise(() => {});
+
+    const result = await runBackgroundJob(baseOpts({ timeoutMs: 50 }));
+
+    expect(result.ok).toBe(false);
+    expect(result.errorKind).toBe("timeout");
+    expect(result.error?.message).toContain("timed out after 50ms");
+    expect(emitCalls).toHaveLength(1);
+    expect(emitCalls[0].sourceEventName).toBe("activity.failed");
+    expect(
+      (emitCalls[0].contextPayload as { errorKind: string }).errorKind,
+    ).toBe("timeout");
+  });
+
+  test("suppressFailureNotifications: failure returns ok=false but emits nothing", async () => {
+    processMessageImpl = async () => {
+      throw new Error("suppressed");
+    };
+
+    const result = await runBackgroundJob(
+      baseOpts({ suppressFailureNotifications: true }),
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.errorKind).toBe("exception");
+    expect(result.error?.message).toBe("suppressed");
+    expect(emitCalls).toHaveLength(0);
+  });
+
+  test("onConversationCreated fires synchronously after bootstrap, BEFORE processMessage", async () => {
+    let processMessageStarted = false;
+    let callbackFiredBeforeProcessMessage = false;
+
+    processMessageImpl = async () => {
+      processMessageStarted = true;
+      // Delay completion so we can observe the ordering — even with the
+      // delay, the callback should already have fired.
+      await new Promise<void>((resolve) => setTimeout(resolve, 10));
+      return { messageId: "msg-after" };
+    };
+
+    const seenConversationIds: string[] = [];
+    const onConversationCreated = (conversationId: string) => {
+      seenConversationIds.push(conversationId);
+      callbackFiredBeforeProcessMessage = !processMessageStarted;
+    };
+
+    const result = await runBackgroundJob(baseOpts({ onConversationCreated }));
+
+    expect(result.ok).toBe(true);
+    expect(seenConversationIds).toEqual([STUB_CONVERSATION_ID]);
+    expect(callbackFiredBeforeProcessMessage).toBe(true);
+  });
+
+  test("onConversationCreated callback throws are swallowed and the job still runs", async () => {
+    const result = await runBackgroundJob(
+      baseOpts({
+        onConversationCreated: () => {
+          throw new Error("callback boom");
+        },
+      }),
+    );
+
+    expect(result.ok).toBe(true);
+    expect(processMessageCalls).toHaveLength(1);
+  });
+
+  test("conversationType=scheduled and scheduleJobId are propagated to bootstrapConversation", async () => {
+    await runBackgroundJob(
+      baseOpts({
+        conversationType: "scheduled",
+        scheduleJobId: "job-abc",
+      }),
+    );
+
+    expect(bootstrapLastArgs).toMatchObject({
+      conversationType: "scheduled",
+      scheduleJobId: "job-abc",
+    });
+  });
+
+  test("default conversationType is 'background' when not specified", async () => {
+    await runBackgroundJob(baseOpts());
+    expect(bootstrapLastArgs).toMatchObject({ conversationType: "background" });
+    // No scheduleJobId by default.
+    expect(bootstrapLastArgs).not.toHaveProperty("scheduleJobId");
+  });
+
+  test("assistantSandwich seeds three messages in user/assistant/user order, with sandwich written before processMessage runs", async () => {
+    let addMessageCountAtProcessMessageStart = -1;
+    processMessageImpl = async () => {
+      addMessageCountAtProcessMessageStart = addMessageCalls.length;
+      return { messageId: "msg-final" };
+    };
+
+    await runBackgroundJob(
+      baseOpts({
+        prompt: "",
+        assistantSandwich: {
+          preamble: "TRUSTED_PRE",
+          content: "UNTRUSTED_PAYLOAD",
+          postamble: "TRUSTED_POST",
+        },
+      }),
+    );
+
+    // All three sandwich addMessage calls happened.
+    expect(addMessageCalls).toHaveLength(3);
+    expect(addMessageCalls[0]).toMatchObject({
+      conversationId: STUB_CONVERSATION_ID,
+      role: "user",
+      content: "TRUSTED_PRE",
+    });
+    expect(addMessageCalls[1]).toMatchObject({
+      conversationId: STUB_CONVERSATION_ID,
+      role: "assistant",
+      content: "UNTRUSTED_PAYLOAD",
+    });
+    expect(addMessageCalls[2]).toMatchObject({
+      conversationId: STUB_CONVERSATION_ID,
+      role: "user",
+      content: "TRUSTED_POST",
+    });
+    expect(processMessageCalls).toHaveLength(1);
+    expect(processMessageCalls[0].content).toBe("");
+    // processMessage observed all 3 sandwich messages already in place.
+    expect(addMessageCountAtProcessMessageStart).toBe(3);
+  });
+
+  describe("pre-first-message gate", () => {
+    test("gate closed: no bootstrap, no processMessage, no notification — result reports skipReason", async () => {
+      preFirstMessageGateOpen = false;
+
+      const result = await runBackgroundJob(baseOpts());
+
+      expect(result.ok).toBe(true);
+      expect(result.skipReason).toBe("pre_first_user_message");
+      expect(result.conversationId).toBe("");
+      expect(bootstrapCalls).toBe(0);
+      expect(processMessageCalls).toHaveLength(0);
+      expect(emitCalls).toHaveLength(0);
+    });
+
+    test("gate closed but allowPreFirstUserMessage=true: runs normally", async () => {
+      preFirstMessageGateOpen = false;
+
+      const result = await runBackgroundJob(
+        baseOpts({ allowPreFirstUserMessage: true }),
+      );
+
+      expect(result.ok).toBe(true);
+      expect(result.skipReason).toBeUndefined();
+      expect(bootstrapCalls).toBe(1);
+      expect(processMessageCalls).toHaveLength(1);
+    });
+  });
+});

package/src/runtime/__tests__/pre-first-message-gate.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Tests for `hasReceivedUserMessage()` — the warm-pool background-job gate.
+ *
+ * Strategy: stub `rawGet` so we can simulate three states:
+ *   1. No user message in standard conversations → gate closed.
+ *   2. A user message exists → gate open, subsequent calls cached.
+ *   3. `rawGet` throws → gate stays closed (fail-conservative).
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+let rawGetImpl: () => unknown = () => null;
+let rawGetCalls = 0;
+
+mock.module("../../memory/raw-query.js", () => ({
+  rawGet: () => {
+    rawGetCalls += 1;
+    return rawGetImpl();
+  },
+}));
+
+// Import after mocks are wired so the module captures the mocked rawGet.
+const { hasReceivedUserMessage, _resetPreFirstMessageGateCacheForTests } =
+  await import("../pre-first-message-gate.js");
+
+beforeEach(() => {
+  _resetPreFirstMessageGateCacheForTests();
+  rawGetCalls = 0;
+  rawGetImpl = () => null;
+});
+
+describe("hasReceivedUserMessage", () => {
+  test("returns false when no user message exists in standard conversations", () => {
+    rawGetImpl = () => null;
+
+    expect(hasReceivedUserMessage()).toBe(false);
+    expect(rawGetCalls).toBe(1);
+  });
+
+  test("returns true when at least one user message exists", () => {
+    rawGetImpl = () => ({ one: 1 });
+
+    expect(hasReceivedUserMessage()).toBe(true);
+    expect(rawGetCalls).toBe(1);
+  });
+
+  test("caches `true` result — subsequent calls do not re-query", () => {
+    rawGetImpl = () => ({ one: 1 });
+
+    expect(hasReceivedUserMessage()).toBe(true);
+    expect(hasReceivedUserMessage()).toBe(true);
+    expect(hasReceivedUserMessage()).toBe(true);
+
+    // Only the first call hits the DB.
+    expect(rawGetCalls).toBe(1);
+  });
+
+  test("does NOT cache `false` result — re-queries each time so the gate opens once the user interacts", () => {
+    rawGetImpl = () => null;
+    expect(hasReceivedUserMessage()).toBe(false);
+    expect(hasReceivedUserMessage()).toBe(false);
+    expect(rawGetCalls).toBe(2);
+
+    // Simulate the user sending their first message — gate flips on next call.
+    rawGetImpl = () => ({ one: 1 });
+    expect(hasReceivedUserMessage()).toBe(true);
+    expect(rawGetCalls).toBe(3);
+
+    // And now the cache kicks in.
+    expect(hasReceivedUserMessage()).toBe(true);
+    expect(rawGetCalls).toBe(3);
+  });
+
+  test("returns false (and logs) when rawGet throws — fail-conservative so background work stays paused", () => {
+    rawGetImpl = () => {
+      throw new Error("schema not initialized");
+    };
+
+    expect(hasReceivedUserMessage()).toBe(false);
+    expect(rawGetCalls).toBe(1);
+  });
+});

package/src/runtime/actor-trust-resolver.ts

@@ -13,6 +13,7 @@
 
 import type { ChannelId } from "../channels/types.js";
 import {
+  findContactByAddress,
   findContactByChannelExternalId,
   findGuardianForChannel,
 } from "../contacts/contact-store.js";
@@ -205,40 +206,61 @@ export function resolveActorTrust(
   );
 
   // --- Member lookup via contacts ---
+  // Primary path: match by externalUserId (populated after channel verification
+  // completes, or for channels registered via the verification upsert path).
+  // Fallback path: match by address (covers channels registered by the inbound
+  // name-capture flow, where address is set but externalUserId remains NULL
+  // until the DTMF challenge succeeds). Mirrors the gateway's OR-based lookup
+  // in ContactStore.getContactByPhoneNumber so the runtime's unverified-caller
+  // guard fires for pre-verification channels the gateway passes through.
   let memberRecord: ActorTrustContext["memberRecord"] = null;
-  const contactMatch = findContactByChannelExternalId(
+  const byExternalId = findContactByChannelExternalId(
     input.sourceChannel,
     canonicalSenderId,
   );
-  if (contactMatch) {
-    const matchingChannel = contactMatch.channels.find(
+  const byExternalIdChannel = byExternalId?.channels.find(
+    (ch) =>
+      ch.type === input.sourceChannel &&
+      ch.externalUserId === canonicalSenderId,
+  );
+
+  if (byExternalId && byExternalIdChannel) {
+    memberRecord = { contact: byExternalId, channel: byExternalIdChannel };
+  } else {
+    // Address fallback: catches channels where externalUserId is not yet set.
+    const byAddress = findContactByAddress(input.sourceChannel, canonicalSenderId);
+    const byAddressChannel = byAddress?.channels.find(
       (ch) =>
         ch.type === input.sourceChannel &&
-        ch.externalUserId === canonicalSenderId,
+        ch.address?.toLowerCase() === canonicalSenderId.toLowerCase(),
     );
-    if (matchingChannel) {
-      memberRecord = { contact: contactMatch, channel: matchingChannel };
+    if (byAddress && byAddressChannel) {
+      memberRecord = { contact: byAddress, channel: byAddressChannel };
     }
   }
+
   log.debug(
     {
       channel: input.sourceChannel,
       canonicalSenderId,
       found: !!memberRecord,
+      via: memberRecord?.channel.externalUserId ? "externalUserId" : memberRecord ? "address" : "none",
     },
     "trust-resolver member lookup",
   );
 
-  // Only use member metadata when the record's externalUserId matches the
+  // Only use member metadata when the record's channel identity matches the
   // current sender to avoid misidentification in group chats.
-  // Canonicalize the stored member ID to handle formatting variance (e.g.
-  // phone numbers stored without E.164 normalization).
+  // Primary check: externalUserId (canonicalized to handle E.164 variance).
+  // Fallback: address match for channels where externalUserId is NULL (e.g.
+  // name-capture registrations that haven't completed DTMF verification yet).
   const memberMatchesSender = memberRecord?.channel.externalUserId
     ? canonicalizeInboundIdentity(
         input.sourceChannel,
         memberRecord.channel.externalUserId,
       ) === canonicalSenderId
-    : false;
+    : (memberRecord?.channel.address?.toLowerCase() ===
+      canonicalSenderId.toLowerCase());
 
   const memberDisplayName =
     memberMatchesSender &&

package/src/runtime/agent-wake.ts

@@ -49,6 +49,7 @@ import type {
 import type { InterfaceId } from "../channels/types.js";
 import { resolveEffectiveContextWindow } from "../config/llm-context-resolution.js";
 import { getConfig } from "../config/loader.js";
+import type { LLMCallSite } from "../config/schemas/llm.js";
 import { getDiskPressureStatus } from "../daemon/disk-pressure-guard.js";
 import {
   classifyDiskPressureTurnPolicy,
@@ -56,6 +57,7 @@ import {
 } from "../daemon/disk-pressure-policy.js";
 import type { TrustContext } from "../daemon/trust-context.js";
 import { getConversationOverrideProfile } from "../memory/conversation-crud.js";
+import { recordRequestLog } from "../memory/llm-request-log-store.js";
 import type { TurnContext } from "../plugins/types.js";
 import type { Message } from "../providers/types.js";
 import { getLogger } from "../util/logger.js";
@@ -183,6 +185,13 @@ export interface WakeOptions {
    */
   sourceChannel?: TrustContext["sourceChannel"];
   sourceInterface?: InterfaceId | "vellum";
+  /**
+   * LLM call site to route this wake through. Defaults to `"mainAgent"` so
+   * conversation wakes share the user's chat-model selection. Background jobs
+   * (e.g. memory consolidation) pass their own call site so operators can
+   * tune the model/profile and observability bucket independently.
+   */
+  callSite?: LLMCallSite;
 }
 
 /**
@@ -539,6 +548,24 @@ export async function wakeAgentForOpportunity(
       }
     };
     const onEvent = (event: AgentEvent): void => {
+      // Replicates the recordRequestLog side-effect in `handleUsage` because
+      // wakes own their own onEvent and never reach `dispatchAgentEvent`.
+      if (event.type === "usage" && event.rawRequest && event.rawResponse) {
+        try {
+          recordRequestLog(
+            conversationId,
+            JSON.stringify(event.rawRequest),
+            JSON.stringify(event.rawResponse),
+            undefined,
+            event.actualProvider,
+          );
+        } catch (err) {
+          log.warn(
+            { err, conversationId, source },
+            "agent-wake: failed to persist LLM request log (non-fatal)",
+          );
+        }
+      }
       if (mode === "buffering") {
         buffered.push(event);
         return;
@@ -635,10 +662,11 @@ export async function wakeAgentForOpportunity(
     // `markProcessing(true)` so a thrown DB/config read can't strand the
     // processing flag.
     const overrideProfile = getConversationOverrideProfile(conversationId);
+    const callSite = opts.callSite ?? "mainAgent";
     const config = getConfig();
     const effectiveContextWindow = resolveEffectiveContextWindow({
       llm: config.llm,
-      callSite: "mainAgent",
+      callSite,
       overrideProfile,
     });
 
@@ -676,12 +704,13 @@ export async function wakeAgentForOpportunity(
           undefined, // no external abort signal
           `wake:${source}`,
           onCheckpoint,
-          // Route through `mainAgent` — same as a normal user turn on this
-          // conversation. Without an explicit callSite, the resolver in
+          // Route through the caller-supplied call site (defaults to
+          // `mainAgent` so a normal user-turn wake shares the user's chat
+          // selection). Without an explicit callSite, the resolver in
           // `RetryProvider` and the routing in `CallSiteRoutingProvider`
-          // short-circuit and silently drop both `llm.callSites.mainAgent`
-          // config and the pinned `overrideProfile` below.
-          "mainAgent",
+          // short-circuit and silently drop both per-callsite config and the
+          // pinned `overrideProfile` below.
+          callSite,
           wakeTurnContext,
           overrideProfile,
           effectiveContextWindow.maxInputTokens,