@vellumai/assistant 0.8.0 → 0.8.2

package/src/home/feed-types.ts

@@ -2,9 +2,8 @@
  * Home activity feed data contract.
  *
  * Defines the shape of `FeedItem`s shown in the macOS Home page feed
- * section (nudges, digests, actions, threads) plus the on-disk file
- * format written by the daemon feed writer (PR 5) and served by the
- * daemon HTTP route (PR 6).
+ * section plus the on-disk file format written by the daemon feed
+ * writer (PR 5) and served by the daemon HTTP route (PR 6).
  *
  * The TDD contract field originally named `ttl` is renamed internally
  * to `expiresAt` — it is an absolute ISO-8601 timestamp, not a
@@ -14,6 +13,15 @@
  * a translation layer at the route boundary; within the daemon, all
  * internal types use `expiresAt`.
  *
+ * **v2 schema collapse** — feed items now have a single `notification`
+ * type. The legacy `nudge | digest | action | thread` distinctions
+ * (and the `source` / `author` / `minTimeAway` fields that supported
+ * them) have been removed; everything that lands in the home feed is
+ * a notification, with the writer's only merge rule being "same `id`
+ * replaces in place, otherwise append". Workspace migration
+ * `061-home-feed-notification-only` rewrites pre-v2 files on first
+ * boot.
+ *
  * A structurally compatible Swift mirror lives at
  * `clients/shared/Network/FeedItem.swift` (PR 3). Any change here
  * must be mirrored there.
@@ -22,38 +30,22 @@
 import { z } from "zod";
 
 /** High-level kind of feed item — drives which Swift view renders it. */
-export type FeedItemType = "nudge" | "digest" | "action" | "thread";
+export type FeedItemType = "notification";
 
 /** User-facing lifecycle of a feed item. */
 export type FeedItemStatus = "new" | "seen" | "acted_on" | "dismissed";
 
-/**
- * Origin of the underlying event.
- *
- * In v1 this is constrained to a closed set so the Swift icon mapping
- * stays exhaustive. Future sources will be added explicitly rather
- * than letting arbitrary strings slip through.
- */
-export type FeedItemSource =
-  | "gmail"
-  | "slack"
-  | "calendar"
-  | "assistant"
-  | "telegram";
-
-/**
- * Internal field used by the hybrid authoring resolver (PR 5 writer).
- *
- * Not part of the TDD public interface — it distinguishes items the
- * assistant produced on its own from items the platform baseline
- * generators (e.g. Gmail digest in PR 12) produced, so assistant
- * overrides can win over platform defaults for the same source.
- */
-export type FeedItemAuthor = "assistant" | "platform";
-
 /** Visual urgency treatment — controls badge color independently of sort priority. */
 export type FeedItemUrgency = "low" | "medium" | "high" | "critical";
 
+/** Broad category for grouping and filtering feed items. */
+export type FeedItemCategory =
+  | "security"
+  | "scheduling"
+  | "background"
+  | "email"
+  | "system";
+
 /**
  * A single action button attached to a feed item.
  *
@@ -84,8 +76,7 @@ export interface FeedItemDetailPanel {
 /**
  * A single item rendered in the Home feed.
  *
- * Mirrors the TDD contract plus two internal-only fields:
- *   - `author`  — hybrid-authoring resolver discriminator
+ * Mirrors the TDD contract plus one internal-only field:
  *   - `createdAt` — when the writer recorded the item (distinct from
  *                   `timestamp`, which is the event time). Used for
  *                   TTL sweeps and stable ordering.
@@ -100,16 +91,12 @@ export interface FeedItem {
   priority: number;
   title: string;
   summary: string;
-  /** Optional; when present must be one of the v1 sources. */
-  source?: FeedItemSource;
   /** Event time (ISO-8601). */
   timestamp: string;
   /** Defaults to `"new"` at parse time. */
   status: FeedItemStatus;
   /** Absolute ISO-8601 expiry timestamp (renamed from TDD `ttl`). */
   expiresAt?: string;
