@vellumai/assistant 0.7.2 → 0.8.0

package/src/heartbeat/heartbeat-service.ts

@@ -3,11 +3,16 @@ import { join } from "node:path";
 
 import { getConfig } from "../config/loader.js";
 import type { HeartbeatConfig } from "../config/schemas/heartbeat.js";
+import {
+  checkDiskPressureBackgroundGate,
+  diskPressureBackgroundSkipLogFields,
+  shouldLogDiskPressureBackgroundSkip,
+} from "../daemon/disk-pressure-background-gate.js";
 import type { HeartbeatAlert } from "../daemon/message-protocol.js";
 import { processMessage } from "../daemon/process-message.js";
 import { emitFeedEvent } from "../home/emit-feed-event.js";
 import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
-import { getConversation } from "../memory/conversation-crud.js";
+import { getConversation, getMessages } from "../memory/conversation-crud.js";
 import { GENERATING_TITLE } from "../memory/conversation-title-service.js";
 import {
   GUARDIAN_PERSONA_TEMPLATE,
@@ -21,6 +26,7 @@ import { getWorkspaceDir, getWorkspacePromptPath } from "../util/platform.js";
 import { stripCommentLines } from "../util/strip-comment-lines.js";
 import {
   completeHeartbeatRun,
+  countCompletedHeartbeatRuns,
   insertPendingHeartbeatRun,
   markStaleRunningAsError,
   markStaleRunsAsMissed,
@@ -38,8 +44,12 @@ const DEFAULT_CHECKLIST = `- Check in with yourself. Read NOW.md. Is it still ac
 - If you have a thought worth sharing, send it. A follow-up, a useful find, a check-in. Not every beat, but when it feels right.
 - If something has happened since your last journal entry, write one. Even a few sentences. The journal is how future-you stays connected.`;
 
+const EARLY_HEARTBEAT_THRESHOLD = 3;
 const REENGAGEMENT_COOLDOWN_MS = 18 * 60 * 60 * 1000; // 18 hours
 const HEARTBEAT_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+const HEARTBEAT_ALERT_MARKER = "HEARTBEAT_ALERT";
+const HEARTBEAT_OK_MARKER = "HEARTBEAT_OK";
+const HEARTBEAT_ALERT_SUMMARY_MAX_CHARS = 700;
 
 // Stripped-comment form of the guardian persona scaffold. Computed
 // once at module load because stripping comment lines is deterministic
@@ -92,6 +102,69 @@ function recordReengagementTimestamp(): void {
   }
 }
 
+type HeartbeatDisposition = "alert" | "ok" | "unknown";
+
+function parseHeartbeatDisposition(text: string | null): HeartbeatDisposition {
+  if (!text) return "unknown";
+  const lines = text
+    .trim()
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  const lastLine = lines.at(-1);
+  if (lastLine === HEARTBEAT_ALERT_MARKER) return "alert";
+  if (lastLine === HEARTBEAT_OK_MARKER) return "ok";
+  return "unknown";
+}
+
+function stripHeartbeatDispositionMarkers(text: string): string {
+  return text
+    .replace(
+      new RegExp(
+        `(?:\\r?\\n)?\\s*(?:${HEARTBEAT_ALERT_MARKER}|${HEARTBEAT_OK_MARKER})\\s*$`,
+      ),
+      "",
+    )
+    .trim();
+}
+
+function truncateSummary(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, Math.max(0, maxChars - 3)).trimEnd()}...`;
+}
+
+function buildHeartbeatAlertSummary(text: string | null): string {
+  const summary = text ? stripHeartbeatDispositionMarkers(text) : "";
+  return truncateSummary(
+    summary || "Your assistant found something worth your attention.",
+    HEARTBEAT_ALERT_SUMMARY_MAX_CHARS,
+  );
+}
+
+function extractVisibleTextFromStoredMessageContent(raw: string): string {
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (typeof parsed === "string") return parsed;
+    if (!Array.isArray(parsed)) return "";
+    const texts: string[] = [];
+    for (const block of parsed) {
+      if (
+        block != null &&
+        typeof block === "object" &&
+        "type" in block &&
+        block.type === "text" &&
+        "text" in block &&
+        typeof block.text === "string"
+      ) {
+        texts.push(block.text);
+      }
+    }
+    return texts.join("\n").trim();
+  } catch {
+    return raw;
+  }
+}
+
 export interface HeartbeatDeps {
   alerter: (alert: HeartbeatAlert) => void;
   onConversationCreated?: (info: {
@@ -168,18 +241,22 @@ export class HeartbeatService {
           "Recovered stale heartbeat runs on startup",
         );
 
-        const total = this._startupMissedCount + this._startupCrashedCount;
-        const today = new Date().toISOString().split("T")[0];
-        void emitFeedEvent({
-          source: "assistant",
-          title: "Heartbeat Runs Missed",
-          summary: `${total} heartbeat run${total > 1 ? "s were" : " was"} missed while the assistant was offline.`,
-          dedupKey: `heartbeat:missed:${today}`,
-          priority: 55,
-          urgency: "high",
-        }).catch((err) => {
-          log.warn({ err }, "Failed to emit missed heartbeat feed event");
-        });
+        if (!isDiskPressureBackgroundLocked("heartbeat-startup")) {
+          const total = this._startupMissedCount + this._startupCrashedCount;
+          const today = new Date().toISOString().split("T")[0];
+          void emitFeedEvent({
+            source: "assistant",
+            title: "Heartbeat Runs Missed",
+            summary: `${total} heartbeat run${
+              total > 1 ? "s were" : " was"
+            } missed while the assistant was offline.`,
+            dedupKey: `heartbeat:missed:${today}`,
+            priority: 55,
+            urgency: "high",
+          }).catch((err) => {
+            log.warn({ err }, "Failed to emit missed heartbeat feed event");
+          });
+        }
       }
     }
 
@@ -328,6 +405,10 @@ export class HeartbeatService {
   async runOnce({ force = false }: { force?: boolean } = {}): Promise<boolean> {
     const config = getConfig().heartbeat;
 
+    if (!force && isDiskPressureBackgroundLocked("heartbeat")) {
+      return false;
+    }
+
     let runId: string | null;
     let scheduledFor: number;
     if (force) {
@@ -579,6 +660,65 @@ export class HeartbeatService {
     }
   }
 
+  private getLatestAssistantMessage(
+    conversationId: string,
+  ): { id: string; text: string } | null {
+    try {
+      const messages = getMessages(conversationId);
+      for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i]!;
+        if (message.role !== "assistant") continue;
+        return {
+          id: message.id,
+          text: extractVisibleTextFromStoredMessageContent(message.content),
+        };
+      }
+    } catch (err) {
+      log.warn(
+        { err, conversationId },
+        "Failed to read heartbeat assistant message",
+      );
+    }
+    return null;
+  }
+
+  private async emitHeartbeatAlertNotification(params: {
+    runId: string;
+    conversationId: string;
+    messageId?: string;
+    conversationTitle: string;
+    summary: string;
+  }): Promise<void> {
+    const { emitNotificationSignal } =
+      await import("../notifications/emit-signal.js");
+
+    await emitNotificationSignal({
+      sourceEventName: "heartbeat.alert",
+      sourceChannel: "watcher",
+      sourceContextId: params.runId,
+      dedupeKey: `heartbeat:alert:${params.runId}`,
+      attentionHints: {
+        requiresAction: true,
+        urgency: "medium",
+        isAsyncBackground: true,
+        visibleInSourceNow: false,
+      },
+      contextPayload: {
+        title: "Heartbeat Alert",
+        summary: params.summary,
+        conversationTitle: params.conversationTitle,
+        conversationId: params.conversationId,
+        messageId: params.messageId,
+      },
+      routingIntent: "single_channel",
+      conversationAffinityHint: { vellum: params.conversationId },
+      conversationMetadata: {
+        source: "heartbeat",
+        groupId: "system:background",
+      },
+    });
+  }
+
   private async executeRun(runId: string, scheduledFor: number): Promise<void> {
     log.info("Running heartbeat");
 
@@ -595,9 +735,11 @@ export class HeartbeatService {
     let conversationId: string | undefined;
     try {
       const checklist = this.readChecklist();
+      const completedRunCount = countCompletedHeartbeatRuns();
       const { prompt, includedReengagement } = this.buildPrompt(
         checklist,
         unhealthyProviders,
+        completedRunCount,
       );
 
       const conversation = bootstrapConversation({
@@ -609,11 +751,6 @@ export class HeartbeatService {
       });
       conversationId = conversation.id;
 
-      this.deps.onConversationCreated?.({
-        conversationId: conversation.id,
-        title: "Heartbeat",
-      });
-
       await processMessage(conversation.id, prompt, undefined, {
         trustContext: {
           sourceChannel: "vellum",
@@ -644,20 +781,32 @@ export class HeartbeatService {
           // Best-effort; fall back to generic title.
         }
 
-        const today = new Date().toISOString().split("T")[0];
-        void emitFeedEvent({
-          source: "assistant",
-          title,
-          summary: "Periodic check completed. Tap to see details.",
-          dedupKey: `heartbeat:ok:${today}`,
-          priority: 30,
-        }).catch((err) => {
-          log.warn(
-            { err, conversationId: conversation.id },
-            "Failed to emit heartbeat feed event",
-          );
-        });
+        const assistantMessage = this.getLatestAssistantMessage(
+          conversation.id,
+        );
+        const disposition = parseHeartbeatDisposition(
+          assistantMessage?.text ?? null,
+        );
+        if (disposition === "alert") {
+          this.deps.onConversationCreated?.({
+            conversationId: conversation.id,
+            title,
+          });
+          void this.emitHeartbeatAlertNotification({
+            runId,
+            conversationId: conversation.id,
+            messageId: assistantMessage?.id,
+            conversationTitle: title,
+            summary: buildHeartbeatAlertSummary(assistantMessage?.text ?? null),
+          }).catch((err) => {
+            log.warn(
+              { err, conversationId: conversation.id },
+              "Failed to emit heartbeat alert notification",
+            );
+          });
+        }
 
+        const today = new Date().toISOString().split("T")[0];
         if (latenessMs > LATE_THRESHOLD_MS) {
           const lateMinutes = Math.round(latenessMs / 60_000);
           void emitFeedEvent({
@@ -714,6 +863,7 @@ export class HeartbeatService {
   buildPrompt(
     checklist: string,
     unhealthyProviders: string[] = [],
+    completedRunCount: number = Infinity,
   ): { prompt: string; includedReengagement: boolean } {
     let prompt = `You are running a periodic heartbeat check. Review the following checklist and take any necessary actions.
 
