@vellumai/assistant 0.6.3 → 0.6.4

package/src/home/__tests__/rollup-producer.test.ts

@@ -0,0 +1,398 @@
+/**
+ * Unit tests for the home-feed rollup producer.
+ *
+ * All dependencies are injected via `RollupProducerDeps` spies so the
+ * tests never touch `mock.module`, which leaks across files in Bun's
+ * test runner. The production caller passes `undefined` and the
+ * producer falls through to the real config loader, feed reader,
+ * relationship-state reader, and provider registry.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type {
+  ContentBlock,
+  Provider,
+  ProviderResponse,
+} from "../../providers/types.js";
+import type { WriteAssistantFeedItemParams } from "../assistant-feed-authoring.js";
+import type { FeedItem } from "../feed-types.js";
+import { runRollupProducer } from "../rollup-producer.js";
+
+const writeItem = mock<
+  (params: WriteAssistantFeedItemParams) => Promise<unknown>
+>(async () => ({}));
+
+const stubRelationshipState = async () =>
+  ({
+    version: 1,
+    assistantId: "self",
+    tier: 2,
+    progressPercent: 42,
+    facts: [
+      { category: "voice", text: "Ships fast, explains the why." },
+      { category: "priorities", text: "JARVIS is the current focus." },
+    ],
+    capabilities: [],
+    conversationCount: 17,
+    hatchedDate: "2026-03-01T00:00:00.000Z",
+    assistantName: "Vellum",
+    userName: "Alex",
+    updatedAt: "2026-04-14T12:00:00.000Z",
+    // biome-ignore lint/suspicious/noExplicitAny: the real shape is
+    // internal-only and we only need the subset the producer reads.
+  }) as any;
+
+function makeAction(overrides: Partial<FeedItem> & { id: string }): FeedItem {
+  return {
+    id: overrides.id,
+    type: "action",
+    priority: 50,
+    title: overrides.title ?? "Action title",
+    summary: overrides.summary ?? "Action summary.",
+    timestamp: overrides.timestamp ?? "2026-04-14T12:00:00.000Z",
+    status: overrides.status ?? "new",
+    author: overrides.author ?? "assistant",
+    createdAt: overrides.createdAt ?? "2026-04-14T12:00:00.000Z",
+    source: overrides.source,
+    expiresAt: overrides.expiresAt,
+    minTimeAway: overrides.minTimeAway,
+    actions: overrides.actions,
+  };
+}
+
+const stubLoadRecentActions = (items: FeedItem[]) => () => items;
+
+function makeProvider(
+  handler: (
+    messages: Parameters<Provider["sendMessage"]>[0],
+    tools: Parameters<Provider["sendMessage"]>[1],
+    systemPrompt: Parameters<Provider["sendMessage"]>[2],
+    options: Parameters<Provider["sendMessage"]>[3],
+  ) => Promise<ProviderResponse>,
+): Provider {
+  return {
+    name: "mock",
+    sendMessage: handler,
+  };
+}
+
+function scriptedProvider(content: ContentBlock[]): Provider {
+  return makeProvider(async () => ({
+    content,
+    model: "mock-model",
+    usage: { inputTokens: 0, outputTokens: 0 },
+    stopReason: "tool_use",
+  }));
+}
+
+function throwingProvider(error: Error): Provider {
+  return makeProvider(async () => {
+    throw error;
+  });
+}
+
+function toolUseContent(input: unknown): ContentBlock {
+  return {
+    type: "tool_use",
+    id: "tu_1",
+    name: "write_feed_items",
+    input: input as Record<string, unknown>,
+  };
+}
+
+const oneAction: FeedItem[] = [
+  makeAction({
+    id: "a1",
+    source: "gmail",
+    title: "Replied to Alice",
+    summary: "Sent a reply to alice@example.com.",
+    createdAt: "2026-04-14T11:30:00.000Z",
+  }),
+];
+
+beforeEach(() => {
+  writeItem.mockClear();
+});
+
+describe("runRollupProducer", () => {
+  test("writes each digest/thread returned in the tool call", async () => {
+    const provider = scriptedProvider([
+      toolUseContent({
+        items: [
+          {
+            type: "digest",
+            source: "gmail",
+            title: "3 replies sent this morning",
+            summary: "Replied to Alice, Bob, and Carol over the past hour.",
+            priority: 70,
+          },
+          {
+            type: "thread",
+            source: "assistant",
+            title: "Outreach sequence 'Q2 renewals'",
+            summary: "Step 1 sent to 2 of 5 contacts; awaiting replies.",
+            priority: 55,
+          },
+        ],
+      }),
+    ]);
+
+    const result = await runRollupProducer(new Date(), {
+      writeItem,
+      loadRelationshipState: stubRelationshipState,
+      loadRecentActions: stubLoadRecentActions(oneAction),
+      resolveProvider: () => provider,
+    });
+
+    expect(result.skippedReason).toBeNull();
+    expect(result.wroteCount).toBe(2);
+    expect(writeItem).toHaveBeenCalledTimes(2);
+    const firstCall = writeItem.mock.calls[0]![0];
+    expect(firstCall.type).toBe("digest");
+    expect(firstCall.title).toBe("3 replies sent this morning");
+    expect(firstCall.priority).toBe(70);
+  });
+
+  test("returns no_actions when the activity log is empty", async () => {
+    // When there's nothing to roll up, we don't even hit the provider.
+    // The scheduler uses this to avoid advancing the cooldown gate.
+    const provider = scriptedProvider([toolUseContent({ items: [] })]);
+    const providerSpy = mock(provider.sendMessage);
+    provider.sendMessage = providerSpy;
+
+    const result = await runRollupProducer(new Date(), {
+      writeItem,
+      loadRelationshipState: stubRelationshipState,
+      loadRecentActions: stubLoadRecentActions([]),
+      resolveProvider: () => provider,
+    });
+
+    expect(result.skippedReason).toBe("no_actions");
+    expect(result.wroteCount).toBe(0);
+    expect(providerSpy).not.toHaveBeenCalled();
+    expect(writeItem).not.toHaveBeenCalled();
+  });
+
+  test("serializes recent actions into the user prompt", async () => {
+    let capturedPrompt = "";
+    const provider = makeProvider(async (messages) => {
+      capturedPrompt = messages
+        .flatMap((m) => m.content)
+        .filter((b): b is { type: "text"; text: string } => b.type === "text")
+        .map((b) => b.text)
+        .join("\n");
+      return {
+        content: [toolUseContent({ items: [] })],
+        model: "mock-model",
+        usage: { inputTokens: 0, outputTokens: 0 },
+        stopReason: "tool_use",
+      };
+    });
+
+    const actions: FeedItem[] = [
+      makeAction({
+        id: "a1",
+        source: "gmail",
+        title: "Replied to Alice",
+        summary: "Sent a reply to alice@example.com.",
+        createdAt: "2026-04-14T11:30:00.000Z",
+      }),
+      makeAction({
+        id: "a2",
+        source: "slack",
+        title: "Posted in #general",
+        summary: "Answered a question about the deploy.",
+        createdAt: "2026-04-14T11:45:00.000Z",
+      }),
+    ];
+
+    await runRollupProducer(new Date(), {
+      writeItem,
+      loadRelationshipState: stubRelationshipState,
+      loadRecentActions: stubLoadRecentActions(actions),
+      resolveProvider: () => provider,
+    });
+
+    expect(capturedPrompt).toContain("Replied to Alice");
+    expect(capturedPrompt).toContain("alice@example.com");
+    expect(capturedPrompt).toContain("Posted in #general");
+    expect(capturedPrompt).toContain("[gmail]");
+    expect(capturedPrompt).toContain("[slack]");
+  });
+
+  test("returns empty_items when the model emits an empty items array", async () => {
+    const provider = scriptedProvider([toolUseContent({ items: [] })]);
+
+    const result = await runRollupProducer(new Date(), {
+      writeItem,
+      loadRelationshipState: stubRelationshipState,
+      loadRecentActions: stubLoadRecentActions(oneAction),
+      resolveProvider: () => provider,
+    });
+
+    expect(result.skippedReason).toBe("empty_items");
+    expect(result.wroteCount).toBe(0);
+    expect(writeItem).not.toHaveBeenCalled();
+  });
+
+  test("caps the batch at MAX_ITEMS_PER_ROLLUP (3)", async () => {
+    const provider = scriptedProvider([
+      toolUseContent({
+        items: [
+          { type: "digest", title: "One", summary: "One summary" },
+          { type: "digest", title: "Two", summary: "Two summary" },
+          { type: "thread", title: "Three", summary: "Three summary" },
+          {
+            type: "digest",
+            title: "Four",
+            summary: "Four summary — should be dropped.",
+          },
+        ],
+      }),
+    ]);
+
+    const result = await runRollupProducer(new Date(), {
+      writeItem,
+      loadRelationshipState: stubRelationshipState,
+      loadRecentActions: stubLoadRecentActions(oneAction),
+      resolveProvider: () => provider,
+    });
+
+    expect(result.wroteCount).toBe(3);
+    expect(writeItem).toHaveBeenCalledTimes(3);
+  });
+
+  test("rejects nudge and action types at coercion time", async () => {
+    // The tool schema narrows `type` to digest/thread, but the runtime
+    // coercion enforces it too so a drifted model can't sneak through.
+    const provider = scriptedProvider([
+      toolUseContent({
+        items: [
+          {
+            type: "nudge",
+            title: "Should be rejected",
+            summary: "Rollup must never emit nudges.",
+          },
+          {
+            type: "action",
+            title: "Also rejected",
+            summary: "Rollup must never emit actions.",
+          },
+          {
+            type: "digest",
+            title: "Valid digest",
+            summary: "This one should land.",
+          },
+        ],
+      }),
+    ]);
+
+    const result = await runRollupProducer(new Date(), {
+      writeItem,
+      loadRelationshipState: stubRelationshipState,
+      loadRecentActions: stubLoadRecentActions(oneAction),
+      resolveProvider: () => provider,
+    });
+
+    expect(result.wroteCount).toBe(1);
+    expect(writeItem).toHaveBeenCalledTimes(1);
+    expect(writeItem.mock.calls[0]![0].title).toBe("Valid digest");
+  });
+
+  test("reports malformed_output when every item in a non-empty batch fails coercion", async () => {
+    const provider = scriptedProvider([
+      toolUseContent({
+        items: [
+          { type: "digest", title: "", summary: "empty title, rejected" },
+          { type: "bogus", title: "bad type", summary: "also rejected" },
+          { type: "digest", title: "valid title" }, // missing summary
+        ],
+      }),
+    ]);
+
+    const result = await runRollupProducer(new Date(), {
+      writeItem,
+      loadRelationshipState: stubRelationshipState,
+      loadRecentActions: stubLoadRecentActions(oneAction),
+      resolveProvider: () => provider,
+    });
+
+    expect(result.skippedReason).toBe("malformed_output");
+    expect(result.wroteCount).toBe(0);
+    expect(writeItem).not.toHaveBeenCalled();
+  });
+
+  test("returns no_provider when the resolver returns null", async () => {
+    const result = await runRollupProducer(new Date(), {
+      writeItem,
+      loadRelationshipState: stubRelationshipState,
+      loadRecentActions: stubLoadRecentActions(oneAction),
+      resolveProvider: () => null,
+    });
+
+    expect(result.skippedReason).toBe("no_provider");
+    expect(result.wroteCount).toBe(0);
+    expect(writeItem).not.toHaveBeenCalled();
+  });
+
+  test("returns provider_error when sendMessage throws", async () => {
+    const provider = throwingProvider(new Error("network down"));
+
+    const result = await runRollupProducer(new Date(), {
+      writeItem,
+      loadRelationshipState: stubRelationshipState,
+      loadRecentActions: stubLoadRecentActions(oneAction),
+      resolveProvider: () => provider,
+    });
+
+    expect(result.skippedReason).toBe("provider_error");
+    expect(result.wroteCount).toBe(0);
+  });
+
+  test("returns malformed_output when the response has no matching tool_use block", async () => {
+    const provider = scriptedProvider([{ type: "text", text: "just prose" }]);
+
+    const result = await runRollupProducer(new Date(), {
+      writeItem,
+      loadRelationshipState: stubRelationshipState,
+      loadRecentActions: stubLoadRecentActions(oneAction),
+      resolveProvider: () => provider,
+    });
+
+    expect(result.skippedReason).toBe("malformed_output");
+    expect(result.wroteCount).toBe(0);
+  });
+
+  test("clamps priority to the valid [0, 100] window", async () => {
+    const provider = scriptedProvider([
+      toolUseContent({
+        items: [
+          {
+            type: "digest",
+            title: "High priority",
+            summary: "Model returned 150",
+            priority: 150,
+          },
+          {
+            type: "thread",
+            title: "Low priority",
+            summary: "Model returned -5",
+            priority: -5,
+          },
+        ],
+      }),
+    ]);
+
+    await runRollupProducer(new Date(), {
+      writeItem,
+      loadRelationshipState: stubRelationshipState,
+      loadRecentActions: stubLoadRecentActions(oneAction),
+      resolveProvider: () => provider,
+    });
+
+    expect(writeItem).toHaveBeenCalledTimes(2);
+    expect(writeItem.mock.calls[0]![0].priority).toBe(100);
+    expect(writeItem.mock.calls[1]![0].priority).toBe(0);
+  });
+});

package/src/home/assistant-feed-authoring.ts

@@ -0,0 +1,124 @@
+/**
+ * Assistant-authoring helper for the home activity feed.
+ *
+ * This is the in-process API the assistant daemon (or a skill / tool
+ * running inside it) calls to append a nudge, digest, action, or
+ * thread to the macOS Home page feed under `author: "assistant"`.
+ *
+ * The helper exists so callers don't have to hand-roll the ceremony
+ * around a `FeedItem`:
+ *
+ *   - generate a stable `id`
+ *   - set the `author` discriminator to `"assistant"` (so the hybrid
+ *     authoring resolver in `feed-writer.ts` lets it override
+ *     platform baseline items for the same `(type, source)` pair)
+ *   - seed `status` / `timestamp` / `createdAt`
+ *   - pick a sensible default `priority` that outranks the platform
+ *     baseline (40) so assistant-authored items surface above
+ *     background generators unless an explicit priority is passed
+ *   - validate the constructed item against `feedItemSchema` so a
+ *     malformed call throws loudly at the source instead of corrupting
+ *     the on-disk snapshot via `appendFeedItem`
+ *
+ * Persistence is delegated to `appendFeedItem` — all of the merge
+ * semantics (digest replacement, thread in-place update, nudge author
+ * precedence, action append-without-replace, per-source action cap)
+ * continue to live in the writer and are not re-implemented here.
+ *
+ * NOTE: This helper is intentionally in-process only. There is no
+ * HTTP route wrapping it. Callers (skills, tools, daemon code) import
+ * and call `writeAssistantFeedItem` directly. Wiring the trigger side
+ * — prompt-driven calls, skill entry points, etc. — is deliberately
+ * out of scope for Phase 5 of the home-activity-feed plan and lives
+ * in follow-up work.
+ */
+
+import { randomUUID } from "node:crypto";
+
+import {
+  type FeedAction,
+  type FeedItem,
+  feedItemSchema,
+  type FeedItemSource,
+  type FeedItemType,
+} from "./feed-types.js";
+import { appendFeedItem } from "./feed-writer.js";
+
+/**
+ * Default priority for assistant-authored feed items. Sits above the
+ * platform baseline (40) so an assistant-authored digest / nudge
+ * surfaces above a same-source platform default unless the caller
+ * passes an explicit value.
+ */
+const DEFAULT_ASSISTANT_PRIORITY = 60;
+
+/**
+ * Parameters accepted by {@link writeAssistantFeedItem}.
+ *
+ * The helper hard-codes `author: "assistant"`, `status: "new"`, and
+ * the id / timestamps, so callers only have to supply the semantic
+ * fields that describe *what* the item is about.
+ */
+export interface WriteAssistantFeedItemParams {
+  /** Kind of feed item — drives the Swift view used to render it. */
+  type: FeedItemType;
+  /** Origin of the underlying event (gmail, slack, calendar, assistant). */
+  source?: FeedItemSource;
+  /** Short headline rendered in the feed row. */
+  title: string;
+  /** Body copy rendered below the title. */
+  summary: string;
+  /**
+   * Priority in [0, 100]. Defaults to {@link DEFAULT_ASSISTANT_PRIORITY}
+   * (60) — higher than the platform baseline of 40 so assistant items
+   * beat same-source platform defaults by default.
+   */
+  priority?: number;
+  /** Action buttons surfaced on the feed row. */
+  actions?: FeedAction[];
+  /** Minimum seconds the user must be away before the item is shown. */
+  minTimeAway?: number;
+  /** Absolute ISO-8601 expiry timestamp. */
+  expiresAt?: string;
+}
+
+/**
+ * Build a fully-formed assistant-authored {@link FeedItem}, validate
+ * it against the canonical schema, persist it through
+ * {@link appendFeedItem}, and return the constructed item so the
+ * caller can log / reference it downstream.
+ *
+ * Throws a `ZodError` if the constructed item fails validation —
+ * that is a programming error in the caller (e.g. empty `title`) and
+ * must not be silently swallowed. Persistence-layer failures are
+ * absorbed by `appendFeedItem` itself per its warn-log contract.
+ */
+export async function writeAssistantFeedItem(
+  params: WriteAssistantFeedItemParams,
+): Promise<FeedItem> {
+  const now = new Date().toISOString();
+
+  const item: FeedItem = {
+    id: randomUUID(),
+    type: params.type,
+    source: params.source,
+    title: params.title,
+    summary: params.summary,
+    priority: params.priority ?? DEFAULT_ASSISTANT_PRIORITY,
+    status: "new",
+    author: "assistant",
+    timestamp: now,
+    createdAt: now,
+    actions: params.actions,
+    minTimeAway: params.minTimeAway,
+    expiresAt: params.expiresAt,
+  };
+
+  // Programming-error guardrail: invalid input throws at the source
+  // instead of corrupting the on-disk snapshot via the writer.
+  feedItemSchema.parse(item);
+
+  await appendFeedItem(item);
+
+  return item;
+}

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

