@vellumai/assistant 0.11.7 → 0.11.8-staging.1

package/src/notifications/guardian-feed-projection.ts

@@ -0,0 +1,492 @@
+/**
+ * Canonical "Needs attention" projection of guardian requests onto the
+ * home feed.
+ *
+ * One pending guardian request is exactly one feed item, keyed by
+ * `guardianFeedItemId(requestId)` so the feed writer's replace-in-place
+ * merge keeps it canonical: re-emits update the same row, and the
+ * terminal-status fan-out rewrites it into a receipt instead of leaving
+ * a stale actionable card. The item's `guardianRequest` field
+ * (`FeedItemGuardianRequestSchema`) is a read projection of the
+ * gateway-owned `guardian_requests` row, never an independent delivery
+ * record: clients derive every affordance from its `status`, and the
+ * daemon updates it wherever `withdrawGuardianRequestCards` settles the
+ * other surfaces.
+ */
+import { z } from "zod";
+
+import {
+  type FeedItem,
+  type FeedItemGuardianIntent,
+  type FeedItemGuardianRequest,
+  FeedItemGuardianStatusSchema,
+  isPendingGuardianFeedItem,
+} from "../api/responses/home.js";
+import {
+  getGuardianRequest,
+  type GuardianRequestStatus,
+  type GuardianRequestWire,
+  listGuardianRequests,
+} from "../channels/gateway-guardian-requests.js";
+import { getConfig } from "../config/loader.js";
+import {
+  appendFeedItem,
+  patchFeedItemContent,
+  readHomeFeed,
+} from "../home/feed-writer.js";
+import { buildSlackMessageDeepLinks } from "../messaging/providers/slack/deep-link.js";
+import {
+  DEFAULT_USER_REFERENCE,
+  resolveGuardianName,
+} from "../prompts/user-reference.js";
+import { getLogger } from "../util/logger.js";
+import {
+  buildToolApprovalSourceView,
+  type GuardianQuestionRequestKind,
+  LenientToolApprovalPayloadSchema,
+  resolveGuardianInstructionModeFromFields,
+  resolveGuardianQuestionInstructionMode,
+} from "./guardian-question-mode.js";
+import { readPayloadString } from "./notification-utils.js";
+import type { NotificationDeliveryResult } from "./types.js";
+
+const log = getLogger("guardian-feed-projection");
+
+// The wire enum in `api/responses/home.ts` cannot import the gateway
+// contract (the api directory is copied verbatim into client packages),
+// so it mirrors `GuardianRequestStatusSchema` by value. This assignment
+// fails to compile if the enums ever diverge in either direction.
+type FeedStatus = z.infer<typeof FeedItemGuardianStatusSchema>;
+type StatusEnumsAligned = [GuardianRequestStatus] extends [FeedStatus]
+  ? [FeedStatus] extends [GuardianRequestStatus]
+    ? true
+    : never
+  : never;
+const _statusEnumsAligned: StatusEnumsAligned = true;
+void _statusEnumsAligned;
+
+/**
+ * The signal events that carry a guardian request. `guardian.question`
+ * covers tool approvals, tool grants, and questions; access requests
+ * predate that registry and still ride their own event with an implied
+ * `access_request` kind.
+ */
+export function isGuardianRequestSignalEvent(sourceEventName: string): boolean {
+  return (
+    sourceEventName === "guardian.question" ||
+    sourceEventName === "ingress.access_request"
+  );
+}
+
+/** Feed-item id of the canonical projection for a guardian request. */
+export function guardianFeedItemId(requestId: string): string {
+  return `guardian:${requestId}`;
+}
+
+/** The `requestId` a guardian feed-item id was built from, or null. */
+export function requestIdFromGuardianFeedItemId(itemId: string): string | null {
+  return itemId.startsWith("guardian:")
+    ? itemId.slice("guardian:".length)
+    : null;
+}
+
+/**
+ * Guardian display name for receipt copy, or undefined when only the
+ * prompt-voice fallback ("my human") is available. A receipt with no
+ * decider label renders as the bare status word.
+ */
+function guardianReceiptName(): string | undefined {
+  const name = resolveGuardianName();
+  return name === DEFAULT_USER_REFERENCE ? undefined : name;
+}
+
+/**
+ * Build the pending `guardianRequest` projection for a `guardian.question`
+ * signal's feed item. Returns null when the payload does not carry the
+ * request id the projection is keyed by.
+ *
+ * `slackDelivery` is the signal's Slack delivery outcome, when one
+ * shipped: its destination chat + message ts locate the guardian-DM
+ * approval card, and the derived deep links are what the client's
+ * "Open in Slack" affordance opens.
+ */
+export function buildPendingGuardianProjection(
+  contextPayload: unknown,
+  slackDelivery?: NotificationDeliveryResult,
+  fallbackKind?: GuardianQuestionRequestKind,
+): FeedItemGuardianRequest | null {
+  // Access-request payloads predate the kind registry and carry no
+  // `requestKind`; the producer's event name supplies it instead.
+  const normalizedPayload =
+    contextPayload &&
+    typeof contextPayload === "object" &&
+    !Array.isArray(contextPayload) &&
+    !("requestKind" in contextPayload) &&
+    fallbackKind
+      ? { ...contextPayload, requestKind: fallbackKind }
+      : contextPayload;
+  const parsed = LenientToolApprovalPayloadSchema.safeParse(normalizedPayload);
+  if (!parsed.success) {
+    return null;
+  }
+  const payload = parsed.data;
+  const requestId = payload.requestId?.trim();
+  if (!requestId) {
+    return null;
+  }
+
+  const intent = intentFromInstructionMode(
+    resolveGuardianQuestionInstructionMode(payload).mode,
+  );
+
+  const sourceView = buildToolApprovalSourceView(payload);
+  const slackLinks = buildSlackCardLinks(slackDelivery);
+  // Access-request payloads name their requester differently.
+  const requesterLabel =
+    payload.requesterIdentifier?.trim() ||
+    readPayloadString(contextPayload, "actorDisplayName")?.trim() ||
+    readPayloadString(contextPayload, "senderIdentifier")?.trim();
+
+  return {
+    requestId,
+    kind: payload.requestKind,
+    intent,
+    status: "pending",
+    ...(requesterLabel ? { requesterLabel } : {}),
+    ...(payload.toolName?.trim() ? { toolName: payload.toolName.trim() } : {}),
+    ...(sourceView?.channel ? { sourceChannel: sourceView.channel } : {}),
+    ...(sourceView
+      ? { sourceContextLabel: describeApprovalSourceContext(sourceView) }
+      : {}),
+    ...(sourceView?.permalink ? { sourceUrl: sourceView.permalink } : {}),
+    ...(slackLinks?.webUrl ? { slackCardUrl: slackLinks.webUrl } : {}),
+    ...(slackLinks?.appUrl ? { slackCardAppUrl: slackLinks.appUrl } : {}),
+  };
+}
+
+/**
+ * A request in answer mode asks the guardian a question; every other
+ * mode asks for an approval. The instruction mode already encodes this
+ * (it decides whether cards render answer options or approve/reject),
+ * so the projection's `intent` is a straight reading of it.
+ */
+function intentFromInstructionMode(
+  mode: "approval" | "answer" | undefined,
+): FeedItemGuardianIntent {
+  return mode === "answer" ? "question" : "approval";
+}
+
+/**
+ * Display label for the originating chat, mirroring the wording the
+ * in-app approval card's source row uses (`sourceMetadataRow` in
+ * `approval-card-data.ts`): Slack chats are named, other channels fall
+ * back to the channel id.
+ */
+function describeApprovalSourceContext(view: {
+  channel: string;
+  chatId?: string | null;
+  isSlackDm: boolean;
+}): string {
+  if (view.channel === "slack" && view.chatId) {
+    return view.isSlackDm ? "Slack direct message" : `Slack #${view.chatId}`;
+  }
+  return view.channel;
+}
+
+/** Deep links to the Slack guardian-DM approval card, when one shipped. */
+function buildSlackCardLinks(
+  slackDelivery?: NotificationDeliveryResult,
+): { appUrl?: string; webUrl?: string } | undefined {
+  if (
+    !slackDelivery ||
+    slackDelivery.status !== "sent" ||
+    !slackDelivery.destination ||
+    !slackDelivery.messageId
+  ) {
+    return undefined;
+  }
+  const slackConfig = getConfig().slack;
+  return buildSlackMessageDeepLinks({
+    teamId: slackConfig?.teamId,
+    teamUrl: slackConfig?.teamUrl,
+    channelId: slackDelivery.destination,
+    messageTs: slackDelivery.messageId,
+  });
+}
+
+export interface GuardianFeedReceiptParams {
+  requestId: string;
+  status: GuardianRequestStatus;
+  /** Action that produced the terminal status, when it was a decision. */
+  decidedAction?: string;
+  /** Epoch ms the request reached its terminal status. */
+  decidedAtMs?: number;
+  /** Non-decision cause of the terminal status (e.g. "superseded"). */
+  terminalReason?: string;
+}
+
+/**
+ * Rewrite a request's canonical feed item into its terminal receipt.
+ *
+ * The item keeps its title and summary; `guardianRequest` flips to the
+ * terminal status (which is what removes the client's action buttons),
+ * and urgency drops to `medium` so the item leaves the protected
+ * "Needs attention" treatment and becomes an ordinary clearable
+ * notification. Returns false only when the write itself failed, so the
+ * withdrawal fan-out can hold its per-request receipt back and retry
+ * (same contract as the other surfaces it settles). A request with no
+ * projection item resolves true: the pending writer converges the
+ * write-vs-resolve race by re-checking canonical status after its
+ * append, so there is nothing here for a retry to fix.
+ */
+export async function writeGuardianFeedReceipt(
+  params: GuardianFeedReceiptParams,
+): Promise<boolean> {
+  const itemId = guardianFeedItemId(params.requestId);
+  try {
+    // `patchFeedItemContent` resolves null both for a missing item and
+    // for a failed file write, and only the second may gate a retry.
+    // The pre-check splits them: an id present here that nulls below is
+    // a lost write (or a concurrent removal, where a retry is harmless).
+    if (!readHomeFeed().items.some((item) => item.id === itemId)) {
+      // No projection item: either the request predates the projection
+      // or the pending write raced the resolution and has not landed
+      // yet. The pending writer converges the race by re-checking
+      // canonical status after its append.
+      log.debug(
+        { requestId: params.requestId, status: params.status },
+        "No guardian feed item to receipt",
+      );
+      return true;
+    }
+    const updated = await patchFeedItemContent(itemId, {
+      urgency: "medium",
+      guardianRequest: (existing) => ({
+        ...existing,
+        status: params.status,
+        ...(params.decidedAction
+          ? { decidedAction: params.decidedAction }
+          : {}),
+        // A decider label only when a person decided: a non-decision
+        // terminal (superseded, expired) must not read as the guardian's
+        // own rejection.
+        ...((params.status === "approved" || params.status === "denied") &&
+        !params.terminalReason
+          ? decidedByLabelPatch()
+          : {}),
+        decidedAt: new Date(params.decidedAtMs ?? Date.now()).toISOString(),
+        ...(params.terminalReason
+          ? { terminalReason: params.terminalReason }
+          : {}),
+      }),
+    });
+    if (!updated) {
+      log.warn(
+        { requestId: params.requestId, status: params.status },
+        "Guardian feed receipt did not persist",
+      );
+      return false;
+    }
+    return true;
+  } catch (err) {
+    log.warn(
+      { err, requestId: params.requestId, status: params.status },
+      "Failed to write guardian feed receipt",
+    );
+    return false;
+  }
+}
+
+/** `{ decidedByLabel }` when a real display name exists, `{}` otherwise. */
+function decidedByLabelPatch(): Pick<
+  Partial<FeedItemGuardianRequest>,
+  "decidedByLabel"
+> {
+  const name = guardianReceiptName();
+  return name === undefined ? {} : { decidedByLabel: name };
+}
+
+/**
+ * Rewrite a request's feed item into its receipt when the canonical row
+ * is already terminal. Converges the write-vs-resolve race from the
+ * writer's side: a request decided while a pending item was being
+ * written already ran its receipt fan-out against an item that did not
+ * exist yet. Best-effort: a transport failure skips (never misreads a
+ * hiccup as "request gone"), and the reconciliation sweep heals what
+ * this misses.
+ */
+export async function receiptGuardianFeedItemIfRequestTerminal(
+  requestId: string,
+): Promise<void> {
+  try {
+    const request = await getGuardianRequest(requestId);
+    if (!request || request.status === "pending") {
+      return;
+    }
+    await writeGuardianFeedReceipt({
+      requestId,
+      status: request.status,
+      decidedAtMs: request.updatedAt,
+    });
+  } catch (err) {
+    log.warn(
+      { err, requestId },
+      "Failed to converge guardian feed item with terminal request",
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Reconciliation
+// ---------------------------------------------------------------------------
+
+/**
+ * Ceiling on backfills per reconciliation round, mirroring the expiry
+ * sweep's batch bound: one round's IPC and file writes stay bounded
+ * however large a backlog grows, and the remainder drains on later
+ * rounds (the sweep runs every minute).
+ */
+const RECONCILE_BACKFILL_LIMIT = 50;
+
+/**
+ * Converge the feed against canonical guardian state. Run from the
+ * guardian expiry sweep, so drift heals on the same cadence expiry does:
+ *
+ *   1. A pending request with no feed item (it predates the projection,
+ *      or its write was lost) gets one backfilled from the request row.
+ *      No conversation is generated: the item links to the request's
+ *      source conversation when it names one, and nothing else.
+ *   2. A feed item still offering actions for a request that is
+ *      terminal (or gone) is rewritten into its receipt, and the drift
+ *      is logged loudly: a terminal request with an actionable
+ *      projection is the invariant this system exists to prevent.
+ *
+ * Skips the round when the gateway is unreachable; an empty list must
+ * not be mistaken for "everything resolved".
+ */
+export async function reconcileGuardianFeedProjections(): Promise<void> {
+  let pending: GuardianRequestWire[];
+  try {
+    pending = await listGuardianRequests({ status: "pending" });
+  } catch (err) {
+    log.debug(
+      { err },
+      "Guardian feed reconciliation skipped: gateway unreachable",
+    );
+    return;
+  }
+
+  const items = readHomeFeed().items;
+  const itemsByRequestId = new Map<string, FeedItem>();
+  for (const item of items) {
+    const requestId = requestIdFromGuardianFeedItemId(item.id);
+    if (requestId) {
+      itemsByRequestId.set(requestId, item);
+    }
+  }
+
+  const pendingIds = new Set(pending.map((request) => request.id));
+
+  const missing = pending.filter(
+    (request) => !itemsByRequestId.has(request.id),
+  );
+  if (missing.length > RECONCILE_BACKFILL_LIMIT) {
+    log.warn(
+      { missing: missing.length, limit: RECONCILE_BACKFILL_LIMIT },
+      "Guardian feed backfill backlog exceeds one round; remainder drains next round",
+    );
+  }
+  for (const request of missing.slice(0, RECONCILE_BACKFILL_LIMIT)) {
+    log.info(
+      { requestId: request.id, kind: request.kind, surface: "home_feed" },
+      "Backfilling feed projection for pending guardian request",
+    );
+    await appendFeedItem(buildBackfillGuardianFeedItem(request));
+    // The request may have resolved between the pending listing and this
+    // append; without the recheck the fresh item would restore live
+    // actions for a terminal request until the next round.
+    await receiptGuardianFeedItemIfRequestTerminal(request.id);
+  }
+
+  for (const [requestId, item] of itemsByRequestId) {
+    if (!isPendingGuardianFeedItem(item) || pendingIds.has(requestId)) {
+      continue;
+    }
+    // The item says pending but the canonical row does not: read the row
+    // to learn its terminal status. Deliberately the throwing lookup: the
+    // degrading variant returns null on a transport failure too, and a
+    // hiccup must skip the row rather than receipt a live request as
+    // cancelled. A row absent from the gateway reads as
+    // cancelled.
+    let request: GuardianRequestWire | null;
+    try {
+      request = await getGuardianRequest(requestId);
+    } catch {
+      continue;
+    }
+    if (request?.status === "pending") {
+      // Raced a fresh listing; the request really is pending.
+      continue;
+    }
+    log.warn(
+      {
+        requestId,
+        surface: "home_feed",
+        canonicalStatus: request?.status ?? "missing",
+      },
+      "Terminal guardian request still had an actionable feed projection",
+    );
+    await writeGuardianFeedReceipt({
+      requestId,
+      status: request?.status ?? "cancelled",
+      ...(request ? { decidedAtMs: request.updatedAt } : {}),
+    });
+  }
+}
+
+/**
+ * Minimal feed item for a pending request discovered without one,
+ * assembled from the canonical row alone (reconciliation has no
+ * notification copy to draw on). `questionText` is the human-readable
+ * ask every producer writes; `activityText` names the action in plain
+ * language when the producer recorded one.
+ */
+function buildBackfillGuardianFeedItem(request: GuardianRequestWire): FeedItem {
+  const summary =
+    request.questionText?.trim() ||
+    request.activityText?.trim() ||
+    `Guardian request ${request.requestCode ?? request.id}`;
+  const intent = intentFromInstructionMode(
+    resolveGuardianInstructionModeFromFields(
+      request.kind,
+      request.toolName ?? undefined,
+    )?.mode,
+  );
+  const now = new Date().toISOString();
+  return {
+    id: guardianFeedItemId(request.id),
+    type: "notification",
+    priority: 50,
+    summary,
+    timestamp: new Date(request.createdAt).toISOString(),
+    createdAt: now,
+    status: "new",
+    category: "security",
+    noteworthy: true,
+    urgency: "high",
+    detailPanel: { kind: "permissionChat" },
+    ...(request.sourceConversationId
+      ? { conversationId: request.sourceConversationId }
+      : {}),
+    guardianRequest: {
+      requestId: request.id,
+      kind: request.kind,
+      intent,
+      status: "pending",
+      ...(request.toolName ? { toolName: request.toolName } : {}),
+      ...(request.sourceChannel
+        ? { sourceChannel: request.sourceChannel }
+        : {}),
+    },
+  };
+}

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

@@ -29,6 +29,12 @@ import { getLogger } from "../util/logger.js";
 import { normalizeTitle, stripMarkdown } from "../util/short-title.js";
 import { isConversationSeedSane } from "./conversation-seed-composer.js";
 import { deriveTitle } from "./copy-composer.js";
+import {
+  buildPendingGuardianProjection,
+  guardianFeedItemId,
+  isGuardianRequestSignalEvent,
+  receiptGuardianFeedItemIfRequestTerminal,
+} from "./guardian-feed-projection.js";
 import { readPayloadString } from "./notification-utils.js";
 import type { NotificationSignal } from "./signal.js";
 import type {
@@ -79,6 +85,7 @@ export async function writeHomeFeedItemForSignal(
   signal: NotificationSignal,
   decision: NotificationDecision,
   vellumDelivery?: NotificationDeliveryResult,
+  deliveryResults?: NotificationDeliveryResult[],
 ): Promise<FeedItem | null> {
   const { mirror, sourceConversationId, sourceScheduleJobId } =
     resolveHomeFeedMirror(signal, vellumDelivery?.conversationId);
@@ -107,7 +114,14 @@ export async function writeHomeFeedItemForSignal(
       : undefined) ||
     renderedCopy?.body?.trim() ||
     payloadBody?.trim() ||
-    "";
+    // Guardian requests must never be dropped for missing copy: the
+    // producer's questionText (or, for access requests, the triggering
+    // message preview) is already the human-readable ask.
+    (isGuardianRequestSignalEvent(signal.sourceEventName)
+      ? (readPayloadString(signal.contextPayload, "questionText")?.trim() ??
+        readPayloadString(signal.contextPayload, "messagePreview")?.trim() ??
+        "")
+      : "");
   if (!resolvedSummary) {
     log.warn(
       { signalId: signal.signalId, sourceEventName: signal.sourceEventName },
@@ -155,8 +169,28 @@ export async function writeHomeFeedItemForSignal(
       ? { ...(baseMetadata ?? {}), scheduleId }
       : baseMetadata;
 
+  // A guardian request's item is keyed by the request rather than the
+  // signal, so the feed's replace-in-place merge keeps exactly one
+  // canonical "Needs attention" item per request across re-emits and
+  // the terminal-status receipt rewrite.
+  const guardianProjection = isGuardianRequestSignalEvent(
+    signal.sourceEventName,
+  )
+    ? buildPendingGuardianProjection(
+        signal.contextPayload,
+        deliveryResults?.find(
+          (r) => r.channel === "slack" && r.status === "sent",
+        ),
+        signal.sourceEventName === "ingress.access_request"
+          ? "access_request"
+          : undefined,
+      )
+    : null;
+
   const item: FeedItem = {
-    id: `notif:${signal.signalId}`,
+    id: guardianProjection
+      ? guardianFeedItemId(guardianProjection.requestId)
+      : `notif:${signal.signalId}`,
     type: "notification",
     priority: 50,
     title: resolvedTitle,
@@ -167,6 +201,7 @@ export async function writeHomeFeedItemForSignal(
     category,
     noteworthy: deriveNoteworthy(signal),
     fromAssistant: signal.sourceChannel === "assistant_tool",
+    ...(guardianProjection ? { guardianRequest: guardianProjection } : {}),
     ...(urgency ? { urgency } : {}),
     ...(sourceConversationId ? { conversationId: sourceConversationId } : {}),
     ...(panelKind ? { detailPanel: { kind: panelKind } } : {}),
@@ -205,6 +240,16 @@ export async function writeHomeFeedItemForSignal(
     : item;
 
   await appendFeedItem(card);
+
+  // Converge the write-vs-resolve race: a request decided while this
+  // write was in flight already ran its receipt fan-out against an item
+  // that did not exist yet. Mirrors the delivery recorder's
+  // `withdrawIfRequestAlreadyTerminal`.
+  if (guardianProjection) {
+    await receiptGuardianFeedItemIfRequestTerminal(
+      guardianProjection.requestId,
+    );
+  }
   return card;
 }
 
@@ -418,15 +463,12 @@ function deriveDetailPanelKind(
     return "toolPermission";
   }
 
-  if (signal.sourceEventName === "guardian.question") {
-    const payload = signal.contextPayload;
-    const kind =
-      payload && typeof payload === "object" && "requestKind" in payload
-        ? payload.requestKind
-        : undefined;
-    if (kind === "tool_approval" || kind === "tool_grant_request") {
-      return "permissionChat";
-    }
+  // Every guardian request opens the permission-style panel: the client
+  // dispatches the guardian card off the item's `guardianRequest`
+  // projection, and the panel kind keeps pre-projection clients (and
+  // bucket-fallback derivations) treating the row as an approval.
+  if (isGuardianRequestSignalEvent(signal.sourceEventName)) {
+    return "permissionChat";
   }
 
   return undefined;
@@ -479,6 +521,12 @@ 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 };
   }

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

@@ -358,6 +358,28 @@ describe("BYOOAuthConnection", () => {
       expect(headers.get("Content-Type")).toBe("application/json");
     });
 
+    test("sends a Buffer body as raw bytes under the caller's Content-Type", async () => {
+      await setupCredential("google");
+      const conn = createConnection();
+      const binary = Buffer.from([
+        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0xff, 0xfe,
+      ]);
+
+      await conn.request({
+        method: "POST",
+        path: "/upload/drive/v3/files",
+        headers: { "Content-Type": "application/pdf" },
+        body: binary,
+      });
+
+      const [, init] = mockFetch.mock.calls[0];
+      const sent = (init as RequestInit).body;
+      expect(Buffer.isBuffer(sent)).toBe(true);
+      expect(Buffer.from(sent as Buffer).equals(binary)).toBe(true);
+      const headers = (init as RequestInit).headers as Headers;
+      expect(headers.get("Content-Type")).toBe("application/pdf");
+    });
+
     test("sends a string body verbatim under the caller's Content-Type", async () => {
       await setupCredential("google");
       const conn = createConnection();

package/src/oauth/byo-connection.ts

@@ -14,7 +14,7 @@ import type {
   OAuthConnectionRequest,
   OAuthConnectionResponse,
 } from "./connection.js";
-import { decodeOAuthResponseBytes } from "./connection.js";
+import { decodeOAuthResponseBytes, isBinaryOAuthBody } from "./connection.js";
 
 const log = getLogger("byo-oauth-connection");
 
@@ -83,15 +83,17 @@ export class BYOOAuthConnection implements OAuthConnection {
 
         // A string body is already in its wire form (multipart, XML,
         // form-encoded, or pre-serialized JSON) and travels verbatim under
-        // the caller's own Content-Type. Objects and arrays are serialized
-        // as JSON and get the JSON Content-Type by default.
+        // the caller's own Content-Type. A Buffer travels as raw bytes.
+        // Objects and arrays are serialized as JSON and get the JSON
+        // Content-Type by default.
         const hasBody = req.body !== undefined && req.body !== null;
+        const binaryBody = isBinaryOAuthBody(req.body) ? req.body : undefined;
         const rawBody = typeof req.body === "string" ? req.body : undefined;
 
         // Use the Headers API for case-insensitive merging. Set defaults
         // first so caller-supplied headers (in any casing) override them.
         const headers = new Headers();
-        if (hasBody && rawBody === undefined) {
+        if (hasBody && rawBody === undefined && binaryBody === undefined) {
           headers.set("Content-Type", "application/json");
         }
         if (req.headers) {
@@ -106,7 +108,11 @@ export class BYOOAuthConnection implements OAuthConnection {
         const resp = await fetch(fullUrl, {
           method: req.method,
           headers,
-          body: hasBody ? (rawBody ?? JSON.stringify(req.body)) : undefined,
+          body: hasBody
+            ? (binaryBody !== undefined
+                ? Buffer.from(binaryBody)
+                : (rawBody ?? JSON.stringify(req.body)))
+            : undefined,
           signal: req.signal
             ? AbortSignal.any([
                 req.signal,