@vellumai/assistant 0.8.1 → 0.8.3

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

@@ -12,6 +12,8 @@
  */
 import {
   type FeedItem,
+  type FeedItemCategory,
+  type FeedItemDetailPanelKind,
   feedItemSchema,
   type FeedItemUrgency,
 } from "../home/feed-types.js";
@@ -23,6 +25,7 @@ import type { NotificationSignal } from "./signal.js";
 import type {
   NotificationDecision,
   NotificationDeliveryResult,
+  RenderedChannelCopy,
 } from "./types.js";
 
 const log = getLogger("home-feed-side-effect");
@@ -49,9 +52,30 @@ export async function writeHomeFeedItemForSignal(
 ): Promise<FeedItem | null> {
   if (!shouldMirrorToHomeFeed(signal)) 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",
@@ -61,17 +85,31 @@ export async function writeHomeFeedItemForSignal(
     : undefined;
   const now = new Date().toISOString();
 
+  const category = deriveCategory(signal);
+  const panelKind = deriveDetailPanelKind(signal);
+  const metadata =
+    signal.contextPayload &&
+    typeof signal.contextPayload === "object" &&
+    !Array.isArray(signal.contextPayload)
+      ? (signal.contextPayload as Record<string, unknown>)
+      : undefined;
+
   const item: FeedItem = {
     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 } : {}),
+    ...(panelKind ? { detailPanel: { kind: panelKind } } : {}),
+    ...(metadata ? { metadata } : {}),
   };
 
   try {
@@ -88,12 +126,60 @@ export async function writeHomeFeedItemForSignal(
   return item;
 }
 
+// ── Category & detail-panel derivation ────────────────────────────────
+
+const EVENT_CATEGORY_MAP: Record<string, FeedItemCategory> = {
+  "credential.health_alert": "security",
+  "activity.failed": "background",
+  "activity.complete": "background",
+  "watcher.notification": "system",
+  "schedule.notify": "scheduling",
+  "guardian.question": "security",
+  "guardian.channel_activation": "security",
+  "ingress.access_request": "security",
+  "ingress.escalation": "security",
+};
+
+function deriveCategory(signal: NotificationSignal): FeedItemCategory {
+  return EVENT_CATEGORY_MAP[signal.sourceEventName] ?? "system";
+}
+
+function deriveDetailPanelKind(
+  signal: NotificationSignal,
+): FeedItemDetailPanelKind | undefined {
+  if (signal.sourceEventName === "credential.health_alert") {
+    return "toolPermission";
+  }
+
+  if (signal.sourceEventName === "guardian.question") {
+    const payload = signal.contextPayload;
+    const kind =
+      payload && typeof payload === "object" && "requestKind" in payload
+        ? (payload as Record<string, unknown>).requestKind
+        : undefined;
+    if (kind === "tool_approval" || kind === "tool_grant_request") {
+      return "permissionChat";
+    }
+  }
+
+  return undefined;
+}
+
 /**
  * `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.
+ *
+ * `assistant_tool` is the source channel used by the `notifications send`
+ * skill (and by background-job failure emits). These signals represent
+ * the assistant actively choosing to share, so we mirror them into the
+ * home feed without requiring a background-typed conversation or the
+ * `isAsyncBackground` hint — the documented (SKILL.md) CLI surface
+ * intentionally does not expose either; internal call sites that still set
+ * the hint keep working unchanged.
  */
 function shouldMirrorToHomeFeed(signal: NotificationSignal): boolean {
+  if (signal.sourceChannel === "assistant_tool") return true;
   if (signal.attentionHints.isAsyncBackground) return true;
   if (!signal.sourceContextId) return false;
   try {
@@ -109,3 +195,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

@@ -4,6 +4,7 @@
  * decision engine route contextually.
  */
 
+import type { ConversationCreateType } from "../memory/conversation-crud.js";
 import type { GuardianQuestionPayload } from "./guardian-question-mode.js";
 
 // ── Source channel registry ────────────────────────────────────────────
@@ -106,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 =
@@ -119,7 +116,7 @@ export type NotificationSourceEventName =
 
 export interface AttentionHints {
   requiresAction: boolean;
-  urgency: "low" | "medium" | "high";
+  urgency: "low" | "medium" | "high" | "critical";
   deadlineAt?: number; // epoch ms
   isAsyncBackground: boolean;
   visibleInSourceNow: boolean;
@@ -214,5 +211,6 @@ export interface NotificationSignal<TEventName extends string = string> {
     groupId?: string;
     scheduleJobId?: string;
     source?: string;
+    conversationType?: ConversationCreateType;
   };
 }

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/connection-resolver.ts

@@ -92,7 +92,7 @@ export async function resolveOAuthConnection(
       ? ` matching ${filters.join(" and ")}`
       : "";
     throw new Error(
-      `No active OAuth connection found for "${provider}"${qualifier}. Connect the service first with \`assistant oauth connect ${provider}\`.`,
+      `No active OAuth connection found for "${provider}"${qualifier}. The ${provider} service needs to be connected before it can be used.`,
     );
   }
 
@@ -102,7 +102,7 @@ export async function resolveOAuthConnection(
   });
   if (!tokenResult.value) {
     throw new Error(
-      `OAuth connection for "${provider}" exists but has no access token. Re-authorize with \`assistant oauth connect ${provider}\`.`,
+      `OAuth connection for "${provider}" exists but the access token is missing or expired. The ${provider} service needs to be reconnected.`,
     );
   }
 
@@ -223,18 +223,22 @@ async function resolvePlatformConnectionId(
 
   if (connections.length === 0) {
     throw new Error(
-      `No active platform OAuth connection found for provider "${provider}"` +
+      `No active OAuth connection found for provider "${provider}"` +
         (account ? ` with account "${account}"` : "") +
-        ". Connect the service on the Vellum platform first.",
+        `. The ${provider} service needs to be connected.`,
     );
   }
 
   if (connections.length > 1 && !account) {
+    const allAccounts = connections
+      .map((c) => c.account_label ?? c.id)
+      .join(", ");
     log.warn(
       {
         provider,
         count: connections.length,
         selectedId: connections[0].id,
+        allAccounts,
       },
       "Multiple active platform connections found; using the most recently created. " +
         "Pass an account option to select a specific connection.",

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,17 +8,22 @@ import type {
   OAuthConnectionResponse,
 } from "./connection.js";
 
+const log = getLogger("platform-oauth-connection");
 const MAX_RETRIES = 3;
 
 export class CredentialRequiredError extends BackendError {
-  constructor(message = "Connection not set up on platform") {
+  constructor(
+    message = "OAuth credential for this provider has expired or been revoked. The service needs to be reconnected.",
+  ) {
     super(message);
     this.name = "CredentialRequiredError";
   }
 }
 
 export class ProviderUnreachableError extends BackendError {
-  constructor(message = "Provider is unreachable") {
+  constructor(
+    message = "The external service provider is temporarily unreachable. This may be a transient issue — retry after a brief pause.",
+  ) {
     super(message);
     this.name = "ProviderUnreachableError";
   }
@@ -107,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

@@ -77,7 +77,7 @@ export const PROVIDER_SEED_DATA: Record<
     pingUrl: "https://www.googleapis.com/oauth2/v2/userinfo",
     baseUrl: "https://gmail.googleapis.com/gmail/v1/users/me",
     displayLabel: "Google",
-    description: "Gmail, Calendar, and Contacts",
+    description: "Gmail, Calendar, Drive, and Contacts",
     dashboardUrl: "https://console.cloud.google.com/apis/credentials",
     clientIdPlaceholder: "123456789.apps.googleusercontent.com",
     logoUrl: "https://cdn.simpleicons.org/google",
@@ -88,6 +88,7 @@ export const PROVIDER_SEED_DATA: Record<
       "https://www.googleapis.com/auth/gmail.settings.basic",
       "https://www.googleapis.com/auth/calendar.readonly",
       "https://www.googleapis.com/auth/calendar.events",
+      "https://www.googleapis.com/auth/drive",
       "https://www.googleapis.com/auth/userinfo.email",
       "https://www.googleapis.com/auth/contacts.readonly",
     ],
@@ -722,6 +723,14 @@ export const PROVIDER_SEED_DATA: Record<
     requiresClientSecret: false,
     logoUrl: "https://cdn.simpleicons.org/slack",
     defaultScopes: [],
+    injectionTemplates: [
+      {
+        hostPattern: "slack.com",
+        injectionType: "header",
+        headerName: "Authorization",
+        valuePrefix: "Bearer ",
+      },
+    ],
   },
 
   telegram: {

package/src/permissions/checker.ts

@@ -21,6 +21,7 @@ import {
   getProtectedDir,
   getWorkspaceDir,
   getWorkspaceHooksDir,
+  getWorkspacePluginsDir,
 } from "../util/platform.js";
 import {
   type ApprovalContext,
@@ -255,6 +256,7 @@ function buildFileContext(): FileContext {
     protectedDir: getProtectedDir(),
     deprecatedDir: getDeprecatedDir(),
     hooksDir: getWorkspaceHooksDir(),
+    pluginsDir: getWorkspacePluginsDir(),
     actorTokenSigningKeyPath: join(
       getProtectedDir(),
       "actor-token-signing-key",

package/src/permissions/ipc-risk-types.ts

@@ -52,6 +52,7 @@ export interface FileContext {
   protectedDir: string;
   deprecatedDir: string;
   hooksDir: string;
+  pluginsDir: string;
   actorTokenSigningKeyPath: string;
   skillSourceDirs: string[];
 }