@vellumai/assistant 0.7.1 → 0.7.2

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/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/public-ingress-urls.ts

@@ -27,17 +27,30 @@
  * All public-facing ingress URL construction is centralized here.
  */
 
+import {
+  buildTwilioConnectActionUrl,
+  buildTwilioMediaStreamUrl,
+  buildTwilioRelayUrl,
+  buildTwilioStatusWebhookUrl,
+  buildTwilioVoiceWebhookUrl,
+  normalizePublicBaseUrl,
+} from "@vellumai/service-contracts/twilio-ingress";
+
 import { getIngressPublicBaseUrl } from "../config/env.js";
 
 export interface IngressConfig {
-  ingress?: { enabled?: boolean; publicBaseUrl?: string };
+  ingress?: {
+    enabled?: boolean;
+    publicBaseUrl?: string;
+  };
 }
 
-/**
- * Trim whitespace and strip trailing slashes from a URL string.
- */
-function normalizeUrl(url: string): string {
-  return url.trim().replace(/\/+$/, "");
+function assertPublicIngressEnabled(config: IngressConfig): void {
+  if (config.ingress?.enabled === false) {
+    throw new Error(
+      "Public ingress is disabled. Ask the assistant to enable it, or update it from the Settings page.",
+    );
+  }
 }
 
 /**
@@ -51,23 +64,15 @@ function normalizeUrl(url: string): string {
  * Throws if no source provides a non-empty value or if ingress is disabled.
  */
 export function getPublicBaseUrl(config: IngressConfig): string {
-  if (config.ingress?.enabled === false) {
-    throw new Error(
-      "Public ingress is disabled. Ask the assistant to enable it, or update it from the Settings page.",
-    );
-  }
+  assertPublicIngressEnabled(config);
 
   const ingressValue = config.ingress?.publicBaseUrl;
-  if (ingressValue) {
-    const normalized = normalizeUrl(ingressValue);
-    if (normalized) return normalized;
-  }
+  const normalizedIngressValue = normalizePublicBaseUrl(ingressValue);
+  if (normalizedIngressValue) return normalizedIngressValue;
 
   const ingressEnvValue = getIngressPublicBaseUrl();
-  if (ingressEnvValue) {
-    const normalized = normalizeUrl(ingressEnvValue);
-    if (normalized) return normalized;
-  }
+  const normalizedIngressEnvValue = normalizePublicBaseUrl(ingressEnvValue);
+  if (normalizedIngressEnvValue) return normalizedIngressEnvValue;
 
   throw new Error(
     "No public base URL configured. Set ingress.publicBaseUrl in config.",
@@ -87,27 +92,24 @@ export function getTwilioVoiceWebhookUrl(
   config: IngressConfig,
   callSessionId?: string,
 ): string {
-  const base = getPublicBaseUrl(config);
-  if (callSessionId) {
-    return `${base}/webhooks/twilio/voice?callSessionId=${callSessionId}`;
-  }
-  return `${base}/webhooks/twilio/voice`;
+  return buildTwilioVoiceWebhookUrl(
+    getPublicBaseUrl(config),
+    callSessionId,
+  );
 }
 
 /**
  * Build the Twilio status callback URL.
  */
 export function getTwilioStatusCallbackUrl(config: IngressConfig): string {
-  const base = getPublicBaseUrl(config);
-  return `${base}/webhooks/twilio/status`;
+  return buildTwilioStatusWebhookUrl(getPublicBaseUrl(config));
 }
 
 /**
  * Build the Twilio connect-action callback URL.
  */
 export function getTwilioConnectActionUrl(config: IngressConfig): string {
-  const base = getPublicBaseUrl(config);
-  return `${base}/webhooks/twilio/connect-action`;
+  return buildTwilioConnectActionUrl(getPublicBaseUrl(config));
 }
 
 /**
@@ -115,9 +117,7 @@ export function getTwilioConnectActionUrl(config: IngressConfig): string {
  * Converts http:// → ws:// and https:// → wss://.
  */
 export function getTwilioRelayUrl(config: IngressConfig): string {
-  const base = getPublicBaseUrl(config);
-  const wsBase = base.replace(/^http(s?)/, "ws$1");
-  return `${wsBase}/webhooks/twilio/relay`;
+  return buildTwilioRelayUrl(getPublicBaseUrl(config));
 }
 
 /**
@@ -127,9 +127,7 @@ export function getTwilioRelayUrl(config: IngressConfig): string {
  * Converts http:// → ws:// and https:// → wss://.
  */
 export function getTwilioMediaStreamUrl(config: IngressConfig): string {
-  const base = getPublicBaseUrl(config);
-  const wsBase = base.replace(/^http(s?)/, "ws$1");
-  return `${wsBase}/webhooks/twilio/media-stream`;
+  return buildTwilioMediaStreamUrl(getPublicBaseUrl(config));
 }
 
 /**

package/src/ipc/__tests__/route-error-envelope.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Unit tests for the IPC error envelope built from `RouteError` instances.
+ *
+ * Asserts that `AssistantIpcServer.buildErrorResponse` forwards the full
+ * `RouteError` shape — including the `details` field — into the IPC response
+ * envelope so IPC clients (e.g. gateway→daemon) receive the same structured
+ * payload as HTTP clients (e.g. `version_incompatible` migration imports).
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+  RouteError,
+  UnprocessableEntityError,
+} from "../../runtime/routes/errors.js";
+import { AssistantIpcServer, type IpcResponse } from "../assistant-server.js";
+
+/**
+ * `buildErrorResponse` is private; access it through an interface cast so the
+ * test exercises the actual production code path without exporting a
+ * test-only API on the server class.
+ */
+type PrivateApi = {
+  buildErrorResponse(id: string, err: unknown): IpcResponse;
+};
+
+function buildErrorResponse(err: unknown): IpcResponse {
+  const server = new AssistantIpcServer() as unknown as PrivateApi;
+  return server.buildErrorResponse("req-1", err);
+}
+
+describe("AssistantIpcServer error envelope", () => {
+  test("forwards RouteError message, statusCode, and code", () => {
+    const err = new RouteError("boom", "BOOM", 418);
+    const response = buildErrorResponse(err);
+
+    expect(response.id).toBe("req-1");
+    expect(response.error).toBe("boom");
+    expect(response.statusCode).toBe(418);
+    expect(response.errorCode).toBe("BOOM");
+    expect(response.errorDetails).toBeUndefined();
+  });
+
+  test("forwards RouteError.details into errorDetails when present", () => {
+    const details = {
+      reason: "version_incompatible" as const,
+      bundle_compat: { engineMin: "0.7.0" },
+      runtime_version: "0.6.0",
+    };
+    const err = new UnprocessableEntityError(
+      "incompatible bundle version",
+      details,
+    );
+
+    const response = buildErrorResponse(err);
+
+    expect(response.errorCode).toBe("UNPROCESSABLE_ENTITY");
+    expect(response.statusCode).toBe(422);
+    expect(response.errorDetails).toEqual(details);
+  });
+
+  test("omits errorDetails when RouteError has no details", () => {
+    const err = new UnprocessableEntityError("plain validation failure");
+
+    const response = buildErrorResponse(err);
+
+    expect(response.errorCode).toBe("UNPROCESSABLE_ENTITY");
+    // `errorDetails` must be omitted entirely (not `undefined` value) so the
+    // serialized JSON envelope stays minimal.
+    expect("errorDetails" in response).toBe(false);
+  });
+
+  test("non-RouteError errors are stringified into `error`", () => {
+    const response = buildErrorResponse(new Error("raw"));
+
+    expect(response.error).toBe("Error: raw");
+    expect(response.errorCode).toBeUndefined();
+    expect(response.errorDetails).toBeUndefined();
+  });
+});

package/src/ipc/assistant-server.ts

@@ -70,6 +70,14 @@ export type IpcResponse = {
   statusCode?: number;
   /** Machine-readable error code (e.g. "NOT_FOUND") for RouteError instances. */
   errorCode?: string;
+  /**
+   * Structured error payload mirroring `RouteError.details` — present only
+   * when the originating `RouteError` carries a `details` field (e.g.
+   * `version_incompatible` migration imports). Mirrors the HTTP adapter's
+   * `error.details` envelope so IPC clients can recover the same
+   * machine-readable context as HTTP clients.
+   */
+  errorDetails?: unknown;
   headers?: Record<string, string>;
 };
 
@@ -136,6 +144,7 @@ export class AssistantIpcServer {
     }
 
     // ⚠️  TEMPORARY — gateway→assistant DB proxy (see ipc/routes/db-proxy.ts).
+    // This is the ONLY route defined directly here; all other routes go in ROUTES.
     // Remove once contacts/guardian-binding logic is fully migrated to the
     // gateway's own database.
     this.methods.set("db_proxy", (params) =>
@@ -273,12 +282,16 @@ export class AssistantIpcServer {
 
   private buildErrorResponse(id: string, err: unknown): IpcResponse {
     if (err instanceof RouteError) {
-      return {
+      const response: IpcResponse = {
         id,
         error: err.message,
         statusCode: err.statusCode,
         errorCode: err.code,
       };
+      if (err.details !== undefined) {
+        response.errorDetails = err.details;
+      }
+      return response;
     }
     return { id, error: String(err) };
   }