-  /** Minimum seconds the user must be away before the item is shown. */
-  minTimeAway?: number;
   actions?: FeedAction[];
   /** Visual urgency treatment — controls badge color independently of sort priority. */
   urgency?: FeedItemUrgency;
@@ -117,31 +104,24 @@ export interface FeedItem {
   conversationId?: string;
   /** Server-driven detail panel descriptor; when present, the client opens this panel kind. */
   detailPanel?: FeedItemDetailPanel;
-  /** Internal: who authored this item. */
-  author: FeedItemAuthor;
+  /** Broad category for grouping and filtering feed items. */
+  category?: FeedItemCategory;
+  /** 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. */
   createdAt: string;
 }
 
-/**
- * Summary of low-priority items that were collapsed out of the main
- * feed list. The client renders this as a single "N low priority
- * updates" line instead of showing each item individually.
- */
-export interface LowPriorityCollapsed {
-  count: number;
-  itemIds: string[];
-}
-
 /**
  * On-disk file format for `~/.vellum/workspace/data/home-feed.json`.
  *
  * Written by the PR 5 writer, read by the PR 6 HTTP route and
- * `parseFeedFile` below. `version` is pinned to `1`; future format
- * changes bump this and live behind a workspace migration.
+ * `parseFeedFile` below. `version` is pinned to `2` (collapsed schema);
+ * pre-v2 files are rewritten by workspace migration
+ * `061-home-feed-notification-only`.
  */
 export interface HomeFeedFile {
-  version: 1;
+  version: 2;
   items: FeedItem[];
   updatedAt: string;
 }
