@vellumai/assistant 0.9.0-dev.202606180940.f141ea3 → 0.9.0-dev.202606181130.57d4082

package/openapi.yaml

@@ -12116,6 +12116,19 @@ paths:
                           propertyNames:
                             type: string
                           additionalProperties: {}
+                        sourceType:
+                          type: string
+                          enum:
+                            - heartbeat
+                            - memory_consolidation
+                            - schedule
+                            - auto_analysis
+                            - user
+                            - other
+                        sourceKey:
+                          type: string
+                        sourceLabel:
+                          type: string
                         createdAt:
                           type: string
                       required:
@@ -12296,6 +12309,19 @@ paths:
                     propertyNames:
                       type: string
                     additionalProperties: {}
+                  sourceType:
+                    type: string
+                    enum:
+                      - heartbeat
+                      - memory_consolidation
+                      - schedule
+                      - auto_analysis
+                      - user
+                      - other
+                  sourceKey:
+                    type: string
+                  sourceLabel:
+                    type: string
                   createdAt:
                     type: string
                 required:
@@ -12508,6 +12534,19 @@ paths:
                           propertyNames:
                             type: string
                           additionalProperties: {}
+                        sourceType:
+                          type: string
+                          enum:
+                            - heartbeat
+                            - memory_consolidation
+                            - schedule
+                            - auto_analysis
+                            - user
+                            - other
+                        sourceKey:
+                          type: string
+                        sourceLabel:
+                          type: string
                         createdAt:
                           type: string
                       required:
@@ -17936,6 +17975,19 @@ paths:
                         propertyNames:
                           type: string
                         additionalProperties: {}
+                      sourceType:
+                        type: string
+                        enum:
+                          - heartbeat
+                          - memory_consolidation
+                          - schedule
+                          - auto_analysis
+                          - user
+                          - other
+                      sourceKey:
+                        type: string
+                      sourceLabel:
+                        type: string
                       createdAt:
                         type: string
                     required:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.9.0-dev.202606180940.f141ea3",
+  "version": "0.9.0-dev.202606181130.57d4082",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/api/index.ts

