@vellumai/assistant 0.6.3 → 0.6.4

package/src/home/__tests__/phase5-exit-criteria.test.ts

@@ -0,0 +1,212 @@
+/**
+ * Phase 5 exit-criteria end-to-end test.
+ *
+ * Exercises the full home-feed flow in-process against a tmpdir
+ * workspace: the platform-baseline generator writes a digest, the
+ * assistant-authoring helper writes a nudge, the HTTP route serves
+ * both with a context banner, and the patch endpoint flips an item
+ * to `seen` — all without spinning up the macOS app.
+ *
+ * Exit-criteria mapping (from the TDD checklist):
+ *
+ *   [x] platform-baseline Gmail digest surfaces via the feed route
+ *       → `generateGmailDigest(now)` + `GET /v1/home/feed` → 1 item
+ *   [x] assistant-authored nudges coexist with platform digests
+ *       → `writeAssistantFeedItem(...)` → 2 items visible
+ *   [x] `minTimeAway` filtering behaves at route boundary
+ *       → seed an item with `minTimeAway: 3600` and query with
+ *         `timeAwaySeconds: 12 * 3600` → included
+ *   [x] context banner reports `newCount` across all authors
+ *       → 2 new items → banner.newCount === 2
+ *   [x] `PATCH /v1/home/feed/:id` flips status and mutates banner
+ *       → patchFeedItemStatus(nudgeId, "seen") → newCount drops to 1
+ *
+ * This test is a wiring-regression safety net — the per-PR unit
+ * tests in this directory (feed-writer, feed-types, authoring,
+ * gmail-digest, plus the route tests under `runtime/routes/__tests__`)
+ * still carry the per-component coverage. Keep this file fast (<5s)
+ * by doing all persistence against a single tmpdir workspace and
+ * calling route handlers directly instead of standing up the HTTP
+ * server.
+ */
+
+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";
+
+// ─── assistantEventHub mock ────────────────────────────────────────────
+// The real feed writer publishes `home_feed_updated` via the in-process
+// event hub on every write. This test doesn't assert on those events —
+// it asserts on the feed file + HTTP-route output — so we stub the hub
+// to an inert publisher. Must run before the first dynamic import of
+// anything that transitively imports `feed-writer.js`.
+const publishSpy = mock<(event: unknown) => Promise<void>>(async () => {});
+mock.module("../../runtime/assistant-event-hub.js", () => ({
+  assistantEventHub: {
+    publish: publishSpy,
+    subscribe: () => () => {},
+  },
+}));
+
+// ─── createConversation / addMessage stub ──────────────────────────────
+// The feed action endpoint (`POST /v1/home/feed/:id/actions/:actionId`)
+// calls into the real conversation store, which drags in a large chunk
+// of daemon state we don't want this test to depend on. The exit-
+// criteria flow we care about is GET + PATCH — not the action POST —
+// so we stub the conversation module to a trivial in-memory fake and
+// never exercise it. If a future exit-criteria item needs the action
+// path, swap this for a real-ish fake.
+mock.module("../../runtime/conversation-store.js", () => ({
+  createConversation: (args: { title: string; source: string }) => ({
+    id: "stub-conversation",
+    title: args.title,
+    source: args.source,
+  }),
+  addMessage: async () => {},
+}));
+
+const { generateGmailDigest } = await import("../platform-gmail-digest.js");
+const { writeAssistantFeedItem } =
+  await import("../assistant-feed-authoring.js");
+const { patchFeedItemStatus, readHomeFeed } = await import("../feed-writer.js");
+const { handleGetHomeFeed } =
+  await import("../../runtime/routes/home-feed-routes.js");
+
+// ─── tmpdir workspace lifecycle ────────────────────────────────────────
+
+let workspaceDir: string;
+let origWorkspaceDir: string | undefined;
+
+beforeEach(() => {
+  workspaceDir = mkdtempSync(join(tmpdir(), "vellum-phase5-e2e-"));
+  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 — tests must not fail on cleanup
+  }
+});
+
+// ─── Helpers ───────────────────────────────────────────────────────────
+
+/** Hit the GET handler directly with a synthetic Request object. */
+async function getFeed(timeAwaySeconds: number): Promise<{
+  items: Array<{
+    id: string;
+    status: string;
+    type: string;
+    source?: string;
+    author: string;
+  }>;
+  updatedAt: string;
+  contextBanner: { greeting: string; timeAwayLabel: string; newCount: number };
+}> {
+  const req = new Request(
+    `http://daemon.local/v1/home/feed?timeAwaySeconds=${timeAwaySeconds}`,
+  );
+  const res = await handleGetHomeFeed(req);
+  expect(res.status).toBe(200);
+  return (await res.json()) as Awaited<ReturnType<typeof getFeed>>;
+}
+
+// ─── Tests ─────────────────────────────────────────────────────────────
+
+describe("Phase 5 exit criteria — end-to-end", () => {
+  test("platform digest + assistant nudge surface via the feed route, and patch flips newCount", async () => {
+    const now = new Date("2026-04-14T12:00:00.000Z");
+
+    // 1. Platform baseline: Gmail digest — mechanical "3 new emails"
+    const digest = await generateGmailDigest(now, async () => 3);
+    expect(digest).not.toBeNull();
+    expect(digest!.source).toBe("gmail");
+    expect(digest!.author).toBe("platform");
+    expect(digest!.type).toBe("digest");
+
+    // 2. Assistant-authored nudge — the hybrid-authoring surface
+    const nudge = await writeAssistantFeedItem({
+      type: "nudge",
+      source: "assistant",
+      title: "Follow up on the Figma file",
+      summary: "Alice is asking when the deck lands.",
+      actions: [
+        {
+          id: "open",
+          label: "Open conversation",
+          prompt: "Remind me about the Figma file.",
+        },
+      ],
+      minTimeAway: 3600,
+    });
+    expect(nudge.author).toBe("assistant");
+    expect(nudge.type).toBe("nudge");
+
+    // 3. On-disk sanity: both items made it into home-feed.json and
+    //    the digest coexists with the assistant nudge (different
+    //    (type, source) so the one-per-source replacement does not
+    //    collapse them into a single item).
+    const onDisk = readHomeFeed();
+    const ids = onDisk.items.map((i) => i.id).sort();
+    expect(ids.length).toBe(2);
+    expect(ids).toContain(digest!.id);
+    expect(ids).toContain(nudge.id);
+
+    // 4. Route: `GET /v1/home/feed?timeAwaySeconds=43200` — both items
+    //    pass the `minTimeAway` gate (3600 <= 43200). Banner reports
+    //    `newCount: 2` since both are still `.new`.
+    const initial = await getFeed(12 * 3600);
+    expect(initial.items.length).toBe(2);
+    expect(initial.contextBanner.newCount).toBe(2);
+    expect(initial.contextBanner.timeAwayLabel.length).toBeGreaterThan(0);
+    expect(initial.contextBanner.greeting.length).toBeGreaterThan(0);
+
+    // 5. Flip the nudge to `seen` via the writer (the route's PATCH
+    //    handler is a thin wrapper around this — we skip the HTTP
+    //    layer here so the test stays at the in-process seam).
+    const patched = await patchFeedItemStatus(nudge.id, "seen");
+    expect(patched).not.toBeNull();
+    expect(patched!.status).toBe("seen");
+
+    // 6. Re-fetch: `newCount` drops to 1 (only the digest is still
+    //    `.new`). Total item count is unchanged — patching status
+    //    must never remove items from the feed.
+    const afterPatch = await getFeed(12 * 3600);
+    expect(afterPatch.items.length).toBe(2);
+    expect(afterPatch.contextBanner.newCount).toBe(1);
+    const seenItem = afterPatch.items.find((i) => i.id === nudge.id);
+    expect(seenItem?.status).toBe("seen");
+  });
+
+  test("minTimeAway gate excludes items when the user has not been away long enough", async () => {
+    // Assistant nudge with a 1-hour away gate
+    const nudge = await writeAssistantFeedItem({
+      type: "nudge",
+      source: "assistant",
+      title: "Come back after lunch",
+      summary: "This only shows after an hour away.",
+      minTimeAway: 3600,
+    });
+
+    // User has only been away 10 minutes → item must be filtered
+    const brief = await getFeed(600);
+    const briefIds = brief.items.map((i) => i.id);
+    expect(briefIds).not.toContain(nudge.id);
+    expect(brief.contextBanner.newCount).toBe(0);
+
+    // User has been away 2 hours → item must now appear
+    const long = await getFeed(2 * 3600);
+    const longIds = long.items.map((i) => i.id);
+    expect(longIds).toContain(nudge.id);
+    expect(long.contextBanner.newCount).toBe(1);
+  });
+});