@@ -171,20 +151,10 @@ export interface SuggestedPrompt {
 // Zod schemas
 // ---------------------------------------------------------------------------
 
-const feedItemTypeSchema = z.enum(["nudge", "digest", "action", "thread"]);
+const feedItemTypeSchema = z.literal("notification");
 
 const feedItemStatusSchema = z.enum(["new", "seen", "acted_on", "dismissed"]);
 
-const feedItemSourceSchema = z.enum([
-  "gmail",
-  "slack",
-  "calendar",
-  "assistant",
-  "telegram",
-]);
-
-const feedItemAuthorSchema = z.enum(["assistant", "platform"]);
-
 const feedItemUrgencySchema = z.enum(["low", "medium", "high", "critical"]);
 
 const feedActionSchema = z.object({
@@ -206,6 +176,14 @@ const feedItemDetailPanelSchema = z.object({
   kind: feedItemDetailPanelKindSchema,
 });
 
+const feedItemCategorySchema = z.enum([
+  "security",
+  "scheduling",
+  "background",
+  "email",
+  "system",
+]);
+
 /**
  * Schema for a single `FeedItem`.
  *
@@ -215,10 +193,6 @@ const feedItemDetailPanelSchema = z.object({
  *     silent coercion tends to mask writer bugs.
  *   - `status` defaults to `"new"` so the writer does not need to
  *     set it on every append.
- *   - `source` is optional but, when present, must be one of the
- *     four v1 sources — unknown values (e.g. `"facebook"`) are
- *     rejected rather than silently passed through.
- *   - `minTimeAway` is a non-negative integer number of seconds.
  */
 export const feedItemSchema = z.object({
   id: z.string(),
@@ -226,16 +200,15 @@ export const feedItemSchema = z.object({
   priority: z.number().int().min(0).max(100),
   title: z.string(),
   summary: z.string(),
-  source: feedItemSourceSchema.optional(),
   timestamp: z.string(),
   status: feedItemStatusSchema.default("new"),
   expiresAt: z.string().optional(),
-  minTimeAway: z.number().int().min(0).optional(),
   actions: z.array(feedActionSchema).optional(),
   urgency: feedItemUrgencySchema.optional(),
   conversationId: z.string().optional(),
   detailPanel: feedItemDetailPanelSchema.optional(),
-  author: feedItemAuthorSchema,
+  category: feedItemCategorySchema.optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
   createdAt: z.string(),
 });
 
@@ -249,14 +222,9 @@ export const suggestedPromptSchema = z.object({
   source: suggestedPromptSourceSchema,
 });
 
-export const lowPriorityCollapsedSchema = z.object({
-  count: z.number().int().min(0),
-  itemIds: z.array(z.string()),
-});
-
 /** Schema for the on-disk `home-feed.json` file. */
 const homeFeedFileSchema = z.object({
-  version: z.literal(1),
+  version: z.literal(2),
   items: z.array(feedItemSchema),
   updatedAt: z.string(),
 });

package/src/home/feed-writer.ts

@@ -2,41 +2,26 @@
  * Home activity feed writer.
  *
  * Owns `<workspace>/data/home-feed.json`, the daemon-side source of
- * truth for the macOS Home page activity feed. Handles the merge
- * semantics defined by the TDD / plan:
+ * truth for the macOS Home page activity feed.
  *
- *   - Digest replacement: at most one digest per `source`. A fresh
- *     digest for a source replaces any prior digest for the same
- *     source in place.
- *   - Thread in-place update: if an incoming `thread` item shares its
+ * **v2 merge semantics** — the schema collapse to a single
+ * `notification` type also collapses the writer's merge rules to a
+ * single rule:
+ *
+ *   - **Same `id` replaces in place**: if an incoming item shares its
  *     `id` with an existing item, replace that item while preserving
  *     its array position so the UI does not jitter on updates.
- *   - Author resolution: for matching `(type, source)` pairs the
- *     hybrid-authoring precedence is `assistant` beats `platform` —
- *     an assistant item overwrites an existing platform item for the
- *     same pair, but a platform item never overwrites an existing
- *     assistant item (no-op). Applies to nudges; actions are exempt
- *     (see next bullet).
- *   - Action append-without-replace: `action` items are the feed's
- *     activity log and never merge by `(type, source)` — each append
- *     becomes a distinct entry so successive background-job events
- *     don't collapse onto each other. A same-`id` action is the one
- *     exception: it performs an in-place update (same semantics as
- *     threads) so callers using a deterministic dedup id via
- *     `emit-feed-event.ts` can refresh an entry without appending a
- *     duplicate. Callers that want to auto-expire an action item
- *     must set `expiresAt` explicitly; the writer does NOT fill in
- *     a default expiry.
- *   - Per-source action cap: after merge, each source keeps at most
- *     {@link MAX_ACTIONS_PER_SOURCE} action items (most recent by
- *     `createdAt`). Older actions for that source are dropped so the
- *     on-disk file can't balloon as background jobs emit events.
- *     Action items without a `source` are unbounded and passed
- *     through untouched.
- *   - TTL filter on read: `readHomeFeed` drops any item whose
+ *     Otherwise, append. The pre-v2 type-specific branches (digest
+ *     replacement by source, thread same-id update, action
+ *     append-without-replace, hybrid-author resolution, per-source
+ *     action cap) are gone — they were holdovers from a multi-type
+ *     vocabulary that no longer exists.
+ *
+ *   - **TTL filter on read**: `readHomeFeed` drops any item whose
  *     `expiresAt` is in the past. This is a stateless sweep — the
  *     writer does not rewrite the file on read, so concurrent reads
- *     never race the writer.
+ *     never race the writer. Callers that want auto-expiry must set
+ *     `expiresAt` explicitly; the writer does NOT fill in a default.
  *
  * Concurrent writers are coalesced with the exact same "latest wins"
  * pattern as `relationship-state-writer.ts`: at most one compute+write
@@ -69,16 +54,7 @@ const log = getLogger("home-feed-writer");
 export const HOME_FEED_FILENAME = "home-feed.json";
 
 /** On-disk file-format version. Bump + migrate if the shape changes. */
-export const HOME_FEED_VERSION = 1;
-
-/**
- * Per-source volume cap for `action` items. When the post-merge item
- * list has more than this many action items for a single source, the
- * oldest (by `createdAt`) are dropped until the count is back within
- * the cap. Other item types are unaffected, and action items without
- * a `source` are also unaffected.
- */
-export const MAX_ACTIONS_PER_SOURCE = 20;
+export const HOME_FEED_VERSION = 2;
 
 /**
  * Canonical path to the home-feed snapshot
@@ -238,8 +214,6 @@ async function runWrite(): Promise<void> {
     items = mergeIncoming(items, incoming);
   }
 
-  items = pruneActionsPerSource(items);
-
   // Track the per-patch result so callers can distinguish an update
   // from an unknown-id no-op. We collect resolvers first and fire them
   // after the write lands so the resolved `FeedItem` matches on-disk
@@ -298,128 +272,23 @@ async function runWrite(): Promise<void> {
 }
 
 /**
- * Apply the merge semantics for a single incoming item against the
+ * Apply the v2 merge rule for a single incoming item against the
  * current item list and return a new list. Pure function — the input
  * array is not mutated.
+ *
+ * Same-`id` replaces in place (preserving array position so the UI
+ * does not jitter); otherwise the item is appended.
  */
 function mergeIncoming(items: FeedItem[], incoming: FeedItem): FeedItem[] {
-  // Digest replacement: one digest per source wins.
-  if (incoming.type === "digest" && incoming.source) {
-    const filtered = items.filter(
-      (i) => !(i.type === "digest" && i.source === incoming.source),
-    );
-    filtered.push(incoming);
-    return filtered;
-  }
-
-  // Thread in-place update: same id wins, preserve position.
-  if (incoming.type === "thread") {
-    const idx = items.findIndex(
-      (i) => i.type === "thread" && i.id === incoming.id,
-    );
-    if (idx !== -1) {
-      const copy = items.slice();
-      copy[idx] = incoming;
-      return copy;
-    }
-  }
-
-  // Action append-without-replace: each action item is a distinct
-  // activity-log entry and must NOT collapse onto an existing action
-  // for the same (type, source) pair. The per-source volume cap in
-  // `pruneActionsPerSource` keeps the log from growing unbounded.
-  //
-  // Exception: same-id in-place update. Callers that want
-  // deterministic dedup (e.g. via `emit-feed-event.ts`'s `dedupKey`)
-  // produce a stable id per logical event; a second emit with the
-  // same id refreshes the existing entry in place rather than
-  // appending a duplicate.
-  if (incoming.type === "action") {
-    const idx = items.findIndex(
-      (i) => i.type === "action" && i.id === incoming.id,
-    );
-    if (idx !== -1) {
-      const copy = items.slice();
-      copy[idx] = incoming;
-      return copy;
-    }
-    return [...items, incoming];
-  }
-
-  // Author resolution: for matching (type, source) pairs, assistant
-  // beats platform. A platform-authored incoming item against an
-  // existing assistant item is a no-op. Applies to nudges (actions
-  // short-circuit above).
-  if (incoming.source) {
-    const existingIdx = items.findIndex(
-      (i) => i.type === incoming.type && i.source === incoming.source,
-    );
-    if (existingIdx !== -1) {
-      const existing = items[existingIdx]!;
-      if (existing.author === "assistant" && incoming.author === "platform") {
-        // Platform can't overwrite assistant — no-op.
-        return items;
-      }
-      if (existing.author === "platform" && incoming.author === "assistant") {
-        const copy = items.slice();
-        copy[existingIdx] = incoming;
-        return copy;
-      }
-    }
+  const idx = items.findIndex((i) => i.id === incoming.id);
+  if (idx !== -1) {
+    const copy = items.slice();
+    copy[idx] = incoming;
+    return copy;
   }
-
   return [...items, incoming];
 }
 
-/**
- * Enforce the per-source volume cap on `action` items. For each
- * source that has more than {@link MAX_ACTIONS_PER_SOURCE} actions in
- * the post-merge list, keep the most recent by `createdAt` and drop
- * the rest. Other item types and action items without a `source` are
- * passed through untouched. Stable with respect to non-affected items.
- */
-function pruneActionsPerSource(items: FeedItem[]): FeedItem[] {
-  const actionsBySource = new Map<string, FeedItem[]>();
-  for (const item of items) {
-    if (item.type !== "action" || !item.source) continue;
-    const bucket = actionsBySource.get(item.source);
-    if (bucket) {
-      bucket.push(item);
-    } else {
-      actionsBySource.set(item.source, [item]);
-    }
-  }
-
-  const overflowing: string[] = [];
-  for (const [source, bucket] of actionsBySource) {
-    if (bucket.length > MAX_ACTIONS_PER_SOURCE) overflowing.push(source);
-  }
-  if (overflowing.length === 0) return items;
-
-  const keepIds = new Set<string>();
-  for (const source of overflowing) {
-    const bucket = actionsBySource.get(source)!.slice();
-    bucket.sort((a, b) => {
-      const am = Date.parse(a.createdAt);
-      const bm = Date.parse(b.createdAt);
-      if (Number.isNaN(am) && Number.isNaN(bm)) return 0;
-      if (Number.isNaN(am)) return 1;
-      if (Number.isNaN(bm)) return -1;
-      return bm - am;
-    });
-    for (const item of bucket.slice(0, MAX_ACTIONS_PER_SOURCE)) {
-      keepIds.add(item.id);
-    }
-  }
-
-  return items.filter((item) => {
-    if (item.type !== "action") return true;
-    if (!item.source) return true;
-    if (!overflowing.includes(item.source)) return true;
-    return keepIds.has(item.id);
-  });
-}
-
 /**
  * Return `true` when the item has an `expiresAt` timestamp that is in
  * the past relative to the supplied `nowMs`. Items without

package/src/home/post-connect-feed.ts

@@ -37,16 +37,15 @@ export async function emitPostConnectNudge(service: string): Promise<void> {
 
   const item: FeedItem = {
     id: `connect-nudge:${service}`,
-    type: "nudge",
+    type: "notification",
     priority: 70,
     title: "Gmail connected — want ongoing help?",
     summary:
       "I can triage your inbox, summarize new emails, or draft replies to important threads.",
-    source: "gmail",
     timestamp: now.toISOString(),
     status: "new",
+    category: "email",
     expiresAt,
-    author: "platform",
     createdAt: now.toISOString(),
     actions: [
       {

package/src/index.ts

@@ -1,5 +1,22 @@
 #!/usr/bin/env bun
 
+import { red } from "./cli/lib/cli-colors.js";
+import {
+  detectUnknownCommand,
+  formatUnknownCommandMessage,
+} from "./cli/lib/unknown-command.js";
 import { buildCliProgram } from "./cli/program.js";
 
-(await buildCliProgram()).parse();
+const program = await buildCliProgram();
+
+// Commander processes `--help` before any action or hook fires, so
+// `assistant <unknown> --help` would dump the root help instead of flagging
+// the typo. Pre-scan argv so the unknown-command error wins over the help
+// short-circuit. See cli/lib/unknown-command.ts.
+const unknown = detectUnknownCommand(program, process.argv.slice(2));
+if (unknown) {
+  process.stderr.write(`${red(formatUnknownCommandMessage(unknown))}\n`);
+  process.exit(1);
+}
+
+program.parse();

package/src/ipc/__tests__/cli-ipc.test.ts

@@ -8,6 +8,8 @@
 
 import { afterEach, describe, expect, mock, test } from "bun:test";
 
+delete process.env.ASSISTANT_IPC_SOCKET_DIR;
+
 import { runAssistantCommandFull } from "../../cli/__tests__/run-assistant-command.js";
 import { AssistantIpcServer } from "../assistant-server.js";