@vellumai/assistant 0.8.2 → 0.8.3

package/src/export/transcript-formatter.ts

@@ -5,6 +5,7 @@
  * subagent conversation sections when present in message metadata.
  */
 
+import { formatLocalTimestamp } from "../daemon/date-context.js";
 import {
   getConversation,
   getMessages,
@@ -23,10 +24,6 @@ interface ContentBlock {
   source?: { media_type?: string; filename?: string };
 }
 
-function formatTimestamp(ms: number): string {
-  return new Date(ms).toISOString().replace("T", " ").slice(0, 19);
-}
-
 function extractAnalysisText(blocks: ContentBlock[]): string {
   const parts: string[] = [];
   for (const block of blocks) {
@@ -67,15 +64,36 @@ function extractAnalysisText(blocks: ContentBlock[]): string {
   return parts.join("\n");
 }
 
-function formatRole(role: string): string {
-  return role === "user" ? "User" : "Assistant";
+export interface TranscriptFormatOptions {
+  timeZone?: string;
+  assistantName?: string | null;
+  userName?: string | null;
+}
+
+function resolveName(
+  name: string | null | undefined,
+  fallback: string,
+): string {
+  return name && name.length > 0 ? name : fallback;
+}
+
+function formatRole(
+  role: string,
+  options: TranscriptFormatOptions = {},
+): string {
+  return role === "user"
+    ? resolveName(options.userName, "User")
+    : resolveName(options.assistantName, "Assistant");
 }
 
-function formatSubagentMessages(msgs: ReturnType<typeof getMessages>): string {
+function formatSubagentMessages(
+  msgs: ReturnType<typeof getMessages>,
+  options: TranscriptFormatOptions = {},
+): string {
   const lines: string[] = [];
   for (const msg of msgs) {
-    const role = formatRole(msg.role);
-    const time = formatTimestamp(msg.createdAt);
+    const role = formatRole(msg.role, options);
+    const time = formatLocalTimestamp(msg.createdAt, options.timeZone);
     const content = parseContent(msg.content);
     const text = extractAnalysisText(content);
     if (text) {
@@ -103,24 +121,33 @@ 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.
+ * last successful run rather than the whole conversation. The per-message
+ * structural shape matches `buildAnalysisTranscript` (header line, body,
+ * optional subagent block) so downstream agents see consistent framing.
+ * The participant *labels*, however, intentionally diverge: this function
+ * honors `TranscriptFormatOptions` so the memory-retrospective prompt can
+ * render the conversation under the assistant and user display names,
+ * while `buildAnalysisTranscript` always uses generic "User"/"Assistant"
+ * labels for the analyze-conversation flow.
  */
 export function formatMessageSliceForTranscript(
   messages: TranscriptMessage[],
+  options: TranscriptFormatOptions = {},
 ): string {
   const lines: string[] = [];
   for (const msg of messages) {
-    appendMessageBlock(lines, msg);
+    appendMessageBlock(lines, msg, options);
   }
   return lines.join("\n");
 }
 
-function appendMessageBlock(lines: string[], msg: TranscriptMessage): void {
-  const role = formatRole(msg.role);
-  const time = formatTimestamp(msg.createdAt);
+function appendMessageBlock(
+  lines: string[],
+  msg: TranscriptMessage,
+  options: TranscriptFormatOptions = {},
+): void {
+  const role = formatRole(msg.role, options);
+  const time = formatLocalTimestamp(msg.createdAt, options.timeZone);
   const content = parseContent(msg.content);
   const text = extractAnalysisText(content);
 
@@ -142,7 +169,14 @@ function appendMessageBlock(lines: string[], msg: TranscriptMessage): void {
           const subMessages = getMessages(notif.conversationId);
           lines.push(`### Subagent: ${notif.label} (${notif.status})`);
           lines.push("");
-          lines.push(formatSubagentMessages(subMessages));
+          // Subagent conversations persist the parent assistant's objective
+          // as a `user` message (see subagent/manager.ts), so reusing the
+          // parent's display-name options would render the assistant's
+          // tasking text under the human user's name. Keep child transcripts
+          // on generic role labels — and only pass through the time zone.
+          lines.push(
+            formatSubagentMessages(subMessages, { timeZone: options.timeZone }),
+          );
           lines.push("");
         }
       }
@@ -163,12 +197,12 @@ export function buildAnalysisTranscript(conversationId: string): string {
   const lines: string[] = [];
 
   lines.push(`# Conversation: ${title}`);
-  lines.push(`Created: ${formatTimestamp(conversation.createdAt)}`);
+  lines.push(`Created: ${formatLocalTimestamp(conversation.createdAt)}`);
   lines.push("");
 
   for (const msg of allMessages) {
     const role = formatRole(msg.role);
-    const time = formatTimestamp(msg.createdAt);
+    const time = formatLocalTimestamp(msg.createdAt);
     const content = parseContent(msg.content);
     const text = extractAnalysisText(content);
 

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

@@ -55,6 +55,7 @@ const stubConfig: {
     activeHoursStart: number | null;
     activeHoursEnd: number | null;
     maxConsecutiveRuns: number | null;
+    disposition: string;
   };
 } = {
   heartbeat: {
@@ -63,6 +64,7 @@ const stubConfig: {
     activeHoursStart: null,
     activeHoursEnd: null,
     maxConsecutiveRuns: null,
+    disposition: "Default disposition text.",
   },
 };
 mock.module("../../config/loader.js", () => ({
@@ -395,6 +397,48 @@ describe("HeartbeatService", () => {
       }
     });
 
+    test("resetTimer() during an in-flight run is not undone by that run's increment", async () => {
+      // Regression: if a guardian message arrives mid-run, `resetTimer()`
+      // zeroes the counter but the in-flight run's `finally` block used to
+      // unconditionally `_consecutiveRuns++`, leaving the counter at 1 and
+      // tripping the cap-at-1 path one auto run too early.
+      stubConfig.heartbeat.maxConsecutiveRuns = 1;
+
+      let releaseInflight: () => void = () => {};
+      const inflight = new Promise<void>((resolve) => {
+        releaseInflight = resolve;
+      });
+      runBackgroundJobImpl = async () => {
+        await inflight;
+        return { conversationId: STUB_CONVERSATION_ID, ok: true };
+      };
+
+      const service = new HeartbeatService({ alerter: () => {} });
+      service.start();
+      try {
+        const runPromise = service.runOnce({ force: false });
+        // Guardian message arrives while the run is still executing.
+        service.resetTimer();
+        releaseInflight();
+        expect(await runPromise).toBe(true);
+
+        // The reset during the in-flight run must survive: the next auto run
+        // should proceed because the counter is still 0, not 1.
+        runBackgroundJobImpl = async () => ({
+          conversationId: STUB_CONVERSATION_ID,
+          ok: true,
+        });
+        expect(await service.runOnce({ force: false })).toBe(true);
+        expect(
+          skipHeartbeatRunCalls.some(
+            (c) => c.reason === "max_consecutive_runs",
+          ),
+        ).toBe(false);
+      } finally {
+        await service.stop();
+      }
+    });
+
     test("null disables the cap entirely", async () => {
       stubConfig.heartbeat.maxConsecutiveRuns = null;
       const service = new HeartbeatService({ alerter: () => {} });

package/src/heartbeat/heartbeat-service.ts

@@ -9,8 +9,6 @@ import {
   shouldLogDiskPressureBackgroundSkip,
 } from "../daemon/disk-pressure-background-gate.js";
 import type { HeartbeatAlert } from "../daemon/message-protocol.js";
-import { getConversation, getMessages } from "../memory/conversation-crud.js";
-import { GENERATING_TITLE } from "../memory/conversation-title-service.js";
 import { emitNotificationSignal } from "../notifications/emit-signal.js";
 import {
   GUARDIAN_PERSONA_TEMPLATE,
@@ -47,9 +45,6 @@ const DEFAULT_CHECKLIST = `- Check in with yourself. Read NOW.md. Is it still ac
 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
@@ -102,69 +97,6 @@ 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: {
@@ -202,6 +134,9 @@ export class HeartbeatService {
   // Reset by resetTimer (guardian message), reconfigure, and stop. Force runs
   // bypass the cap and do not increment.
   private _consecutiveRuns = 0;
+  // Bumped every time the counter is reset so an in-flight run that finishes
+  // after a guardian message can detect the reset and skip its increment.
+  private _resetGeneration = 0;
 
   constructor(deps: HeartbeatDeps) {
     this.deps = deps;
@@ -360,6 +295,7 @@ export class HeartbeatService {
   /** Restart the timer with the latest config (e.g. after settings change). */
   reconfigure(): void {
     this._consecutiveRuns = 0;
+    this._resetGeneration++;
     this.configEpoch++;
     if (this._pendingRunId) {
       supersedePendingRun(this._pendingRunId);
@@ -384,6 +320,7 @@ export class HeartbeatService {
     // Counter resets even when the timer is null so a guardian message during
     // a stopped window still clears the count.
     this._consecutiveRuns = 0;
+    this._resetGeneration++;
     if (!this.timer) return;
     if (this.cronMode) {
       clearTimeout(this.timer as ReturnType<typeof setTimeout>);
@@ -404,6 +341,7 @@ export class HeartbeatService {
 
   async stop(): Promise<void> {
     this._consecutiveRuns = 0;
+    this._resetGeneration++;
     this.stopped = true;
     if (this.timer) {
       clearTimeout(this.timer as ReturnType<typeof setTimeout>);
@@ -552,6 +490,11 @@ export class HeartbeatService {
     }
     const run = this.executeRun(runId, scheduledFor);
     this.activeRun = run;
+    // Snapshot the reset generation so we can detect whether a reset (guardian
+    // message, reconfigure, stop) happened while this run was in flight. If it
+    // did, the counter was already zeroed and we must not undo that reset by
+    // incrementing in `finally`.
+    const startGeneration = this._resetGeneration;
     try {
       await run;
     } catch (err) {
@@ -561,7 +504,7 @@ export class HeartbeatService {
         this.activeRun = null;
       }
       this._lastRunAt = Date.now();
-      if (!force) {
+      if (!force && this._resetGeneration === startGeneration) {
         this._consecutiveRuns++;
       }
       if (!this.cronMode) {
@@ -699,66 +642,6 @@ 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",
-        conversationType: "background",
-      },
-    });
-  }
-
   private async executeRun(runId: string, scheduledFor: number): Promise<void> {
     log.info("Running heartbeat");
 
@@ -787,9 +670,9 @@ export class HeartbeatService {
     // The runner fires `onConversationCreated` synchronously after
     // bootstrap so the macOS sidebar gets the new conversation
     // immediately rather than waiting up to HEARTBEAT_TIMEOUT_MS for
-    // the LLM turn to finish. We forward to `deps.onConversationCreated`
-    // for every run; "silent OK" is enforced by NOT emitting any
-    // notification signal further down, not by hiding the conversation.
+    // the LLM turn to finish. If the model judges the run worth
+    // surfacing to the guardian, it calls the `notifications` skill
+    // directly — no in-band marker.
     let conversationId: string | undefined;
     const result = await runBackgroundJob({
       jobName: "heartbeat",
@@ -821,62 +704,26 @@ export class HeartbeatService {
         "Heartbeat completed",
       );
 
-      // Mark the run record as ok and surface any disposition-driven
-      // alert the assistant decided to raise. The runner owns failure
-      // emission via `activity.failed`; success-side surfacing (alerts,
-      // late warnings) lives here so it can read the actual conversation
-      // contents.
+      // Mark the run record as ok. The runner owns failure emission via
+      // `activity.failed`; any user-facing alert the model decided to
+      // raise was emitted in-band via the `notifications` skill during
+      // the turn itself.
       const transitioned = completeHeartbeatRun(runId, {
         status: "ok",
         conversationId: result.conversationId,
       });
 
-      if (transitioned) {
-        let title = "Heartbeat";
-        try {
-          const row = getConversation(result.conversationId);
-          if (row?.title && row.title !== GENERATING_TITLE) {
-            title = row.title;
-          }
-        } catch {
-          // Best-effort; fall back to generic title.
-        }
-
-        const assistantMessage = this.getLatestAssistantMessage(
-          result.conversationId,
-        );
-        const disposition = parseHeartbeatDisposition(
-          assistantMessage?.text ?? null,
-        );
-        if (disposition === "alert") {
-          // Conversation was already surfaced via the runner's bootstrap
-          // callback above; alert just needs to emit the notification.
-          void this.emitHeartbeatAlertNotification({
+      if (transitioned && latenessMs > LATE_THRESHOLD_MS) {
+        const lateMinutes = Math.round(latenessMs / 60_000);
+        log.warn(
+          {
+            latenessMs,
+            lateMinutes,
+            scheduledFor,
             runId,
-            conversationId: result.conversationId,
-            messageId: assistantMessage?.id,
-            conversationTitle: title,
-            summary: buildHeartbeatAlertSummary(assistantMessage?.text ?? null),
-          }).catch((err) => {
-            log.warn(
-              { err, conversationId: result.conversationId },
-              "Failed to emit heartbeat alert notification",
-            );
-          });
-        }
-
-        if (latenessMs > LATE_THRESHOLD_MS) {
-          const lateMinutes = Math.round(latenessMs / 60_000);
-          log.warn(
-            {
-              latenessMs,
-              lateMinutes,
-              scheduledFor,
-              runId,
-            },
-            "Heartbeat ran late",
-          );
-        }
+          },
+          "Heartbeat ran late",
+        );
       }
       return;
     }
@@ -941,18 +788,14 @@ Do NOT attempt to use tools for these providers — they will fail. Skip any che
 </credential-status>`;
     }
 
-    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>`;
+    const disposition = getConfig().heartbeat.disposition;
+    if (disposition) {
+      prompt += `\n\n<heartbeat-disposition>\n${disposition}\n</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.
+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 surfacing it via the notifications skill this time. First impressions matter.
 </early-heartbeat>`;
     }
 

package/src/home/__tests__/feed-types.test.ts

@@ -116,6 +116,28 @@ describe("feedItemSchema — valid minimal items", () => {
     expect(parsed.category).toBeUndefined();
     expect(parsed.metadata).toBeUndefined();
   });
+
+  test("noteworthy field passes through when present", () => {
+    const parsed = feedItemSchema.parse({
+      ...minimalNotification(),
+      noteworthy: true,
+    });
+    expect(parsed.noteworthy).toBe(true);
+  });
+
+  test("items without noteworthy field still parse (backward compat)", () => {
+    const parsed = feedItemSchema.parse(minimalNotification());
+    expect(parsed.noteworthy).toBeUndefined();
+  });
+
+  test("title is optional and may be omitted", () => {
+    const { title: _omitted, ...rest } = minimalNotification();
+    const parsed = feedItemSchema.parse(rest);
+    expect(parsed.title).toBeUndefined();
+    expect(parsed.summary).toBe(
+      "You mentioned wanting to review the onboarding designs.",
+    );
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -244,4 +266,22 @@ describe("parseFeedFile", () => {
       }),
     ).toThrow();
   });
+
+  test("accepts a file with a noteworthy item", () => {
+    const parsed = parseFeedFile({
+      version: 2,
+      items: [{ ...minimalNotification(), noteworthy: true }],
+      updatedAt: NOW_ISO,
+    });
+    expect(parsed.items[0]?.noteworthy).toBe(true);
+  });
+
+  test("accepts a file whose items omit noteworthy (backward compat)", () => {
+    const parsed = parseFeedFile({
+      version: 2,
+      items: [minimalNotification()],
+      updatedAt: NOW_ISO,
+    });
+    expect(parsed.items[0]?.noteworthy).toBeUndefined();
+  });
 });

package/src/home/feed-types.ts

@@ -89,7 +89,13 @@ export interface FeedItem {
   type: FeedItemType;
   /** Integer in [0, 100]; higher values sort earlier. */
   priority: number;
-  title: string;
+  /**
+   * Optional short header. Omit when the source did not supply one — the
+   * notification pipeline never manufactures a title from rendered copy
+   * (LLM-echoed bodies stutter against `summary`). Clients fall back to
+   * `summary` when rendering a row.
+   */
+  title?: string;
   summary: string;
   /** Event time (ISO-8601). */
   timestamp: string;
@@ -106,6 +112,10 @@ export interface FeedItem {
   detailPanel?: FeedItemDetailPanel;
   /** Broad category for grouping and filtering feed items. */
   category?: FeedItemCategory;
+  /** True when this item represents an assistant-initiated share or a high-importance system event. Used by clients to split inbox vs activity surfaces. */
+  noteworthy?: boolean;
+  /** True when the assistant herself emitted this item (e.g. via the `notifications send` skill). Drives clients to swap the row's leading icon for the persona avatar; system-generated items keep the category icon. */
+  fromAssistant?: boolean;
   /** Arbitrary structured data the detail panel or other consumers can use. */
   metadata?: Record<string, unknown>;
   /** Internal: ISO-8601 writer-record time, used for ordering + TTL. */
@@ -198,7 +208,7 @@ export const feedItemSchema = z.object({
   id: z.string(),
   type: feedItemTypeSchema,
   priority: z.number().int().min(0).max(100),
-  title: z.string(),
+  title: z.string().optional(),
   summary: z.string(),
   timestamp: z.string(),
   status: feedItemStatusSchema.default("new"),
@@ -208,6 +218,8 @@ export const feedItemSchema = z.object({
   conversationId: z.string().optional(),
   detailPanel: feedItemDetailPanelSchema.optional(),
   category: feedItemCategorySchema.optional(),
+  noteworthy: z.boolean().optional(),
+  fromAssistant: z.boolean().optional(),
   metadata: z.record(z.string(), z.unknown()).optional(),
   createdAt: z.string(),
 });