@vellumai/assistant 0.12.1 → 0.12.2-dev.202609162214.308bda0

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

@@ -23,7 +23,10 @@ import {
   getMessageById,
   updateMessageContent,
 } from "../persistence/conversation-crud.js";
-import { isBackgroundConversationType } from "../persistence/conversation-types.js";
+import {
+  ASSISTANT_INITIATED_SOURCE,
+  isBackgroundConversationType,
+} from "../persistence/conversation-types.js";
 import { publishConversationMessagesChanged } from "../runtime/sync/resource-sync-events.js";
 import { getLogger } from "../util/logger.js";
 import { normalizeTitle, stripMarkdown } from "../util/short-title.js";
@@ -272,6 +275,11 @@ async function resolveOwnedConversationMessageId(
   sourceConversationId: string | undefined,
   summary: string,
 ): Promise<string | undefined> {
+  // The completed reply is already the source conversation's canonical row.
+  // This signal's body is a compact push preview, not conversation content.
+  if (signal.sourceEventName === "chat.assistant_reply") {
+    return undefined;
+  }
   if (vellumDelivery?.conversationId) {
     return vellumDelivery.conversationId === sourceConversationId
       ? vellumDelivery.messageId
@@ -495,6 +503,18 @@ function deriveDetailPanelKind(
  * `isAsyncBackground` hint. `chat.assistant_reply` also mirrors: it is the
  * durable in-app record for the push sent after a user leaves a chat, while
  * retaining the normal interactive conversation as its navigation target.
+ *
+ * A delivery that materialized an assistant-initiated thread never mirrors.
+ * Under the `assistant-initiated-threads` flag, `conversation-pairing.ts`
+ * promotes a background `assistant.share` into a standard conversation
+ * stamped {@link ASSISTANT_INITIATED_SOURCE}, and that thread's row in the
+ * sidebar's assistant section is the share's one surface. Mirroring it here
+ * as well put the same share in the bell a second time, labeled by its
+ * source channel ("Heartbeat"). The check reads the paired conversation's
+ * `source` rather than re-deriving the promotion rule, so it holds however
+ * that rule narrows or widens. Guardian requests are checked first on
+ * purpose: the bell is their canonical home whatever conversation they pair
+ * with.
  */
 function resolveHomeFeedMirror(
   signal: NotificationSignal,
@@ -525,6 +545,15 @@ function resolveHomeFeedMirror(
     : fallbackConversationId;
   const sourceScheduleJobId = sourceRow?.scheduleJobId ?? undefined;
 
+  // Guardian requests always project into the feed: the "Needs
+  // attention" item is the request's canonical home, and the request
+  // blocks on the guardian whatever kind of conversation raised it.
+  if (isGuardianRequestSignalEvent(signal.sourceEventName)) {
+    return { mirror: true, sourceConversationId, sourceScheduleJobId };
+  }
+  if (isAssistantInitiatedThreadDelivery(fallbackConversationId)) {
+    return { mirror: false };
+  }
   if (
     signal.sourceChannel === "assistant_tool" ||
     signal.sourceEventName === "chat.assistant_reply"
@@ -534,18 +563,37 @@ function resolveHomeFeedMirror(
   if (signal.attentionHints.isAsyncBackground) {
     return { mirror: true, sourceConversationId, sourceScheduleJobId };
   }
-  // Guardian requests always project into the feed: the "Needs
-  // attention" item is the request's canonical home, and the request
-  // blocks on the guardian whatever kind of conversation raised it.
-  if (isGuardianRequestSignalEvent(signal.sourceEventName)) {
-    return { mirror: true, sourceConversationId, sourceScheduleJobId };
-  }
   if (isBackgroundConversationType(sourceRow?.conversationType)) {
     return { mirror: true, sourceConversationId, sourceScheduleJobId };
   }
   return { mirror: false };
 }
 
+/**
+ * Whether the vellum delivery this signal produced landed in a thread the
+ * sidebar's assistant section already shows.
+ *
+ * Best-effort like the source lookup above: a missing id, a missing row, or
+ * a lookup failure all read as "not an assistant thread", so a storage
+ * hiccup degrades to the pre-existing behavior (a bell row) rather than
+ * dropping the notification everywhere.
+ */
+function isAssistantInitiatedThreadDelivery(
+  deliveryConversationId: string | undefined,
+): boolean {
+  if (!deliveryConversationId) {
+    return false;
+  }
+  try {
+    return (
+      getConversation(deliveryConversationId)?.source ===
+      ASSISTANT_INITIATED_SOURCE
+    );
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Routing-intent enforcement can prune `selectedChannels` without also
  * pruning `renderedCopy`, so iterating `renderedCopy` directly risks

package/src/notifications/schedule-result-producer.ts

@@ -32,6 +32,7 @@ import { getAttentionStateByConversationIds } from "../persistence/conversation-
 import {
   getAssistantMessageIdsInTurn,
   getMessageById,
+  getMessagesAfter,
   type MessageRow,
 } from "../persistence/conversation-crud.js";
 import { stringifyMessageContent } from "../persistence/message-content.js";
@@ -39,7 +40,6 @@ import {
   isPrivateAssistantText,
   projectPersistedAssistantContent,
 } from "../persistence/user-facing-content.js";
-import type { ContentBlock } from "../providers/types.js";
 import { emitNotificationSignal } from "./emit-signal.js";
 import { hasNotifiedSourceContextSince } from "./events-store.js";
 import {
@@ -79,28 +79,70 @@ export interface ScheduleResultNotificationParams {
 }
 
 /**
- * Whether a tool call in the run's turn delivered the result somewhere the
- * user will see it, outside the notification pipeline.
+ * Whether the run delivered its result through the messaging tool, and the
+ * call succeeded.
  *
- * The schedule skill prescribes two such routes for rich content — the
- * messaging tool for email, and the Slack Web API's `chat.postMessage` through
- * bash — and neither writes a `notification_events` row, so the pipeline probe
- * cannot see them. Without this check a well-authored Slack digest would post
+ * The messaging tool is the route the schedule skill prescribes for rich
+ * content, and it writes no `notification_events` row, so the pipeline probe
+ * cannot see it. Without this check a well-authored Slack digest would post
  * its summary and then get a second notification whose body is "Posted the
- * digest to #general." This is a recognized-routes list, not a general "did
- * the run do anything?" heuristic: a route that is not here gets the fallback,
- * which is the safe failure.
+ * digest to #general."
+ *
+ * Both conditions are load-bearing. The route has to be recognized, because
+ * this is a known-routes list rather than a general "did the run do anything?"
+ * heuristic. And the call has to have succeeded: a `tool_use` block records
+ * only that the model called the tool, so a send the channel refused leaves
+ * the same block as one that landed, and suppressing on it costs the user both
+ * the digest and the run's explanation of the failure. The executor's verdict
+ * is on the `tool_result` the call produced, so success is read from there,
+ * and a call with no result counts as undelivered. Either condition unmet gets
+ * the fallback, which is the safe failure.
+ *
+ * The result read starts at the run's first row, so it covers the results
+ * interleaved through the turn. Rows from a later turn in a reused
+ * conversation can come back too and are harmless, because only this run's
+ * own call ids are matched.
+ *
+ * A Slack Web API post through bash is deliberately not a route. It is off
+ * the guided path and unrecorded, and recognizing it would mean reading a
+ * shell command for a method name. A run that posts that way gets the
+ * fallback too: at worst a duplicate, never a silence.
  */
-function isDirectDelivery(block: ContentBlock): boolean {
-  if (block.type !== "tool_use") {
-    return false;
+function deliveredThroughMessagingTool(
+  conversationId: string,
+  runRows: readonly MessageRow[],
+): boolean {
+  const callIds = new Set<string>();
+  for (const row of runRows) {
+    for (const block of row.content) {
+      if (block.type === "tool_use" && block.name === "messaging_send") {
+        callIds.add(block.id);
+      }
+    }
   }
-  if (block.name === "messaging_send") {
-    return true;
+  if (callIds.size === 0) {
+    return false;
   }
-  if (block.name === "bash") {
-    const command = (block.input as { command?: unknown } | undefined)?.command;
-    return typeof command === "string" && command.includes("chat.postMessage");
+  const [firstRunRow] = runRows;
+  for (const row of getMessagesAfter(conversationId, {
+    id: firstRunRow.id,
+    createdAt: firstRunRow.createdAt,
+  })) {
+    if (row.role !== "user") {
+      continue;
+    }
+    for (const block of row.content) {
+      // guard:allow-tool-result-only: the local executor's verdict on a
+      // delivery it ran. A server-side `web_search_tool_result` carries no
+      // `is_error` and never delivers anything.
+      if (
+        block.type === "tool_result" &&
+        block.is_error !== true &&
+        callIds.has(block.tool_use_id)
+      ) {
+        return true;
+      }
+    }
   }
   return false;
 }
@@ -237,11 +279,11 @@ export async function emitScheduleResultNotification(
       return;
     }
 
-    // The run delivered around the pipeline — an email through the messaging
-    // tool, a Slack post through the Web API. The user has the result; a
-    // notification reading "posted it" on top would be the duplicate.
+    // The run delivered around the pipeline through the messaging tool, and
+    // the call succeeded. The user has the result; a notification reading
+    // "posted it" on top would be the duplicate.
     const runRows = collectRunRows(latestRow, conversationId, runStartedAt);
-    if (runRows.some((row) => row.content.some(isDirectDelivery))) {
+    if (deliveredThroughMessagingTool(conversationId, runRows)) {
       return;
     }
 

package/src/oauth/AGENTS.md

@@ -8,6 +8,10 @@ When introducing a new built-in OAuth integration (one that appears in `seed-pro
 
 Add an entry to `PROVIDER_SEED_DATA`. Required fields: `provider`, `authorizeUrl`, `tokenExchangeUrl`, `defaultScopes`, `displayLabel`, `description`, `dashboardUrl`, `clientIdPlaceholder`, `logoUrl`, and `injectionTemplates`. Optional: `availableScopes` — either a structured array of `{scope, description?}` objects or a URL string pointing to the provider's scope documentation. See existing entries for the full shape. The `provider` key must be snake_case and is used as the canonical identifier everywhere else.
 
+`injectionTemplates` is also a security boundary, not only an injection rule. `assistant oauth request` and `assistant channels request` accept an absolute URL only when its host matches one of the entry's `hostPattern` values (`assertOAuthRequestUrlAllowed` in `../runtime/routes/oauth-commands-routes.ts`), so that list is the full set of hosts the credential may be sent to. A pattern matches exactly unless it starts with `*.`; reserve the wildcard for per-tenant hosts that cannot be enumerated (`*.salesforce.com`), and name a fixed host the provider documents (`files.slack.com`) by name. The guard sees only the URL the caller passes: the connection follows a redirect itself, and a cross-origin hop carries no `Authorization`, so a redirect target never receives the credential and never needs listing.
+
+`responseOkField` declares the boolean a provider's API puts in every response body to report success (Slack: `ok`), and it is read in one place, `providerReportsFailure` in `identity-verifier.ts`. It is not `identityOkField`, which governs only the identity call and stays the documented `--identity-ok-field` contract. Both request doors and `oauth ping` treat an explicit `false` under a 2xx as a failed call, since such a provider hides refusals behind a successful status; a body without the field leaves the status as the verdict. Declare it on every row that calls such an API, the bot row included.
+
 If the provider will support managed mode, set `managedServiceConfigKey` to a slug matching the key you will add to `ServicesSchema` (e.g. `"acme-oauth"`).
 
 ### 2. _(managed only)_ Add a service schema — `../config/schemas/services.ts`

package/src/oauth/__tests__/identity-verifier.test.ts

@@ -1,6 +1,9 @@
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
-import { verifyIdentity } from "../identity-verifier.js";
+import {
+  providerReportsFailure,
+  verifyIdentity,
+} from "../identity-verifier.js";
 import type { OAuthProviderRow } from "../oauth-store.js";
 
 // ---------------------------------------------------------------------------
@@ -66,6 +69,7 @@ function makeProviderRow(
     identityResponsePaths: null,
     identityFormat: null,
     identityOkField: null,
+    responseOkField: null,
     featureFlag: null,
     createdAt: now,
     updatedAt: now,
@@ -469,3 +473,34 @@ describe("verifyIdentity", () => {
     });
   });
 });
+
+describe("providerReportsFailure", () => {
+  test("reads an explicit false in the declared field as failure", () => {
+    expect(
+      providerReportsFailure(
+        { responseOkField: "ok" },
+        { ok: false, error: "invalid_auth" },
+      ),
+    ).toBe(true);
+    expect(
+      providerReportsFailure({ responseOkField: "ok" }, { ok: true }),
+    ).toBe(false);
+  });
+
+  test("a body without the field says nothing", () => {
+    // A download or an endpoint outside the envelope; the status decides.
+    expect(providerReportsFailure({ responseOkField: "ok" }, null)).toBe(false);
+    expect(
+      providerReportsFailure({ responseOkField: "ok" }, Buffer.from("png")),
+    ).toBe(false);
+    expect(
+      providerReportsFailure({ responseOkField: "ok" }, { data: {} }),
+    ).toBe(false);
+  });
+
+  test("a provider that declares no field never reports failure", () => {
+    expect(
+      providerReportsFailure({ responseOkField: null }, { ok: false }),
+    ).toBe(false);
+  });
+});

package/src/oauth/__tests__/seed-providers-managed.test.ts

@@ -60,6 +60,26 @@ describe("PROVIDER_SEED_DATA managed mode wiring", () => {
       );
     }
 
+    // `folders:read` is documented too, but the app's scope picker only
+    // offers `folder_metadata:read` under Folders, so Figma answers
+    // "Invalid scopes for app" whenever it is requested.
+    expect(figma.defaultScopes).not.toContain("folders:read");
+    if (Array.isArray(availableScopes)) {
+      expect(availableScopes.map(({ scope }) => scope)).toContain(
+        "folders:read",
+      );
+    }
+
+    // `file_code_connect:write` is only offered to apps owned by an
+    // Organization-plan team. Managed apps in other environments are not,
+    // so requesting it fails the whole authorization there.
+    expect(figma.defaultScopes).not.toContain("file_code_connect:write");
+    if (Array.isArray(availableScopes)) {
+      expect(availableScopes.map(({ scope }) => scope)).toContain(
+        "file_code_connect:write",
+      );
+    }
+
     // GET /v1/me backs both the ping and the identity label.
     expect(figma.defaultScopes).toContain("current_user:read");
   });
@@ -127,6 +147,135 @@ describe("PROVIDER_SEED_DATA managed mode wiring", () => {
     expect(figma.featureFlag).toBe("figma-oauth");
   });
 
+  test("shopify keeps its per-tenant URL templates", () => {
+    // Shopify has no global OAuth host: every endpoint lives on the
+    // merchant's own domain. Hardcoding any host here would send every
+    // merchant's authorization to the wrong store, so the {tenant_host}
+    // placeholder the platform substitutes must survive.
+    const shopify = PROVIDER_SEED_DATA.shopify;
+    expect(shopify).toBeDefined();
+    for (const url of [
+      shopify.authorizeUrl,
+      shopify.tokenExchangeUrl,
+      shopify.refreshUrl,
+      shopify.baseUrl,
+      shopify.identityUrl,
+    ]) {
+      expect(url).toContain("{tenant_host}");
+    }
+  });
+
+  test("shopify requests comma-separated scopes", () => {
+    // Shopify parses `scope` as a comma-separated list; the OAuth2 default
+    // space separator is read as one malformed scope and the whole
+    // authorization request is rejected.
+    expect(PROVIDER_SEED_DATA.shopify.scopeSeparator).toBe(",");
+  });
+
+  test("shopify does not request approval-gated scopes", () => {
+    // Shopify rejects the entire authorization request when the app cannot
+    // grant a requested scope -- the same failure that broke monday and
+    // Figma. These scopes all require Shopify's prior approval.
+    const gated = [
+      "read_all_orders",
+      "read_customer_payment_methods",
+      "read_own_subscription_contracts",
+      "write_own_subscription_contracts",
+      "read_shopify_payments_dispute_evidences",
+      "write_shopify_payments_dispute_evidences",
+    ];
+    for (const scope of gated) {
+      expect(PROVIDER_SEED_DATA.shopify.defaultScopes).not.toContain(scope);
+    }
+  });
+
+  test("shopify injects the Admin API's own auth header", () => {
+    // The Admin API reads X-Shopify-Access-Token and ignores an
+    // Authorization: Bearer header entirely, so a Bearer template here would
+    // make every proxied request unauthenticated.
+    const templates = PROVIDER_SEED_DATA.shopify.injectionTemplates;
+    expect(templates).toBeDefined();
+    const [template] = templates ?? [];
+    expect(template?.headerName).toBe("X-Shopify-Access-Token");
+    expect(template?.valuePrefix).toBe("");
+    expect(template?.hostPattern).toBe("*.myshopify.com");
+  });
+
+  test("quickbooks is wired up for managed mode behind its flag", () => {
+    const quickbooks = PROVIDER_SEED_DATA.quickbooks;
+    expect(quickbooks).toBeDefined();
+    expect(quickbooks.managedServiceConfigKey).toBe("quickbooks-oauth");
+    expect("quickbooks-oauth" in ServicesSchema.shape).toBe(true);
+    // Hidden until the platform side and client ids are live, like Figma
+    // and Shopify.
+    expect(quickbooks.featureFlag).toBe("quickbooks-oauth");
+  });
+
+  test("quickbooks uses Intuit's OAuth endpoints with HTTP Basic", () => {
+    const quickbooks = PROVIDER_SEED_DATA.quickbooks;
+    expect(quickbooks.authorizeUrl).toBe(
+      "https://appcenter.intuit.com/connect/oauth2",
+    );
+    expect(quickbooks.tokenExchangeUrl).toBe(
+      "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer",
+    );
+    expect(quickbooks.refreshUrl).toBe(quickbooks.tokenExchangeUrl);
+    expect(quickbooks.tokenEndpointAuthMethod).toBe("client_secret_basic");
+  });
+
+  test("quickbooks keeps its per-company URL templates", () => {
+    // Every Accounting API path is scoped to the realm the user picked on
+    // Intuit's consent screen. The platform fills {realm_id} from the
+    // connection; a hardcoded realm here would send every company's calls
+    // to the wrong books.
+    const quickbooks = PROVIDER_SEED_DATA.quickbooks;
+    for (const url of [quickbooks.baseUrl, quickbooks.identityUrl]) {
+      expect(url).toContain("/v3/company/{realm_id}");
+    }
+  });
+
+  test("quickbooks seeds no ping or revoke URL", () => {
+    // The ping route sends the URL's origin as a base override and cannot
+    // fill {realm_id}; the daemon's revoke helper posts an unauthenticated
+    // form body that Intuit's JSON + Basic-auth endpoint rejects. Either
+    // would fail silently on every your-own connection.
+    const quickbooks = PROVIDER_SEED_DATA.quickbooks;
+    expect(quickbooks.pingUrl).toBeUndefined();
+    expect(quickbooks.revokeUrl).toBeUndefined();
+  });
+
+  test("quickbooks requests only the accounting scope by default", () => {
+    // Payments needs a Payments-enabled app and the OpenID scopes only add
+    // the user's profile; requesting either widens the consent screen for
+    // nothing the Accounting API needs.
+    const quickbooks = PROVIDER_SEED_DATA.quickbooks;
+    expect(quickbooks.defaultScopes).toEqual([
+      "com.intuit.quickbooks.accounting",
+    ]);
+    const available = quickbooks.availableScopes;
+    expect(Array.isArray(available)).toBe(true);
+    if (Array.isArray(available)) {
+      expect(available.map(({ scope }) => scope)).toContain(
+        "com.intuit.quickbooks.payment",
+      );
+    }
+  });
+
+  test("quickbooks allows the credential on both Intuit API hosts", () => {
+    // Development keys only work against sandbox companies, which live on
+    // the sandbox host. Both hosts belong to Intuit and take the same
+    // bearer token.
+    const templates = PROVIDER_SEED_DATA.quickbooks.injectionTemplates ?? [];
+    expect(templates.map((t) => t.hostPattern).sort()).toEqual([
+      "quickbooks.api.intuit.com",
+      "sandbox-quickbooks.api.intuit.com",
+    ]);
+    for (const template of templates) {
+      expect(template.headerName).toBe("Authorization");
+      expect(template.valuePrefix).toBe("Bearer ");
+    }
+  });
+
   test("every managedServiceConfigKey resolves to a ServicesSchema key", () => {
     // Cross-repo invariant: a provider with managedServiceConfigKey but no
     // matching ServicesSchema entry silently falls back to BYO mode in

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

@@ -308,6 +308,66 @@ describe("BYOOAuthConnection", () => {
       expect((init as RequestInit).method).toBe("GET");
     });
 
+    test("follows a cross-origin redirect without the credential and returns the target's bytes", async () => {
+      // Real fetch against two loopback origins: the credential goes to the
+      // host the caller named, the redirect target sees no Authorization,
+      // and the target's bytes come back as the response body. This is the
+      // path a Slack file download takes when files.slack.com answers with a
+      // 302 to its CDN.
+      globalThis.fetch = originalFetch;
+      await setupCredential("google");
+      const bytes = Buffer.from([
+        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+      ]);
+      const seen: { origin?: string | null; target?: string | null } = {};
+
+      const target = Bun.serve({
+        port: 0,
+        hostname: "127.0.0.1",
+        fetch: (req) => {
+          seen.target = req.headers.get("authorization");
+          return new Response(bytes, {
+            status: 200,
+            headers: { "content-type": "image/png" },
+          });
+        },
+      });
+      const origin = Bun.serve({
+        port: 0,
+        hostname: "127.0.0.1",
+        fetch: (req) => {
+          seen.origin = req.headers.get("authorization");
+          return new Response(null, {
+            status: 302,
+            headers: { Location: `http://127.0.0.1:${target.port}/signed` },
+          });
+        },
+      });
+
+      try {
+        const conn = new BYOOAuthConnection({
+          id: "conn-google",
+          provider: "google",
+          baseUrl: `http://127.0.0.1:${origin.port}`,
+          accountInfo: null,
+        });
+
+        const result = await conn.request({
+          method: "GET",
+          path: "/files-pri/T0123-F0456/download/shot.png",
+        });
+
+        expect(seen.origin).toBe("Bearer test-access-token");
+        expect(seen.target).toBeNull();
+        expect(result.status).toBe(200);
+        expect(Buffer.isBuffer(result.body)).toBe(true);
+        expect(Buffer.from(result.body as Buffer).equals(bytes)).toBe(true);
+      } finally {
+        origin.stop(true);
+        target.stop(true);
+      }
+    });
+
     test("appends query parameters", async () => {
       await setupCredential("google");
       const conn = createConnection();
@@ -708,6 +768,51 @@ describe("BYOOAuthConnection", () => {
       expect(headers.get("Authorization")).toBe("Bearer test-access-token");
     });
 
+    test("sends the token in the provider's own header when one is configured", async () => {
+      // Shopify's Admin API reads X-Shopify-Access-Token and ignores
+      // Authorization, so a Bearer header reaches the shop unauthenticated.
+      await setupCredential("google");
+      const conn = new BYOOAuthConnection({
+        id: "conn-google",
+        provider: "google",
+        baseUrl: "https://example-store.myshopify.com",
+        accountInfo: null,
+        tokenHeader: { name: "X-Shopify-Access-Token", valuePrefix: "" },
+      });
+
+      await conn.request({
+        method: "GET",
+        path: "/admin/api/2026-07/shop.json",
+        // A caller-supplied Authorization must not ride along.
+        headers: { Authorization: "Bearer caller-supplied" },
+      });
+
+      const [url, init] = mockFetch.mock.calls[0];
+      expect(url).toBe(
+        "https://example-store.myshopify.com/admin/api/2026-07/shop.json",
+      );
+      const headers = (init as RequestInit).headers as Headers;
+      expect(headers.get("X-Shopify-Access-Token")).toBe("test-access-token");
+      expect(headers.has("Authorization")).toBe(false);
+    });
+
+    test("keeps the value prefix from the token header template", async () => {
+      await setupCredential("google");
+      const conn = new BYOOAuthConnection({
+        id: "conn-google",
+        provider: "google",
+        baseUrl: "https://discord.com/api",
+        accountInfo: null,
+        tokenHeader: { name: "Authorization", valuePrefix: "Bot " },
+      });
+
+      await conn.request({ method: "GET", path: "/users/@me" });
+
+      const [, init] = mockFetch.mock.calls[0];
+      const headers = (init as RequestInit).headers as Headers;
+      expect(headers.get("Authorization")).toBe("Bot test-access-token");
+    });
+
     test("uses Telegram Bot API token URL format without Bearer auth", async () => {
       await setupTelegramCredential();
       const conn = createConnection("telegram");

package/src/oauth/byo-connection.ts

@@ -21,11 +21,29 @@ const log = getLogger("byo-oauth-connection");
 /** Default per-request timeout to prevent hung requests from blocking indefinitely. */
 const REQUEST_TIMEOUT_MS = 30_000;
 
+/**
+ * How the access token is attached to an outbound request. Almost every
+ * provider reads `Authorization: Bearer <token>`; a few use their own header
+ * (Shopify's Admin API reads `X-Shopify-Access-Token` and ignores
+ * Authorization entirely). Derived from the provider's header-type injection
+ * template so the seed is the single source of truth.
+ */
+export interface BYOTokenHeader {
+  name: string;
+  /** Text placed before the token, e.g. `"Bearer "`, `"Bot "`, or `""`. */
+  valuePrefix: string;
+}
+
 export interface BYOOAuthConnectionOptions {
   id: string;
   provider: string;
   baseUrl: string;
   accountInfo: string | null;
+  /**
+   * Token header override. When omitted the connection falls back to
+   * `Authorization: Bearer` (or `Bot` for discord_channel).
+   */
+  tokenHeader?: BYOTokenHeader | null;
 }
 
 export class BYOOAuthConnection implements OAuthConnection {
@@ -34,12 +52,14 @@ export class BYOOAuthConnection implements OAuthConnection {
   readonly accountInfo: string | null;
 
   private readonly baseUrl: string;
+  private readonly tokenHeader: BYOTokenHeader | null;
 
   constructor(opts: BYOOAuthConnectionOptions) {
     this.id = opts.id;
     this.provider = opts.provider;
     this.baseUrl = opts.baseUrl;
     this.accountInfo = opts.accountInfo;
+    this.tokenHeader = opts.tokenHeader ?? null;
   }
 
   async request(req: OAuthConnectionRequest): Promise<OAuthConnectionResponse> {
@@ -51,8 +71,12 @@ export class BYOOAuthConnection implements OAuthConnection {
         // 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";
+        // Providers with their own token header (Shopify) override the
+        // whole thing via `tokenHeader`.
+        const tokenHeader: BYOTokenHeader = this.tokenHeader ?? {
+          name: "Authorization",
+          valuePrefix: this.provider === "discord_channel" ? "Bot " : "Bearer ",
+        };
         const requestPath = isTelegram
           ? buildTelegramBotApiPath(req.path, token)
           : req.path;
@@ -93,16 +117,22 @@ export class BYOOAuthConnection implements OAuthConnection {
           }
         }
         if (!isTelegram) {
-          headers.set("Authorization", `${authScheme} ${token}`);
+          // The credential always wins over a caller-supplied value, and a
+          // provider that reads its own header must not also receive a
+          // stray Authorization the caller happened to send.
+          if (tokenHeader.name.toLowerCase() !== "authorization") {
+            headers.delete("Authorization");
+          }
+          headers.set(tokenHeader.name, `${tokenHeader.valuePrefix}${token}`);
         }
 
         const resp = await fetch(fullUrl, {
           method: req.method,
           headers,
           body: hasBody
-            ? (binaryBody !== undefined
-                ? Buffer.from(binaryBody)
-                : (rawBody ?? JSON.stringify(req.body)))
+            ? binaryBody !== undefined
+              ? Buffer.from(binaryBody)
+              : (rawBody ?? JSON.stringify(req.body))
             : undefined,
           // Following a redirect would replay a POST as a GET against a URL
           // the caller never asked for, and hide the 3xx from them.