@@ -0,0 +1,158 @@
+/**
+ * Background-job → home feed event helper.
+ *
+ * The "force-write, not taught-write" entry point for the activity
+ * log. Every background job that wants to surface something on the
+ * Home page calls `emitFeedEvent({ source, title, summary, ... })`
+ * at the end of its completion path — no LLM involved, no prompt
+ * instruction, just a deterministic side effect. This keeps the
+ * "what got surfaced" question grep-able to a single symbol.
+ *
+ * Opinionated defaults for action items:
+ *
+ *   - `type` is hard-coded to `"action"` — this helper is specifically
+ *     for the activity log. Nudges / digests / threads continue to
+ *     go through `writeAssistantFeedItem` or platform baseline
+ *     generators.
+ *   - `author` is hard-coded to `"assistant"` so hybrid authoring
+ *     resolution treats these as assistant-produced (platform
+ *     defaults can never overwrite them).
+ *   - `source` is REQUIRED — actions always have an origin (gmail,
+ *     slack, calendar, assistant). The per-source volume cap in
+ *     `feed-writer.ts` depends on this.
+ *   - No default `expiresAt`. Action items persist until the user
+ *     dismisses them. Callers that want auto-expiry pass `expiresAt`
+ *     explicitly.
+ *   - Optional `dedupKey` — when set, the helper derives a
+ *     deterministic id so a second emit for the same logical event
+ *     (e.g. the same background job running twice on the same
+ *     signal) updates the existing entry in place instead of
+ *     appending a duplicate. When absent, a fresh `randomUUID` is
+ *     used and every call produces a new entry.
+ *
+ * Persistence goes through `appendFeedItem`, inheriting its
+ * warn-log-on-failure contract — callers never need a try/catch.
+ * Schema validation runs at build time so a malformed call throws
+ * loudly at the source rather than silently corrupting the file.
+ */
+
+import { randomUUID } from "node:crypto";
+
+import {
+  type FeedAction,
+  type FeedItem,
+  feedItemSchema,
+  type FeedItemSource,
+} from "./feed-types.js";
+import { appendFeedItem } from "./feed-writer.js";
+
+/**
+ * Default priority for background-job action items. Sits below the
+ * assistant nudge default (60) so an explicit nudge from
+ * `writeAssistantFeedItem` surfaces above routine activity log
+ * entries, but above the platform baseline (40) so background job
+ * traces outrank same-source platform defaults.
+ */
+const DEFAULT_EMIT_PRIORITY = 50;
+
+/**
+ * Parameters accepted by {@link emitFeedEvent}.
+ *
+ * All action items emitted by background jobs have an origin, so
+ * `source` is required. Everything else is optional — callers supply
+ * only the fields that describe the specific event.
+ */
+export interface EmitFeedEventParams {
+  /** Origin of the underlying event (gmail, slack, calendar, assistant). */
+  source: FeedItemSource;
+  /** Short headline rendered in the feed row. */
+  title: string;
+  /** Body copy rendered below the title. */
+  summary: string;
+  /**
+   * Stable key used to derive a deterministic id so a second emit
+   * for the same logical event updates the existing feed entry in
+   * place. Should include enough structure to identify the event
+   * uniquely (e.g. `"gmail-unread:msg-<messageId>"`,
+   * `"task-runner:<taskId>"`). When omitted, every call produces a
+   * fresh id and appends a new entry.
+   */
+  dedupKey?: string;
+  /**
+   * Priority in [0, 100]. Defaults to {@link DEFAULT_EMIT_PRIORITY}
+   * (50) — above the platform baseline of 40, below the assistant
+   * nudge default of 60.
+   */
+  priority?: number;
+  /** Action buttons surfaced on the feed row. */
+  actions?: FeedAction[];
+  /** Minimum seconds the user must be away before the item is shown. */
+  minTimeAway?: number;
+  /**
+   * Absolute ISO-8601 expiry timestamp. Omit to let the item persist
+   * until the user dismisses it (default for activity-log actions).
+   */
+  expiresAt?: string;
+}
+
+/**
+ * Build a deterministic feed item id from a source + dedup key.
+ *
+ * The id is intentionally human-readable: `emit:<source>:<dedupKey>`.
+ * This makes debugging easier than a hash (you can eyeball the file
+ * and immediately see which background job produced which entry)
+ * and `FeedItem.id` is a free-form string so there is no length or
+ * charset constraint to worry about.
+ */
+function deterministicId(source: FeedItemSource, dedupKey: string): string {
+  return `emit:${source}:${dedupKey}`;
+}
+
+/**
+ * Emit a background-job activity-log entry onto the home feed.
+ *
+ * Builds a fully-formed assistant-authored `action` {@link FeedItem},
+ * validates it against the canonical schema, and persists it via
+ * {@link appendFeedItem}. Returns the constructed item so the caller
+ * can log / reference it downstream.
+ *
+ * Throws a `ZodError` if the constructed item fails validation
+ * (e.g. a `priority` outside `[0, 100]`) — a programming error in
+ * the caller that must not be silently swallowed. Persistence-layer
+ * failures are absorbed by `appendFeedItem` per its warn-log
+ * contract.
+ */
+export async function emitFeedEvent(
+  params: EmitFeedEventParams,
+): Promise<FeedItem> {
+  const now = new Date().toISOString();
+
+  const id =
+    params.dedupKey !== undefined
+      ? deterministicId(params.source, params.dedupKey)
+      : randomUUID();
+
+  const item: FeedItem = {
+    id,
+    type: "action",
+    source: params.source,
+    title: params.title,
+    summary: params.summary,
+    priority: params.priority ?? DEFAULT_EMIT_PRIORITY,
+    status: "new",
+    author: "assistant",
+    timestamp: now,
+    createdAt: now,
+    actions: params.actions,
+    minTimeAway: params.minTimeAway,
+    expiresAt: params.expiresAt,
+  };
+
+  // Programming-error guardrail: invalid input throws at the source
+  // instead of corrupting the on-disk snapshot via the writer.
+  feedItemSchema.parse(item);
+
+  await appendFeedItem(item);
+
+  return item;
+}