@vellumai/assistant 0.8.2 → 0.8.4

package/src/notifications/emit-signal.ts

@@ -88,6 +88,7 @@ function getBroadcaster(): NotificationBroadcaster {
           targetGuardianPrincipalId: info.targetGuardianPrincipalId,
           groupId: info.groupId,
           source: info.source,
+          silent: info.silent,
         });
         log.info(
           {
@@ -387,10 +388,18 @@ export async function emitNotificationSignal<TEventName extends string>(
     // Step 5: Mirror background-origin signals into the home activity feed.
     // The helper itself decides whether to write (background filter); we
     // catch and log so a feed-write failure cannot poison the dispatch result.
+    // Pass the paired vellum delivery conversation as a fallback so producers
+    // whose `sourceContextId` is a sentinel string (e.g. heartbeat startup,
+    // credential health, watcher emits, scheduler retries-exhausted) still
+    // get a "Go to Convo" button — pointing at the conversation the
+    // broadcaster paired the notification with.
+    const pairedVellumConversationId = dispatchResult.deliveryResults.find(
+      (r) => r.channel === "vellum",
+    )?.conversationId;
     await writeHomeFeedItemForSignal(
       signal,
       decision,
-      dispatchResult.deliveryResults,
+      pairedVellumConversationId,
     ).catch((err) => {
       log.warn({ err, signalId }, "writeHomeFeedItemForSignal threw");
     });

package/src/notifications/home-feed-side-effect.ts

@@ -22,10 +22,7 @@ import { getConversation } from "../memory/conversation-crud.js";
 import { isBackgroundConversationType } from "../memory/conversation-types.js";
 import { getLogger } from "../util/logger.js";
 import type { NotificationSignal } from "./signal.js";
-import type {
-  NotificationDecision,
-  NotificationDeliveryResult,
-} from "./types.js";
+import type { NotificationDecision, RenderedChannelCopy } from "./types.js";
 
 const log = getLogger("home-feed-side-effect");
 
@@ -40,6 +37,16 @@ const FEED_ITEM_URGENCIES: ReadonlySet<string> = new Set<FeedItemUrgency>([
  * Append a `FeedItem` for the given notification signal when the
  * filter criteria pass.
  *
+ * `fallbackConversationId` is used as the feed item's "Go to Convo"
+ * navigation target when `signal.sourceContextId` doesn't resolve to a
+ * real conversation row. The notification broadcaster pairs the vellum
+ * delivery with a conversation (newly created or reused) before this
+ * function runs, so callers can thread that paired id through here for
+ * producers whose `sourceContextId` is a sentinel (heartbeat startup,
+ * credential health, watcher emits, scheduler retries-exhausted) — the
+ * feed item will then carry the paired delivery conversation and the
+ * "Go to Convo" button can render.
+ *
  * Returns the persisted `FeedItem`, or `null` if the signal does not
  * qualify for home-feed mirroring (non-background origin AND no
  * `isAsyncBackground` hint) or if schema validation fails.
@@ -47,17 +54,39 @@ const FEED_ITEM_URGENCIES: ReadonlySet<string> = new Set<FeedItemUrgency>([
 export async function writeHomeFeedItemForSignal(
   signal: NotificationSignal,
   decision: NotificationDecision,
-  deliveryResults: NotificationDeliveryResult[],
+  fallbackConversationId?: string,
 ): Promise<FeedItem | null> {
-  if (!shouldMirrorToHomeFeed(signal)) return null;
+  const { mirror, sourceConversationId } = resolveHomeFeedMirror(
+    signal,
+    fallbackConversationId,
+  );
+  if (!mirror) return null;
 
-  const renderedCopy = decision.renderedCopy.vellum;
-  const payloadTitle = readPayloadString(signal.contextPayload, "title");
-  const payloadBody = readPayloadString(signal.contextPayload, "body");
+  const renderedCopy =
+    decision.renderedCopy.vellum ??
+    firstSelectedRenderedCopy(decision.renderedCopy, decision.selectedChannels);
+  const payloadTitle =
+    readPayloadString(signal.contextPayload, "title") ??
+    readPayloadString(signal.contextPayload, "requestedTitle");
+  const payloadBody =
+    readPayloadString(signal.contextPayload, "body") ??
+    readPayloadString(signal.contextPayload, "requestedMessage");
+
+  // Source the title from the payload only. The LLM's `renderedCopy.title`
+  // often echoes the body when no explicit title was passed, which stutters
+  // against `summary` in the row. Leave undefined when absent; renderers
+  // fall back to `summary`.
+  const resolvedTitle = payloadTitle?.trim() || undefined;
+  const resolvedSummary =
+    renderedCopy?.body?.trim() || payloadBody?.trim() || "";
+  if (!resolvedSummary) {
+    log.warn(
+      { signalId: signal.signalId, sourceEventName: signal.sourceEventName },
+      "Home-feed write skipped: no summary available (would have fallen back to event name)",
+    );
+    return null;
+  }
 
-  const conversationId = deliveryResults.find(
-    (r) => r.channel === "vellum",
-  )?.conversationId;
   const urgency = FEED_ITEM_URGENCIES.has(signal.attentionHints.urgency)
     ? (signal.attentionHints.urgency as FeedItemUrgency)
     : undefined;
@@ -76,14 +105,16 @@ export async function writeHomeFeedItemForSignal(
     id: `notif:${signal.signalId}`,
     type: "notification",
     priority: 50,
-    title: renderedCopy?.title ?? payloadTitle ?? signal.sourceEventName,
-    summary: renderedCopy?.body ?? payloadBody ?? signal.sourceEventName,
+    ...(resolvedTitle ? { title: resolvedTitle } : {}),
+    summary: resolvedSummary,
     timestamp: now,
     createdAt: now,
     status: "new",
     category,
+    noteworthy: deriveNoteworthy(signal),
+    fromAssistant: signal.sourceChannel === "assistant_tool",
     ...(urgency ? { urgency } : {}),
-    ...(conversationId ? { conversationId } : {}),
+    ...(sourceConversationId ? { conversationId: sourceConversationId } : {}),
     ...(panelKind ? { detailPanel: { kind: panelKind } } : {}),
     ...(metadata ? { metadata } : {}),
   };
@@ -108,7 +139,6 @@ const EVENT_CATEGORY_MAP: Record<string, FeedItemCategory> = {
   "credential.health_alert": "security",
   "activity.failed": "background",
   "activity.complete": "background",
-  "heartbeat.alert": "system",
   "watcher.notification": "system",
   "schedule.notify": "scheduling",
   "guardian.question": "security",
@@ -143,19 +173,51 @@ function deriveDetailPanelKind(
 }
 
 /**
- * `sourceContextId` is best-effort — it may not be a conversation id
- * (e.g. scheduler job id, watcher event id), so a lookup failure
- * falls through to "not a background conversation" rather than throwing.
+ * The lookup is best-effort and unified: a single `getConversation` call
+ * both gates the "background conversation" mirror branch and populates
+ * `sourceConversationId` for the "Go to Thread" navigation target. Misses
+ * (scheduler job ids, watcher event ids, CLI tool-call ids) leave
+ * `sourceConversationId` undefined so the client hides the affordance.
+ *
+ * `assistant_tool` mirrors unconditionally because the documented
+ * `notifications send` skill (and background-job failure emits) deliberately
+ * does not require a background-typed conversation or the
+ * `isAsyncBackground` hint.
  */
-function shouldMirrorToHomeFeed(signal: NotificationSignal): boolean {
-  if (signal.attentionHints.isAsyncBackground) return true;
-  if (!signal.sourceContextId) return false;
-  try {
-    const row = getConversation(signal.sourceContextId);
-    return isBackgroundConversationType(row?.conversationType);
-  } catch {
-    return false;
+function resolveHomeFeedMirror(
+  signal: NotificationSignal,
+  fallbackConversationId?: string,
+): {
+  mirror: boolean;
+  sourceConversationId?: string;
+} {
+  let sourceRow: { conversationType?: string } | null = null;
+  if (signal.sourceContextId) {
+    try {
+      sourceRow = getConversation(signal.sourceContextId) ?? null;
+    } catch {
+      sourceRow = null;
+    }
+  }
+  // Prefer the producer's source context (e.g. the heartbeat / background
+  // job conversation that emitted the signal) for the "Go to Convo" target,
+  // since that's where the work actually happened. Fall back to the paired
+  // delivery conversation only when the source context didn't resolve —
+  // covers producers whose `sourceContextId` is a sentinel string.
+  const sourceConversationId = sourceRow
+    ? signal.sourceContextId
+    : fallbackConversationId;
+
+  if (signal.sourceChannel === "assistant_tool") {
+    return { mirror: true, sourceConversationId };
+  }
+  if (signal.attentionHints.isAsyncBackground) {
+    return { mirror: true, sourceConversationId };
   }
+  if (isBackgroundConversationType(sourceRow?.conversationType)) {
+    return { mirror: true, sourceConversationId };
+  }
+  return { mirror: false };
 }
 
 function readPayloadString(payload: unknown, key: string): string | undefined {
@@ -163,3 +225,50 @@ function readPayloadString(payload: unknown, key: string): string | undefined {
   const value = (payload as Record<string, unknown>)[key];
   return typeof value === "string" ? value : undefined;
 }
+
+/**
+ * Routing-intent enforcement can prune `selectedChannels` without also
+ * pruning `renderedCopy`, so iterating `renderedCopy` directly risks
+ * surfacing copy for a channel that was never delivered. Walk
+ * `selectedChannels` in order instead so the channel that actually shipped
+ * wins.
+ */
+function firstSelectedRenderedCopy(
+  renderedCopy: NotificationDecision["renderedCopy"],
+  selectedChannels: NotificationDecision["selectedChannels"],
+): RenderedChannelCopy | undefined {
+  for (const channel of selectedChannels) {
+    const copy = renderedCopy[channel];
+    if (copy && (copy.title?.trim() || copy.body?.trim())) return copy;
+  }
+  return undefined;
+}
+
+// ── Noteworthy derivation ─────────────────────────────────────────────
+//
+// Clients split the feed into inbox-style (noteworthy) and activity-style
+// (routine) surfaces. Assistant-initiated shares and a small allow-list of
+// high-importance system events land in the inbox; routine background
+// signals stay in activity.
+
+const NOTEWORTHY_EVENT_NAMES: ReadonlySet<string> = new Set([
+  "guardian.question",
+  "guardian.channel_activation",
+  "ingress.access_request",
+  "ingress.escalation",
+  "credential.health_alert",
+]);
+
+function deriveNoteworthy(signal: NotificationSignal): boolean {
+  // Background-job failures emit with `sourceChannel: "assistant_tool"`
+  // (see `runtime/background-job-runner.ts`), so the activity.failed rule
+  // must run BEFORE the assistant_tool short-circuit — otherwise every
+  // routine watcher/heartbeat failure would land in the Inbox instead of
+  // staying in the activity feed.
+  if (signal.sourceEventName === "activity.failed") {
+    return signal.attentionHints.urgency === "critical";
+  }
+  if (signal.sourceChannel === "assistant_tool") return true;
+  if (NOTEWORTHY_EVENT_NAMES.has(signal.sourceEventName)) return true;
+  return false;
+}

package/src/notifications/signal.ts

@@ -107,10 +107,6 @@ export const NOTIFICATION_SOURCE_EVENT_NAMES = [
     description:
       "OAuth credential health issue detected (expired, revoked, missing scopes)",
   },
-  {
-    id: "heartbeat.alert",
-    description: "Heartbeat found something worth surfacing to the guardian",
-  },
 ] as const;
 
 export type NotificationSourceEventName =

package/src/notifications/types.ts

@@ -7,6 +7,7 @@
 
 import type { ChannelPolicies } from "../channels/config.js";
 import type { ChannelId } from "../channels/types.js";
+import type { AttentionHints } from "./signal.js";
 
 /**
  * Derived from the channel policy registry: only channels whose
@@ -81,6 +82,13 @@ export interface ChannelDeliveryPayload {
   deepLinkTarget?: Record<string, unknown>;
   /** Original signal context payload — available for channel-specific structured rendering. */
   contextPayload?: Record<string, unknown>;
+  /**
+   * Forwarded from the originating signal so adapters can make
+   * urgency-aware decisions (e.g. the vellum adapter suppresses the OS
+   * banner for non-urgent intents while still emitting the conversation
+   * pairing side effects).
+   */
+  urgency: AttentionHints["urgency"];
 }
 
 /** Interface that each channel adapter must implement. */

package/src/oauth/connect-orchestrator.ts

@@ -20,6 +20,7 @@
  */
 
 import { emitPostConnectNudge } from "../home/post-connect-feed.js";
+import { invalidateAssistantSuggestedPromptsCache } from "../home/suggested-prompts.js";
 import type { TokenEndpointAuthMethod } from "../security/oauth2.js";
 import { prepareOAuth2Flow, startOAuth2Flow } from "../security/oauth2.js";
 import { getLogger } from "../util/logger.js";
@@ -252,6 +253,7 @@ export async function orchestrateOAuthConnect(
               },
               "Deferred OAuth2 flow completed — tokens stored",
             );
+            invalidateAssistantSuggestedPromptsCache();
             void emitPostConnectNudge(options.service);
             options.onDeferredComplete?.({
               success: true,
@@ -375,6 +377,7 @@ export async function orchestrateOAuthConnect(
       "orchestrateOAuthConnect: tokens stored, connect complete",
     );
 
+    invalidateAssistantSuggestedPromptsCache();
     void emitPostConnectNudge(options.service);
 
     return {

package/src/oauth/credential-token-resolver.ts

@@ -49,6 +49,8 @@ function manualTokenAccessCredentialKey(provider: string): string | null {
       return credentialKey("slack_channel", "bot_token");
     case "telegram":
       return credentialKey("telegram", "bot_token");
+    case "sanity":
+      return credentialKey("sanity", "api_token");
     default:
       return null;
   }

package/src/oauth/manual-token-connection.ts

@@ -122,6 +122,24 @@ export async function syncManualTokenConnection(
       return;
     }
 
+    case "sanity": {
+      const tokenResult = await getSecureKeyResultAsync(
+        credentialKey("sanity", "api_token"),
+      );
+      if (tokenResult.unreachable) {
+        log.warn(
+          "Skipping sanity manual-token reconciliation — credential backend unreachable",
+        );
+        return;
+      }
+      if (tokenResult.value) {
+        await ensureManualTokenConnection(provider, accountInfo);
+      } else {
+        removeManualTokenConnection(provider);
+      }
+      return;
+    }
+
     default:
       return;
   }
@@ -142,4 +160,5 @@ export async function syncManualTokenConnection(
 export async function backfillManualTokenConnections(): Promise<void> {
   await syncManualTokenConnection("telegram");
   await syncManualTokenConnection("slack_channel");
+  await syncManualTokenConnection("sanity");
 }

package/src/oauth/oauth-store.ts

@@ -1100,5 +1100,17 @@ export async function disconnectOAuthProvider(
 
   deleteConnection(conn.id);
 
+  // Dynamic import: `suggested-prompts.ts` imports from this module, so a
+  // static import here would create a cycle. The cache invalidation is
+  // best-effort — failures must not block disconnect.
+  void import("../home/suggested-prompts.js")
+    .then((m) => m.invalidateAssistantSuggestedPromptsCache())
+    .catch((err) => {
+      log.warn(
+        { err: err instanceof Error ? err.message : String(err) },
+        "Failed to invalidate suggested-prompts cache after disconnect",
+      );
+    });
+
   return "disconnected";
 }

package/src/oauth/platform-connection.test.ts

@@ -261,17 +261,57 @@ describe("PlatformOAuthConnection", () => {
     ).rejects.toThrow(CredentialRequiredError);
   });
 
-  test("502 response throws ProviderUnreachableError", async () => {
+  test("502 response retries then throws ProviderUnreachableError", async () => {
+    let callCount = 0;
+    const client = makeMockClient(
+      mock(async () => {
+        callCount++;
+        return new Response("", { status: 502 });
+      }) as unknown as typeof globalThis.fetch,
+    );
+
+    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    await expect(
+      conn.request({ method: "GET", path: "/test" }),
+    ).rejects.toThrow(ProviderUnreachableError);
+    // 1 initial + 3 retries = 4 total attempts
+    expect(callCount).toBe(4);
+  });
+
+  test("502 response includes detail from response body", async () => {
     const client = makeMockClient(
       mock(
-        async () => new Response("", { status: 502 }),
+        async () => new Response("upstream timeout after 30s", { status: 502 }),
       ) as unknown as typeof globalThis.fetch,
     );
 
     const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
     await expect(
       conn.request({ method: "GET", path: "/test" }),
-    ).rejects.toThrow(ProviderUnreachableError);
+    ).rejects.toThrow(/upstream timeout after 30s/);
+  });
+
+  test("502 recovers on retry", async () => {
+    let callCount = 0;
+    const client = makeMockClient(
+      mock(async () => {
+        callCount++;
+        if (callCount <= 2) {
+          return new Response("", { status: 502 });
+        }
+        return new Response(
+          JSON.stringify({ status: 200, headers: {}, body: { ok: true } }),
+          { status: 200 },
+        );
+      }) as unknown as typeof globalThis.fetch,
+    );
+
+    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const result = await conn.request({ method: "GET", path: "/test" });
+
+    expect(result.status).toBe(200);
+    expect(result.body).toEqual({ ok: true });
+    expect(callCount).toBe(3);
   });
 
   test("withToken throws clear error", async () => {

package/src/oauth/platform-connection.ts

@@ -1,5 +1,6 @@
 import type { VellumPlatformClient } from "../platform/client.js";
 import { BackendError } from "../util/errors.js";
+import { getLogger } from "../util/logger.js";
 import { getHttpRetryDelay, isRetryableStatus, sleep } from "../util/retry.js";
 import type {
   OAuthConnection,
@@ -7,6 +8,7 @@ import type {
   OAuthConnectionResponse,
 } from "./connection.js";
 
+const log = getLogger("platform-oauth-connection");
 const MAX_RETRIES = 3;
 
 export class CredentialRequiredError extends BackendError {
@@ -111,19 +113,26 @@ export class PlatformOAuthConnection implements OAuthConnection {
         throw new CredentialRequiredError();
       }
 
-      if (response.status === 502) {
-        throw new ProviderUnreachableError();
-      }
-
       if (
         !response.ok &&
         isRetryableStatus(response.status) &&
         attempt < MAX_RETRIES
       ) {
+        log.warn(
+          { status: response.status, attempt, provider: "platform-proxy" },
+          `Retryable status ${response.status} from platform proxy (attempt ${attempt + 1}/${MAX_RETRIES + 1})`,
+        );
         await sleep(getHttpRetryDelay(response, attempt));
         continue;
       }
 
+      if (response.status === 502) {
+        const detail = await response.text().catch(() => "");
+        throw new ProviderUnreachableError(
+          `The external service provider is temporarily unreachable (HTTP 502).${detail ? ` Detail: ${detail}` : ""} This may be a transient issue — retry after a brief pause.`,
+        );
+      }
+
       if (!response.ok) {
         throw new BackendError(
           `Platform proxy returned unexpected status ${response.status}`,

package/src/oauth/seed-providers.ts

@@ -746,6 +746,28 @@ export const PROVIDER_SEED_DATA: Record<
     logoUrl: "https://cdn.simpleicons.org/telegram",
     defaultScopes: [],
   },
+
+  sanity: {
+    provider: "sanity",
+    authorizeUrl: "urn:manual-token",
+    tokenExchangeUrl: "urn:manual-token",
+    baseUrl: "https://api.sanity.io",
+    displayLabel: "Sanity",
+    description: "Content management platform",
+    dashboardUrl: "https://www.sanity.io/manage",
+    clientIdPlaceholder: null,
+    requiresClientSecret: false,
+    logoUrl: "https://cdn.simpleicons.org/sanity",
+    defaultScopes: [],
+    injectionTemplates: [
+      {
+        hostPattern: "*.sanity.io",
+        injectionType: "header",
+        headerName: "Authorization",
+        valuePrefix: "Bearer ",
+      },
+    ],
+  },
 };
 
 export const SEEDED_PROVIDER_KEYS = new Set(Object.keys(PROVIDER_SEED_DATA));

package/src/permissions/prompter.ts

@@ -196,7 +196,10 @@ export class PermissionPrompter {
     }
     // The prompter owns deregistration; all callers use get() to peek before
     // routing to resolveConfirmation, which fires the rpcResolve callback.
-    const interaction = pendingInteractions.resolve(requestId);
+    const interaction = pendingInteractions.resolve(
+      requestId,
+      decision === "allow" ? "approved" : "rejected",
+    );
     this.ownedIds.delete(requestId);
     (interaction?.rpcResolve as ((v: ConfirmResult) => void) | undefined)?.(
       { decision, selectedPattern, selectedScope, decisionContext },
@@ -210,7 +213,7 @@ export class PermissionPrompter {
    */
   denyAllPending(): void {
     for (const requestId of [...this.ownedIds]) {
-      const interaction = pendingInteractions.resolve(requestId);
+      const interaction = pendingInteractions.resolve(requestId, "superseded");
       this.ownedIds.delete(requestId);
       (interaction?.rpcResolve as ((v: ConfirmResult) => void) | undefined)?.(
         {

package/src/permissions/secret-prompter.ts

@@ -130,7 +130,10 @@ export class SecretPrompter {
     }
     // approval-routes calls pendingInteractions.get() before routing here;
     // the prompter owns deregistration so it fires the Promise callback cleanly.
-    const interaction = pendingInteractions.resolve(requestId);
+    const interaction = pendingInteractions.resolve(
+      requestId,
+      value === undefined ? "cancelled" : "answered",
+    );
     this.ownedIds.delete(requestId);
     (interaction?.rpcResolve as ((v: SecretPromptResult) => void) | undefined)?.(
       { value: value ?? null, delivery: delivery ?? "store" },