@vellumai/assistant 0.7.3 → 0.8.1

package/src/export/transcript-formatter.ts

@@ -97,6 +97,61 @@ function parseContent(raw: string): ContentBlock[] {
   }
 }
 
+type TranscriptMessage = ReturnType<typeof getMessages>[number];
+
+/**
+ * Format a slice of messages as a transcript body (no top-of-conversation
+ * header). Used by background jobs that process incremental slices — the
+ * memory-retrospective job re-renders only the messages added since its
+ * last successful run rather than the whole conversation. The format
+ * matches `buildAnalysisTranscript` per message so downstream agents see a
+ * consistent shape regardless of whether the input is a full transcript or
+ * a slice.
+ */
+export function formatMessageSliceForTranscript(
+  messages: TranscriptMessage[],
+): string {
+  const lines: string[] = [];
+  for (const msg of messages) {
+    appendMessageBlock(lines, msg);
+  }
+  return lines.join("\n");
+}
+
+function appendMessageBlock(lines: string[], msg: TranscriptMessage): void {
+  const role = formatRole(msg.role);
+  const time = formatTimestamp(msg.createdAt);
+  const content = parseContent(msg.content);
+  const text = extractAnalysisText(content);
+
+  lines.push(`## ${role} (${time})`);
+  lines.push(text);
+  lines.push("");
+
+  if (msg.metadata) {
+    try {
+      const parsed = messageMetadataSchema.safeParse(JSON.parse(msg.metadata));
+      if (parsed.success && parsed.data.subagentNotification) {
+        const notif = parsed.data.subagentNotification;
+        if (
+          (notif.status === "completed" ||
+            notif.status === "failed" ||
+            notif.status === "aborted") &&
+          notif.conversationId
+        ) {
+          const subMessages = getMessages(notif.conversationId);
+          lines.push(`### Subagent: ${notif.label} (${notif.status})`);
+          lines.push("");
+          lines.push(formatSubagentMessages(subMessages));
+          lines.push("");
+        }
+      }
+    } catch {
+      // Skip unparseable metadata
+    }
+  }
+}
+
 export function buildAnalysisTranscript(conversationId: string): string {
   const conversation = getConversation(conversationId);
   if (!conversation) {
@@ -124,11 +179,15 @@ export function buildAnalysisTranscript(conversationId: string): string {
     // Check for subagent notifications in metadata
     if (msg.metadata) {
       try {
-        const parsed = messageMetadataSchema.safeParse(JSON.parse(msg.metadata));
+        const parsed = messageMetadataSchema.safeParse(
+          JSON.parse(msg.metadata),
+        );
         if (parsed.success && parsed.data.subagentNotification) {
           const notif = parsed.data.subagentNotification;
           if (
-            (notif.status === "completed" || notif.status === "failed" || notif.status === "aborted") &&
+            (notif.status === "completed" ||
+              notif.status === "failed" ||
+              notif.status === "aborted") &&
             notif.conversationId
           ) {
             const subMessages = getMessages(notif.conversationId);

package/src/filing/filing-service.ts

@@ -1,7 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
 import { getConfig } from "../config/loader.js";
 import type { LLMCallSite } from "../config/schemas/llm.js";
 import {
@@ -9,8 +8,7 @@ import {
   diskPressureBackgroundSkipLogFields,
   shouldLogDiskPressureBackgroundSkip,
 } from "../daemon/disk-pressure-background-gate.js";
-import { processMessage } from "../daemon/process-message.js";
-import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
+import { runBackgroundJob } from "../runtime/background-job-runner.js";
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceDir } from "../util/platform.js";
 import { stripCommentLines } from "../util/strip-comment-lines.js";
@@ -67,10 +65,6 @@ If the disk shape changed (files split, files moved, files created, files remove
 This is your knowledge base — keep it sharp.`;
 
 export interface FilingDeps {
-  onConversationCreated?: (info: {
-    conversationId: string;
-    title: string;
-  }) => void;
   getCurrentHour?: () => number;
 }
 
@@ -115,8 +109,8 @@ export class FilingService {
 
   start(): void {
     const fullConfig = getConfig();
-    if (isAssistantFeatureFlagEnabled("memory-v2-enabled", fullConfig)) {
-      log.info("Filing service disabled — memory v2 flag is set");
+    if (fullConfig.memory.v2.enabled) {
+      log.info("Filing service disabled — memory v2 is active");
       this._nextRunAt = null;
       this._nextCompactionAt = null;
       return;
@@ -218,6 +212,13 @@ export class FilingService {
       return false;
     }
 
+    if (this.activeCompactionRun) {
+      log.debug(
+        "Compaction run in progress, skipping filing to avoid concurrent PKB writes",
+      );
+      return false;
+    }
+
     // Skip if buffer is empty — no work to do
     if (!force && !this.hasBufferContent()) {
       log.debug("Buffer is empty, skipping filing");
@@ -228,15 +229,7 @@ export class FilingService {
     const run = this.executeRun();
     this.activeRun = run;
     try {
-      await Promise.race([
-        run,
-        new Promise<never>((_, reject) =>
-          setTimeout(
-            () => reject(new Error("Filing execution timed out")),
-            FILING_TIMEOUT_MS,
-          ),
-        ),
-      ]);
+      await run;
     } finally {
       this.activeRun = null;
       this._lastRunAt = Date.now();
@@ -272,18 +265,17 @@ export class FilingService {
       return false;
     }
 
+    if (this.activeRun) {
+      log.debug(
+        "Filing run in progress, skipping compaction to avoid concurrent PKB writes",
+      );
+      return false;
+    }
+
     const run = this.executeCompactionRun();
     this.activeCompactionRun = run;
     try {
-      await Promise.race([
-        run,
-        new Promise<never>((_, reject) =>
-          setTimeout(
-            () => reject(new Error("Compaction execution timed out")),
-            FILING_TIMEOUT_MS,
-          ),
-        ),
-      ]);
+      await run;
     } finally {
       this.activeCompactionRun = null;
       this._lastCompactionAt = Date.now();
@@ -339,7 +331,8 @@ export class FilingService {
 
   private executeRun(): Promise<void> {
     return this.executeBackgroundJob({
-      title: "Knowledge base filing",
+      jobName: "filing",
+      systemHint: "Knowledge base filing",
       prompt: FILING_PROMPT_TEMPLATE,
       callSite: "filingAgent",
     });
@@ -347,47 +340,40 @@ export class FilingService {
 
   private executeCompactionRun(): Promise<void> {
     return this.executeBackgroundJob({
-      title: "Knowledge base compaction",
+      jobName: "compaction",
+      systemHint: "Knowledge base compaction",
       prompt: COMPACTION_PROMPT_TEMPLATE,
       callSite: "compactionAgent",
     });
   }
 
   private async executeBackgroundJob(opts: {
-    title: string;
+    jobName: string;
+    systemHint: string;
     prompt: string;
     callSite: LLMCallSite;
   }): Promise<void> {
-    log.info({ title: opts.title }, "Running background job");
-
-    try {
-      const conversation = bootstrapConversation({
-        conversationType: "background",
-        source: "filing",
-        groupId: "system:background",
-        origin: "filing",
-        systemHint: opts.title,
-      });
-
-      this.deps.onConversationCreated?.({
-        conversationId: conversation.id,
-        title: opts.title,
-      });
-
-      await processMessage(conversation.id, opts.prompt, undefined, {
-        trustContext: {
-          sourceChannel: "vellum",
-          trustClass: "guardian",
-        },
-        callSite: opts.callSite,
-      });
+    log.info({ jobName: opts.jobName }, "Running background job");
+
+    const result = await runBackgroundJob({
+      jobName: opts.jobName,
+      source: "filing",
+      systemHint: opts.systemHint,
+      prompt: opts.prompt,
+      trustContext: {
+        sourceChannel: "vellum",
+        trustClass: "guardian",
+      },
+      callSite: opts.callSite,
+      timeoutMs: FILING_TIMEOUT_MS,
+      origin: "filing",
+    });
 
+    if (result.ok) {
       log.info(
-        { conversationId: conversation.id, title: opts.title },
+        { conversationId: result.conversationId, jobName: opts.jobName },
         "Background job completed",
       );
-    } catch (err) {
-      log.error({ err, title: opts.title }, "Background job failed");
     }
   }
 }

package/src/heartbeat/__tests__/heartbeat-service.test.ts

@@ -0,0 +1,359 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+let workspaceDir: string;
+
+// Stub the in-process SSE hub so the writer's publish path is a
+// no-op in these tests.
+const publishSpy = mock<(event: unknown) => Promise<void>>(async () => {});
+
+mock.module("../../runtime/assistant-event-hub.js", () => ({
+  assistantEventHub: {
+    publish: publishSpy,
+    subscribe: () => () => {},
+  },
+}));
+
+// Stub workspace prompt reads so the heartbeat service doesn't try to
+// read real workspace files. Use a fallback for early module-load calls
+// (e.g. AuthSessionCache constructor) before beforeEach sets workspaceDir.
+const fallbackDir = join(tmpdir(), "vellum-hb-svc-fallback");
+mock.module("../../util/platform.js", () => ({
+  getWorkspaceDir: () => workspaceDir ?? fallbackDir,
+  getWorkspacePromptPath: (name: string) =>
+    join(workspaceDir ?? fallbackDir, name),
+  vellumRoot: () => workspaceDir ?? fallbackDir,
+  getDataDir: () => join(workspaceDir ?? fallbackDir, "data"),
+  getConversationsDir: () => join(workspaceDir ?? fallbackDir, "conversations"),
+  isMacOS: () => false,
+  isLinux: () => true,
+  isWindows: () => false,
+  getPlatformName: () => "linux",
+  normalizeAssistantId: (id: string) => id,
+  getEmbeddingModelsDir: () => join(workspaceDir ?? fallbackDir, "models"),
+  getSandboxRootDir: () => join(workspaceDir ?? fallbackDir, "sandbox"),
+  getSandboxWorkingDir: () => join(workspaceDir ?? fallbackDir, "sandbox/work"),
+  getInterfacesDir: () => join(workspaceDir ?? fallbackDir, "interfaces"),
+  getSoundsDir: () => join(workspaceDir ?? fallbackDir, "sounds"),
+  getAvatarDir: () => join(workspaceDir ?? fallbackDir, "avatar"),
+  AVATAR_IMAGE_FILENAME: "avatar-image.png",
+  getAvatarImagePath: () =>
+    join(workspaceDir ?? fallbackDir, "avatar/avatar-image.png"),
+
+  getXdgVellumConfigDirName: () => ".vellum",
+}));
+
+// Stub config so heartbeat is enabled. Must export every symbol from
+// the real module because Bun's mock.module replaces the entire module.
+const stubConfig = {
+  heartbeat: {
+    enabled: true,
+    intervalMs: 60_000,
+    activeHoursStart: null,
+    activeHoursEnd: null,
+  },
+};
+mock.module("../../config/loader.js", () => ({
+  getConfig: () => stubConfig,
+  getConfigReadOnly: () => stubConfig,
+  loadConfig: () => stubConfig,
+  saveConfig: () => {},
+  invalidateConfigCache: () => {},
+  loadRawConfig: () => ({}),
+  saveRawConfig: () => {},
+  applyNestedDefaults: (c: unknown) => c,
+  deepMergeMissing: (a: unknown) => a,
+  deepMergeOverwrite: (a: unknown) => a,
+  mergeDefaultWorkspaceConfig: () => {},
+  getNestedValue: () => undefined,
+  setNestedValue: () => {},
+  API_KEY_PROVIDERS: [],
+  _appendQuarantineBulletin: () => {},
+}));
+
+// Stub prompt helpers.
+mock.module("../../prompts/persona-resolver.js", () => ({
+  GUARDIAN_PERSONA_TEMPLATE: "",
+  resolveGuardianPersona: () => null,
+  resolveGuardianPersonaPath: () => null,
+  resolveGuardianPersonaStrict: () => null,
+  isGuardianPersonaCustomized: () => false,
+  resolveUserSlug: () => null,
+  resolveUserPersona: () => null,
+  resolveChannelPersona: () => null,
+  resolvePersonaContext: () => ({}),
+  ensureGuardianPersonaFile: () => {},
+}));
+mock.module("../../prompts/system-prompt.js", () => ({
+  isTemplateContent: () => false,
+  SYSTEM_PROMPT_CACHE_BOUNDARY: "<<CACHE_BOUNDARY>>",
+  buildCoreIdentityContext: () => "",
+  buildSystemPrompt: () => "",
+  buildCliReferenceSection: () => "",
+  ensurePromptFiles: () => {},
+  stripCommentLines: (s: string) => s,
+}));
+
+// Mock runBackgroundJob — HeartbeatService now delegates the
+// bootstrap/processMessage/timeout/failure-emit boundary to it.
+const STUB_CONVERSATION_ID = "conv-heartbeat-test";
+
+interface RunBackgroundJobCall {
+  jobName: string;
+  source: string;
+  prompt: string;
+  trustContext: { sourceChannel: string; trustClass: string };
+  callSite: string;
+  timeoutMs: number;
+  origin: string;
+  groupId?: string;
+  onConversationCreated?: (id: string) => void;
+}
+
+const runBackgroundJobCalls: RunBackgroundJobCall[] = [];
+let runBackgroundJobImpl: (opts: RunBackgroundJobCall) => Promise<{
+  conversationId: string;
+  ok: boolean;
+  error?: Error;
+  errorKind?: string;
+}> = async () => ({
+  conversationId: STUB_CONVERSATION_ID,
+  ok: true,
+});
+
+mock.module("../../runtime/background-job-runner.js", () => ({
+  runBackgroundJob: async (opts: RunBackgroundJobCall) => {
+    runBackgroundJobCalls.push(opts);
+    // Mirror the real runner's contract: fire onConversationCreated with the
+    // bootstrap-returned id BEFORE the job's processMessage finishes. Stub
+    // it here so HeartbeatService tests can observe sidebar timing.
+    opts.onConversationCreated?.(STUB_CONVERSATION_ID);
+    return runBackgroundJobImpl(opts);
+  },
+}));
+
+// Stub credential health service so the heartbeat doesn't spin up a
+// real check during the test.
+mock.module("../../credential-health/credential-health-service.js", () => ({
+  checkAllCredentials: async () => ({ unhealthy: [] }),
+}));
+
+// Stub the heartbeat-run-store so the tests don't need a populated SQLite
+// schema. Each function is a no-op that returns sensible defaults.
+let heartbeatRunIdCounter = 0;
+const skipHeartbeatRunCalls: Array<{ runId: string; reason: string }> = [];
+mock.module("../heartbeat-run-store.js", () => ({
+  insertPendingHeartbeatRun: () => `heartbeat-run-${++heartbeatRunIdCounter}`,
+  startHeartbeatRun: () => true,
+  completeHeartbeatRun: () => true,
+  skipHeartbeatRun: (runId: string, reason: string) => {
+    skipHeartbeatRunCalls.push({ runId, reason });
+  },
+  supersedePendingRun: () => {},
+  markStaleRunsAsMissed: () => 0,
+  markStaleRunningAsError: () => 0,
+  countCompletedHeartbeatRuns: () => 10,
+}));
+
+// Stub the pre-first-message gate so tests can flip it on/off without
+// needing to seed the SQLite messages table. Defaults to OPEN so existing
+// tests (which assume the user has interacted) keep passing.
+let preFirstMessageGateOpen = true;
+mock.module("../../runtime/pre-first-message-gate.js", () => ({
+  hasReceivedUserMessage: () => preFirstMessageGateOpen,
+}));
+
+
+const { HeartbeatService } = await import("../heartbeat-service.js");
+
+let origWorkspaceDir: string | undefined;
+
+beforeEach(() => {
+  workspaceDir = mkdtempSync(join(tmpdir(), "vellum-hb-svc-"));
+  origWorkspaceDir = process.env.VELLUM_WORKSPACE_DIR;
+  process.env.VELLUM_WORKSPACE_DIR = workspaceDir;
+  publishSpy.mockClear();
+  runBackgroundJobCalls.length = 0;
+  skipHeartbeatRunCalls.length = 0;
+  preFirstMessageGateOpen = true;
+  runBackgroundJobImpl = async () => ({
+    conversationId: STUB_CONVERSATION_ID,
+    ok: true,
+  });
+});
+
+afterEach(() => {
+  if (origWorkspaceDir === undefined) {
+    delete process.env.VELLUM_WORKSPACE_DIR;
+  } else {
+    process.env.VELLUM_WORKSPACE_DIR = origWorkspaceDir;
+  }
+  try {
+    rmSync(workspaceDir, { recursive: true, force: true });
+  } catch {
+    // best-effort
+  }
+});
+
+describe("HeartbeatService", () => {
+  test("invokes runBackgroundJob with expected options on each tick", async () => {
+    const service = new HeartbeatService({
+      alerter: () => {},
+    });
+
+    await service.runOnce({ force: true });
+
+    expect(runBackgroundJobCalls).toHaveLength(1);
+    const call = runBackgroundJobCalls[0]!;
+    expect(call.jobName).toBe("heartbeat");
+    expect(call.source).toBe("heartbeat");
+    expect(call.callSite).toBe("heartbeatAgent");
+    expect(call.origin).toBe("heartbeat");
+    // groupId is intentionally NOT passed — `system:background` is the
+    // runner's default, so passing it explicitly was redundant.
+    expect(call.groupId).toBeUndefined();
+    expect(call.timeoutMs).toBeGreaterThan(0);
+    expect(call.trustContext).toEqual({
+      sourceChannel: "vellum",
+      trustClass: "guardian",
+    });
+    expect(call.prompt).toContain("<heartbeat-checklist>");
+    expect(call.prompt).toContain("<heartbeat-disposition>");
+  });
+
+  test("fires onConversationCreated synchronously via the runner BEFORE the runner returns", async () => {
+    const created: Array<{ conversationId: string; title: string }> = [];
+    let runnerHasResolved = false;
+    let callbackFiredBeforeRunnerResolved = false;
+
+    runBackgroundJobImpl = async () => {
+      // Force the runner to take longer than the synchronous callback so
+      // we can verify the SSE entry is created before the job finishes.
+      await new Promise<void>((resolve) => setTimeout(resolve, 10));
+      runnerHasResolved = true;
+      return { conversationId: STUB_CONVERSATION_ID, ok: true };
+    };
+
+    const service = new HeartbeatService({
+      alerter: () => {},
+      onConversationCreated: (info) => {
+        created.push(info);
+        callbackFiredBeforeRunnerResolved = !runnerHasResolved;
+      },
+    });
+
+    await service.runOnce({ force: true });
+
+    expect(created).toEqual([
+      { conversationId: STUB_CONVERSATION_ID, title: "Heartbeat" },
+    ]);
+    expect(callbackFiredBeforeRunnerResolved).toBe(true);
+  });
+
+  test("does not race processMessage with an outer timeout — runner timeout is authoritative", async () => {
+    // If the heartbeat were still running an outer Promise.race, a
+    // long-running runner would surface as a 'Heartbeat execution timed out'
+    // log entry. With the outer race removed, runOnce just awaits the
+    // runner and returns whatever it produces.
+    let runnerCompleted = false;
+    runBackgroundJobImpl = async () => {
+      await new Promise<void>((resolve) => setTimeout(resolve, 30));
+      runnerCompleted = true;
+      return { conversationId: STUB_CONVERSATION_ID, ok: true };
+    };
+
+    const alerts: unknown[] = [];
+    const service = new HeartbeatService({
+      alerter: (alert) => alerts.push(alert),
+    });
+
+    await service.runOnce({ force: true });
+
+    expect(runnerCompleted).toBe(true);
+    // No alerter call because the runner returned ok=true and there was no
+    // outer-timeout failure to surface.
+    expect(alerts).toHaveLength(0);
+  });
+
+  test("calls alerter with the failure message when the runner reports ok=false", async () => {
+    runBackgroundJobImpl = async () => ({
+      conversationId: STUB_CONVERSATION_ID,
+      ok: false,
+      error: new Error("LLM call failed"),
+      errorKind: "exception",
+    });
+
+    const alerts: Array<{ type: string; title: string; body: string }> = [];
+    const service = new HeartbeatService({
+      alerter: (alert) =>
+        alerts.push(alert as { type: string; title: string; body: string }),
+    });
+
+    await service.runOnce({ force: true });
+
+    expect(alerts).toHaveLength(1);
+    expect(alerts[0]).toMatchObject({
+      type: "heartbeat_alert",
+      title: "Heartbeat Failed",
+      body: "LLM call failed",
+    });
+  });
+
+  test("does not call alerter when the runner reports ok=true", async () => {
+    const alerts: unknown[] = [];
+    const service = new HeartbeatService({
+      alerter: (alert) => alerts.push(alert),
+    });
+
+    await service.runOnce({ force: true });
+
+    expect(alerts).toHaveLength(0);
+  });
+
+  test("scheduled run skips with reason 'pre_first_user_message' when the user has not yet interacted", async () => {
+    preFirstMessageGateOpen = false;
+    const service = new HeartbeatService({
+      alerter: () => {},
+    });
+    // start() seeds `_pendingRunId` via `scheduleNextRun` so the skip is
+    // recorded with the pending run id. Without start() the test still
+    // passes the no-LLM-call assertion but the skip record would be a
+    // silent miss (the same `if (runId)` guard the existing "disabled"
+    // branch uses).
+    service.start();
+    skipHeartbeatRunCalls.length = 0;
+
+    try {
+      // A non-forced runOnce simulates the interval timer firing.
+      const result = await service.runOnce({ force: false });
+
+      expect(result).toBe(false);
+      expect(runBackgroundJobCalls).toHaveLength(0);
+      expect(
+        skipHeartbeatRunCalls.some(
+          (c) => c.reason === "pre_first_user_message",
+        ),
+      ).toBe(true);
+    } finally {
+      await service.stop();
+    }
+  });
+
+  test("forced run bypasses the pre-first-message gate (manual operator action)", async () => {
+    preFirstMessageGateOpen = false;
+    const service = new HeartbeatService({
+      alerter: () => {},
+    });
+
+    await service.runOnce({ force: true });
+
+    expect(runBackgroundJobCalls).toHaveLength(1);
+    expect(
+      skipHeartbeatRunCalls.some(
+        (c) => c.reason === "pre_first_user_message",
+      ),
+    ).toBe(false);
+  });
+});

package/src/heartbeat/heartbeat-run-store.ts

@@ -22,7 +22,8 @@ export type HeartbeatRunStatus =
 export type HeartbeatSkipReason =
   | "disabled"
   | "outside_active_hours"
-  | "overlap";
+  | "overlap"
+  | "pre_first_user_message";
 
 export interface HeartbeatRunRecord {
   id: string;