@vellumai/assistant 0.7.1 → 0.7.3

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

@@ -0,0 +1,99 @@
+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 ────────────────────────────────────────────
+const publishSpy = mock<(event: unknown) => Promise<void>>(async () => {});
+
+mock.module("../../runtime/assistant-event-hub.js", () => ({
+  assistantEventHub: {
+    publish: publishSpy,
+    subscribe: () => () => {},
+  },
+}));
+
+const { emitPostConnectNudge } = await import("../post-connect-feed.js");
+const { readHomeFeed } = await import("../feed-writer.js");
+
+// ─── tmpdir workspace lifecycle ────────────────────────────────────────
+
+let workspaceDir: string;
+let origWorkspaceDir: string | undefined;
+
+beforeEach(() => {
+  workspaceDir = mkdtempSync(join(tmpdir(), "vellum-pcf-"));
+  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("emitPostConnectNudge", () => {
+  test("emits a nudge feed item for google", async () => {
+    await emitPostConnectNudge("google");
+
+    const feed = readHomeFeed();
+    expect(feed.items).toHaveLength(1);
+
+    const item = feed.items[0]!;
+    expect(item.id).toBe("connect-nudge:google");
+    expect(item.type).toBe("nudge");
+    expect(item.source).toBe("gmail");
+    expect(item.title).toContain("Gmail connected");
+    expect(item.actions).toHaveLength(2);
+    expect(item.actions![0]!.label).toBe("Triage my inbox");
+    expect(item.actions![1]!.label).toBe("Set up daily digest");
+    expect(item.expiresAt).toBeDefined();
+    expect(item.author).toBe("platform");
+  });
+
+  test("no-ops for non-email services", async () => {
+    await emitPostConnectNudge("slack");
+    await emitPostConnectNudge("notion");
+    await emitPostConnectNudge("linear");
+
+    const feed = readHomeFeed();
+    expect(feed.items).toHaveLength(0);
+  });
+
+  test("reconnecting appends a second nudge (same-author nudges don't deduplicate)", async () => {
+    await emitPostConnectNudge("google");
+    await emitPostConnectNudge("google");
+
+    const feed = readHomeFeed();
+    // Same-author (platform) same-source nudges both persist —
+    // the feed writer's author-resolution only handles cross-author
+    // replacement. In practice, reconnects are rare and the 7-day
+    // expiry prevents buildup.
+    expect(feed.items).toHaveLength(2);
+    expect(feed.items.every((i) => i.id === "connect-nudge:google")).toBe(true);
+  });
+
+  test("nudge expires after 7 days", async () => {
+    await emitPostConnectNudge("google");
+
+    const feed = readHomeFeed();
+    const item = feed.items[0]!;
+    const created = new Date(item.createdAt).getTime();
+    const expires = new Date(item.expiresAt!).getTime();
+    const sevenDaysMs = 7 * 24 * 60 * 60 * 1000;
+
+    // Allow 1 second tolerance for test execution time
+    expect(Math.abs(expires - created - sevenDaysMs)).toBeLessThan(1000);
+  });
+});

package/src/home/__tests__/relationship-state-writer.test.ts

@@ -432,6 +432,12 @@ describe("relationship-state-writer", () => {
       // Also sanity: it must be a real, recent date (not the epoch
       // sentinel we emit when stat fails).
       expect(Date.parse(first.hatchedDate)).toBeGreaterThan(0);
+      const sidecarPath = join(workspaceDir, "data", "hatched.json");
+      expect(existsSync(sidecarPath)).toBe(true);
+      const sidecar = JSON.parse(readFileSync(sidecarPath, "utf-8")) as {
+        hatchedAt: string;
+      };
+      expect(sidecar.hatchedAt).toBe(first.hatchedDate);
     });
 
     test("honors an explicit Hatched bullet in IDENTITY.md over file birthtime", async () => {
@@ -488,9 +494,10 @@ describe("relationship-state-writer", () => {
       expect(state.hatchedDate).toBe("2025-01-15T00:00:00.000Z");
     });
 
-    test("IDENTITY.md birthtime takes precedence over the sidecar", async () => {
-      // Seed a stale sidecar and then an IDENTITY.md without an
-      // explicit Hatched bullet — birthtime wins over the sidecar.
+    test("sidecar takes precedence over IDENTITY.md metadata", async () => {
+      // Seed an existing sidecar and then an IDENTITY.md without an
+      // explicit Hatched bullet — the persisted sidecar wins so the
+      // date remains stable across later identity edits.
       mkdirSync(join(workspaceDir, "data"), { recursive: true });
       writeFileSync(
         join(workspaceDir, "data", "hatched.json"),
@@ -500,12 +507,7 @@ describe("relationship-state-writer", () => {
       writeFile("IDENTITY.md", "- **Name:** Sage\n- **Role:** Assistant\n");
 
       const state = (await computeRelationshipState()) as RelationshipStateLike;
-      // The sidecar value is 2020-06-01 but IDENTITY.md was just
-      // written, so birthtime will be a much more recent date.
-      expect(state.hatchedDate).not.toBe("2020-06-01T00:00:00.000Z");
-      expect(Date.parse(state.hatchedDate)).toBeGreaterThan(
-        Date.parse("2020-06-01T00:00:00.000Z"),
-      );
+      expect(state.hatchedDate).toBe("2020-06-01T00:00:00.000Z");
     });
   });
 

package/src/home/__tests__/suggested-prompts.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, mock, test } from "bun:test";
+
+// ─── Mocks ─────────────────────────────────────────────────────────────
+
+let mockConnectedProviders = new Set<string>();
+
+mock.module("../../oauth/oauth-store.js", () => ({
+  isProviderConnected: async (provider: string) =>
+    mockConnectedProviders.has(provider),
+  listProviders: () => [
+    { provider: "google" },
+    { provider: "slack" },
+    { provider: "notion" },
+    { provider: "linear" },
+    { provider: "github" },
+  ],
+}));
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+const { getSuggestedPrompts } = await import("../suggested-prompts.js");
+
+// ─── Tests ─────────────────────────────────────────────────────────────
+
+describe("getSuggestedPrompts", () => {
+  test("shows 'Connect X' prompts when providers are disconnected", async () => {
+    mockConnectedProviders = new Set();
+
+    const prompts = await getSuggestedPrompts();
+    const ids = prompts.map((p) => p.id);
+
+    expect(ids).toContain("connect-google");
+    expect(ids).toContain("connect-slack");
+    expect(prompts.find((p) => p.id === "connect-google")!.label).toBe(
+      "Connect Gmail",
+    );
+  });
+
+  test("shows email management prompts when Google is connected", async () => {
+    mockConnectedProviders = new Set(["google"]);
+
+    const prompts = await getSuggestedPrompts();
+    const ids = prompts.map((p) => p.id);
+
+    // Should NOT show "Connect Gmail"
+    expect(ids).not.toContain("connect-google");
+
+    // Should show management prompts
+    expect(ids).toContain("manage-google-triage-my-inbox");
+    expect(ids).toContain("manage-google-summarize-today's-emails");
+
+    const triage = prompts.find(
+      (p) => p.id === "manage-google-triage-my-inbox",
+    );
+    expect(triage).toBeDefined();
+    expect(triage!.label).toBe("Triage my inbox");
+    expect(triage!.icon).toBe("mail");
+    expect(triage!.source).toBe("deterministic");
+  });
+
+  test("still shows Connect prompts for disconnected providers alongside management prompts", async () => {
+    mockConnectedProviders = new Set(["google"]);
+
+    const prompts = await getSuggestedPrompts();
+    const ids = prompts.map((p) => p.id);
+
+    // Gmail management prompts
+    expect(ids).toContain("manage-google-triage-my-inbox");
+    // Slack still disconnected
+    expect(ids).toContain("connect-slack");
+  });
+
+  test("providers without connectedPrompts show nothing when connected", async () => {
+    mockConnectedProviders = new Set(["slack"]);
+
+    const prompts = await getSuggestedPrompts();
+    const ids = prompts.map((p) => p.id);
+
+    // No connect prompt since connected
+    expect(ids).not.toContain("connect-slack");
+    // No management prompts since Slack doesn't define any
+    expect(ids.filter((id) => id.startsWith("manage-slack"))).toHaveLength(0);
+  });
+});

package/src/home/feed-scheduler.ts

@@ -28,6 +28,11 @@
  *     scheduler needing to touch the event hub.
  */
 
+import {
+  checkDiskPressureBackgroundGate,
+  diskPressureBackgroundSkipLogFields,
+  shouldLogDiskPressureBackgroundSkip,
+} from "../daemon/disk-pressure-background-gate.js";
 import { getLogger } from "../util/logger.js";
 import type { FeedItem } from "./feed-types.js";
 import {
@@ -119,6 +124,19 @@ export function startFeedScheduler(
       rollupRan: false,
     };
     if (stopped || tickRunning) return summary;
+    const diskPressureGate = checkDiskPressureBackgroundGate("background-work");
+    if (diskPressureGate.action === "skip") {
+      if (shouldLogDiskPressureBackgroundSkip("home-feed-scheduler")) {
+        log.warn(
+          {
+            source: "feed-scheduler",
+            ...diskPressureBackgroundSkipLogFields(diskPressureGate),
+          },
+          "Home feed scheduler skipped during disk pressure cleanup mode",
+        );
+      }
+      return summary;
+    }
     tickRunning = true;
     const nowMs = now.getTime();
     try {

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

@@ -0,0 +1,68 @@
+/**
+ * Post-connection feed nudge.
+ *
+ * Emits a one-time nudge feed item when the user successfully connects
+ * an email-capable OAuth provider. The nudge highlights ongoing email
+ * management capabilities (inbox triage, daily digests) so the user
+ * discovers what they can do beyond the initial setup.
+ *
+ * Uses a deterministic id (`connect-nudge:<service>`) so reconnecting
+ * the same provider replaces the existing nudge in place rather than
+ * appending a duplicate.
+ */
+
+import type { FeedItem } from "./feed-types.js";
+import { appendFeedItem } from "./feed-writer.js";
+
+/**
+ * Services that should trigger an email management nudge on connection.
+ * Only providers with real email integration are listed — see
+ * `relationship-state-writer.ts` for the same "only Gmail is real" note.
+ */
+const EMAIL_SERVICES = new Set(["google"]);
+
+/**
+ * Emit a feed nudge for a newly connected email provider.
+ *
+ * No-ops silently when the service is not email-capable. Never throws —
+ * the feed writer's warn-log contract absorbs persistence failures.
+ */
+export async function emitPostConnectNudge(service: string): Promise<void> {
+  if (!EMAIL_SERVICES.has(service)) return;
+
+  const now = new Date();
+  const expiresAt = new Date(
+    now.getTime() + 7 * 24 * 60 * 60 * 1000,
+  ).toISOString();
+
+  const item: FeedItem = {
+    id: `connect-nudge:${service}`,
+    type: "nudge",
+    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",
+    expiresAt,
+    author: "platform",
+    createdAt: now.toISOString(),
+    actions: [
+      {
+        id: "inbox-triage",
+        label: "Triage my inbox",
+        prompt:
+          "Help me triage my inbox — summarize what's unread and flag anything that needs a reply",
+      },
+      {
+        id: "daily-digest",
+        label: "Set up daily digest",
+        prompt:
+          "Set up a daily email digest that summarizes my unread messages each morning",
+      },
+    ],
+  };
+
+  await appendFeedItem(item);
+}

package/src/home/relationship-state-writer.ts

@@ -18,13 +18,7 @@
  * a missing or unreadable file degrades gracefully to an empty string.
  */
 
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  statSync,
-  writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { countConversations as countConversationsDb } from "../memory/conversation-queries.js";
@@ -39,6 +33,7 @@ import {
   getWorkspaceDir,
   getWorkspacePromptPath,
 } from "../util/platform.js";
+import { resolveAndPersistHatchedAt } from "../workspace/hatched-date.js";
 import { computeProgressPercent, computeTier } from "./progress-formula.js";
 import {
   type Capability,
@@ -149,11 +144,12 @@ function readOnboardingSidecar(): OnboardingContext | null {
  * Reads USER.md / SOUL.md / IDENTITY.md, queries the oauth connection
  * store, and counts conversations via the DB-authoritative helper.
  *
- * Side effect: on the very first call when IDENTITY.md cannot provide
- * a hatched date, `resolveFallbackHatchedDate` persists a one-time
- * `data/hatched.json` sidecar so subsequent calls return a monotonic
- * timestamp. All other paths are read-only. Callers that want to
- * persist the full snapshot should use `writeRelationshipState()`.
+ * Side effect: on the very first call without an explicit Hatched
+ * bullet or existing hatched sidecar, the shared resolver persists a
+ * one-time `data/hatched.json` value seeded from IDENTITY.md metadata
+ * or a real current timestamp. All other paths are read-only. Callers
+ * that want to persist the full snapshot should use
+ * `writeRelationshipState()`.
  */
 export async function computeRelationshipState(): Promise<RelationshipState> {
   // Persona source-of-truth:
@@ -682,74 +678,17 @@ function countConversations(): number {
   }
 }
 
-/**
- * Filename for the hatched-date sidecar, used as a stable fallback
- * when IDENTITY.md is missing / unreadable / has no explicit hatched
- * bullet and file stat is unavailable. Lives under the workspace
- * data dir alongside `relationship-state.json`.
- */
-const HATCHED_SIDECAR_FILENAME = "hatched.json";
-
-function getHatchedSidecarPath(): string {
-  return join(getDataDir(), HATCHED_SIDECAR_FILENAME);
-}
-
-/**
- * Resolve a stable hatched-date fallback timestamp.
- *
- * The Swift client, OpenAPI schema, and UI have no special handling
- * for a Unix-epoch sentinel — they'll render "1/1/1970" to the user.
- * Instead, we use `new Date().toISOString()` the first time a
- * fallback is needed and persist it to a small sidecar file
- * (`data/hatched.json`). Subsequent calls read the sidecar first, so
- * the returned timestamp is monotonic across writes and the
- * `hatchedDate` field never drifts once initialized.
- *
- * Never throws — a sidecar read/write failure still yields a valid
- * (though non-stable) `now` timestamp, which is still far better than
- * the epoch sentinel.
- */
-function resolveFallbackHatchedDate(): string {
-  const path = getHatchedSidecarPath();
-  try {
-    if (existsSync(path)) {
-      const parsed = JSON.parse(readFileSync(path, "utf-8")) as {
-        hatchedAt?: string;
-      };
-      if (parsed.hatchedAt && !isNaN(Date.parse(parsed.hatchedAt))) {
-        return parsed.hatchedAt;
-      }
-    }
-  } catch {
-    // Fall through to write a fresh sidecar.
-  }
-  const now = new Date().toISOString();
-  try {
-    mkdirSync(getDataDir(), { recursive: true });
-    writeFileSync(path, JSON.stringify({ hatchedAt: now }, null, 2), "utf-8");
-  } catch {
-    // If even the sidecar write fails, return `now` anyway — the
-    // caller will just get a fresh-looking date on every call. Not
-    // ideal, but far better than the epoch sentinel.
-  }
-  return now;
-}
-
 /**
  * Pull `assistantName` and `hatchedDate` from IDENTITY.md.
  *
  * IDENTITY.md is a freeform markdown file, so for the name we scan
  * bullet lines for any recognizable `name` label (`Name`,
  * `Assistant Name`, `Preferred Name`, etc.). For the hatched date we
- * prefer any explicit `hatched:` / `birth:` bullet, then fall back to
- * the file's `stat.birthtime` (matching the pattern already
- * established by `identity-routes.ts`), and finally to `stat.mtime`
- * if birthtime is unavailable. We never fall back to `new Date()`
- * directly — `writeRelationshipState()` is called on every turn
- * boundary, so a raw `Date.now()` fallback would cause `hatchedDate`
- * to drift forward on every write. Instead, when nothing else is
- * readable we resolve via `resolveFallbackHatchedDate()` which
- * persists a stable timestamp to a sidecar file on first use.
+ * prefer any explicit `hatched:` / `birth:` bullet, then use the
+ * shared hatched-date resolver. That resolver reads an existing
+ * `data/hatched.json` sidecar first, otherwise seeds it from valid
+ * IDENTITY.md birthtime/mtime or a real current timestamp. This keeps
+ * `hatchedDate` stable without writing from read-only HTTP handlers.
  */
 function parseIdentity(identityPath: string): {
   assistantName: string;
@@ -792,24 +731,10 @@ function parseIdentity(identityPath: string): {
     return { assistantName, hatchedDate: explicitHatched };
   }
 
-  // Stable fallback: use the IDENTITY.md file birth time so the
-  // relationship start date is monotonic across turns. Matches the
-  // approach used by `identity-routes.ts` for the Settings UI.
-  try {
-    const stats = statSync(identityPath);
-    const candidate =
-      stats.birthtime.getTime() > 0 ? stats.birthtime : stats.mtime;
-    if (candidate.getTime() > 0) {
-      return { assistantName, hatchedDate: candidate.toISOString() };
-    }
-  } catch {
-    // File missing or unreadable — fall through to the sidecar.
-  }
-
-  // Last-ditch fallback: `resolveFallbackHatchedDate` returns a stable,
-  // real timestamp (persisted to `data/hatched.json` on first call) so
-  // the wire contract always carries a valid ISO date.
-  return { assistantName, hatchedDate: resolveFallbackHatchedDate() };
+  return {
+    assistantName,
+    hatchedDate: resolveAndPersistHatchedAt(identityPath),
+  };
 }
 
 /**

package/src/home/suggested-prompts.ts

@@ -21,14 +21,34 @@ const log = getLogger("suggested-prompts");
  * listed here produce deterministic "Connect X" prompts when disconnected.
  * The icon values are VIcon case names rendered by the macOS client.
  */
+interface PromptEntry {
+  label: string;
+  prompt: string;
+  icon: string;
+}
+
 const CONNECT_PROMPT_META: Record<
   string,
-  { label: string; prompt: string; icon: string }
+  PromptEntry & { connectedPrompts?: PromptEntry[] }
 > = {
   google: {
     label: "Connect Gmail",
     prompt: "Help me connect my Gmail account",
     icon: "mail",
+    connectedPrompts: [
+      {
+        label: "Triage my inbox",
+        prompt:
+          "Help me triage my inbox — summarize what's unread and flag anything that needs a reply",
+        icon: "mail",
+      },
+      {
+        label: "Summarize today's emails",
+        prompt:
+          "Summarize the emails I received today and highlight anything important",
+        icon: "mail",
+      },
+    ],
   },
   slack: {
     label: "Connect Slack",
@@ -75,7 +95,9 @@ export async function getSuggestedPrompts(): Promise<SuggestedPrompt[]> {
 
 /**
  * Check which well-known OAuth providers are not connected and return
- * a "Connect X" prompt for each.
+ * a "Connect X" prompt for each. For connected providers that have
+ * `connectedPrompts`, return those instead so users discover ongoing
+ * management capabilities.
  */
 async function getDeterministicPrompts(): Promise<SuggestedPrompt[]> {
   const providers = listProviders();
@@ -86,15 +108,29 @@ async function getDeterministicPrompts(): Promise<SuggestedPrompt[]> {
     if (!meta) continue;
 
     const connected = await isProviderConnected(provider.provider);
-    if (connected) continue;
 
-    prompts.push({
-      id: `connect-${provider.provider}`,
-      label: meta.label,
-      icon: meta.icon,
-      prompt: meta.prompt,
-      source: "deterministic",
-    });
+    if (!connected) {
+      prompts.push({
+        id: `connect-${provider.provider}`,
+        label: meta.label,
+        icon: meta.icon,
+        prompt: meta.prompt,
+        source: "deterministic",
+      });
+      continue;
+    }
+
+    if (meta.connectedPrompts) {
+      for (const cp of meta.connectedPrompts) {
+        prompts.push({
+          id: `manage-${provider.provider}-${cp.label.toLowerCase().replace(/\s+/g, "-")}`,
+          label: cp.label,
+          icon: cp.icon,
+          prompt: cp.prompt,
+          source: "deterministic",
+        });
+      }
+    }
   }
 
   return prompts;

package/src/inbound/platform-callback-registration.ts

@@ -16,11 +16,7 @@
  * callback_url that external services should use.
  */
 
-import {
-  getPlatformAssistantId,
-  getPlatformBaseUrl,
-  getPlatformInternalApiKey,
-} from "../config/env.js";
+import { getPlatformAssistantId, getPlatformBaseUrl } from "../config/env.js";
 import { getIsPlatform } from "../config/env-registry.js";
 import { credentialKey } from "../security/credential-key.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
@@ -32,7 +28,6 @@ export interface PlatformCallbackRegistrationContext {
   isPlatform: boolean;
   platformBaseUrl: string;
   assistantId: string;
-  hasInternalApiKey: boolean;
   hasAssistantApiKey: boolean;
   authHeader: string | null;
   enabled: boolean;
@@ -54,20 +49,18 @@ export async function resolvePlatformCallbackRegistrationContext(): Promise<Plat
   );
   const assistantId =
     getPlatformAssistantId().trim() || storedAssistantIdRaw?.trim() || "";
-  const internalApiKey = getPlatformInternalApiKey().trim();
-  const assistantApiKey = storedAssistantApiKeyRaw?.trim() || "";
-  const authHeader = internalApiKey
-    ? `Bearer ${internalApiKey}`
-    : assistantApiKey
-      ? `Api-Key ${assistantApiKey}`
-      : null;
+  const envAssistantCredential = process.env.ASSISTANT_API_KEY?.trim();
+  const assistantCredential =
+    storedAssistantApiKeyRaw?.trim() || envAssistantCredential || undefined;
+  const authHeader = assistantCredential
+    ? `Api-Key ${assistantCredential}`
+    : null;
 
   return {
     isPlatform: platform,
     platformBaseUrl,
     assistantId,
-    hasInternalApiKey: internalApiKey.length > 0,
-    hasAssistantApiKey: assistantApiKey.length > 0,
+    hasAssistantApiKey: !!assistantCredential,
     authHeader,
     // Enabled when we have enough context to register callback routes.
     // Does NOT require IS_PLATFORM — self-hosted assistants with stored