@@ -730,11 +880,20 @@ Do NOT attempt to use tools for these providers — they will fail. Skip any che
     }
 
     prompt += `\n\n<heartbeat-disposition>
+This heartbeat runs frequently. Do not manufacture a report just because it ran.
+If there is nothing genuinely useful, actionable, or interesting to surface, keep the response brief and end with HEARTBEAT_OK.
+If there is something worth interrupting the guardian for, write a concise guardian-facing note first: what happened, why it matters, and the recommended next step. Address the guardian directly as "you"; do not write instructions to yourself or another intermediary. Then end with HEARTBEAT_ALERT. That note may be used as notification copy.
 After completing your review, end your response with one of:
 - HEARTBEAT_OK — if everything looks good, no action needed
 - HEARTBEAT_ALERT — if you found issues that need attention (describe them before this marker)
 </heartbeat-disposition>`;
 
+    if (completedRunCount < EARLY_HEARTBEAT_THRESHOLD) {
+      prompt += `\n\n<early-heartbeat>
+This is one of your first heartbeats. Your user hasn't heard from you yet and may not know you're here. Find something genuinely useful to share — a follow-up from a recent conversation, something you noticed, or a quick check-in. Lean toward HEARTBEAT_ALERT this time. First impressions matter.
+</early-heartbeat>`;
+    }
+
     let includedReengagement = false;
     if (isShallowProfile() && isReengagementCooldownElapsed()) {
       includedReengagement = true;
@@ -745,6 +904,21 @@ After completing your review, end your response with one of:
   }
 }
 
