@vellumai/assistant 0.6.5 → 0.6.6

package/src/heartbeat/__tests__/heartbeat-feed-event.test.ts

@@ -0,0 +1,160 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+// 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.
+mock.module("../../util/platform.js", () => ({
+  getWorkspaceDir: () => workspaceDir,
+  getWorkspacePromptPath: (name: string) => join(workspaceDir, name),
+  vellumRoot: () => workspaceDir,
+  getDataDir: () => join(workspaceDir, "data"),
+}));
+
+// Stub config so heartbeat is enabled.
+mock.module("../../config/loader.js", () => ({
+  getConfig: () => ({
+    heartbeat: {
+      enabled: true,
+      intervalMs: 60_000,
+      activeHoursStart: null,
+      activeHoursEnd: null,
+    },
+  }),
+}));
+
+// Stub conversation bootstrap.
+const lastConversationId = "conv-heartbeat-test";
+mock.module("../../memory/conversation-bootstrap.js", () => ({
+  bootstrapConversation: () => ({ id: lastConversationId }),
+}));
+
+// Stub prompt helpers.
+mock.module("../../prompts/persona-resolver.js", () => ({
+  GUARDIAN_PERSONA_TEMPLATE: "",
+  resolveGuardianPersona: () => null,
+}));
+mock.module("../../prompts/system-prompt.js", () => ({
+  isTemplateContent: () => false,
+}));
+
+const { getHomeFeedPath } = await import("../../home/feed-writer.js");
+const { HeartbeatService } = await import("../heartbeat-service.js");
+
+interface OnDiskItem {
+  id: string;
+  type: string;
+  source?: string;
+  title: string;
+  summary: string;
+  priority: number;
+  status: string;
+  author: string;
+  urgency?: string;
+}
+
+function readFeedItems(): OnDiskItem[] {
+  const raw = JSON.parse(readFileSync(getHomeFeedPath(), "utf-8"));
+  return raw.items as OnDiskItem[];
+}
+
+let workspaceDir: string;
+let origWorkspaceDir: string | undefined;
+
+beforeEach(() => {
+  workspaceDir = mkdtempSync(join(tmpdir(), "vellum-hb-feed-"));
+  origWorkspaceDir = process.env.VELLUM_WORKSPACE_DIR;
+  process.env.VELLUM_WORKSPACE_DIR = workspaceDir;
+  publishSpy.mockClear();
+});
+
+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("heartbeat feed events", () => {
+  test("successful heartbeat emits feed event with priority 30 and no urgency", async () => {
+    const service = new HeartbeatService({
+      processMessage: async () => ({ messageId: "msg-1" }),
+      alerter: () => {},
+    });
+
+    await service.runOnce({ force: true });
+
+    // Give the fire-and-forget emitFeedEvent time to flush.
+    await new Promise((r) => setTimeout(r, 100));
+
+    const items = readFeedItems();
+    const heartbeatItem = items.find((i) => i.title === "Heartbeat");
+    expect(heartbeatItem).toBeDefined();
+    expect(heartbeatItem!.summary).toBe("Heartbeat check completed.");
+    expect(heartbeatItem!.priority).toBe(30);
+    expect(heartbeatItem!.urgency).toBeUndefined();
+    expect(heartbeatItem!.source).toBe("assistant");
+  });
+
+  test("failed heartbeat emits feed event with priority 55 and urgency medium", async () => {
+    const service = new HeartbeatService({
+      processMessage: async () => {
+        throw new Error("LLM call failed");
+      },
+      alerter: () => {},
+    });
+
+    await service.runOnce({ force: true });
+
+    // Give the fire-and-forget emitFeedEvent time to flush.
+    await new Promise((r) => setTimeout(r, 100));
+
+    const items = readFeedItems();
+    const heartbeatItem = items.find((i) => i.title === "Heartbeat");
+    expect(heartbeatItem).toBeDefined();
+    expect(heartbeatItem!.summary).toBe(
+      "Heartbeat check failed. Check logs for details.",
+    );
+    expect(heartbeatItem!.priority).toBe(55);
+    expect(heartbeatItem!.urgency).toBe("medium");
+    expect(heartbeatItem!.source).toBe("assistant");
+  });
+
+  test("dedupKey uses date for daily dedup", async () => {
+    const service = new HeartbeatService({
+      processMessage: async () => ({ messageId: "msg-1" }),
+      alerter: () => {},
+    });
+
+    // Run twice — same day should dedup to one item.
+    await service.runOnce({ force: true });
+    await new Promise((r) => setTimeout(r, 100));
+    await service.runOnce({ force: true });
+    await new Promise((r) => setTimeout(r, 100));
+
+    const items = readFeedItems();
+    const heartbeatItems = items.filter((i) => i.title === "Heartbeat");
+    expect(heartbeatItems).toHaveLength(1);
+
+    const today = new Date().toISOString().split("T")[0];
+    expect(heartbeatItems[0]!.id).toBe(`emit:assistant:heartbeat:ok:${today}`);
+  });
+});