package/src/home/__tests__/platform-gmail-digest.test.ts

@@ -0,0 +1,222 @@
+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";
+
+// ─── assistantEventHub mock ────────────────────────────────────────────
+// The real feed-writer publishes `home_feed_updated` via the in-process
+// event hub on every write; tests don't care about that side effect, so
+// we stub the hub to an inert publisher. Must be in place before the
+// first dynamic import of feed-writer.js so the module graph picks up
+// the mock.
+const publishSpy = mock<(event: unknown) => Promise<void>>(async () => {});
+
+mock.module("../../runtime/assistant-event-hub.js", () => ({
+  assistantEventHub: {
+    publish: publishSpy,
+    subscribe: () => () => {},
+  },
+}));
+
+// Dynamic import so the mock above resolves before the real module is
+// evaluated.
+const { generateGmailDigest } = await import("../platform-gmail-digest.js");
+const { getHomeFeedPath, readHomeFeed } = await import("../feed-writer.js");
+
+// ─── tmpdir workspace lifecycle ────────────────────────────────────────
+
+let workspaceDir: string;
+let origWorkspaceDir: string | undefined;
+
+beforeEach(() => {
+  workspaceDir = mkdtempSync(join(tmpdir(), "vellum-pgd-"));
+  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
+  }
+});
+
+// ─── Tests ─────────────────────────────────────────────────────────────
+
+describe("generateGmailDigest", () => {
+  test("returns null and does not write when count is 0", async () => {
+    const result = await generateGmailDigest(
+      new Date("2026-04-14T12:00:00.000Z"),
+      async () => 0,
+    );
+    expect(result).toBeNull();
+
+    // No file should have been written — readHomeFeed returns the
+    // empty sentinel with the Unix-epoch updatedAt.
+    const feed = readHomeFeed();
+    expect(feed.items).toEqual([]);
+    expect(feed.updatedAt).toBe(new Date(0).toISOString());
+  });
+
+  test("returns a digest FeedItem with the expected shape when count > 0", async () => {
+    const now = new Date("2026-04-14T12:00:00.000Z");
+    const result = await generateGmailDigest(now, async () => 7);
+
+    expect(result).not.toBeNull();
+    expect(result!.type).toBe("digest");
+    expect(result!.source).toBe("gmail");
+    expect(result!.author).toBe("platform");
+    expect(result!.priority).toBe(40);
+    expect(result!.minTimeAway).toBe(3600);
+    expect(result!.status).toBe("new");
+    expect(result!.title).toContain("7");
+    expect(result!.timestamp).toBe(now.toISOString());
+    expect(result!.createdAt).toBe(now.toISOString());
+  });
+
+  test("minTimeAway is exactly 3600 seconds (1 hour)", async () => {
+    const result = await generateGmailDigest(
+      new Date("2026-04-14T12:00:00.000Z"),
+      async () => 1,
+    );
+    expect(result).not.toBeNull();
+    expect(result!.minTimeAway).toBe(3600);
+  });
+
+  test("title uses singular form for count of 1, plural otherwise", async () => {
+    const now = new Date("2026-04-14T12:00:00.000Z");
+
+    const one = await generateGmailDigest(now, async () => 1);
+    expect(one!.title).toBe("1 new email");
+
+    const many = await generateGmailDigest(now, async () => 3);
+    expect(many!.title).toBe("3 new emails");
+  });
+
+  test("returns null when count source throws", async () => {
+    const result = await generateGmailDigest(
+      new Date("2026-04-14T12:00:00.000Z"),
+      async () => {
+        throw new Error("boom");
+      },
+    );
+    expect(result).toBeNull();
+
+    const feed = readHomeFeed();
+    expect(feed.items).toEqual([]);
+  });
+
+  test("writes the item to home-feed.json via appendFeedItem", async () => {
+    const now = new Date("2026-04-14T12:00:00.000Z");
+    const result = await generateGmailDigest(now, async () => 5);
+    expect(result).not.toBeNull();
+
+    const raw = readFileSync(getHomeFeedPath(), "utf-8");
+    const file = JSON.parse(raw) as {
+      items: Array<{
+        id: string;
+        type: string;
+        source?: string;
+        author: string;
+        priority: number;
+        title: string;
+      }>;
+    };
+
+    expect(file.items.length).toBe(1);
+    expect(file.items[0]).toMatchObject({
+      id: result!.id,
+      type: "digest",
+      source: "gmail",
+      author: "platform",
+      priority: 40,
+      title: "5 new emails",
+    });
+  });
+
+  test("summary uses generic check-in copy on first-ever digest", async () => {
+    const result = await generateGmailDigest(
+      new Date("2026-04-14T12:00:00.000Z"),
+      async () => 4,
+    );
+    expect(result).not.toBeNull();
+    expect(result!.summary).toBe("Since your last check-in");
+  });
+
+  test("summary references the prior digest timestamp on subsequent call", async () => {
+    const first = await generateGmailDigest(
+      new Date("2026-04-14T14:32:00.000Z"),
+      async () => 2,
+    );
+    expect(first).not.toBeNull();
+
+    // Same-day follow-up → "Since h:mm AM/PM" pulled from the first
+    // digest's timestamp (2:32 PM UTC rendered via en-US locale).
+    const sameDay = await generateGmailDigest(
+      new Date("2026-04-14T16:00:00.000Z"),
+      async () => 5,
+    );
+    expect(sameDay).not.toBeNull();
+    expect(sameDay!.summary).toMatch(/^Since \d{1,2}:\d{2}\s?(AM|PM)$/);
+  });
+
+  test("summary includes weekday when prior digest is on a different day", async () => {
+    const first = await generateGmailDigest(
+      new Date("2026-04-13T22:00:00.000Z"),
+      async () => 1,
+    );
+    expect(first).not.toBeNull();
+
+    const nextDay = await generateGmailDigest(
+      new Date("2026-04-14T14:00:00.000Z"),
+      async () => 3,
+    );
+    expect(nextDay).not.toBeNull();
+    // Cross-day → "Since <Weekday> h:mm AM/PM" — weekday prefix set.
+    expect(nextDay!.summary).toMatch(
+      /^Since (Mon|Tue|Wed|Thu|Fri|Sat|Sun) \d{1,2}:\d{2}\s?(AM|PM)$/,
+    );
+  });
+
+  // Integration: exercise the writer's one-per-source rule. Two
+  // successive generator calls should leave exactly one Gmail digest
+  // on disk — the newer call replaces the earlier one in place.
+  test("second call replaces the first via one-per-source rule", async () => {
+    const first = await generateGmailDigest(
+      new Date("2026-04-14T12:00:00.000Z"),
+      async () => 2,
+    );
+    expect(first).not.toBeNull();
+
+    const second = await generateGmailDigest(
+      new Date("2026-04-14T13:00:00.000Z"),
+      async () => 9,
+    );
+    expect(second).not.toBeNull();
+    expect(second!.id).not.toBe(first!.id);
+
+    const raw = readFileSync(getHomeFeedPath(), "utf-8");
+    const file = JSON.parse(raw) as {
+      items: Array<{
+        id: string;
+        type: string;
+        source?: string;
+        title: string;
+      }>;
+    };
+
+    const gmailDigests = file.items.filter(
+      (i) => i.type === "digest" && i.source === "gmail",
+    );
+    expect(gmailDigests.length).toBe(1);
+    expect(gmailDigests[0]!.id).toBe(second!.id);
+    expect(gmailDigests[0]!.title).toBe("9 new emails");
+  });
+});