+function isDiskPressureBackgroundLocked(logKey: string): boolean {
+  const diskPressureGate = checkDiskPressureBackgroundGate("background-work");
+  if (diskPressureGate.action === "allow") return false;
+  if (shouldLogDiskPressureBackgroundSkip(logKey)) {
+    log.warn(
+      {
+        source: "heartbeat",
+        ...diskPressureBackgroundSkipLogFields(diskPressureGate),
+      },
+      "Heartbeat skipped during disk pressure cleanup mode",
+    );
+  }
+  return true;
+}
+
 /**
  * Check if the given hour falls within the active window.
  * Handles overnight windows (e.g. start=22, end=6).

package/src/home/feed-scheduler.ts

@@ -28,6 +28,11 @@
  *     scheduler needing to touch the event hub.
  */
 
+import {
+  checkDiskPressureBackgroundGate,
+  diskPressureBackgroundSkipLogFields,
+  shouldLogDiskPressureBackgroundSkip,
+} from "../daemon/disk-pressure-background-gate.js";
 import { getLogger } from "../util/logger.js";
 import type { FeedItem } from "./feed-types.js";
 import {
@@ -119,6 +124,19 @@ export function startFeedScheduler(
       rollupRan: false,
     };
     if (stopped || tickRunning) return summary;
+    const diskPressureGate = checkDiskPressureBackgroundGate("background-work");
+    if (diskPressureGate.action === "skip") {
+      if (shouldLogDiskPressureBackgroundSkip("home-feed-scheduler")) {
+        log.warn(
+          {
+            source: "feed-scheduler",
+            ...diskPressureBackgroundSkipLogFields(diskPressureGate),
+          },
+          "Home feed scheduler skipped during disk pressure cleanup mode",
+        );
+      }
+      return summary;
+    }
     tickRunning = true;
     const nowMs = now.getTime();
     try {

package/src/inbound/platform-callback-registration.ts

@@ -16,11 +16,7 @@
  * callback_url that external services should use.
  */
 
-import {
-  getPlatformAssistantId,
-  getPlatformBaseUrl,
-  getPlatformInternalApiKey,
-} from "../config/env.js";
+import { getPlatformAssistantId, getPlatformBaseUrl } from "../config/env.js";
 import { getIsPlatform } from "../config/env-registry.js";
 import { credentialKey } from "../security/credential-key.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
@@ -32,7 +28,6 @@ export interface PlatformCallbackRegistrationContext {
   isPlatform: boolean;
   platformBaseUrl: string;
   assistantId: string;
-  hasInternalApiKey: boolean;
   hasAssistantApiKey: boolean;
   authHeader: string | null;
   enabled: boolean;
@@ -54,20 +49,18 @@ export async function resolvePlatformCallbackRegistrationContext(): Promise<Plat
   );
   const assistantId =
     getPlatformAssistantId().trim() || storedAssistantIdRaw?.trim() || "";
-  const internalApiKey = getPlatformInternalApiKey().trim();
-  const assistantApiKey = storedAssistantApiKeyRaw?.trim() || "";
-  const authHeader = internalApiKey
-    ? `Bearer ${internalApiKey}`
-    : assistantApiKey
-      ? `Api-Key ${assistantApiKey}`
-      : null;
+  const envAssistantCredential = process.env.ASSISTANT_API_KEY?.trim();
+  const assistantCredential =
+    storedAssistantApiKeyRaw?.trim() || envAssistantCredential || undefined;
+  const authHeader = assistantCredential
+    ? `Api-Key ${assistantCredential}`
+    : null;
 
   return {
     isPlatform: platform,
     platformBaseUrl,
     assistantId,
-    hasInternalApiKey: internalApiKey.length > 0,
-    hasAssistantApiKey: assistantApiKey.length > 0,
+    hasAssistantApiKey: !!assistantCredential,
     authHeader,
     // Enabled when we have enough context to register callback routes.
     // Does NOT require IS_PLATFORM — self-hosted assistants with stored

package/src/ipc/__tests__/clients-list-ipc.test.ts

@@ -0,0 +1,169 @@
+/**
+ * End-to-end test for `assistant clients list` over IPC.
+ *
+ * Regression test for the gap where the same-user filter on
+ * `GET /v1/clients` (which reads `headers["x-vellum-actor-principal-id"]`)
+ * silently returned an empty list over IPC because the IPC adapter did
+ * not inject the synthetic actor-principal header that the HTTP adapter
+ * populates from the verified `AuthContext`.
+ *
+ * Asserts that in non-dev-bypass mode (`isHttpAuthDisabled() === false`),
+ * the CLI sees same-user clients via the IPC path because the IPC server
+ * fills in the header from the local guardian principal.
+ */
+
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  test,
+} from "bun:test";
+
+import { runAssistantCommandFull } from "../../cli/__tests__/run-assistant-command.js";
+import { AssistantIpcServer } from "../assistant-server.js";
+
+// ── Module mocks (must be set up before importing the route) ──────────────
+
+let fakeHttpAuthDisabled = false;
+let fakeLocalPrincipalId: string | undefined = "guardian-local";
+
+mock.module("../../config/env.js", () => ({
+  isHttpAuthDisabled: () => fakeHttpAuthDisabled,
+  hasUngatedHttpAuthDisabled: () => false,
+}));
+
+mock.module("../../runtime/local-actor-identity.js", () => ({
+  findLocalGuardianPrincipalId: () => fakeLocalPrincipalId,
+}));
+
+// ── Real imports (after mocks) ────────────────────────────────────────────
+
+import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
+
+// ── Fixtures ──────────────────────────────────────────────────────────────
+
+let server: AssistantIpcServer | null = null;
+
+function registerClient(args: {
+  clientId: string;
+  actorPrincipalId?: string;
+}): void {
+  assistantEventHub.subscribe({
+    type: "client",
+    clientId: args.clientId,
+    interfaceId: "macos",
+    capabilities: ["host_bash", "host_file", "host_cu"],
+    actorPrincipalId: args.actorPrincipalId,
+    callback: () => {},
+  });
+}
+
+function clearHub(): void {
+  const ids = assistantEventHub.listClients().map((c) => c.clientId);
+  for (const id of ids) {
+    assistantEventHub.disposeClient(id);
+  }
+}
+
+async function startServer(): Promise<void> {
+  server = new AssistantIpcServer();
+  await server.start();
+  // Allow the listener to be ready before the CLI tries to connect.
+  await new Promise((resolve) => setTimeout(resolve, 50));
+}
+
+beforeEach(() => {
+  fakeHttpAuthDisabled = false;
+  fakeLocalPrincipalId = "guardian-local";
+  clearHub();
+});
+
+afterEach(() => {
+  server?.stop();
+  server = null;
+});
+
+afterAll(() => {
+  mock.restore();
+});
+
+// ── Tests ────────────────────────────────────────────────────────────────
+
+describe("assistant clients list over IPC — same-user filter", () => {
+  test("returns same-user clients in non-dev-bypass mode", async () => {
+    registerClient({
+      clientId: "client-self-1",
+      actorPrincipalId: "guardian-local",
+    });
+    registerClient({
+      clientId: "client-self-2",
+      actorPrincipalId: "guardian-local",
+    });
+    registerClient({
+      clientId: "client-other",
+      actorPrincipalId: "other-user",
+    });
+
+    await startServer();
+
+    const { stdout } = await runAssistantCommandFull(
+      "clients",
+      "list",
+      "--json",
+    );
+
+    const parsed = JSON.parse(stdout.trim()) as {
+      clients: Array<{ clientId: string }>;
+    };
+    const ids = parsed.clients.map((c) => c.clientId).sort();
+    expect(ids).toEqual(["client-self-1", "client-self-2"]);
+  });
+
+  test("returns empty when no local guardian principal is bound (fail-closed)", async () => {
+    fakeLocalPrincipalId = undefined;
+    registerClient({
+      clientId: "client-self",
+      actorPrincipalId: "guardian-local",
+    });
+
+    await startServer();
+
+    const { stdout } = await runAssistantCommandFull(
+      "clients",
+      "list",
+      "--json",
+    );
+    const parsed = JSON.parse(stdout.trim()) as {
+      clients: Array<{ clientId: string }>;
+    };
+    expect(parsed.clients).toEqual([]);
+  });
+
+  test("dev-bypass mode returns all clients regardless of principal", async () => {
+    fakeHttpAuthDisabled = true;
+    registerClient({
+      clientId: "client-self",
+      actorPrincipalId: "guardian-local",
+    });
+    registerClient({
+      clientId: "client-other",
+      actorPrincipalId: "other-user",
+    });
+
+    await startServer();
+
+    const { stdout } = await runAssistantCommandFull(
+      "clients",
+      "list",
+      "--json",
+    );
+    const parsed = JSON.parse(stdout.trim()) as {
+      clients: Array<{ clientId: string }>;
+    };
+    const ids = parsed.clients.map((c) => c.clientId).sort();
+    expect(ids).toEqual(["client-other", "client-self"]);
+  });
+});