@@ -385,6 +385,8 @@ export {
   FeedItemDetailPanelKindSchema,
   FeedItemDetailPanelSchema,
   FeedItemSchema,
+  type FeedItemSourceType,
+  FeedItemSourceTypeSchema,
   type FeedItemStatus,
   FeedItemStatusSchema,
   type FeedItemType,

package/src/api/responses/home.ts

@@ -55,6 +55,25 @@ export const FeedItemCategorySchema = z.enum([
 ]);
 export type FeedItemCategory = z.infer<typeof FeedItemCategorySchema>;
 
+/**
+ * Producer of a feed item's source conversation — lets clients filter the
+ * activity feed by what generated each notification: the periodic
+ * heartbeat, a memory-consolidation pass, a recurring schedule, an
+ * auto-analysis run, etc. Derived at read time from the source
+ * conversation's `source` column (see `home/feed-source-enrichment.ts`).
+ * Individual schedules are distinguished by `sourceKey`/`sourceLabel`, not
+ * this coarse type.
+ */
+export const FeedItemSourceTypeSchema = z.enum([
+  "heartbeat",
+  "memory_consolidation",
+  "schedule",
+  "auto_analysis",
+  "user",
+  "other",
+]);
+export type FeedItemSourceType = z.infer<typeof FeedItemSourceTypeSchema>;
+
 /**
  * A single action button attached to a feed item.
  *
@@ -120,6 +139,13 @@ export const FeedItemSchema = z.object({
   noteworthy: z.boolean().optional(),
   fromAssistant: z.boolean().optional(),
   metadata: z.record(z.string(), z.unknown()).optional(),
+  // Source-conversation classification, enriched at read time. `sourceKey`
+  // is the stable filter id — `schedule:<id>` for schedules so each filters
+  // separately, otherwise the `sourceType`. `sourceLabel` is the display
+  // string (a schedule's name, or a static label like "Heartbeat").
+  sourceType: FeedItemSourceTypeSchema.optional(),
+  sourceKey: z.string().optional(),
+  sourceLabel: z.string().optional(),
   createdAt: z.string(),
 });
 export type FeedItem = z.infer<typeof FeedItemSchema>;

package/src/home/feed-source-enrichment.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it } from "bun:test";
+
+import { type FeedItem } from "../api/responses/home.js";
+import {
+  classifyConversationSource,
+  enrichFeedItemsWithSource,
+  type FeedSourceEnrichmentDeps,
+} from "./feed-source-enrichment.js";
+
+function makeItem(partial: Partial<FeedItem> & Pick<FeedItem, "id">): FeedItem {
+  return {
+    type: "notification",
+    priority: 50,
+    summary: "summary",
+    timestamp: "2026-06-18T00:00:00.000Z",
+    createdAt: "2026-06-18T00:00:00.000Z",
+    status: "new",
+    ...partial,
+  };
+}
+
+describe("classifyConversationSource", () => {
+  it("maps each known producer source to its coarse type", () => {
+    expect(classifyConversationSource("heartbeat")).toBe("heartbeat");
+    expect(classifyConversationSource("memory-retrospective")).toBe(
+      "memory_consolidation",
+    );
+    expect(classifyConversationSource("memory-retrospective-fork")).toBe(
+      "memory_consolidation",
+    );
+    expect(classifyConversationSource("schedule")).toBe("schedule");
+    expect(classifyConversationSource("auto-analysis")).toBe("auto_analysis");
+    expect(classifyConversationSource("user")).toBe("user");
+    expect(classifyConversationSource("home-feed")).toBe("user");
+  });
+
+  it("falls through to 'other' for unknown / paired-delivery / empty sources", () => {
+    expect(classifyConversationSource("notification")).toBe("other");
+    expect(classifyConversationSource("something-else")).toBe("other");
+    expect(classifyConversationSource(null)).toBe("other");
+    expect(classifyConversationSource(undefined)).toBe("other");
+  });
+});
+
+describe("enrichFeedItemsWithSource", () => {
+  const deps = (
+    conv: Record<string, { source: string; scheduleJobId: string | null }>,
+    schedules: Record<string, string> = {},
+  ): FeedSourceEnrichmentDeps => ({
+    getConversationRow: (id) => conv[id] ?? null,
+    getScheduleName: (id) => schedules[id] ?? null,
+  });
+
+  it("classifies a heartbeat item with a static label", () => {
+    const [item] = enrichFeedItemsWithSource(
+      [makeItem({ id: "n1", conversationId: "c1" })],
+      deps({ c1: { source: "heartbeat", scheduleJobId: null } }),
+    );
+    expect(item.sourceType).toBe("heartbeat");
+    expect(item.sourceKey).toBe("heartbeat");
+    expect(item.sourceLabel).toBe("Heartbeat");
+  });
+
+  it("classifies a memory-consolidation item", () => {
+    const [item] = enrichFeedItemsWithSource(
+      [makeItem({ id: "n2", conversationId: "c2" })],
+      deps({ c2: { source: "memory-retrospective", scheduleJobId: null } }),
+    );
+    expect(item.sourceType).toBe("memory_consolidation");
+    expect(item.sourceKey).toBe("memory_consolidation");
+    expect(item.sourceLabel).toBe("Memory consolidation");
+  });
+
+  it("gives distinct keys and names to two different schedules", () => {
+    const [a, b] = enrichFeedItemsWithSource(
+      [
+        makeItem({ id: "n3", conversationId: "cA" }),
+        makeItem({ id: "n4", conversationId: "cB" }),
+      ],
+      deps(
+        {
+          cA: { source: "schedule", scheduleJobId: "sched-A" },
+          cB: { source: "schedule", scheduleJobId: "sched-B" },
+        },
+        { "sched-A": "Morning digest", "sched-B": "Evening recap" },
+      ),
+    );
+    expect(a.sourceType).toBe("schedule");
+    expect(a.sourceKey).toBe("schedule:sched-A");
+    expect(a.sourceLabel).toBe("Morning digest");
+    // scheduleId recovered from the conversation row is surfaced in metadata.
+    expect(a.metadata?.scheduleId).toBe("sched-A");
+
+    expect(b.sourceKey).toBe("schedule:sched-B");
+    expect(b.sourceLabel).toBe("Evening recap");
+  });
+
+  it("prefers an explicit metadata.scheduleId over the conversation row", () => {
+    const [item] = enrichFeedItemsWithSource(
+      [
+        makeItem({
+          id: "n5",
+          conversationId: "cX",
+          metadata: { scheduleId: "from-payload" },
+        }),
+      ],
+      deps(
+        { cX: { source: "schedule", scheduleJobId: "from-row" } },
+        { "from-payload": "Payload schedule" },
+      ),
+    );
+    expect(item.sourceKey).toBe("schedule:from-payload");
+    expect(item.sourceLabel).toBe("Payload schedule");
+  });
+
+  it("labels a schedule with no resolvable name as 'Scheduled'", () => {
+    const [item] = enrichFeedItemsWithSource(
+      [makeItem({ id: "n6", conversationId: "cY" })],
+      deps({ cY: { source: "schedule", scheduleJobId: "gone" } }),
+    );
+    expect(item.sourceKey).toBe("schedule:gone");
+    expect(item.sourceLabel).toBe("Scheduled");
+  });
+
+  it("classifies items with no source conversation as 'other'", () => {
+    const [item] = enrichFeedItemsWithSource(
+      [makeItem({ id: "n7" })],
+      deps({}),
+    );
+    expect(item.sourceType).toBe("other");
+    expect(item.sourceKey).toBe("other");
+    expect(item.sourceLabel).toBe("Other");
+  });
+
+  it("resolves each distinct conversation at most once", () => {
+    const calls: string[] = [];
+    enrichFeedItemsWithSource(
+      [
+        makeItem({ id: "n8", conversationId: "dup" }),
+        makeItem({ id: "n9", conversationId: "dup" }),
+      ],
+      {
+        getConversationRow: (id) => {
+          calls.push(id);
+          return { source: "heartbeat", scheduleJobId: null };
+        },
+      },
+    );
+    expect(calls).toEqual(["dup"]);
+  });
+});

package/src/home/feed-source-enrichment.ts

@@ -0,0 +1,176 @@
+/**
+ * Read-time enrichment of home-feed items with their source-conversation
+ * classification.
+ *
+ * The activity feed surfaces notifications produced by many background
+ * flows — the periodic heartbeat, memory-consolidation passes, each
+ * recurring schedule, auto-analysis runs, etc. Clients let the user filter
+ * the feed by that producer, so every item is tagged with:
+ *
+ *   - `sourceType`  — coarse producer category.
+ *   - `sourceKey`   — stable filter id (`schedule:<id>` per schedule,
+ *                     otherwise the `sourceType`).
+ *   - `sourceLabel` — human-readable display (a schedule's name, or a
+ *                     static label such as "Heartbeat").
+ *
+ * The classification is derived from the source conversation's `source`
+ * column (and, for schedules, its name) rather than persisted onto the
+ * feed item. Resolving at read time keeps labels fresh across schedule
+ * renames and retroactively classifies items written before this feature
+ * existed, with no migration.
+ *
+ * The lookups are injectable so the enrichment can be unit-tested without
+ * a live database; production callers use the defaults.
+ */
+
+import {
+  type FeedItem,
+  type FeedItemSourceType,
+} from "../api/responses/home.js";
+import { AUTO_ANALYSIS_SOURCE } from "../memory/auto-analysis-constants.js";
+import { getConversation } from "../memory/conversation-crud.js";
+import {
+  MEMORY_RETROSPECTIVE_FORK_SOURCE,
+  MEMORY_RETROSPECTIVE_SOURCE,
+} from "../memory/memory-retrospective-constants.js";
+import { getSchedule } from "../schedule/schedule-store.js";
+
+/** Minimal source-conversation shape the enrichment needs. */
+interface ConversationSourceRow {
+  source: string;
+  scheduleJobId: string | null;
+}
+
+export interface FeedSourceEnrichmentDeps {
+  /** Resolve the source columns for a conversation, or null when missing. */
+  getConversationRow?: (id: string) => ConversationSourceRow | null;
+  /** Resolve a schedule's display name, or null when missing. */
+  getScheduleName?: (id: string) => string | null;
+}
+
+/**
+ * Map a conversation's `source` column to a coarse feed source type.
+ * Mechanical mapping over the known producer sources; anything else
+ * (including the broadcaster's paired `"notification"` delivery
+ * conversations) falls through to `"other"`.
+ */
+export function classifyConversationSource(
+  source: string | null | undefined,
+): FeedItemSourceType {
+  switch (source) {
+    case "heartbeat":
+      return "heartbeat";
+    case MEMORY_RETROSPECTIVE_SOURCE:
+    case MEMORY_RETROSPECTIVE_FORK_SOURCE:
+      return "memory_consolidation";
+    case "schedule":
+      return "schedule";
+    case AUTO_ANALYSIS_SOURCE:
+      return "auto_analysis";
+    case "user":
+    case "home-feed":
+      return "user";
+    default:
+      return "other";
+  }
+}
+
+/** Static display labels for non-schedule source types. */
+const STATIC_SOURCE_LABELS: Record<
+  Exclude<FeedItemSourceType, "schedule">,
+  string
+> = {
+  heartbeat: "Heartbeat",
+  memory_consolidation: "Memory consolidation",
+  auto_analysis: "Auto-analysis",
+  user: "Conversation",
+  other: "Other",
+};
+
+function defaultGetConversationRow(id: string): ConversationSourceRow | null {
+  try {
+    const row = getConversation(id);
+    return row
+      ? { source: row.source, scheduleJobId: row.scheduleJobId }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function defaultGetScheduleName(id: string): string | null {
+  try {
+    return getSchedule(id)?.name ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Return a copy of each feed item enriched with `sourceType`, `sourceKey`,
+ * and `sourceLabel`. Conversation and schedule lookups are memoized across
+ * the batch so each distinct source is resolved at most once.
+ */
+export function enrichFeedItemsWithSource(
+  items: FeedItem[],
+  deps: FeedSourceEnrichmentDeps = {},
+): FeedItem[] {
+  if (items.length === 0) return items;
+
+  const getConversationRow =
+    deps.getConversationRow ?? defaultGetConversationRow;
+  const getScheduleName = deps.getScheduleName ?? defaultGetScheduleName;
+
+  const convCache = new Map<string, ConversationSourceRow | null>();
+  const resolveConv = (id: string): ConversationSourceRow | null => {
+    if (!convCache.has(id)) convCache.set(id, getConversationRow(id));
+    return convCache.get(id) ?? null;
+  };
+
+  const scheduleNameCache = new Map<string, string | null>();
+  const resolveScheduleName = (id: string): string | null => {
+    if (!scheduleNameCache.has(id)) {
+      scheduleNameCache.set(id, getScheduleName(id));
+    }
+    return scheduleNameCache.get(id) ?? null;
+  };
+
+  return items.map((item) => {
+    const row = item.conversationId ? resolveConv(item.conversationId) : null;
+    const sourceType = classifyConversationSource(row?.source);
+
+    const metadataScheduleId =
+      typeof item.metadata?.scheduleId === "string"
+        ? item.metadata.scheduleId
+        : undefined;
+    const scheduleId = metadataScheduleId ?? row?.scheduleJobId ?? undefined;
+
+    let sourceKey: string;
+    let sourceLabel: string;
+    if (sourceType === "schedule" && scheduleId) {
+      sourceKey = `schedule:${scheduleId}`;
+      sourceLabel = resolveScheduleName(scheduleId) ?? "Scheduled";
+    } else if (sourceType === "schedule") {
+      sourceKey = "schedule";
+      sourceLabel = "Scheduled";
+    } else {
+      sourceKey = sourceType;
+      sourceLabel = STATIC_SOURCE_LABELS[sourceType];
+    }
+
+    // Surface the scheduleId in metadata when it was recovered from the
+    // source conversation so clients have a single place to read it.
+    const metadata =
+      scheduleId !== undefined && metadataScheduleId === undefined
+        ? { ...(item.metadata ?? {}), scheduleId }
+        : item.metadata;
+
+    return {
+      ...item,
+      sourceType,
+      sourceKey,
+      sourceLabel,
+      ...(metadata ? { metadata } : {}),
+    };
+  });
+}

package/src/runtime/routes/home-feed-routes.ts

@@ -28,6 +28,7 @@ import {
   type FeedItemStatus,
   HomeFeedResponseSchema,
 } from "../../api/responses/home.js";
+import { enrichFeedItemsWithSource } from "../../home/feed-source-enrichment.js";
 import { patchFeedItemStatus, readHomeFeed } from "../../home/feed-writer.js";
 import { revalidateHomeContentInBackground } from "../../home/home-content-refresh.js";
 import { getPersonalizedGreeting } from "../../home/home-greeting.js";
@@ -135,8 +136,10 @@ export async function handleGetHomeFeed({
   // v2 schema dropped per-item `minTimeAway` gating; surface every item
   // and let the client decide what to render based on its own
   // session state. `timeAwaySeconds` survives only to feed the
-  // context-banner relative-time label.
-  const filtered = feed.items;
+  // context-banner relative-time label. Each item is enriched with its
+  // source-conversation classification (`sourceType`/`sourceKey`/
+  // `sourceLabel`) so clients can filter the feed by what produced it.
+  const filtered = enrichFeedItemsWithSource(feed.items);
 
   const now = new Date();
 
@@ -287,7 +290,9 @@ export function handleListHomeFeed({
   const total = filtered.length;
   const offset = params.offset ?? 0;
   const limit = params.limit ?? 20;
-  const items = filtered.slice(offset, offset + limit);
+  const items = enrichFeedItemsWithSource(
+    filtered.slice(offset, offset + limit),
+  );
 
   return {
     items,