package/src/heartbeat/heartbeat-service.ts

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { getConfig } from "../config/loader.js";
 import type { LLMCallSite } from "../config/schemas/llm.js";
 import type { HeartbeatAlert } from "../daemon/message-protocol.js";
+import { emitFeedEvent } from "../home/emit-feed-event.js";
 import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
 import {
   GUARDIAN_PERSONA_TEMPLATE,
@@ -396,6 +397,19 @@ export class HeartbeatService {
       }
 
       log.info({ conversationId: conversation.id }, "Heartbeat completed");
+
+      void emitFeedEvent({
+        source: "assistant",
+        title: "Heartbeat",
+        summary: "Heartbeat check completed.",
+        dedupKey: `heartbeat:ok:${new Date().toISOString().split("T")[0]}`,
+        priority: 30,
+      }).catch((err) => {
+        log.warn(
+          { err, conversationId: conversation.id },
+          "Failed to emit heartbeat feed event",
+        );
+      });
     } catch (err) {
       log.error({ err }, "Heartbeat failed");
       try {
@@ -407,6 +421,15 @@ export class HeartbeatService {
       } catch (alertErr) {
         log.error({ alertErr }, "Failed to broadcast heartbeat alert");
       }
+
+      void emitFeedEvent({
+        source: "assistant",
+        title: "Heartbeat",
+        summary: "Heartbeat check failed. Check logs for details.",
+        dedupKey: `heartbeat:fail:${new Date().toISOString().split("T")[0]}`,
+        priority: 55,
+        urgency: "medium",
+      }).catch(() => {});
     }
   }
 
@@ -431,7 +454,7 @@ ${checklist}
     if (unhealthyProviders.length > 0) {
       const providers = unhealthyProviders.join(", ");
       prompt += `\n\n<credential-status>
-The following providers have broken or expired OAuth credentials: ${providers}.
+The following providers have broken or expired credentials: ${providers}.
 Do NOT attempt to use tools for these providers — they will fail. Skip any checklist items that depend on them and note the outage in your summary.
 </credential-status>`;
     }

package/src/home/__tests__/feed-population-integration.test.ts