package/src/home/__tests__/progress-formula.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  computeProgressPercent,
+  computeTier,
+  PROGRESS_TARGETS,
+  PROGRESS_WEIGHTS,
+} from "../progress-formula.js";
+import type { Capability, Fact } from "../relationship-state.js";
+
+function fact(id: string): Fact {
+  return {
+    id,
+    category: "world",
+    text: "placeholder",
+    confidence: "strong",
+    source: "inferred",
+  };
+}
+
+function cap(id: string, tier: Capability["tier"]): Capability {
+  return {
+    id,
+    name: id,
+    description: "",
+    tier,
+    gate: "",
+  };
+}
+
+function facts(n: number): Fact[] {
+  return Array.from({ length: n }, (_, i) => fact(`f-${i}`));
+}
+
+function unlockedCaps(n: number): Capability[] {
+  return Array.from({ length: n }, (_, i) => cap(`c-${i}`, "unlocked"));
+}
+
+describe("progress-formula", () => {
+  describe("PROGRESS_WEIGHTS", () => {
+    test("sum to exactly 1 so a fully saturated input yields 100", () => {
+      const sum =
+        PROGRESS_WEIGHTS.facts +
+        PROGRESS_WEIGHTS.capabilities +
+        PROGRESS_WEIGHTS.conversations;
+      // Use toBeCloseTo for float safety.
+      expect(sum).toBeCloseTo(1, 10);
+    });
+  });
+
+  describe("computeProgressPercent", () => {
+    test("zero state -> 0", () => {
+      expect(
+        computeProgressPercent({
+          facts: [],
+          capabilities: [],
+          conversationCount: 0,
+        }),
+      ).toBe(0);
+    });
+
+    test("all saturated -> 100", () => {
+      expect(
+        computeProgressPercent({
+          facts: facts(PROGRESS_TARGETS.facts),
+          capabilities: unlockedCaps(PROGRESS_TARGETS.capabilities),
+          conversationCount: PROGRESS_TARGETS.conversations,
+        }),
+      ).toBe(100);
+    });
+
+    test("saturation clamps: inputs beyond target do not exceed 100", () => {
+      expect(
+        computeProgressPercent({
+          facts: facts(PROGRESS_TARGETS.facts * 3),
+          capabilities: unlockedCaps(PROGRESS_TARGETS.capabilities * 3),
+          conversationCount: PROGRESS_TARGETS.conversations * 3,
+        }),
+      ).toBe(100);
+    });
+
+    test("facts-only at target contributes exactly its weight", () => {
+      expect(
+        computeProgressPercent({
+          facts: facts(PROGRESS_TARGETS.facts),
+          capabilities: [],
+          conversationCount: 0,
+        }),
+      ).toBe(Math.round(PROGRESS_WEIGHTS.facts * 100));
+    });
+
+    test("capabilities-only at target contributes exactly its weight", () => {
+      expect(
+        computeProgressPercent({
+          facts: [],
+          capabilities: unlockedCaps(PROGRESS_TARGETS.capabilities),
+          conversationCount: 0,
+        }),
+      ).toBe(Math.round(PROGRESS_WEIGHTS.capabilities * 100));
+    });
+
+    test("conversations-only at target contributes exactly its weight", () => {
+      expect(
+        computeProgressPercent({
+          facts: [],
+          capabilities: [],
+          conversationCount: PROGRESS_TARGETS.conversations,
+        }),
+      ).toBe(Math.round(PROGRESS_WEIGHTS.conversations * 100));
+    });
+
+    test("non-unlocked capabilities do not contribute", () => {
+      const mixed: Capability[] = [
+        cap("a", "next-up"),
+        cap("b", "earned"),
+        cap("c", "unlocked"),
+      ];
+      // Only 1 of PROGRESS_TARGETS.capabilities counts toward the caps weight.
+      const expected = Math.round(
+        ((PROGRESS_WEIGHTS.capabilities * 1) / PROGRESS_TARGETS.capabilities) *
+          100,
+      );
+      expect(
+        computeProgressPercent({
+          facts: [],
+          capabilities: mixed,
+          conversationCount: 0,
+        }),
+      ).toBe(expected);
+    });
+
+    test("specific mix: half facts, half caps, half conversations -> 50", () => {
+      // Each signal at half its target contributes half its weight; total
+      // is half of the combined weight (1) * 100 = 50.
+      expect(
+        computeProgressPercent({
+          facts: facts(PROGRESS_TARGETS.facts / 2),
+          capabilities: unlockedCaps(PROGRESS_TARGETS.capabilities / 2),
+          conversationCount: PROGRESS_TARGETS.conversations / 2,
+        }),
+      ).toBe(50);
+    });
+  });
+
+  describe("computeTier", () => {
+    test("zero state -> tier 1 (Getting to know you)", () => {
+      expect(
+        computeTier({ facts: [], capabilities: [], conversationCount: 0 }),
+      ).toBe(1);
+    });
+
+    test("5 conversations + 3 facts -> tier 2 (Finding my footing)", () => {
+      expect(
+        computeTier({
+          facts: facts(3),
+          capabilities: [],
+          conversationCount: 5,
+        }),
+      ).toBe(2);
+    });
+
+    test("just below tier 2 threshold on facts -> still tier 1", () => {
+      expect(
+        computeTier({
+          facts: facts(2),
+          capabilities: [],
+          conversationCount: 5,
+        }),
+      ).toBe(1);
+    });
+
+    test("just below tier 2 threshold on conversations -> still tier 1", () => {
+      expect(
+        computeTier({
+          facts: facts(3),
+          capabilities: [],
+          conversationCount: 4,
+        }),
+      ).toBe(1);
+    });
+
+    test("20 conversations + 3 unlocked caps -> tier 3 (Hitting our stride)", () => {
+      expect(
+        computeTier({
+          facts: facts(5),
+          capabilities: unlockedCaps(3),
+          conversationCount: 20,
+        }),
+      ).toBe(3);
+    });
+
+    test("20 conversations + 2 unlocked caps -> tier 2 (fallthrough)", () => {
+      expect(
+        computeTier({
+          facts: facts(3),
+          capabilities: unlockedCaps(2),
+          conversationCount: 20,
+        }),
+      ).toBe(2);
+    });
+
+    test("tier 4 is reserved and unreachable from the default heuristic", () => {
+      // Even a fully-saturated input should not produce tier 4 today.
+      const result = computeTier({
+        facts: facts(50),
+        capabilities: unlockedCaps(6),
+        conversationCount: 1_000,
+      });
+      expect(result).not.toBe(4);
+      expect(result).toBe(3);
+    });
+  });
+});