@vellumai/assistant 0.8.5 → 0.8.6

package/src/notifications/edit-notification.ts

@@ -0,0 +1,201 @@
+/**
+ * Edit an already-sent notification.
+ *
+ * Patches the home-feed entry the user actually sees, then attempts a
+ * best-effort update of any per-channel deliveries that support
+ * in-place edits (Slack via chat.update today). Feed-only fields
+ * (`urgency`, `status`) skip the channel hop — channel messages don't
+ * carry that metadata, only body/title.
+ */
+
+import {
+  type FeedItem,
+  type FeedItemStatus,
+  type FeedItemUrgency,
+} from "../home/feed-types.js";
+import { patchFeedItemContent } from "../home/feed-writer.js";
+import { getLogger } from "../util/logger.js";
+import { findLatestDecisionByEventId } from "./decisions-store.js";
+import {
+  findDeliveriesByDecisionId,
+  type NotificationDeliveryRow,
+  updateDeliveryRenderedCopy,
+} from "./deliveries-store.js";
+import { getBroadcaster } from "./emit-signal.js";
+import type { NotificationChannel } from "./types.js";
+
+const log = getLogger("edit-notification");
+
+/** Prefix used by `home-feed-side-effect` when minting feed item ids. */
+export const FEED_ITEM_ID_PREFIX = "notif:";
+
+export interface EditNotificationParams {
+  /** Feed item id (`notif:<uuid>`) or bare signal uuid. */
+  id: string;
+  title?: string;
+  body?: string;
+  urgency?: FeedItemUrgency;
+  status?: FeedItemStatus;
+}
+
+export type ChannelEditOutcome =
+  | "updated"
+  | "unsupported"
+  | "skipped"
+  | "failed";
+
+export interface ChannelEditResult {
+  channel: NotificationChannel;
+  deliveryId: string;
+  outcome: ChannelEditOutcome;
+  /** Reason for skip/failure when `outcome` is not `"updated"`. */
+  reason?: string;
+}
+
+export interface EditNotificationResult {
+  feedItem: FeedItem;
+  channels: ChannelEditResult[];
+}
+
+/**
+ * Normalize a user-supplied id into the canonical feed-item form
+ * (`notif:<uuid>`). Accepts either the full prefixed id or a bare uuid.
+ */
+export function normalizeFeedItemId(id: string): string {
+  const trimmed = id.trim();
+  if (trimmed.startsWith(FEED_ITEM_ID_PREFIX)) return trimmed;
+  return `${FEED_ITEM_ID_PREFIX}${trimmed}`;
+}
+
+/** Strip the `notif:` prefix to recover the original signal/event id. */
+export function feedItemIdToSignalId(feedItemId: string): string {
+  return feedItemId.startsWith(FEED_ITEM_ID_PREFIX)
+    ? feedItemId.slice(FEED_ITEM_ID_PREFIX.length)
+    : feedItemId;
+}
+
+/**
+ * Apply an edit to a previously-sent notification.
+ *
+ * Returns the updated feed item plus per-channel update outcomes.
+ * Resolves to `null` when the feed item id isn't on disk so callers
+ * can surface a clear "not found" to the user.
+ */
+export async function editNotification(
+  params: EditNotificationParams,
+): Promise<EditNotificationResult | null> {
+  const feedItemId = normalizeFeedItemId(params.id);
+
+  const feedItem = await patchFeedItemContent(feedItemId, {
+    title: params.title,
+    summary: params.body,
+    urgency: params.urgency,
+    status: params.status,
+  });
+  if (!feedItem) {
+    log.warn({ feedItemId }, "Edit requested for unknown feed item");
+    return null;
+  }
+
+  // Only edit channel messages when the user-visible text changed.
+  // Urgency/status are feed-only — pushing a channel update for those
+  // alone would re-deliver the same body and confuse the recipient.
+  const shouldUpdateChannels =
+    params.title !== undefined || params.body !== undefined;
+  if (!shouldUpdateChannels) {
+    return { feedItem, channels: [] };
+  }
+
+  const signalId = feedItemIdToSignalId(feedItemId);
+  const decision = findLatestDecisionByEventId(signalId);
+  if (!decision) {
+    log.info(
+      { feedItemId, signalId },
+      "Feed item has no persisted decision — skipping channel updates",
+    );
+    return { feedItem, channels: [] };
+  }
+
+  const deliveries = findDeliveriesByDecisionId(decision.id);
+  const channels = await updateChannelDeliveries(deliveries, {
+    title: params.title,
+    body: params.body,
+  });
+
+  return { feedItem, channels };
+}
+
+async function updateChannelDeliveries(
+  deliveries: NotificationDeliveryRow[],
+  patch: { title?: string; body?: string },
+): Promise<ChannelEditResult[]> {
+  const broadcaster = getBroadcaster();
+  const results: ChannelEditResult[] = [];
+
+  for (const delivery of deliveries) {
+    const channel = delivery.channel as NotificationChannel;
+    if (delivery.status !== "sent") {
+      results.push({
+        channel,
+        deliveryId: delivery.id,
+        outcome: "skipped",
+        reason: `delivery status is ${delivery.status}`,
+      });
+      continue;
+    }
+
+    const adapter = broadcaster.getAdapter(channel);
+    if (!adapter?.update) {
+      results.push({
+        channel,
+        deliveryId: delivery.id,
+        outcome: "unsupported",
+        reason: `${channel} adapter does not support in-place edits`,
+      });
+      continue;
+    }
+
+    try {
+      const result = await adapter.update(
+        {
+          deliveryId: delivery.id,
+          destination: delivery.destination,
+          messageId: delivery.messageId,
+        },
+        patch,
+      );
+      if (!result.success) {
+        results.push({
+          channel,
+          deliveryId: delivery.id,
+          outcome: "failed",
+          reason: result.error ?? "unknown error",
+        });
+        continue;
+      }
+      updateDeliveryRenderedCopy(delivery.id, {
+        renderedTitle: patch.title,
+        renderedBody: patch.body,
+      });
+      results.push({
+        channel,
+        deliveryId: delivery.id,
+        outcome: "updated",
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.error(
+        { err, channel, deliveryId: delivery.id },
+        "Channel adapter update threw",
+      );
+      results.push({
+        channel,
+        deliveryId: delivery.id,
+        outcome: "failed",
+        reason: message,
+      });
+    }
+  }
+
+  return results;
+}

package/src/notifications/emit-signal.ts

@@ -51,7 +51,7 @@ const log = getLogger("emit-signal");
 
 let broadcasterInstance: NotificationBroadcaster | null = null;
 
-function getBroadcaster(): NotificationBroadcaster {
+export function getBroadcaster(): NotificationBroadcaster {
   if (!broadcasterInstance) {
     broadcasterInstance = new NotificationBroadcaster([
       new VellumAdapter(broadcastMessage),
@@ -188,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 {
@@ -223,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", () => {