@@ -0,0 +1,312 @@
+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";
+
+// Stub the in-process SSE hub so the writer's publish path is a
+// no-op in these tests. Must be in place before the writer module is
+// imported (directly or transitively) so the dynamic import below
+// picks it up.
+const publishSpy = mock<(event: unknown) => Promise<void>>(async () => {});
+
+mock.module("../../runtime/assistant-event-hub.js", () => ({
+  assistantEventHub: {
+    publish: publishSpy,
+    subscribe: () => () => {},
+  },
+}));
+
+const { emitFeedEvent } = await import("../emit-feed-event.js");
+const { readHomeFeed, MAX_ACTIONS_PER_SOURCE } =
+  await import("../feed-writer.js");
+
+type FeedItemSource = "gmail" | "slack" | "calendar" | "assistant";
+
+const ALL_SOURCES: FeedItemSource[] = [
+  "gmail",
+  "slack",
+  "calendar",
+  "assistant",
+];
+
+let workspaceDir: string;
+let origWorkspaceDir: string | undefined;
+
+beforeEach(() => {
+  workspaceDir = mkdtempSync(join(tmpdir(), "vellum-feed-integ-"));
+  origWorkspaceDir = process.env.VELLUM_WORKSPACE_DIR;
+  process.env.VELLUM_WORKSPACE_DIR = workspaceDir;
+  publishSpy.mockClear();
+});
+
+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("feed population integration", () => {
+  test("items from all 4 sources coexist and are sorted by priority", async () => {
+    // Emit one item per source with distinct priorities.
+    await emitFeedEvent({
+      source: "gmail",
+      title: "Gmail action",
+      summary: "Replied to a thread.",
+      priority: 30,
+      dedupKey: "gmail-1",
+    });
+    await emitFeedEvent({
+      source: "slack",
+      title: "Slack action",
+      summary: "Sent a message in #general.",
+      priority: 70,
+      dedupKey: "slack-1",
+    });
+    await emitFeedEvent({
+      source: "calendar",
+      title: "Calendar action",
+      summary: "Meeting prep reminder.",
+      priority: 50,
+      dedupKey: "cal-1",
+    });
+    await emitFeedEvent({
+      source: "assistant",
+      title: "Assistant action",
+      summary: "Ran weekly review.",
+      priority: 90,
+      dedupKey: "asst-1",
+    });
+
+    const feed = readHomeFeed();
+    expect(feed.items).toHaveLength(4);
+
+    // Verify all four sources are present.
+    const sources = new Set(feed.items.map((i) => i.source));
+    for (const s of ALL_SOURCES) {
+      expect(sources.has(s)).toBe(true);
+    }
+
+    // Items should be sorted by priority DESC.
+    const priorities = feed.items.map((i) => i.priority);
+    for (let i = 1; i < priorities.length; i++) {
+      expect(priorities[i - 1]!).toBeGreaterThanOrEqual(priorities[i]!);
+    }
+
+    // Spot-check the ordering: assistant (90) first, gmail (30) last.
+    expect(feed.items[0]!.source).toBe("assistant");
+    expect(feed.items[feed.items.length - 1]!.source).toBe("gmail");
+  });
+
+  test("per-source cap holds across mixed sources", async () => {
+    // Emit MAX + 5 items for gmail and MAX + 5 for slack, plus a
+    // handful from calendar and assistant. Only the capped sources
+    // should be pruned.
+    const overflow = MAX_ACTIONS_PER_SOURCE + 5;
+
+    for (let i = 0; i < overflow; i++) {
+      await emitFeedEvent({
+        source: "gmail",
+        title: `Gmail item ${i}`,
+        summary: `Gmail summary ${i}`,
+        priority: 50,
+      });
+    }
+
+    for (let i = 0; i < overflow; i++) {
+      await emitFeedEvent({
+        source: "slack",
+        title: `Slack item ${i}`,
+        summary: `Slack summary ${i}`,
+        priority: 50,
+      });
+    }
+
+    // A few items from the other two sources — should be untouched.
+    for (let i = 0; i < 3; i++) {
+      await emitFeedEvent({
+        source: "calendar",
+        title: `Calendar item ${i}`,
+        summary: `Calendar summary ${i}`,
+        priority: 50,
+      });
+    }
+    for (let i = 0; i < 2; i++) {
+      await emitFeedEvent({
+        source: "assistant",
+        title: `Assistant item ${i}`,
+        summary: `Assistant summary ${i}`,
+        priority: 50,
+      });
+    }
+
+    const feed = readHomeFeed();
+
+    const gmailItems = feed.items.filter((i) => i.source === "gmail");
+    const slackItems = feed.items.filter((i) => i.source === "slack");
+    const calendarItems = feed.items.filter((i) => i.source === "calendar");
+    const assistantItems = feed.items.filter((i) => i.source === "assistant");
+
+    expect(gmailItems).toHaveLength(MAX_ACTIONS_PER_SOURCE);
+    expect(slackItems).toHaveLength(MAX_ACTIONS_PER_SOURCE);
+    expect(calendarItems).toHaveLength(3);
+    expect(assistantItems).toHaveLength(2);
+  });
+
+  test("expired items are filtered out at read time", async () => {
+    // One item that expired in the past, one that is still valid.
+    const pastDate = new Date(Date.now() - 60_000).toISOString();
+    const futureDate = new Date(Date.now() + 3_600_000).toISOString();
+
+    await emitFeedEvent({
+      source: "gmail",
+      title: "Expired item",
+      summary: "Should not appear.",
+      expiresAt: pastDate,
+      dedupKey: "expired-1",
+    });
+    await emitFeedEvent({
+      source: "slack",
+      title: "Still valid",
+      summary: "Should appear.",
+      expiresAt: futureDate,
+      dedupKey: "valid-1",
+    });
+    await emitFeedEvent({
+      source: "calendar",
+      title: "No expiry",
+      summary: "Should also appear.",
+      dedupKey: "no-expiry-1",
+    });
+
+    const feed = readHomeFeed();
+    expect(feed.items).toHaveLength(2);
+
+    const titles = feed.items.map((i) => i.title);
+    expect(titles).toContain("Still valid");
+    expect(titles).toContain("No expiry");
+    expect(titles).not.toContain("Expired item");
+  });
+
+  test("dedup: two items with the same dedupKey produce only one entry", async () => {
+    await emitFeedEvent({
+      source: "gmail",
+      title: "First version",
+      summary: "Original summary.",
+      dedupKey: "shared-key",
+    });
+    await emitFeedEvent({
+      source: "gmail",
+      title: "Second version",
+      summary: "Updated summary.",
+      dedupKey: "shared-key",
+    });
+
+    const feed = readHomeFeed();
+    const matching = feed.items.filter((i) => i.id === "emit:gmail:shared-key");
+    expect(matching).toHaveLength(1);
+    expect(matching[0]!.title).toBe("Second version");
+    expect(matching[0]!.summary).toBe("Updated summary.");
+  });
+
+  test("dedup works across reads — no phantom duplicates", async () => {
+    await emitFeedEvent({
+      source: "assistant",
+      title: "Version 1",
+      summary: "First emit.",
+      dedupKey: "cross-read",
+    });
+
+    // Read once to confirm the item is there.
+    const feed1 = readHomeFeed();
+    expect(
+      feed1.items.filter((i) => i.id === "emit:assistant:cross-read"),
+    ).toHaveLength(1);
+
+    // Emit again with the same dedupKey.
+    await emitFeedEvent({
+      source: "assistant",
+      title: "Version 2",
+      summary: "Second emit.",
+      dedupKey: "cross-read",
+    });
+
+    const feed2 = readHomeFeed();
+    const matching = feed2.items.filter(
+      (i) => i.id === "emit:assistant:cross-read",
+    );
+    expect(matching).toHaveLength(1);
+    expect(matching[0]!.title).toBe("Version 2");
+  });
+
+  test("mixed priorities and urgencies sort correctly", async () => {
+    const events: Array<{
+      source: FeedItemSource;
+      title: string;
+      priority: number;
+      dedupKey: string;
+    }> = [
+      {
+        source: "gmail",
+        title: "Low priority gmail",
+        priority: 10,
+        dedupKey: "g-low",
+      },
+      {
+        source: "slack",
+        title: "High priority slack",
+        priority: 95,
+        dedupKey: "s-high",
+      },
+      {
+        source: "calendar",
+        title: "Mid priority calendar",
+        priority: 50,
+        dedupKey: "c-mid",
+      },
+      {
+        source: "assistant",
+        title: "High priority assistant",
+        priority: 95,
+        dedupKey: "a-high",
+      },
+      {
+        source: "gmail",
+        title: "Mid priority gmail",
+        priority: 50,
+        dedupKey: "g-mid",
+      },
+      {
+        source: "slack",
+        title: "Low priority slack",
+        priority: 20,
+        dedupKey: "s-low",
+      },
+    ];
+
+    for (const e of events) {
+      await emitFeedEvent({
+        source: e.source,
+        title: e.title,
+        summary: `Summary for ${e.title}`,
+        priority: e.priority,
+        dedupKey: e.dedupKey,
+      });
+    }
+
+    const feed = readHomeFeed();
+    expect(feed.items).toHaveLength(6);
+
+    // Verify descending priority order.
+    const priorities = feed.items.map((i) => i.priority);
+    for (let i = 1; i < priorities.length; i++) {
+      expect(priorities[i - 1]!).toBeGreaterThanOrEqual(priorities[i]!);
+    }
+  });
+});

