@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/src/notifications/broadcaster.ts

@@ -229,6 +229,13 @@ export interface BroadcastDecisionOptions {
   onConversationCreated?: OnConversationCreatedFn;
   /** Deadline override for tests; defaults to PLATFORM_OUTCOME_DEADLINE_MS. */
   platformOutcomeDeadlineMs?: number;
+  /**
+   * Array each channel's result is appended to as it settles, and the same
+   * array `broadcastDecision` returns. Pass one when a broadcast that throws
+   * partway still has to be told apart from one that touched no channel: the
+   * return value is lost to the throw, the sink is not.
+   */
+  resultsSink?: NotificationDeliveryResult[];
 }
 
 // Cap on how long the deferred vellum send waits for the platform dispatch
@@ -348,7 +355,7 @@ export class NotificationBroadcaster {
       signal.contextPayload
         ? parseAccessRequestPayload(signal.contextPayload)
         : undefined;
-    const results: NotificationDeliveryResult[] = [];
+    const results: NotificationDeliveryResult[] = options?.resultsSink ?? [];
 
     // Vellum pairing carried forward for the platform channel's deep link.
     // A single-pass carry is safe because orderedChannels sorts vellum first.
@@ -794,7 +801,9 @@ export class NotificationBroadcaster {
   /**
    * Dispatch a prepared payload through its channel adapter and record the
    * outcome (delivery row status + results entry). Returns the adapter's
-   * result, or null when the send threw.
+   * result, or null when the send threw. The recorded result tracks what the
+   * adapter actually did, so a status write that fails after a successful
+   * send is logged and swallowed rather than downgrading the result.
    */
   private async sendAndRecord(
     dispatch: PendingChannelDispatch,
@@ -822,14 +831,25 @@ export class NotificationBroadcaster {
         const resolvedMessageId =
           adapterResult.messageId ?? pairing.messageId ?? undefined;
         if (hasPersistedDecision) {
-          updateDeliveryStatus(
-            deliveryId,
-            "sent",
-            undefined,
-            adapterResult.messageId
-              ? { messageId: adapterResult.messageId }
-              : undefined,
-          );
+          try {
+            updateDeliveryStatus(
+              deliveryId,
+              "sent",
+              undefined,
+              adapterResult.messageId
+                ? { messageId: adapterResult.messageId }
+                : undefined,
+            );
+          } catch (statusErr) {
+            // The message is already out; a lost status write must not turn
+            // this into a `failed` result. Callers read the results to decide
+            // whether a retry would re-deliver, so reporting a real send as
+            // failed releases the signal's dedupe claim and double-sends.
+            log.warn(
+              { err: statusErr, channel, signalId: signal.signalId },
+              "Failed to record a sent delivery; the send itself succeeded",
+            );
+          }
         }
         results.push(
           buildDeliveryResult(dispatch, "sent", {

package/src/notifications/copy-composer.ts

@@ -30,6 +30,7 @@ import {
   NOTIFICATION_TITLE_MAX_LENGTH,
   readPayloadString,
   sanitizeIdentityField,
+  sanitizeMessagePreview,
 } from "./notification-utils.js";
 import type {
   NotificationSignal,
@@ -47,6 +48,36 @@ function str(value: unknown, fallback: string): string {
   return fallback;
 }
 
+/**
+ * Read an untrusted payload string for interpolation into copy: sanitized
+ * like an identity field, undefined when the value is absent, not a string,
+ * or sanitizes down to nothing.
+ */
+function optionalSanitizedPayloadField(value: unknown): string | undefined {
+  return typeof value === "string"
+    ? nonEmpty(sanitizeIdentityField(value))
+    : undefined;
+}
+
+/** {@link optionalSanitizedPayloadField} with a fallback for the empty case. */
+function sanitizedPayloadField(value: unknown, fallback: string): string {
+  return optionalSanitizedPayloadField(value) ?? fallback;
+}
+
+/**
+ * Plugin and schedule names from a `schedule.*` payload, with the fallbacks
+ * every schedule template shares.
+ */
+function schedulePayloadNames(payload: Record<string, unknown>): {
+  scheduleName: string;
+  pluginName: string;
+} {
+  return {
+    scheduleName: sanitizedPayloadField(payload.scheduleName, "a schedule"),
+    pluginName: sanitizedPayloadField(payload.pluginName, "A plugin"),
+  };
+}
+
 /**
  * Derive a short notification title from a message body. Trims to the
  * first sentence terminator when present, then caps the result at
@@ -115,6 +146,44 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
     body: str(payload.message, "A reminder has fired"),
   }),
 
+  // The schedule.* fields below (names, cadence, error reason) originate in
+  // plugin-authored declaration files, so they are sanitized like any other
+  // untrusted actor-controlled string before interpolation.
+  "schedule.declared": (payload) => {
+    const { scheduleName, pluginName } = schedulePayloadNames(payload);
+    const cadence = optionalSanitizedPayloadField(payload.cadence);
+    const cadenceSuffix = cadence ? ` (${cadence})` : "";
+    return {
+      title: `New plugin schedule: ${scheduleName}`,
+      body: `Plugin "${pluginName}" armed the schedule "${scheduleName}"${cadenceSuffix}. It will run automatically; you can disable it from your schedules.`,
+    };
+  },
+
+  "schedule.definition_changed": (payload) => {
+    const { scheduleName, pluginName } = schedulePayloadNames(payload);
+    return {
+      title: `Plugin schedule changed: ${scheduleName}`,
+      body: `Plugin "${pluginName}" changed the definition of its schedule "${scheduleName}".`,
+    };
+  },
+
+  "schedule.definition_error": (payload) => {
+    const { scheduleName, pluginName } = schedulePayloadNames(payload);
+    const reason = sanitizeMessagePreview(
+      str(payload.reason, "the declaration is invalid"),
+    );
+    // `paused` says the schedule stopped running over this error rather than
+    // carrying on with what it last loaded, which is the part the user acts on.
+    const pausedSuffix =
+      payload.paused === true
+        ? " It is paused until the declaration loads again."
+        : "";
+    return {
+      title: `Plugin schedule error: ${scheduleName}`,
+      body: `Plugin "${pluginName}" has a schedule "${scheduleName}" that could not be loaded: ${reason}${pausedSuffix}`,
+    };
+  },
+
   "guardian.question": (payload) => {
     const question = str(
       payload.questionText,

package/src/notifications/emit-signal.ts

@@ -21,6 +21,7 @@ import type { ConversationCreateType } from "../persistence/conversation-types.j
 import { isPlatformClientConfigured } from "../platform/client.js";
 import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import { getLogger } from "../util/logger.js";
+import { withSqliteRetry } from "../util/sqlite-retry.js";
 import { VellumAdapter } from "./adapters/macos.js";
 import { PlatformPushAdapter } from "./adapters/platform.js";
 import { SlackAdapter } from "./adapters/slack.js";
@@ -36,7 +37,7 @@ import {
   type DeterministicCheckContext,
   runDeterministicChecks,
 } from "./deterministic-checks.js";
-import { createEvent, updateEventDedupeKey } from "./events-store.js";
+import { createEvent, setEventDedupeKey } from "./events-store.js";
 import { writeHomeFeedItemForSignal } from "./home-feed-side-effect.js";
 import { dispatchDecision } from "./runtime-dispatch.js";
 import type {
@@ -226,6 +227,25 @@ export interface EmitSignalResult {
   dispatched: boolean;
   reason: string;
   deliveryResults: NotificationDeliveryResult[];
+  /**
+   * True when the pipeline threw before reaching a verdict. Dispatch, dedupe,
+   * suppression, and a blocked deterministic check are all verdicts. Callers
+   * that latch their own guard on a completed emit branch on this flag;
+   * `reason` is a human-facing log string and never a control signal.
+   */
+  pipelineFailed: boolean;
+}
+
+/**
+ * True when at least one channel adapter has already been handed the signal.
+ * `sent` is a completed delivery; `pending` is the platform push that passed
+ * its outcome deadline and is still in flight. Both mean a retry would
+ * re-deliver.
+ */
+function hasChannelSideEffect(
+  results: readonly NotificationDeliveryResult[],
+): boolean {
+  return results.some((r) => r.status === "sent" || r.status === "pending");
 }
 
 /**
@@ -245,6 +265,15 @@ export async function emitNotificationSignal<TEventName extends string>(
 ): Promise<EmitSignalResult> {
   const signalId = uuid();
 
+  // The event row claims `params.dedupeKey` when it lands, and the failure
+  // path below releases that claim.
+  let eventPersisted = false;
+
+  // Every channel result the broadcast produces, appended as each channel
+  // settles. A throw discards the dispatch return value, so this is how the
+  // failure path learns which channels already ran.
+  const channelResults: NotificationDeliveryResult[] = [];
+
   const signal: NotificationSignal<TEventName> = {
     signalId,
     createdAt: Date.now(),
@@ -263,16 +292,27 @@ export async function emitNotificationSignal<TEventName extends string>(
   };
 
   try {
-    // Step 1: Persist the event
-    const eventRow = createEvent({
-      id: signalId,
-      sourceEventName: params.sourceEventName,
-      sourceChannel: params.sourceChannel,
-      sourceContextId: params.sourceContextId,
-      attentionHints: params.attentionHints,
-      payload: (params.contextPayload ?? {}) as Record<string, unknown>,
-      dedupeKey: params.dedupeKey,
-    });
+    // Step 1: Persist the event. The insert contends with other writers on
+    // the shared database (notably the memory worker's bulk writes), and a
+    // lost signal is unrecoverable (the producer has already returned by
+    // the time contention surfaces), so transient `SQLITE_BUSY`/`SQLITE_IOERR`
+    // rides the shared retry helper instead of failing the pipeline.
+    const eventRow = await withSqliteRetry(
+      () =>
+        createEvent({
+          id: signalId,
+          sourceEventName: params.sourceEventName,
+          sourceChannel: params.sourceChannel,
+          sourceContextId: params.sourceContextId,
+          attentionHints: params.attentionHints,
+          payload: (params.contextPayload ?? {}) as Record<string, unknown>,
+          dedupeKey: params.dedupeKey,
+        }),
+      {
+        op: "notification-create-event",
+        context: { signalId, sourceEventName: params.sourceEventName },
+      },
+    );
 
     if (!eventRow) {
       log.info(
@@ -285,8 +325,10 @@ export async function emitNotificationSignal<TEventName extends string>(
         dispatched: false,
         reason: "Signal deduplicated at event store level",
         deliveryResults: [],
+        pipelineFailed: false,
       };
     }
+    eventPersisted = true;
 
     // Step 1.5: Source-active pre-gate. visibleInSourceNow is a hard invariant
     // the decision engine cannot override, and it depends only on the signal —
@@ -307,6 +349,7 @@ export async function emitNotificationSignal<TEventName extends string>(
         dispatched: false,
         reason: `Signal suppressed: ${sourceActiveCheck.reason}`,
         deliveryResults: [],
+        pipelineFailed: false,
       };
     }
 
@@ -427,7 +470,7 @@ export async function emitNotificationSignal<TEventName extends string>(
     // only the producer's dedupeKey, which may be null).
     if (decision.dedupeKey && !params.dedupeKey) {
       try {
-        updateEventDedupeKey(signalId, decision.dedupeKey);
+        setEventDedupeKey(signalId, decision.dedupeKey);
       } catch (err) {
         log.warn(
           { err, signalId },
@@ -458,6 +501,7 @@ export async function emitNotificationSignal<TEventName extends string>(
           dispatched: false,
           reason: `Signal blocked by deterministic checks: ${checkResult.reason}`,
           deliveryResults: [],
+          pipelineFailed: false,
         };
       }
     }
@@ -472,9 +516,10 @@ export async function emitNotificationSignal<TEventName extends string>(
       signal,
       decision,
       broadcaster,
-      params.onConversationCreated
-        ? { onConversationCreated: params.onConversationCreated }
-        : undefined,
+      {
+        onConversationCreated: params.onConversationCreated,
+        resultsSink: channelResults,
+      },
     );
 
     // Step 5: Mirror background-origin signals into the home activity feed.
@@ -511,6 +556,7 @@ export async function emitNotificationSignal<TEventName extends string>(
       dispatched: dispatchResult.dispatched,
       reason: dispatchResult.reason,
       deliveryResults: dispatchResult.deliveryResults,
+      pipelineFailed: false,
     };
   } catch (err) {
     const errMsg = err instanceof Error ? err.message : String(err);
@@ -518,6 +564,26 @@ export async function emitNotificationSignal<TEventName extends string>(
       { err: errMsg, signalId, sourceEventName: params.sourceEventName },
       "Signal pipeline failed",
     );
+    // The persisted event claimed this signal's dedupe key before the
+    // pipeline threw. Leaving the claim in place makes every retry
+    // short-circuit as a duplicate of an emit that never reached a verdict,
+    // so release it. The row itself stays as the audit trail of the attempt.
+    //
+    // A partially dispatched broadcast is the exception. Its retry gets a
+    // fresh decision id, and delivery dedupe is keyed to the decision, so
+    // the channels that already went out would go out again. Keeping the
+    // claim costs the channels that did not get the signal; releasing it
+    // double-sends to the ones that did.
+    if (eventPersisted && !hasChannelSideEffect(channelResults)) {
+      try {
+        setEventDedupeKey(signalId, null);
+      } catch (releaseErr) {
+        log.warn(
+          { err: releaseErr, signalId },
+          "Failed to release the dedupe key of a failed signal",
+        );
+      }
+    }
     if (params.throwOnError) {
       throw err instanceof Error ? err : new Error(errMsg);
     }
@@ -527,6 +593,7 @@ export async function emitNotificationSignal<TEventName extends string>(
       dispatched: false,
       reason: `Signal pipeline failed: ${errMsg}`,
       deliveryResults: [],
+      pipelineFailed: true,
     };
   }
 }

package/src/notifications/events-store.ts

@@ -91,8 +91,16 @@ export function createEvent(
   return row;
 }
 
-/** Update the dedupeKey on an existing event (e.g. when the decision engine generates one). */
-export function updateEventDedupeKey(eventId: string, dedupeKey: string): void {
+/**
+ * Write an existing event's dedupe key. A string claims that key, which is
+ * how a decision-engine-generated key lands on the row. `null` releases the
+ * claim so a later event may take it while this row stays for the audit
+ * trail.
+ */
+export function setEventDedupeKey(
+  eventId: string,
+  dedupeKey: string | null,
+): void {
   const db = getDb();
   db.update(notificationEvents)
     .set({ dedupeKey, updatedAt: Date.now() })

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

@@ -170,9 +170,12 @@ function deriveFallbackTitle(summary: string): string {
   // fence into a stray backtick). Ordered markers matter most: the seed prompt
   // asks the model for numbered lists, and a leading `1.` also reads as a
   // sentence terminator, which would truncate the title to the first digit.
-  // The leading-space allowance and rule set mirror `flattenToPlainText` in
-  // workspace migration 138, which must stay self-contained and so cannot share
-  // this code. A backfilled title and a freshly written one have to match.
+  //
+  // Deliberately regex-based, unlike the remark-backed
+  // `stripMarkdownForPreview`. The leading-space allowance and rule set mirror
+  // `flattenToPlainText` in workspace migration 138, which must stay
+  // self-contained and so cannot share code with either: a backfilled title and
+  // a freshly written one have to match, which a parser swap would break.
   const deblocked = summary
     .replace(/^\s{0,3}(?:```|~~~).*$/gm, "")
     .replace(/^\s{0,3}#{1,6}\s+/gm, "")

package/src/notifications/notification-utils.ts

@@ -6,6 +6,10 @@
  * circular dependencies.
  */
 
+import type { Root, RootContent } from "mdast";
+
+import { parseMarkdown } from "../messaging/content/parse.js";
+import { stripAnsiAndControlChars } from "../util/ansi.js";
 import { isPlainObject } from "../util/object.js";
 
 // ── String helpers ──────────────────────────────────────────────────────────
@@ -59,14 +63,178 @@ export function truncate(text: string, maxLength: number): string {
   return text.slice(0, maxLength - 1) + "…";
 }
 
+// ── Markdown flattening ─────────────────────────────────────────────────────
+
+/**
+ * Node types whose children are blocks rather than an inline run, so their text
+ * needs a paragraph break between children instead of being butted together.
+ */
+const BLOCK_CONTAINER_TYPES = new Set([
+  "blockquote",
+  "listItem",
+  "footnoteDefinition",
+]);
+
+/** Plain text of one mdast node, markers and media dropped. */
+function nodeText(node: RootContent): string {
+  switch (node.type) {
+    // Literal runs. Code keeps its value: a fenced block previews as its code,
+    // and the parser has already decided what is code, so markdown-looking
+    // lines inside it are safe.
+    case "text":
+    case "inlineCode":
+    case "code":
+      return node.value;
+    // Raw HTML, which the parser splits into tag nodes around the text between
+    // them. The in-app renderer registers no `rehype-raw`, so tags and comments
+    // display as nothing there; dropping the tag nodes keeps the preview
+    // matching what the reply actually looks like, and keeps the contents of an
+    // HTML comment off the lock screen. The visible text between a tag pair is
+    // its own `text` node and survives.
+    case "html":
+      return "";
+    // Media carries no prose. A caller names it separately when the flattened
+    // text comes up empty; see {@link mediaEmbedAltTexts}.
+    //
+    // A space rather than nothing: an embed needs no surrounding whitespace, so
+    // `before![alt](url)after` would otherwise flatten to one run-on word. The
+    // callers collapse and trim, so an embed-only reply still reduces to empty
+    // and still reaches its media fallback.
+    case "image":
+    case "imageReference":
+      return " ";
+    case "break":
+      return "\n";
+    case "thematicBreak":
+      return "";
+    case "table":
+    case "list":
+      return node.children.map(nodeText).join("\n");
+    case "tableRow":
+      return node.children.map(nodeText).join(" ");
+    default:
+      return "children" in node
+        ? node.children
+            .map(nodeText)
+            .join(BLOCK_CONTAINER_TYPES.has(node.type) ? "\n\n" : "")
+        : "";
+  }
+}
+
+/**
+ * Flatten markdown to the plain text a notification surface renders, where
+ * markers would otherwise arrive as literal punctuation.
+ *
+ * Parses with the same remark/GFM processor the web client and the channel
+ * renderers use, rather than matching markers by hand. That is what keeps a
+ * balanced-paren URL, a tilde fence nested in a backtick one, a pipeless GFM
+ * table, and image syntax quoted inside a code span from each needing their own
+ * special case.
+ *
+ * Media embeds are dropped whole, alt text included. The alt describes the
+ * attachment rather than adding prose, so keeping it previews a video as its
+ * own caption. Copy that is nothing but embeds therefore flattens to empty,
+ * which is a caller's signal to describe the media instead.
+ *
+ * Line structure survives, so callers needing multi-line copy keep it; collapse
+ * whitespace separately for a single line.
+ */
+export function stripMarkdownForPreview(value: string): string {
+  return parseMarkdown(value).children.map(nodeText).join("\n\n");
+}
+
+/**
+ * Destinations the assistant resolves into attachment rows. Mirrors the link
+ * forms `daemon/assistant-attachments.ts` extracts.
+ */
+const TRACKED_MEDIA_URL_RE = /^vellum:\/\/(?:workspace|host)\//i;
+
+/** A media embed the flattener dropped, kept so a caller can name it. */
+export interface MediaEmbed {
+  /**
+   * Image description, already plain text: the parser resolves a formatted
+   * description rather than handing back its markers.
+   */
+  alt: string;
+  /**
+   * Whether the destination resolves through the attachment store. A
+   * `vellum://` embed becomes an attachment row, so a caller holding
+   * attachment metadata has already counted it; a remote one leaves no row
+   * there and its alt is the only label it has.
+   */
+  tracked: boolean;
+}
+
+/** Collect every image node, depth first. */
+function collectMediaEmbeds(
+  node: Root | RootContent,
+  into: MediaEmbed[],
+): void {
+  if (node.type === "image") {
+    into.push({
+      alt: node.alt ?? "",
+      tracked: TRACKED_MEDIA_URL_RE.test(node.url),
+    });
+    return;
+  }
+  // A reference embed names a definition rather than a destination, so it
+  // cannot be matched against the attachment store.
+  if (node.type === "imageReference") {
+    into.push({ alt: node.alt ?? "", tracked: false });
+    return;
+  }
+  if ("children" in node) {
+    for (const child of node.children) {
+      collectMediaEmbeds(child, into);
+    }
+  }
+}
+
+/**
+ * The media embeds in `value`, in order, empty alts included.
+ *
+ * Lets a caller describe copy whose entire content was embeds. Remote
+ * `https://` embeds are as valid as `vellum://` ones and register nothing in
+ * the attachment store, so without this a reply of one remote image would go
+ * out with no copy at all rather than merely an unhelpful one.
+ */
+export function mediaEmbeds(value: string): MediaEmbed[] {
+  const embeds: MediaEmbed[] = [];
+  collectMediaEmbeds(parseMarkdown(value), embeds);
+  return embeds;
+}
+
+/**
+ * Copy naming media, from whatever labels a caller could recover: attachment
+ * filenames, or the alt texts {@link mediaEmbedAltTexts} pulled back out of
+ * copy that flattened away.
+ *
+ * Labels are model- and tool-authored, so a single one is sanitized before it
+ * can reach the lock screen; one that sanitizes away leaves generic copy rather
+ * than a dangling "Sent ".
+ *
+ * Returns an empty string for no labels, leaving the caller to decide whether
+ * that means suppress the notification or fall back further.
+ */
+export function describeMedia(labels: string[]): string {
+  if (labels.length === 0) {
+    return "";
+  }
+  if (labels.length > 1) {
+    return `Sent ${labels.length} attachments`;
+  }
+  const label = sanitizeMessagePreview(labels[0].replace(/\s+/g, " ").trim());
+  return label ? `Sent ${label}` : "Sent an attachment";
+}
+
 // ── Sanitization ────────────────────────────────────────────────────────────
 
-/** Strip control characters and newlines, then truncate to `maxLength`. */
+/**
+ * Strip escape sequences, flatten control characters and newlines to spaces,
+ * then truncate to `maxLength`.
+ */
 function sanitize(value: string, maxLength: number): string {
-  return truncate(
-    value.replace(/[\x00-\x1f\x7f-\x9f\r\n]+/g, " ").trim(),
-    maxLength,
-  );
+  return truncate(stripAnsiAndControlChars(value, " ").trim(), maxLength);
 }
 
 /**

package/src/notifications/signal.ts

@@ -65,6 +65,18 @@ export const NOTIFICATION_SOURCE_EVENT_NAMES = [
     id: "schedule.notify",
     description: "Scheduled notification triggered (one-shot or recurring)",
   },
+  {
+    id: "schedule.definition_error",
+    description: "Plugin schedule declaration failed to parse or validate",
+  },
+  {
+    id: "schedule.declared",
+    description: "Plugin-declared schedule armed for the first time",
+  },
+  {
+    id: "schedule.definition_changed",
+    description: "Plugin upgrade changed an armed schedule's definition",
+  },
   {
     id: "guardian.question",
     description: "Guardian approval question requiring response",

package/src/oauth/AGENTS.md

@@ -35,9 +35,11 @@ Managed-sign-in users should get the integration pre-enabled by setting `service
 
 ### 4. Set the logo URL — `seed-providers.ts`
 
-The `logoUrl` field in `seed-providers.ts` is the source of truth for a provider's logo. Most providers use a [Simple Icons](https://simpleicons.org) (CC0-licensed) CDN URL like `https://cdn.simpleicons.org/acme`. The web client resolves logos from this field (see `clients/web/src/components/integrations/integration-icon.tsx`) and falls back to an initials avatar.
+The `logoUrl` field in `seed-providers.ts` is the source of truth for a provider's logo. Most providers use a [Simple Icons](https://simpleicons.org) (CC0-licensed) CDN URL like `https://cdn.simpleicons.org/acme`.
 
-For brands Simple Icons doesn't host (e.g. Salesforce, which Simple Icons removed for trademark reasons), use the `glincker/thesvg` source via jsDelivr — `https://cdn.jsdelivr.net/gh/glincker/thesvg@main/public/icons/<key>/default.svg`. The recognised `logoUrl` prefixes are enforced by `oauth-provider-seed-logos.test.ts`; if you need a third source, extend that allowlist.
+**Verify the URL actually resolves before you commit it.** `oauth-provider-seed-logos.test.ts` only checks the prefix, so a slug that Simple Icons has never hosted (or has since dropped) passes CI and then renders as an initials avatar in the client. Simple Icons removes brands on trademark request: Salesforce is gone, every Microsoft product went in v13, and Slack is currently absent pending permission from the trademark owner. For those, use the `glincker/thesvg` source via jsDelivr: `https://cdn.jsdelivr.net/gh/glincker/thesvg@main/public/icons/<key>/default.svg`. The recognised `logoUrl` prefixes are enforced by `oauth-provider-seed-logos.test.ts`; if you need a third source, extend that allowlist.
+
+`logoUrl` is a fallback, not the last word. The web client prefers a logo bundled in `clients/web/public/images/integrations/` when one exists for the provider key, uses `logoUrl` when it doesn't, and only then falls back to an initials avatar (see `BUNDLED_LOGO_URLS` in `clients/web/src/components/integrations/integration-icon.tsx`). Bundling an asset for a new first-class provider is optional but preferred: it survives a CDN removal, works offline, and keeps the integrations list from telling a third party which providers a user is looking at.
 
 ### 5. Secret patterns (if applicable) — `packages/service-contracts/src/secret-detection.ts`
 

package/src/oauth/byo-connection.ts

@@ -47,6 +47,11 @@ export class BYOOAuthConnection implements OAuthConnection {
       async (token) => {
         const effectiveBaseUrl = req.baseUrl ?? this.baseUrl;
         const isTelegram = this.provider === "telegram";
+        // Discord bot tokens authenticate with the `Bot ` scheme, not
+        // `Bearer`. Sending Bearer here reaches Discord as an unusable
+        // credential and comes back 401, which reads as a revoked token.
+        const authScheme =
+          this.provider === "discord_channel" ? "Bot" : "Bearer";
         const requestPath = isTelegram
           ? buildTelegramBotApiPath(req.path, token)
           : req.path;
@@ -87,7 +92,7 @@ export class BYOOAuthConnection implements OAuthConnection {
           }
         }
         if (!isTelegram) {
-          headers.set("Authorization", `Bearer ${token}`);
+          headers.set("Authorization", `${authScheme} ${token}`);
         }
 
         const resp = await fetch(fullUrl, {

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

@@ -19,6 +19,7 @@ import {
   getSecureKeyResultAsync,
   type SecureKeyResult,
 } from "../security/secure-keys.js";
+import { manualTokenProvider } from "./manual-token-providers.js";
 
 // ── Types ─────────────────────────────────────────────────────────────
 
@@ -44,16 +45,8 @@ export interface ConnectionAccessTokenResult {
  * rather than assuming the OAuth access-token path.
  */
 function manualTokenAccessCredentialKey(provider: string): string | null {
-  switch (provider) {
-    case "slack_channel":
-      return credentialKey("slack_channel", "bot_token");
-    case "telegram":
-      return credentialKey("telegram", "bot_token");
-    case "sanity":
-      return credentialKey("sanity", "api_token");
-    default:
-      return null;
-  }
+  const spec = manualTokenProvider(provider);
+  return spec ? credentialKey(provider, spec.accessField) : null;
 }
 
 /**