@vellumai/assistant 0.8.3 → 0.8.5

package/src/notifications/emit-signal.ts

@@ -14,8 +14,9 @@ import { v4 as uuid } from "uuid";
 import { getDeliverableChannels } from "../channels/config.js";
 import { findGuardianForChannel } from "../contacts/contact-store.js";
 import type { ConversationCreateType } from "../memory/conversation-crud.js";
+import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import { getLogger } from "../util/logger.js";
-import { type BroadcastFn, VellumAdapter } from "./adapters/macos.js";
+import { VellumAdapter } from "./adapters/macos.js";
 import { PlatformPushAdapter } from "./adapters/platform.js";
 import { SlackAdapter } from "./adapters/slack.js";
 import { TelegramAdapter } from "./adapters/telegram.js";
@@ -49,56 +50,38 @@ const log = getLogger("emit-signal");
 // ── Broadcaster singleton ──────────────────────────────────────────────
 
 let broadcasterInstance: NotificationBroadcaster | null = null;
-let registeredBroadcastFn: BroadcastFn | null = null;
-
-/**
- * Register the broadcast function so the vellum adapter can deliver
- * notifications to connected clients. Must be called once during
- * daemon startup (before any signals are emitted).
- */
-export function registerBroadcastFn(fn: BroadcastFn): void {
-  registeredBroadcastFn = fn;
-  // Reset the broadcaster so it picks up the new broadcast function
-  broadcasterInstance = null;
-}
 
 function getBroadcaster(): NotificationBroadcaster {
   if (!broadcasterInstance) {
-    const adapters = [
+    broadcasterInstance = new NotificationBroadcaster([
+      new VellumAdapter(broadcastMessage),
       new TelegramAdapter(),
       new SlackAdapter(),
       new PlatformPushAdapter(),
-    ];
-    if (registeredBroadcastFn) {
-      adapters.unshift(new VellumAdapter(registeredBroadcastFn));
-    }
-    broadcasterInstance = new NotificationBroadcaster(adapters);
+    ]);
 
     // Wire the conversation-created callback so the macOS client is notified
     // immediately when a vellum notification conversation is paired — before
     // slower channel deliveries (e.g. Telegram) delay the push.
-    if (registeredBroadcastFn) {
-      const broadcastFn = registeredBroadcastFn;
-      broadcasterInstance.setOnConversationCreated((info) => {
-        broadcastFn({
-          type: "notification_conversation_created",
-          conversationId: info.conversationId,
-          title: info.title,
-          sourceEventName: info.sourceEventName,
-          targetGuardianPrincipalId: info.targetGuardianPrincipalId,
-          groupId: info.groupId,
-          source: info.source,
-          silent: info.silent,
-        });
-        log.info(
-          {
-            conversationId: info.conversationId,
-            guardianScoped: info.targetGuardianPrincipalId != null,
-          },
-          "Emitted notification_conversation_created push event",
-        );
+    broadcasterInstance.setOnConversationCreated((info) => {
+      broadcastMessage({
+        type: "notification_conversation_created",
+        conversationId: info.conversationId,
+        title: info.title,
+        sourceEventName: info.sourceEventName,
+        targetGuardianPrincipalId: info.targetGuardianPrincipalId,
+        groupId: info.groupId,
+        source: info.source,
+        silent: info.silent,
       });
-    }
+      log.info(
+        {
+          conversationId: info.conversationId,
+          guardianScoped: info.targetGuardianPrincipalId != null,
+        },
+        "Emitted notification_conversation_created push event",
+      );
+    });
   }
   return broadcasterInstance;
 }
@@ -115,18 +98,15 @@ function getConnectedChannels(): NotificationChannel[] {
     switch (channel) {
       case "vellum":
         // Vellum is always considered connected (the local transport is
-        // always available when the daemon is running).
+        // always available when the assistant is running).
         channels.push(channel);
         break;
       case "platform":
-        // Platform push is connected when the daemon has a registered
-        // broadcast function — i.e., full daemon mode where platform
-        // credentials are also available. Mirrors the vellum gate so
-        // the decision engine doesn't route to platform in standalone
-        // CLI contexts where VellumPlatformClient.create() returns null.
-        if (registeredBroadcastFn) {
-          channels.push(channel);
-        }
+        // Platform push is treated as connected at the decision-engine
+        // layer; the actual delivery path lazily resolves
+        // `VellumPlatformClient.create()` in `PlatformPushAdapter.send()`
+        // and reports a delivery failure when credentials are absent.
+        channels.push(channel);
         break;
       case "telegram": {
         // A binding-based channel is connected when the guardian has an
@@ -388,10 +368,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,11 +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,
-  RenderedChannelCopy,
-} from "./types.js";
+import type { NotificationDecision, RenderedChannelCopy } from "./types.js";
 
 const log = getLogger("home-feed-side-effect");
 
@@ -41,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.
@@ -48,9 +54,13 @@ 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 ??
@@ -77,9 +87,6 @@ export async function writeHomeFeedItemForSignal(
     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;
@@ -107,7 +114,7 @@ export async function writeHomeFeedItemForSignal(
     noteworthy: deriveNoteworthy(signal),
     fromAssistant: signal.sourceChannel === "assistant_tool",
     ...(urgency ? { urgency } : {}),
-    ...(conversationId ? { conversationId } : {}),
+    ...(sourceConversationId ? { conversationId: sourceConversationId } : {}),
     ...(panelKind ? { detailPanel: { kind: panelKind } } : {}),
     ...(metadata ? { metadata } : {}),
   };
@@ -166,28 +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` 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.
+ * `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.sourceChannel === "assistant_tool") return true;
-  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 {

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/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

@@ -79,7 +79,7 @@ export class PermissionPrompter {
       const timeoutMs = getConfig().timeouts.permissionTimeoutSec * 1000;
 
       const timer = setTimeout(() => {
-        const interaction = pendingInteractions.resolve(requestId);
+        const interaction = pendingInteractions.resolve(requestId, "cancelled");
         this.ownedIds.delete(requestId);
         log.warn(
           { requestId, toolName },
@@ -130,7 +130,7 @@ export class PermissionPrompter {
       if (signal) {
         const onAbort = () => {
           if (this.ownedIds.has(requestId)) {
-            pendingInteractions.resolve(requestId);
+            pendingInteractions.resolve(requestId, "cancelled");
             this.ownedIds.delete(requestId);
             resolve({ decision: "deny", wasAbort: true });
           }
@@ -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)?.(
         {
@@ -229,7 +232,7 @@ export class PermissionPrompter {
 
   dispose(): void {
     for (const requestId of [...this.ownedIds]) {
-      const interaction = pendingInteractions.resolve(requestId);
+      const interaction = pendingInteractions.resolve(requestId, "cancelled");
       this.ownedIds.delete(requestId);
       interaction?.rpcReject?.(
         new AssistantError("Prompter disposed", ErrorCode.INTERNAL_ERROR),

package/src/permissions/question-prompter.ts

@@ -223,8 +223,11 @@ export class QuestionPrompter {
           signal.removeEventListener("abort", onAbort);
         }
         // Idempotent: a no-op if the entry was already removed (e.g. by
-        // `removeByConversation`) or by an earlier path.
-        pendingInteractions.resolve(requestId);
+        // `removeByConversation`) or by an earlier path. The route's
+        // success path resolves with "answered" before invoking rpcResolve,
+        // so this fallback only fires for timeout / abort / removeByConversation —
+        // all cancellation-shaped outcomes.
+        pendingInteractions.resolve(requestId, "cancelled");
         fn();
       };
 

package/src/permissions/secret-prompter.ts

@@ -71,7 +71,7 @@ export class SecretPrompter {
       const timeoutMs = getConfig().timeouts.permissionTimeoutSec * 1000;
 
       const timer = setTimeout(() => {
-        pendingInteractions.resolve(requestId);
+        pendingInteractions.resolve(requestId, "cancelled");
         this.ownedIds.delete(requestId);
         log.warn({ requestId, service, field }, "Secret prompt timed out");
         resolve({ value: null, delivery: "store" });
@@ -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" },
@@ -139,7 +142,7 @@ export class SecretPrompter {
 
   dispose(): void {
     for (const requestId of [...this.ownedIds]) {
-      const interaction = pendingInteractions.resolve(requestId);
+      const interaction = pendingInteractions.resolve(requestId, "cancelled");
       this.ownedIds.delete(requestId);
       interaction?.rpcReject?.(
         new AssistantError("Prompter disposed", ErrorCode.INTERNAL_ERROR),

package/src/plugin-api/index.ts

@@ -25,6 +25,8 @@
  * - {@link UserPromptSubmitContext} — passed to `user-prompt-submit` hook,
  *   fired immediately before the agent loop receives a user's prompt
  * - {@link PluginLogger} — pino-compatible logger shape on the contexts
+ * - {@link ToolDefinition} — author-facing tool spec (default-export shape
+ *   for both plugin tool files and workspace tool files)
  * - {@link ToolContext} — passed to a plugin tool's `execute` method
  * - {@link ToolExecutionResult} — return shape of a plugin tool's `execute`
  *
@@ -41,6 +43,8 @@ export type {
   PluginLogger,
   PluginShutdownContext,
   ToolContext,
+  ToolDefinition,
   ToolExecutionResult,
   UserPromptSubmitContext,
 } from "./types.js";
+export { RiskLevel } from "./types.js";

package/src/plugin-api/types.ts

@@ -1,43 +1,17 @@
 /**
- * Public plugin-API types.
- *
- * This module is the entry point plugin authors land on when they import
- * from `@vellumai/plugin-api`. The shapes here are the canonical public
- * contract — anything exported is part of the surface that semver gates.
- *
- * ## Tool-execution types
- *
- * `ToolContext` and `ToolExecutionResult` are re-exports of the narrow,
- * stable bases defined alongside their daemon-internal counterparts in
- * `assistant/src/tools/types.ts`. The daemon-internal `ToolContext` /
- * `ToolExecutionResult` (with CES, trust classification, lifecycle
- * events, sensitive-output bindings, risk metadata, etc.) `extends`
- * the public bases, so the runtime can hand plugins the full value
- * without a manual cast and tsc enforces the structural relationship.
- * Plugin tools see the narrow surface only — they MUST NOT set fields
- * that belong to the daemon-internal extension.
- *
- * ## Hook contexts
- *
- * The init / shutdown hook contexts are owned by this module directly.
- * They have no daemon-internal extension today (the daemon constructs
- * and hands them straight through), so there's nothing to inherit from.
- *
- * ## Compatibility
- *
- * Adding fields to any public shape is non-breaking. Renaming or
- * removing fields is breaking and gated on a major bump of
- * `@vellumai/plugin-api`.
+ * Public plugin-API types — the canonical contract for
+ * `@vellumai/plugin-api`. Adding fields is non-breaking; renaming /
+ * removing is breaking and gated on a major bump.
  */
 
 import type { Message } from "../providers/types.js";
 
-// ─── Tool-execution types (re-exported from daemon source-of-truth) ──────────
-
 export type {
-  PluginToolContext as ToolContext,
-  PluginToolExecutionResult as ToolExecutionResult,
+  ToolContext,
+  ToolDefinition,
+  ToolExecutionResult,
 } from "../tools/types.js";
+export { RiskLevel } from "../tools/types.js";
 
 // ─── Logger ──────────────────────────────────────────────────────────────────
 

package/src/plugins/defaults/index.ts

@@ -24,6 +24,7 @@
  * chain) does not trip a TDZ.
  */
 
+import { memoryV3ShadowPlugin } from "../../memory/v3/shadow-middleware.js";
 import { registerPlugin, resetPluginRegistryForTests } from "../registry.js";
 import { type Plugin, PluginExecutionError } from "../types.js";
 import { defaultCircuitBreakerPlugin } from "./circuit-breaker.js";
@@ -60,6 +61,11 @@ function getAllDefaultPlugins(): readonly Plugin[] {
     defaultEmptyResponsePlugin,
     defaultToolErrorPlugin,
     defaultMemoryRetrievalPlugin,
+    // Live-shadow v3 retrieval. Always registered; inert unless both
+    // `memory.v3.enabled` and `memory.v3.shadow` are on (gated inside the
+    // middleware). Ordered after the default so the default terminal still
+    // produces the injected (v2) `MemoryResult`.
+    memoryV3ShadowPlugin,
     defaultInjectorsPlugin,
     defaultTokenEstimatePlugin,
     defaultOverflowReducePlugin,