package/src/home/emit-feed-event.ts

@@ -41,6 +41,7 @@ import { randomUUID } from "node:crypto";
 import {
   type FeedAction,
   type FeedItem,
+  type FeedItemDetailPanel,
   feedItemSchema,
   type FeedItemSource,
   type FeedItemUrgency,
@@ -96,6 +97,10 @@ export interface EmitFeedEventParams {
   expiresAt?: string;
   /** Visual urgency treatment — controls badge color independently of sort priority. */
   urgency?: FeedItemUrgency;
+  /** Optional conversation this feed item is associated with. */
+  conversationId?: string;
+  /** Server-driven detail panel descriptor; when present, the client opens this panel kind. */
+  detailPanel?: FeedItemDetailPanel;
 }
 
 /**
@@ -148,6 +153,8 @@ export async function emitFeedEvent(
     createdAt: now,
     actions: params.actions,
     urgency: params.urgency,
+    conversationId: params.conversationId,
+    detailPanel: params.detailPanel,
     minTimeAway: params.minTimeAway,
     expiresAt: params.expiresAt,
   };

package/src/home/feed-types.ts

@@ -34,7 +34,12 @@ export type FeedItemStatus = "new" | "seen" | "acted_on" | "dismissed";
  * stays exhaustive. Future sources will be added explicitly rather
  * than letting arbitrary strings slip through.
  */
-export type FeedItemSource = "gmail" | "slack" | "calendar" | "assistant";
+export type FeedItemSource =
+  | "gmail"
+  | "slack"
+  | "calendar"
+  | "assistant"
+  | "telegram";
 
 /**
  * Internal field used by the hybrid authoring resolver (PR 5 writer).
@@ -62,6 +67,20 @@ export interface FeedAction {
   prompt: string;
 }
 
+/** Which detail panel the macOS client should open for this feed item. */
+export type FeedItemDetailPanelKind =
+  | "emailDraft"
+  | "documentPreview"
+  | "permissionChat"
+  | "paymentAuth"
+  | "toolPermission"
+  | "updatesList";
+
+/** Server-driven detail panel descriptor attached to a feed item. */
+export interface FeedItemDetailPanel {
+  kind: FeedItemDetailPanelKind;
+}
+
 /**
  * A single item rendered in the Home feed.
  *
@@ -81,7 +100,7 @@ export interface FeedItem {
   priority: number;
   title: string;
   summary: string;
-  /** Optional; when present must be one of the four v1 sources. */
+  /** Optional; when present must be one of the v1 sources. */
   source?: FeedItemSource;
   /** Event time (ISO-8601). */
   timestamp: string;
@@ -94,6 +113,10 @@ export interface FeedItem {
   actions?: FeedAction[];
   /** Visual urgency treatment — controls badge color independently of sort priority. */
   urgency?: FeedItemUrgency;
+  /** Optional conversation this feed item is associated with. */
+  conversationId?: string;
+  /** Server-driven detail panel descriptor; when present, the client opens this panel kind. */
+  detailPanel?: FeedItemDetailPanel;
   /** Internal: who authored this item. */
   author: FeedItemAuthor;
   /** Internal: ISO-8601 writer-record time, used for ordering + TTL. */
@@ -157,6 +180,7 @@ const feedItemSourceSchema = z.enum([
   "slack",
   "calendar",
   "assistant",
+  "telegram",
 ]);
 
 const feedItemAuthorSchema = z.enum(["assistant", "platform"]);
@@ -169,6 +193,19 @@ const feedActionSchema = z.object({
   prompt: z.string(),
 });
 
+const feedItemDetailPanelKindSchema = z.enum([
+  "emailDraft",
+  "documentPreview",
+  "permissionChat",
+  "paymentAuth",
+  "toolPermission",
+  "updatesList",
+]);
+
+const feedItemDetailPanelSchema = z.object({
+  kind: feedItemDetailPanelKindSchema,
+});
+
 /**
  * Schema for a single `FeedItem`.
  *
@@ -196,6 +233,8 @@ export const feedItemSchema = z.object({
   minTimeAway: z.number().int().min(0).optional(),
   actions: z.array(feedActionSchema).optional(),
   urgency: feedItemUrgencySchema.optional(),
+  conversationId: z.string().optional(),
+  detailPanel: feedItemDetailPanelSchema.optional(),
   author: feedItemAuthorSchema,
   createdAt: z.string(),
 });

package/src/home/rewrite-command-preview.ts

@@ -0,0 +1,66 @@
+import { getConfiguredProvider } from "../providers/provider-send-message.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("command-preview-rewriter");
+const REWRITE_TIMEOUT_MS = 3000;
+const REWRITE_MAX_TOKENS = 100;
+
+const SYSTEM_PROMPT = `You rewrite technical computer commands into simple, human-readable descriptions.
+Output ONLY the rewritten description — no quotes, no explanation, no preamble.
+Keep it under 15 words. Use plain language a non-technical person would understand.
+Examples:
+- "ls -la ~/Desktop" → "View files on the desktop"
+- "cat ~/.bashrc" → "Read shell configuration file"
+- "rm -rf /tmp/cache" → "Delete temporary cache files"
+- "grep -r 'password' ." → "Search files for the word 'password'"
+- "curl https://api.example.com/users" → "Fetch user data from an API"`;
+
+export async function rewriteCommandPreview(
+  toolName: string,
+  commandPreview: string,
+): Promise<string | null> {
+  try {
+    const provider = await getConfiguredProvider("feedEventCopy");
+    if (!provider) return null;
+
+    const response = await provider.sendMessage(
+      [
+        {
+          role: "user",
+          content: [
+            {
+              type: "text",
+              text: `Tool: ${toolName}\nCommand: ${commandPreview}`,
+            },
+          ],
+        },
+      ],
+      [],
+      SYSTEM_PROMPT,
+      {
+        config: {
+          max_tokens: REWRITE_MAX_TOKENS,
+          callSite: "feedEventCopy",
+        },
+        signal: AbortSignal.timeout(REWRITE_TIMEOUT_MS),
+      },
+    );
+
+    const block = response.content.find((entry) => entry.type === "text");
+    const text =
+      block && "text" in block ? (block as { text: string }).text.trim() : "";
+    if (!text) return null;
+    return (
+      text
+        .replace(/^["'`]+/, "")
+        .replace(/["'`]+$/, "")
+        .trim() || null
+    );
+  } catch (err) {
+    log.warn(
+      { err, toolName, commandPreview },
+      "Command preview rewrite failed",
+    );
+    return null;
+  }
+}