@vellumai/assistant 0.8.4 → 0.8.6

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 {
+export 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
@@ -208,6 +188,15 @@ export interface EmitSignalParams<TEventName extends string = string> {
     source?: string;
     conversationType?: ConversationCreateType;
   };
+  /**
+   * When true, the vellum-channel delivery materializes a fresh conversation
+   * to host the notification (and any follow-up interaction). Set this only
+   * for flows where the conversation IS the interaction surface — e.g.
+   * guardian.question, tool grant requests, ingress access requests. Passive
+   * notifications leave this unset; they surface via the home feed and link
+   * back to their originating conversation via `sourceContextId`.
+   */
+  requiresConversation?: boolean;
 }
 
 export interface EmitSignalResult {
@@ -243,6 +232,7 @@ export async function emitNotificationSignal<TEventName extends string>(
     routingHints: params.routingHints,
     conversationAffinityHint: params.conversationAffinityHint,
     conversationMetadata: params.conversationMetadata,
+    requiresConversation: params.requiresConversation,
   };
 
   try {

package/src/notifications/signal.ts

@@ -213,4 +213,14 @@ export interface NotificationSignal<TEventName extends string = string> {
     source?: string;
     conversationType?: ConversationCreateType;
   };
+  /**
+   * When true, the vellum-channel delivery materializes a fresh conversation
+   * to host the notification (and any follow-up interaction). Set this only
+   * for flows where the conversation IS the interaction surface — e.g.
+   * guardian.question, tool grant requests, ingress access requests. Passive
+   * notifications (scheduler fired, watcher alert, activity complete, etc.)
+   * should leave this unset; they surface via the home feed and link back
+   * to their originating conversation via `sourceContextId`.
+   */
+  requiresConversation?: boolean;
 }

package/src/notifications/types.ts

@@ -45,6 +45,12 @@ export interface NotificationDeliveryResult {
 export interface DeliveryResult {
   success: boolean;
   error?: string;
+  /**
+   * Channel-native message identifier captured at send time (e.g. Slack `ts`).
+   * Persisted onto `notification_deliveries.messageId` so later edits can
+   * target the same message via `ChannelAdapter.update()`.
+   */
+  messageId?: string;
 }
 
 /** Resolved destination for a specific channel. */
@@ -91,6 +97,16 @@ export interface ChannelDeliveryPayload {
   urgency: AttentionHints["urgency"];
 }
 
+/**
+ * Patch supplied when an already-delivered notification is edited.
+ * Adapters only need to act on `title` and `body` — feed-only fields
+ * like `urgency` and `status` are handled by the home-feed patch.
+ */
+export interface ChannelUpdatePayload {
+  title?: string;
+  body?: string;
+}
+
 /** Interface that each channel adapter must implement. */
 export interface ChannelAdapter {
   channel: NotificationChannel;
@@ -98,6 +114,27 @@ export interface ChannelAdapter {
     payload: ChannelDeliveryPayload,
     destination: ChannelDestination,
   ): Promise<DeliveryResult>;
+  /**
+   * Optional: edit a previously-sent message in place. Channels that
+   * cannot edit (push, email, SMS) omit this and the router treats
+   * them as `"unsupported"`. Adapters that implement it use
+   * `delivery.messageId` (captured at send time) as the channel-native
+   * handle for the in-place update.
+   */
+  update?(
+    delivery: ChannelUpdateContext,
+    patch: ChannelUpdatePayload,
+  ): Promise<DeliveryResult>;
+}
+
+/** Per-delivery state an adapter needs to update a previously-sent message. */
+export interface ChannelUpdateContext {
+  /** notification_deliveries.id */
+  deliveryId: string;
+  /** Channel-native destination (e.g. Slack chat id). */
+  destination: string;
+  /** Channel-native message identifier captured at send time. */
+  messageId: string | null;
 }
 
 // -- Decision engine output ---------------------------------------------------

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

@@ -28,7 +28,7 @@ mock.module("../util/logger.js", () => ({
 // Use encrypted backend with a temp store path
 // ---------------------------------------------------------------------------
 
-import { _setStorePath } from "../security/encrypted-store.js";
+import { setStorePathForTesting } from "../__tests__/encrypted-store-test-helpers.js";
 import { _resetBackend } from "../security/secure-keys.js";
 
 const TEST_DIR = join(
@@ -130,6 +130,7 @@ mock.module("./oauth-store.js", () => ({
 // Imports (after mocks)
 // ---------------------------------------------------------------------------
 
+import { credentialKey } from "../security/credential-key.js";
 import { setSecureKeyAsync } from "../security/secure-keys.js";
 import {
   _resetInflightRefreshes,
@@ -163,7 +164,7 @@ afterAll(() => {
 });
 
 beforeEach(() => {
-  _setStorePath(STORE_PATH);
+  setStorePathForTesting(STORE_PATH);
   _setMetadataPath(join(TEST_DIR, "metadata.json"));
   _resetBackend();
   _resetRefreshBreakers();
@@ -251,11 +252,22 @@ function createConnection(service = "google"): BYOOAuthConnection {
   return new BYOOAuthConnection({
     id: `conn-${service}`,
     provider: service,
-    baseUrl: "https://gmail.googleapis.com/gmail/v1/users/me",
+    baseUrl:
+      service === "telegram"
+        ? "https://api.telegram.org"
+        : "https://gmail.googleapis.com/gmail/v1/users/me",
     accountInfo: null,
   });
 }
 
+async function setupTelegramCredential() {
+  await setupCredential("telegram");
+  await setSecureKeyAsync(
+    credentialKey("telegram", "bot_token"),
+    "telegram-test-token",
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
@@ -437,6 +449,58 @@ describe("BYOOAuthConnection", () => {
       expect(headers.get("X-Custom-Header")).toBe("custom-value");
       expect(headers.get("Authorization")).toBe("Bearer test-access-token");
     });
+
+    test("uses Telegram Bot API token URL format without Bearer auth", async () => {
+      await setupTelegramCredential();
+      const conn = createConnection("telegram");
+
+      const result = await conn.request({
+        method: "GET",
+        path: "/getMe",
+      });
+
+      expect(result.status).toBe(200);
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+
+      const [url, init] = mockFetch.mock.calls[0];
+      expect(url).toBe("https://api.telegram.org/bottelegram-test-token/getMe");
+      const headers = (init as RequestInit).headers as Headers;
+      expect(headers.has("Authorization")).toBe(false);
+    });
+
+    test("does not double-prefix Telegram paths that already include bot token", async () => {
+      await setupTelegramCredential();
+      const conn = createConnection("telegram");
+
+      await conn.request({
+        method: "GET",
+        path: "/bottelegram-test-token/getMe",
+      });
+
+      const [url, init] = mockFetch.mock.calls[0];
+      expect(url).toBe("https://api.telegram.org/bottelegram-test-token/getMe");
+      const headers = (init as RequestInit).headers as Headers;
+      expect(headers.has("Authorization")).toBe(false);
+    });
+
+    test("returns Telegram 401 responses without OAuth refresh", async () => {
+      await setupTelegramCredential();
+      const conn = createConnection("telegram");
+      const refreshCallsBefore = mockRefreshOAuth2Token.mock.calls.length;
+
+      globalThis.fetch = mock(() =>
+        Promise.resolve(new Response("Unauthorized", { status: 401 })),
+      ) as unknown as typeof fetch;
+
+      const result = await conn.request({
+        method: "GET",
+        path: "/getMe",
+      });
+
+      expect(result.status).toBe(401);
+      expect(result.body).toBe("Unauthorized");
+      expect(mockRefreshOAuth2Token.mock.calls.length).toBe(refreshCallsBefore);
+    });
   });
 
   describe("proactive token refresh", () => {

package/src/oauth/byo-connection.ts

@@ -46,7 +46,11 @@ export class BYOOAuthConnection implements OAuthConnection {
       this.provider,
       async (token) => {
         const effectiveBaseUrl = req.baseUrl ?? this.baseUrl;
-        let fullUrl = `${effectiveBaseUrl}${req.path}`;
+        const isTelegram = this.provider === "telegram";
+        const requestPath = isTelegram
+          ? buildTelegramBotApiPath(req.path, token)
+          : req.path;
+        let fullUrl = `${effectiveBaseUrl}${requestPath}`;
 
         if (req.query && Object.keys(req.query).length > 0) {
           const params = new URLSearchParams();
@@ -60,8 +64,12 @@ export class BYOOAuthConnection implements OAuthConnection {
           fullUrl += `?${params.toString()}`;
         }
 
+        const logUrl = isTelegram
+          ? redactTelegramBotTokenFromUrl(fullUrl, token)
+          : fullUrl;
+
         log.debug(
-          { method: req.method, url: fullUrl, provider: this.provider },
+          { method: req.method, url: logUrl, provider: this.provider },
           "Making authenticated request",
         );
 
@@ -76,18 +84,23 @@ export class BYOOAuthConnection implements OAuthConnection {
             headers.set(key, value);
           }
         }
-        headers.set("Authorization", `Bearer ${token}`);
+        if (!isTelegram) {
+          headers.set("Authorization", `Bearer ${token}`);
+        }
 
         const resp = await fetch(fullUrl, {
           method: req.method,
           headers,
           body: req.body ? JSON.stringify(req.body) : undefined,
           signal: req.signal
-            ? AbortSignal.any([req.signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)])
+            ? AbortSignal.any([
+                req.signal,
+                AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+              ])
             : AbortSignal.timeout(REQUEST_TIMEOUT_MS),
         });
 
-        if (resp.status === 401) {
+        if (resp.status === 401 && !isTelegram) {
           // Throw with a status property so withValidToken detects the 401
           // and triggers its refresh-and-retry logic.
           const err = new Error(`HTTP 401 from ${this.provider}`);
@@ -108,6 +121,20 @@ export class BYOOAuthConnection implements OAuthConnection {
   }
 }
 
+function buildTelegramBotApiPath(path: string, token: string): string {
+  if (path.startsWith("/bot")) return path;
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  return `/bot${token}${normalizedPath}`;
+}
+
+function redactTelegramBotTokenFromUrl(url: string, token: string): string {
+  const redactedStoredToken = url.split(token).join("[REDACTED]");
+  return redactedStoredToken.replace(
+    /\/bot[^/?#]+(?=\/|[?#]|$)/g,
+    "/bot[REDACTED]",
+  );
+}
+
 async function buildResponse(resp: Response): Promise<OAuthConnectionResponse> {
   const headers: Record<string, string> = {};
   resp.headers.forEach((value, key) => {

package/src/oauth/connect-orchestrator.ts

@@ -64,6 +64,12 @@ export interface OAuthConnectOptions {
   openUrl?: (url: string) => void;
   /** Send a message to the client (e.g. open_url). */
   sendToClient?: (msg: { type: string; [key: string]: unknown }) => void;
+  /**
+   * Conversation this connect flow belongs to. When set and `sendToClient`
+   * is used, the emitted `open_url` event carries it on the inner message
+   * so downstream consumers can route per-conversation.
+   */
+  conversationId?: string;
 
   /**
    * Callback transport to use for the OAuth redirect.
@@ -331,6 +337,9 @@ export async function orchestrateOAuthConnect(
               type: "open_url",
               url,
               title: `Connect ${options.service}`,
+              ...(options.conversationId
+                ? { conversationId: options.conversationId }
+                : {}),
             });
           } else {
             log.warn(

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

@@ -9,6 +9,7 @@ let mockConnection: Record<string, unknown> | undefined;
 let mockAccessToken: string | undefined;
 let mockConfig: Record<string, unknown> = {};
 let mockPlatformClient: Record<string, unknown> | null = null;
+let syncManualTokenCalls: string[] = [];
 
 // ---------------------------------------------------------------------------
 // Module mocks (must precede imports of the module under test)
@@ -47,6 +48,15 @@ mock.module("./credential-token-resolver.js", () => ({
   }),
 }));
 
+mock.module("./manual-token-connection.js", () => ({
+  syncManualTokenConnection: async (provider: string) => {
+    syncManualTokenCalls.push(provider);
+    if (provider === "telegram" && mockConnection?.provider === "telegram") {
+      mockConnection.accountInfo = "@example_bot";
+    }
+  },
+}));
+
 mock.module("../config/loader.js", () => ({
   getConfig: () => mockConfig,
 }));
@@ -92,6 +102,7 @@ function setupDefaults(): void {
   mockProvider = {
     provider: "google",
     baseUrl: "https://gmail.googleapis.com/gmail/v1/users/me",
+    authorizeUrl: "https://accounts.google.com/o/oauth2/v2/auth",
     managedServiceConfigKey: null,
   };
   mockConnection = {
@@ -121,6 +132,7 @@ function setupDefaults(): void {
     },
   };
   mockPlatformClient = makeMockClient();
+  syncManualTokenCalls = [];
 }
 
 // ---------------------------------------------------------------------------
@@ -159,6 +171,42 @@ describe("resolveOAuthConnection", () => {
     expect(result.accountInfo).toBe("user@example.com");
   });
 
+  test("managed path falls back to displayed account label when account_identifier does not match", async () => {
+    mockProvider!.managedServiceConfigKey = "google-oauth";
+    const fetchPaths: string[] = [];
+    mockPlatformClient = {
+      ...makeMockClient(),
+      fetch: mock(async (path: string) => {
+        fetchPaths.push(path);
+        if (path.includes("account_identifier=alice%40example.com")) {
+          return new Response(JSON.stringify({ results: [] }), { status: 200 });
+        }
+        return new Response(
+          JSON.stringify({
+            results: [
+              {
+                id: "platform-conn-1",
+                account_label: "alice@example.com",
+              },
+            ],
+          }),
+          { status: 200 },
+        );
+      }),
+    };
+
+    const result = await resolveOAuthConnection("google", {
+      account: "alice@example.com",
+    });
+
+    expect(result).toBeInstanceOf(PlatformOAuthConnection);
+    expect(result.accountInfo).toBe("alice@example.com");
+    expect(fetchPaths).toEqual([
+      "/v1/assistants/asst-123/oauth/connections/?provider=google&status=ACTIVE&account_identifier=alice%40example.com",
+      "/v1/assistants/asst-123/oauth/connections/?provider=google&status=ACTIVE",
+    ]);
+  });
+
   test("returns PlatformOAuthConnection when GitHub is in managed mode", async () => {
     mockProvider!.provider = "github";
     mockProvider!.managedServiceConfigKey = "github-oauth";
@@ -216,6 +264,34 @@ describe("resolveOAuthConnection", () => {
       }),
     ).rejects.toThrow(/No active OAuth connection found/);
   });
+
+  test("BYO path reconciles manual-token providers before exact account lookup", async () => {
+    mockProvider = {
+      provider: "telegram",
+      baseUrl: "https://api.telegram.org",
+      authorizeUrl: "urn:manual-token",
+      managedServiceConfigKey: null,
+    };
+    mockConnection = {
+      id: "conn-telegram",
+      provider: "telegram",
+      oauthAppId: "app-telegram",
+      accountInfo: null,
+      grantedScopes: JSON.stringify([]),
+      status: "active",
+      clientId: "manual-config",
+    };
+    mockAccessToken = "telegram-test-token";
+
+    const result = await resolveOAuthConnection("telegram", {
+      account: "@example_bot",
+    });
+
+    expect(syncManualTokenCalls).toEqual(["telegram"]);
+    expect(mockConnection.accountInfo).toBe("@example_bot");
+    expect(result).toBeInstanceOf(BYOOAuthConnection);
+    expect(result.id).toBe("conn-telegram");
+  });
 });
 
 describe("resolveEffectiveBaseUrl", () => {

package/src/oauth/connection-resolver.ts

@@ -9,6 +9,7 @@ import { getLogger } from "../util/logger.js";
 import { BYOOAuthConnection } from "./byo-connection.js";
 import type { OAuthConnection } from "./connection.js";
 import { getConnectionAccessTokenResult } from "./credential-token-resolver.js";
+import { syncManualTokenConnection } from "./manual-token-connection.js";
 import { getActiveConnection, getProvider } from "./oauth-store.js";
 import { PlatformOAuthConnection } from "./platform-connection.js";
 
@@ -82,6 +83,10 @@ export async function resolveOAuthConnection(
   }
 
   // BYO path — requires a local connection row, access token, and base URL.
+  if (providerRow?.authorizeUrl === "urn:manual-token") {
+    await syncManualTokenConnection(provider);
+  }
+
   const conn = getActiveConnection(provider, { clientId, account });
   if (!conn) {
     const filters = [
@@ -185,20 +190,26 @@ interface ResolvePlatformConnectionIdOptions {
   account?: string;
 }
 
+interface PlatformConnectionEntry {
+  id: string;
+  account_label?: string | null;
+}
+
 /**
- * Fetch the platform-side connection ID for a managed provider by calling
- * the List Connections endpoint.
+ * Fetch active platform connections for a managed provider by calling the
+ * List Connections endpoint.
  */
-async function resolvePlatformConnectionId(
-  options: ResolvePlatformConnectionIdOptions,
-): Promise<string> {
-  const { client, provider, account } = options;
-
+async function fetchPlatformConnections(options: {
+  client: VellumPlatformClient;
+  provider: string;
+  accountIdentifier?: string;
+}): Promise<PlatformConnectionEntry[]> {
+  const { client, provider, accountIdentifier } = options;
   const params = new URLSearchParams();
   params.set("provider", provider);
   params.set("status", "ACTIVE");
-  if (account) {
-    params.set("account_identifier", account);
+  if (accountIdentifier) {
+    params.set("account_identifier", accountIdentifier);
   }
 
   const path = `/v1/assistants/${client.platformAssistantId}/oauth/connections/?${params.toString()}`;
@@ -219,7 +230,35 @@ async function resolvePlatformConnectionId(
     Array.isArray(body)
       ? body
       : ((body as Record<string, unknown>).results ?? [])
-  ) as Array<{ id: string; account_label?: string }>;
+  ) as PlatformConnectionEntry[];
+  return connections;
+}
+
+/**
+ * Fetch the platform-side connection ID for a managed provider by calling
+ * the List Connections endpoint.
+ */
+async function resolvePlatformConnectionId(
+  options: ResolvePlatformConnectionIdOptions,
+): Promise<string> {
+  const { client, provider, account } = options;
+
+  let connections = await fetchPlatformConnections({
+    client,
+    provider,
+    accountIdentifier: account,
+  });
+
+  if (account && connections.length === 0) {
+    const unfilteredConnections = await fetchPlatformConnections({
+      client,
+      provider,
+    });
+    connections = unfilteredConnections.filter(
+      (connection) =>
+        connection.account_label === account || connection.id === account,
+    );
+  }
 
   if (connections.length === 0) {
     throw new Error(